The engine, in one page

A VizFor design is a document, not an image. The image is what a pinned headless Chromium makes of the document, and it makes the same one every time.

The document format is vf-HTML: HTML restricted to a registered vocabulary of custom elements called Blocks, each validated against its own schema. There is no <div>, no class, no style attribute and no CSS file. A parameter a Block does not declare is refused by name, with a code.

That restriction is the product, not a limitation of it. Everything about the rendered file that has a hard pass/fail condition — can the bundled fonts draw these characters, does every asset the document names actually resolve — is deterministic code that answers before anything is delivered. Everything that is a judgement about the design rather than about the file — contrast, the safe area, where the eye lands — is measured just as deterministically and reported rather than enforced. What is left over is the creative layer, and that is the part a person or an agent works in.

Four facts to have before you write anything

1. The vocabulary is closed. A short list of Blocks draws and arranges; a few structural ones shape the document and draw nothing. An unknown element, an undeclared attribute or a <!-- comment --> is a rejection, not a warning. The vocabulary →
2. Nothing mutates a document except a command. The editor, the built-in assistant and a third party's agent are three clients of one command registry. A batch applies as one unit: if any command in it fails, none is applied. The commands →
3. A node id names a node, not a place. Every node carries a short id — text-0, group-1, or a name somebody wrote — that stays with it for as long as it exists. Inserting or removing something else never renumbers it, so an id you read once stays good. Never build one by counting.
4. The render is a contract. Fonts are bundled and the render network is blocked; a character no bundled face covers is a check failure rather than a silent substitution. Nothing in a render path may read the clock, and randomness is seeded per node id — the same document renders to the same bytes.

The shape of a document

<vf-doc studio="core" spec-version="1">
  <vf-brief>
    <vf-field name="intent">Lead with zero-config setup</vf-field>
  </vf-brief>
  <vf-canvas preset="APP_STORE_6_9" locale="en-US" align-y="center">
    <vf-background kind="solid" color="#0E1B4D"></vf-background>
    <vf-text role="title" color="#FFFFFF" x="50%" y="30%" anchor="center">
      Set up in one line
    </vf-text>
  </vf-canvas>
</vf-doc>

One <vf-doc>, holding exactly one <vf-canvas> — the surface that is drawn — and optionally a <vf-brief>, which records why this design is what it is. The brief reaches no pixel, and is versioned and diffed with the design it belongs to.

Where to go next

• Document shape — the regions, ids, and what the canvas takes its size from.
• Placement and layout — flowing versus absolute, paint order, groups and stacks.
• Text and material — the two bundled families, vertical setting, and how a photograph enters a document.
• Conventions — the rules that are true but are in no schema, published verbatim from the engine.
• What gets refused — every rejection code, the budgets, and the reserved attributes.
• For agents — connecting over MCP, and the machine-readable copies of everything on these pages.

What this section is generated from

Every list on these pages — Blocks, parameters, commands, tools, presets, Channel rules, rejection codes — is read out of the packages that implement them when the page renders. There is no second copy to fall out of step, which is the same rule the endpoint guides at GET /api/agent-doc already follow. The prose around those lists is written by hand, and a test fails the build when a page names a Block, a command or a tool the engine does not have.