# sukuna-ui — full documentation

> SSR-safe, accessible React component library — 46 dark-first components built on Base UI and Tailwind v4 design tokens, WCAG AA, zero-runtime styling, RSC-ready, and documented for AI coding agents (llms.txt). This file concatenates every component page plus the design-token reference; the index is at https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt.

sukuna-ui is a React 18/19 component library: 46 components, SSR- and React Server Components-safe, WCAG AA contrast in both themes, dark-first with a light mode, styled with Tailwind v4 design tokens (`--sk-*`) on top of Base UI. Zero runtime styling.

Install: `bun add sukuna-ui` (or `npm i sukuna-ui`). Then pick one CSS path:

- **Tailwind v4 (primary):** in your global CSS add `@import "tailwindcss"; @import "sukuna-ui/theme.css"; @source "../node_modules/sukuna-ui/dist";`
- **No Tailwind:** `import "sukuna-ui/styles.css"` once.

Set the theme with `data-theme="dark"` (default/brand) or `"light"` on `<html>`. Every component below links to a Markdown page with its full API, variants, states and accessibility notes. Static components (Text, Badge, Card, Table…) work in Server Components; interactive ones are `'use client'`.

## Components

- Accordion: Vertically stacked, expandable sections.
- Alert: An inline message that draws attention to information, success, a caution, or an error.
- AlertDialog: Ask the user to confirm something that is hard to undo ("Delete project?", "Discard changes?").
- Avatar: A user/entity image with a graceful fallback (initials or icon) while loading or on error.
- Badge: A small, pill-shaped label for status and metadata — "LIVE", counts, tags.
- Breadcrumbs: Show the path to the current page and let users jump back up it.
- Button: Triggers an action.
- Card: A surface container that groups related content on an elevation.
- Carousel: A horizontal, one-slide-at-a-time content carousel for images, cards, or arbitrary nodes — the gap Slider (a range input) doesn't fill.
- Checkbox: A boolean checkbox.
- Chip: A compact token for filters, selections, or tags — optionally removable.
- Collapsible: A single disclosure: "Show advanced options", "Read more", a sidebar group.
- Combobox: A text input with a filtered list of suggestions (free-text autocomplete).
- ContextMenu: Offer contextual actions where the pointer is — right-click on desktop, long-press on touch.
- Counter: Animates a number from a start to a target value — for stat tiles, KPIs, pricing, and dashboards.
- Dialog: A modal dialog.
- Divider: A thin rule that separates content, horizontally or vertically.
- Drawer: A panel that slides in from an edge (nav, filters, details).
- Field: Wraps one form control (an Input, Checkbox, Switch, …) with a label, an optional description and an optional error, and wires the id / aria-labelledby / aria-describedby / aria-invalid relationships for you.
- GradientText: Fills text with a gradient (via background-clip: text) for wordmarks, hero headings, and accent phrases.
- HoverCard: Preview richer context for a link without a click — a user card, a repo summary, a footnote.
- Input: A single-line text input.
- Menu: A dropdown menu of actions triggered by a button.
- Meter: Show a scalar measurement within a known range: storage used, quota, password strength, a score.
- NumberField: Enter a number precisely.
- Pagination: Navigate between pages of results, with first/last always shown and ellipses in between.
- Popover: Show a small, interactive panel next to the element that opened it — filters, quick settings, a share box, a date picker later.
- Progress: A horizontal progress bar, determinate or indeterminate.
- RadioGroup: Choose one option from a small set.
- RowActions: Every data table eventually needs a per-row "Edit / Duplicate / Delete" menu.
- ScrollArea: Give a bounded region (a list, a code block, a sidebar) an overlay scrollbar that looks the same in every browser and matches the Sukuna surface, instead of the OS default.
- Select: A single-select dropdown.
- ShinyText: Sweeps a soft light band across dimmed text — for "New" flags, premium labels, and subtle CTA emphasis.
- Skeleton: A placeholder shimmer shown while content loads.
- Slider: Pick a number from a range by dragging or with the keyboard.
- Spinner: An indeterminate loading indicator (CSS spin).
- Stepper: Show progress through an ordered sequence of steps.
- Switch: An on/off toggle for an immediate setting (not form submission).
- Table: Present tabular data with Sukuna styling.
- Tabs: Switch between panels of related content.
- Text: The typographic primitive.
- Textarea: Multi-line free text: comments, descriptions, messages.
- Toast: Transient notifications.
- ToggleGroup: Pick one option from a small, mutually-exclusive set (segmented control), or toggle several independent options (a formatting toolbar).
- Tooltip: A hover/focus tooltip for supplementary text.
- VideoPlayer: Plays a single video with Sukuna-branded controls instead of each browser's native chrome, so video looks the same in Chrome, Safari and Firefox and matches the rest of the library.

---

# Accordion — sukuna-ui

> Vertically stacked, expandable sections.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Accordion } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/accordion · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-accordion.md

## Purpose

Vertically stacked, expandable sections. Keyboard + `aria` wiring from Base UI.

## API

```ts
export interface AccordionItemData { value: string; trigger: ReactNode; content: ReactNode; disabled?: boolean }

export interface AccordionProps {
  items: AccordionItemData[]
  value?: string[]
  defaultValue?: string[]
  onValueChange?: (value: string[]) => void
  openMultiple?: boolean          // default false
  headingLevel?: 1|2|3|4|5|6      // default 3 — heading element for each item's header (WCAG 1.3.1)
}
```

## Variants & tokens

item: `border-b border-line`. trigger: `group flex w-full items-center justify-between gap-3 py-3 text-left font-medium text-text hover:text-text focus-visible:ring-2 focus-visible:ring-accent-glow`. icon (chevron): `text-text-dim transition-transform group-data-[panel-open]:rotate-180`. panel content: `pb-3 text-sm text-text-dim`.

## States

collapsed · expanded (chevron rotated) · focus-visible · disabled item.

**Motion (v1.3, `docs/motion.md`):** panels animate height via `--accordion-panel-height` (`duration-base`); the chevron rotates. Reduced motion: instant.

## Accessibility

- [ ] Trigger is a `<button>` with `aria-expanded`/`aria-controls` (Base UI); panels are regions.
- [ ] Enter/Space toggle; arrow keys move between headers.
- [ ] Expanded state shown by more than the chevron (content visibility).

---

# Alert — sukuna-ui

> An inline message that draws attention to information, success, a caution, or an error.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Alert } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/alert · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-alert.md

## Purpose

An inline message that draws attention to information, success, a caution, or an error.

## API

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

export interface AlertProps extends ComponentPropsWithoutRef<'div'> {
  tone?: 'info' | 'success' | 'warning' | 'danger'   // default 'info'
  title?: ReactNode
  icon?: ReactNode
  // role derives from tone: 'alert' (assertive) for danger/warning, 'status' (polite)
  // otherwise. An explicit `role` prop always overrides the derived default.
}
```

## Variants & tokens

Base root: `w-full rounded-md border border-line border-l-4 bg-surface-2 p-4 flex gap-3`.
Left border + icon color by tone: info `text-faint`, success `success`, warning `premium`,
danger `accent` (Sukuna's one red). title `font-display font-bold text-text`; body `text-sm text-text-dim`.

## States

Static; no interactive states. (No built-in dismiss in v1 — see Decisions.)

## Accessibility

- [x] Role derives from tone: `role="alert"` (assertive) for danger/warning, `role="status"`
  (polite) for info/success; an explicit `role` overrides. Note: a live region only announces
  content that appears *after* it exists, so a server-rendered alert present at page load is
  not read aloud — the assertive announcement applies to alerts that appear after load.
- [ ] Tone is reinforced by the title/text, never color alone.
- [ ] Icon is decorative; the message text carries the meaning.

---

# AlertDialog — sukuna-ui

> Ask the user to confirm something that is hard to undo ("Delete project?", "Discard changes?").

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { AlertDialog } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/alert-dialog · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-alert-dialog.md

## Purpose

Ask the user to confirm something that is hard to undo ("Delete project?", "Discard changes?").
It differs from `Dialog` in the ways that matter for safety: it is `role="alertdialog"`, it does
**not** close on an outside click (the user must pick an answer), and it offers explicit
`Cancel` / `Action` parts. Everything else (focus trap, scroll lock, `Escape`, focus return) comes
from Base UI and matches Dialog.

## API

```ts
import type { ReactNode } from 'react'

export interface AlertDialogProps {
  children: ReactNode          // Trigger + Content
  open?: boolean
  defaultOpen?: boolean        // default false
  onOpenChange?: (open: boolean) => void
}
```

Compound: `AlertDialog` (state) · `AlertDialog.Trigger` (wraps one element, like `Dialog.Trigger`)
· `AlertDialog.Content` (backdrop + centered popup; `div` props) · `AlertDialog.Title` (`h2`,
required for a name) · `AlertDialog.Description` (`p`, the consequence) · `AlertDialog.Footer`
(right-aligned action row) · `AlertDialog.Cancel` (ghost button that closes) ·
`AlertDialog.Action` (a **primary Button** that runs `onClick` and then closes).

`Action` accepts every `Button` prop except `as` (it must stay a `<button>`), including `loading`.
Deliberately **not** in v1: a `danger` look (Q10 — one red; the primary crimson already marks the
consequential action), `closeOnOutsideClick` (an alert dialog must never allow it).

## Variants & tokens

No visual variants. Backdrop/popup reuse Dialog's recipe (`bg-black/60 backdrop-blur-sm`;
`max-w-md rounded-lg border border-line bg-surface p-6 shadow-card`), `z-[var(--sk-z-dialog)]`.
`Action` uses `buttonStyles({ variant: 'primary' })`; `Cancel` is `buttonStyles({ variant:
'ghost' })` so both line up at 40px. Footer: `mt-6 flex justify-end gap-2`.

No new tokens.

## States

closed (server renders only the trigger) · open (backdrop fade + popup scale) · closing. Outside
press: **ignored**. `Escape` and `Cancel` close without acting; `Action` runs its `onClick` and closes.
Initial focus lands on `Cancel` when present (the safe choice) — Base UI's default is the first
focusable, and `Cancel` comes first in the footer. Reduced motion: transitions off.

**Motion (v1.3, `docs/motion.md`):** the popup scale-in (95→100%) now actually animates (`transition-[opacity,scale]`). Reduced motion: instant.

## Accessibility

- [ ] Popup is `role="alertdialog"` with `aria-modal`, `aria-labelledby` → Title,
      `aria-describedby` → Description.
- [ ] Focus trapped while open; returns to the trigger on close.
- [ ] Outside click never dismisses; `Escape` does.
- [ ] Both buttons are native `<button>`s with visible focus rings.
- [ ] Contrast ≥4.5:1 both themes; `prefers-reduced-motion` honored.

---

# Avatar — sukuna-ui

> A user/entity image with a graceful fallback (initials or icon) while loading or on error.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Avatar } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/avatar · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-avatar.md

## Purpose

A user/entity image with a graceful fallback (initials or icon) while loading or on error.

## API

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

export interface AvatarProps extends ComponentPropsWithoutRef<'span'> {
  src?: string
  alt?: string
  fallback?: ReactNode   // initials or an icon, shown while loading / on error / when no src
  size?: 'sm' | 'md' | 'lg'   // default 'md'
}
```

## Variants & tokens

root: `relative inline-flex items-center justify-center overflow-hidden rounded-full bg-surface-2 text-text-dim select-none`; size sm `size-8 text-xs` / md `size-10 text-sm` / lg `size-12 text-md`. image: `size-full object-cover`. fallback: `font-semibold`.

## States

image loaded (image shown) · loading/error/no src (fallback shown).

## Accessibility

- [ ] Provide `alt` for a meaningful image; empty `alt` for decorative.
- [ ] Fallback initials are visible text; contrast ≥ 4.5:1 on `--sk-surface-2`.

---

# Badge — sukuna-ui

> A small, pill-shaped label for status and metadata — "LIVE", counts, tags.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Badge } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/badge · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-badge.md

## Purpose

A small, pill-shaped label for status and metadata — "LIVE", counts, tags. Not interactive; if a
badge needs to be clickable it belongs inside a Button or Link.

## API

```ts
import type { ComponentPropsWithoutRef } from 'react'

export interface BadgeProps extends ComponentPropsWithoutRef<'span'> {
  tone?: 'neutral' | 'accent' | 'success' | 'premium'  // default 'neutral'
  size?: 'sm' | 'md'                                    // default 'md'
  dot?: boolean   // leading status dot in currentColor
}
```

Extends `<span>`; adds only `tone`, `size`, `dot`. Pill radius is fixed (not a prop).

## Variants & tokens

| tone | utilities |
|---|---|
| neutral | `bg-surface-2 text-text-dim border border-line` |
| accent | `bg-gradient-accent text-text border border-transparent` |
| success | `bg-surface-2 text-success border border-line` |
| premium | `bg-surface-2 text-premium border border-line` |

| size | utilities |
|---|---|
| sm | `h-5 px-2 text-xs gap-1` |
| md | `h-6 px-2.5 text-sm gap-1.5` |

Base: `inline-flex items-center justify-center rounded-pill font-semibold whitespace-nowrap select-none align-middle`. Dot: `inline-block size-1.5 rounded-full bg-current shrink-0`, `aria-hidden`.

## States

Static; no interactive states.

## Accessibility

- [ ] The dot is decorative (`aria-hidden`); status is conveyed by the text, never color/dot alone.
- [ ] `accent` text on the crimson gradient meets contrast in both themes (shares the Button
      primary treatment; verify).
- [ ] Not a `button`/`a` — no role, not focusable. Clickable status → wrap in Button/Link.
- [ ] Text contrast ≥ 4.5:1 for every tone in both themes.

---

# Breadcrumbs — sukuna-ui

> Show the path to the current page and let users jump back up it.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Breadcrumbs } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/breadcrumbs · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-breadcrumbs.md

## Purpose

Show the path to the current page and let users jump back up it.

## API

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

export interface BreadcrumbItem { label: ReactNode; href?: string; current?: boolean }

export interface BreadcrumbsProps extends Omit<ComponentPropsWithoutRef<'nav'>, 'children'> {
  items: BreadcrumbItem[]
  separator?: ReactNode   // default '/'
}
```

## Variants & tokens

root: `<nav>`; list: `flex items-center gap-2 text-sm`; link: `text-text-dim hover:text-text
transition-colors focus-visible:ring-2 focus-visible:ring-accent-glow rounded-sm`; current:
`text-text font-medium`; separator: `text-text-faint select-none`.

## States

Static; links hover/focus.

## Accessibility

- [ ] `<nav aria-label="Breadcrumb">` around an ordered list.
- [ ] Current page marked `aria-current="page"` and not a link.
- [ ] Separators are decorative (`aria-hidden`).

---

# Button — sukuna-ui

> Triggers an action.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Button } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/button · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-button.md

## Purpose

Triggers an action. Crimson is reserved for the one primary action on a surface; everything else is quiet.

## API

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

interface ButtonOwnProps {
  variant?: 'primary' | 'secondary' | 'ghost' | 'outline' | 'link'   // default 'primary' (outline/link: v1.3)
  size?: 'sm' | 'md' | 'lg'                    // default 'md'
  loading?: boolean        // shows spinner, sets aria-busy, blocks clicks; keeps width
  fullWidth?: boolean
  iconOnly?: boolean       // v1.3 — square (w = h) at every size; pair with aria-label
  leadingIcon?: ReactNode
  trailingIcon?: ReactNode
}

// Discriminated on `as`. The default renders a native <button> (`type` defaults to 'button');
// `as="a"` renders an <a> with identical styling and accepts every anchor prop (href, target…).
// On the anchor, `disabled` maps to aria-disabled="true" + tabIndex={-1} + pointer-events: none,
// because a native <a> has no disabled attribute.
export type ButtonProps =
  | (ButtonOwnProps & { as?: 'button' } & Omit<ComponentPropsWithoutRef<'button'>, 'color'>)
  | (ButtonOwnProps & { as: 'a'; disabled?: boolean } & Omit<ComponentPropsWithoutRef<'a'>, 'color'>)

// Icon-only usage requires `aria-label` — enforced at the type level: pass visible `children`
// or an `aria-label`.
```

`as="a"` covers "a link that looks like a button". Deliberately **not** in v1: `asChild`/slot
polymorphism, a `color` prop (variants own color), a `premium` variant (premium is a surface
treatment, not a button), a `danger` variant (Sukuna has one red; destructive actions are out of
scope for v1).

## Variants & tokens

| Variant | Background | Text | Border | Hover |
|---|---|---|---|---|
| primary | `--sk-gradient-accent` | `--sk-text` | none | brighten + `--sk-accent-glow` shadow |
| secondary | `--sk-surface-2` | `--sk-text` | `--sk-line` | bg `--sk-well` |
| ghost | transparent | `--sk-text-dim` | none | text `--sk-text`, bg `--sk-line-soft` |
| outline (v1.3) | transparent | `--sk-text` | `--sk-line` | bg `--sk-line-soft` |
| link (v1.3) | transparent | `--sk-accent` | none | underline (offset 4); `h-auto px-0` via compound variant |

`iconOnly` (v1.3): `px-0` + `w-8`/`w-10`/`w-12` per size (compound variants) → a square control.

| Size | Height | Padding-x | Font | Radius |
|---|---|---|---|---|
| sm | 32px | `--sk-space-3` | `--sk-text-sm` | `--sk-radius-sm` |
| md | 40px | `--sk-space-5` | `--sk-text-md` | `--sk-radius-md` |
| lg | 48px | `--sk-space-6` | `--sk-text-lg` | `--sk-radius-lg` |

Font: `--sk-font-display`, weight `--sk-weight-bold`, `--sk-tracking-tight`.

## States

| State | Behavior |
|---|---|
| default | as above; `cursor: pointer` |
| hover | per table; `--sk-duration-fast` transition |
| focus-visible | 2px ring `--sk-accent-glow`, offset 2px. Never remove outline without replacing it. |
| active | `transform: scale(.98)` |
| disabled | `opacity: .45`, `cursor: not-allowed`, `pointer-events` NOT removed (tooltips must still work) |
| loading | spinner replaces `leadingIcon`, label stays (visually dimmed) to preserve width, `aria-busy="true"`, `disabled` |

**Motion (v1.3, `docs/motion.md`):** the active press (`scale .98`) now actually animates (`transition-[…,scale]`). Reduced motion: instant.

## Accessibility

- [ ] Native `<button>`; never a `div` with `role="button"`.
- [ ] Icon-only usage requires `aria-label` (enforce via TS: if no children, `aria-label` becomes required — overload type).
- [ ] Focus ring visible in both themes at ≥ 3:1 contrast against surface.
- [ ] Text contrast ≥ 4.5:1 for all variants in both themes.
- [ ] `aria-busy` while loading; spinner has `aria-hidden`.
- [ ] Space and Enter activate (native).

---

# Card — sukuna-ui

> A surface container that groups related content on an elevation.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Card } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/card · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-card.md

## Purpose

A surface container that groups related content on an elevation. Pure layout/skin — not
interactive. A clickable card is a Button or Link wrapping a Card, not a Card with an `onClick`.

## API

```ts
import type { ComponentPropsWithoutRef } from 'react'

export interface CardProps extends ComponentPropsWithoutRef<'div'> {
  elevation?: 'flat' | 'raised' | 'sunken'   // default 'flat'
  padding?: 'none' | 'sm' | 'md' | 'lg'       // default 'md'
  radius?: 'md' | 'lg'                         // default 'lg'
}
```

Extends `<div>`; adds only `elevation`, `padding`, `radius`.

## Variants & tokens

| elevation | utilities |
|---|---|
| flat | `bg-surface border border-line` |
| raised | `bg-surface border border-line shadow-card` |
| sunken | `bg-well border border-line` |

| padding | utility | | radius | utility |
|---|---|---|---|---|
| none | — | | md | `rounded-md` |
| sm | `p-4` | | lg | `rounded-lg` |
| md | `p-6` | | | |
| lg | `p-8` | | | |

Base: `block text-text`.

## States

Static; no interactive states. (`raised` is a resting elevation, not a hover effect.)

**Motion (v1.3, `docs/motion.md`):** `interactive` hover lift now actually animates (`transition-[…,translate]`). Reduced motion: instant.

## Accessibility

- [ ] A Card is a generic container — no implicit role. Give it a landmark/role only when its
      content warrants one (`role="group"` + `aria-label`, `<section>` via wrapping, etc.).
- [ ] Not focusable and has no click handler; clickable surfaces wrap a Button/Link.
- [ ] `sunken`/`flat` surfaces keep text contrast ≥ 4.5:1 in both themes.

---

# Carousel — sukuna-ui

> A horizontal, one-slide-at-a-time content carousel for images, cards, or arbitrary nodes — the gap Slider (a range input) doesn't fill.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Carousel } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/carousel · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-carousel.md

## Purpose

A horizontal, one-slide-at-a-time content carousel for images, cards, or arbitrary nodes — the gap
`Slider` (a range input) doesn't fill. Accessible by construction: labelled slides, a live region,
keyboard and swipe navigation, and a required pause control whenever it auto-rotates.

## API

**Root-managed** (not compound in v1): each direct child becomes one slide, and the root renders the
viewport, track, controls, dots, and (with `autoplay`) the pause toggle. Index state uses
`useControllableState` (like Checkbox/Switch).

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

interface CarouselProps extends Omit<ComponentPropsWithoutRef<'section'>, 'onChange'> {
  'aria-label': string           // REQUIRED — names the carousel region
  index?: number                 // controlled active slide
  defaultIndex?: number          // uncontrolled initial; default 0
  onIndexChange?: (index: number) => void
  loop?: boolean                 // wrap past the ends; default false
  autoplay?: boolean             // default false
  autoplayInterval?: number      // ms; default 5000
  pauseOnHover?: boolean         // pause on hover/focus; default true
  controls?: boolean             // render prev/next; default true
  dots?: boolean                 // render indicator dots; default true
  children: ReactNode            // each direct child is one slide
}
```

Deliberately **not** in v1 (logged as `// DECISION(open)`): pointer **swipe/drag** (deferred; buttons
+ dots + keyboard cover navigation), a compound `Carousel.Slide`/`Viewport`/`Track` API, vertical
orientation, `slidesToShow > 1` / peek, fade transition, `inert` on off-screen slides (their focusable
content stays tabbable for now), infinite virtualization, thumbnail navigation.

## Variants & tokens

`tv()` with slots (no color variants — it inherits surface/text from its slides):

| Slot | Key utilities → tokens |
|---|---|
| root | `relative` |
| viewport | `overflow-hidden`; carries the `aria-live` region |
| track | `flex` + `transition-transform duration-base ease-sukuna motion-reduce:transition-none` (`--sk-duration-base`, `--sk-ease`); inline `translateX` transform |
| slide | `shrink-0 grow-0 basis-full` |
| controls | absolute overlay, `pointer-events-none`; buttons re-enable pointer events |
| control | `rounded-full bg-surface-2 border border-line` + focus ring `ring-focus-ring` (`--sk-radius-pill`, `--sk-focus-ring`); `disabled:opacity-45 disabled:cursor-not-allowed` |
| footer | `mt-3 flex justify-center gap-3` — holds dots + play toggle |
| dot | `rounded-full bg-line` → `active` `bg-accent` (`--sk-line`, `--sk-accent`); focus ring |
| playToggle | small round button, focus ring |

No new tokens required.

## States

| State | Behavior |
|---|---|
| default | active slide shown; track translated by `index * -100%`. |
| navigate | prev/next/dots/keys change `index`; track transitions over `--sk-duration-base`. |
| prefers-reduced-motion | `motion-reduce:transition-none` — slide change is instant; **autoplay does not auto-start**. |
| at start / at end (`!loop`) | prev/next disabled respectively; with `loop`, they wrap. |
| autoplay running | advances every `autoplayInterval`; the pause toggle shows "Pause"; slides container `aria-live="off"`. |
| autoplay paused | on hover/focus (`pauseOnHover`), when the toggle is pressed, or under reduced-motion; slides container `aria-live="polite"`. |
| focus-visible | solid `--sk-focus-ring` on every control. |

## Accessibility

- [ ] Root is a labelled region: `aria-roledescription="carousel"` + required `aria-label`.
- [ ] Each slide: `role="group"`, `aria-roledescription="slide"`, `aria-label="{n} of {total}"`.
- [ ] Viewport `aria-live="polite"` when idle, `"off"` during autoplay.
- [ ] Prev/next are real `<button>`s with `aria-label`; disabled at the ends when `!loop`.
- [ ] Dots are buttons with `aria-label="Go to slide {n}"` and `aria-current` on the active dot.
- [ ] **Autoplay always renders a pause toggle** (WCAG 2.2.2); autoplay also pauses on hover/focus
      and never auto-starts under reduced-motion.
- [ ] Keyboard: arrows + Home/End move slides; controls are in the tab order; focus is never trapped.
- [ ] `motion-reduce:transition-none` makes slide changes instant.
- [ ] Known v1 gap: off-screen slides' focusable content stays tabbable (no `inert` yet) — a
      documented follow-up.

---

# Checkbox — sukuna-ui

> A boolean checkbox.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Checkbox } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/checkbox · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-checkbox.md

## Purpose

A boolean checkbox. A native `<input type="checkbox">` tinted with `accent-color`, so keyboard,
focus, and the indeterminate state come from the platform. Pass `label` for clickable text beside
the box (rendered inside a `<label>`), or label the bare input yourself.

## API

```ts
import type { ComponentPropsWithoutRef } from 'react'

type Native = Omit<
  ComponentPropsWithoutRef<'input'>,
  'size' | 'type' | 'checked' | 'defaultChecked' | 'onChange' | 'value' | 'defaultValue'
>

export interface CheckboxProps extends Native {
  size?: 'sm' | 'md'                    // default 'md'
  checked?: boolean                     // controlled
  defaultChecked?: boolean              // uncontrolled initial, default false
  onCheckedChange?: (checked: boolean) => void
  indeterminate?: boolean               // visual/AT "mixed"; default false
  label?: ReactNode                     // wraps input + text in a <label>; text click toggles
}
```

Boolean-friendly API (`onCheckedChange(checked)`) instead of raw `onChange`. Uncontrolled +
controlled via the shared `useControllableState` hook. Enter toggles as well as Space (handled
in `onKeyDown` with `preventDefault`, so it never implicitly submits a form); a consumer
`onKeyDown` runs first and can `preventDefault()` to opt out.

## Variants & tokens

Base: `accent-accent cursor-pointer rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-glow focus-visible:ring-offset-2 focus-visible:ring-offset-bg disabled:opacity-45 disabled:cursor-not-allowed`.
`accent-accent` sets `accent-color: var(--sk-accent)` — the native control renders in crimson.

| size | utility |
|---|---|
| sm | `size-4` |
| md | `size-5` |

With `label`: wrapper `<label>` `inline-flex items-center gap-2 cursor-pointer select-none text-text
has-[:disabled]:cursor-not-allowed has-[:disabled]:text-text-dim`; text `text-sm` (sm) / `text-md` (md).

## States

default · hover · focus-visible (accent-glow ring) · checked (native, accent) · indeterminate
(native mixed) · disabled (opacity .45, not-allowed).

## Accessibility

- [ ] Named by `label` (wrapping `<label>`), or by `<label htmlFor>`, `aria-label`, or `aria-labelledby`.
- [ ] Space toggles (native); Enter toggles too and never submits the form.
- [ ] Clicking the `label` text toggles the box.
- [ ] `indeterminate` is set as the DOM property so AT reports "mixed".
- [ ] Focus ring ≥ 3:1 against the surface in both themes.

---

# Chip — sukuna-ui

> A compact token for filters, selections, or tags — optionally removable.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Chip } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/chip · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-chip.md

## Purpose

A compact token for filters, selections, or tags — optionally removable. (For a non-removable
status pill, use Badge.)

## API

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

export interface ChipProps extends ComponentPropsWithoutRef<'span'> {
  tone?: 'neutral' | 'accent' | 'success' | 'premium'   // default 'neutral'
  size?: 'sm' | 'md'                                     // default 'md'
  leadingIcon?: ReactNode
  onDismiss?: () => void      // renders a × remove button
  dismissLabel?: string       // aria-label for the remove button (default 'Remove')
}
```

## Variants & tokens

Root: `inline-flex items-center gap-1.5 rounded-md border font-medium whitespace-nowrap`.
tone → same mapping as Badge (neutral/accent/success/premium). size sm `h-6 px-2 text-xs` / md `h-7 px-2.5 text-sm`. dismiss button: `rounded-sm text-current/70 hover:text-current focus-visible:ring-2 focus-visible:ring-accent-glow`.

## States

Static; the dismiss button is a native `<button>` (keyboard/focus for free).

## Accessibility

- [ ] Remove button has an `aria-label` (default "Remove"); it's a real `<button>`.
- [ ] Tone conveyed by text, not color alone.
- [ ] Text/border contrast ≥ 4.5:1 / 3:1 in both themes.

---

# Collapsible — sukuna-ui

> A single disclosure: "Show advanced options", "Read more", a sidebar group.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Collapsible } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/collapsible · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-collapsible.md

## Purpose

A single disclosure: "Show advanced options", "Read more", a sidebar group. `Accordion` is for a
*set* of sections; using a one-item Accordion for this adds a heading level and item chrome you
don't want. Collapsible is the unstyled-by-default primitive with a styled trigger and an animated
panel.

## API

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

export interface CollapsibleProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange'> {
  open?: boolean
  defaultOpen?: boolean                 // default false
  onOpenChange?: (open: boolean) => void
  disabled?: boolean                    // default false
}
```

Compound: `Collapsible` (a `div`; state) · `Collapsible.Trigger` (a `button` with a rotating
chevron; `hideIcon` to drop it; Base UI `render` to swap the element) · `Collapsible.Content` (the
panel; `keepMounted` to keep it in the DOM while closed, e.g. for find-in-page).

## Variants & tokens

No variants. trigger: `inline-flex items-center gap-2 text-sm font-medium text-text` + focus ring;
icon: `text-text-dim` rotating 180° on `data-[panel-open]`. panel: height animates via Base UI's
`--collapsible-panel-height` (`h-[var(--collapsible-panel-height)]`, `data-[starting-style]:h-0`,
`data-[ending-style]:h-0`), `overflow-hidden`. content: `pt-2 text-sm text-text-dim`. No new tokens.

## States

closed · open · disabled (trigger `opacity-45`, `cursor-not-allowed` via `data-[disabled]` — Base UI keeps a
disabled trigger focusable with `aria-disabled`, no native `disabled`, same as Tabs D27). Reduced motion: no height
transition, no chevron rotation transition.

## Accessibility

- [ ] Trigger is a native `<button>` with `aria-expanded` + `aria-controls` → panel.
- [ ] Enter/Space toggle (native).
- [ ] Hidden panel content is not in the tab order.
- [ ] Focus ring visible both themes; `prefers-reduced-motion` honored.

---

# Combobox — sukuna-ui

> A text input with a filtered list of suggestions (free-text autocomplete).

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Combobox } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/combobox · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-combobox.md

## Purpose

A text input with a filtered list of suggestions (free-text autocomplete). For a fixed
pick-from-list without typing, use Select.

## API

```ts
export interface ComboboxProps {
  items: string[]
  value?: string          // the input text (controlled)
  defaultValue?: string
  onValueChange?: (value: string) => void
  placeholder?: string    // default 'Search…'
  disabled?: boolean
  emptyMessage?: string   // default 'No results'
  maxRenderedItems?: number // cap displayed suggestions (Base UI `limit`); search spans all items
  'aria-label'?: string
}
```

For large suggestion lists, set `maxRenderedItems` (e.g. `50`) so only the top N filtered matches
render — filtering still runs over the full `items`. Items also use `content-visibility: auto` so
off-screen options are cheap. Beyond a few thousand items, prefer server-side search feeding a
capped `items`.

## Variants & tokens

input: same as Input (`bg-surface-2 border-line rounded-md`, focus ring). popup: `z-50 max-h-72
overflow-y-auto rounded-md border border-line bg-surface p-1 shadow-card` + fade/scale. item:
`h-9 px-2.5 rounded-sm data-[highlighted]:bg-line-soft data-[selected]:text-accent`. empty:
`text-sm text-text-dim`.

## States

closed · typing (filtered list) · item highlighted (keyboard) · empty (no matches) · disabled.

**Motion (v1.3, `docs/motion.md`):** directional entrance — fade + scale 95→100% + a 4px slide from the input side (`data-side`). Reduced motion: instant.

## Accessibility

- [ ] `role="combobox"` input with `aria-expanded`/`aria-controls`; listbox + options wired by Base UI.
- [ ] Arrow keys move, Enter selects, Escape closes; typeahead filters.
- [ ] Give the input an `aria-label` or associate a `<label>`.

---

# ContextMenu — sukuna-ui

> Offer contextual actions where the pointer is — right-click on desktop, long-press on touch.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { ContextMenu } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/context-menu · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-context-menu.md

## Purpose

Offer contextual actions where the pointer is — right-click on desktop, long-press on touch.
Positioning at the cursor, keyboard nav, typeahead, focus return, and dismiss come from Base UI
Context Menu. Shares `MenuItemOption` and the popup/item look with `Menu` so the two read as one
family.

## API

```ts
import type { ReactNode } from 'react'
import type { MenuItemOption } from '../menu'   // reused: { label, onSelect?, disabled?, id? }

export interface ContextMenuProps {
  children: ReactNode             // area that responds to right-click / long-press (wrapped in a
                                  // display:contents trigger carrying the touch/iOS fixes)
  items: MenuItemOption[]
}
```

Reuses `MenuItemOption` verbatim (label / `onSelect` / `disabled` / `id`). Deliberately **not** in
v1: separators, submenus, and checkbox/radio items — same scope line as `Menu`; add to both together
if wanted.

## Variants & tokens

Identical to `Menu`. popup: `z-50 min-w-40 rounded-md border border-line bg-surface p-1 shadow-card`
with enter/exit transitions. item: `flex items-center gap-2 h-9 px-2.5 rounded-sm text-sm text-text
cursor-pointer data-[highlighted]:bg-line-soft data-[disabled]:opacity-45`.

No new tokens — same set as `Menu` (`--sk-surface`, `--sk-line`, `--sk-line-soft`, `--sk-shadow-card`,
text tokens).

## States

closed · open at cursor (positioned popup) · item highlighted (pointer/keyboard) · disabled item.

**Motion (v1.3, `docs/motion.md`):** directional entrance — fade + scale 95→100% + a 4px slide from the opening side (`data-side`). Reduced motion: instant.

## Accessibility

- [ ] `role="menu"`/`menuitem`; opens on `contextmenu` event and on long-press (touch).
- [ ] Full keyboard: once open, Arrow keys move, Enter/Space select, Escape closes, focus returns.
- [ ] Also openable from the keyboard (ContextMenu key / Shift+F10) via Base UI.
- [ ] Highlighted item ≥3:1 against the popup; disabled items announced as disabled.
- [ ] Never the *only* path to an action — provide a `Menu`/button alternative for critical actions.

---

# Counter — sukuna-ui

> Animates a number from a start to a target value — for stat tiles, KPIs, pricing, and dashboards.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Counter } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/counter · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-counter.md

## Purpose

Animates a number from a start to a target value — for stat tiles, KPIs, pricing, and dashboards.
The **server renders the final value** (correct for no-JS and SEO); the animation is a progressive
enhancement that runs once on the client. Motion is decorative and never gates the information.

## API

```ts
import type { ComponentPropsWithoutRef } from 'react'

interface CounterOwnProps {
  value: number              // target value; ALSO the value rendered on the server / with no JS
  from?: number              // animation start; default 0
  duration?: number          // ms; default 1200
  decimals?: number          // fixed fraction digits; default 0
  prefix?: string            // e.g. '$'
  suffix?: string            // e.g. '%', 'k'
  format?: (n: number) => string   // full custom formatter; overrides decimals/prefix/suffix
  once?: boolean             // default true; animate only the first mount, snap on later value changes
  startOnView?: boolean      // default false; hold at `from` until scrolled into view (v1.3)
}

// Renders a <span>. `children` is omitted — the number IS the content.
export type CounterProps =
  CounterOwnProps & Omit<ComponentPropsWithoutRef<'span'>, 'children'>
```

`startOnView` (added v1.3) holds at `from` until an `IntersectionObserver` reports the number on
screen; without the API it counts on mount. Deliberately **not** in v1: locale/`Intl.NumberFormat` presets (pass your own
via `format`), scroll-scrubbed counting, spring physics, per-digit odometer roll. `format` is the
escape hatch for currency/locale — `format={(n) => n.toLocaleString()}`.

## Variants & tokens

No color/size variants — a Counter inherits type and color from its context (wrap it in `Text`, or
set `className`). The only intrinsic style is **`tabular-nums`** (`--sk-` numerals rule) so the width
doesn't jitter frame to frame while counting.

| Base | Utility |
|---|---|
| numerals | `tabular-nums` |

No new color/spacing tokens required.

## States

| State | Behavior |
|---|---|
| server / no-JS | renders the formatted **`value`** (final). This is the accessible source of truth. |
| mount (motion OK) | displays `from`, then rAF-interpolates to `value` over `duration` with an ease-out curve; ends exactly on `value`. |
| prefers-reduced-motion | **no animation** — shows the final `value` immediately (WCAG 2.3.3 / respects `motion-reduce`). |
| value change (`once={false}`) | re-animates from the currently displayed number to the new `value`. |
| value change (`once`, default) | snaps to the new `value` without re-animating. |

> One-frame note: because the server emits the final value, the mount effect briefly sets the
> display to `from` before the first animation frame. This is imperceptible and never happens for
> reduced-motion users. Documented as the SSR-correct tradeoff — we optimize for no-JS/SEO
> correctness over a hypothetical flash.

## Accessibility

- [ ] The animating digits are decorative: put the mid-animation text in an `aria-hidden` inner
      span and expose the **final** formatted value via `role="img"` + `aria-label` on the outer
      `<span>`, so a screen reader announces `"1,234"` once, not every frame. (`role="img"` is what
      makes `aria-label` valid on the wrapper — a bare `<span aria-label>` fails axe's
      `aria-prohibited-attr`.)
- [ ] Reduced-motion users get the final value with no animation.
- [ ] The final value is present in server HTML (no-JS + SEO + SR all read it).
- [ ] `tabular-nums` prevents layout shift during the count.
- [ ] Color/contrast is the responsibility of the surrounding `Text`/`className`; Counter adds none.

---

# Dialog — sukuna-ui

> A modal dialog.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Dialog } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/dialog · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-dialog.md

## Purpose

A modal dialog. Focus trap, scroll lock, `Escape`/outside-click dismiss, and `aria` wiring come
from Base UI (`@base-ui/react/dialog`); we style backdrop, popup, title, etc.

## API

```ts
export interface DialogProps {
  children: ReactNode
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
  modal?: boolean | 'trap-focus'   // default modal
}
```

Compound: `Dialog` (root) + `Dialog.Trigger` (wraps an element) + `Dialog.Content` (backdrop +
popup, portalled) + `Dialog.Title` + `Dialog.Description` + `Dialog.Close` (a button).

```tsx
<Dialog>
  <Dialog.Trigger><Button>Open</Button></Dialog.Trigger>
  <Dialog.Content>
    <Dialog.Title>Delete project?</Dialog.Title>
    <Dialog.Description>This can't be undone.</Dialog.Description>
    <Dialog.Close>Cancel</Dialog.Close>
  </Dialog.Content>
</Dialog>
```

## Variants & tokens

- backdrop: `fixed inset-0 z-50 bg-black/60 backdrop-blur-sm` + fade.
- popup: centered, `w-[90vw] max-w-lg rounded-lg border border-line bg-surface p-6 shadow-card` +
  scale/opacity enter-exit. `z-50` = `--sk-z-dialog`.
- title: `font-display text-lg font-bold tracking-tight`; description: `text-sm text-text-dim`.
- close: ghost-style button.

## States

closed (nothing) · open (backdrop + popup, focus trapped) · enter/leave transitions.

**Motion (v1.3, `docs/motion.md`):** the popup scale-in (95→100%) now actually animates (it was listed as `transform`, which Tailwind v4 `scale-*` never uses). Reduced motion: instant.

## Accessibility

- [ ] `role="dialog"` + `aria-modal`; labelled by `Dialog.Title`, described by `Dialog.Description`
      (Base UI wires these).
- [ ] Focus moves into the dialog on open, is trapped while open, and returns to the trigger on close.
- [ ] `Escape` and outside-click dismiss (modal).
- [ ] Background is inert/scroll-locked while open.

---

# Divider — sukuna-ui

> A thin rule that separates content, horizontally or vertically.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Divider } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/divider · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-divider.md

## Purpose

A thin rule that separates content, horizontally or vertically.

## API

```ts
import type { ComponentPropsWithoutRef } from 'react'

export interface DividerProps extends ComponentPropsWithoutRef<'div'> {
  orientation?: 'horizontal' | 'vertical'   // default 'horizontal'
  decorative?: boolean   // if true: aria-hidden, no separator role
}
```

## Variants & tokens

Base: `border-line`. horizontal → `w-full border-t`; vertical → `h-full self-stretch border-l`.

## States

Static; no interactive states.

## Accessibility

- [ ] Non-decorative dividers expose `role="separator"` + `aria-orientation`.
- [ ] Purely visual dividers set `decorative` so AT ignores them.
- [ ] Line meets ≥ 3:1 against the surface where it conveys structure.

---

# Drawer — sukuna-ui

> A panel that slides in from an edge (nav, filters, details).

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Drawer } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/drawer · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-drawer.md

## Purpose

A panel that slides in from an edge (nav, filters, details). Focus trap, scroll lock, and dismiss
come from Base UI Dialog; we anchor and animate it to a side.

## API

```ts
export interface DrawerProps { children: ReactNode; open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean) => void; modal?: boolean | 'trap-focus' }
```

Compound: `Drawer` + `Drawer.Trigger` + `Drawer.Content` (takes `side?: 'left'|'right'|'top'|'bottom'`,
default `'right'`) + `Drawer.Title` + `Drawer.Description` + `Drawer.Close`.

## Variants & tokens

backdrop: `fixed inset-0 bg-black/60 backdrop-blur-sm`. popup: `fixed bg-surface p-6 shadow-card`
anchored per `side` (e.g. right → `inset-y-0 right-0 h-full w-80 border-l`) with a slide-in
transform via `data-[starting-style]`/`data-[ending-style]`.

## States

closed · open (slides in from `side`, focus trapped) · enter/leave transforms.

## Accessibility

- [ ] `role="dialog"` + `aria-modal`; labelled by `Drawer.Title`, described by `Drawer.Description`.
- [ ] Focus moves in on open, trapped while open, returns to trigger on close.
- [ ] `Escape` / outside-click dismiss; background scroll-locked.

---

# Field — sukuna-ui

> Wraps one form control (an Input, Checkbox, Switch, …) with a label, an optional description and an optional error, and wires the id / aria-labelledby / aria-describedby / aria-invalid relationships for you.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Field } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/field · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-field.md

## Purpose

Wraps one form control (an `Input`, `Checkbox`, `Switch`, …) with a label, an optional
description and an optional error, and wires the `id` / `aria-labelledby` / `aria-describedby` /
`aria-invalid` relationships for you. It is the connective tissue of a form, not a control itself —
the control stays whatever you put inside. Built on **Base UI Field**, which owns the id and aria
bookkeeping so the wrapper stays thin.

## API

```tsx
import { Field } from '@sukuna/ui'
import { Input } from '@sukuna/ui'

<Field invalid={hasError}>
  <Field.Label>Email</Field.Label>
  <Field.Control render={<Input type="email" />} />
  <Field.Description>Work address only.</Field.Description>
  <Field.Error>Enter a valid email.</Field.Error>
</Field>
```

Compound parts (each maps 1:1 to a Base UI Field part; every prop the Base part takes is accepted):

| Part | Renders | Notes |
|---|---|---|
| `Field` (root) | `<div>` | `invalid`, `name`, `disabled`, `validate`, `validationMode` from Base UI Field.Root. |
| `Field.Label` | `<label>` | Auto `htmlFor` → control id. |
| `Field.Control` | `<input>` | Pass `render={<Input/>}` (or any Base UI control) to use a custom control. |
| `Field.Description` | `<p>` | Auto-linked into the control's `aria-describedby`. |
| `Field.Error` | `<div>` | Shows conditionally (see §5); auto-linked into `aria-describedby` when shown. |

`Field.Error` accepts Base UI's `match` (`boolean | keyof ValidityState`). When `match` is omitted,
the wrapper defaults it to `true` if the root has `invalid` set — so a controlled `<Field invalid>`
shows its error with no extra prop, while native-constraint validation (no `invalid` prop) keeps
Base UI's default behavior (show when the control's `ValidityState` is invalid).

Deliberately **not** in v1: a monolithic `label` / `error` string prop (the compound parts are the
API; a one-shot convenience wrapper can come later), `size` variants (the inner control owns its
size), built-in async validation UI beyond what Base UI Field exposes.

## Variants & tokens

No visual variants. Slots map straight to type/spacing tokens:

| Slot | Utilities | Tokens |
|---|---|---|
| root | `flex flex-col gap-1.5` | layout only |
| label | `text-sm font-medium text-text` | `--sk-text` |
| control | `w-full` | layout only (control brings its own styling) |
| description | `text-sm text-text-dim` | `--sk-text-dim` |
| error | `text-sm text-accent` | `--sk-accent` (Sukuna's one red, used as the danger tone) |

No raw hex; all colors resolve through `@theme` in `src/styles/theme.css`.

## States

| State | Behavior |
|---|---|
| default | label + control; description/error optional |
| invalid (`<Field invalid>`) | control gets `aria-invalid="true"`; `Field.Error` renders and joins `aria-describedby` |
| valid | `Field.Error` renders `null`; nothing added to `aria-describedby` for it |
| disabled (`<Field disabled>`) | forwarded to the control (Base UI Field.Root precedence) |
| focus | handled entirely by the inner control (Input's own focus ring) |

The wrapper adds **zero** runtime styling and no focus handling of its own — focus visuals live on
the control.

## Accessibility

- [ ] Label is a real `<label>` associated with the control (`htmlFor` ↔ control `id`, from Base UI).
- [ ] Description and error, when present, are referenced by the control's `aria-describedby`.
- [ ] `aria-invalid="true"` on the control when the field is invalid.
- [ ] Error text meets ≥ 4.5:1 contrast in both themes (`text-accent` on surfaces).
- [ ] No independent focus target on the wrapper; focus lives on the control.

---

# GradientText — sukuna-ui

> Fills text with a gradient (via background-clip: text) for wordmarks, hero headings, and accent phrases.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { GradientText } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/gradient-text · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-gradient-text.md

## Purpose

Fills text with a gradient (via `background-clip: text`) for wordmarks, hero headings, and accent
phrases. Pure CSS — server-rendered, no runtime, no hooks. The gradient is a **preset** that resolves
through `--sk-*` tokens, so it stays on-brand and theme-aware in both light and dark.

## API

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

export type GradientTextElement =
  | 'span' | 'p' | 'div' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'

interface GradientTextOwnProps {
  as?: GradientTextElement          // default 'span'
  gradient?: 'accent'               // default 'accent' — preset only (see §11); 'premium' pending Q13
  children: ReactNode
}

export type GradientTextProps =
  GradientTextOwnProps & Omit<ComponentPropsWithoutRef<'span'>, 'color'>
```

Deliberately **not** in v1: a raw `from`/`via`/`to` color prop or arbitrary hex — that would force
interpolated class names (violates rule #7) or raw hex in a utility (violates rule #8). Custom
gradients are the documented escape hatch: pass `style={{ backgroundImage: 'linear-gradient(...)' }}`
(inline style reliably overrides the `bg-gradient-accent` utility; a `className` gradient may not,
since tailwind-merge doesn't dedupe the custom utility). `color` is omitted so it can't fight the
clipped fill.

## Variants & tokens

| Variant | Fill | Utility | Status |
|---|---|---|---|
| accent | `--sk-gradient-accent` | `bg-gradient-accent` | **shipped** |
| premium | `--sk-gradient-premium` | `bg-gradient-premium` | pending owner (Q13) |

The clip mechanism: `bg-clip-text` + `-webkit-background-clip:text` + `-webkit-text-fill-color:transparent`
reveals the gradient, while a real `color` (`text-accent`) stays as the fallback (see §8). `premium`
is **not shipped** — `--sk-gradient-premium` (e.g. `linear-gradient(135deg, var(--sk-premium),
var(--sk-premium-dim))`) is not yet in `docs/tokens.md`; it's added as an additive `minor` once the
token + `@utility bg-gradient-premium` are approved (Q13) and emitted by `scripts/build-tokens.ts`.

## States

Static — no interactive states, no animation, so no reduced-motion concern. Selectable, copyable real
text.

## Accessibility

- [ ] Renders real, selectable text (not an image) — screen readers and search engines read it.
- [ ] Real `color` (`text-accent`) via `-webkit-text-fill-color: transparent` (not `color:
      transparent`), so text stays visible if `background-clip: text` is unsupported and contrast
      tooling has a real color to read.
- [ ] Use real heading tags (`as="h1"`) for headings — the gradient is style, not structure.
- [ ] **Contrast:** clipped gradient text can dip below AA. Reserve GradientText for **large display
      text** (≥ 24px / bold, so the 3:1 large-text floor applies) and ensure the gradient's lightest
      stop clears 3:1 on the surface. Do not use it for body copy — documented in TSDoc `@remarks`.
- [ ] `-webkit-background-clip: text` prefix included for WebKit/Blink.

---

# HoverCard — sukuna-ui

> Preview richer context for a link without a click — a user card, a repo summary, a footnote.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { HoverCard } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/hover-card · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-hover-card.md

## Purpose

Preview richer context for a link without a click — a user card, a repo summary, a footnote.
Positioning, hover/focus open-and-close delays, portalling, and dismiss come from Base UI Preview
Card. Distinct from `Tooltip`: HoverCard holds interactive/structured content and is **not** a
`role="tooltip"` (screen readers reach its content), so it must never carry information the user
can't get another way.

## API

```ts
import type { ReactNode } from 'react'

export interface HoverCardProps {
  children: ReactNode          // Trigger + Content
  open?: boolean
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
  delay?: number               // ms before opening on hover; default 300
  closeDelay?: number          // ms before closing after leave; default 300
}
```

Compound: `HoverCard` + `HoverCard.Trigger` (renders an `<a>`; accepts `href`, `delay`,
`closeDelay`, and Base UI `render` to swap the element) + `HoverCard.Content` (takes
`side?: 'top'|'right'|'bottom'|'left'` default `'top'`, `align?: 'start'|'center'|'end'` default
`'center'`, `sideOffset?: number` default `8`). `delay`/`closeDelay` live on the **Trigger** (Base
UI), not the root.

Deliberately **not** in v1: an arrow (no library component uses one — Tooltip/Menu offset without
one), `openOnHover={false}` click mode (that's `Popover`, out of scope for now), and a backdrop.

## Variants & tokens

popup: `max-w-xs rounded-md border border-line bg-surface p-4 text-sm text-text shadow-card` with
enter/exit fade+scale via `data-[starting-style]`/`data-[ending-style]` and
`origin-[var(--transform-origin)]`. positioner: `z-[var(--sk-z-popover)]`. trigger: focus ring only
(colour inherited so any link style works).

No new tokens — reuses `--sk-surface`, `--sk-line`, `--sk-shadow-card`, `--sk-focus-ring`,
`--sk-z-popover`, text tokens.

## States

closed · opening (after `delay`, fades/scales in) · open · closing (after `closeDelay`). Reduced
motion: enter/exit transforms collapse to instant (`motion-reduce:*`).

**Motion (v1.3, `docs/motion.md`):** directional entrance — fade + scale 95→100% + a 4px slide from the trigger side (`data-side`). Reduced motion: instant.

## Accessibility

- [ ] Opens on hover **and** keyboard focus of the trigger; closes on blur/leave/Escape.
- [ ] Content reachable by AT (not `role="tooltip"`); never the sole source of critical info.
- [ ] Interactive content inside the card is focusable and the card stays open while focus is in it.
- [ ] `prefers-reduced-motion` honored (no scale/slide).
- [ ] Text contrast ≥4.5:1 in both themes.

---

# Input — sukuna-ui

> A single-line text input.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Input } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/input · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-input.md

## Purpose

A single-line text input. Native `<input>` styled to Sukuna, with size and an invalid state.

## API

```ts
import type { ComponentPropsWithoutRef } from 'react'

export interface InputProps extends Omit<ComponentPropsWithoutRef<'input'>, 'size'> {
  size?: 'sm' | 'md' | 'lg'   // default 'md' (shadows the native numeric `size` attr — omitted)
  invalid?: boolean           // sets aria-invalid + crimson border
}
```

Native `size` (visible width in chars) is omitted in favor of the variant `size`. Everything else
native passes through (`type`, `value`, `defaultValue`, `onChange`, `placeholder`, `disabled`,
`required`, `name`, `autoComplete`, `aria-*`, …).

## Variants & tokens

Base: `w-full bg-surface-2 text-text border border-line placeholder:text-text-faint transition-[border-color,box-shadow] duration-fast ease-sukuna focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-glow focus-visible:border-accent disabled:opacity-45 disabled:cursor-not-allowed`.

| size | utilities |
|---|---|
| sm | `h-8 px-3 text-sm rounded-sm` |
| md | `h-10 px-3 text-md rounded-md` |
| lg | `h-12 px-4 text-lg rounded-lg` |

| invalid | utilities |
|---|---|
| true | `border-accent focus-visible:ring-accent-glow` |

Sukuna has one red (crimson), so the invalid border reuses `--sk-accent` (see `docs/questions.md` Q10).

## States

| State | Behavior |
|---|---|
| default | as above |
| focus-visible | 2px `--sk-accent-glow` ring, border → accent |
| invalid | crimson border always; `aria-invalid="true"` |
| disabled | `opacity .45`, `cursor: not-allowed` (native disabled) |

## Accessibility

- [ ] Every input has a programmatic label — a `<label htmlFor>`, `aria-label`, or
      `aria-labelledby`. The component does not render a label; the consumer supplies one.
- [ ] `invalid` sets `aria-invalid`; pair with `aria-describedby` pointing at the error text.
- [ ] Placeholder is not a label (it disappears on input); never rely on it alone.
- [ ] Focus ring ≥ 3:1 against the surface in both themes.

---

# Menu — sukuna-ui

> A dropdown menu of actions triggered by a button.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Menu } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/menu · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-menu.md

## Purpose

A dropdown menu of actions triggered by a button. Keyboard nav, typeahead, focus, and dismiss from
Base UI.

## API

```ts
import type { ReactElement, ReactNode } from 'react'

export interface MenuItemOption {
  label: ReactNode
  icon?: ReactNode        // v1.3 — decorative leading icon (aria-hidden, 16px, text-text-dim)
  onSelect?: () => void   // fires on click / Enter / Space; the menu then closes
  disabled?: boolean
  id?: string             // stable React key — set it for dynamic (filtered/reordered) menus;
                          // falls back to the array index
}

export interface MenuProps {
  children: ReactElement            // the trigger (e.g. a Button)
  items: MenuItemOption[]
  side?: 'top' | 'right' | 'bottom' | 'left'   // default 'bottom'
  align?: 'start' | 'center' | 'end'            // default 'start'
  sideOffset?: number                            // default 6
}
```

## Variants & tokens

popup: `z-50 min-w-40 rounded-md border border-line bg-surface p-1 shadow-card` + enter/exit
transitions. item: `flex items-center gap-2 h-9 px-2.5 rounded-sm text-sm text-text cursor-pointer
data-[highlighted]:bg-line-soft data-[disabled]:opacity-45`.

## States

closed · open (positioned popup) · item highlighted (keyboard) · disabled item.

**Motion (v1.3, `docs/motion.md`):** directional entrance — fade + scale 95→100% + a 4px slide from the trigger side (`data-side`). Reduced motion: instant.

## Accessibility

- [ ] `role="menu"`/`menuitem` wired by Base UI; trigger has `aria-haspopup`/`aria-expanded`.
- [ ] Arrow keys move, Enter/Space select, Escape closes, focus returns to trigger.

---

# Meter — sukuna-ui

> Show a scalar measurement within a known range: storage used, quota, password strength, a score.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Meter } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/meter · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-meter.md

## Purpose

Show a scalar measurement within a known range: storage used, quota, password strength, a score.
`Progress` is for *task completion over time* (`role="progressbar"`, has an indeterminate state);
Meter is a *static gauge* (`role="meter"`) and is announced as such. Using the right one tells
screen-reader users what the bar means.

## API

```ts
import type { ReactNode } from 'react'

export interface MeterProps {
  value: number                         // required — a meter always has a value
  min?: number                          // default 0
  max?: number                          // default 100
  label?: ReactNode                     // visible caption; also names the meter
  showValue?: boolean                   // default false — prints the formatted value on the right
  format?: Intl.NumberFormatOptions     // e.g. { style: 'percent' } or { style: 'unit', unit: 'gigabyte' }
  size?: 'sm' | 'md'                    // default 'md'
  tone?: 'accent' | 'success' | 'premium'   // default 'accent'
  className?: string
  'aria-label'?: string                 // required when there is no `label`
  'aria-valuetext'?: string             // override the spoken value ("3 of 5 GB")
}
```

Deliberately **not** in v1: low/high/optimum thresholds that auto-switch the tone (pick `tone`
yourself), segmented meters, a vertical orientation.

## Variants & tokens

Track `bg-surface-2 rounded-pill w-full overflow-hidden`; indicator `h-full rounded-pill`.

| size | track height | | tone | indicator |
|---|---|---|---|---|
| sm | `h-1.5` | | accent | `bg-accent` |
| md | `h-2` | | success | `bg-success` |
| | | | premium | `bg-premium` |

Header row: `mb-1 flex justify-between text-sm`; label `text-text-dim`, value
`text-text tabular-nums`. No new tokens (success/premium already exist and pass AA for UI, D22).

## States

Static — no hover/focus (not interactive). Indicator width transition on value change
(`transition-[width] motion-reduce:transition-none`).

**Motion (v1.3, `docs/motion.md`):** the bar grows in from the left on mount (`starting:scale-x-0`, `duration-slow`) and eases between values. Reduced motion: instant.

## Accessibility

- [ ] `role="meter"` with `aria-valuenow/min/max`; `aria-valuetext` from `format` or override.
- [ ] Named by `label` (`aria-labelledby`) or `aria-label`.
- [ ] Indicator color is not the only signal — pair with `showValue` or text when tone matters.

---

# NumberField — sukuna-ui

> Enter a number precisely.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { NumberField } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/number-field · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-number-field.md

## Purpose

Enter a number precisely. Steppers, arrow-key increment, min/max clamping, and `Intl` formatting
(currency, percent, decimals) come from Base UI Number Field — a plain `<input type="number">` gives
none of that and formats inconsistently across browsers.

## API

```ts
import type { ComponentPropsWithoutRef } from 'react'

interface NumberFieldOwnProps {
  value?: number | null           // controlled; null = empty
  defaultValue?: number           // uncontrolled initial
  onValueChange?: (value: number | null) => void
  min?: number
  max?: number
  step?: number                   // default 1
  largeStep?: number              // Shift+Arrow / PageUp-Down; default 10
  format?: Intl.NumberFormatOptions   // e.g. { style: 'currency', currency: 'USD' }
  size?: 'sm' | 'md' | 'lg'       // default 'md'
  readOnly?: boolean
  allowWheelScrub?: boolean        // default false — scroll wheel over the input changes value
}

// The visible field is a native <input>; own props are consumed, the rest spread onto it.
export type NumberFieldProps = NumberFieldOwnProps &
  Omit<
    ComponentPropsWithoutRef<'input'>,
    'value' | 'defaultValue' | 'onChange' | 'size' | 'type' | 'min' | 'max' | 'step'
  >
```

Deliberately **not** in v1: a `ScrubArea` drag-to-change cursor (pointer-only, poor a11y; wheel scrub
is opt-in instead), prefix/suffix adornment slots (use `format`), and a `variant` prop (one surface
treatment, matching `Input`).

## Variants & tokens

group: `inline-flex items-stretch rounded-md border border-line bg-surface-2
focus-within:ring-2 focus-within:ring-focus-ring`. input: `min-w-0 flex-1 bg-transparent px-3
text-text tabular-nums outline-none placeholder:text-text-faint`. decrement/increment:
`grid w-9 place-items-center text-text-dim hover:bg-well hover:text-text
data-[disabled]:opacity-45` (decrement gets a right border, increment a left border via
`border-line`).

| Size | Height | Font | Radius |
|---|---|---|---|
| sm | 32px (`h-8`) | `text-sm` | `rounded-sm` |
| md | 40px (`h-10`) | `text-md` | `rounded-md` |
| lg | 48px (`h-12`) | `text-lg` | `rounded-lg` |

No new tokens — reuses `--sk-surface-2`, `--sk-line`, `--sk-well`, `--sk-focus-ring`, text tokens.

## States

| State | Behavior |
|---|---|
| default | steppers enabled within range |
| focus-within | 2px `--sk-focus-ring` ring on the group |
| at-min / at-max | the corresponding stepper is `disabled` (dimmed, not clickable) |
| readOnly | input not editable (native `readonly`), still focusable/selectable; the value can't be changed |
| disabled | whole group `opacity-45`, `cursor-not-allowed`, steppers off |

## Accessibility

- [ ] Input exposes `role="spinbutton"` with `aria-valuenow/min/max` (Base UI).
- [ ] Stepper buttons have `aria-label` ("Increase"/"Decrease") and `aria-hidden` icons.
- [ ] Arrow keys step; Shift+Arrow / PageUp-Down use `largeStep`; Home/End jump to min/max.
- [ ] Focus ring visible in both themes at ≥3:1 against surface.
- [ ] Pair with `Field` (`Field.Label`) for an associated label; `aria-label` accepted otherwise.

---

# Pagination — sukuna-ui

> Navigate between pages of results, with first/last always shown and ellipses in between.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Pagination, paginationRange } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/pagination · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-pagination.md

## Purpose

Navigate between pages of results, with first/last always shown and ellipses in between.

## API

```ts
import type { ComponentPropsWithoutRef } from 'react'

export interface PaginationProps extends Omit<ComponentPropsWithoutRef<'nav'>, 'onChange'> {
  page: number            // current page, 1-based
  count: number           // total pages
  onPageChange?: (page: number) => void
  siblingCount?: number   // pages shown around current (default 1)
}
```

## Variants & tokens

page button: `size-9 rounded-md text-sm text-text-dim hover:bg-line-soft data-[active]:bg-surface-2
data-[active]:text-text focus-visible:ring-2 focus-visible:ring-accent-glow`; nav (prev/next):
same + `disabled:opacity-45`; ellipsis: `text-text-faint`.

## States

page: default · hover · active (`aria-current="page"`). prev/next disabled at the bounds.

## Accessibility

- [ ] `<nav aria-label="Pagination">`; current page `aria-current="page"`.
- [ ] Prev/Next have labels and are `disabled` at the ends.
- [ ] Ellipses are inert text, not buttons.

---

# Popover — sukuna-ui

> Show a small, interactive panel next to the element that opened it — filters, quick settings, a share box, a date picker later.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Popover } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/popover · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-popover.md

## Purpose

Show a small, interactive panel next to the element that opened it — filters, quick settings, a
share box, a date picker later. Opens on **click** (not hover) and holds real controls, which is
what separates it from `Tooltip` (hover, text only) and `HoverCard` (hover, preview only). Unlike
`Dialog` it is non-modal by default: the page stays interactive and scrollable. Positioning,
flipping, focus management, outside-press and `Escape` dismiss come from Base UI Popover.

## API

```ts
import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react'

export interface PopoverProps {
  children: ReactNode                 // Trigger + Content
  open?: boolean
  defaultOpen?: boolean               // default false
  onOpenChange?: (open: boolean) => void
  modal?: boolean | 'trap-focus'      // default false — page stays interactive
}

export interface PopoverContentProps extends ComponentPropsWithoutRef<'div'> {
  side?: 'top' | 'right' | 'bottom' | 'left'   // default 'bottom'
  align?: 'start' | 'center' | 'end'           // default 'center'
  sideOffset?: number                          // default 8
}
```

Compound: `Popover` (state) · `Popover.Trigger` (wraps **one** element, e.g. a `Button`; Base UI
merges `onClick`/`aria-expanded`/`aria-haspopup`/ref onto it — same contract as `Dialog.Trigger`) ·
`Popover.Content` (portal + positioner + popup) · `Popover.Title` (`h2`, names the popup) ·
`Popover.Description` (`p`) · `Popover.Close` (ghost `button`; Base UI `render` to swap it).

Deliberately **not** in v1: an arrow (Tooltip/Menu/HoverCard have none), `openOnHover` (that is
`HoverCard`), a backdrop, anchoring to a non-trigger element.

## Variants & tokens

No visual variants. popup: `w-72 max-w-[calc(100vw-2rem)] rounded-md border border-line bg-surface
p-4 text-sm text-text shadow-card`, fade + scale from `var(--transform-origin)` via
`data-[starting-style]`/`data-[ending-style]`. positioner: `z-[var(--sk-z-popover)]` (60 — above a
Dialog at 50, so a Popover inside a Dialog renders on top). title/description/close mirror Dialog.

No new tokens — `--sk-surface`, `--sk-line`, `--sk-shadow-card`, `--sk-focus-ring`, `--sk-z-popover`.

## States

closed (server renders only the trigger) · open (fades/scales in) · closing. `Escape`, outside press
and `Popover.Close` close it; focus returns to the trigger. Reduced motion: transitions off.

**Motion (v1.3, `docs/motion.md`):** directional entrance — fade + scale 95→100% + a 4px slide from the trigger side (`data-side`). Reduced motion: instant.

## Accessibility

- [ ] Trigger gets `aria-expanded` + `aria-haspopup="dialog"`; popup is `role="dialog"`.
- [ ] `Popover.Title` / `Popover.Description` wire `aria-labelledby` / `aria-describedby`.
- [ ] Focus moves into the popup on open and returns to the trigger on close.
- [ ] `Escape` closes; outside press closes.
- [ ] Text contrast ≥4.5:1 both themes; focus ring on `Popover.Close`.
- [ ] `prefers-reduced-motion` honored.

---

# Progress — sukuna-ui

> A horizontal progress bar, determinate or indeterminate.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Progress } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/progress · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-progress.md

## Purpose

A horizontal progress bar, determinate or indeterminate.

## API

```ts
export interface ProgressProps {
  value?: number | null   // 0..max; null/omitted → indeterminate
  max?: number            // default 100
  label?: ReactNode
  size?: 'sm' | 'md'      // default 'md'
  className?: string
  'aria-label'?: string
}
```

## Variants & tokens

track: `overflow-hidden rounded-pill bg-surface-2`, size sm `h-1.5` / md `h-2`. indicator:
`bg-accent rounded-pill transition-[width]`; indeterminate → `w-1/3 animate-pulse`. label:
`text-sm text-text-dim`. Base UI sizes the indicator width from the value.

## States

determinate (width = value) · indeterminate (pulsing partial bar).

**Motion (v1.3, `docs/motion.md`):** determinate bar grows in from the left on mount (`starting:scale-x-0`); indeterminate is a sliding 40% bar (`animate-indeterminate`) — static under reduced motion. Reduced motion: instant.

## Accessibility

- [ ] `role="progressbar"` with `aria-valuenow/min/max` (determinate) from Base UI.
- [ ] Accessible name via `aria-label` or a visible `label`.
- [ ] Indeterminate omits `aria-valuenow`.

---

# RadioGroup — sukuna-ui

> Choose one option from a small set.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { RadioGroup } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/radio-group · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-radio-group.md

## Purpose

Choose one option from a small set. Roving focus + arrow-key selection from Base UI.

## API

```ts
export interface RadioOption { value: string; label: ReactNode; disabled?: boolean }

export interface RadioGroupProps {
  items: RadioOption[]
  value?: string
  defaultValue?: string
  onValueChange?: (value: string) => void
  name?: string
  disabled?: boolean
  orientation?: 'vertical' | 'horizontal'   // default 'vertical'
  size?: 'sm' | 'md'                          // default 'md'
  'aria-label'?: string
}
```

## Variants & tokens

group: flex (col vertical / row horizontal) gap. control (the radio): `rounded-full border border-line bg-surface-2 data-[checked]:border-accent focus-visible:ring-2 focus-visible:ring-accent-glow disabled:opacity-45`, size sm `size-4` / md `size-5`. indicator: centered `rounded-full bg-accent` dot, hidden when unchecked. label: `text-sm text-text`.

## States

unchecked · checked (accent border + dot) · focus-visible ring · disabled.

## Accessibility

- [ ] `role="radiogroup"` with an accessible name (`aria-label`/`aria-labelledby`).
- [ ] Arrow keys move + select; Tab enters/leaves the group (Base UI).
- [ ] Each option has a visible, associated label.

---

# RowActions — sukuna-ui

> Every data table eventually needs a per-row "Edit / Duplicate / Delete" menu.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { RowActions } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/row-actions · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-row-actions.md

## Purpose

Every data table eventually needs a per-row "Edit / Duplicate / Delete" menu. RowActions packages
the pattern: a square ghost `Button` with a vertical-ellipsis icon, a required accessible name that
names the row ("Actions for Invoice #42"), and a `Menu` of options that can carry icons. It is
kept out of `Table` itself so `Table` stays a zero-JS server component and never pulls Base UI
(its 2 kB size budget); `Table.ActionsCell` / `Table.ActionsHeaderCell` give the column its layout.

## API

```ts
import type { MenuItemOption } from 'sukuna-ui'

export interface RowActionsProps {
  items: MenuItemOption[]          // { label, icon?, onSelect?, disabled?, id? }
  'aria-label'?: string            // default 'Row actions' — pass one that names the row
  size?: 'sm' | 'md'               // trigger size; default 'sm' (fits a 44px table row)
  align?: 'start' | 'center' | 'end'   // menu alignment; default 'end' (column sits at the right)
  side?: 'top' | 'right' | 'bottom' | 'left'   // default 'bottom'
  disabled?: boolean               // disables the trigger
  className?: string               // merged onto the trigger
}
```

`MenuItemOption` gains `icon?: ReactNode` (v1.3) — a decorative, `aria-hidden` leading icon,
16px, tinted `text-text-dim`. Applies to `Menu`, `ContextMenu` and `RowActions`.

Table layout parts (static, in `Table`): `Table.ActionsHeaderCell` — a `th` whose default content is
a visually hidden "Actions" label (screen readers still get a column name), `w-px text-right`;
`Table.ActionsCell` — a `td`, `w-px text-right whitespace-nowrap`, holding the `RowActions`.

```tsx
<Table>
  <Table.Header>
    <Table.Row>
      <Table.HeaderCell>Invoice</Table.HeaderCell>
      <Table.ActionsHeaderCell />
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>#42</Table.Cell>
      <Table.ActionsCell>
        <RowActions
          aria-label="Actions for invoice #42"
          items={[
            { label: 'Edit', icon: <PencilIcon />, onSelect: edit },
            { label: 'Delete', icon: <TrashIcon />, onSelect: remove },
          ]}
        />
      </Table.ActionsCell>
    </Table.Row>
  </Table.Body>
</Table>
```

Deliberately **not** in v1: separators/groups/submenus (Menu doesn't have them yet), a `danger`
item color (Q10), a Table `columns` config (Table is compositional by design).

## Variants & tokens

Trigger = `Button variant="ghost" iconOnly size="sm|md"` (32/40px square). Icon: vertical ellipsis
SVG, `size-4`, `currentColor`. Menu: unchanged Menu tokens; item icon slot `size-4 shrink-0
text-text-dim` inside the existing `gap-2` row. No new tokens.

## States

Trigger: default / hover / focus-visible / disabled (Button's). Menu: closed / open, item
highlighted / disabled (Menu's). Reduced motion via Menu.

## Accessibility

- [ ] Trigger is a native `<button>` with `aria-haspopup="menu"`/`aria-expanded` and a name
      (default "Row actions"; docs push a row-specific name so 20 identical buttons are distinguishable).
- [ ] Items are `role="menuitem"`; icons are `aria-hidden`, the label is the name.
- [ ] Arrow keys / Enter / Escape via Menu; focus returns to the trigger.
- [ ] Actions header keeps a screen-reader column name ("Actions", visually hidden).

---

# ScrollArea — sukuna-ui

> Give a bounded region (a list, a code block, a sidebar) an overlay scrollbar that looks the same in every browser and matches the Sukuna surface, instead of the OS default.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { ScrollArea } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/scroll-area · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-scroll-area.md

## Purpose

Give a bounded region (a list, a code block, a sidebar) an overlay scrollbar that looks the same in
every browser and matches the Sukuna surface, instead of the OS default. The content is real,
server-rendered DOM inside a native-scrolling viewport — only the visible scrollbar is custom — so
keyboard scrolling, wheel, and text selection behave natively.

## API

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

interface ScrollAreaOwnProps {
  orientation?: 'vertical' | 'horizontal' | 'both'  // which scrollbars to render; default 'vertical'
  children: ReactNode
}

// Sizing (height / max-height / width) is the consumer's job via className on the root.
export type ScrollAreaProps = ScrollAreaOwnProps & ComponentPropsWithoutRef<'div'>
```

Deliberately **not** in v1: a Radix-style `type` (`hover`/`always`/`scroll`/`auto`) visibility mode
(Base UI shows the scrollbar on interaction; a single sensible default), and `scrollHideDelay`.

## Variants & tokens

root: `relative overflow-hidden` (consumer sets size). viewport: `h-full w-full rounded-[inherit]`
(native scroll; `focus-visible:ring-2 focus-visible:ring-focus-ring` when focusable).
scrollbar: `flex touch-none select-none p-0.5 bg-transparent
transition-colors duration-fast data-[hovering]:bg-well/50` — `w-2.5` vertical / `h-2.5` horizontal.
thumb: `flex-1 rounded-pill bg-line hover:bg-text-faint`. corner: `bg-transparent`.

No new tokens — reuses `--sk-line`, `--sk-well`, `--sk-text-faint`, `--sk-focus-ring`,
`--sk-radius-pill`.

## States

idle (thumb dim) · hovering scrollbar (track tint, thumb brighter) · dragging thumb · at edge.
Vertical only / horizontal only / both (a corner square where they meet).

## Accessibility

- [ ] Viewport scrolls with wheel, arrow keys, PageUp/Down, Home/End (native — not intercepted).
- [ ] Content is real DOM, present at SSR and reachable by AT and Find-in-page.
- [ ] Custom scrollbar is decorative; never the only way to reach content.
- [ ] Thumb ≥3:1 against the track; focusable viewport shows a visible ring.
- [ ] Respects OS "always show scrollbars" without breaking layout (overlay, not layout-shifting).

---

# Select — sukuna-ui

> A single-select dropdown.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Select } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/select · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-select.md

## Purpose

A single-select dropdown. Keyboard, typeahead, positioning, dismiss, and listbox a11y come from
Base UI (`@base-ui/react/select`); we style the trigger, popup, and items.

## API

```ts
export interface SelectOption { value: string; label: ReactNode; disabled?: boolean }

export interface SelectProps {
  items: SelectOption[]
  value?: string            // controlled
  defaultValue?: string
  onValueChange?: (value: string) => void
  placeholder?: string      // default 'Select…'
  disabled?: boolean
  name?: string             // form field name
  id?: string
  size?: 'sm' | 'md'        // default 'md'
  'aria-label'?: string
}
```

Prop-driven with an `items` array (string values in v1). The `Value` shows the selected item's
label, or the placeholder when empty.

## Variants & tokens

- trigger: `bg-surface-2 text-text border border-line rounded-md`, `data-[popup-open]:border-accent`,
  focus ring; `size` sm `h-8 text-sm` / md `h-10 text-md`.
- popup: `min-w-[var(--anchor-width,10rem)] max-h-[min(24rem,var(--available-height,24rem))] overflow-y-auto`
  `rounded-md border border-line bg-surface p-1 shadow-card` + fade/scale; z-index on the positioner
  (`z-[var(--sk-z-popover)]`). Opens below the trigger (`alignItemWithTrigger={false}`, flips up
  when cramped), is at least as wide as the trigger, and never taller than the space on its side.
- item: `h-9 px-2.5 rounded-sm text-sm`, `data-[highlighted]:bg-line-soft`, `data-[disabled]` dim.
- indicator: `text-accent` check; icon: `text-text-dim` chevron.

## States

closed · open (listbox) · item highlighted (keyboard) · item selected (check) · disabled item ·
disabled trigger.

**Motion (v1.3, `docs/motion.md`):** directional entrance — fade + scale 95→100% + a 4px slide from the trigger side (`data-side`). Reduced motion: instant.

## Accessibility

- [ ] Trigger exposes the selected value; give it an `aria-label` or associate a `<label>` via `id`.
- [ ] Listbox roles, arrow-key navigation, typeahead, and selection from Base UI.
- [ ] `Escape` / outside-click dismiss; focus returns to the trigger.
- [ ] Disabled items are not selectable and are announced disabled.

---

# ShinyText — sukuna-ui

> Sweeps a soft light band across dimmed text — for "New" flags, premium labels, and subtle CTA emphasis.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { ShinyText } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/shiny-text · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-shiny-text.md

## Purpose

Sweeps a soft light band across dimmed text — for "New" flags, premium labels, and subtle CTA
emphasis. Pure CSS animation, so it works in Server Components. The base text is legible on its own;
the sheen is decorative and honors `prefers-reduced-motion`.

## API

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

export type ShinyTextElement = 'span' | 'p' | 'div' | 'strong'

interface ShinyTextOwnProps {
  as?: ShinyTextElement                 // default 'span'
  speed?: 'slow' | 'normal' | 'fast'    // default 'normal' — enum, not a raw duration (rule #7)
  children: ReactNode
}

export type ShinyTextProps =
  ShinyTextOwnProps & Omit<ComponentPropsWithoutRef<'span'>, 'color'>
```

Deliberately **not** in v1: `disabled` (manual freeze — deferred; `animate-shine` is a custom
utility tailwind-merge doesn't know, so a `disabled → animate-none` variant risks an unresolved
cascade conflict; `motion-reduce` already covers the a11y need), arbitrary duration/delay numbers
(enum keeps class names literal), configurable sheen color or angle (fixed to the on-brand light
band), gradient-fill text (that's `GradientText`). `color` omitted so it can't fight the clipped
sheen.

## Variants & tokens

| Variant | Values → utility |
|---|---|
| speed | slow → `animate-shine-slow` · normal → `animate-shine` · fast → `animate-shine-fast` |

Base clips a dim→bright→dim gradient to the text and reveals it with
`-webkit-text-fill-color: transparent`, over a real `text-dim` fallback color. The keyframe + utilities
were added to the theme layer via `scripts/build-tokens.ts` (emitted into the generated `theme.css`),
all with literal class names:

```css
@keyframes sk-shine {
  0%   { background-position: 200% center; }
  100% { background-position: -200% center; }
}
@utility animate-shine      { animation: sk-shine 3s linear infinite; }
@utility animate-shine-slow { animation: sk-shine 6s linear infinite; }
@utility animate-shine-fast { animation: sk-shine 1.6s linear infinite; }
```

No new **color** token needed — the band is built from `--sk-text-dim` (base) and `--sk-text`
(highlight). Durations are the proposed values in owner question Q13 (tunable, patch pre-1.0).

## States

| State | Behavior |
|---|---|
| default | light band sweeps across the text on a loop (linear). |
| prefers-reduced-motion | `motion-reduce:animate-none` — the sheen freezes; the dimmed base text stays fully legible. |

## Accessibility

- [ ] Real, selectable text — the sheen is `aria`-neutral decoration, not content.
- [ ] `prefers-reduced-motion` freezes the animation (`motion-reduce:animate-none`); verified in a
      browser test alongside the other reduced-motion components.
- [ ] The resting/base color is `text-dim`, which clears 4.5:1 on `--sk-bg`/`--sk-surface` in both
      themes — text is never below-contrast when the band isn't over it.
- [ ] `-webkit-background-clip: text` prefix included; solid `text-dim` shows if clip is unsupported.
- [ ] No flashing faster than 3/s (WCAG 2.3.1) — the slowest visible cycle is the sweep, not a flash.

---

# Skeleton — sukuna-ui

> A placeholder shimmer shown while content loads.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Skeleton } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/skeleton · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-skeleton.md

## Purpose

A placeholder shimmer shown while content loads.

## API

```ts
import type { ComponentPropsWithoutRef } from 'react'

export interface SkeletonProps extends ComponentPropsWithoutRef<'div'> {
  variant?: 'text' | 'rectangular' | 'circular'   // default 'rectangular'
  // size comes from your className/style (e.g. className="h-4 w-40")
}
```

## Variants & tokens

Base: `animate-pulse bg-surface-2`. text → `rounded-sm h-[1em]`; rectangular → `rounded-md`;
circular → `rounded-full`.

## States

Static; always pulsing while mounted.

## Accessibility

- [ ] Decorative (`aria-hidden`); convey loading via a container `aria-busy`/`role="status"`.

---

# Slider — sukuna-ui

> Pick a number from a range by dragging or with the keyboard.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Slider } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/slider · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-slider.md

## Purpose

Pick a number from a range by dragging or with the keyboard.

## API

```ts
export interface SliderProps {
  value?: number
  defaultValue?: number
  onValueChange?: (value: number) => void
  min?: number     // default 0
  max?: number     // default 100
  step?: number    // default 1
  disabled?: boolean
  className?: string
  'aria-label'?: string
}
```

## Variants & tokens

track: `h-1.5 w-full rounded-pill bg-surface-2`; indicator: `bg-accent rounded-pill` (Base UI sizes
it); thumb: `size-4 rounded-full bg-text border border-line focus-visible:ring-2
focus-visible:ring-accent-glow`; disabled → `opacity-45`.

## States

default · dragging · focus-visible ring on thumb · disabled.

## Accessibility

- [ ] Thumb exposes `role="slider"` + `aria-valuenow/min/max` (Base UI); give an `aria-label`.
- [ ] Arrow keys adjust by `step`; Home/End jump to min/max.
- [ ] Disabled sliders are not focusable.

---

# Spinner — sukuna-ui

> An indeterminate loading indicator (CSS spin).

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Spinner } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/spinner · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-spinner.md

## Purpose

An indeterminate loading indicator (CSS spin).

## API

```ts
import type { ComponentPropsWithoutRef } from 'react'

export interface SpinnerProps extends Omit<ComponentPropsWithoutRef<'span'>, 'children'> {
  size?: 'sm' | 'md' | 'lg'   // default 'md'
  label?: string              // accessible name, default 'Loading'
}
```

## Variants & tokens

Wrapper: `inline-flex text-accent` (crimson by default; override via `className`). SVG:
`animate-spin` + size sm `size-4` / md `size-5` / lg `size-6`; strokes use `currentColor`.

## States

Static; always spinning while mounted.

## Accessibility

- [ ] `role="status"` + `aria-label` announces loading; the SVG is `aria-hidden`.
- [ ] Motion is decorative; respect reduced-motion at the app level if needed.

---

# Stepper — sukuna-ui

> Show progress through an ordered sequence of steps.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Stepper } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/stepper · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-stepper.md

## Purpose

Show progress through an ordered sequence of steps.

## API

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

export interface Step { label: ReactNode; description?: ReactNode }

export interface StepperProps extends Omit<ComponentPropsWithoutRef<'ol'>, 'children'> {
  steps: Step[]
  activeStep: number   // 0-based index of the current step
  orientation?: 'horizontal' | 'vertical'   // default 'horizontal'
}
```

## Variants & tokens

indicator by state: completed `bg-accent text-text border-accent` (check); current
`border-accent text-accent` + ring; upcoming `border-line text-text-faint`. connector: completed →
`bg-accent`, else `bg-line`. label: current/completed `text-text`, upcoming `text-text-dim`.

## States

per step: completed (`index < activeStep`) · current (`=== activeStep`, `aria-current="step"`) ·
upcoming (`> activeStep`).

## Accessibility

- [ ] Ordered list; current step `aria-current="step"`.
- [ ] Completed/current conveyed by more than color (check icon + number + text weight).
- [ ] Give the list an `aria-label` (e.g. "Progress").

---

# Switch — sukuna-ui

> An on/off toggle for an immediate setting (not form submission).

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Switch } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/switch · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-switch.md

## Purpose

An on/off toggle for an immediate setting (not form submission). There is no native switch element,
so it's a `<button role="switch">` with a sliding thumb; keyboard and semantics come from the button.

## API

```ts
import type { ComponentPropsWithoutRef } from 'react'

type Native = Omit<ComponentPropsWithoutRef<'button'>, 'type' | 'onClick' | 'value' | 'role' | 'aria-checked'>

export interface SwitchProps extends Native {
  size?: 'sm' | 'md'                    // default 'md'
  checked?: boolean
  defaultChecked?: boolean              // default false
  onCheckedChange?: (checked: boolean) => void
}
```

Toggle via `onCheckedChange`. Uncontrolled + controlled through `useControllableState`. Give it an
accessible name (`aria-label` / `aria-labelledby`).

## Variants & tokens

Slots — `root` (the track/button) and `thumb`:

- root base: `group relative inline-flex items-center rounded-pill p-0.5 border border-line bg-surface-2 transition-colors duration-fast ease-sukuna cursor-pointer aria-checked:bg-gradient-accent aria-checked:border-transparent disabled:opacity-45 disabled:cursor-not-allowed focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-glow focus-visible:ring-offset-2 focus-visible:ring-offset-bg`
- thumb base: `inline-block rounded-full bg-text transition-transform duration-fast ease-sukuna`

| size | root | thumb |
|---|---|---|
| sm | `h-5 w-9` | `size-4 group-aria-checked:translate-x-4` |
| md | `h-6 w-11` | `size-5 group-aria-checked:translate-x-5` |

The thumb slides via `group-aria-checked` reading the track's `aria-checked`.

## States

off · on (crimson gradient track, thumb slid right) · focus-visible (accent-glow ring) ·
disabled (opacity .45, not-allowed).

## Accessibility

- [ ] `role="switch"` with `aria-checked` reflecting state (set by the component).
- [ ] Accessible name required (`aria-label`/`aria-labelledby`) — no visible label is rendered.
- [ ] Space and Enter toggle (native button).
- [ ] Focus ring ≥ 3:1 against the surface in both themes.
- [ ] Thumb is decorative (`aria-hidden`).

---

# Table — sukuna-ui

> Present tabular data with Sukuna styling.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Table } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/table · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-table.md

## Purpose

Present tabular data with Sukuna styling. Composition over configuration; sorting/selection/
virtualization are out of scope (use a data-grid library for those).

## API

```ts
export const Table: ForwardRefExoticComponent<TableProps> & {
  Header, Body, Row, HeaderCell, Cell   // thin styled wrappers over thead/tbody/tr/th/td
  ActionsHeaderCell, ActionsCell        // v1.3 — the actions column (see component-row-actions.md)
}
```

```tsx
<Table>
  <Table.Header><Table.Row><Table.HeaderCell>Name</Table.HeaderCell></Table.Row></Table.Header>
  <Table.Body><Table.Row><Table.Cell>Ariel</Table.Cell></Table.Row></Table.Body>
</Table>
```

**Actions column (v1.3).** `Table.ActionsHeaderCell` is a `th` (`w-px text-right`) whose default
content is a visually hidden "Actions" (`sr-only`) so the column keeps an accessible name; pass
children to replace it. `Table.ActionsCell` is a `td` (`w-px text-right whitespace-nowrap`) that
holds a `RowActions` (⋯ menu with icon options). Both stay static — the menu lives in
`RowActions`, so `Table` never imports Base UI and keeps its 2 kB budget.

## Variants & tokens

wrapper: `w-full overflow-x-auto` (horizontal scroll on small screens). table: `w-full border-collapse
text-sm text-text`. headerCell: `h-10 px-3 text-xs uppercase tracking-eyebrow text-text-dim border-b
border-line`. row: `border-b border-line`, `data-[interactive]:hover:bg-line-soft`. cell: `h-11 px-3`.

## States

Static. Rows can opt into a hover with `data-interactive`.

## Accessibility

- [ ] Real `<table>`/`<thead>`/`<th>` semantics (use `Table.HeaderCell` for headers).
- [ ] Add `scope="col"`/`scope="row"` on header cells where appropriate (native prop passthrough).
- [ ] The wrapper scrolls horizontally so the table never breaks the page layout.

---

# Tabs — sukuna-ui

> Switch between panels of related content.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Tabs } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/tabs · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-tabs.md

## Purpose

Switch between panels of related content. Roving focus + arrow-key navigation from Base UI.

## API

```ts
export interface TabItem { value: string; label: ReactNode; content: ReactNode; disabled?: boolean }

export interface TabsProps {
  items: TabItem[]
  value?: string
  defaultValue?: string
  onValueChange?: (value: string) => void
  'aria-label'?: string
  orientation?: 'horizontal' | 'vertical'   // v1.3 — default 'horizontal'
}
```

**Vertical (v1.3).** `orientation="vertical"` stacks the tabs in a left-hand column beside the
panel — settings pages, docs sections, sidebar navigation. Base UI switches the keys to
ArrowUp/ArrowDown and sets `aria-orientation="vertical"` on the tablist. Labels can hold an
icon + text (`gap-2`).

## Variants & tokens

list: `flex border-b border-line`. tab: `h-10 px-3 text-sm font-medium text-text-dim border-b-2 border-transparent -mb-px hover:text-text data-[selected]:text-text data-[selected]:border-accent focus-visible:ring-2 focus-visible:ring-accent-glow`. panel: `pt-4 text-text`.

Vertical: root `flex items-start gap-6`; list `flex-col shrink-0 min-w-44 border-r border-line`;
tab `w-full justify-start h-9 border-r-2 -mr-px rounded-l-sm`, selected also `bg-surface-2`;
panel `flex-1 min-w-0 pt-0`. Horizontal keeps the bottom underline (`border-b-2 -mb-px`).

## States

tab: default · hover · selected (accent underline) · focus-visible · disabled.

**Motion (v1.3, `docs/motion.md`):** the selected underline (vertical: right-edge bar) is a Base UI `Tabs.Indicator` that slides to the new tab (`ease-spring`, `duration-base`); the tab draws its own border until the indicator is measured (no-JS/SSR). Reduced motion: instant.

## Accessibility

- [ ] `role="tablist"`/`tab`/`tabpanel` wired by Base UI; give the list an `aria-label`.
- [ ] Arrow keys move between tabs (Left/Right horizontal, Up/Down vertical); Tab key moves to the panel.
- [ ] Vertical: tablist carries `aria-orientation="vertical"`.
- [ ] Selected tab is distinguishable by more than color (underline + text weight).

---

# Text — sukuna-ui

> The typographic primitive.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Text } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/text · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-text.md

## Purpose

The typographic primitive. Renders body copy, labels, eyebrows, and headings against the Sukuna
type scale, weights, tones, and tracking. One component so type stays consistent; `as` picks the
semantic element.

## API

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

export type TextElement =
  | 'p' | 'span' | 'div' | 'label' | 'strong' | 'em' | 'small'
  | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'

export interface TextProps extends Omit<ComponentPropsWithoutRef<'p'>, 'color'> {
  as?: TextElement          // default 'p'
  font?: 'sans' | 'display' // default 'sans'; 'display' = Archivo, for headlines
  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl'   // default 'md'
  weight?: 'regular' | 'semibold' | 'bold' | 'black'        // default 'regular'
  tone?: 'default' | 'dim' | 'faint' | 'accent' | 'success' | 'premium' // default 'default'
  align?: 'start' | 'center' | 'end'
  leading?: 'tight' | 'normal'      // default 'normal'
  tracking?: 'tight' | 'normal' | 'eyebrow'   // default 'normal'; 'eyebrow' also uppercases
  truncate?: boolean        // single-line ellipsis
  numeric?: boolean         // tabular-nums for aligned figures
}
```

`color` is omitted from the native props so it can't fight `tone`. `as` is a fixed allowlist of
intrinsic tags (not `asChild` polymorphism, which stays out of v1) — SSR-safe and enough for text.

## Variants & tokens

| Variant | Values → utility |
|---|---|
| font | sans → `font-sans` · display → `font-display` |
| size | xs/sm/md/lg/xl/2xl/3xl → `text-xs … text-3xl` (`--sk-text-*`) |
| weight | regular/semibold/bold/black → `font-normal/semibold/bold/black` (400/600/700/900) |
| tone | default `text-text` · dim `text-text-dim` · faint `text-text-faint` · accent `text-accent` · success `text-success` · premium `text-premium` |
| align | start/center/end → `text-start/center/end` |
| leading | tight `leading-tight` · normal `leading-normal` |
| tracking | tight/normal/eyebrow → `tracking-*`; eyebrow adds `uppercase` |
| truncate | true → `truncate` |
| numeric | true → `tabular-nums` |

## States

Static; no interactive states. It inherits nothing that changes on hover/focus.

## Accessibility

- [ ] Use real heading tags (`as="h2"`) for headings — never size alone to fake hierarchy.
- [ ] `tone="faint"` is for placeholder/disabled/decorative text; don't use it for essential body
      copy (it can fall below 4.5:1).
- [ ] `default`/`dim` tones meet 4.5:1 on `--sk-bg`/`--sk-surface` in both themes.
- [ ] `eyebrow` conveys style, not meaning; don't rely on uppercase to carry information.
- [ ] `label` usage associates with a control via `htmlFor`.

---

# Textarea — sukuna-ui

> Multi-line free text: comments, descriptions, messages.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Textarea } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/textarea · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-textarea.md

## Purpose

Multi-line free text: comments, descriptions, messages. Same surface, border, focus ring and
`invalid` treatment as `Input`, so forms look uniform, and it drops into `Field.Control` the same
way. Optional content-based auto-grow uses the CSS `field-sizing: content` property — no JS.

## API

```ts
import type { ComponentPropsWithoutRef } from 'react'

export interface TextareaProps extends ComponentPropsWithoutRef<'textarea'> {
  size?: 'sm' | 'md' | 'lg'                  // default 'md' — text size + padding, like Input
  invalid?: boolean                           // crimson border + aria-invalid
  resize?: 'none' | 'vertical' | 'both'       // default 'vertical'
  autoResize?: boolean                        // default false — grows with content (field-sizing)
}
```

`rows` stays native (default 3 via the attribute). `ref` → `HTMLTextAreaElement`.
Deliberately **not** in v1: a character counter (compose with `Field.Description`), JS auto-grow
for browsers without `field-sizing` (they keep a fixed, resizable box — graceful fallback).

## Variants & tokens

Base mirrors Input: `w-full bg-surface-2 text-text border border-line placeholder:text-text-faint`,
`focus-visible:ring-2 ring-focus-ring border-accent`, `disabled:opacity-45`.

| Size | Padding | Font | Radius | Min height |
|---|---|---|---|---|
| sm | `px-3 py-1.5` | `text-sm` | `rounded-sm` | 64px |
| md | `px-3 py-2` | `text-md` | `rounded-md` | 80px |
| lg | `px-4 py-3` | `text-lg` | `rounded-lg` | 96px |

resize: `resize-none` / `resize-y` / `resize`. autoResize: `[field-sizing:content]` (+ a
`max-h-80` cap so it never eats the page). invalid: `border-accent`. No new tokens.

## States

default · hover (none — text fields don't lift) · focus-visible (ring + crimson border) · invalid ·
disabled · readOnly (native). Reduced motion: only a color transition, no motion.

## Accessibility

- [ ] Native `<textarea>`; name from `<label htmlFor>`, `Field.Label` or `aria-label`.
- [ ] `invalid` → `aria-invalid="true"`; pair with `Field.Error` for the message.
- [ ] Focus ring ≥3:1 both themes; text/placeholder contrast per tokens.

---

# Toast — sukuna-ui

> Transient notifications.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { ToastProvider, useToast } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/toast · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-toast.md

## Purpose

Transient notifications. Wrap the app in `ToastProvider`; call `useToast().toast(...)` to show one.

## API

```ts
export interface ToastProviderProps { children: ReactNode; timeout?: number; limit?: number }
export function ToastProvider(props: ToastProviderProps): JSX.Element

export interface ToastOptions { title?: ReactNode; description?: ReactNode; type?: string }
export function useToast(): { toast: (options: ToastOptions) => string }  // returns the toast id
```

Usage:

```tsx
<ToastProvider><App /></ToastProvider>
// inside App:
const { toast } = useToast()
toast({ title: 'Saved', description: 'Your changes were saved.' })
```

## Variants & tokens

viewport: `fixed bottom-4 right-4 z-50 flex w-80 flex-col gap-2`. root: `rounded-md border border-line bg-surface p-4 shadow-card` + enter/exit slide/opacity. title `font-display font-bold text-sm`; description `text-sm text-text-dim`; close: top-right ghost button.

## States

enter (slide/fade in) · visible · auto-dismiss after `timeout` · close (button/swipe from Base UI).

**Motion (v1.3, `docs/motion.md`):** stacked deck — older toasts peek above the newest (scale −6% per step, content faded), fan out while hovered/focused, swipe right/down to dismiss (`duration-slow`). Reduced motion: instant.

## Accessibility

- [ ] Viewport is a labelled region; toasts announce politely (Base UI live region).
- [ ] Close button has `aria-label`; Escape/close supported.
- [ ] Auto-dismiss pauses on hover/focus (Base UI).

---

# ToggleGroup — sukuna-ui

> Pick one option from a small, mutually-exclusive set (segmented control), or toggle several independent options (a formatting toolbar).

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Toggle, ToggleGroup } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/toggle-group · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-toggle-group.md

## Purpose

Pick one option from a small, mutually-exclusive set (segmented control), or toggle several
independent options (a formatting toolbar). Roving focus, `aria-pressed`, and keyboard navigation
come from Base UI. Distinct from `RadioGroup` (which is for form values with labels/descriptions);
ToggleGroup is a compact button-style control, and `Toggle` is a single pressable button.

## API

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

export interface ToggleOption {
  value: string
  label: ReactNode
  disabled?: boolean
  'aria-label'?: string   // required when label is icon-only
}

interface ToggleGroupOwnProps {
  items: ToggleOption[]
  value?: string | string[]          // controlled; string in single mode, string[] in multiple
  defaultValue?: string | string[]
  onValueChange?: (value: string[]) => void   // always an array from Base UI
  multiple?: boolean                  // default false → single-select (segmented control)
  size?: 'sm' | 'md' | 'lg'           // default 'md'
  orientation?: 'horizontal' | 'vertical'  // default 'horizontal'
  disabled?: boolean
}

// A group needs an accessible name: pass aria-label or aria-labelledby.
export type ToggleGroupProps = ToggleGroupOwnProps &
  Omit<ComponentPropsWithoutRef<'div'>, 'onChange' | 'defaultValue' | 'dir'>

// Standalone single toggle button (e.g. a mute button). forwardRef to the <button>.
interface ToggleOwnProps {
  pressed?: boolean
  defaultPressed?: boolean
  onPressedChange?: (pressed: boolean) => void
  size?: 'sm' | 'md' | 'lg'
}
export type ToggleProps = ToggleOwnProps &
  Omit<ComponentPropsWithoutRef<'button'>, 'onChange' | 'value'>
```

Deliberately **not** in v1: `variant` styles beyond the single segmented look, and per-item icons +
text combos beyond what `label: ReactNode` already allows.

## Variants & tokens

root: `inline-flex rounded-md border border-line bg-surface-2 p-0.5 gap-0.5`
(`flex-col` when `orientation="vertical"`). item: `inline-flex items-center justify-center gap-2
rounded-sm text-text-dim font-medium select-none cursor-pointer transition-colors duration-fast
hover:text-text data-[pressed]:bg-well data-[pressed]:text-text
data-[disabled]:opacity-45 data-[disabled]:cursor-not-allowed
focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring`.

| Size | Item height | Padding-x | Font |
|---|---|---|---|
| sm | 28px | `px-2.5` | `text-sm` |
| md | 34px | `px-3` | `text-md` |
| lg | 40px | `px-4` | `text-lg` |

No new tokens — reuses `--sk-surface-2`, `--sk-line`, `--sk-well`, `--sk-focus-ring`, text tokens.

## States

default (unpressed) · hover · pressed (`data-[pressed]` → `--sk-well` fill) · focus-visible (ring) ·
disabled (per item or whole group).

## Accessibility

- [ ] Group requires `aria-label`/`aria-labelledby` (enforced in docs + a warning-free story).
- [ ] Items expose `aria-pressed`; roving `tabIndex` with Arrow keys (Base UI), Home/End jump.
- [ ] Icon-only items require `aria-label` (enforced on `ToggleOption`).
- [ ] Pressed vs unpressed distinguished by more than color (fill + text weight/contrast ≥3:1).
- [ ] Focus ring visible in both themes.

---

# Tooltip — sukuna-ui

> A hover/focus tooltip for supplementary text.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { Tooltip } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/tooltip · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-tooltip.md

## Purpose

A hover/focus tooltip for supplementary text. Behavior (delay, positioning, dismiss, a11y wiring)
comes from Base UI (`@base-ui/react/tooltip`); we style the popup.

## API

```ts
import type { ReactElement, ReactNode } from 'react'

export interface TooltipProps {
  children: ReactElement          // the trigger (an element; Base UI merges trigger props onto it)
  content: ReactNode              // tooltip body
  side?: 'top' | 'right' | 'bottom' | 'left'   // default 'top'
  align?: 'start' | 'center' | 'end'           // default 'center'
  sideOffset?: number             // default 8
  delay?: number                  // open delay ms; default 300 (focus opens instantly)
  open?: boolean                  // controlled
  defaultOpen?: boolean
  onOpenChange?: (open: boolean) => void
}
```

A composition wrapper (not `forwardRef`): the ref belongs on the trigger element you pass as
`children`.

## Variants & tokens

Popup: `z-40 max-w-xs rounded-md border border-line bg-surface-2 text-text px-2.5 py-1.5 text-sm shadow-card select-none` + enter/exit transition via Base UI `data-[starting-style]`/`data-[ending-style]`. `z-40` = `--sk-z-tooltip`.

## States

closed (nothing rendered) · open (popup, positioned by Base UI) · enter/leave transitions.

**Motion (v1.3, `docs/motion.md`):** directional entrance — fade + scale 95→100% + a 4px slide from the trigger side (`data-side`). Reduced motion: instant.

## Accessibility

- [ ] Popup wired as the trigger's description by Base UI; content is supplementary, not essential.
- [ ] Opens on hover AND keyboard focus; dismiss on Escape / blur (Base UI).
- [ ] Not a replacement for a label; don't put interactive content inside a tooltip.

---

# VideoPlayer — sukuna-ui

> Plays a single video with Sukuna-branded controls instead of each browser's native chrome, so video looks the same in Chrome, Safari and Firefox and matches the rest of the library.

- **Package:** `sukuna-ui` — `bun add sukuna-ui` (or `npm i sukuna-ui`)
- **Import:** `import { useVideoPlayer, VideoPlayer, VideoPlayerAudio, VideoPlayerEndScreen, VideoPlayerOverlay, VideoPlayerPanel, VideoPlayerPlaylist, VideoPlayerShare, VideoPlayerSkip, VideoPlayerUpNext } from 'sukuna-ui'`
- **Styles:** `@import "sukuna-ui/theme.css"` (Tailwind v4) or `import "sukuna-ui/styles.css"` (no Tailwind) — see [Getting started](https://raw.githubusercontent.com/arielplas/sukuna-ui/main/llms.txt)
- **Source:** https://github.com/arielplas/sukuna-ui/tree/main/src/components/video-player · **Spec:** https://github.com/arielplas/sukuna-ui/blob/main/docs/component-video-player.md

## Purpose

Plays a single video with Sukuna-branded controls instead of each browser's native chrome, so video
looks the same in Chrome, Safari and Firefox and matches the rest of the library. It covers the
basics people expect from any player — play/pause, seek, time, volume, speed, captions,
picture-in-picture, fullscreen and keyboard shortcuts — and, per owner request Q22, the feature set
of the Nuevo plugin for Video.js: chapters, preview thumbnails, quality, playlists, transcript,
end screens, share, overlays, live, ads, cast and more.

Three tiers keep that from becoming one heavy component:

- **Tier 1 — core** (in `VideoPlayer`): everything a viewer expects on every video.
- **Tier 2 — parts** (separate named exports rendered as children): opt-in features; unused parts
  are tree-shaken.
- **Tier 3 — adapters** (subpath entries, vendor SDK as an optional peer): streaming engines, ads,
  Cast, DRM, VR. We ship the interface and all the chrome; the app installs the SDK.

## API

The root renders the frame, the `<video>` and all Tier 1 controls. **Children are parts** (Tier 2).
Media comes in through `src` / `sources` and `tracks` props (arrays, like Nuevo's playlist items),
because the player must know resolutions, chapters and thumbnails up front, and playlist items reuse
the same shape. Tracks are fetched and rendered by the player (not the browser's `::cue`), which is
what makes caption styling, the transcript and chapter segments possible; `<track>` children are
therefore not used.

```ts
import type { ComponentPropsWithoutRef, ReactNode } from 'react'

interface VideoPlayerProps extends Omit<ComponentPropsWithoutRef<'video'>, 'controls'> {
  title?: string                    // shown top-left while controls are visible; also names the region
  'aria-label'?: string             // region name when there is no `title`; one of the two is required
  aspectRatio?: '16/9' | '4/3' | '1/1' | '21/9' | '9/16'   // default '16/9'; literal classes, no interpolation
  playbackRates?: number[]          // speed menu entries; default [0.5, 0.75, 1, 1.25, 1.5, 2]
  autoHide?: boolean                // hide controls after 2.5s idle while playing; default true
  hotkeys?: boolean                 // keyboard shortcuts while focus is inside the player; default true
  children?: ReactNode              // parts (Tier 2) and useVideoPlayer() consumers

  // ── Tier 1 additions (Q22) — shipped in W1 ──
  sources?: VideoSource[]           // { src, type?, res?: number | 'SD' | 'HD', label?, default? } → quality menu
  tracks?: VideoTrack[]             // { kind: 'captions'|'subtitles'|'chapters', src, srclang?, label?, default? }
  chapters?: Chapter[]              // { start, title, thumb? } — alternative to a chapters VTT
  thumbnails?: string | ThumbnailCue[]   // sprite VTT url (#xywh=) or explicit cues → hover preview
  startTime?: number                // seconds
  logo?: { src: string; alt: string; href?: string }   // watermark, top-right
  info?: ReactNode                  // line under the title (series, episode…)
  skipSeconds?: number              // rewind/forward buttons + J/L; default 10
  frameRate?: number                // for , / . frame stepping; default 24
  settings?: Array<'quality' | 'speed' | 'captions' | 'picture' | 'sleep' | 'loop' | 'snapshot' | 'download'>
                                    // gear rows; default ['quality', 'speed', 'captions']
  contextMenu?: boolean             // default true
  touchControls?: boolean           // back/play/forward row + double-tap seek on coarse pointers; default true
  autoplayPolicy?: 'muted' | 'none' // 'muted' → autoplay muted + "Tap to unmute" chip; default 'none'
  labels?: Partial<VideoPlayerLabels>   // every visible and aria string (i18n)

  // ── Tier 2 behaviours that are only props — W2/W3 ──
  resume?: string                   // storage key; restores position, shows the Resume prompt (W2)
  watchLimit?: { seconds: number; content: ReactNode }   // stop + cover at the limit; seeking past it blocked (W3)
  syncGroup?: string                // players in the same group pause each other
  floating?: boolean                // dock to a corner when scrolled out of view
  theater?: boolean                 // controlled; also defaultTheater. The app owns layout; we own the button + T key (W2)
  onTheaterChange?: (on: boolean) => void
  live?: boolean | { dvrWindow?: number }   // LIVE pill, DVR seek, "jump to live" (W3)
  download?: string | { src: string; filename?: string }   // gear → Download (W3)
  onSnapshot?: (image: Blob, time: number) => void         // gear → Snapshot; else a PNG download (W3)

  // ── Tier 3 seams — W4 ──
  engine?: VideoEngine              // shipped: { name, handles(src), attach(video, src, callbacks) → { setLevel, destroy } }
                                    // hlsEngine() from 'sukuna-ui/video/hls'; dash.js / Shaka / DRM next (Q26)
  ads?: AdAdapter                   // Q26: VAST / VMAP / IMA / DAI → our ad chrome
  cast?: CastAdapter                // Q26: Chromecast (AirPlay is native, Tier 1)
  renderer?: Renderer               // Q26: e.g. VR/360 WebGL canvas
  onAnalytics?: (e: PlayerEvent) => void   // Q26: one normalized event stream for any tracker

  // ── events ──
  onChapterChange?: (chapter: Chapter, index: number) => void
  onQualityChange?: (source: VideoSource) => void
}
```

**Parts** (Tier 2) are separate named exports so unused ones tree-shake (approved, Q23). A part
registers itself through the context registry; the core then shows its buttons (list, share,
previous/next) and hotkeys.

| Export | Renders | Key props |
|---|---|---|
| `VideoPlayerPanel` | right-side drawer with tabs: chapters list (thumbs, durations), playlist, transcript | `tabs`, `defaultOpen` |
| `VideoPlayerPlaylist` | renders nothing; the current item's media drives the player; prev/next buttons; `Shift+N/P`; auto-advance | `items`, `index` / `defaultIndex`, `onIndexChange`, `autoAdvance` (true), `repeat`, `rememberKey` |
| `VideoPlayerUpNext` | countdown card for the playlist's next item; Cancel stops auto-advance | `countdown` (default 10) |
| `VideoPlayerEndScreen` | replay, share (when `VideoPlayerShare` is mounted), related grid (links or buttons) | `related` |
| `VideoPlayerShare` | link (optionally at current time), embed code; opened from the top-right share button | `url`, `embed` |
| `VideoPlayerSkip` | "Skip intro" / "Skip recap" button for a time range | `start`, `end`, `label` |
| `VideoPlayerOverlay` (W3) | timed card / banner / plain content; `showOn="pause"` for a banner on pause; dismissible. News-ticker variant waits on Q25 | `aria-label`, `start`, `end`, `showOn`, `variant`, `placement`, `dismissible` |
| `VideoPlayerAudio` (W3) | audio mode: cover art (or initials tile), title, artist, Web Audio frequency visualizer | `art`, `title`, `artist`, `visualizer` |

`useVideoPlayer()` exposes state and actions (`play`, `seek`, `setQuality`, `chapters`, …) so apps
can build their own parts or a fully chromeless UI (Nuevo's "chromeless player" demo).

- **`ref` → the `<video>` element**, so consumers can call `play()`, read `currentTime`, etc.
- Every native media prop and event (`src`, `poster`, `autoPlay`, `muted`, `loop`, `preload`,
  `playsInline`, `onPlay`, `onTimeUpdate`, `onRateChange`, …) passes straight to `<video>`.
- `className` and `style` go to the **root frame** (layout: width, max-width, margins); everything
  else goes to `<video>`. `// DECISION(open): className → root` (a video-level class has no use when
  the player owns the chrome).
- `controls` is omitted: the native chrome is always off; ours replaces it.
- Type-level: `title` or `aria-label` is required (same overload trick as icon-only Button).

**Not planned** (Q22 recommendation): VPAID (runs third-party JS in the page; IAB-deprecated),
YouTube tech (iframe; can't be styled), automatic subtitle translation (needs a translation
service), Nuevo's WordPress plugin and dev tools (stream tester, sprite generator).

## Variants & tokens

**The player chrome is always dark.** The root sets `data-theme="dark"`, so every `--sk-*` token
inside it resolves to the dark palette even in a light app. Video frames are dark-dominant and the
controls sit on a black scrim; light-theme text (`#141413`) would be unreadable there. No new tokens.
The focus ring (`--sk-focus-ring`) stays crimson in both.

| Slot | Utilities → tokens |
|---|---|
| root | `@container relative overflow-hidden rounded-lg bg-well shadow-card` · `--sk-radius-lg`, `--sk-well` (#000), `--sk-shadow-card` |
| video | `size-full object-contain` |
| scrim (bottom) | `bg-linear-to-t from-well/85 via-well/40 to-transparent`, ~45% of height |
| scrim (top, with `title`) | `bg-linear-to-b from-well/70 to-transparent`, ~25% of height |
| title | `font-display font-bold tracking-tight text-lg text-text`, truncates |
| bigPlay | 64px circle, `bg-gradient-accent text-on-accent` + `shadow-[0_0_28px_6px_var(--sk-accent-glow)]` — the one crimson primary on the surface |
| controlButton | 36px square (`size-9 rounded-md`), `text-text hover:bg-line-soft`, 20px icon — ghost icon Button look |
| time | `font-sans text-sm tabular-nums text-text` + `text-text-dim` for the duration |
| seek track | 4px → 6px on hover/drag, `rounded-pill bg-text/20` |
| seek buffered | `bg-text/35` (inline `width` %, positional) |
| seek played | `bg-accent` (`--sk-accent`) |
| seek thumb | 14px `bg-accent`, `ring-4 ring-accent-glow` on drag; scales in on hover (`scale-0 → scale-100`) |
| seek hover time | small chip `bg-surface-2 border border-line rounded-sm text-xs tabular-nums` above the pointer |
| volume slider | 72px track, same as seek but `bg-text` fill (volume isn't a brand moment); expands from `w-0` on hover/focus of the mute group |
| settings menu | in-house paged menu (`role="menu"`), `bg-surface/95 border-line rounded-md shadow-card`; radio rows show a crimson tick |
| spinner | our `Spinner` (lg) centered while `waiting` |
| error panel | centered `text-text` message + `text-text-dim` detail, `Retry` secondary Button |

**Q22 additions** (all existing tokens):

| Slot | Utilities → tokens |
|---|---|
| seek segments (chapters) | one `seg` per chapter, `gap-[3px]`, each `rounded-pill bg-text/20`; hovered segment `h-2`; played `bg-accent` per segment |
| thumbnail preview | 160×90 frame `rounded-sm shadow-card`, chapter title (`font-display font-bold text-sm`) above, time chip below |
| chapter label | beside the time: `· Chapter name ›` `text-sm`, truncates; opens the panel |
| settings menu | `bg-surface/95 border-line rounded-md shadow-card`, 260px; rows show current value in `text-text-dim` + chevron; sub-pages have a back header; toggles use our Switch look; chips use `border-accent bg-accent/14` when checked |
| side panel | `w-[min(340px,44%)]` right drawer, `bg-surface/95 backdrop-blur`, tabs with crimson underline (Tabs look); current item `bg-accent/10` + 3px crimson left rail; slides with `translate` `duration-slow` |
| skip intro / resume / up next | floating cards `bg-surface/95 border-line rounded-md`; ride above the bar and drop to the edge when controls hide; up-next countdown ring stroke `--sk-accent` |
| end screen / share / watch limit | full-frame cover `bg-well/70 backdrop-blur-sm`; primary action is the crimson Button, the rest secondary |
| loop range | `border-x-2 border-premium bg-premium/15` over the bar |
| ad chrome | `AD` badge `bg-premium text-bg`, pod position + countdown, "Skip in 5" → "Skip ad" tab on the right edge; ad progress `bg-premium` |
| live | `LIVE` pill: dot `bg-accent` pulsing at the live edge (static under reduced motion), `text-text-dim` when behind + `−0:42` |
| context menu | Menu popup look at the pointer |
| touch row | 48px round back/forward (`bg-well/45`) around the 64px crimson play; double-tap flashes a side ripple with "+10 seconds" |

Aspect ratio: `aspect-video` / `aspect-[4/3]` / `aspect-square` / `aspect-[21/9]` / `aspect-[9/16]`
as literal `tv()` variant strings.

**Compact layout** (container < 480px, `@max-[30rem]:` literal): 32px buttons, volume slider and PiP
hidden (mute stays), time shows `current / duration` in `text-xs`, bigPlay 52px. No JS measuring.

## States

| State | Behavior |
|---|---|
| idle (not started) | poster (or first frame) + big crimson play button centered; bottom bar visible; title visible. |
| playing | big play hides; controls fade out after 2.5s without pointer movement (`autoHide`); cursor hides with them. |
| controls shown | pointer move, touch, or keyboard focus inside the player; stays shown while paused, while a menu is open, while dragging, and while focus is in the control bar. |
| paused | pause icon → play icon; controls pinned; big play does **not** return (it's a start affordance only). |
| waiting / buffering | centered Spinner after a 200ms delay (no flash on quick seeks); controls stay usable. |
| seeking (drag) | segments grow to 5px (hovered chapter 8px), thumb shown with glow, preview follows the pointer, video scrubs live. |
| ended | play icon becomes **replay**; controls pinned. |
| muted / volume 0 | volume icon shows the muted glyph; unmuting restores the previous level (min 0.1). |
| captions on | CC button `aria-pressed="true"` + a 2px crimson underline; only rendered when the video has ≥1 `captions`/`subtitles` track. |
| picture-in-picture | PiP button `aria-pressed`; `I` toggles. Hidden where unsupported (Firefox). |
| fullscreen | root goes fullscreen (not the `<video>`, so our controls come too); icon flips to exit. iOS Safari falls back to `video.webkitEnterFullscreen()` (native chrome there). |
| error | video `error` → error panel with the media error in plain words ("This video couldn't be loaded. Check the link or your connection.") + Retry (`load()`). |
| focus-visible | solid `--sk-focus-ring` on every control; the root gets a ring when focused directly. |
| reduced motion | controls hide/show instantly (no fade); thumb appears without scale; no glow pulse. |

**Motion (`docs/motion.md`):** controls fade (`opacity`, `duration-base`); seek track height and
thumb `scale` (`duration-fast`, listed explicitly — rule 3); volume slider width expand
(`duration-base ease-sukuna`). All with `motion-reduce:` fallbacks.

## Accessibility

- [x] Root: labelled `<section>` (role `region`) named by `title` or `aria-label`; `aria-roledescription="video player"`; focusable (`tabIndex={0}`) so hotkeys work after a click.
- [x] Every control is a native `<button>` with an `aria-label` that says what happens now ("Play", "Pause", "Mute", "Unmute", "Enter fullscreen", "Turn on captions"); icons `aria-hidden`.
- [x] Toggle buttons (captions, PiP) use `aria-pressed`; play/mute/fullscreen swap their label instead (the action changes).
- [x] Seek and volume are `role="slider"` with `aria-label` ("Seek", "Volume") and spoken `aria-valuetext` (seek includes the chapter).
- [x] Settings: gear `aria-haspopup="menu"` + `aria-expanded`; pages are `role="menu"`, choices `menuitemradio` + `aria-checked`; caption-style chips are named "Size: Large".
- [x] Controls never hide while focus is inside them (WCAG 2.4.7/2.4.11 — focus stays visible).
- [x] Hotkeys only fire with focus inside the player and never steal keys from sliders, menus or text inputs; `?` opens a shortcuts sheet (`role="dialog"`, focus on Close, Escape closes).
- [x] Buffering spinner: `role="status"` + "Loading"; error panel: `role="alert"`.
- [ ] Contrast (owner visual pass): control icons `--sk-text` on the scrim ≥ 4.5:1 over a bright frame; crimson played bar ≥ 3:1 against the `bg-text/20` track.
- [x] Autoplay is the consumer's choice; `autoplayPolicy="muted"` is the only autoplay mode and always shows "Tap to unmute". Caption tracks are the consumer's responsibility (WCAG 1.2.2).
- [x] Touch targets ≥ 32px in compact, 36px otherwise; touch row 48px.

---

# Design tokens

# Tokens — Sukuna → `--sk-*`

Source: Pomo Design System (Sukuna language). Dark is the default theme. Light palette **approved by owner 2026-09-16**.

## Color (semantic)

| Token | Dark (source) | Light (proposed) | Use |
|---|---|---|---|
| `--sk-bg` | `#0A0A0B` (ink) | `#FAF9F5` | Page canvas |
| `--sk-surface` | `#141416` (panel) | `#FFFFFF` | Cards, dialogs |
| `--sk-surface-2` | `#1C1C20` (panel2) | `#F1EFE9` | Nested surfaces, inputs |
| `--sk-well` | `#000000` | `#E8E5DD` | Sunken areas |
| `--sk-line` | `rgba(255,255,255,.10)` | `rgba(0,0,0,.12)` | Borders |
| `--sk-line-soft` | `rgba(255,255,255,.06)` | `rgba(0,0,0,.06)` | Dividers |
| `--sk-accent` | `#FF3B4E` (crimson) | `#D8253A` | Primary action, "live" |
| `--sk-accent-deep` | `#B01221` | `#9A0E1C` | Hover/pressed accent |
| `--sk-accent-glow` | `rgba(255,59,78,.6)` | `rgba(216,37,58,.35)` | Decorative glow shadow (not the focus ring) |
| `--sk-focus-ring` | `#FF3B4E` | `#D8253A` | Solid focus ring (≥3:1 on every surface, WCAG 1.4.11) |
| `--sk-on-accent` | `#FFFFFF` | `#FFFFFF` | Text/icons on the crimson accent/gradient (Button primary) |
| `--sk-premium` | `#E8DCC4` (bone) | `#786A4A` | Premium / gold surfaces |
| `--sk-premium-dim` | `#B5A98C` | `#776A48` | Premium secondary |
| `--sk-text` | `#F4F1EC` | `#141413` | Primary text |
| `--sk-text-dim` | `#9A948A` | `#5E5A52` | Secondary text |
| `--sk-text-faint` | `#8C8479` | `#6F6B63` | Placeholders, disabled |
| `--sk-success` | `#31C877` | `#177B46` | Done / positive |

> **Contrast floor.** Every color used as text must clear WCAG AA — 4.5:1 (normal) / 3:1 (large or
> non-text UI) — on `bg`, `surface` and `surface-2` in **both** themes. `text-faint` (both themes)
> and light-theme `premium`/`premium-dim`/`success` were retuned to meet this (see D22). The focus
> ring uses the solid `--sk-focus-ring`, not the translucent `--sk-accent-glow` (which failed 3:1).
> Verify with `scratchpad` contrast script when changing any color token.
| `--sk-gradient-accent` | `linear-gradient(135deg,#D8253A,#B01221)` | `linear-gradient(135deg,#D8253A,#9A0E1C)` | Wordmark, hero CTA, Button primary |

## Typography

| Token | Value |
|---|---|
| `--sk-font-sans` | `-apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", Arial, sans-serif` |
| `--sk-font-display` | `"Archivo", var(--sk-font-sans)` — library does NOT bundle the font; document `@import` / `next/font` for consumers |
| `--sk-text-xs / sm / md / lg / xl / 2xl / 3xl` | `11 / 12 / 14 / 16 / 18 / 24 / 34 px` |
| `--sk-weight-regular / semibold / bold / black` | `400 / 600 / 700 / 900` |
| `--sk-tracking-tight / normal / eyebrow` | `-0.02em / 0 / 0.22em` |
| `--sk-leading-tight / normal` | `1.02 / 1.5` |
| Numerals | `font-variant-numeric: tabular-nums` on numeric Text variant |

## Spacing, radius, shadow, motion

| Group | Tokens |
|---|---|
| Space | `--sk-space-1..8` = `4 6 8 12 16 20 24 32 px` |
| Radius | `--sk-radius-sm 8px`, `--sk-radius-md 12px`, `--sk-radius-lg 16px`, `--sk-radius-pill 999px` |
| Shadow | `--sk-shadow-card: 0 30px 60px -24px rgba(0,0,0,.9), 0 0 0 1px rgba(255,255,255,.06)` (dark) / light **proposed** `0 20px 40px -24px rgba(0,0,0,.25), 0 0 0 1px rgba(0,0,0,.06)` — pending owner approval, see `questions.md` Q12 |
| Motion | `--sk-duration-fast 120ms`, `--sk-duration-base 200ms`, `--sk-duration-slow 320ms` (v1.3), `--sk-ease: cubic-bezier(.2,.8,.2,1)`, `--sk-ease-spring: linear(…)` (v1.3, ≈2% overshoot) — see `docs/motion.md` |
| Z-index | `--sk-z-tooltip 40`, `--sk-z-dialog 50` |

## Theme wiring (Tailwind v4)

`src/styles/theme.css`, shipped as `sukuna-ui/theme.css`:

```css
:root, [data-theme="dark"]  { --sk-bg: #0A0A0B; --sk-surface: #141416; /* ... */ }
[data-theme="light"]        { --sk-bg: #FAF9F5; --sk-surface: #FFFFFF; /* ... */ }

@theme inline {
  --color-bg: var(--sk-bg);
  --color-surface: var(--sk-surface);
  --color-surface-2: var(--sk-surface-2);
  --color-accent: var(--sk-accent);
  --color-text: var(--sk-text);
  /* one line per semantic color */
  --font-display: var(--sk-font-display);
  --radius-sm: var(--sk-radius-sm);
  --ease-sukuna: var(--sk-ease);
  --duration-fast: var(--sk-duration-fast);
}

@utility bg-gradient-accent { background-image: var(--sk-gradient-accent); }
```

`@theme inline` keeps the utility pointing at the runtime variable, so `data-theme` switches colors without Tailwind's `dark:` variant. Consumers override by redefining any `--sk-*` under their own selector, exactly as before.
