Components Overview

The components catalog is generated from primitive schemas, specs, example manifests, and adapter exports. Treat it as the routeable index of canonical behavior, not as a list of visual widgets.

Every canonical primitive page should answer:

• What problem the primitive solves.
• Which slots are public.
• Which states exist and where they are reflected.
• Which events and keyboard interactions are required.
• Which ARIA roles and relationships must be present.
• Which validator rules protect the contract.
• Which adapters expose it and how examples map to those adapters.

These nine primitives are visible across React, Vanilla, Vue, Solid, and Svelte routes.

Read primitive anatomy as a DOM contract:

• Required slots must be present for the primitive to be valid.
• Repeatable slots need stable IDs or values.
• Optional slots remain public when rendered.
• Adapter helper components may exist without becoming schema slots.
• Portals change DOM location, not semantic ownership.

For example, Dialog includes trigger, overlay, content, title, description, and close. React may also provide Header and Footer helper components, but those helpers are composition conveniences, not required schema slots.

State documentation distinguishes:

• Controlled state: open, value, inputValue, selectedValues, or equivalent plus callbacks.
• Uncontrolled state: defaultOpen, defaultValue, defaultInputValue, or equivalent.
• Reflected state: data-state, data-selected, data-highlighted, aria-expanded, aria-selected, aria-activedescendant, hidden.
• Derived state: layout attributes such as data-placement, data-side, and data-align.

Do not mix controlled and uncontrolled props on the same instance unless the primitive explicitly documents a migration path.

Keyboard and focus rules are not optional:

• Tabs, Menu, Listbox, Select, and Combobox use roving focus or active-descendant navigation.
• Dialog uses focus scope and dismissable layer behavior.
• Popover, Menu, Select, Combobox, and Tooltip include outside dismiss or close behavior.
• Tooltip keeps trigger focus; Combobox keeps focus on input while highlight moves through options.

The component page should name the actual keys: Tab, Shift+Tab, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, Enter, Space, Escape, and typeahead where applicable.

The docs build produces machine-readable catalogs:

• docs-tree.json: route navigation.
• components-catalog.json: primitive metadata.
• api-catalog.json: exports by primitive and adapter.
• primitive-coverage.json: implementation and test coverage.
• search-index.json: routeable search content.
• llms.txt: compact agent-readable summary.

When component docs change, regenerate these artifacts with pnpm content:build and verify with pnpm content:check.

• Primitive spec has purpose, non-goals, anatomy, DOM contract, state, events, keyboard, ARIA, validator, adapters, tests, and SSR notes.
• Schema slots and states match the rendered adapter output.
• Examples exist for every supported adapter route.
• DOM contract snapshots cover critical attributes.
• Adapter parity tests cover high-risk interaction paths.