# primitive-authoring references, retrieval map

One line per file: `path, the question it answers`. Load this first; load
files on demand from it. Axes are topical (no severity ranking applies).
The skill body's task-shape table routes entry asks; this map covers every
file, including the depth references those entries cross-link.

## Authoring lifecycle

- [primitive-audit.md](primitive-audit.md), does the primitive I'm about to build already exist? The mandatory §0 affordance-by-affordance audit before ANY new component.
- [authoring-cycle.md](authoring-cycle.md), what are the 5 steps to author a new primitive or modify an existing one, and which rules are non-negotiable?
- [worked-example.md](worked-example.md), what does a finished primitive look like end to end? Two annotated builds: `<badge-ui>` (presentation) and `<counter-ui>` (form-associated).

## Contracts (API · yaml · tokens · CSS · lifecycle)

- [api-contract.md](api-contract.md), how do I declare `static properties` (type, default, reflect, attribute), avoid the `attr:` silent-typo trap, and expose a selection-item's `selected` state (declared reflected prop, never a `data-*` stamp, ADR-0056)?
- [yaml-contract.md](yaml-contract.md), what fields does the `<name>.yaml` SoT take, and how does it feed the generated `.a2ui.json` sidecar?
- [token-contract.md](token-contract.md), is this component's CSS honoring the two-block `@scope` token contract, and why does it misrender under a theme?
- [css-patterns.md](css-patterns.md), how do I structure a component stylesheet: two-block `@scope`, variants vs modes, token layering, deriving an inset item's border-radius from its rounded container (concentric-corner radius)?
- [lifecycle-patterns.md](lifecycle-patterns.md), how do I keep `connected()`/`disconnected()` symmetric for listeners, timers, observers, and popovers?
- [svg-authoring.md](svg-authoring.md), viewBox/coordinate scaling, stroke-width, text-anchor/dominant-baseline, card-bleed clipping, currentColor vs `var()` inside SVG markup, hit-testing, for `chart-ui`/`qr-code-ui`/`icon-ui`/any new `<svg>`-emitting primitive.
- [form-control-sizing.md](form-control-sizing.md), does a form-control host fill its container or hug its content, and where does the legibility floor live (ADR-0077)?
- [for-attribute-event-contract.md](for-attribute-event-contract.md), what does `for=` resolve to, and how does a `for=`-bound pair talk to each other (ADR-0079)?

## Shells & modules

- [shell-patterns.md](shell-patterns.md), how do I author a shell or a bespoke cluster child (`<admin-*>` `<chat-*>` `<editor-*>` `<simple-*>`) per ADR-0023?
- [module-promotion.md](module-promotion.md), when and how do I lift a UI block duplicated across consumers into a shared `packages/web-modules/` element (the 5-phase arc)?

## Demos & doc surfaces

- [composite-demo-protocol.md](composite-demo-protocol.md), what discipline governs any `packages/web-modules/**` demo edit, beyond what the `Pattern source:` gate can see?
- [examples-structure.md](examples-structure.md): what order do a primitive's own `<name>.examples.html` `<h2 variant="section">` blocks follow, and where does `Typography registers` sit relative to `Edge Cases` and the generated API tail?
- [canonical-pattern-index.md](canonical-pattern-index.md), which canonical `.contents.html` files should I survey for a given UI type? Auto-generated; regenerate via `scripts/build-canonical-pattern-index.mjs`.
- [trait-pages.md](trait-pages.md), which sections, in which order, must a `site/pages/traits/<name>/` detail page carry (ADR-0019 template)?

## Conventions & failure catalog

- [code-style.md](code-style.md), is this idiomatic AdiaUI? The conventions (`<*-ui>` elements, tokens, layout primitives) and the working feature each protects.
- [anti-patterns.md](anti-patterns.md), what named mistake shapes (AP-##) has the coherence audit already caught, so I don't repeat them?
- [common-gotchas.md](common-gotchas.md), which authoring traps render broken without console errors: CSS/composition layering (§§1–5), async-lifecycle races (§6), regeneration ordering (§7)?

## Historical

- [llm-bridge.md](llm-bridge.md), superseded 2026-07-18 pointer: `@adia-ai/llm` internals belong to `llm-client-maintenance`; kept only to redirect.