Skip to main content
This is the completeness standard for the reference. The guide is a model of the SDK, not a catalog of names, so every entry (a component, prop, API method, event, or data-model entity) must carry the layers below, to the extent they apply. An entry that only names a thing is incomplete. This contract governs all reference files and every edit. When you learn a new fact by verifying against ground truth (see the verify protocol), write it back here to the same bar.

​
Source-of-truth invariant (every reference page)

Every page under reference/ is the source of truth and is exhaustive for what it covers. These three rules hold for all of them, so individual pages don’t restate them in full, they only add their own caveats (e.g. structural vs. conditional classes, which tokens are theme-safe, the React/custom-element count split):
  • If a name isn’t on its reference page, it doesn’t exist. Any prop, CSS class/variable, wireframe slot, {variable} token, hook, event, API method, or component absent from the page that owns it is not a real identifier: don’t use it. (A missing token resolves to undefined; a missing -wireframe tag renders nothing.)
  • Never invent or guess a name. Use only identifiers that appear verbatim on these pages, or that you verified against ground truth and wrote back here to the same bar.
  • Inspect to confirm placement. The page proves a name is real; to see where it lands on a specific rendered element, inspect it live with shadowDom={false} (see Debugging).

​
The five layers

  1. Surface: the name, type/signature, and where it lives (which component/surface it belongs to). Answers “does it exist?”
  2. Behavior: what it actually does, its default, the states/transitions it drives, and how it interacts or combines with related items (other props, variants, modes). Answers “what happens if I use it, and if I combine it?” This is where most catalogs stop short.
  3. Data: what data it reads or writes: the model entity/field involved, which hook/event surfaces that field, and how to mutate it. Answers “what data do I have, and where do I get it?”
  4. Intent: what it is for, when it is the right tool, and when it is the wrong tool (with the better alternative). Answers “should I use this for my goal?”: this is what lets the reader correct a mismatched requirement instead of applying a name literally.
  5. Composition: valid combinations, what overrides what, and scoping rules (e.g. which variant serves which context; whether the surface is anchored (Velt-positioned) or statically-placed). Answers “how does it fit with everything else?”
Not every layer applies to every entry (a pure styling token has no Data layer). Cover the ones that do.

​
Epistemic rules (non-negotiable)

  • State facts with certainty when verified; never hedge. If a behavior is known, state it. If it is not, that is a Data/Behavior absence: document the absence explicitly (see next).
  • Document absences, not just presence. If a capability or field does not exist, say so plainly and name the consequence (e.g. “editor identity for an edit is not stored, so ‘who edited’ cannot be shown client-side”). A reader must be able to reach a confident “not supported” verdict from the guide alone.
  • No external paths. Never reference implementation file paths, absolute filesystem paths, dependency-directory locations, or any repo-internal file location. The guide is self-sufficient knowledge; the bundler rejects entries that leak such a path.
  • Right tool, not literal tool. When an entry is commonly misapplied (e.g. status dropdown used for arbitrary categories), the Intent layer must call out the mismatch and point to the correct mechanism.

​
The feasibility ladder (how Behavior/Intent feed decisions)

Every requirement is answerable by naming the first layer that achieves it, in this order: default behavior → prop/config → wireframe → primitive → headless. Reference entries should make that placement obvious: a prop entry says what it covers (so the reader stops there), and an Intent/absence note says when to climb to the next rung. A “not in default/prop/wireframe, achievable via primitives/headless” verdict must also confirm the Data layer supports it (the needed fields/events exist) before claiming feasibility.

​
Per-artifact application

  • Props: Surface + a one-line Behavior/Intent; deep Behavior + Composition (interactions, defaults, state) live in Behaviors and are linked, not duplicated.
  • Behaviors: Behavior + Composition for every non-obvious prop/mode, default behaviors, prop-interaction matrices, state machines, positioning ownership.
  • Data models: Data for every entity: fields, the hook/event that exposes each, mutation API, custom-data storage, and absences.
  • Component definitions: Surface + Intent (purpose, right-tool/wrong-tool) for every component and slot; anchored-vs-static classification.
  • Events / Hooks: Surface + Data, each cross-linked to its Data models entity.
  • Decision tree: applies the feasibility ladder + the anchored-vs-static axis to route every requirement.