Primitive Concepts

A primitive is a behavior contract with a public DOM shape. It is not a styled component. The controller decides state transitions, the adapter maps them to framework syntax, and the DOM reflects the result for users, assistive technology, tests, and agents.

Every primitive has four layers:

1. Anatomy: named slots and their relationships.
2. State: controlled/uncontrolled inputs and reflected output attributes.
3. Interaction: native events, keyboard model, focus policy, and dismissal rules.
4. Validation: schema-backed rules that report broken structure or semantics.

Slots are public. If a spec names trigger, content, option, panel, or hidden-input, the rendered DOM should expose that slot through data-slot.

Slot rules:

• Required slots must exist.
• Repeatable slots need stable identity.
• Optional slots still follow public naming when rendered.
• Parent/child relationships matter for validation.
• Portal boundaries do not erase ownership relationships.

An agent should be able to inspect markup and answer "which primitive is this, which slot is this node, and what state is it in?"

Primitives support controlled and uncontrolled state when interaction complexity requires it.

Controlled examples:

• open + onOpenChange for Dialog, Popover, Menu, Select, Combobox, Tooltip.
• value + onValueChange for Tabs, Listbox, Select.
• inputValue + onInputValueChange for Combobox.

Uncontrolled examples:

• defaultOpen
• defaultValue
• defaultInputValue

Do not pass both controlled and uncontrolled values for the same state dimension after initial implementation. The validator treats controlled/uncontrolled conflicts as contract bugs because they create ambiguous truth.

Important state must be visible in DOM:

If state is visible only through CSS classes, the primitive is not agent-friendly enough.

The event model follows the web platform:

• Pointer and mouse: pointerdown, mousedown, click, mouseenter, mouseleave.
• Focus: focus, blur, focusin, focusout.
• Keyboard: keydown with named key handling.
• Forms: input, change, submit.

Adapter callbacks should describe state changes, but they should not replace platform events as the underlying model.

Complex primitives require explicit keyboard behavior:

• Tabs: roving focus, Arrow*, Home, End, optional manual activation with Enter/Space.
• Dialog: focus trap in modal mode, LIFO close behavior, focus restoration.
• Menu: roving focus, typeahead, submenu open/close, Escape.
• Listbox/Select: option navigation and selection commit.
• Combobox: focus stays on input while aria-activedescendant points at highlighted options.
• Tooltip: trigger keeps focus, content is not tabbed into by default.

Do not ship a primitive that "looks clickable" but cannot be operated from the keyboard.

Use native elements first, then ARIA only where native semantics are insufficient.

Common relationships:

• aria-controls: trigger/input points to content/listbox/panel.
• aria-labelledby: content/panel points back to label/title/trigger.
• aria-describedby: trigger or content points to helper text.
• aria-selected: option or tab selected state.
• aria-activedescendant: active option while DOM focus remains on input/listbox.
• aria-modal: modal dialog content.

Every ARIA ID reference should resolve to an element in the rendered DOM after hydration.

Server output must match the client contract:

• IDs are deterministic.
• Initial state is the same on server and client.
• Client-only measurement waits until mount.
• Hidden content stays hidden until activated.
• Portal targets do not break ARIA linkage.

Hydration mismatches are not just React warnings. They can break validator repair, focus restoration, and screen reader relationships.

Validator messages should include:

• Rule ID.
• Trigger condition.
• Fix suggestion.
• Whether the issue can be auto-fixed.

Example issue shape:

{
  "ruleId": "aria.broken-controls-linkage",
  "trigger": "Trigger aria-controls points to a missing content id.",
  "suggestion": "Render the content slot with the referenced id or update aria-controls.",
  "canAutoFix": false
}

• Required slots are present.
• State has one source of truth.
• ARIA relationships resolve.
• Keyboard model is documented and tested.
• Focus behavior is deterministic.
• Public data-* attributes match the schema.