> ## Documentation Index
> Fetch the complete documentation index at: https://velt-codex-ui-customization-guide-refresh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Entry contract (how every reference entry must be written)

> Explain the reference entry contract and source-of-truth rules for Velt customization identifiers.

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