Platform widgets

The fast path: live data, working sticky header, working dropdowns, filters and paging — at the price of a look bounded by props.

1. Where the truth about props lives

GET /docs/widgets

Generated from the real widget parsers, so it cannot drift from the platform. For each kind: label, whether it is chrome or a page block, the write path, a JSON Schema of its props with defaults, and the allowed values of every enum.

Read the schema of the kind you are about to change. Do not write a prop from memory: an unknown value is accepted and the default is drawn.

2. The write path is where agents go wrong

Props are nested per widget: props.listing.…, props.card.…, props.form.…. The reference states writePath for each kind — use it. Writing to the root of props is accepted and does nothing.

sections is a replace-set: read the block, change the one element, send the whole list back. Sending a single section deletes the rest.

3. The wrapper is configurable too — and it is how you reskin a widget

Every block sits in a standard wrapper, and its axes are written next to kind, at the root of props, not inside the widget's own path. Ask for the current list rather than trusting any copy of it — one that named a props.innerMax nothing had ever read survived for weeks:

curl -s https://api.vizen.shop/docs/widgets | jq -r '
  .wrapper.axes[] | [.path, .type, (.default // "-"), .anchor.at] | @tsv'

Each row carries the file:line in the storefront that sets the default, and .wrapper.elements does the same for the two wrapper divs themselves.

When the props run out, the wrapper is the next move, not own markup. props.wrapperClass: "my-hero" puts your own class on the band — including the band of siteHeader, siteMenu and siteFooter — and you restyle it from your own CSS (.my-hero > .vz-inner { … }). You keep the working widget, its live data and its props, and change only the look. Two catches: the CSS has to live in a level 3 document (level-1 styles are trapped in a shadow root), and you must never target the platform's own class names directly. Recipe: GET /docs/own-markup §5, skill vizen-own-markup.

Per-device overrides live under props.tablet and props.mobile, same keys.

4. Known limits — say them out loud before promising a look

• the listing's own strip cannot be recoloured today: container.fill on productListing is accepted and does nothing;
• the listing template is default and there are no others;
• siteMenu.level2 builds a real dropdown from your category tree — it opens on click, not on hover, whatever the field description says;
• some style props are clamped: a font weight of 800 renders as 600, a label size of 13 renders as 15.

If the owner wants something outside these bounds, that is the fork into vizen-own-markup — and it costs live data in product rows. Say so.

5. Validate before writing

POST /docs/validate with the sections you are about to send. It replies per path whether the value will be applied, silently ignored, or not understood — which is exactly the class of mistake this area produces most. Nothing is written.

6. Verify

Re-read the block and open the page. A 200 is not evidence. Full checklist: vizen-troubleshoot.