# Architecture Decisions

This document records significant architectural decisions made during the development of nuka-ui, including context, reasoning, and tradeoffs.

---

## ADR-001: Variant + Intent API for components

**Date:** 2026-04-03  
**Status:** Accepted

### Context

UI components that carry semantic meaning (danger, success, warning) need a way to express both visual weight and semantic color independently. The naive approach is flat variants: `variant="danger"`, `variant="ghost-danger"`, etc.

### Decision

Separate `variant` and `intent` into distinct props:

- `variant`: controls visual weight and shape (primary, secondary, outline, ghost, link)
- `intent`: controls semantic color (default, danger, success, warning)

All variant x intent combinations are valid. CVA `compoundVariants` handles the class composition.

### Consequences

- 25 explicit compound variant definitions per component that uses this pattern
- Cleaner consumer API: `<Button variant="ghost" intent="danger">` vs `<Button variant="ghost-danger">`
- Scales naturally to new intents or variants without breaking existing combinations
- Adding a new intent requires adding N compoundVariants where N is the number of variants

### Alternatives considered

**Flat variants**: simpler initially but causes combinatorial explosion as variants grow. `ghost-danger`, `outline-success`, `link-warning` become unwieldy and undiscoverable.

**CSS data attributes**: `<Button data-intent="danger">` avoids prop pollution but loses TypeScript type safety and makes the API less explicit.

---

## ADR-002: Token architecture: primitives + semantic layer

**Date:** 2026-04-03  
**Status:** Accepted

### Context

CSS custom properties need to serve two masters: design system internals (consistent scale) and consumer theming (easy overrides). Flat token structures make theming hard. Deeply nested structures make maintenance hard.

### Decision

Two-layer token architecture:

- **Primitive tokens**: raw scale values, no `--nuka-` prefix (e.g. `--color-accent-500`, `--space-4`)
- **Semantic tokens**: purpose-driven, `--nuka-` prefixed, reference primitives (e.g. `--nuka-accent-bg: var(--color-accent-500)`)

Components reference only semantic tokens. Consumers can remap semantic tokens without touching primitives.

### Consequences

- Theming is done by overriding `--nuka-*` tokens on `[data-theme]`
- Primitives are stable: adding a new color to the scale doesn't affect existing components
- Component-level tokens are added only when semantic tokens are insufficient

### Alternatives considered

**Single layer**: all tokens flat. Simple but makes dark mode and theming require overriding every token individually.

**Three layers** (primitives to semantic to component): more granular but premature for the current component count. Revisit when component-specific theming needs arise.

---

## ADR-003: `data-theme` attribute for theming

**Date:** 2026-04-03  
**Status:** Accepted

### Context

Theme switching requires a CSS selector anchor. Common approaches are class-based (`.dark`) or attribute-based (`data-theme="dark"`).

### Decision

Use `data-theme` attribute on a container element. Semantic tokens are scoped to `[data-theme="light"]` and `[data-theme="dark"]`.

### Consequences

- Multiple themes can coexist on the same page (nested `data-theme` attributes)
- No class pollution: themes don't interfere with utility class systems
- Explicit and readable in the DOM

### Alternatives considered

**Class-based (`.dark`)**: Tailwind's default approach. Works but collides with utility classes and makes nested themes awkward.

**`prefers-color-scheme` only**: automatic but gives consumers no control over manual theme switching.

---

## ADR-004: No component-level tokens by default

**Date:** 2026-04-03  
**Status:** Accepted

### Context

Some design systems define per-component tokens (`--button-bg`, `--button-text`, etc.) for maximum consumer flexibility.

### Decision

Components reference semantic tokens directly. Component-level tokens are added only when a component has styling needs that cannot be expressed through existing semantic tokens.

### Consequences

- Less token surface area to maintain and document
- Consumers who need per-component overrides use `className` prop or CSS targeting
- If component-level tokens are needed later, they are additive and non-breaking

### Alternatives considered

**Per-component tokens for everything**: maximum flexibility but significant maintenance overhead and cognitive load for consumers learning the token system.

---

## ADR-005: Flat variants deferred in favor of variant + intent

**Date:** 2026-04-03  
**Status:** Accepted

### Context

The initial Button implementation used flat variants including `danger` as a variant. During development it became clear this would not scale.

### Decision

Migrated to variant + intent before any other components were built. `danger`, `success`, and `warning` are intents, not variants. This was done early to avoid a breaking change later.

### Future consideration

If the need arises for `intent` to affect layout or shape (not just color), the prop contract remains stable; `intent` values can be extended additively.

---

## ADR-006: Badge variant naming, element choice, and focus ring

**Date:** 2026-04-04
**Status:** Accepted

### Context

Badge is a non-interactive display label. It uses the same variant + intent architecture as Button but needs different variant names and has no interactive states.

### Decisions

**1. `solid`/`subtle`/`outline` instead of `primary`/`secondary`/`ghost`**

Button's variant names describe action weight: "primary" means "the main action." Badge has no actions. Its variants describe visual appearance: `solid` is a filled background, `subtle` is a tinted background, `outline` is a bordered label. Using action-semantic names for a display-only element would be misleading.

**2. `<span>` as the default element**

A `<span>` has no implicit ARIA role, which is correct for a non-interactive inline label. A `<div>` would break inline flow. A `<button>` would imply interactivity that Badge does not have. When interactivity is needed, consumers use `asChild` to render an appropriate interactive element.

**3. No focus ring in base classes**

Badge is not interactive and should never receive focus. Adding focus ring classes would be incorrect: they would either never fire (wasted classes) or incorrectly suggest interactivity. When `asChild` wraps an interactive child (e.g. `<a>`), the child's own focus styles apply. Badge adds nothing.

### Consequences

- Badge variant names are decoupled from Button: each component uses names appropriate to its role
- Future non-interactive display components (Tag, Alert) can follow Badge's naming pattern
- `asChild` remains the escape hatch for interactive use cases without polluting Badge's base styles

---

## ADR-007: Text polymorphism: `as` prop with allow-list, not `asChild` or full generics

**Date:** 2026-04-04
**Status:** Accepted

### Context

Text is a typography primitive that renders different HTML elements depending on context: `<p>` for paragraphs, `<span>` for inline text, `<label>` for form labels, `<li>` for list items, `<time>` for timestamps. It needs a polymorphism mechanism.

### Decisions

**1. `as` prop instead of `asChild`**

`asChild` (Radix Slot) is designed for component composition, merging styles onto an arbitrary consumer component (e.g., rendering a Button as a router Link). Text's polymorphism is element-switching: the component author controls which HTML tag renders. The consumer isn't compositing an external component; they're selecting a semantic element. `as` is the correct pattern for this use case. `asChild` would add Radix as a dependency for a component that has no Radix-native behavior.

**2. Allow-list (`TextElement` union) instead of full generic polymorphism**

A fully generic `as` prop (`<Text<T> as={T}>`) provides exact HTML attribute inference for any element. This is powerful but adds significant type complexity: generic component signatures, conditional ref types, and complex type narrowing. For Text, the set of valid elements is small and well-known: `p`, `span`, `label`, `li`, `time`, `abbr`, `figcaption`, `div`. An explicit union type documents intent, keeps the type signature simple, and prevents misuse (e.g., `as="button"` which should use Button instead).

### Consequences

- `Text` has no Radix dependency: it is a pure HTML + CVA component
- The `TextElement` allow-list must be extended if new valid elements are identified (additive, non-breaking)
- Consumers who need to render Text styles on a custom component should use `className` directly with `textVariants()`
- If a future `TextLink` component is needed, it would be a separate component, not an `asChild` extension of Text
- The ref type is `HTMLElement` (common base) since the forwarded element varies; consumers who need a specific ref type should cast

---

## ADR-008: Divider: no variant/intent, no asChild, conditional element rendering

**Date:** 2026-04-04
**Status:** Accepted

### Context

Divider is a visual separator used to divide sections of content. It renders as either a horizontal rule or a vertical line, and optionally displays a centered text label. Its design requirements differ significantly from interactive or semantically-colored components like Button or Badge.

### Decisions

**1. No `variant` or `intent` props**

Divider is structural chrome: it carries no semantic color meaning. Adding `intent` (danger, success, warning) to a line separator would be API noise with no valid use case. Its color comes from `--nuka-border-base`, a single neutral token. If a consumer needs a colored divider, `className` is the correct escape hatch.

**2. Conditional root element (`<hr>` vs `<div>`)**

The root element varies based on props:

- Horizontal without label: `<hr>`, has implicit `role="separator"` and `aria-orientation="horizontal"`, no redundant ARIA attributes needed
- Vertical without label: `<div role="separator" aria-orientation="vertical">`, because `<hr>` does not support vertical orientation in practice
- Horizontal with label: `<div role="separator" aria-orientation="horizontal">`, because the labeled layout is a flex container, not a semantic rule

The ref type is `HTMLElement`, the correct common supertype for `HTMLHRElement` and `HTMLDivElement`. This is the same pattern used by Text (ADR-007).

**3. Vertical + label is explicitly unsupported**

A vertically-oriented divider with centered label text is visually problematic (requires 90-degree text rotation) and semantically unclear. Rather than implementing a half-broken feature, the component logs a `console.warn` in development and renders the vertical divider without the label. This is graceful degradation: no crash, clear feedback to the developer.

**4. No `asChild`**

Divider is not a polymorphic component. There is no valid use case for rendering a separator as another element. `asChild` would add Radix as a dependency for zero benefit.

### Consequences

- Divider is the first component to intentionally omit variant/intent, establishing that the pattern is opt-in per component, not mandatory
- The conditional element rendering adds internal complexity but produces correct accessibility semantics for each configuration
- Consumers who need a styled divider beyond the size variants use `className` directly

---

## ADR-009: Remove Radix UI: first-party Slot and composeRefs

**Date:** 2026-04-04
**Status:** Accepted

### Context

The project used `@radix-ui/react-slot` (and its transitive dependency `@radix-ui/react-compose-refs`) to implement the `asChild` composition pattern on Button and Badge. This was the only Radix package in `dependencies`.

### Decision

Removed all Radix UI dependencies. Implemented `Slot` and `composeRefs` from scratch in `src/utils/slot.tsx`. The public API (`asChild` prop on components) is unchanged.

`Slot` merges props, refs, event handlers, className, and style from the Slot element onto its single child element. `composeRefs` composes multiple refs (function refs and ref objects) into a single ref callback.

### Reasoning

nuka-ui is a portfolio project that demonstrates platform-level frontend engineering. Using a third-party primitive for composition, even a small, well-scoped one, obscures understanding of a well-known pattern. The `Slot` contract is stable and the implementation is non-trivial enough to be worth owning: ref composition, event handler merging, className concatenation, and style merging each require deliberate handling.

### Consequences

- No external UI primitive dependencies remain. All composition behavior is owned, tested, and visible in the repository.
- Future components that need `asChild` import from `@nuka/utils/slot`: no external dependency decision required.
- `composeRefs` is available for any component that needs to compose a forwarded ref with an internal ref.
- The implementation must be maintained internally: any edge cases in Slot behavior are our responsibility.

### Alternatives considered

**Keeping `@radix-ui/react-slot` as a sanctioned carve-out**: rejected. Inconsistent with the no-third-party-UI-primitives policy. If we carve out Slot, the boundary becomes subjective.

**Dropping `asChild` entirely**: rejected. The `asChild` pattern is a genuine composition tool that strengthens the component API. Removing it would force consumers into less ergonomic patterns (wrapper elements, manual className forwarding) without good reason.

---

## ADR-010: Avatar image loading strategy: layered fallback with `key` remount

**Date:** 2026-04-04
**Status:** Accepted

### Context

Avatar needs image loading state management to avoid flash-of-broken-image. When an `<img>` element fails to load, the browser briefly renders a broken image icon before `onError` fires. This is visible to the user and disrupts layout. Radix UI's Avatar primitive handles this natively, but nuka-ui has adopted a no-third-party-UI-primitives policy (ADR-009).

### Decision

Implemented image loading state in React (`loaded`, `errored`) using `onLoad`/`onError` handlers. The fallback layer (initials or icon) is always rendered as the visible base layer. The `<img>` element is layered on top with `opacity-0` initially, revealed via `opacity-100` on successful load. On error, the `<img>` is removed from the DOM entirely, leaving the fallback visible.

`key={src}` on the `<img>` element forces a clean DOM remount when `src` changes, ensuring no stale image is displayed. The parent component detects the `src` change via a previous-value ref and resets `loaded`/`errored` state synchronously during render. This is simpler and more reliable than a `useEffect` with cleanup that manually resets state variables.

### Consequences

- No flash of broken image. The fallback is always visible until the image has fully loaded.
- Load state is fully owned and visible: no hidden browser behavior.
- The `key` + ref approach is simpler than a `useEffect` with cleanup but means the `<img>` element remounts on every `src` change, which is acceptable for an avatar where `src` changes are infrequent.
- The three-tier fallback resolution (image to initials to icon) is explicit and testable.

### Alternatives considered

**`onError` only**: rejected. The broken image icon is visible during the network round-trip before `onError` fires. This is the flash-of-broken-image problem the layered approach solves.

**Radix Avatar primitive**: rejected. Violates the no-third-party-UI-primitives policy (ADR-009). The load state management is straightforward enough to own.

**`useEffect` with cleanup for `src` changes**: rejected. More code, more edge cases (stale closures, race conditions between effect cleanup and state updates). `key={src}` achieves the same reset with zero additional code.

---

## ADR-011: Icon: decorative-by-default accessibility contract and cloneElement child enforcement

**Date:** 2026-04-04
**Status:** Accepted

### Context

Icon is a sizing and accessibility wrapper for SVG-based icons from any library. It needs to handle two accessibility modes (decorative and labelled) and ensure child SVGs are always correctly hidden from the accessibility tree regardless of what the consumer passes.

### Decisions

**1. Decorative by default**

Without a `label` prop, Icon renders with `aria-hidden="true"` on the wrapper. This is the correct default because the vast majority of icon usage is decorative: icons placed alongside visible text that already conveys meaning. Requiring consumers to opt into `aria-hidden` on every decorative icon would be error-prone and would lead to accessibility violations when forgotten. The `label` prop switches to labelled mode (`role="img"` + `aria-label`), which is the minority case for standalone icons.

**2. `React.cloneElement` to inject `aria-hidden` onto child SVGs**

The child SVG must always have `aria-hidden="true"`: the accessible name lives on the wrapper, not on the SVG. Rather than requiring consumers to remember to pass `aria-hidden={true}` to every icon library component, Icon enforces this by cloning the child element and injecting `aria-hidden="true"`, `width="100%"`, and `height="100%"`. This is defensive and correct: the wrapper owns the accessibility contract, not the consumer.

**3. `children: React.ReactElement` constraint**

`React.cloneElement` only works on a single React element. The type is `React.ReactElement` (not `React.ReactNode`) to enforce this at the type level. In development, a runtime warning fires if `children` is not a valid element. This trades flexibility (no string children, no fragments) for safety: Icon's purpose is to wrap a single SVG element, and accepting anything else would be a misuse.

**4. No `variant` or `intent`**

Icon has no semantic color role: it is a utility wrapper. Its `color` prop maps directly to `--nuka-text-*` tokens with `"inherit"` as the default, meaning the icon inherits `currentColor` from its parent. This is the correct default for inline icons where the parent text color should flow through.

**5. Dual CVA instances (`iconVariants` + `iconColorVariants`)**

Following the Spinner precedent (ADR not previously recorded; Spinner uses `spinnerVariants` + `spinnerColorVariants`). Separating size and color into distinct CVA instances keeps each concern isolated and composable. The `color` prop conflicts with the native HTML `color` attribute on `HTMLSpanElement`, resolved via `Omit<React.HTMLAttributes<HTMLSpanElement>, "color">`, the same pattern as Spinner.

### Consequences

- Icons are accessible by default with zero consumer effort for the common decorative case.
- The `cloneElement` approach requires that icon library components forward arbitrary props to their root SVG. All major libraries (Lucide, Heroicons, Phosphor) do this.
- `children: React.ReactElement` prevents passing strings, numbers, or fragments. This is intentional.
- The `color="inherit"` default means Icon is transparent to parent color context, which is the desired behavior for inline icons.

---

## ADR-012: Kbd: no variant/intent, no asChild, `<kbd>` element, composition model

**Date:** 2026-04-04
**Status:** Accepted

### Context

Kbd is a display-only primitive that renders keyboard key labels. Its design requirements differ fundamentally from interactive or semantically-colored components.

### Decisions

**1. `<kbd>` element: non-negotiable**

The HTML `<kbd>` element is semantically defined as keyboard input. It is the correct and only valid element for this component. No `<span>`, `<code>`, or other element is appropriate as the root.

**2. No `variant` or `intent` props**

Kbd is structural chrome. It carries no semantic color meaning: `intent="danger"` on a key label has no valid use case. A single visual treatment using `--nuka-bg-subtle`, `--nuka-border-base`, and `--nuka-text-base` is correct. Consumers who need custom color use `className`.

**3. No `asChild`**

`<kbd>` is the semantic. There is no valid element to substitute for it. Including `asChild` would add complexity for zero benefit and would encourage incorrect usage.

**4. `size` as the only variant axis**

Three sizes (`sm`, `md`, `lg`) cover the real use cases: tooltips (small), body copy (medium), and command palettes (large). No other variant axis is meaningful for a key label.

**5. Individual `<kbd>` composition model**

The HTML spec describes keyboard shortcuts as nested `<kbd>` elements: a wrapping `<kbd>` containing individual `<kbd>` children. `Kbd` renders a single key. Consumers compose sequences themselves. No `KbdGroup` or `keys` prop; that is a separate concern.

### Consequences

- Kbd is the second component (after Divider) to intentionally omit variant/intent, reinforcing that the pattern is opt-in per component
- No `asChild` means no Slot import and no Radix-adjacent complexity
- The composition model follows the HTML spec and is documented in the "Pattern: Keyboard Shortcut" story
- `<kbd>` has no implicit ARIA role; no `role` attribute is added. This is correct per the spec

---

## ADR-013: Select: composable combobox pattern, `hidden` attribute, and Storybook a11y inconclusive

**Date:** 2026-04-04
**Status:** Accepted

### Context

Select is the most complex Tier 2 component. It requires a custom dropdown with keyboard navigation, styled to match `Input`, using the ARIA combobox pattern (`role="combobox"` + `role="listbox"`). A native `<select>` cannot be reliably styled to match across browsers.

### Decisions

**1. Composable multi-component API**

Select is composed of five parts: `Select` (root context provider), `SelectTrigger` (combobox button), `SelectContent` (listbox container), `SelectItem` (option), and `SelectSeparator` (visual divider). Consumers compose them declaratively. This matches the pattern used by Radix Select and shadcn/ui, giving consumers control over content without forcing them to pass an array of option objects as props.

**2. `hidden` attribute on listbox instead of conditional rendering**

The listbox `<div role="listbox">` is always in the DOM with `hidden={!open}`. This ensures `aria-controls` on the trigger always resolves to a valid element. Conditional rendering (`{open && <div>}`) would leave `aria-controls` pointing to a non-existent element when closed, which is valid per ARIA 1.2 but flagged by axe-core. The `hidden` attribute removes the element from the accessibility tree while keeping it in the DOM, solving both concerns. It also allows `SelectItem` components to register their labels on mount, so the trigger can display the selected option's label without the listbox being visible.

**3. Registry version counter for synchronous label display**

`SelectItem` registers its value, label, and ref via `useLayoutEffect` on mount. The option registry is a `Map` stored in a ref for stable identity. A `registryVersion` state counter increments on each registration, included as a `useMemo` dependency for the context value. This forces context consumers (notably `SelectTrigger`) to re-render when options register, enabling the trigger to display the selected option's label immediately after mount.

**4. `aria-label` fallback for combobox accessible name**

`role="combobox"` has `nameFrom: author`, so text content does not contribute to the accessible name. When no `aria-labelledby` is present (i.e., outside a `FormField`), the trigger derives `aria-label` from the selected option label, the `placeholder` prop, or a fallback `"Select"`. Inside `FormField`, `aria-labelledby` from the `Label` takes precedence and `aria-label` is omitted.

**5. Known Storybook a11y panel inconclusive**

The Storybook accessibility panel reports `aria-controls` as "inconclusive" on Select stories. This is a tooling limitation: axe-core runs in the parent frame and cannot resolve element IDs inside the story iframe. Console inspection confirms the DOM is correct: `aria-controls` on the trigger matches `id` on the listbox, which is present in the DOM with `hidden=""`. The IDs match. This is not a WCAG violation.

### Consequences

- The composable API requires five imports for full usage but matches industry convention and is self-documenting
- The `hidden` attribute approach means option elements exist in the DOM when closed, but are excluded from the accessibility tree
- The registry pattern adds a render cycle on mount but ensures labels are always available to the trigger
- No third-party UI primitive dependencies: all keyboard navigation, type-ahead, and ARIA semantics are owned

**Implementation note (2026-04-16):** The option registry described in decision 3 has been extracted into `src/hooks/use-option-registry.ts` for reuse by Combobox. The architectural approach (Map in a ref, version counter for context re-render) is unchanged. The extraction is a refactor for code sharing, not a design change.

---

## ADR-014: Tier 3 Batch 1: Alert, Progress, and Skeleton design decisions

**Date:** 2026-04-04
**Status:** Accepted

### Context

Alert, Progress, and Skeleton are the first Tier 3 (feedback & display) components. Each has distinct design requirements that diverge from the interactive component patterns established in Tiers 1-2.

### Decisions

**1. Alert: controlled-only dismiss, no internal state**

Alert accepts an optional `onDismiss?: () => void` prop. When provided, a dismiss button renders. There is no internal `open`/`isOpen` state; the consumer owns visibility entirely. This is consistent with React's controlled component pattern and avoids the complexity of dual controlled/uncontrolled modes for a simple presentational component. The dismiss button is a plain `<button>` element with ghost styling, not a `Button` component, which avoids circular import risk and over-engineering for a single icon button.

**2. Progress: two CVA instances (track vs. fill)**

Progress uses `progressTrackVariants` for the outer track (owns `size`) and `progressFillVariants` for the inner fill (owns `intent`). This separation exists because `size` and `intent` apply to different DOM elements. Combining them in a single CVA instance would require passing the full variant set to both elements, with unused variants on each. The two-instance approach keeps each CVA focused on the element it styles.

**3. Skeleton: no variant/intent, no size prop, hardcoded `aria-hidden`**

Skeleton is a purely structural component with no semantic color meaning. It has a `shape` prop (`rect`, `circle`, `text`) but no `variant`, `intent`, or `size`. Consumers control dimensions via `className` or `style`; this is intentional because skeleton dimensions must match the content they replace, which varies per usage. `aria-hidden="true"` is hardcoded and not overridable via props. Skeleton is purely visual decoration; screen reader announcements for loading state belong to the parent context (e.g., `aria-busy` on a container), never on the skeleton itself. Allowing consumers to remove `aria-hidden` would create an accessibility antipattern.

**4. Progress indeterminate mode: CSS animation with reduced-motion support**

When `value` is `undefined`, Progress enters indeterminate mode with a CSS animation (`nuka-progress-indeterminate` keyframe). `aria-valuenow` is genuinely omitted (not set to `undefined` as a string) per the ARIA progressbar specification. `@media (prefers-reduced-motion: reduce)` disables the animation; no JavaScript prop needed.

### Consequences

- Alert's controlled-only pattern is simpler to implement and test; consumers who need uncontrolled dismiss wrap it in their own state
- The two-CVA-instance approach for Progress establishes a pattern for future components with multi-element styling (e.g., Slider already uses this)
- Skeleton's lack of variant/intent reinforces that the pattern is opt-in per component, not mandatory, joining Divider (ADR-008) and Kbd (ADR-012) in this category
- Reduced-motion handling via CSS `@media` query is consistent across Progress and Skeleton, with no per-component JavaScript required

**See also:** ADR-025 extracts the dismiss button into a shared `DismissButton` utility (`src/utils/dismiss-button.tsx`), superseding the inline implementation described in decision 1 above.

---

## ADR-015: `@floating-ui/react` as sanctioned external dependency

**Date:** 2026-04-04
**Status:** Accepted

### Context

Tooltip and Popover require floating position logic: scroll observation, overflow boundary detection, flip/shift/arrow middleware, cross-browser measurement, and real-time repositioning on scroll/resize. This is the same class of problem that motivated ADR-009's removal of Radix UI, but the scope and nature of the dependency are fundamentally different.

### Decision

`@floating-ui/react` is added to `dependencies` as the only deliberate exception to the no-third-party-UI-primitives policy established in ADR-009.

### Reasoning

The distinction from Radix UI is categorical, not a matter of degree:

- **Radix UI** imposes a full component API: it owns rendering, ARIA semantics, keyboard navigation, and state management. Using it means delegating the entire component contract to a third party.
- **Floating UI** provides a positioning primitive. It computes `{ x, y }` coordinates and exposes hooks for interaction detection (`useHover`, `useClick`, `useDismiss`). It does not render any DOM elements, impose any component structure, or manage accessible names/roles beyond what the consumer explicitly configures.

Rolling floating position logic first-party would produce a worse implementation with real edge cases around:

- `ResizeObserver` and `IntersectionObserver` cross-browser behavior
- Scroll container detection across shadow DOM boundaries
- Overflow boundary calculation with nested scrolling contexts
- Sub-pixel measurement rounding errors

These are positioning math problems, not component design problems. Owning them adds maintenance burden without demonstrating any component architecture skill.

### Consequences

- `@floating-ui/react` is the sole external UI-adjacent dependency. This exception is narrow and deliberate.
- Future floating components (DropdownMenu, Dialog popover mode, DatePicker) reuse this dependency: no additional dependency decisions required.
- The library is used as a primitive: all ARIA semantics, focus management, and component structure remain first-party.
- If `@floating-ui/react` is ever abandoned, the migration surface is limited to positioning logic; no component APIs would need rewriting.

### Alternatives considered

**First-party positioning engine**: rejected. The implementation complexity is high, the edge cases are browser-specific, and the result would be strictly worse than Floating UI's battle-tested solution. This is not a learning opportunity; it is a solved problem.

**CSS Anchor Positioning (`anchor()`)**: not yet viable. Browser support is insufficient (no Firefox, no Safari stable as of early 2026). Revisit when baseline support reaches 90%+.

---

## ADR-016: Tooltip and Popover compound component design

**Date:** 2026-04-04
**Status:** Accepted

### Context

Tooltip and Popover are the first floating UI components in nuka-ui. They share positioning infrastructure (`@floating-ui/react`) but have distinct interaction models, ARIA patterns, and focus management requirements.

### Decisions

**1. Compound component pattern (Root + Trigger + Content)**

Both components use the same compound structure:

```tsx
<Tooltip>
  <TooltipTrigger>...</TooltipTrigger>
  <TooltipContent>...</TooltipContent>
</Tooltip>
```

The Root component (`Tooltip`, `Popover`) is a context provider that owns state and Floating UI configuration. It renders no DOM element. Trigger and Content are separate components that consume context.

This pattern was chosen over a single-prop wrapper (`<Tooltip content="...">`) because:

- It allows arbitrary trigger elements via `asChild`: tooltips on icon buttons, links, or custom components
- It gives consumers full control over content rendering: Popover content can contain forms, lists, or any interactive elements
- It aligns with the compound pattern established by `Select` (ADR-013) and anticipated by Tier 4 components (Dialog, DropdownMenu, Tabs)

**2. Tooltip interaction model: hover + focus, non-interactive content**

- Opens on hover (with configurable delay, default 600ms) and focus (immediate, no delay)
- Closes on mouseleave, blur, and Escape
- Content has `role="tooltip"` and `pointer-events-none`; tooltips are never interactive
- Trigger uses `aria-describedby` pointing to the tooltip's `id`
- `side` prop on the Root controls placement (`top`, `right`, `bottom`, `left`)

The delay applies only to hover-open, not focus-open. Focus-triggered tooltips must be immediate per WCAG 1.4.13 (Content on Hover or Focus); the user has already made an explicit action.

**3. Popover interaction model: click, interactive content**

- Opens on click, closes on Escape and outside click
- Content has `role="dialog"`; Popover panels are interactive regions
- Focus moves into the panel on open (first focusable child, or the panel itself via `tabIndex={-1}`)
- Focus returns to the trigger on close (handled natively by Floating UI's `useDismiss`)
- Trigger uses `aria-expanded` and `aria-controls`
- No focus trap; that belongs to Dialog (Tier 4), not Popover

**4. Portal rendering for both**

Both render content via `ReactDOM.createPortal(..., document.body)` to escape stacking contexts. Content is conditionally rendered (`{open && <portal>}`), not hidden with `hidden` attribute. Unlike Select (ADR-013), there is no registry pattern that requires options to be in the DOM when closed.

SSR safety: both Content components guard with `typeof document === 'undefined'`.

**5. No variant/intent on either component**

Tooltip and Popover are structural chrome: they carry no semantic color meaning. Tooltip has a single dark surface style; Popover has a single bordered surface style. This follows the precedent set by Divider (ADR-008), Kbd (ADR-012), and Skeleton (ADR-014).

### Consequences

- The compound pattern adds import count (3 per component) but is self-documenting and matches industry convention (Radix, shadcn/ui, Ark UI)
- Tooltip and Popover establish the Floating UI integration pattern for all future floating components
- The clear separation between Tooltip (non-interactive, `role="tooltip"`) and Popover (interactive, `role="dialog"`) prevents misuse; consumers cannot accidentally put interactive content in a tooltip
- `side` on Tooltip Root (not Content) keeps placement configuration where it belongs: at the `useFloating` call site

---

## ADR-017: Toast: singleton store, no provider, queue design, and action slot

**Date:** 2026-04-04
**Status:** Accepted

### Context

Toast is a programmatic notification system. Unlike other nuka-ui components, it is invoked imperatively (`toast('message')`) rather than declaratively. This requires a state management pattern that works outside the React render tree.

### Decisions

**1. Module-level singleton store instead of Context/Provider**

The store is a plain TypeScript module (`toastStore.ts`) with no React dependency. State lives in a module-level `let state: ToastItem[]` variable. React subscribes via `useSyncExternalStore(store.subscribe, store.getSnapshot)`. This means `toast()` works from event handlers, async callbacks, and non-React code without any provider in the component tree. A Context-based approach would require `<ToastProvider>` wrapping the app, which adds ceremony for no benefit, since toast state is inherently global (one notification queue per page).

**2. `useSyncExternalStore` over `useState` + `useEffect`**

`useSyncExternalStore` is React's sanctioned API for reading external mutable state. It handles concurrent mode tearing, server-side rendering (via `getServerSnapshot`), and automatic re-rendering. Using `useState` + `useEffect` to sync external state is fragile and prone to tearing in React 18+ concurrent features.

**3. Queue with max 5 visible toasts**

More than 5 simultaneous toasts overwhelm the user. New toasts beyond the limit are queued (`visible: false`) and promoted FIFO as visible toasts dismiss. The queue is transparent to the consumer: `toast()` always accepts calls regardless of current count. Auto-dismiss timers start when a toast becomes visible, not when it's queued.

**4. `dismissing` flag for exit animation**

When `toast.dismiss(id)` is called, the toast is marked `dismissing: true` (triggering `data-state="closed"` CSS animation) but remains in the DOM for 300ms (the exit animation duration). After 300ms, `remove(id)` filters it from state. This decouples animation timing from React rendering.

**5. `duration: Infinity` for persistent toasts**

`Infinity` is a valid JavaScript number that naturally passes `if (duration === Infinity) return` checks without special-casing string sentinels or nullable types. The timer simply never starts.

**6. `__reset()`: dev/test only, not part of public API**

`toastStore.__reset()` clears all toasts synchronously. It is exported from `toastStore.ts` but intentionally not re-exported from `src/index.ts`. The double-underscore prefix is a conventional signal that this is internal. It is necessary for Storybook story isolation and test `beforeEach` cleanup.

**7. `action` slot on `ToastItem`**

`ToastItem.action` is an optional `{ label: string; onClick: () => void }` that renders an inline action button (e.g., "Undo") in the toast. This is a common real-world pattern that cannot be achieved with message strings alone. The action button dismisses the toast after executing the callback. The slot is minimal (a single label and callback) rather than accepting arbitrary React nodes, which would complicate the store's serializable-friendly shape.

### Consequences

- No `<ToastProvider>` needed: consumers render `<Toaster />` once, call `toast()` anywhere
- The singleton pattern means only one toast queue per JavaScript context; multiple `<Toaster />` instances would render duplicate toasts (documented, not prevented)
- `__reset()` must be called in test/story setup to avoid state leaking between tests
- The `action` slot is additive and does not affect consumers who don't use it
- CSS keyframes for enter/exit animation live in `src/styles/animations.css`, following the Spinner pattern. A `@media (prefers-reduced-motion: reduce)` override disables all `data-state` animations globally

---

## ADR-018: Banner: `role="region"` distinction from Alert, no portal, required `aria-label`

**Date:** 2026-04-04
**Status:** Accepted

### Context

Banner is a full-width informational strip for persistent, non-urgent messaging (announcements, maintenance notices, cookie consent). It is visually similar to Alert but has a fundamentally different semantic role.

### Decisions

**1. `role="region"` instead of `role="alert"`**

Alert uses `role="alert"`, which triggers an assertive live-region announcement, appropriate for urgent, transient feedback (form errors, action results). Banner conveys persistent contextual information that should not interrupt the user. `role="region"` with a required `aria-label` creates a navigable landmark without assertive announcements. This is the key semantic distinction between the two components.

**2. `aria-label` required at the type level**

`role="region"` without an accessible name is a landmark without identity: screen reader users see an anonymous region, which is worse than no landmark. The `aria-label` prop is required in the TypeScript interface (not optional) by using `Omit<React.HTMLAttributes, 'aria-label'>` to remove the optional default and re-declaring it as required. This makes the accessibility requirement a compile-time error, not a runtime or audit discovery.

**3. No portal, no fixed positioning**

Banner does not render via `createPortal` and does not apply `position: fixed` or `position: sticky`. Consumers own placement: a Banner at the top of the page is the consumer's layout decision, not the component's. This avoids z-index conflicts, scroll behavior assumptions, and stacking context issues that would arise from opinionated positioning.

**4. Intent-only CVA: no `variant` prop**

Banner has one visual weight: full-width, border-left accent. There is no meaningful secondary, outline, or ghost treatment. Adding `variant` would create unused combinations. Intent alone (default, success, danger, warning) covers all real use cases. This is the first component to use intent-only CVA without compound variants.

**5. `action` slot**

An optional `action?: React.ReactNode` slot renders between the message content and the dismiss button. This covers common patterns like "Learn more" links and "Accept"/"Decline" button pairs. The slot accepts arbitrary React nodes rather than a structured `{ label, onClick }` shape (unlike Toast's action) because Banner actions are often multi-element layouts.

### Consequences

- Banner and Alert are clearly distinct: Banner is persistent context (`role="region"`), Alert is urgent feedback (`role="alert"`)
- The required `aria-label` enforces accessibility at build time: no consumer can accidentally ship an anonymous region
- No positioning opinions means Banner works in any layout context without fighting consumer CSS
- Intent-only CVA is simpler than the standard variant x intent pattern: no compound variants needed

---

## ADR-019: EmptyState: dual illustration/icon slots, priority rule, no CVA

**Date:** 2026-04-04
**Status:** Accepted

### Context

EmptyState is a blank-slate component for empty lists, search results, and tables. It is a structural layout component with no semantic color meaning.

### Decisions

**1. `illustration` and `icon` as separate slots with priority**

Two visual slots serve different fidelity levels: `illustration` for large artwork (SVGs, images, custom components) and `icon` for simpler icons. When both are provided, `illustration` takes precedence and `icon` is silently ignored. The implementation is `const visual = illustration ?? icon ?? null`, a single line that handles all cases without conditional branching.

This dual-slot approach is preferred over a single `visual` slot because it makes the API self-documenting: consumers know exactly what fidelity level they're providing, and the component can apply appropriate container styling for each.

**2. `heading` is required**

An EmptyState without a heading is not a valid UI pattern: the user needs to know why the area is empty. Making `heading` required at the type level prevents consumers from rendering a bare icon with no explanation.

**3. `role="status"`**

EmptyState communicates that content is absent, a state condition, not an error or alert. `role="status"` is a polite live region that announces changes without interrupting the user. This is correct for content that transitions from populated to empty (e.g., after filtering).

**4. No CVA, no variant, no intent**

EmptyState is a neutral layout container. It has no semantic color meaning; there is no "danger empty state" or "success empty state." All visual treatment is structural (centering, spacing, max-width). Consumers who need custom styling use `className`. This follows the precedent set by Divider (ADR-008) and Kbd (ADR-012).

### Consequences

- The `illustration ?? icon ?? null` priority rule is simple and predictable: no surprising behavior when both slots are populated
- Required `heading` prevents incomplete empty states at compile time
- No CVA means no `EmptyStateVariantProps` export: the component has a smaller API surface than most nuka-ui components
- `role="status"` ensures screen reader users are informed when content disappears

---

## ADR-020: Timeline: compound component, semantic HTML, intent on item only

**Date:** 2026-04-04
**Status:** Accepted

### Context

Timeline displays a vertical sequence of events. It is a display-only component with ordered data, distinct from interactive step indicators or progress trackers.

### Decisions

**1. Compound component: `Timeline` + `TimelineItem`**

`Timeline` renders as `<ol>` (root) and `TimelineItem` renders as `<li>` (entry). This two-component pattern provides correct list semantics (screen readers announce "list with N items") while giving consumers full control over each item's content. A single-component API with an `items` array prop would lose the ability to pass arbitrary children to individual items.

**2. `<ol>` over `<ul>`**

Timeline events have a defined sequence: they are ordered by time. An ordered list (`<ol>`) is semantically correct. An unordered list (`<ul>`) would misrepresent the data structure to assistive technology.

**3. `<time>` element for timestamps**

When `timestamp` is provided, it renders inside a `<time>` element. This is the semantically correct HTML element for temporal data. It enables assistive technology and user agents to recognize the content as a date/time value.

**4. `intent` on `TimelineItem` only, not on `Timeline`**

Individual events have different semantic states (success, danger, warning). The timeline as a whole does not. Placing `intent` on the root would require all items to share the same color, which contradicts the primary use case of mixed-status event sequences.

**5. Marker-only CVA (`timelineItemMarkerVariants`)**

Only the circular marker dot receives intent-based styling. The content area (title, description, timestamp) uses neutral text tokens regardless of intent. This keeps the visual emphasis on the timeline's structural elements without overwhelming the text content with color.

**6. Connector line via CSS with `group`/`group-last:hidden`**

The vertical connector between items is a `<div>` with `w-px` and `bg-(--nuka-border-base)`. The `<li>` has the `group` class, and the connector has `group-last:hidden`, Tailwind's first-class utility for hiding an element when its group parent is the last child. This correctly hides the connector on the last item without SVG, pseudo-elements, or arbitrary CSS selectors.

### Consequences

- `Timeline` + `TimelineItem` is the third compound component in nuka-ui (after Select and Tooltip/Popover), establishing the pattern as standard for multi-element components
- `<ol>`/`<li>` semantics give screen reader users accurate list structure information
- Intent on individual items enables mixed-status timelines, the primary use case
- The `group`/`group-last:hidden` connector approach uses only first-class Tailwind utilities: no custom CSS needed

---

## ADR-021: Responsive prop pattern for layout primitives

**Date:** 2026-04-05
**Status:** Accepted

### Context

Layout components (Stack, Grid, Container) need per-breakpoint control over direction, gap, column count, alignment, and other geometric properties. A fixed set of props (`direction`, `directionSm`, `directionMd`, ...) causes prop explosion. Inline styles bypass Tailwind's design system integration.

### Decision

Introduce a `Responsive<T>` type that accepts either a scalar value or a breakpoint object:

```ts
type Breakpoint = "base" | "sm" | "md" | "lg" | "xl" | "2xl";
type Responsive<T> = T | Partial<Record<Breakpoint, T>>;
```

Uses Tailwind v4 default breakpoints. The `base` key represents mobile-first defaults (no breakpoint prefix). Both `direction="row"` and `direction={{ base: "column", md: "row" }}` are valid.

### Consequences

- Scalar and object forms both valid: simple cases stay simple, complex cases are possible
- `resolveResponsiveClasses` utility handles resolution for all layout components
- All emitted classes must be statically present in source for Tailwind scanning (see ADR-022)
- Adding new breakpoints would be additive and non-breaking

### Alternatives considered

**Per-breakpoint prop suffixes** (`directionSm`, `directionMd`, ...): rejected due to prop explosion. Every layout prop would multiply by the number of breakpoints.

**Inline styles**: rejected because they bypass Tailwind's class-based system, lose theming coherence, and make responsive behavior impossible without JavaScript media query listeners.

---

## ADR-022: Lookup table strategy for responsive classes

**Date:** 2026-04-05
**Status:** Accepted

### Context

Tailwind v4 scans source files for complete class strings at build time. Dynamically constructed class strings (e.g., `` `${prefix}:flex-row` ``) are not detectable by the scanner and will be purged from the output CSS.

### Decision

Use static lookup tables mapping every (breakpoint, prop value) pair to a complete Tailwind class string. A `buildLookup` helper generates breakpoint-keyed records from a base map at module initialization. The `resolveResponsiveClasses` utility resolves `Responsive<T>` values against these tables, returning an array of class strings for `cn()` to spread.

### Consequences

- Every valid class is enumerable and statically present as a complete string literal in source
- Tables are verbose but explicit and safe: no runtime string construction
- The utility is independently testable with pure function tests
- Adding a new prop value or breakpoint requires adding entries to the lookup table; the type system enforces completeness

### Alternatives considered

**CSS custom properties with inline styles**: rejected because it loses Tailwind integration and theming coherence. Gap would need `style={{ gap: 'var(--space-4)' }}` instead of `gap-4`.

**Dynamic string construction** (`` `${bp}:gap-${n}` ``): rejected because classes are not detectable by Tailwind's scanner and would be purged.

---

## ADR-023: Extract useControllableState shared hook

**Date:** 2026-04-07
**Status:** Accepted

### Context

The controlled/uncontrolled state pattern was inlined identically across Switch, Slider, RadioGroup, Tooltip, Popover, and Select (twice). Each copy consisted of three lines: an `isControlled` boolean, an internal `useState`, and a derived current value. The pattern is pure boilerplate with no component-specific variation.

### Decision

Extracted into `src/hooks/use-controllable-state.ts`. The hook accepts a controlled value, a default value, and an optional onChange callback. It returns the current value and a stable setter. The setter updates internal state when uncontrolled and always calls onChange.

### Consequences

- Six components simplified. Each loses approximately 5 lines of boilerplate.
- All future stateful components (Collapsible, Accordion, Tabs, Dialog, DropdownMenu) use the hook from day one.
- The hook is tested in isolation. Component tests no longer need to cover the controlled/uncontrolled switching logic exhaustively.
- Internal utility, not exported from the public package entry point.

---

## ADR-024: Extract useFormFieldProps shared hook

**Date:** 2026-04-07
**Status:** Accepted

### Context

Every form control (Input, Textarea, Slider, Switch, RadioGroup, SelectTrigger) contained an identical block that resolved id, disabled, aria-invalid, aria-describedby, and aria-required by merging consumer props with FormFieldContext values. The logic was copy-pasted verbatim with no component-specific variation, except Switch which intentionally omits aria-invalid.

### Decision

Extracted into `src/hooks/use-form-field-props.ts`. The hook accepts consumer prop values and an options object, calls `useFormField()` internally, and returns resolved ARIA attributes ready to spread. A `skipInvalid` option allows components like Switch to opt out of aria-invalid without fighting the hook output.

### Consequences

- Six components simplified.
- Future form controls (DatePicker input, Combobox) receive correct FormField integration by calling the hook with no manual assembly required.
- The aria-describedby merge logic (consumer value + context ids, filter, join) exists in one place. A future change to FormField's id scheme propagates automatically.
- Internal utility, not exported from the public package entry point.

### Note on Input's intent fallback

Input derives aria-invalid from `intent="danger"` as a tertiary fallback after consumer prop and context hasError. This is Input-specific and remains in Input.tsx rather than inside the hook.

---

## ADR-025: Internal DismissButton and Portal utilities

**Date:** 2026-04-07
**Status:** Accepted

### Context

Four components (Alert, Banner, Tag, Toast) each contained a hand-rolled dismiss button with slightly different styles. Alert was missing the focus ring present in Banner, and Toast used a unicode character instead of an SVG. Two components (Tooltip, Popover) contained identical portal rendering with an SSR guard.

### Decision

Extracted `DismissButton` (`src/utils/dismiss-button.tsx`) and `Portal` (`src/utils/portal.tsx`) as internal utilities. Both are not exported from the public package entry point.

DismissButton uses a single SVG (`viewBox="0 0 24 24"`) with wrapper sizing via `size-3` (sm) and `size-4` (md), following the established sizing pattern used by Switch thumb and Checkbox/Radio indicators.

Portal wraps `ReactDOM.createPortal` with a `typeof document === "undefined"` SSR guard, replacing the identical guard previously inlined in TooltipContent and PopoverContent.

### Consequences

- Alert's missing focus ring is fixed as a side effect of the extraction.
- Toast's unicode dismiss character is replaced with the SVG used by Alert/Banner/Tag.
- All four dismissible components now have identical dismiss button behavior.
- Tooltip and Popover no longer contain inline portal + SSR guard code.
- Dialog, Sheet, and DropdownMenu (navigation batch) use Portal and DismissButton from day one.

### Alternatives considered

**Using Button component**: rejected. Button is a public component with variant/intent/size props. A dismiss button has none of these. The circular import concern is real and remains valid.

**Two separate SVG shapes for sm/md sizes**: rejected. One SVG scales via wrapper `size-*` classes, consistent with the sizing pattern established across Switch, Checkbox, and Radio.

---

## ADR-026: Card: variant-only, no intent, compound pattern with internal reuse

**Date:** 2026-04-07
**Status:** Accepted

### Context

Card is a surface container. It needs visual differentiation (elevated, outlined, filled) but carries no semantic color meaning: there is no "danger card" or "success card" in standard UI patterns.

### Decisions

1. No `intent` prop. Variant alone covers all valid visual states. Follows Divider (ADR-008) and Banner (ADR-018) precedent.
2. Compound component pattern: Card + CardHeader + CardTitle + CardDescription + CardBody + CardFooter. Each sub-component is independently exported and composable.
3. CardTitle delegates to Heading, CardDescription delegates to Text, CardHeader and CardFooter use Stack. Component reuse rules (CLAUDE.md) applied throughout.
4. Default root element is `div`. asChild available for polymorphism (e.g. rendering Card as an `<article>` or `<section>` when semantics require it).
5. CardTitle accepts the full `HeadingElement` union (`h1`-`h6`) via its `as` prop, defaulting to `h3`. No subset constraint to avoid type mismatches under `exactOptionalPropertyTypes`.
6. CardHeader and CardFooter use Stack when `asChild` is false. When `asChild` is true, they skip Stack entirely and render via Slot directly.
7. Shadow tokens (`--shadow-sm`, `--shadow-md` primitives and `--nuka-shadow-card` semantic) added to support the `elevated` variant. Dark mode uses hardcoded higher-opacity values for visibility on dark surfaces.

### Consequences

- Consumers who need custom card colors use className: no variant explosion.
- CardTitle heading level is consumer-controlled via the `as` prop, supporting correct document outline in any context.
- Sub-components are independently importable for cases where only part of the Card structure is needed.
- Shadow tokens establish the pattern for future components that need elevation (Dialog, Sheet, DropdownMenu).

### Alternatives considered

**Adding `intent` prop**: rejected. Card is structural chrome. Intent would create variants that have no standard design meaning and would add unused compound variant definitions.

**Constraining `CardTitle` `as` to `h2`-`h4`**: rejected. With `exactOptionalPropertyTypes`, a consumer passing a valid `HeadingElement` value outside the subset would get a type error. The full union avoids this and preserves flexibility.

**Wrapping Slot inside Stack for asChild**: rejected. Stack adds its own flex layout classes that conflict with the consumer's child element when asChild is true. The explicit conditional branch keeps behavior predictable.

---

## ADR-027: Collapsible and Accordion: CSS grid-rows animation, two context layers

**Date:** 2026-04-07
**Status:** Accepted

### Context

Collapsible requires a height animation without JavaScript measurement. Accordion requires single/multiple open state coordination and keyboard navigation between triggers.

### Decisions

1. CSS grid-rows animation (`0fr` to `1fr`) for Collapsible, applied via Tailwind utilities (`grid grid-rows-[0fr]` base, `data-[state=open]:grid-rows-[1fr]` open state) and `transition-[grid-template-rows]`. No custom CSS classes in `src/styles/index.css`. The inner div with `overflow-hidden` prevents content from being visible during the `0fr` state. `motion-reduce:transition-none` disables the transition for users who prefer reduced motion.

2. Accordion uses two context layers: root context for shared state and config, item context for per-item open state. This avoids prop-drilling through AccordionItem.

3. Accordion delegates its content animation entirely to Collapsible by wrapping CollapsibleTrigger and CollapsibleContent internally. Accordion does not re-implement open/close logic.

4. AccordionTrigger chevron uses Icon wrapping an SVG, per CLAUDE.md reuse rules.

5. `useControllableState` is used at the Accordion root for both single and multiple modes. The type parameter differs: `string | undefined` for single, `string[]` for multiple.

6. Keyboard navigation (ArrowUp/Down, Home/End) operates on `button[data-accordion-trigger]` elements via `querySelectorAll` on the root ref. Focus wraps cyclically.

### Consequences

- The grid-rows approach is widely supported and produces smooth animations without measuring DOM heights. All styling is pure Tailwind: no custom CSS classes needed.
- Two context layers add file count but make AccordionItem a clean composition boundary.
- Accordion test coverage can rely on Collapsible's animation tests; Accordion only needs to test state coordination and keyboard navigation.
- The `data-accordion-trigger` attribute enables keyboard navigation to target only accordion triggers, not nested button elements.

---

## ADR-028: Tabs: hidden attribute panels, roving tabindex, activation modes

**Date:** 2026-04-07
**Status:** Accepted

### Context

Tabs needs to handle panel content preservation, keyboard navigation following the ARIA
tabs specification, and two common activation modes.

### Decisions

1. Inactive panels use the `hidden` attribute, not conditional rendering. This preserves
   form state, scroll position, and avoids remounting. The hidden attribute excludes panels
   from the accessibility tree without conditional rendering.

2. Roving tabindex on triggers. Only the active/focused trigger has tabIndex=0.
   All others have tabIndex=-1. This matches the ARIA tabs keyboard interaction model
   and prevents Tab from cycling through every trigger.

3. Two activation modes: automatic (selection follows focus, the common case) and
   manual (Enter/Space required to select, useful for tabs with expensive renders).

4. Three visual variants on TabsList: underline (default), pill, boxed. These are
   style-only: behavior is identical. Variant lives on TabsList, not Tabs root,
   because it is a presentation concern of the list container.

5. IDs derived from a single useId call at the root, suffixed per value. This avoids
   N useId calls for N tabs.

### Consequences

- hidden-attribute approach means N panel DOM nodes always exist. Acceptable for standard
  tab counts; consumers with 50+ tabs should reconsider the UI pattern.
- Roving tabindex requires coordinated tabIndex state across all triggers, managed via
  Tabs root context.

---

## ADR-029: Dialog and Sheet: first-party focus trap, scroll lock, shared utilities

**Date:** 2026-04-07
**Status:** Accepted

### Context

Dialog requires WCAG 2.4.3-compliant focus management (focus moves into dialog on open,
returns to trigger on close, Tab cycles within dialog) and scroll lock. Sheet is
semantically identical to Dialog with different visual presentation.

### Decisions

1. First-party `useFocusTrap` hook using the `tabbable` package (already a transitive
   dependency via `@floating-ui/react`) to query focusable elements. `tabbable` is a
   utility library for DOM queries, not a UI primitive: using it does not violate ADR-009.

2. First-party `useScrollLock` with ref-counting for stacked modals and scrollbar-width
   compensation to prevent layout shift.

3. Dialog and Sheet have separate React contexts but share the same utility hooks.
   Sharing context would couple two components that may diverge in API.

4. `DialogTitle` is required: verified at runtime in development via `console.error`.
   `aria-labelledby` without a corresponding element produces an invalid ARIA reference.

5. Sheet is implemented as a parallel structure to Dialog, not as a Dialog prop variant.
   This keeps each component's API clean and avoids a single component with too many props.

6. Sheet slide animations use Tailwind transition utilities (`transition-transform`,
   `data-[state=open]:translate-x-0`) rather than CSS keyframes. This keeps all sheet
   styling in the component file and avoids adding side-specific keyframes to index.css.
   Dialog uses CSS keyframes for its scale + fade animation because Tailwind does not
   have a built-in scale animation utility that composes with the centered transform.

### Consequences

- Focus trap handles the portaled-children edge case via `focusout`/`relatedTarget` check.
  This covers the most common case (a Popover inside a Dialog).
- Scroll lock ref-counting means the first Dialog to open is the last to release the lock.
- `DialogTitle` runtime check adds a `useEffect` per Dialog instance. Acceptable cost.
- `tabbable` is a transitive dependency. If `@floating-ui/react` drops it, it can be
  added as a direct dependency with no code changes.

---

## ADR-030: Menu system: shared navigation hook, ARIA menu vs listbox distinction

**Date:** 2026-04-08
**Status:** Accepted

### Context

DropdownMenu, ContextMenu, and Menubar all need arrow-key navigation with type-ahead,
but with menu semantics (role="menu", role="menuitem") distinct from listbox semantics
(role="listbox", role="option") used by Select.

### Decisions

1. Shared useMenuNavigation hook. This is the third navigation pattern after RadioGroup
   and Select. It handles the ARIA menu keyboard spec: arrow keys, Home/End, type-ahead,
   Escape, Tab-to-close (not Tab-to-trap).

2. Disabled items remain focusable via arrow keys (per ARIA menu spec). This differs from
   disabled options in Select which are skipped. The difference reflects the ARIA spec
   distinction between menu items and listbox options.

3. ContextMenu uses Floating UI virtual element API for cursor-position placement.
   The virtual element approach is the correct pattern for positioning at arbitrary
   coordinates without a DOM anchor.

4. ContextMenu trigger has no aria-haspopup or aria-expanded. Context menus are
   not announced in advance. Adding these attributes would be incorrect per the ARIA spec.

5. Menubar cross-menu coordination via root context. When a menu is open and the user
   arrows horizontally, the Menubar root closes the current menu and opens the adjacent
   one atomically. This requires root-level knowledge of which menu is open.

6. Shared CVA variants in src/components/Menu/. All three menu components share
   menuItemVariants, menuContentVariants, and base components (MenuItemBase, etc.)
   from a shared internal directory. Nothing in Menu/ is part of the public API.

### Consequences

- useMenuNavigation replaces the navigateItems placeholder in docs/COMPONENTS.md.
- ContextMenu and DropdownMenu share the same CVA variants for menu items via the
  shared Menu/ directory.
- Menubar is the most complex component in this batch due to cross-menu coordination.
  It was built last within the tier.

---

## ADR-031: NavigationMenu, Breadcrumb, Pagination: structural navigation components

**Date:** 2026-04-08
**Status:** Accepted

### Context

Three navigation components needed for site-level navigation patterns. Each is structural chrome with no semantic color intent.

### Decisions

1. **NavigationMenu sub-panels use `role="dialog"`, not `role="menu"`.** Sub-panel content is arbitrary (links, cards, featured content) and follows standard browser Tab focus order. This is the critical distinction from Menubar, whose panels use `role="menu"` with arrow-key navigation. Floating UI handles positioning with the same pattern as Popover.

2. **Breadcrumb root is `<nav aria-label="Breadcrumb">` with `<ol>` list.** `BreadcrumbPage` renders a `<span aria-current="page">`, not an `<a>` tag. The current page is not navigable. Separators use `role="presentation"` with `aria-hidden="true"`.

3. **Pagination uses a compound API with links, not a data-driven `onPageChange` callback.** `PaginationPrevious` and `PaginationNext` use `Button` with `asChild` internally, composing existing button styles rather than reimplementing them. The compound API composes link elements that consumers provide.

4. **No `variant`/`intent` on any of these three components.** They are structural chrome. Color comes from semantic tokens directly, not from CVA compound variants.

### Consequences

- NavigationMenu content panels allow standard Tab navigation. Consumers can put any content inside them without fighting a menu keyboard model.
- Breadcrumb and Pagination are purely structural. Consumers who need router integration use `asChild` on `BreadcrumbLink`, `PaginationLink`, `PaginationPrevious`, and `PaginationNext`.
- Pagination reuses `Button` rather than creating a parallel button system. Any future Button style changes automatically propagate to pagination controls.

---

## ADR-032: Stepper and Sidebar: state inference, responsive rendering, content sharing

**Date:** 2026-04-08
**Status:** Accepted

### Context

Stepper is a multi-step flow indicator with no native ARIA role. Sidebar is the most complex navigation component, requiring three rendering modes (desktop expanded, desktop collapsed icon-only, mobile Sheet drawer) while sharing content across contexts.

### Decisions

1. **Stepper state inference.** Step state (completed/current/upcoming) is inferred from `currentStep` when not explicitly provided. Explicit per-item `state` overrides inference. This allows the common case (sequential flow) to be simple, and the complex case (error on a specific step) to be expressive.

2. **Stepper uses `aria-current="step"` on the current item and `nav`/`ol` semantics** per the ARIA pattern for step indicators. There is no native ARIA role for steppers. The `<nav aria-label="Progress">` wrapper provides a navigation landmark.

3. **Sidebar content sharing between desktop and mobile contexts via context.** `SidebarProvider` stores the expanded/mobile/mobileOpen state. On desktop, `Sidebar` renders as `<aside>`. On mobile, `Sidebar` renders its children inside a `Sheet` from `side="left"`. Content is declared once in JSX and rendered in the appropriate context.

4. **`SidebarMenuButton` `tooltip` prop is required** (not optional) because it provides the accessible name for the icon-only collapsed state. A sidebar button without a label and without a tooltip would be inaccessible. The tooltip renders via the existing `Tooltip`/`TooltipTrigger`/`TooltipContent` components only when the sidebar is collapsed on desktop.

5. **`useMediaQuery` for breakpoint detection.** Simple `window.matchMedia` wrapper, SSR-safe (returns `false` when `window` is undefined). The mobile breakpoint is configurable via `SidebarProvider` prop, defaulting to `(max-width: 768px)`.

6. **No `variant`/`intent` on Stepper root or Sidebar.** Stepper indicator color is derived from step state (completed/current/upcoming/error), not from a variant system. Sidebar is structural chrome. Both follow the precedent of navigation components without CVA (ADR-031).

### Consequences

- Stepper's state inference means consumers only need to set `currentStep` for the common case. The `state` prop is available per item for edge cases like error states.
- `onStepClick` only fires for completed, non-disabled steps. This prevents navigation to future steps.
- Sidebar reuses Sheet (with focus trap and scroll lock) and Tooltip (with Floating UI positioning) rather than building custom drawer/tooltip behavior.
- `useMediaQuery` is an internal utility, not exported from the public package entry point. It is independently testable.

## ADR-033: Token system improvements and WCAG contrast fixes

**Date:** 2026-04-09
**Status:** Accepted

### Context

The token system had six structural gaps (feedback primitive scale, shadow bypass in dark mode, missing accent-fg, missing elevation shadows, missing backdrop overlay, missing disabled tokens) and six pre-existing WCAG 2.2 AA contrast failures in feedback categories. The structural gaps were addressed first by converting feedback primitives from role-named steps to a numeric scale and adding missing semantic tokens. The contrast failures were then resolved as a follow-up.

### Decisions

1. **Feedback primitives converted from role-named to numeric scale.** The old three role-named steps per category (`-subtle`, `-base`, `-emphasis`) provided no intermediate values for the dark-mode semantic layer, forcing all 16 dark-mode feedback tokens to use hardcoded `oklch()` literals. The numeric scale (100-600, six steps per category) was designed so that each step corresponds to an exact value needed by either the light or dark semantic layer. This eliminated all hardcoded dark-mode feedback values. Steps are numbered lightest (100) to darkest (600), matching the accent scale convention.

2. **Intermediate primitive steps (success-250, danger-250) added for dark-mode base surfaces.** The success-300 and danger-300 steps are referenced by both themes for `-base`. In light mode, white text on the surface requires lower lightness (darker). In dark mode, near-black text on the surface requires higher lightness (lighter). No single value passes 4.5:1 with both white and near-black text. Adding intermediate steps decouples the dark-mode base surface from the light-mode base, using the two-layer architecture as designed. The 250 steps are referenced only by dark-mode semantic tokens; light-mode base tokens continue to reference the 300 steps unchanged. Success-250 at oklch(58% 0.16 145) gives 5.04:1 with neutral-950. Danger-250 at oklch(60% 0.20 15) gives 4.59:1.

3. **`--nuka-warning-fg` uses dark text (neutral-900) rather than darkening the warning base color.** Warning amber (hue 85) at the lightness needed for recognizable amber identity cannot achieve 4.5:1 with white text. Darkening to pass contrast produces brown, losing the hue identity. The solution follows the `--nuka-accent-fg` pattern: a separate foreground token for content on filled warning surfaces. The value is `var(--color-neutral-900)` in both themes because warning-base is the same amber in both themes, and dark text provides 7.11:1 contrast. A lighter dark-mode value would be inconsistent with the token's purpose and unnecessary.

4. **Radio inner dot uses `bg-current` driven by parent text color.** The alternative was intent-specific dot color classes, which would require either a new CVA variant axis on Radio or conditional className logic. The `bg-current` approach reuses CSS `currentColor` inheritance: the indicator span sets `text-(--nuka-text-inverse)` as a base, and the warning selection indicator variant overrides with `peer-checked:text-(--nuka-warning-fg)`. The dot inherits the resolved color automatically. This is the same mechanism Checkbox already uses for its SVG checkmark (`stroke="currentColor"`).

5. **`--nuka-accent-fg` is a separate token from `--nuka-text-inverse`.** Both default to `var(--color-neutral-0)`, but they serve different semantic roles. `--nuka-text-inverse` means "text on an inverse surface" and couples to the surface system. `--nuka-accent-fg` means "foreground on an accent-colored surface" and is overridable independently when a consumer customizes the accent color to a lighter value.

6. **`--nuka-bg-overlay` has no primitive.** It is an alpha-composite value (`oklch(0% 0 0 / 0.5)`) that does not fit the discrete-step primitive scale. The 0.5 opacity is an intentional default for both themes, documented as consumer-overridable for dark mode contexts that need higher visual weight.

7. **Shadow primitive bypass in dark mode resolved.** Dark-mode `--nuka-shadow-card` was a hardcoded inline value, bypassing the primitive scale. Dark shadow primitives (`--shadow-sm-dark`, `--shadow-md-dark`, `--shadow-lg-dark`) were added to `:root`, and all dark semantic shadow tokens now reference these via `var()`.

8. **Elevation shadow and disabled token categories established.** `--nuka-shadow-overlay` (medium elevation) and `--nuka-shadow-modal` (high elevation) were added alongside `--nuka-shadow-card` (low elevation). `--nuka-accent-bg-disabled` and `--nuka-border-disabled` extend disabled-state coverage beyond the existing `--nuka-text-disabled` and `--nuka-input-bg-disabled`.

### Consequences

- Dark-mode feedback tokens are all `var()` references. The "hardcoded for dark mode, primitives are light-first" comment is no longer accurate and was removed.
- Consumer overrides now possible that were not before: accent foreground independent of inverse text, modal/overlay shadow elevation independent of card shadow, backdrop overlay opacity, disabled accent and border colors.
- Warning primary buttons and selection indicators render with dark text on amber in both themes. This is visually distinct from other intents by design.
- The `bg-current` pattern in Radio creates a dependency: the indicator span's text color drives the dot color. Changes to indicator text color classes propagate to the dot automatically.
- Info-300 was darkened from 55% to 53%. Info is not an exposed intent in the component API, so no component is directly affected. The adjustment is for architectural correctness.
- Six pre-existing contrast failures are resolved. No previously passing pair was broken.

---

## ADR-034: Dark surface primitive sub-scale and intent-specific foreground tokens

**Date:** 2026-04-09
**Status:** Accepted

### Context

The dark theme semantic layer contained five hardcoded `oklch()` surface values (bg-base, bg-subtle, bg-muted, border-base, input-bg, input-bg-readonly) because no matching primitives existed. This prevented consumers from rethemeing dark surfaces without editing the semantic layer directly.

Separately, all filled colored surfaces (primary buttons, solid badges, stepper indicators) used `text-(--nuka-text-inverse)` for foreground text. In dark mode, `--nuka-text-inverse` resolves to `neutral-950` (14% L). On accent-500 (44% L), this gives only 2.56:1 contrast, failing WCAG AA. The existing `--nuka-accent-fg` token (white in both themes) provides 7.77:1 on accent-500, but no equivalent existed for danger and success intents.

Additionally, `--nuka-accent-bg-subtle` in dark mode referenced `accent-800` (20.8% L), sitting 9 L points below bg-base (30% L). This caused Alert secondary/default, Banner default, and SelectItem selected state to render as dark wells rather than raised tinted surfaces.

### Decisions

1. **`--color-neutral-dark-*` primitive sub-scale on `:root`.** Six named primitives (dark-base, dark-subtle, dark-muted, dark-border, dark-input, dark-input-readonly) hold the dark surface values. The dark semantic layer references them via `var()`. Light and dark surface hierarchies have different lightness targets with no shared steps in the neutral scale, so a separate sub-scale avoids naming ambiguity and makes both independently overridable. Consumers retheme dark surfaces by overriding six primitives on `:root`.

2. **`--nuka-danger-fg` and `--nuka-success-fg` tokens added.** These follow the `--nuka-accent-fg` pattern: dedicated foreground tokens for text on filled colored surfaces. In light mode, both use `neutral-0` (white): 4.65:1 on danger-300 and 5.51:1 on success-300. In dark mode, both use `neutral-950` (near-black): 5.04:1 on danger-250 and 4.65:1 on success-250. White text was considered for dark mode but fails contrast on both surfaces (3.95:1 and 4.28:1) because danger-250 and success-250 are intentionally lighter than their light-mode counterparts.

3. **All filled surface compound variants updated to use intent-specific fg tokens.** `text-(--nuka-text-inverse)` replaced with `text-(--nuka-accent-fg)`, `text-(--nuka-danger-fg)`, `text-(--nuka-success-fg)`, or `text-(--nuka-warning-fg)` as appropriate. This affects `intentCompoundVariants` in variants.ts, Button compoundVariants, Badge solid compoundVariants, and Stepper indicator states. The primary/default cell is the only one with a visible change in dark mode (white text replaces near-black on accent-500).

4. **`--nuka-accent-bg-subtle` in dark mode hardcoded to `oklch(35% 0.02 257)`.** This places the subtle accent surface 5 L points above bg-base (30% L), matching the light-theme gap between accent-100 (96.8% L) and bg-base (100% L). No existing primitive matches this value. The hardcoded approach is consistent with other dark-only values (text-muted, text-subtle tints).

### Consequences

- Dark surface tokens are all `var()` references. Zero hardcoded oklch() surface values remain in the semantic layer except overlay (alpha composite, documented), text tints (intentional, documented), and accent-bg-subtle (dark-only, documented).
- Consumers can retheme dark surfaces by overriding six `:root` primitives. This is documented in CUSTOMIZATION.md.
- Danger and success foreground tokens use dark text in dark mode, matching warning's existing pattern. White text on these surfaces would fail WCAG AA.
- The only visible change is primary/default in dark mode: white text on accent-500 (7.77:1) replacing near-black text (2.56:1).
- Alert, Banner, and SelectItem accent-bg-subtle surfaces lift from 20.8% L to 35% L in dark mode, resolving the visual well effect.

### Alternatives considered

**Extending the neutral scale with dark-range stops**: rejected. The neutral scale is anchored to lightness values (higher number = lower L). Dark surface values at 26-46% L would interleave awkwardly with existing 700-950 stops, creating naming ambiguity.

**Keeping hardcoded values in the semantic layer**: rejected. Prevents consumer theming of dark surfaces without editing the semantic layer.

**White text for all filled surfaces in dark mode**: rejected. Fails WCAG AA on danger-250 (3.95:1) and success-250 (4.28:1). Darkening these surfaces to pass with white would collapse them into the 300-step values, defeating the two-step light/dark architecture.

---

## ADR-035: cloneElement vs Slot for asChild components with internal content

**Date:** 2026-04-11
**Status:** Accepted

### Context

The `asChild` pattern in nuka-ui uses `Slot` to merge props from a wrapper component onto a consumer-provided child element. Slot requires exactly one React element as its child. This works for components like `PaginationLink` and `Button` where the component's `Comp` element has no internal children of its own: the consumer's child IS the sole content.

`PaginationPrevious` and `PaginationNext` are different. They render internal structural content (an Icon + label text) as children of their `Comp` element. When `asChild=true` and `Comp=Slot`, Slot receives both the internal Icon and the consumer's child element, violating the single-child constraint.

### Decision

Components with internal content that use `asChild` bypass `Slot` and use `React.cloneElement` directly. The consumer's child element is cloned with merged props (aria-label, ref, event handlers), and the component's internal content (Icon, label) is injected as the cloned element's children.

```tsx
if (asChild && React.isValidElement(children)) {
  const child = children;
  const label = child.props.children ?? "Previous";
  return (
    <Button asChild variant="ghost" size="sm">
      {React.cloneElement(
        child,
        { ref, "aria-label": "...", ...props },
        <Icon />,
        label,
      )}
    </Button>
  );
}
```

When `asChild=false`, the component uses its standard element (`"a"` or `"span"`) with internal content rendered normally.

### Reasoning

**Slot cannot handle multiple children**: this is by design. Slot merges props onto a single element. Passing multiple children is not an edge case to work around; it is a misuse of the abstraction.

**cloneElement preserves the consumer's element type**: the consumer passes `<button>`, and a `<button>` is what renders. Props from the wrapper (aria-label, ref) are merged. The consumer's own props (disabled, onClick) are preserved. This matches the semantic contract of `asChild`.

**Internal content injection is intentional**: PaginationPrevious/PaginationNext provide structural chrome (navigation icons, default labels) that should appear regardless of the rendered element type. The consumer can override the label via their element's children, but the Icon is always present.

### Consequences

- Two patterns exist for `asChild`: Slot (for components without internal content) and cloneElement (for components with internal content). The choice is determined by whether the component renders its own children inside `Comp`.
- `composeRefs` must be imported from `@nuka/utils/slot` when using cloneElement, to merge the forwarded ref with any ref on the consumer's child.
- Future components with internal content + `asChild` should follow PaginationPrevious as the reference implementation, not Button or PaginationLink.

### First instances

`PaginationPrevious` and `PaginationNext` in `src/components/Pagination/Pagination.tsx`.

---

## ADR-036: Eyebrow typography component

**Date:** 2026-04-12
**Status:** Accepted

### Context

Page sections frequently use a small uppercase label above a heading to establish hierarchy (e.g. "Case study" above "Scaling the design system"). This pattern was being built ad hoc with `Text` plus manual `uppercase tracking-wide text-xs font-semibold` classes.

### Decision

Add `Eyebrow` as a dedicated typography component with a `color` variant (base, muted, accent) and fixed typographic treatment: uppercase, wide tracking, extra-small size, semibold weight. Polymorphic `as` prop accepting `p` (default) or `span`. No `variant`/`intent` system because the component has no semantic color meaning beyond the three color options.

### Consequences

- Eliminates repeated utility class combinations for the eyebrow pattern.
- `color` is the only variant axis. No `size` prop because the typographic treatment is fixed by design.
- No `"use client"` directive. Pure render component, server-safe.

---

## ADR-037: VisuallyHidden accessibility utility component

**Date:** 2026-04-12
**Status:** Accepted

### Context

Screen-reader-only content is needed by multiple components (FileInput uses it for the hidden file input, icon-only buttons need accessible labels) and by consumers building accessible patterns. The `sr-only` Tailwind class handles the styling, but wrapping it in a component provides a discoverable API and consistent `as` polymorphism.

### Decision

Add `VisuallyHidden` as a thin wrapper around `sr-only`. Polymorphic `as` prop accepting `span` (default), `p`, `div`, and heading elements (`h1`-`h6`). No variant system. Ref forwarded via generic cast to `HTMLElement`.

### Consequences

- Internal and external use: FileInput uses it for the hidden file input, consumers use it for accessible labels.
- The heading element options allow hidden headings for document outline without visual presence.
- No `"use client"` directive. Server-safe.

---

## ADR-038: Section layout component with spacing and background variants

**Date:** 2026-04-13
**Status:** Accepted

### Context

Page layouts need semantic `<section>` elements with consistent vertical spacing and background colors from the token system. Consumers were using raw HTML sections with manual padding and background classes.

### Decision

Add `Section` with three CVA variant axes: `spacing` (none/sm/md/lg/xl), `background` (base/subtle/muted/emphasis), and `divider` (boolean for top border). Polymorphic `as` prop covering all block-level semantic elements (section, div, article, aside, main, header, footer). `asChild` supported via Slot.

### Consequences

- Spacing variant uses responsive padding values (e.g. `py-(--space-6) md:py-(--space-8)` for `md`).
- Background variant maps directly to semantic surface tokens (`--nuka-bg-base`, `--nuka-bg-subtle`, etc.).
- No `variant`/`intent` pattern because Section is structural chrome with no semantic color meaning.
- The `emphasis` background with `text-(--nuka-text-inverse)` enables dark section blocks within light pages.

---

## ADR-039: SplitLayout two-column grid component

**Date:** 2026-04-13
**Status:** Accepted

### Context

Two-column layouts (sidebar + main, form + preview) are a common pattern. Consumers were building them with raw CSS grid or flex classes. The responsive stacking behavior (columns on desktop, single column on mobile) requires breakpoint-aware classes.

### Decision

Add `SplitLayout` as a CSS grid component with `sidebar` (left/right), `sideWidth` (sm/md/lg/xl mapping to fractional grid templates), `stackBelow` (breakpoint at which columns collapse to single column), and responsive `gap` via `Responsive<GapScale>`. Uses a pre-computed 32-entry layout class map (4 widths x 2 sides x 4 breakpoints) to ensure all grid-template-columns classes are statically present for Tailwind scanning. Expects exactly two children with a dev-mode warning.

### Consequences

- The lookup table approach follows ADR-022 for responsive class generation.
- `asChild` supported for rendering as semantic elements.
- No `"use client"` directive. Server-safe layout primitive.
- The two-child constraint is validated only in development to avoid runtime overhead.

---

## ADR-040: ScrollArea with CSS-only custom scrollbar

**Date:** 2026-04-14
**Status:** Accepted

### Context

Custom scrollbar styling improves visual consistency across the library. The two approaches are: (1) a JavaScript-based virtual scrollbar (Radix ScrollArea pattern) that replaces native scrolling, or (2) CSS-only styling of the native scrollbar.

### Decision

CSS-only approach. A `.nuka-scroll-area` class in `animations.css` styles WebKit scrollbars (`::-webkit-scrollbar`, `::-webkit-scrollbar-track`, `::-webkit-scrollbar-thumb`) at 6px width/height. Firefox is handled via `scrollbar-width: thin` and `scrollbar-color` standard properties referencing the same tokens. The component adds `orientation` (vertical/horizontal/both) for overflow control, `maxHeight`/`maxWidth` as inline styles (justified exception: arbitrary consumer-provided dimensions), and `tabIndex` defaulting to 0 for keyboard accessibility.

### Consequences

- No JavaScript scrollbar replacement. Native scrolling behavior is preserved, including momentum scrolling on mobile and accessibility features.
- WebKit and Firefox have different levels of customization. WebKit gets full track/thumb styling; Firefox gets thin width and two-color scheme. This is an acceptable tradeoff.
- `tabIndex={0}` ensures keyboard users can scroll the container with arrow keys.
- No `"use client"` directive. Server-safe.

---

## ADR-041: Scroll tokens for custom scrollbar theming

**Date:** 2026-04-14
**Status:** Accepted

### Context

ScrollArea needs theme-aware scrollbar colors that respond to light/dark mode. Hardcoding colors would prevent consumer theming.

### Decision

Add two semantic tokens: `--nuka-scroll-thumb` and `--nuka-scroll-track`. Light theme: neutral-400 and neutral-100. Dark theme: neutral-dark-border and neutral-dark-subtle. These follow the existing two-layer architecture: semantic tokens reference primitives, components reference semantic tokens.

### Consequences

- Consumers can retheme scrollbar colors by overriding two tokens.
- Both tokens are added to `tokens.css` (multi-theme) and `root.css` (light-only).
- The dark theme values reuse existing dark surface primitives, maintaining visual coherence with borders and subtle surfaces.

---

## ADR-042: NumberInput with controlled/uncontrolled state and FormField integration

**Date:** 2026-04-14
**Status:** Accepted

### Context

Number inputs with increment/decrement controls are a common form pattern. The native `<input type="number">` provides arrow keys and spinner buttons, but the spinner UI varies across browsers and is not styleable.

### Decision

Add `NumberInput` wrapping a native `<input type="number">` with browser spinner hidden (`appearance: textfield`), plus custom increment/decrement buttons with Icon-wrapped SVGs. Uses `useControllableState` for controlled/uncontrolled dual API (following Slider pattern) and `useFormFieldProps` for FormField integration (following Input pattern). Renders as `<div role="group">` with `aria-label` forwarded to the group. Buttons disabled at min/max boundaries. `incrementLabel` and `decrementLabel` props allow consumer-provided accessible button labels.

### Consequences

- `"use client"` directive required (interactive state).
- Reuses `inputVariants` from Input for visual consistency. No separate CVA needed.
- `tabIndex={0}` on control buttons ensures keyboard accessibility.
- The `role="group"` wrapper with `aria-label` provides an accessible grouping for the three controls.
- Custom button labels enable localization.

---

## ADR-043: FileInput with drag-and-drop and file list

**Date:** 2026-04-14
**Status:** Accepted

### Context

File upload patterns need drag-and-drop support, file list display with removal, and visual feedback for drag-over state. These behaviors are not available from native file inputs.

### Decision

Add `FileInput` with a drag-and-drop zone styled via `fileInputZoneVariants` CVA (intent x isDragOver compound variants), a hidden native `<input type="file">` wrapped in `VisuallyHidden`, and a file list rendered as `<ul role="list">` with `DismissButton` for file removal. Uses `useFormFieldProps` for FormField integration. File size formatting is an internal utility (B/KB/MB). `maxFiles` prop caps the file count with a dev-mode warning. Single-file mode (no `multiple` prop) replaces the file list on each selection.

### Consequences

- `"use client"` directive required (drag state, file state).
- Consumes three internal utilities: `VisuallyHidden` (hidden input), `DismissButton` (file removal), `Text` (labels and file info).
- The compound variant matrix (4 intents x 2 drag states = 8 entries) provides visual feedback for all intent/drag combinations.
- `dragLabel` and `browseLabel` props enable localization.
- `React.useId()` generates input IDs when FormField does not provide one.

---

## ADR-044: Nav compound component with CSS-driven submenus

**Date:** 2026-04-14
**Status:** Accepted

### Context

Horizontal navigation with optional dropdown submenus is a standard site-level pattern. The menu system (ADR-030) handles application menus with ARIA menu semantics and arrow-key navigation. Site navigation is different: it uses link semantics, Tab-based focus order, and hover/focus-within for submenu visibility.

### Decision

Add `Nav` as a compound component: `Nav` (root `<nav>`), `NavList` (`<ul>`), `NavItem` (`<li>` with `group` class), `NavLink` (`<a>` with `active` prop for `aria-current="page"`), `NavTrigger` (`<button>` with chevron icon and `aria-haspopup`), `NavSubmenu` (`<ul>` positioned absolutely with `group-hover`/`group-focus-within` visibility).

Submenus are CSS-driven via Tailwind `group-hover:` and `group-focus-within:` utilities. No JavaScript state management. `NavLink` and `NavTrigger` support `asChild` via Slot.

### Consequences

- No `"use client"` directive on any Nav component. Fully server-safe.
- CSS-driven submenus work without JavaScript but do not support the ARIA menu keyboard model (arrow-key navigation between items). This is intentional: site navigation uses Tab-based focus, not menu-based focus.
- `NavTrigger` declares `aria-haspopup` but not `aria-expanded`. Toggling `aria-expanded` requires JavaScript state, which would force a `"use client"` boundary and remove the server-safe guarantee. The tradeoff is accepted: screen readers announce the trigger as having a popup, and `group-focus-within` ensures the submenu is keyboard-reachable via Tab.
- `NavSubmenu` `align` prop (start/end) controls horizontal positioning for edge-of-viewport menus.
- `NavLink` `active` prop sets `aria-current="page"` and accent text color, following the Breadcrumb pattern (ADR-031).

### Alternatives considered

**Using useMenuNavigation from the menu system**: rejected. Site navigation links follow standard Tab focus order. Imposing arrow-key menu navigation on site nav links would violate user expectations and conflict with the ARIA link role.

---

## ADR-045: "use client" directive strategy for RSC compatibility

**Date:** 2026-04-14
**Status:** Accepted

### Context

React Server Components (Next.js App Router) require explicit `"use client"` boundaries for components that use hooks, event handlers managed via state, or browser APIs. Components that are pure render functions can run on the server without the directive.

### Decision

Include `"use client"` only on components that contain React hooks (`useState`, `useEffect`, `useRef` with mutation, `useContext`, custom hooks). Components that use only `cn()`, CVA, `Slot`, and `forwardRef` do not include the directive. The directive is placed at the top of the component source file (not in `index.ts`), and the build preserves it in the compiled output.

### Consequences

- Server-safe components (Alert, AppShell, AspectRatio, Badge, Banner, Breadcrumb, Button, Card, Code, Container, Divider, EmptyState, Eyebrow, Grid, Heading, Icon, Kbd, Nav, Pagination, ScrollArea, Section, Skeleton, Spinner, SplitLayout, Stack, Tag, Text, Textarea, Timeline, VisuallyHidden) work in RSC without wrapping.
- Client-required components include the directive and can be imported from server components in Next.js without additional configuration (the bundler creates the client boundary automatically).
- The decision is per-file, not per-component-directory. A compound component may have server-safe sub-components and client-required sub-components in the same directory.

### Amendment (2026-04-17, nuka-ui 1.1.3)

The 1.1.2 release demonstrated that the server-safe subset was architecturally fragile: any consumer attaching a ref to a "server-safe" component from a Server Component triggered the RSC serialization error. `BreadcrumbLink` rendered with `asChild` and `next/link` is one concrete case that hit this in practice.

nuka-ui 1.1.3 adopts a new policy: every component that accepts a `ref` prop, uses `Slot`, uses `asChild`, or calls a hook carries `"use client";`. In practice this means every public component.

The SEO concern that originally motivated the server-safe subset was based on a misunderstanding. Client Components are still server-rendered during the initial response; the directive controls hydration code shipping, not rendering location.

See ADR-048 for the new policy in full.

---

## ADR-046: Semantic font family tokens with component-level override

**Date:** 2026-04-14
**Status:** Accepted

### Context

Typography components need a way to reference font families via the token system while allowing per-instance overrides. A single `--nuka-font-family` token would force all typography to use the same family. Different roles (headings, body, UI, code) typically use different families.

### Decision

Four semantic font family tokens: `--nuka-font-heading` (serif default), `--nuka-font-body` (sans default), `--nuka-font-ui` (sans default), `--nuka-font-code` (mono default). Each typography component references the token appropriate to its role. `Heading` accepts a `family` prop that overrides the token with a specific primitive. `Text` references `--nuka-font-body`. `Eyebrow` references `--nuka-font-body`. `Code` and `Kbd` reference `--nuka-font-code`.

When the `family` prop is not provided, the CSS variable drives the font. When provided, the component applies the corresponding primitive directly, bypassing the variable. This means a consumer can set all headings to sans globally via `--nuka-font-heading: var(--font-family-sans)`, and still override one heading to serif via `<Heading family="serif">`.

### Consequences

- Global typography changes require overriding one token per role, not touching component files.
- The `family` prop on `Heading` is the only component-level font override. Other components use their token without an override prop, keeping the API minimal.
- `--nuka-font-ui` is separate from `--nuka-font-body` even though both default to sans. This allows products that use different fonts for UI chrome vs. long-form text.

---

## ADR-047: inputVariants reuse in NumberInput and FileInput

**Date:** 2026-04-14
**Status:** Accepted

### Context

NumberInput wraps a native `<input type="number">` and FileInput contains a hidden `<input type="file">`. Both need intent-based border styling consistent with Input.

### Decision

NumberInput imports and applies `inputVariants` from `Input.variants.ts` directly on its native input, rather than defining its own CVA instance. This ensures visual parity with Input for intent and size variants. FileInput defines its own `fileInputZoneVariants` because its drop zone has a fundamentally different visual treatment (dashed border, larger padding, drag-over state) that does not overlap with input field styling. The hidden file input inside FileInput receives no visual styling.

### Consequences

- NumberInput has no `NumberInput.variants.ts` file. This is a justified exception to the "every component with CVA gets a variants file" rule because the CVA instance belongs to Input, not NumberInput.
- FileInput has `FileInput.variants.ts` with its own compound variant matrix (intent x isDragOver).
- Future form controls that wrap a styled `<input>` should follow NumberInput's pattern of reusing `inputVariants` rather than duplicating the definitions.
- Visual consistency between Input, NumberInput, and Textarea is guaranteed by the shared CVA source.

---

## ADR-048: "use client" directive is required on every component that accepts a ref, uses Slot, or uses hooks

**Date:** 2026-04-17
**Status:** Accepted

### Context

nuka-ui 1.1.2 shipped with a partial "use client" policy: the directive was applied only to components that called React hooks. Components that used only `cn()`, CVA, `Slot`, and forwarded refs were considered "server-safe" and shipped without the directive.

This policy broke in production. A consumer rendering `<BreadcrumbLink asChild>` wrapped around a `next/link` component from a Server Component page triggered "Refs cannot be used in Server Components" at runtime. The failure class is broader than this single case: any consumer attaching a ref from a Server Component to a "server-safe" component hits the same error. React Hook Form's `register()`, `framer-motion`'s ref props, and any `useRef` forwarded via composition all exhibit this pattern, so the "server-safe" subset was only safe under an unrealistic no-ref assumption.

### Decision

1. Every component that accepts a `ref` prop carries `"use client";` on line 1 of its source file.
2. Every component that uses `Slot` from `@nuka/utils/slot` or accepts an `asChild` prop carries the directive.
3. Every component that calls a React hook or a `useXxx` custom hook carries the directive.

These conditions are enforced by the `nuka/require-use-client` ESLint rule introduced in Batch C of the 1.1.3 release. The rule runs in CI and blocks merges that regress the policy.

### Consequences

- Every public component ships as a Client Component. There is no "server-safe" subset.
- Consumers can import any component from a Server Component boundary in Next.js App Router (or equivalent RSC-supporting frameworks) without additional configuration. The bundler creates the client boundary automatically.
- Bundle size cost: every component's compiled code ships to the client. This is acceptable because nuka-ui components are interactive primitives. The previously "server-safe" subset (Stack, Grid, Container, Heading, etc.) was a distinction consumers could not safely rely on once refs or composition were introduced.
- SEO is unaffected. Client Components render to HTML on the server during the initial response. The directive controls hydration code shipping, not rendering location.
- Supersedes the partial-coverage strategy described in ADR-045. See the ADR-045 amendment for the reasoning.

### Alternatives considered

**Keep the server-safe subset, relax the ESLint rule for ref-only components**: rejected. Ref serialization from a Server Component is the exact failure class 1.1.2 hit. Allowing ref-only components to skip the directive reintroduces that class in a narrower but still production-breaking form. The rule must be uniform to be useful.

**Move to a barrel-level directive (single `"use client";` on `src/index.ts`)**: rejected. A barrel-level directive would force every consumer to go through the full library bundle even when they import a single component, because the directive makes the whole file a client module. Per-file directives preserve tree-shaking and allow Next.js to include only the components a page actually uses.

## ADR-049: Generated Tailwind safelist for runtime-constructed responsive classes

**Date:** 2026-04-19
**Status:** Accepted

### Context

`src/utils/responsive.ts` exposes layout-primitive lookups (`gapClasses`, `directionClasses`, `textSizeClasses`, etc.) that components consume via the `Responsive<T>` prop pattern (ADR-021, ADR-022). Each lookup is produced by a `buildLookup<T>()` call that takes a base map like `{ none: "gap-0", xs: "gap-1", ... }` and builds a breakpoint-keyed `{ base, sm, md, lg, xl, "2xl" }` record at module init time, prefixing each base token with the matching Tailwind breakpoint (`"sm:"`, `"md:"`, etc.).

Tailwind v4's scanner reads source files and includes a class in the compiled CSS only if it appears as a complete string literal in the source. `buildLookup` constructs its outputs at runtime by string concatenation, so `"sm:gap-4"` is never visible to the scanner as a literal even though it is returned by the lookup.

Empirical measurement of the 1.1.3 `dist/styles.css` against every class the lookups can emit:

- `aspectRatioClasses`: 100 percent coverage (36 of 36), because a hand-authored `_aspectRatioSafelist` array was embedded at the bottom of `responsive.ts` for exactly this purpose.
- Every other lookup: 17 to 31 percent coverage. The responsive variants that happened to appear in the compiled bundle did so only because some Storybook story or component source coincidentally contained the literal string; there was no mechanism ensuring every variant was covered.
- Aggregate: 228 of 324 originally expected classes were missing.

Consumer impact: `<Stack gap={{ base: "sm", md: "lg" }}>` returns the strings `gap-2` and `md:gap-6`. If the consumer's own sources do not happen to contain the literal `md:gap-6`, no CSS rule exists and the component renders with no gap at `md` and up. Every layout primitive accepting a `Responsive<T>` prop was affected.

### Decision

Split the base maps into a shared module and generate a safelist file from them on every build.

- `src/utils/responsive-maps.ts` is the single source of truth. It exports every base map, the `BREAKPOINT_PREFIXES` object, all type aliases (`GapScale`, `Direction`, ...), and an `ALL_BASE_MAPS` array that enumerates every base map by name.
- `src/utils/responsive.ts` imports the base maps and passes each to `buildLookup<T>()`. Runtime behavior is unchanged. Public exports remain identical in name, type, and value.
- `tools/generate-safelist.mjs` loads `responsive-maps.ts` via `esbuild.transformSync` plus a data-URL dynamic import (zero new dependencies; esbuild is already a transitive Vite dep), computes the full cross-product of breakpoint prefixes and whitespace-split base tokens, and writes `src/utils/_tailwind-safelist.ts`. The generator sorts, deduplicates, and formats the output with prettier so byte-for-byte determinism holds across runs.
- `_tailwind-safelist.ts` exports a single `_safelist` array of string literals. Tailwind's scanner sees the literals. Nothing in `src/` imports it at runtime; the generator verifies this with an import-shaped regex across `src/` and fails if any runtime file pulls it in.
- An npm `prebuild` lifecycle script wires the generator into every build path (`npm run build`, `npm run prepare`, `npm run test:dist`, `npm run release`). A `check:safelist` script runs the generator in dry-run mode and fails if the on-disk file is out of date. It is chained first in `test:all` because it is the cheapest signal with the clearest message when a developer forgot to regenerate.
- A verification test at `tests/dist/responsive-safelist.test.ts` reads the actual `dist/styles.css`, recomputes the expected set from `ALL_BASE_MAPS`, and asserts every expected class appears as a correctly escaped rule in the bundle. It runs as part of `test:dist`, which runs against the built output.

### Consequences

- Every class that `buildLookup` can return at runtime is guaranteed to have a matching rule in `dist/styles.css`. The `<Stack gap={{ md: "lg" }}>` class of bug is extinguished for every `buildLookup` consumer.
- The hand-authored `_aspectRatioSafelist` block is removed. The generated safelist is the single mechanism.
- Adding a new lookup requires: add the base map and types to `responsive-maps.ts`, add an entry to `ALL_BASE_MAPS`, wire the lookup in `responsive.ts`, run `npm run build:safelist`, commit both files. The CI `check:safelist` step catches forgotten regenerations.
- The safelist file's exact byte contents are tied to the installed prettier version. A prettier upgrade that changes formatting defaults will surface as a `check:safelist` failure in otherwise unrelated PRs. The fix is to regenerate and commit; no behavior changes.
- Generator placement is npm-lifecycle rather than Vite-plugin. The scanner-visibility guarantee is a language-level concern (every emitted class appears as a source literal), not a bundler-level one. Running the generator as an npm script means Storybook, Vitest, and any future consumer build pipeline invoking `npm run build` inherits the guarantee for free.

### Invariant enforced by the verification test

For every base map entry in `ALL_BASE_MAPS`, for every prefix in `BREAKPOINT_PREFIXES`, for every whitespace-split token in every value of that map, the prefixed token appears as a CSS rule in `dist/styles.css` using Tailwind v4's escape form (`.\32 xl\:aspect-\[4\/3\]` and similar). The test also asserts that the generated `_safelist` contains exactly the expected set, so generator drift is caught independently of CSS coverage.

### Alternatives considered

**Extend the hand-authored safelist to all lookups**: rejected. The array would be roughly 500 lines and every base-map edit would require a manual, error-prone sync. The 228 missing classes in 1.1.3 are exactly the failure mode the hand-authored approach produces at scale.

**Tailwind config-level safelist**: not available. Tailwind v4 does not expose a configuration-level safelist analogous to v3's `safelist` option. Literal-in-source is the only supported mechanism.

**Parse `responsive.ts` for object literals in the generator**: rejected. The task brief allowed this as a fallback. Parsing TypeScript AST for literals couples generator correctness to code-shape details that the runtime refactor is free to change. Extracting the base maps into a dedicated module removes that coupling entirely for a single-file cost.

**Vite plugin instead of npm script**: rejected. The scanner-visibility guarantee is not bundler-specific. An npm-lifecycle generator runs under every tool that invokes `npm run build`; a Vite plugin would only run under Vite.

## ADR-050: Surface-aware focus ring via data-surface attribute cascade

**Date:** 2026-04-19
**Status:** Accepted

### Context

`--nuka-border-focus` is a single value per theme: accent-500 in light mode, accent-400 in dark mode. Components that render a focus ring reference this token directly.

When a dark block appears inside a light page (a `<Section background="emphasis">`, a hero panel, a CTA strip), the light-theme focus ring fails WCAG 2.2 AA against the dark background. The computed ratio is ~2.3:1, below the 3:1 minimum for UI components. Symmetric failure exists in dark theme on inverse (white) blocks at ~2.6:1.

The zanakadric port documented this by override: 8+ sites used `[--nuka-border-focus:...]` inline on buttons inside dark sections. That pattern is a workaround, not a solution.

Adding a per-component `focusIntent` prop would propagate the fix to every interactive component (Button, Input, Select, Checkbox, Radio, Switch, Tabs trigger, Menu item, NavigationMenu trigger, every dismiss button). Each component would grow an identical prop, identical documentation, and identical tests for an identical concern. That is the wrong shape for a uniform cross-cutting token.

### Decision

Redefine `--nuka-border-focus` inside any subtree that carries the attribute `data-surface="inverse"`. The redefinition happens in `src/styles/tokens.css` via attribute selectors scoped to each theme:

```css
[data-theme="light"] [data-surface="inverse"],
:root [data-surface="inverse"] {
  --nuka-border-focus: var(--color-accent-400);
}

[data-theme="dark"] [data-surface="inverse"] {
  --nuka-border-focus: var(--color-accent-500);
}
```

`<Section background="emphasis">` emits `data-surface="inverse"` automatically in its render. The common case requires zero consumer action. Consumers who build custom dark surfaces set the attribute themselves.

**Contrast ratios:**

- Light inverse: accent-400 on neutral-900, ~6.9:1 (passes AA 3:1 for UI components)
- Dark inverse: accent-500 on neutral-0, ~7.8:1 (passes AA 3:1 for UI components)

### Consequences

- `data-surface` becomes part of the library's public theming contract. **Removing or renaming it is a major version bump.**
- `data-theme` and `data-surface` compose via CSS cascade. Both can appear on different ancestor elements in the tree. When both apply to the same subtree, the surface rule wins because its selector specificity `[data-theme="x"] [data-surface="inverse"]` is (0, 2, 0) vs the theme rule's (0, 1, 0).
- Consumers learn one new attribute convention. `Section background="emphasis"` auto-wires, so most consumers do not need to see the attribute directly.
- Zero interactive-component source code changes. Focus-ring resolution was already token-based; this task changes what the token resolves to in a given subtree.
- If new tokens later need surface-scoped redefinition (for example `--nuka-text-base` on an emphasis surface), the mechanism is in place and only the override block is extended.
- The mechanism does not support setting `data-theme` and `data-surface` on the same element. Consumers who need inverse-on-root nest: `<html data-theme="dark"><div data-surface="inverse">...</div></html>`. Documented in `docs/THEMING.md`.

### Alternatives considered

**Per-component `focusIntent` prop**: rejected. Scales poorly (one prop per interactive component, identical semantics in each), invites inconsistency (some components forget to add it), and puts burden on consumers to set it per instance.

**Per-instance className override (`[--nuka-border-focus:...]`)**: rejected. Forces every consumer to rediscover the fix independently. Does not compose with nested dark surfaces. Was the exact pattern that produced the 8-site workaround in zanakadric.

**Automatic detection via `color-mix()` or JS luminance inspection**: rejected. No reliable CSS-only path exists to inspect computed background luminance inside a selector. JS-based detection via `getComputedStyle` is fragile (does not re-run on prop changes, adds a hydration step), framework-coupled, and imposes a runtime cost on every focusable element.

**`focusRingVariant` CVA variant per component**: rejected for the same scaling reasons as the prop option, plus adds compound-variant combinations that do not correspond to real design decisions.

## ADR-051: 24x24 CSS px touch target invariant enforced via CSS, test, and lint

**Date:** 2026-04-19
**Status:** Accepted

### Context

WCAG 2.2 Level AA Success Criterion 2.5.8 (Target Size Minimum) requires each pointer target to be at least 24x24 CSS pixels. A cluster-5 audit of nuka-ui's interactive primitives surfaced one concrete failure: Switch at the `md` size rendered a 20x36 track, below the 24 px height minimum.

The failure was easy to miss during development because:

- jsdom does not compute CSS layout, so component unit tests cannot measure the rendered box.
- The Storybook a11y addon does not enforce 2.5.8 by default.
- A conformance gap on one size variant of one component is invisible in the variant matrix.

The Switch fix revealed a secondary concern: the `sm`/`md`/`lg` size ramp, built around different heights (24/20/24), collapsed visually when md was raised to 24. The rebalance grows md and lg in all three axes (track height, track width, thumb size) to restore a clear visual progression.

### Decision

Defense in depth: three independent enforcement mechanisms.

1. **CSS contract.** Each component's size variants declare classes that produce ≥24 px on the interactive element. Documented in `docs/ACCESSIBILITY.md`.
2. **Regression test.** `tests/a11y/touch-targets.test.tsx` renders every interactive primitive at every size and asserts height ≥24 via a className→pixel lookup. jsdom cannot lay out CSS; className parsing is the substitute.
3. **Lint rule.** `nuka/no-sub-touch-target-sizes` flags Tailwind classes `h-1..h-5`, `min-h-1..min-h-5`, `size-1..size-5`, and arbitrary-value equivalents inside CVA `variants.*.*` positions within `*.variants.ts` files. Indicator-inside-wrapper exemptions use `eslint-disable-next-line`.

**Switch scale rebalance (concrete):**

| Size | Track              | Thumb            | Fill ratio |
| ---- | ------------------ | ---------------- | ---------- |
| sm   | 24×40 (`h-6 w-10`) | 16×16 (`size-4`) | 67%        |
| md   | 28×48 (`h-7 w-12`) | 20×20 (`size-5`) | 71%        |
| lg   | 32×56 (`h-8 w-14`) | 24×24 (`size-6`) | 75%        |

All three sizes pass 2.5.8 AA; each size is visually distinct.

### Consequences

- The Switch `md` fix and rebalance bring the library to full 2.5.8 AA compliance.
- `md` and `lg` Switches are taller than in 1.1.3. Consumers with tight vertical layouts around these components may need to adjust. `sm` stays unchanged and remains the compact option.
- Adding a new interactive primitive now requires passing the regression test and not tripping the lint rule. The cost is a handful of extra lines in a pull request.
- The lint rule is a heuristic; it operates on string literals and will miss dynamic class composition. The regression test is the ground truth.
- The test relies on a static Tailwind-class → pixel map. If the project switches Tailwind config values for the spacing or typography scale, the map must be updated. Current scale is default Tailwind (0.25rem = 4 px per step at 16 px root).

### Alternatives considered

**Storybook test-runner with real layout measurement**: rejected. Requires new infrastructure (test-runner config, headless browser in CI), high value but out of scope for a single-violation fix.

**Per-component inline size assertions**: rejected. Scales poorly as the number of components grows. A shared regression test over a table of primitives is one place to change when the touch-target rule itself changes.

**Trust the a11y-addon alone**: rejected. The addon does not enforce 2.5.8 by default, and even with enforcement enabled it runs only in Storybook runs, not in unit-test CI.

**Naive Switch fix (h-5 → h-6 only)**: rejected in favor of the rebalance. Keeping all three tracks at the same 24 px height collapsed the visual ramp to width-only differences of 4-8 px, producing three toggles that looked nearly identical. The rebalance grows each size in three axes so the progression is obvious.

## ADR-052: Typography contract and nine-value weight scale

**Date:** 2026-04-19
**Status:** Accepted

### Context

Before this ADR, four typography inconsistencies had accumulated across the component library:

1. `Text.as` accepted 8 elements. Semantic HTML has roughly three times as many phrasing and flow elements that legitimately want typographic control.
2. Font-weight scales were partial: Text and Heading accepted 4 weight values (regular / medium / semibold / bold). Eyebrow, Label, CardTitle, CardDescription, and EmptyState internals exposed nothing and hardcoded their own defaults. Button, Badge, Tag, Chip, Avatar, and 13 other chrome components hardcoded `font-medium` as a Tailwind literal, bypassing the `--font-weight-*` token contract.
3. Color vocabularies differed across components. Text accepted 9 color values. Eyebrow accepted 3. Same semantic axis, different reachable set.
4. There was no written document stating which component exposes which axis. The rule "new typography components should match existing ones" was implicit, relied on review, and had already drifted.

The four-value weight scale was the most visible gap. Per MDN, CSS `font-weight` has nine common named steps (100, 200, 300, 400, 500, 600, 700, 800, 900) corresponding to the OpenType `usWeightClass` specification. Port feedback cited 48-72 px italic display numbers and 128 px hero treatments that require weights 800 or 900. Weight 950 is sometimes cited (Google Fonts) but is not in the CSS specification; MDN documents the nine-step ramp as canonical.

### Decision

1. **Contract document.** Add `docs/TYPOGRAPHY.md`. Specifies the canonical scale per axis (family, weight, size, color, align, truncate), a per-component exposure matrix, invariants new components must satisfy, and a rendering caveat about synthesized-weight fallback.

2. **Nine-value weight token scale.** Extend `--font-weight-*` tokens in `tokens.css` and `root.css` from 4 values to 9: `thin` (100), `extralight` (200), `light` (300), `regular` (400, existing), `medium` (500, existing), `semibold` (600, existing), `bold` (700, existing), `extrabold` (800), `black` (900). The four existing tokens keep their names and values, so this is purely additive.

3. **Full scale on every typography component.** Text, Heading, Eyebrow, and Label each expose a `weight` prop accepting all 9 values. No subsetting; subsets encode judgments nobody remembers. CardTitle, CardDescription, and EmptyState forward optional weight props to their internal Text or Heading instance so consumers can override typography through compound APIs.

4. **Eyebrow color alignment.** Widen Eyebrow's `color` from 3 values to the full 9-value set that Text accepts. Same semantic axis, same reachable set.

5. **Tokenize all chrome font-weight classes.** Replace every Tailwind font-weight literal (`font-medium`, `font-semibold`, etc.) in production component files with the arbitrary-value tokenized form `font-[number:var(--font-weight-<name>)]`. 15 occurrences across 14 files. A machine-executable grep guard in cmd-test enforces that no Tailwind font-weight keyword appears in any authored class string under `src/components/**/*.{ts,tsx}` (excluding stories and tests).

6. **Chrome components do not expose weight props.** Button, Badge, Tag, Chip, Avatar, Nav, NavigationMenu triggers / links, MenubarTrigger, SkipLink, Stepper indicators, Table header / footer, BreadcrumbPage, CommandMenuGroup, and menu label variants hardcode their weight by design. Weight variation within a button group or badge row would look like a bug.

### Consequences

- Contributors have a single reference document for typography API shape. Future coherence reviews compare component implementations against `docs/TYPOGRAPHY.md` instead of against memory or against whichever sibling component a reviewer happens to remember.
- Consumers can express the full CSS weight range through tokens, including sub-regular weights for editorial light body text and display-heavy weights for hero treatments. The tokens are customizable so a consumer can retune any weight value.
- Consumers are responsible for loading font files that support the weights they use. The library exposes every CSS-spec weight but does not ship font files. Synthesized fallback glyphs (what the browser produces when the loaded font lacks a requested weight) are lower quality than hinted faces; at weights 100 and 200 combined with low contrast, MDN warns they may be unreadable. The contract document surfaces this risk.
- API symmetry: every weight-bearing prop across Text, Heading, Eyebrow, Label accepts the same 9 values. Cross-component memorization is one mental model.
- Chrome components cannot be retuned at the prop level. Consumers who need a display-light button label need a different primitive (Text-as-button, a Link composite, etc.). The library considers this the correct outcome; mixed weights in a button row signal a bug.
- The grep guard catches regressions at cmd-test time, not at review time. New components that land with a `font-medium` literal fail CI.

### Alternatives considered

**Keep the four-value weight scale.** Rejected. Omits weights port feedback actively needs. Pushes consumers to `className` overrides that silently leak past the token system.

**Subset the scale per component.** Rejected. A component accepting `regular / medium / semibold / bold / extrabold / black` looks intentional but encodes a judgment ("we don't think `thin` and `extralight` are ever useful for headings") that nobody remembers later. The partial-scale pattern is exactly what this ADR exists to eliminate.

**Include weight 950.** Rejected. Not in the CSS specification per MDN. Google Fonts supports it, other foundries do not. Including it in the canonical scale would create a token consumers could legitimately use in a value that degrades inconsistently across font sources.

**No contract document; rely on code review.** Rejected. Current state is the counter-example. Eyebrow's 3-value color enum survived multiple reviews.

**Runtime enforcement (throw if a component passes a weight outside the canonical scale).** Rejected. The contract is a social artifact for maintainers, not a runtime check for consumers. TypeScript's structural type system already produces compile-time errors for out-of-union values.

**Hardcoded-weight components expose the prop with a "recommended" subset.** Rejected. Violates invariant #1 of the contract (no subsetting). Also contradicts the goal: if variation looks like a bug in a button row, exposing it with a smaller menu does not change that.

**Do Piece 5 (literal replacement) only in the five originally-named files.** Rejected during preflight. The goal of the cluster is eliminating token-bypass leaks; leaving 13 other sites with the same leak defeats the purpose. Bundling all sites into one refactor commit keeps the diff reviewable and the grep guard tractable.

## ADR-053: Callout primitive for pulled quotations and editorial emphasis

**Date:** 2026-04-19
**Status:** Accepted

### Context

Three port cases converge on a single primitive need:

1. Pulled quotations from testimonials or case studies. A block of emphasized text attributed to a source. Semantically a `<blockquote>` with a `<cite>` child. Visually raised or bordered.
2. Inline editorial asides. Short "note", "warning", or "tip" blocks that interrupt main-body prose. Visual treatment varies by intent; no urgency (not a live region).
3. Marketing emphasis blocks. A sentence or paragraph pulled from surrounding copy to draw the eye, often with an accent border and larger type.

Alert nearly serves cases 2 and 3 but fails case 1 (no citation, no blockquote semantics) and carries `role="alert"`, which announces the content in the live region. Editorial content should not interrupt screen reader flow. No existing component provides a blockquote primitive. The Cluster 1 TextElement union (ADR-052) added `blockquote` and `cite` specifically to enable this component.

### Decision

1. **New `Callout` component.** Default root `<blockquote>` (HTMLQuoteElement). 4-variant display-primitive shape (`primary`, `secondary`, `outline`, `ghost`) matching Alert, Badge, Tag, Chip. 4-intent (`default`, `danger`, `success`, `warning`). 3-size (`sm`, `md`, `lg`). Reuses `intentCompoundVariants({ secondaryDefault: [accent tokens] })` with the same secondary-default cell as Alert.

2. **Optional `citation` prop.** Renders through `<Text as="cite">` with hardcoded `color="muted"` and `size="sm"`. Produces a `<cite>` child below the main body. Named `citation` (not `cite`) to avoid collision with the native HTML `cite` attribute on `<blockquote>`, which takes a source URL and stays reachable through prop spread.

3. **`asChild` escape hatch.** Uses `Slot` from `@nuka/utils/slot` for a clean root swap. When `asChild` is true, the consumer's tree renders verbatim with Callout classes merged. The `citation` prop is ignored in this path; consumers compose their own figure+figcaption structure. A dev-mode `console.warn` fires when both `asChild` and `citation` are passed.

4. **Body and citation both inherit color from the parent.** Body children render directly in the `<blockquote>` (matches Alert: consumer content is not structural chrome). The citation renders as a bare `<cite className="text-sm">` so it inherits the CVA intent color. Wrapping either body or citation in `<Text>` would emit a color class from Text's `defaultVariants.color = "base"` that overrides the intent color on the parent; `color="muted"` has the same problem since muted gray has insufficient contrast on primary+danger / primary+success / primary+warning colored backgrounds. Body font-size comes from CVA size variants (`text-sm / text-base / text-lg`); citation is hardcoded at `text-sm` with the browser default `<cite>` italic for visual hierarchy.

5. **No icon slot.** Editorial callouts rarely benefit from a severity icon. Consumers who need iconography compose with `asChild` + `<figure>`.

6. **No `role="alert"`.** Screen readers announce Callout as a standard blockquote region. Editorial content does not interrupt live-region speech.

### Consequences

- Consumers have a dedicated primitive for pulled / emphasized content distinct from Alert. Editorial content no longer reaches for `role="alert"`.
- The citation pattern is structured (dedicated prop) for the simple case and composable (asChild with figure + figcaption) for the full HTML-spec-recommended case.
- Validates the Cluster 1 typography work. Callout is the first component to render internal content through `<Text as="cite">`; the TextElement union addition in ADR-052 was made for exactly this use case.
- Callout does not expose typographic props. Consumers who need custom weight, family, or color inside the body compose with their own Text children instead of a bare string.
- Consumers who need the native HTML `cite` attribute (source URL) pass it via prop spread. The name collision between our `citation` display-text prop and the native `cite` URL attribute is resolved in favor of preserving both axes.

### Alternatives considered

**Extend Alert with a `citation` prop and a `role` prop override.** Rejected. Conflates urgent feedback (live region) with editorial emphasis. Role is not a prop and should not be consumer-swappable on a feedback component.

**Render Callout as `<aside>`.** Rejected. `<aside>` is for tangentially related content (sidebars, page-level asides). A pulled quotation is the `<blockquote>` semantic.

**Name the prop `cite` and `Omit<..., "cite">` from the base HTML attributes.** Rejected. Drops a native HTML attribute without replacement. `citation` preserves both axes and reads clearly.

**Include an icon slot matching Alert.** Rejected. Editorial content rarely benefits from a severity icon; it reads as visual noise. Consumers who want iconography compose with `asChild` + `<figure>`.

**Expose `weight`, `color`, and `family` props directly on Callout.** Rejected. Duplicates the Text API. Contract compliance means Callout defers to internal Text defaults. Consumers who need per-instance typographic control compose with their own Text inside Callout's children or use `asChild`.

**Wrap body children in `<Text as="p">` to satisfy the compound-component Text-usage rule.** Rejected. The typography contract rule applies to structural text slots the component owns (titles, descriptions, labels), not to arbitrary consumer-provided children. Alert does not wrap its children either. More importantly, Text's `defaultVariants.color = "base"` emits `text-(--nuka-text-base)` unconditionally, which would override Callout's CVA intent color on the parent. The body correctly inherits from the blockquote.

**Render citation through `<Text as="cite" color="muted">`.** Rejected. `muted` is a neutral gray token chosen for recede-on-neutral-surfaces; it fails WCAG 4.5:1 contrast on primary+danger, primary+success, and primary+warning colored backgrounds. Any fixed Text color choice has the same problem on at least some of the 16 variant x intent cells. Citation is rendered as a bare `<cite className="text-sm">` so it inherits the intent color from the parent blockquote. Hierarchy comes from size (smaller) and the browser default italic styling of `<cite>`. Font-family, weight, and color all propagate through inheritance, satisfying the token-tracking goal of the compound-component Text-usage rule without introducing a cross-variant contrast regression.

---

## ADR-054: `data-slot` attribute contract for compound components

**Date:** 2026-04-20
**Status:** Accepted

### Context

Consumers that want to target internal parts of compound components currently have three brittle paths:

1. `className` on an exported sub-component. Works when the part is exported. Fails for parts that are not independently exported: Dialog's overlay, Select's listbox when closed, Accordion's connector line, Timeline's marker, every inline element inside a composite.
2. Descendant selectors over DOM structure. `[&>div:nth-child(2)]` works until the internal DOM changes.
3. CVA class names. Brittle: CVA output is not part of the library's public API and changes per release.

The zanakadric downstream port accumulated eight sites using one of these approaches across Dialog, Select, Sheet, and Tabs. Each site is a maintenance timebomb. A refactor of any internal DOM structure breaks consumers silently.

The ecosystem convention (Radix `data-radix-*`, shadcn/ui `data-slot` since late-2024) is a stable data-attribute contract.

### Decision

Every compound component emits a `data-slot="<name>"` attribute on every nameable internal DOM element. Slot names are kebab-case, describe role not implementation, and become part of the library's public API. Rename is a major version bump. Addition is a minor.

Shared primitives emit `data-slot` from the base:

- `src/utils/modal-primitive.tsx` emits `trigger`, `title`, `description`, `close`. Dialog and Sheet inherit. DialogContent and SheetContent add `overlay` and `content`.
- `src/components/Menu/*Base.tsx` emit `item`, `checkbox-item`, `radio-item`, `group`, `label`, `separator`, `item-indicator`. DropdownMenu, ContextMenu, and Menubar inherit.

Single-part components do not emit `data-slot`. The root element is the whole component; there is no ambiguity. Excluded: Button, Badge, Tag, Chip, Text, Heading, Label, Eyebrow, VisuallyHidden, Spinner, Skeleton, Progress, Icon, Kbd, Divider, Code, Section, Input, Textarea, Avatar, AspectRatio, Container, Grid, Stack, Banner, Alert, SkipLink.

Pure context providers (Dialog, Sheet, Tooltip, Popover, DropdownMenu, ContextMenu, MenubarMenu, Combobox, CommandMenu when closed, DatePicker) do not emit a `root` slot because they render no DOM.

CSS-only parts (ScrollArea scrollbar and thumb per ADR-040) do not emit slots. ScrollArea emits `root` only.

Consumer-supplied slots are not attributed. SplitLayout emits `root` only; main and side are consumer-supplied children.

`asChild`-composed parts forward `data-slot` through `src/utils/slot.tsx`. `mergeProps` spreads slot-provided props first; the consumer's child only overrides if it also sets `data-slot`, which is opt-in. Forwarding is locked by `src/utils/slot.test.tsx`.

Accordion retains its existing `data-accordion-trigger=""` attribute (ADR-027 keyboard navigation) and adds `data-slot="trigger"` alongside. Two attributes, two purposes. Replacing `data-accordion-trigger` with a scoped `data-slot="trigger"` query would require every Accordion keyboard handler to ancestor-scope via `closest("[data-slot='root']")` before `querySelectorAll(...)` to avoid matching DialogTrigger, TooltipTrigger, and every other `trigger` in the tree. The dedicated attribute is safer and simpler.

### Slot naming table

The full table (approximately 140 rows) is enforced by `tests/contracts/data-slots.test.tsx` and mirrored in `docs/CUSTOMIZATION.md`. Summary by family:

**Modal (Dialog, Sheet):** `trigger`, `title`, `description`, `close`, `content`, `overlay`. Sheet additionally coexists with `data-side`.

**Floating (Tooltip, Popover):** `trigger`, `content`. No arrow element.

**Menu (DropdownMenu, ContextMenu, Menubar):** `trigger`, `content`, `item`, `checkbox-item`, `radio-item`, `group`, `label`, `separator`, `item-indicator`. Menubar additionally emits `root` on its menu bar container. All three families share the item-level slot vocabulary; consumer disambiguation is by trigger-anchored ancestor scope.

**Listbox:** Select `root`, `trigger`, `content`, `item`, `separator`. Combobox `trigger`, `input-wrapper`, `input`, `content`, `listbox`, `item`, `group`, `empty`.

**Palette (CommandMenu):** `overlay`, `dialog`, `input-wrapper`, `input`, `list`, `item`, `group`, `group-heading`, `empty`, `shortcut`. Uses `dialog` not `content` because CommandMenu is a modal palette, not a drawer or popover.

**Disclosure:** Card `root`, `header`, `title`, `description`, `body`, `footer`. Accordion `root`, `item`, `trigger-heading`, `trigger`, `content`. Collapsible `root`, `trigger`, `content`, `content-inner`. Tabs `root`, `list`, `trigger`, `content`.

**Ordered display:** Timeline `root`, `item`, `item-marker-wrapper`, `item-marker`, `item-connector`, `item-content`, `item-timestamp`, `item-title`, `item-description`. Stepper `root`, `list`, `separator` (horizontal connector), `item`, `indicator`, `title`, `description`, `content`.

**Navigation:** Breadcrumb `root`, `list`, `item`, `link`, `page`, `separator`, `ellipsis`. Pagination `root`, `list`, `item`, `link`, `previous`, `next`, `ellipsis`. Nav `root`, `list`, `item`, `link`, `trigger`, `submenu`. NavigationMenu `root`, `list`, `item`, `trigger`, `content`, `link`. No indicator or viewport elements in NavigationMenu; scope-list entries for them do not correspond to rendered DOM.

**Tabular:** Table `root` (scroll wrapper), `table` (nested element), `caption`, `header`, `head-cell`, `body`, `row`, `cell`, `footer`. DataTable inherits Table and Pagination slots; no new attributes.

**Form controls with internal parts:** RadioGroup `root`. Radio `item`, `item-input`, `item-indicator`, `item-label`. Checkbox `root`, `input`, `indicator`, `label`. Switch `root`, `thumb`, `label`. Slider `root`, `input`, `track`, `fill`, `thumb`, `value`. FileInput `root`, `zone`, `input`, `file-list`, `file-item`, `file-name`, `file-size`, `file-remove-button`. NumberInput `root`, `input`, `decrement`, `increment`.

**Structural and remaining:** FormField `root`, `hint`, `error`. Sidebar `provider`, `root`, `header`, `content`, `footer`, `group`, `group-label`, `inset`, `menu`, `menu-item`, `menu-button`, `trigger`. AppShell `root`, `header`, `body`, `main`. EmptyState `root`, `visual`, `heading`, `description`, `action`. Callout `root`, `citation`. DatePicker: DatePickerInput `input-root`, `input`, `toggle`; DatePickerCalendar `calendar`, `calendar-header`, `prev-button`, `month-year-label`, `next-button`, `grid`, `weekday-row`, `weekday`, `week-row`, `day-cell`, `day-button`. Toast `toast`, `message`, `action`, `close`. Toaster `toaster`.

### Consequences

- Consumers target internal parts via `[data-slot="overlay"]` in plain CSS or `[&_[data-slot=overlay]]:...` in Tailwind arbitrary variants, without depending on class names or DOM structure.
- Slot names are semver-protected. Renaming a slot is a breaking change and requires a major version bump.
- Internal DOM can refactor freely as long as slot names remain on the correct elements.
- Every existing `data-*` attribute (`data-state`, `data-theme`, `data-surface`, `data-variant`, `data-side`, `data-expanded`, `data-collapsed`, `data-accordion-trigger`) coexists with `data-slot` without collision. Each attribute serves a distinct purpose: structural identity, runtime state, context cascade, or style variant.
- `data-testid` attributes on Slider (`slider-fill`, `slider-thumb`) and FileInput (`file-input-zone`) remain in place. No breaking change.
- ScrollArea cannot target its scrollbar or thumb via `data-slot`. Those are pseudo-elements only per ADR-040; `::-webkit-scrollbar-thumb` and the `scrollbar-color` property are the consumer-facing hooks.
- SplitLayout emits `root` only because main and side are consumer-supplied children. Consumers who want to attribute those parts do it themselves.
- New compound components must register their slots in `tests/contracts/data-slots.test.tsx`. Missing registration is detectable in review.

### Alternatives considered

**Class-based targeting.** Rejected. CVA outputs are not public API. Class strings mutate between releases and break consumers silently.

**Descendant tag-position selectors (`[&>div:nth-child(2)]`).** Rejected. Couples to DOM order. Breaks on any internal structure change.

**Expose every internal as a public sub-component (`<DialogOverlay>`, `<TimelineMarker>`).** Rejected. Explodes the API surface without benefit. Dialog's overlay is not a standalone primitive; it is the backdrop of a specific modal. Timeline's marker is an inline column of its item; it does not compose elsewhere.

**`data-radix-*` namespace for cross-library compatibility.** Rejected. nuka-ui has never depended on Radix. Inheriting the Radix namespace implies a relationship that does not exist and does not help consumers who are not using Radix.

**`data-nuka-slot` prefix to future-proof against namespace collisions.** Rejected. `data-slot` is the ecosystem convention (shadcn/ui since late-2024). Matching the convention lowers consumer cognitive load.

**Runtime slot derivation from `displayName`.** Rejected. `displayName` is dev-mode-only and not stable through minification. Static attribute is simpler, cheaper, and production-safe.

**Differentiated slot vocabulary per menu family (`dropdown-menu-item`, `context-menu-item`).** Rejected. All three emit the same role (`menuitem`) and serve the same consumer purpose. Differentiation is handled by ancestor scoping; shared vocabulary matches the shared semantic.

### F8 deferred (Timeline and Stepper component tokens)

The zanakadric port backlog F8 proposed component-level tokens for Timeline marker size, Timeline connector thickness, Stepper indicator size, and Stepper connector thickness.

ADR-004 states: "Components reference semantic tokens directly. Component-level tokens are added only when a component has styling needs that cannot be expressed through existing semantic tokens."

Timeline markers use `w-8 h-8 rounded-full` + `border-2` with semantic tokens for color (`--nuka-accent-bg`, `--nuka-border-base`). The dimensions match the `Icon size="sm"` (32px) that the marker contains. Stepper's indicator uses the same size for the same reason. No consumer on record has requested override of these dimensions; the port itself never needed one. Adding four new tokens per component, each verified against every variant and surface, multiplies the contract doc surface area without concrete demand.

F8 is filed as deferred, not rejected. If a future consumer raises a documented use case (a dense Timeline in a narrow panel that needs smaller markers, for instance), revisit with that use case in hand. For now, `className` escape hatch is sufficient for one-off sizing.