@design-ai/cli 4.55.0

package/knowledge/PRINCIPLES.md

@@ -0,0 +1,108 @@
+<!-- hand-written -->
+---
+title: Design-AI principles — agent priming cheat sheet
+applies_to: [all]
+purpose: Single-page reference. Read at the start of every design task. Every rule cites a deeper knowledge file.
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Design-AI principles
+
+The 30 load-bearing rules across this knowledge base. Read this first; it primes you for any design task. Every line links to the deeper file with reasoning + edge cases.
+
+## Color
+
+1. **Contrast: 4.5:1 body, 3:1 UI/large text.** Cite [`a11y/contrast.md`](a11y/contrast.md). Always state the ratio explicitly when introducing a color pair.
+2. **Tokens by role, not by hex.** `--color-primary-default` not `--blue-600`. Cite [`colors/color-theory.md`](colors/color-theory.md).
+3. **Dark mode is recomputed, not inverted.** Increase chroma 10–20% for low-light; reset semantic anchors. Cite [`colors/color-theory.md`](colors/color-theory.md).
+4. **Money colors are a separate axis** from primary/error. `--color-money-positive` / `--color-money-negative` / `--color-money-neutral`. Cite [`patterns/money-and-amount.md`](patterns/money-and-amount.md).
+5. **Korean stock convention is INVERTED**: red=up, blue=down. Cite [`patterns/money-and-amount.md`](patterns/money-and-amount.md).
+6. **Color + icon redundancy.** Never encode meaning by color alone — pair with icon, label, or pattern. Cite [`a11y/contrast.md`](a11y/contrast.md).
+
+## Typography
+
+7. **Korean +10% line-height** vs Latin defaults. Body 1.5 → 1.6. Cite [`i18n/korean-typography.md`](i18n/korean-typography.md).
+8. **Korean body emphasis = weight 600** (not 500). Hangul reads thinner at the same numeric weight. Cite [`i18n/korean-typography.md`](i18n/korean-typography.md).
+9. **Tabular numerals for amounts.** `font-feature-settings: 'tnum' 1`. Cite [`patterns/money-and-amount.md`](patterns/money-and-amount.md).
+10. **Pretendard for Korean primary.** Pairs Hangul + Latin in matched proportions. Cite [`i18n/korean-typography.md`](i18n/korean-typography.md).
+11. **Type scale: base 14 product UI / 18+ marketing.** Ratio 1.25 (major third) is the safe default. Cite [`typography/type-scale-fundamentals.md`](typography/type-scale-fundamentals.md).
+
+## Spacing & layout
+
+12. **4-base spacing scale.** `4, 8, 12, 16, 20, 24, 32, 40, 48, 64`. No arbitrary values. Cite [`layout/spacing-and-grid.md`](layout/spacing-and-grid.md).
+13. **12-col grid, 24px gutter.** Standard for product UIs. Container queries for component-internal layout. Cite [`layout/spacing-and-grid.md`](layout/spacing-and-grid.md).
+14. **Korean consumer mobile is denser** than Western defaults. Reduce padding ~15–25% from MUI/Material defaults. Cite [`i18n/korean-product-conventions.md`](i18n/korean-product-conventions.md).
+
+## Motion
+
+15. **Three duration tiers**: 150ms (micro) / 250ms (component) / 400ms (hero only). Cite [`motion/principles.md`](motion/principles.md).
+16. **`ease-out` for entrances, `ease-in` for exits, `ease-in-out` for position changes.** Cite [`motion/principles.md`](motion/principles.md).
+17. **Respect `prefers-reduced-motion`.** Drop fade/scale/parallax; keep state changes. Cite [`motion/principles.md`](motion/principles.md).
+
+## Accessibility
+
+18. **Every interactive element keyboard-reachable** with visible focus indicator (≥ 2px, 3:1 contrast). Cite [`a11y/keyboard-and-focus.md`](a11y/keyboard-and-focus.md).
+19. **Touch targets ≥ 44×44 mobile / ≥ 24×24 web AA.** Use `hitSlop` to extend without growing visual. Cite [`a11y/keyboard-and-focus.md`](a11y/keyboard-and-focus.md).
+20. **Modal: focus trap on open, restore focus on close, Escape closes.** Cite WAI-ARIA Dialog Pattern + [`examples/component-modal.md`](../examples/component-modal.md).
+21. **Form errors via `aria-invalid` + `aria-describedby`** pointing at the error text. Cite [`patterns/form-design.md`](patterns/form-design.md).
+22. **Disabled state requires `aria-disabled`** in addition to native `disabled`. Cite [`a11y/keyboard-and-focus.md`](a11y/keyboard-and-focus.md).
+
+## Forms
+
+23. **Single column, labels above, validate on blur.** Cite [`patterns/form-design.md`](patterns/form-design.md).
+24. **Mark optional with `(optional)`, not required with `*`.** Required is the default; mark exceptions. Cite [`patterns/form-design.md`](patterns/form-design.md).
+25. **Korean: separate marketing-consent checkbox** from required-terms. Pre-checked is illegal. Cite [`i18n/korean-product-conventions.md`](i18n/korean-product-conventions.md).
+26. **Phone-first auth + KakaoTalk login** for Korean consumer apps. Cite [`i18n/korean-product-conventions.md`](i18n/korean-product-conventions.md).
+27. **Daum Postcode API for any Korean address field.** Never free-form. Cite [`i18n/korean-product-conventions.md`](i18n/korean-product-conventions.md).
+
+## Lists & navigation
+
+28. **Virtualize lists > 50 items** (FlatList on RN, react-virtual on web). Skeleton on first load only. Cite [`patterns/list-and-feed.md`](patterns/list-and-feed.md).
+29. **Bottom-tab-bar for Korean consumer mobile** (3–5 tabs, always with Korean labels). Cite [`patterns/mobile-navigation.md`](patterns/mobile-navigation.md).
+
+## Components
+
+30. **When specing a component, cite all 3 references** (Ant Design, MUI, shadcn-ui) and explain API choices ("API choices made" section). Don't invent — adapt. Cite [`skills/component-spec-writer/PLAYBOOK.md`](../skills/component-spec-writer/PLAYBOOK.md).
+
+## Data visualization
+
+31. **Pick palette type by data shape**: sequential (low→high), diverging (positive↔negative), categorical (distinct). Cite [`patterns/chart-color-encoding.md`](patterns/chart-color-encoding.md).
+32. **≤ 8 categorical colors.** More than 8 = user can't track. Cite [`patterns/chart-color-encoding.md`](patterns/chart-color-encoding.md).
+33. **Dashboard order: KPI row → primary chart → secondary 2-up → detail table.** Cite [`patterns/dashboard-composition.md`](patterns/dashboard-composition.md).
+34. **"Last updated" indicator on every live dashboard.** Cite [`patterns/realtime-data.md`](patterns/realtime-data.md).
+35. **Don't blast updates** — throttle to ≤10/sec per element, batch high-frequency. Respect `prefers-reduced-motion`. Cite [`patterns/realtime-data.md`](patterns/realtime-data.md).
+
+## Documentation & long-form
+
+36. **Documents follow Diátaxis types**: tutorial / how-to / reference / explanation. Each has a different template + voice. Don't mix in one doc. Cite [`patterns/information-architecture.md`](patterns/information-architecture.md).
+37. **Body 18px on docs, not 14px.** Long-form reading needs bigger text than UI. Cite [`patterns/document-typography.md`](patterns/document-typography.md).
+38. **Lead with the answer (TL;DR pyramid).** Especially in reports. Senior reader stops at the first paragraph; structure for that. Cite [`patterns/report-design.md`](patterns/report-design.md).
+39. **Active voice, second person, imperative for instructions.** Cite [`patterns/technical-writing.md`](patterns/technical-writing.md).
+40. **Slide title = the message, not the topic.** "Revenue tripled in Q4" beats "Revenue". Cite [`patterns/slide-deck-design.md`](patterns/slide-deck-design.md).
+41. **Korean documents: pick honorific level (~합니다 vs ~해요) and stay consistent.** Cite [`i18n/korean-document-style.md`](i18n/korean-document-style.md).
+
+## Output discipline
+
+When producing any design artifact:
+
+- **Cite knowledge files** for every claim category. No silent assertions.
+- **Contrast matrix** for any color-related output.
+- **Tokens by name in semantic layer**, hex only in primitive layer.
+- **Light + dark** when both requested. Recomputed.
+- **Don't section** with at least 2 specific misuses.
+- **Korean considerations** if `language` includes `ko`.
+
+## When in doubt
+
+- Default to **boring, defensible, cited** over **clever, novel, justified-by-vibe**.
+- If the upstream design systems all do X, do X unless you have a specific reason.
+- If you're unsure, ask one clarifying question. Don't guess.
+- Open the relevant `knowledge/<category>/<file>.md` rather than reasoning from training data.
+
+## How this file is used
+
+- **Loaded at session start** by the agent (alongside `AGENTS.md` / `CLAUDE.md`).
+- **Re-read before declaring an artifact complete** — verification phase reference.
+- **Cited in artifacts** as `PRINCIPLES.md` for the broad rules; specific files for details.

package/knowledge/a11y/contrast.md

@@ -0,0 +1,70 @@
+<!-- hand-written -->
+---
+title: Contrast — WCAG 2.1 / 2.2 reference
+applies_to: [web, mobile, all-ui]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Contrast
+
+WCAG 2.1 / 2.2 contrast requirements. Cite this file when justifying any color decision involving text or interactive UI.
+
+## Required ratios
+
+| Content | AA (legal floor) | AAA (target for product UI) |
+| --- | --- | --- |
+| Body text (< 18pt regular / < 14pt bold) | **4.5:1** | 7:1 |
+| Large text (≥ 18pt regular / ≥ 14pt bold) | **3:1** | 4.5:1 |
+| UI components (buttons, form borders, focus indicators, icons that convey meaning) | **3:1** | — |
+| Graphical objects that convey information | **3:1** | — |
+| Decorative content, logos | exempt | exempt |
+
+> "Large text" = ≥ 24px regular or ≥ 18.66px bold. Pixel sizes assume default browser root.
+
+## Quick failure modes
+
+- **Placeholder gray**: `#9CA3AF` on `#FFFFFF` is 2.88:1 — fails AA at any size. Use `#6B7280` (4.83:1) or darker.
+- **Disabled text "disabled-by-design"**: WCAG explicitly **exempts disabled controls**. But if "disabled" is your primary state (e.g., greyed-out menu item), users perceive it as live and you must clear AA.
+- **Brand color on white**: Many brand reds and greens fail AA for body. Reserve them for large text, icons (3:1 only), or accents on darker backgrounds.
+- **Focus indicators**: WCAG 2.4.11 (AA in WCAG 2.2) requires the focus ring itself to clear **3:1 against adjacent colors AND ≥ 2px thickness**. A subtle outline-blue on a light blue button often fails.
+- **Hover-only states**: hover is not a contrast requirement, but the **default state** must clear contrast on its own. Don't rely on hover to fix a non-compliant resting state.
+
+## Computing contrast (WCAG)
+
+The relative luminance of an sRGB component `c ∈ [0, 1]` is:
+
+```
+c' = c/12.92               if c ≤ 0.03928
+c' = ((c + 0.055)/1.055)^2.4   otherwise
+
+L = 0.2126 R' + 0.7152 G' + 0.0722 B'
+```
+
+Contrast ratio of two luminances:
+
+```
+ratio = (L_lighter + 0.05) / (L_darker + 0.05)
+```
+
+Range: 1 (identical) to 21 (black on white).
+
+## APCA (forthcoming)
+
+WCAG 3 will replace the WCAG 2 ratio with APCA (Accessible Perceptual Contrast Algorithm). Different scale (`Lc`), different polarity rules (dark-on-light vs light-on-dark are not symmetric). Don't migrate yet — APCA is not yet a normative web standard. Track: <https://www.myndex.com/APCA/>.
+
+## Tools
+
+| Tool | When |
+| --- | --- |
+| Browser DevTools color picker | Quick spot check (every browser shows AA/AAA badges). |
+| `color-contrast` CLI npm package | Automated CI check. |
+| WebAIM Contrast Checker | Authoritative web reference. |
+| Stark (Figma plugin) | Designing in Figma. |
+
+## What this rule does NOT cover
+
+- **Color blindness simulation** — pass contrast does not guarantee discriminability. Test with deuteranopia/protanopia simulators if color encodes meaning (status, charts).
+- **Text on imagery / video** — use a scrim (overlay 40–60% black) and verify against the **darkest** patch of the image you allow.
+- **Dark mode contrast inversion** — recompute every token. Light-mode AA does not imply dark-mode AA.

package/knowledge/a11y/keyboard-and-focus.md

@@ -0,0 +1,108 @@
+<!-- hand-written -->
+---
+title: Keyboard and focus — WCAG operable
+applies_to: [web, all-ui]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Keyboard and focus
+
+Every interactive element on screen must be operable by keyboard alone, with a visible focus indicator at every step. This is non-negotiable for AA compliance and for ~7% of users.
+
+## Tab order rules
+
+- Logical reading order. Tab follows the visual reading order — top-to-bottom, left-to-right (or RTL equivalent).
+- Skipping with `tabindex="-1"`: removes the element from the tab order but keeps it focusable programmatically. Use for items focused by code (e.g., modal title focused on open).
+- **Never** use `tabindex` ≥ 1. It overrides natural order and creates inconsistencies.
+- Hidden/disabled elements: `display:none`, `visibility:hidden`, `disabled` — auto-removed.
+- Decorative interactive-looking divs: must have `role` and `tabindex="0"` to be reachable, OR not be interactive.
+
+## Focus indicators
+
+Required by WCAG 2.4.11 (AA in 2.2).
+
+| Property | Minimum |
+| --- | --- |
+| Thickness | 2 CSS px outline OR equivalent area |
+| Contrast | 3:1 against adjacent colors (the element's normal color AND its background) |
+| Coverage | Encloses the element fully OR fills it with a 3:1+ contrast change |
+
+```css
+/* Good — works on light and dark backgrounds */
+button:focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: 2px;
+}
+
+/* Better for design systems — token-driven */
+button:focus-visible {
+  outline: 2px solid var(--color-focus-ring);
+  outline-offset: 2px;
+}
+
+/* DO NOT do this */
+*:focus { outline: none; }  /* removes a11y, fails 2.4.7 */
+```
+
+`:focus-visible` (modern browsers) keeps focus rings on keyboard nav but hides them for mouse clicks — users who don't want them are not disturbed, keyboard users are protected.
+
+## Required keyboard interactions per pattern
+
+| Component | Keys |
+| --- | --- |
+| Button | `Enter`, `Space` activate. |
+| Link | `Enter` activates. (Not space — that scrolls.) |
+| Menu / Dropdown | `↑/↓` move, `Enter` activate, `Escape` close, `Home/End` first/last. |
+| Tabs | `←/→` move (`↑/↓` if vertical), `Home/End` first/last, `Enter/Space` activate (or auto-activate for some patterns). |
+| Combobox | `↓` open, `↑/↓` navigate options, `Enter` select, `Escape` close, type-ahead supported. |
+| Modal / Dialog | Open: focus moves into dialog. `Escape` closes. Focus is **trapped** until close. On close: focus returns to the trigger. |
+| Slider | `←/↓` decrement, `→/↑` increment, `Home` min, `End` max, `PageUp/Down` larger step. |
+| Tree | `↑/↓` move, `←` collapse / move to parent, `→` expand / move to first child, `Enter` activate. |
+| Toggle / Switch | `Space` toggles. (Not Enter unless `<button>`-typed.) |
+| Date picker | Within calendar grid: arrow keys move days, `PageUp/Down` months, `Shift+PgUp/Dn` years. |
+
+Source: [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) — the canonical reference for keyboard patterns.
+
+## Focus management on route change (SPA)
+
+When a client-side route changes:
+- Move focus to the new page's `<h1>` (or main landmark).
+- Update document title (so screen reader announces the new context).
+- Without this, screen reader users hear nothing — the route change is invisible.
+
+```ts
+// On route change
+useEffect(() => {
+  document.title = newTitle;
+  document.querySelector('h1')?.focus();
+}, [route]);
+```
+
+## Touch target sizing
+
+WCAG 2.5.5 (Level AAA) and 2.5.8 (Level AA in 2.2) require:
+
+| Standard | Minimum |
+| --- | --- |
+| WCAG 2.2 AA (Target Size — Minimum) | **24×24 CSS px** |
+| WCAG 2.1 AAA (Target Size) | **44×44 CSS px** |
+| iOS HIG | 44×44 pt |
+| Material guidelines | 48×48 dp |
+
+For consumer mobile UIs, **target 44×44 minimum**. Smaller is allowed only when:
+- Equivalent target available elsewhere on the page, OR
+- Inline within a sentence (e.g., link in body text).
+
+Spacing matters too: a 24×24 button surrounded by enough space to count as a 44×44 hit area is better than a tightly-packed grid of 32×32 buttons.
+
+## Common failures to flag in review
+
+- `<div onClick>` with no `role` and no tab support.
+- Placeholder used as label (`<input placeholder="Email">` with no `<label>`).
+- Modal that steals focus on open but doesn't return it on close.
+- `Escape` on dropdown closes the page modal too (event bubbling).
+- Custom select with no type-ahead.
+- Focus ring removed globally with `outline: none`.
+- Carousel that auto-advances and traps focus.

package/knowledge/colors/color-theory.md

@@ -0,0 +1,90 @@
+<!-- hand-written -->
+---
+title: Color theory for product UI
+applies_to: [design-system, brand, all-ui]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Color theory for product UI
+
+Practical color reasoning for product designers. Skip if you've designed three real systems already; otherwise this is the floor.
+
+## Color spaces
+
+| Space | When to use |
+| --- | --- |
+| **HEX / RGB** | Final output, code-side. Not for reasoning about hue/luminance. |
+| **HSL** | Quick mental model — hue spin, lightness ramps. Falls apart for perceptually uniform ramps (e.g., yellow at L=50% reads brighter than blue at L=50%). |
+| **OKLCH** | Modern default for design tokens. Perceptually uniform, predictable lightness ramps, stable hue under chroma changes. Tailwind v4 defaults to OKLCH. Browser-supported in 2023+. |
+| **HCT (Material 3)** | Same family as OKLCH but tuned for Material's tone mapping. Use if you build on Material 3. |
+
+**Rule of thumb**: design and store tokens in **OKLCH or HCT**, output in HEX/RGB for code. Don't author tokens in HSL — your "L=50%" yellow will read 1.5× brighter than your "L=50%" blue.
+
+## Building a palette — the steps
+
+1. **Pick the brand primary** (1 hex).
+2. **Generate the ramp**: 10–11 stops from `50` (lightest) to `950` (darkest). Use OKLCH lightness step ≈ 8–10% per stop. Keep chroma constant where possible — falling chroma at the dark end avoids muddy darks.
+3. **Pick semantic anchors** in the ramp:
+   - `primary-default` = step 500 or 600 (pick the one that hits 4.5:1 on white).
+   - `primary-hover` = +1 step darker.
+   - `primary-active` = +2 steps darker.
+   - `primary-subtle-bg` = step 50 or 100.
+4. **Generate accent / supporting hues** by holding `L` and `C` constant in OKLCH and rotating `H`. This produces palette members that feel like siblings.
+5. **Pick neutrals** — usually a hue-cooled gray (slight blue tint matching the primary). Pure `#808080` reads cold and dead.
+6. **Pick semantic non-brand**: `success` (green-600), `warning` (amber-500), `error` (red-600), `info` (often = primary).
+7. **Dark mode**: Don't just invert. Recompute. Increase chroma by 10–20% (low-light eye is less saturated), keep semantic ranks the same (success-600 stays success-600), but sample from a cooler/darker baseline.
+
+## Anchor lightness for AA on white
+
+For white backgrounds, the primary text/CTA color must clear ratio:
+
+| Hue family | OKLCH `L` for ≈ 4.5:1 on white |
+| --- | --- |
+| Blue | ~50% |
+| Red | ~52% |
+| Green (cool, like emerald) | ~46% |
+| Yellow / Amber | ~36–40% (yellows go nearly to black before they clear AA) |
+| Purple | ~50% |
+| Gray | ~45% |
+
+These are starting estimates — always verify with a contrast checker.
+
+## Color roles (semantic naming)
+
+Use **role-based names**, not hue-based:
+
+```
+✗ blue-600
+✓ color-primary-default
+
+✗ gray-900
+✓ color-text-primary
+
+✗ red-500
+✓ color-feedback-error
+```
+
+Ramps stay hue-named (`blue-50` … `blue-950`); the **alias layer** above ramps is role-named. This is the same model as Ant Design, Tailwind, Material 3, and Polaris.
+
+## Anti-patterns
+
+- **Too many primaries**: a "primary" and a "primary-2" both used for CTAs. Pick one. The second goes into the secondary slot or gets cut.
+- **Pure black for text**: `#000000` is harsh. Most systems use `#1F1F1F` or `#111827` (Tailwind's gray-900).
+- **Pure white for backgrounds with content**: causes glare; use `#FAFAFA` or `#F9FAFB` for subdued backgrounds.
+- **Color encoding meaning without redundancy**: green for "online" / red for "offline" with no icon or label fails for color-blind users. WCAG 1.4.1.
+- **Inverted dark mode**: light mode swapped doesn't work. White becomes pure black, contrast hurts the eye, and brand hues lose punch.
+
+## Tools
+
+- **OKLCH picker**: <https://oklch.com> — design ramps in OKLCH, copy as CSS.
+- **Material Theme Builder**: <https://material-foundation.github.io/material-theme-builder/> — HCT-based, useful even for non-Material projects.
+- **Adobe Leonardo**: <https://leonardocolor.io> — generates ramps with target contrast ratios as the constraint.
+- **Tailwind v4 OKLCH variables**: defined as `oklch(l c h)` in CSS — paste from designer to dev cleanly.
+
+## Cross-reference
+
+- [knowledge/colors/palettes-by-product-type.md](palettes-by-product-type.md) — battle-tested palette starting points
+- [knowledge/colors/mui-palette-structure.md](mui-palette-structure.md) — MUI's role/state model
+- [knowledge/a11y/contrast.md](../a11y/contrast.md) — WCAG ratios

package/knowledge/colors/mui-palette-structure.md

@@ -0,0 +1,105 @@
+---
+title: MUI palette structure
+source: refs/mui/packages/mui-material/src/styles/createPalette.js
+upstream: https://github.com/mui/material-ui/blob/master/packages/mui-material/src/styles/createPalette.js
+extracted_at: 2026-05-19
+applies_to: [react, mui, material-design]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# MUI palette structure
+
+MUI splits palette into two layers:
+
+1. **Color objects** — `main`, `light`, `dark`, `contrastText` per role.
+2. **Roles** — `primary`, `secondary`, `error`, `warning`, `info`, `success`, plus surface/text scales.
+
+```ts
+type ColorPartial = {
+  main: string;
+  light?: string;        // auto-derived if missing (lighten by 0.2)
+  dark?: string;         // auto-derived if missing (darken by 0.3)
+  contrastText?: string; // auto-derived for accessible 3:1 against main
+};
+
+type Palette = {
+  mode: 'light' | 'dark';
+  primary: ColorPartial;
+  secondary: ColorPartial;
+  error: ColorPartial;
+  warning: ColorPartial;
+  info: ColorPartial;
+  success: ColorPartial;
+  // Surface
+  background: { default: string; paper: string };
+  // Text — semantic, not raw
+  text: {
+    primary: string;     // High-emphasis (87% opacity in light)
+    secondary: string;   // Medium (60%)
+    disabled: string;    // Low (38%)
+  };
+  // Other
+  divider: string;
+  action: {
+    active: string;
+    hover: string;
+    selected: string;
+    disabled: string;
+    focus: string;
+  };
+};
+```
+
+## Light mode defaults
+
+| Role | Token | Hex |
+| --- | --- | --- |
+| primary | `primary.main` | `#1976d2` |
+| secondary | `secondary.main` | `#9c27b0` |
+| error | `error.main` | `#d32f2f` |
+| warning | `warning.main` | `#ed6c02` |
+| info | `info.main` | `#0288d1` |
+| success | `success.main` | `#2e7d32` |
+| background | `background.default` | `#fff` |
+| background | `background.paper` | `#fff` |
+| text | `text.primary` | `rgba(0,0,0,0.87)` |
+| text | `text.secondary` | `rgba(0,0,0,0.6)` |
+| text | `text.disabled` | `rgba(0,0,0,0.38)` |
+| divider | `divider` | `rgba(0,0,0,0.12)` |
+
+## Dark mode defaults
+
+| Role | Token | Hex |
+| --- | --- | --- |
+| primary | `primary.main` | `#90caf9` |
+| secondary | `secondary.main` | `#ce93d8` |
+| error | `error.main` | `#f44336` |
+| warning | `warning.main` | `#ffa726` |
+| info | `info.main` | `#29b6f6` |
+| success | `success.main` | `#66bb6a` |
+| background | `background.default` | `#121212` |
+| background | `background.paper` | `#121212` |
+| text | `text.primary` | `#fff` |
+| text | `text.secondary` | `rgba(255,255,255,0.7)` |
+| text | `text.disabled` | `rgba(255,255,255,0.5)` |
+| divider | `divider` | `rgba(255,255,255,0.12)` |
+
+## Action overlay opacities
+
+Action states are **overlays** on top of the role color, not separate tokens. Light/dark vary:
+
+| State | Light opacity | Dark opacity |
+| --- | --- | --- |
+| `hover` | 0.04 | 0.08 |
+| `selected` | 0.08 | 0.16 |
+| `focus` | 0.12 | 0.12 |
+| `disabled` | 0.26 | 0.3 |
+
+## Designer notes
+
+- The **opacity-based text scale** (87/60/38) is Material 1's hierarchy. Modern Material 3 uses HCT-based on-surface variants with hard hex values. Use opacity for muted text in legacy systems, hex tokens in new systems.
+- `contrastText` is auto-computed against `main`. If you override `main`, leave `contrastText` blank — let MUI compute it. If you fix `contrastText` manually, **verify ≥ 4.5:1**.
+- `background.default` and `background.paper` are intentionally identical in dark mode (`#121212`). Material 3 separates them via elevation overlays. If you want depth in dark mode, set `background.paper` to `#1e1e1e` or use `Paper` `elevation` props.
+- Don't add custom roles (e.g., `tertiary`) without also defining `light/dark/contrastText` — the theme provider will throw.