@design-ai/cli 4.55.0

package/knowledge/design-tokens/tailwind-v4.md

@@ -0,0 +1,284 @@
+<!-- hand-written -->
+---
+title: Tailwind CSS v4 default theme reference
+applies_to: [tailwindcss, oklch, design-tokens, web]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Tailwind CSS v4 default theme
+
+Tailwind v4 ships an OKLCH-based default theme that's the most commonly used token set in modern web product UIs. Worth knowing as a reference, even if you customize.
+
+## Theme syntax
+
+Tailwind v4 uses CSS-native `@theme` declarations:
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-primary-500: oklch(0.606 0.250 292.717);
+  --spacing: 0.25rem;
+  --font-sans: 'Inter', sans-serif;
+  /* ... */
+}
+```
+
+Variables become utility classes automatically (`bg-primary-500`, `p-4`, `font-sans`).
+
+## Color scale (the hero feature)
+
+Tailwind v4's default colors are OKLCH-derived. **Each scale is perceptually uniform** — step from 100 to 200 is visually the same magnitude as 800 to 900. This is the headline change from v3.
+
+### Color families
+
+22 default color families × 11 steps each = 242 default colors. Listed below in OKLCH rotation order:
+
+```
+red, orange, amber, yellow, lime, green, emerald, teal, cyan,
+sky, blue, indigo, violet, purple, fuchsia, pink, rose,
+slate, gray, zinc, neutral, stone
+```
+
+The first 17 are chromatic; the last 5 are neutral grays with subtle hue tints.
+
+### Steps (per family)
+
+`50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950`
+
+### Lightness mapping (consistent across families)
+
+| Step | Approximate OKLCH `L` |
+| --- | --- |
+| 50  | 0.96–0.98 |
+| 100 | 0.93–0.95 |
+| 200 | 0.87–0.90 |
+| 300 | 0.78–0.82 |
+| 400 | 0.65–0.72 |
+| 500 | 0.55–0.62 |
+| 600 | 0.49–0.55 |
+| 700 | 0.42–0.49 |
+| 800 | 0.36–0.43 |
+| 900 | 0.30–0.38 |
+| 950 | 0.18–0.28 |
+
+**Step 600 hits ~4.5:1 on white** for most chromatic colors — this is the canonical "primary brand" anchor. Step 500 hits ~3:1 (UI-sized only).
+
+### Sample family — violet
+
+```css
+@theme {
+  --color-violet-50:  oklch(0.969 0.016 293.756);  /* #F5F3FF */
+  --color-violet-100: oklch(0.943 0.029 294.588);  /* #EDE9FE */
+  --color-violet-200: oklch(0.894 0.057 293.283);  /* #DDD6FE */
+  --color-violet-300: oklch(0.811 0.111 293.571);  /* #C4B5FD */
+  --color-violet-400: oklch(0.702 0.183 293.541);  /* #A78BFA */
+  --color-violet-500: oklch(0.606 0.250 292.717);  /* #8B5CF6 */
+  --color-violet-600: oklch(0.541 0.281 293.009);  /* #7C3AED */
+  --color-violet-700: oklch(0.491 0.270 292.581);  /* #6D28D9 */
+  --color-violet-800: oklch(0.432 0.232 292.759);  /* #5B21B6 */
+  --color-violet-900: oklch(0.381 0.176 293.745);  /* #4C1D95 */
+  --color-violet-950: oklch(0.283 0.141 291.089);  /* #2E1065 */
+}
+```
+
+## Spacing
+
+Tailwind v4 default uses a single `--spacing` base, with utilities scaling it:
+
+```css
+@theme {
+  --spacing: 0.25rem;  /* 4px (assuming 16px root) */
+}
+```
+
+| Class | Value |
+| --- | --- |
+| `p-1` | 4px |
+| `p-2` | 8px |
+| `p-3` | 12px |
+| `p-4` | 16px |
+| `p-5` | 20px |
+| `p-6` | 24px |
+| `p-8` | 32px |
+| `p-10` | 40px |
+| `p-12` | 48px |
+| `p-16` | 64px |
+| `p-20` | 80px |
+| `p-24` | 96px |
+
+Aligns with our 4-base scale per [`layout/spacing-and-grid.md`](../layout/spacing-and-grid.md).
+
+## Typography
+
+```css
+@theme {
+  --font-sans: ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+  --font-serif: ui-serif, Georgia, Cambria, 'Times New Roman', Times, serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;
+}
+```
+
+System-font stacks are the default — performant, no FOUT.
+
+### Type scale
+
+| Class | Size | Line height |
+| --- | --- | --- |
+| `text-xs` | 12px | 16px (1.33) |
+| `text-sm` | 14px | 20px (1.43) |
+| `text-base` | 16px | 24px (1.5) |
+| `text-lg` | 18px | 28px (1.56) |
+| `text-xl` | 20px | 28px (1.4) |
+| `text-2xl` | 24px | 32px (1.33) |
+| `text-3xl` | 30px | 36px (1.2) |
+| `text-4xl` | 36px | 40px (1.11) |
+| `text-5xl` | 48px | 1 |
+| `text-6xl` | 60px | 1 |
+| `text-7xl` | 72px | 1 |
+| `text-8xl` | 96px | 1 |
+| `text-9xl` | 128px | 1 |
+
+Note: large sizes (`5xl+`) drop to `line-height: 1` (display use). Body sizes have generous leading.
+
+### Weights
+
+`font-thin` 100 / `font-extralight` 200 / `font-light` 300 / `font-normal` 400 / `font-medium` 500 / `font-semibold` 600 / `font-bold` 700 / `font-extrabold` 800 / `font-black` 900.
+
+## Breakpoints
+
+```css
+@theme {
+  --breakpoint-sm: 40rem;    /* 640px */
+  --breakpoint-md: 48rem;    /* 768px */
+  --breakpoint-lg: 64rem;    /* 1024px */
+  --breakpoint-xl: 80rem;    /* 1280px */
+  --breakpoint-2xl: 96rem;   /* 1536px */
+}
+```
+
+Mobile-first: utilities apply at all sizes by default; `md:bg-blue-500` applies at ≥ 768px.
+
+## Border radius
+
+| Class | Value |
+| --- | --- |
+| `rounded-none` | 0 |
+| `rounded-sm` | 0.125rem (2px) |
+| `rounded` | 0.25rem (4px) |
+| `rounded-md` | 0.375rem (6px) |
+| `rounded-lg` | 0.5rem (8px) |
+| `rounded-xl` | 0.75rem (12px) |
+| `rounded-2xl` | 1rem (16px) |
+| `rounded-3xl` | 1.5rem (24px) |
+| `rounded-full` | 9999px |
+
+## Shadows
+
+```
+shadow-2xs  / shadow-xs  / shadow-sm  / shadow  /
+shadow-md  / shadow-lg  / shadow-xl  / shadow-2xl  /
+shadow-inner  / shadow-none
+```
+
+Default values use `rgb(0 0 0 / x)` with varying offset and blur.
+
+## Transitions
+
+| Class | Properties |
+| --- | --- |
+| `transition` | most common (color, bg, border, opacity, shadow, transform, filter, backdrop-filter) |
+| `transition-all` | everything (avoid in production) |
+| `transition-colors` | color-only |
+| `transition-opacity` | opacity-only |
+| `transition-shadow` | shadow-only |
+| `transition-transform` | transform-only |
+
+Default duration `150ms`, ease `cubic-bezier(0.4, 0, 0.2, 1)`.
+
+| Class | Duration |
+| --- | --- |
+| `duration-75` | 75ms |
+| `duration-100` | 100ms |
+| `duration-150` | 150ms |
+| `duration-200` | 200ms |
+| `duration-300` | 300ms |
+| `duration-500` | 500ms |
+| `duration-700` | 700ms |
+| `duration-1000` | 1000ms |
+
+Consistent with [`motion/principles.md`](../motion/principles.md) duration tiers.
+
+## Z-index scale
+
+`z-0`, `z-10`, `z-20`, `z-30`, `z-40`, `z-50`, `z-auto`.
+
+For component systems with modals/popovers/tooltips: extend with semantic z-tokens (`--z-modal`, `--z-popover`, etc.) above this default.
+
+## Dark mode
+
+Tailwind v4 supports two strategies:
+
+### Media query (default)
+
+```css
+.dark\:bg-slate-900 { ... }
+```
+
+Applied via `@media (prefers-color-scheme: dark)`.
+
+### Class-based (most product apps)
+
+```css
+@variant dark (&:where(.dark, .dark *));
+```
+
+Then `<html class="dark">` toggles dark mode globally.
+
+### Token override
+
+```css
+@theme {
+  --color-bg: oklch(1 0 0);  /* white */
+}
+
+@layer base {
+  .dark {
+    --color-bg: oklch(0.18 0 0);  /* near-black */
+  }
+}
+```
+
+## How to customize
+
+To make Tailwind v4 yours:
+
+1. Override `@theme` with your brand tokens.
+2. Add semantic aliases:
+   ```css
+   @theme {
+     --color-primary-default: var(--color-violet-600);
+     --color-primary-hover: var(--color-violet-700);
+   }
+   ```
+3. Drop unused color families if bundle size matters (Tailwind tree-shakes; minimal concern).
+
+## When NOT to use Tailwind v4 defaults
+
+- **Brand has very specific palette**: replace the chromatic families with your brand ramps.
+- **Korean fintech needing red=up convention**: replace `--color-money-positive` / `--color-money-negative` semantically; keep primary scale.
+- **Material Design alignment**: use Material 3 tokens instead — see [`material-3.md`](material-3.md).
+- **Apps where `oklch()` browser support matters** (older browsers): provide hex fallbacks via PostCSS plugin or extract hex equivalents.
+
+## Worked example using Tailwind v4
+
+See [`examples/palette-saas-violet.md`](../../examples/palette-saas-violet.md) for a complete palette generated from Tailwind v4 violet ramps.
+
+## Cross-reference
+
+- [`knowledge/colors/color-theory.md`](../colors/color-theory.md) — OKLCH rationale, ramp construction
+- [`knowledge/design-tokens/material-3.md`](material-3.md) — alternative HCT-based token system
+- [`knowledge/design-tokens/ant-design.md`](ant-design.md) — alternative seed-token system
+- [Tailwind CSS v4 docs](https://tailwindcss.com/docs/theme)

package/knowledge/game-ui/game-accessibility.md

@@ -0,0 +1,317 @@
+<!-- hand-written -->
+---
+title: Game accessibility (subtitles, color-blind, remap, motor, cognitive)
+applies_to: [game-ui, accessibility, a11y]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Game accessibility
+
+Games are entertainment for everyone. ~15% of the global population has some disability; for games specifically, the impact areas are vision, hearing, motor, and cognitive.
+
+Modern AAA games (The Last of Us Part II, Forza Horizon, God of War Ragnarök) have raised the bar dramatically. Korean games are catching up, but still trail Western.
+
+## The four axes
+
+### 1. Vision
+
+- **Low vision**: small text, low contrast.
+- **Color blindness**: red-green most common.
+- **Total blindness**: rare in games; some screen-reader-supported games exist.
+
+### 2. Hearing
+
+- **Deaf / hard-of-hearing**: missing audio cues, missing dialogue.
+- **Sound sensitivity**: loud, sudden sounds.
+
+### 3. Motor / physical
+
+- **Limited dexterity**: rapid button presses, complex combos.
+- **Single-hand**: many games assume two hands on controller.
+- **Cognitive impact on motor**: tremor, RSI.
+
+### 4. Cognitive
+
+- **Reading speed**: subtitle pace.
+- **Attention / focus**: complex HUDs.
+- **Memory**: long sequences without notes.
+- **Reaction time**: time-pressured mechanics.
+
+## Universal options menu (the new standard)
+
+Modern games surface accessibility options prominently. Often a separate top-level menu (not buried under "Options").
+
+```
+┌──────────────────────────────────┐
+│ Accessibility                    │
+│ ───────────                       │
+│                                  │
+│ Display                          │
+│   • Subtitles            [On]   │
+│   • Subtitle size        [Med]  │
+│   • Subtitle background  [On]   │
+│   • Color-blind mode     [Off]  │
+│   • High contrast        [Off]  │
+│   • Brightness           [50%]  │
+│   • Reduce motion        [Off]  │
+│                                  │
+│ Audio                            │
+│   • Visual sound indicators [Off]│
+│   • Music volume         [80%]  │
+│   • Voice volume         [100%] │
+│                                  │
+│ Controls                         │
+│   • Remap buttons          ▶    │
+│   • Toggle hold-to-press   [On] │
+│   • Auto-aim             [Off]  │
+│                                  │
+│ Difficulty                       │
+│   • Combat difficulty   [Normal]│
+│   • Puzzle hints           [On] │
+│   • Story mode             [Off]│
+└──────────────────────────────────┘
+```
+
+## Subtitles + closed captions
+
+Subtitles: dialogue. Closed captions: dialogue + audio cues ("[footsteps approaching]").
+
+| Setting | Default | Options |
+| --- | --- | --- |
+| **On / off** | On | binary |
+| **Size** | Medium | Small / Med / Large / X-Large |
+| **Background** | Semi-transparent | None / Light / Dark / Black |
+| **Color** | White | White / Yellow / Custom |
+| **Speaker name** | On | binary |
+| **Sound effect cues** | Off | binary |
+
+For Korean games:
+- 자막 default ON (high default expectation).
+- Pretendard / NanumSquare; readable at distance.
+- Color contrast WCAG AA minimum.
+
+### Speaker labels
+
+```
+[Character name]: 안녕하세요!
+```
+
+Or color-coded per speaker:
+```
+[Hero — blue]: ...
+[Villain — red]: ...
+```
+
+## Color-blind modes
+
+Three main types:
+- **Protanopia / Protanomaly**: red-blind / weak.
+- **Deuteranopia / Deuteranomaly**: green-blind / weak.
+- **Tritanopia / Tritanomaly**: blue-yellow blind.
+
+Most common: red-green (deuteranopia ~6% of men).
+
+### Approaches
+
+| Approach | Pros | Cons |
+| --- | --- | --- |
+| **Color-blind preset filters** | Easy toggle | Affects whole game appearance |
+| **Color-blind-aware design from start** | No filter needed | More design work upfront |
+| **Custom color picker** | Player tunes individually | More complex UX |
+
+Best practice: **don't rely on color alone**. Reinforce with shape, pattern, position, or text:
+
+```
+Red enemy:    [shape: skull icon] + red color
+Green ally:   [shape: shield icon] + green color
+```
+
+Then color-blind filter is a backup, not the only way.
+
+For Korean MMO context:
+- Many enemies / allies use color exclusively. Modernize with shape redundancy.
+- Damage type icons (fire / ice / lightning) help.
+
+## Motor accessibility
+
+### Remappable controls
+
+EVERY button must be remappable. No exceptions.
+
+### Toggle vs hold
+
+For sustained actions (sprint, aim down sights):
+- **Hold** is default (intuitive).
+- **Toggle** option (less finger strain).
+
+```
+Sprint:  [Hold to sprint] / [Toggle sprint]
+```
+
+### Auto-aim / aim assist
+
+- **Off / Low / Medium / High** levels.
+- Helps reduced-dexterity players.
+- Competitive games may disable in PvP for fairness.
+
+### Reduce QTE (quick-time events)
+
+For QTEs (rapid button presses):
+- **Hold instead of press repeatedly** option.
+- **Auto-complete** option.
+- **Disable** option (may skip cinematic).
+
+### Difficulty options
+
+Common tiers:
+- **Story mode** — minimal challenge; focus on narrative.
+- **Easy** — forgiving.
+- **Normal** — default.
+- **Hard** — challenging.
+- **Expert / Nightmare** — punishing.
+
+Difficulty should be changeable mid-game. Don't lock players into a choice from main menu.
+
+## Cognitive accessibility
+
+### HUD options
+
+- **HUD on / off** toggle.
+- **Element-level toggles** (hide compass but show health).
+- **HUD scale** (50%-200%).
+- **Damage number visibility**.
+
+### Hint systems
+
+For puzzles:
+- **Auto-hint after N seconds**.
+- **Manual hint button**.
+- **Walkthrough mode** (full solve).
+
+Don't lock progression behind cognitively-difficult puzzle.
+
+### Tutorial
+
+- **Skip tutorial** (after first time).
+- **Replay tutorial** (open via menu).
+- **Tooltips toggle**.
+
+### Save anywhere / save often
+
+Don't require players to play 30+ minutes between saves. Allow:
+- **Manual save anywhere**.
+- **Auto-save frequently**.
+- **Cloud save** for cross-device.
+
+## Hearing accessibility
+
+### Visual sound indicators
+
+Show direction-of-sound for important audio cues:
+
+```
+[player center]
+              ↗ footsteps (faint)
+   ←  gunshot (loud)
+```
+
+Direction + intensity visualization. Critical for FPS deaf players.
+
+### Subtitled SFX
+
+Closed captions extend to:
+
+```
+[door creaking]
+[distant explosion]
+[heart beating fast]
+```
+
+Less common; Last of Us Part II does this well.
+
+### Audio sliders
+
+Per-channel:
+- Master.
+- Music.
+- Dialogue.
+- SFX.
+- Ambient.
+- Voice chat (multiplayer).
+
+Player can mute music, keep dialogue audible.
+
+## Motion sickness / reduced motion
+
+- **Camera shake** off / reduced.
+- **Field of view** adjustable (wider FOV = less nausea for some).
+- **Motion blur** off.
+- **Chromatic aberration** off.
+- **Head bob** off.
+- **Vignette** off.
+
+For VR specifically: comfort options critical (teleport vs smooth locomotion, reduced peripheral vision).
+
+## Color contrast in game UI
+
+WCAG-aligned guidelines:
+- **Body text**: 4.5:1 contrast against background.
+- **Large text** (18pt+): 3:1.
+- **HUD numbers**: 4.5:1 minimum.
+- **Subtitles**: 7:1 (higher because over moving backgrounds).
+
+Use a contrast checker. Don't ship with low-contrast UI.
+
+## Korean game accessibility
+
+Korean games have historically had less accessibility focus. Catching up:
+- 자막 toggles standard.
+- Color-blind options increasingly common.
+- Auto-battle helps motor-impaired (functional accessibility).
+- Localized subtitles (Korean / Japanese / Chinese / English).
+
+Areas where Korean games often lag:
+- Screen reader support (rare).
+- Visual sound indicators (rare).
+- Comprehensive remap (some games).
+
+Korean players with disabilities increasingly demand parity. Catching up to Western standards is a 2024+ trend.
+
+## Testing for accessibility
+
+Recommended:
+- **Test with players with disabilities**. AbleGamers, Special Effect provide consulting.
+- **Color-blind simulation tools** (Sim Daltonism, Color Oracle).
+- **Play with mute** (subtitle test).
+- **Play with one hand** (motor test).
+- **Play at low resolution / blurred** (vision test).
+
+## Resources
+
+- **AbleGamers** — accessibility consulting + community.
+- **Special Effect** — UK-based gaming accessibility.
+- **Game Accessibility Guidelines** (gameaccessibilityguidelines.com) — comprehensive checklist.
+- **CVAA** — US Communications and Video Accessibility Act; affects some online gaming.
+- **EU EAA** — EU Accessibility Act; mobile games included from 2025.
+
+## Don't
+
+- Don't bury accessibility in submenus. Top-level menu.
+- Don't lock difficulty.
+- Don't make accessibility opt-in for everything. Some defaults should be on (subtitles).
+- Don't rely only on color for crucial info.
+- Don't make remapping require an external tool.
+- Don't skip QTE accessibility.
+- Don't make tutorials non-skippable.
+- Don't ignore Korean players with disabilities. Same demands, same standards.
+
+## Cross-reference
+
+- [`knowledge/game-ui/game-ui-fundamentals.md`](game-ui-fundamentals.md) — fundamentals
+- [`knowledge/game-ui/hud-design.md`](hud-design.md) — HUD a11y
+- [`knowledge/game-ui/menu-systems.md`](menu-systems.md) — settings menu
+- [`knowledge/game-ui/korean-gaming-conventions.md`](korean-gaming-conventions.md) — KR market
+- [`knowledge/a11y/contrast.md`](../a11y/contrast.md) — color contrast standards
+- [`knowledge/a11y/keyboard-and-focus.md`](../a11y/keyboard-and-focus.md) — keyboard / focus