ranui 0.1.10-alpha.9 → 0.2.0-alpha.0

package/docs/COMPONENTS.md

@@ -0,0 +1,326 @@
+# ranui Component API (Generated)
+
+Auto-generated by `bin/generate-component-api.ts` (`npm run doc:api`).
+Per-element reference of attributes, typed properties, events (with `detail`
+shape), slots, and `::part()` names — extracted from source. For CSS variables
+(theming tokens) see [style-tokens-public.md](./style-tokens-public.md); for
+design rules see [DESIGN.md](./DESIGN.md).
+
+Generated at: 2026-07-04T08:44:03.975Z
+
+29 custom elements.
+
+## `<r-button>`
+
+Source: `components/button/index.ts`
+
+- **Attributes**: `disabled: boolean | string`, `effect: string`, `icon: string`, `iconSize: string`, `sheet: string`, `type: string`
+- **Properties**:
+  - `disabled: boolean | string`
+  - `effect: string`
+  - `icon: string`
+  - `iconSize: string`
+  - `sheet: string`
+  - `type: string` — Visual variant: `''` (default) | `'primary'` | `'warning'` | `'text'`. Drives the `:host([type=...])` styles.
+- **Events**: —
+- **Slots**: `default`
+- **Parts**: `button`, `content`
+
+## `<r-card>`
+
+Source: `components/card/index.ts`
+
+- **Attributes**: `description: string`, `sheet: string`, `title: string`
+- **Properties**: `description: string`, `sheet: string`, `title: string`
+- **Events**: —
+- **Slots**: `default`, `extra (named)`, `footer (named)`
+- **Parts**: `body`, `card`, `description`, `extra`, `footer`, `header`, `title`
+
+## `<r-checkbox>`
+
+Source: `components/checkbox/index.ts`
+
+- **Attributes**: `checked: boolean`, `disabled: boolean`, `sheet: string`, `value: string`
+- **Properties**: `checked: boolean`, `disabled: boolean`, `sheet: string`, `value: string`
+- **Events**: `change` → detail `{ checked }`
+- **Slots**: `default`
+- **Parts**: `checkbox`, `inner`, `input`, `label`, `wrapper`
+
+## `<r-colorpicker>`
+
+Source: `components/colorpicker/index.ts`
+
+- **Attributes**: `disabled`, `sheet: string`, `value: string`
+- **Properties**: `sheet: string`, `value: string`
+- **Events**: `change`
+- **Slots**: —
+- **Parts**: `block`, `swatch`
+
+## `<r-content>`
+
+Source: `components/popover/content/index.ts`
+
+- **Attributes**: —
+- **Properties**: —
+- **Events**: `change`
+- **Slots**: `default`
+- **Parts**: —
+
+## `<r-dropdown>`
+
+Source: `components/dropdown/index.ts`
+
+- **Attributes**: `arrow: string`, `sheet: string`, `transit: string`
+- **Properties**: `arrow: string`, `sheet: string`, `show: string`, `transit: string`
+- **Events**: —
+- **Slots**: `default`
+- **Parts**: `dropdown`
+
+## `<r-dropdown-item>`
+
+Source: `components/select/dropdown-item/index.ts`
+
+- **Attributes**: `active: string`, `sheet: string`, `title: string`, `value: string`
+- **Properties**: `active: string`, `sheet: string`, `title: string`, `value: string`
+- **Events**: —
+- **Slots**: `default`
+- **Parts**: `content`, `item`
+
+## `<r-form>`
+
+Source: `components/form/index.ts`
+
+- **Attributes**: `sheet: string`
+- **Properties**: `sheet: string`, `value: string | null`
+- **Events**: —
+- **Slots**: `default`, `r-form_content (named)`
+- **Parts**: —
+
+## `<r-icon>`
+
+Source: `components/icon/index.ts`
+
+- **Attributes**: `aria-label`, `color: string`, `decorative: boolean`, `name: string`, `sheet: string`, `size: string`, `spin: boolean`
+- **Properties**: `ariaLabel: string`, `color: string`, `decorative: boolean`, `name: string`, `sheet: string`, `size: string`, `spin: boolean`
+- **Events**: `ranui-icon-registered` → detail `{ name }`
+- **Slots**: —
+- **Parts**: `ran-icon`
+
+## `<r-img>`
+
+Source: `components/image/index.ts`
+
+- **Attributes**: —
+- **Properties**:
+  - `alt` — Alternative text forwarded to the inner `<img>`. Defaults to `''` (empty),
+  - `fallback`
+  - `sheet`
+- **Events**: —
+- **Slots**: —
+- **Parts**: —
+
+## `<r-input>`
+
+Source: `components/input/index.ts`
+
+- **Attributes**: `allowclear`, `count`, `disabled: boolean`, `icon: string`, `label: string`, `maxlength`, `maxrows`, `message: string`, `minrows`, `name: string`, `onPressEnter`, `placeholder: string`, `prefix: string`, `sheet: string`, `showcount`, `status: string`, `suffix: string`, `type: string`, `value: string`, `variant`
+- **Properties**:
+  - `disabled: boolean` — input 上 disabled 属性
+  - `icon: string` — 一个 icon
+  - `label: string` — 类似于 Metiral Design 的输入体验。
+  - `max: string` — 当 input 类型为 number 类型时，可以获取 max 属性
+  - `message: string` — 下方的提示/校验文案
+  - `min: string` — 当 input 类型为 number 类型时，可以获取 min 属性
+  - `name: string` — 与 form 组件联动时，收集的属性名
+  - `placeholder: string` — input 的占位字符
+  - `prefix: string` — 前面的 icon
+  - `required: boolean` — input 是否为必选
+  - `sheet: string`
+  - `status: string` — input 框的状态
+  - `step: string` — 当 input 类型为 number 类型时，可以获取 step 属性
+  - `suffix: string` — 后面的 icon
+  - `type: string` — input 的类型
+  - `value: string` — input 的值
+- **Events**: `change` → detail `{ value }` · `input` → detail `{ value }`
+- **Slots**: —
+- **Parts**: `content`, `input`, `label`, `message`
+
+## `<r-link>`
+
+Source: `components/link/index.ts`
+
+- **Attributes**: `href: string`, `replace: boolean`, `sheet: string`
+- **Properties**: `href: string`, `replace: boolean`, `sheet: string`
+- **Events**: `ran-navigate` → detail `{ path, replace }`
+- **Slots**: —
+- **Parts**: —
+
+## `<r-loading>`
+
+Source: `components/loading/index.ts`
+
+- **Attributes**: `name: 'double-bounce' | 'rotate' | 'stretch' | 'cube' | 'dot' | 'triple-bounce' | 'scale-out' | 'circle' | 'circle-line' | 'square' | 'pulse' | 'solar' | 'cube-fold' | 'circle-fold' | 'cube-grid' | 'circle-turn' | 'circle-rotate' | 'circle-spin' | 'dot-bar' | 'dot-circle' | 'line' | 'dot-pulse' | 'line-scale' | 'text' | 'cube-dim' | 'dot-line' | 'arc' | 'drop' | 'pacman'`, `sheet: string`
+- **Properties**: `name: 'double-bounce' | 'rotate' | 'stretch' | 'cube' | 'dot' | 'triple-bounce' | 'scale-out' | 'circle' | 'circle-line' | 'square' | 'pulse' | 'solar' | 'cube-fold' | 'circle-fold' | 'cube-grid' | 'circle-turn' | 'circle-rotate' | 'circle-spin' | 'dot-bar' | 'dot-circle' | 'line' | 'dot-pulse' | 'line-scale' | 'text' | 'cube-dim' | 'dot-line' | 'arc' | 'drop' | 'pacman'`, `sheet: string`
+- **Events**: —
+- **Slots**: —
+- **Parts**: `sun`
+
+## `<r-math>`
+
+Source: `components/math/index.ts`
+
+- **Attributes**: `latex: string`, `sheet: string`
+- **Properties**: `latex: string`, `sheet: string`
+- **Events**: —
+- **Slots**: —
+- **Parts**: —
+
+## `<r-message>`
+
+Source: `components/message/index.ts`
+
+- **Attributes**: —
+- **Properties**: `content: string | null`, `sheet: string`, `type: string | null`
+- **Events**: —
+- **Slots**: —
+- **Parts**: —
+
+## `<r-modal>`
+
+Source: `components/modal/index.ts`
+
+- **Attributes**: `autoFocus: boolean`, `closable: boolean`, `closeOnEsc: boolean`, `lockScroll: boolean`, `maskClosable: boolean`, `open: boolean`, `sheet: string`, `title: string`
+- **Properties**: `autoFocus: boolean`, `closable: boolean`, `closeOnEsc: boolean`, `lockScroll: boolean`, `maskClosable: boolean`, `open: boolean`, `sheet: string`, `title: string`
+- **Events**: `afterclose` → detail `{ trigger }` · `afteropen` · `beforeclose` → detail `{ trigger }` · `beforeopen` · `close` → detail `{ trigger }` · `open`
+- **Slots**: `default`, `footer (named)`
+- **Parts**: `body`, `close`, `dialog`, `footer`, `header`, `mask`, `root`, `title`
+
+## `<r-option>`
+
+Source: `components/select/option/index.ts`
+
+- **Attributes**: —
+- **Properties**: `disabled: boolean | string | undefined | null`, `sheet`, `value`
+- **Events**: —
+- **Slots**: `default`
+- **Parts**: —
+
+## `<r-player>`
+
+Source: `components/player/index.ts`
+
+- **Attributes**: `currenttime`, `currentTime: string`, `debug: string`, `playbackrate`, `playbackRate: string`, `sheet: string`, `src: string`, `volume: string`
+- **Properties**: `currentTime: string`, `debug: string`, `playbackRate: string`, `sheet: string`, `src: string`, `volume: string`
+- **Events**: `change` → detail `{ currentTime, data, duration, tag, type }`
+- **Slots**: —
+- **Parts**: —
+
+## `<r-popover>`
+
+Source: `components/popover/index.ts`
+
+- **Attributes**: `arrow: string`, `placement: string`, `sheet: string`, `trigger: string`
+- **Properties**: `arrow: string`, `getPopupContainerId: string`, `placement: string`, `sheet: string`, `trigger: string`
+- **Events**: —
+- **Slots**: `default`
+- **Parts**: —
+
+## `<r-progress>`
+
+Source: `components/progress/index.ts`
+
+- **Attributes**: `drag`, `primary`
+- **Properties**: `dot: string`, `percent: string`, `sheet: string`, `total: string`, `type: string`
+- **Events**: `change` → detail `{ percent, total, value }`
+- **Slots**: —
+- **Parts**: `dot`, `fill`, `track`
+
+## `<r-radar>`
+
+Source: `components/radar/index.ts`
+
+- **Attributes**: —
+- **Properties**: `abilitys`, `colorLine`, `colorPolygon`, `fillColor`, `fontColor`, `sheet`, `strokeColor`
+- **Events**: —
+- **Slots**: —
+- **Parts**: —
+
+## `<r-route>`
+
+Source: `components/route/index.ts`
+
+- **Attributes**: `exact: boolean`, `path: string`, `sheet: string`
+- **Properties**: `exact: boolean`, `params: Record<string, string>`, `path: string`, `sheet: string`
+- **Events**: `routematch` → detail `{ params, path }`
+- **Slots**: `default`
+- **Parts**: —
+
+## `<r-router>`
+
+Source: `components/router/index.ts`
+
+- **Attributes**: `base: string`, `mode: 'history' | 'hash'`, `sheet: string`
+- **Properties**: `base: string`, `mode: 'history' | 'hash'`, `sheet: string`
+- **Events**: `routechange` → detail `{ path }`
+- **Slots**: `default`
+- **Parts**: —
+
+## `<r-scratch>`
+
+Source: `components/scratch/index.ts`
+
+- **Attributes**: `disabled`, `effect`, `icon`, `iconSize`, `sheet`
+- **Properties**: —
+- **Events**: —
+- **Slots**: —
+- **Parts**: —
+
+## `<r-section>`
+
+Source: `components/section/index.ts`
+
+- **Attributes**: `heading: string`, `sheet: string`, `subtitle: string`
+- **Properties**: `heading: string`, `sheet: string`, `subtitle: string`
+- **Events**: —
+- **Slots**: `default`
+- **Parts**: `body`, `header`, `heading`, `subtitle`
+
+## `<r-select>`
+
+Source: `components/select/index.ts`
+
+- **Attributes**: `clear`, `defaultValue: string`, `disabled: boolean`, `dropdownclass: string`, `getPopupContainerId: string`, `placement: string`, `sheet: string`, `showSearch: string`, `trigger: string`, `type: string`, `value: string`
+- **Properties**: `defaultValue: string`, `disabled: boolean`, `dropdownclass: string`, `getPopupContainerId: string`, `placement: string`, `sheet: string`, `showSearch: string`, `trigger: string`, `type: string`, `value: string`
+- **Events**: `change` → detail `{ label, value }` · `search` → detail `{ value }`
+- **Slots**: `default`
+- **Parts**: `icon`, `search`, `select`, `selection`, `selection-item`
+
+## `<r-skeleton>`
+
+Source: `components/skeleton/index.ts`
+
+- **Attributes**: `disabled`, `sheet: string`
+- **Properties**: `sheet: string`
+- **Events**: —
+- **Slots**: —
+- **Parts**: —
+
+## `<r-tab>`
+
+Source: `components/tabpane/index.ts`
+
+- **Attributes**: —
+- **Properties**: `disabled`, `effect`, `icon`, `iconSize`, `key`, `label`, `sheet`
+- **Events**: —
+- **Slots**: `default`
+- **Parts**: `content`
+
+## `<r-tabs>`
+
+Source: `components/tab/index.ts`
+
+- **Attributes**: `active: string | null`, `align: string`, `effect: string | null`, `forceRender`, `sheet: string`, `type: string`
+- **Properties**: `active: string | null`, `align: string`, `effect: string | null`, `sheet: string`, `type: string`
+- **Events**: `change` → detail `{ active }`
+- **Slots**: `default`
+- **Parts**: `content`, `content-wrap`, `header`, `indicator`, `nav`, `tabs`

package/docs/DESIGN.md

@@ -0,0 +1,182 @@
+# ranui DESIGN.md
+
+> An executable design specification — written for humans **and** AI agents.
+> When generating or editing ranui UI, follow these rules so output is consistent
+> instead of drifting in style. Based on the [Geist design system](https://vercel.com/design)
+> ([design.md](https://vercel.com/design.md) / [design.dark.md](https://vercel.com/design.dark.md)).
+
+## How to use this file
+
+- Prefer **semantic tokens** (`--ran-color-*`, `--ran-space-*`, …) over raw scales or hex.
+- Decide by **role/state**, not by eyeballing a value. The value is chosen for you.
+- When a choice is unresolved, mark it explicitly — don't bury a guess in code.
+- Design **all reachable states** (default, hover, active, focus, disabled, loading, empty, error), not just the happy path.
+- **Verify the rendered result**, in light and dark, at narrow and wide widths — code review alone is not enough.
+
+Conflict resolution order: **user goals → verified evidence → this file → repo guidance (`CLAUDE.md`) → shipped patterns → general heuristics.**
+
+---
+
+## 1. Color — a state ladder, not a palette
+
+Each hue is a **10-step scale** (`100`–`1000`). Every step has **one fixed job**, so interaction states are decided up front:
+
+| Step | Role                        |
+| ---- | --------------------------- |
+| 100  | Default background          |
+| 200  | Hover background            |
+| 300  | Active (pressed) background |
+| 400  | Default border              |
+| 500  | Hover border                |
+| 600  | Active border               |
+| 700  | Solid fill (button/badge)   |
+| 800  | Solid fill — hover          |
+| 900  | Secondary text & icons      |
+| 1000 | Primary text & icons        |
+
+Scales: `--ran-gray-100..1000`, `--ran-gray-alpha-100..1000` (translucent, layers over any surface), `--ran-blue-*`, `--ran-red-*`, `--ran-amber-*`, `--ran-green-*`, plus `--ran-background-100/200`.
+
+**Use the semantic layer, not the scale, in components:**
+
+| Token                                        | Maps to                         | Use for             |
+| -------------------------------------------- | ------------------------------- | ------------------- |
+| `--ran-color-bg`                             | background-100                  | Page background     |
+| `--ran-color-bg-subtle`                      | background-200                  | Subtle page zones   |
+| `--ran-color-bg-elevated`                    | bg-100 / gray-100 (dark)        | Cards, surfaces     |
+| `--ran-color-bg-muted`                       | gray-100                        | Inset / muted fills |
+| `--ran-color-bg-hover`                       | gray-200                        | Hover background    |
+| `--ran-color-bg-active`                      | gray-300                        | Active background   |
+| `--ran-color-text`                           | gray-1000                       | Primary text        |
+| `--ran-color-text-secondary`                 | gray-900                        | Secondary text      |
+| `--ran-color-text-disabled`                  | gray-700                        | Disabled text       |
+| `--ran-color-border`                         | gray-400                        | Default border      |
+| `--ran-color-border-hover`                   | gray-500                        | Hover border        |
+| `--ran-color-border-active`                  | gray-600                        | Active border       |
+| `--ran-color-primary` / `-hover` / `-active` | blue-700 / 800 / 900            | Primary action      |
+| `--ran-color-success` / `warning` / `danger` | green-700 / amber-700 / red-700 | Status              |
+| `--ran-color-link`                           | blue-700                        | Links               |
+
+**Accent meaning:** blue = primary & links · green = success · amber = warning · red = danger/error.
+
+**Light & dark:** same token name, different value. `gray-1000` is `#171717` in light and `#ededed` in dark. Components reference the _semantic name_; dark mode only redefines the base scale (one mixin), and everything re-resolves.
+
+**Rules**
+
+- Never hard-code a hex/rgb in a component for a value that should follow the theme.
+- A component token's fallback must point at a **token that flips** (`var(--ran-gray-alpha-100, …)`, `var(--ran-blue-100, …)`, `var(--ran-color-text, …)`), never a light-only literal — otherwise it breaks in dark mode.
+
+---
+
+## 2. Spacing — a limited, rhythmic scale
+
+A **4px base unit** with **nine values** only: `--ran-space-1..24` → `4, 8, 12, 16, 24, 32, 40, 64, 96`px.
+
+**Rhythm**
+
+- `8px` between elements inside a group.
+- `16px` between groups.
+- `32–40px` between sections.
+
+**Rule:** pick a value from the scale. Don't invent `20px`/`28px` — a limited set is what creates the page's rhythm.
+
+---
+
+## 3. Typography — choose a role, not a size
+
+Fonts: `--ran-font-family` (Geist Sans, UI & prose), `--ran-font-mono` (Geist Mono, code, data, and eyebrow/labels). Base: `--ran-font-size: 14px`, `--ran-line-height: 1.5715`.
+
+Decide by **role**; the role fixes font, size, weight, line-height:
+
+| Role    | Use                    | Weight  | Notes                                                 |
+| ------- | ---------------------- | ------- | ----------------------------------------------------- |
+| heading | Titles                 | 600     | Tight letter-spacing (≈ -0.03em); 32 / 24 / 20 / 16px |
+| label   | Single-line, scannable | 500     | 14 / 13 / 12px; no wrapping                           |
+| copy    | Multi-line body        | 400     | line-height ~1.55; 16 / 14px                          |
+| button  | Button text            | 500     | 14px; `line-height: 1` for crisp vertical centering   |
+| mono    | Code, data, eyebrows   | 400/500 | `--ran-font-mono`                                     |
+
+**Rule:** ask "what role is this text?" (heading / label / copy / button) — the style follows. Don't pick raw px per instance.
+
+---
+
+## 4. Radius & elevation
+
+Radius: `--ran-radius-sm` 6 · `--ran-radius-md` 12 · `--ran-radius-lg` 16 · `--ran-radius-full` 9999.
+
+- Controls (button, input, select) → `sm`. Cards / dialogs → `md`. Large surfaces → `lg`. Pills / avatars → `full`.
+
+**Elevation is a role, not decoration.** Pick the shadow by _what the element is_, and make sure the tier is actually perceptible — a shadow you can't see fails its job.
+
+| Tier    | Token                   | Use for                                                                                                                                               |
+| ------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Raised  | `--ran-shadow-elevated` | In-flow surfaces that also have a border — `r-card`, `r-section`. Subtle on purpose.                                                                  |
+| Overlay | `--ran-shadow-menu`     | Transient layers floating **over** content — `r-dropdown`, `r-select` menu, `r-popover`, tooltips, `r-message`/toast. Must clearly lift off the page. |
+| Modal   | `--ran-shadow-modal`    | Blocking dialogs — `r-modal`. Strongest.                                                                                                              |
+
+A floating overlay must **never** fall back to `--ran-shadow-elevated` (the card tier) — it will look flat. Borderless overlays (dropdown, toast) rely on the shadow alone for separation, so the overlay tiers carry real weight.
+
+**Stacking follows the same roles (z-index ladder).** Floating overlays portal to `<body>`, so they need an explicit stacking tier. The z-index must sit on the element that is **positioned and portaled** (the host) — a z-index on an inner shadow node is trapped in the host's stacking context and does nothing against page content.
+
+| Tier     | Token              | Default | Use for                                                                                             |
+| -------- | ------------------ | ------- | --------------------------------------------------------------------------------------------------- |
+| Modal    | `--ran-z-modal`    | `1000`  | Blocking dialogs (`r-modal`) and their mask.                                                        |
+| Dropdown | `--ran-z-dropdown` | `1100`  | Dropdown / select menu / popover. **Above** modal, so a select opened inside a modal stays visible. |
+| Message  | `--ran-z-message`  | `1200`  | Toasts / notifications. Always on top.                                                              |
+
+Override a tier globally (set `--ran-z-dropdown` on `:root`) or per component (`--ran-dropdown-host-z-index`, `--ran-modal-root-z-index`, `--ran-message-z-index`) — never reach for `!important`. An overlay open while the page scrolls must re-run its placement on `scroll`/`resize` so it tracks its trigger (e.g. inside a sticky header).
+
+---
+
+## 5. Motion — prefer none
+
+Durations: `--ran-motion-duration-fast` `0.15s`, `--ran-motion-duration-base` `0.2s`.
+
+| Duration | Use                                                |
+| -------- | -------------------------------------------------- |
+| 0ms      | A change that is already obvious — apply instantly |
+| ~150ms   | Hover / active state transitions                   |
+| ~200ms   | Popovers & menus appearing                         |
+| ~300ms   | Modals & dialogs                                   |
+
+**Principle:** the bigger the change, the more time it earns. Otherwise: don't animate. Keep motion quick, light, and restrained. Respect `prefers-reduced-motion`.
+
+---
+
+## 6. Content — copy is part of the system
+
+- **Buttons:** an action **plus** an object. ✅ "Deploy project", "Delete member". ❌ "Deploy", "OK", "Delete".
+- **Errors:** say **what happened**, then **how to fix it**. ✅ "Build failed: the bundle exceeds the size limit. Reduce it or raise the limit." ❌ "Operation failed, please try again."
+- **Confirmations / toasts:** state the **change**, not "success". ✅ "Project deleted". ❌ "Successfully deleted" (the toast appearing already implies success).
+- Be specific; every sentence should remove guesswork, not add it.
+
+---
+
+## 7. Accessibility — the system serves everyone
+
+- Maintain sufficient text-to-background contrast (**WCAG AA**).
+- **Never signal state with color alone** — pair it with an icon or text (e.g. ✓ / ✕ labels, not just green/red).
+- Every interactive element has a **visible focus ring** — `--ran-focus-ring`, or `outline: 2px solid var(--ran-color-primary); outline-offset: 2px`. Never remove it for "cleanliness".
+- **Full keyboard navigation** — nothing is mouse-only.
+- Respect `prefers-reduced-motion` and `prefers-color-scheme`.
+
+---
+
+## 8. Components — how to apply the system
+
+- Use the semantic ranui components (`r-button`, `r-input`, `r-select`, `r-card`, `r-modal`, …) rather than re-building primitives.
+- Theme through **CSS variables**, **`::part()`**, or the **`sheet`** attribute (escape hatch). CSS variables cross Shadow DOM; selectors do not.
+- Component tokens default to semantic tokens: `var(--ran-btn-content-background-color, var(--ran-color-primary, #006bff))`.
+- Map states to the color ladder: default → `bg`/`text`; hover → `bg-hover` / `border-hover` / `primary-hover`; active → `bg-active` / `primary-active`; disabled → `text-disabled` + reduced opacity; focus → focus ring.
+- See [THEME_STYLE_SYSTEM_DESIGN.md](./THEME_STYLE_SYSTEM_DESIGN.md) for the token architecture and [style-tokens-public.md](./style-tokens-public.md) for the generated per-component token list.
+
+---
+
+## Verification checklist (before shipping UI)
+
+- [ ] Primary task and primary action are unmistakable.
+- [ ] Works in **light and dark**, at **narrow and wide** widths.
+- [ ] All changed **states** exercised (hover, active, focus, disabled, loading, empty, error).
+- [ ] **Keyboard / focus** behavior verified; visible focus everywhere.
+- [ ] Edge cases: long text, large numbers, both locales (en / zh).
+- [ ] Spacing comes from the scale; type uses a role; color uses semantic tokens.
+- [ ] Copy follows §6; nothing signals state by color alone (§7).