@design-ai/cli 4.55.0

package/knowledge/video/video-fundamentals.md

@@ -0,0 +1,296 @@
+<!-- hand-written -->
+---
+title: Video fundamentals (codecs, resolution, framerate, bitrate, captions)
+applies_to: [video, production, encoding, accessibility]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Video fundamentals
+
+Designing for video means thinking about more than visual composition. Every video has technical specs (codec, resolution, framerate, bitrate, audio) that determine quality, file size, compatibility, and accessibility.
+
+This file is the foundation for [`marketing-video.md`](marketing-video.md), [`social-and-short-form.md`](social-and-short-form.md), [`in-product-video.md`](in-product-video.md), and [`korean-video-conventions.md`](korean-video-conventions.md).
+
+## Resolution
+
+| Name | Pixels | Aspect | Use |
+| --- | --- | --- | --- |
+| **SD** | 720 × 480 | 4:3 | Legacy; rare today |
+| **HD / 720p** | 1280 × 720 | 16:9 | Mid-quality web |
+| **Full HD / 1080p** | 1920 × 1080 | 16:9 | Most common; YouTube standard |
+| **2K** | 2048 × 1080 | 17:9 | Cinema |
+| **4K UHD** | 3840 × 2160 | 16:9 | Premium delivery; 4× of 1080p |
+| **8K UHD** | 7680 × 4320 | 16:9 | Future; rare delivery |
+| **Vertical 1080** | 1080 × 1920 | 9:16 | Reels, Shorts, TikTok |
+| **Square 1080** | 1080 × 1080 | 1:1 | Instagram feed |
+
+Default delivery: **1080p (1920×1080)** for landscape, **1080×1920** for vertical. Shoot at 4K when possible (gives reframe headroom in post).
+
+## Framerate (fps)
+
+| fps | Use |
+| --- | --- |
+| **24** | Cinematic / film aesthetic |
+| **25** | PAL broadcast (KR uses NTSC, but online is fps-agnostic) |
+| **30 (29.97)** | NTSC broadcast; default for many online platforms |
+| **48 / 50** | High-frame "soap opera" effect |
+| **60** | Smooth motion, sports, gaming |
+| **120+** | Slow-motion source (slowed in post) |
+
+Default: **30fps** for product / marketing. **60fps** for product demos with motion (UI scrolling, gaming, fast action). **24fps** for cinematic / brand storytelling.
+
+Don't mix framerates within a single video — looks weird at cuts.
+
+## Codec and container
+
+| Container | Codec | Use |
+| --- | --- | --- |
+| **MP4** | H.264 (AVC) | Universal compatibility; default delivery |
+| **MP4** | H.265 (HEVC) | 50% smaller files at same quality; 2024+ widely supported |
+| **WebM** | VP9 | YouTube uses; smaller than H.264 |
+| **WebM** | AV1 | Newest; smallest files; nascent support |
+| **MOV** | ProRes | Editing master format; huge files |
+| **MKV** | Various | Personal libraries; not for delivery |
+
+For web delivery in 2024+: **MP4 / H.264** for compatibility, **MP4 / H.265** or **WebM / AV1** for smaller file size. Provide both; let the browser pick.
+
+## Bitrate
+
+Bitrate = data per second. Higher = better quality + larger files.
+
+| Resolution | fps | Bitrate (Mbps) for streaming |
+| --- | --- | --- |
+| 720p | 30 | 2.5-5 |
+| 1080p | 30 | 5-10 |
+| 1080p | 60 | 8-12 |
+| 4K | 30 | 15-25 |
+| 4K | 60 | 25-50 |
+
+For landing page autoplay video: **target 1-3 Mbps** (small file size, optimized for mobile data). Compress aggressively; the eye forgives more than designers expect.
+
+For YouTube delivery: YouTube re-encodes anyway, so upload at higher bitrate (10-50 Mbps for 1080p source) and let the platform optimize.
+
+## Audio
+
+| Spec | Default |
+| --- | --- |
+| Codec | AAC |
+| Sample rate | 48 kHz |
+| Channels | Stereo (2 ch) |
+| Bitrate | 128-256 kbps |
+
+For voice-only / product demos: 96-128 kbps mono is enough.
+For music / cinematic: 192-256 kbps stereo.
+
+### Loudness
+
+Online platforms normalize loudness:
+- **YouTube**: -14 LUFS integrated.
+- **Instagram / TikTok**: -14 LUFS approx.
+- **Cinema**: -23 to -27 LUFS.
+- **Broadcast (KR)**: -23 LUFS (방송통신위원회 standard).
+
+Mix to **-14 LUFS** for online delivery. Going louder = platforms turn it down. Going much quieter = users can't hear, abandon video.
+
+### Audio matters more than designers think
+
+Bad audio = users abandon faster than bad video. A pristine 4K shot with hissy audio reads as amateur. A blurry phone-shot with crisp audio reads as authentic.
+
+Invest in:
+- A real microphone (lavalier, shotgun, USB condenser).
+- Quiet recording environment.
+- Audio leveling in post.
+
+## Color space
+
+| Color space | Use |
+| --- | --- |
+| **sRGB / Rec. 709** | Standard web / HD; default |
+| **DCI-P3** | Wider gamut; modern displays; iPhone standard |
+| **Rec. 2020** | 4K / HDR; future |
+| **HDR (HDR10, Dolby Vision)** | Premium content with bright highlights |
+
+Default delivery: **Rec. 709 (sRGB equivalent)**. HDR for premium / cinematic only — most users don't have HDR displays.
+
+For Korean video: most platforms still SDR. HDR is "nice to have" but not standard.
+
+## Aspect ratios
+
+| Ratio | Use |
+| --- | --- |
+| **16:9 (1.78)** | YouTube, TV, landscape default |
+| **9:16 (0.56)** | Vertical (TikTok, Reels, Shorts, Stories) |
+| **1:1 (1.0)** | Instagram feed, square crops |
+| **4:5 (0.8)** | Instagram feed (taller, more screen) |
+| **2.35:1 / 2.39:1** | Cinema widescreen (anamorphic) |
+| **2:1 (2.0)** | Modern shows (Stranger Things etc.) |
+
+Plan ratio at shoot time. Cropping 16:9 to 9:16 wastes ~70% of frame and rarely works. Shoot 4K 16:9 if you need both 16:9 + 1:1 outputs (1:1 crops from center).
+
+## File size estimation
+
+Rough formula: **resolution × fps × bitrate × duration**.
+
+| Output | 30 sec file size |
+| --- | --- |
+| 1080p / 30fps / 5 Mbps | ~19 MB |
+| 1080p / 30fps / 2 Mbps (web optimized) | ~7.5 MB |
+| 4K / 30fps / 25 Mbps | ~94 MB |
+| Vertical 1080 / 30fps / 3 Mbps | ~11 MB |
+
+For autoplay marketing video: **target < 5MB for 5-15 second loops**. Above that, mobile users on cellular abandon.
+
+## Captions and subtitles
+
+### Why captions matter
+
+- **Accessibility**: deaf / hard-of-hearing users.
+- **Sound-off viewing**: 80%+ of social video viewed muted.
+- **Non-native speakers**: Korean → English markets, etc.
+- **SEO**: caption text indexed by search engines.
+- **Watch-time**: captioned videos retain viewers longer.
+
+### Format
+
+| Format | Use |
+| --- | --- |
+| **SRT** (.srt) | Universal; simplest |
+| **WebVTT** (.vtt) | Web video standard; supports styling |
+| **TTML** | Broadcast / cinema |
+| **Burned-in (open captions)** | Always-visible; can't disable |
+
+For web video: **WebVTT** sidecar files; let the platform / `<track>` element load them.
+
+For social video where captions need to be always-visible: burn them in at editing time (1-2 second visibility per phrase, styled to match brand).
+
+### Caption styling
+
+- **Position**: bottom center; avoid bottom 5% (cut off on some screens) — use bottom 10-15%.
+- **Background**: semi-opaque dark band behind text.
+- **Font**: sans-serif, condensed (more text fits per line).
+- **Size**: 4-6% of video height (1080p video = 40-60px).
+- **Line length**: ≤ 32 characters per line; ≤ 2 lines visible at once.
+- **Duration**: 1-7 seconds per caption; align with speech.
+
+### Korean captions
+
+- **Hangul reads larger** at the same point size — slightly smaller font OK (3.5-5% of video height).
+- **Line breaks**: break at natural phrase boundaries, not character count.
+- **자막 vs 폐쇄자막** — 자막 is open / always visible; 폐쇄자막 is closed / toggleable.
+
+### Auto-captioning
+
+Tools:
+- **YouTube** auto-captions: decent for English; OK for Korean; always review.
+- **Whisper (OpenAI)** open-source; excellent quality including Korean.
+- **Otter.ai / Rev / Descript**: paid services with auto + human review.
+- **Capcut, Canva Video**: built-in for short-form / social.
+
+Workflow: auto-generate → human review → export SRT / VTT → embed.
+
+## Loop video for marketing
+
+For autoplay landing-page hero loops:
+
+| Spec | Target |
+| --- | --- |
+| Duration | 5-15 seconds, seamlessly looping |
+| Resolution | 1080p source, often delivered at 720p |
+| Bitrate | 1-3 Mbps |
+| Audio | None (silent — autoplay browsers mute anyway) |
+| Format | MP4 (H.264) + WebM (VP9) for fallback |
+| Poster | Static frame for slow connections + reduced-motion |
+
+Optimization:
+- Use `ffmpeg -movflags +faststart` so video starts streaming before fully loaded.
+- Compress aggressively — landing-page video doesn't need 4K.
+- Provide `<video poster="...">` so something shows during load.
+
+## Production format vs delivery format
+
+Two stages:
+
+### Production (master)
+
+- 4K source if possible (gives crop / reframe headroom).
+- ProRes 422 or H.264 high-bitrate (50+ Mbps) for editing.
+- Lossless audio.
+- Color graded but not yet compressed.
+
+### Delivery
+
+- Compressed to platform's spec.
+- 1080p typically; 4K for premium.
+- Compressed audio (AAC).
+
+Don't deliver the master file (huge) and don't archive the delivery file (lossy). Keep both.
+
+## Performance for web video
+
+For HTML5 video:
+
+```html
+<video
+  autoplay
+  muted
+  loop
+  playsinline
+  poster="hero-poster.jpg"
+  preload="auto"
+>
+  <source src="hero.webm" type="video/webm" />
+  <source src="hero.mp4" type="video/mp4" />
+</video>
+```
+
+- `muted` is required for autoplay (browsers block audio on autoplay).
+- `playsinline` for iOS (otherwise full-screen).
+- `poster` for first paint / fallback.
+- Multiple sources for browser-pick.
+- `preload="auto"` for above-the-fold; `preload="metadata"` below.
+
+For lazy-loaded below-the-fold video: use IntersectionObserver to delay `load()`.
+
+For HLS streaming (longer videos, adaptive bitrate): use a player like Video.js, hls.js, or Shaka Player.
+
+## Accessibility
+
+- **Captions / subtitles** for any spoken content.
+- **Audio descriptions** for any visual content critical to understanding (separate audio track describing what's on screen).
+- **Transcripts** posted near the video (full text alternative).
+- **Don't auto-play with sound** — disorienting.
+- **Allow pause** on autoplay loops (control or click-to-pause).
+- **Respect `prefers-reduced-motion`** — show poster / static image instead of looping video.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  video.hero-loop {
+    display: none;
+  }
+  video.hero-loop ~ .poster-fallback {
+    display: block;
+  }
+}
+```
+
+## Don't
+
+- Don't ship 4K hero loops for marketing — bandwidth waste on mobile.
+- Don't auto-play with sound. Browsers block it; users hate it; accessibility issue.
+- Don't skip captions. 80% of social video watched muted.
+- Don't deliver MOV / ProRes for web — files are huge.
+- Don't shoot vertical at the last minute by cropping landscape — composition suffers.
+- Don't mix framerates within a video.
+- Don't ignore audio. Bad audio kills retention faster than bad video.
+- Don't ship video without a poster image — users see blank space during load.
+
+## Cross-reference
+
+- [`knowledge/video/marketing-video.md`](marketing-video.md) — landing-page / hero / brand video
+- [`knowledge/video/social-and-short-form.md`](social-and-short-form.md) — TikTok / Reels / Shorts
+- [`knowledge/video/in-product-video.md`](in-product-video.md) — onboarding / help / explainer
+- [`knowledge/video/korean-video-conventions.md`](korean-video-conventions.md) — KR-specific
+- [`knowledge/motion/motion-tools.md`](../motion/motion-tools.md) — Lottie alternative for shorter motion
+- [`knowledge/a11y/contrast.md`](../a11y/contrast.md) — caption contrast rules

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@design-ai/cli",
+  "version": "4.55.0",
+  "description": "Senior product designer for any AI coding agent. Installs design-ai (20 skills, 17 commands, 4 agents) into Claude Code globally. Korean market depth plus website improvement control tower.",
+  "bin": {
+    "design-ai": "cli/bin/design-ai.mjs",
+    "design-ai-mcp": "cli/bin/design-ai-mcp.mjs"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test cli/lib/*.test.mjs",
+    "audit": "python3 -B tools/audit/run-all.py",
+    "audit:strict": "python3 -B tools/audit/run-all.py --strict",
+    "audit:runner:self-test": "python3 -B tools/audit/run-all.py --self-test",
+    "coverage:self-test": "python3 -B tools/audit/check-coverage.py --self-test",
+    "doctor:assertions:self-test": "python3 -B tools/audit/doctor_assertions.py --self-test",
+    "smoke:assertions:self-test": "python3 -B tools/audit/smoke_assertions.py --self-test",
+    "package:check": "python3 -B tools/audit/package-contents.py --self-test && python3 -B tools/audit/package-contents.py",
+    "package:smoke:self-test": "python3 -B tools/audit/package-smoke.py --self-test",
+    "package:smoke": "python3 -B tools/audit/package-smoke.py --pack",
+    "registry:smoke": "python3 -B tools/audit/registry-smoke.py",
+    "registry:smoke:self-test": "python3 -B tools/audit/registry-smoke.py --self-test",
+    "release:metadata": "python3 -B tools/audit/release-metadata.py",
+    "release:metadata:self-test": "python3 -B tools/audit/release-metadata.py --self-test",
+    "ci:local:self-test": "python3 -B tools/audit/local-ci.py --self-test",
+    "tokens:ant-design:self-test": "python3 -B tools/extractors/ant_design_tokens.py --self-test",
+    "release:self-test": "npm run audit:runner:self-test && npm run coverage:self-test && npm run doctor:assertions:self-test && npm run smoke:assertions:self-test && npm run package:smoke:self-test && npm run registry:smoke:self-test && npm run release:metadata:self-test && npm run ci:local:self-test && npm run tokens:ant-design:self-test",
+    "release:check": "npm test && npm run audit:strict && git diff --check && npm run package:check && npm run release:metadata && npm run release:self-test && npm run package:smoke",
+    "ci:local": "python3 -B tools/audit/local-ci.py",
+    "preview": "python3 -B tools/preview/render-tokens.py"
+  },
+  "keywords": [
+    "design",
+    "design-system",
+    "website",
+    "seo",
+    "performance",
+    "ui",
+    "ux",
+    "design-tokens",
+    "claude-code",
+    "claude-code-plugin",
+    "ai-agent",
+    "mcp",
+    "model-context-protocol",
+    "korean",
+    "motion",
+    "illustration",
+    "print",
+    "video",
+    "game-ui",
+    "conversational",
+    "spatial",
+    "vr",
+    "ar"
+  ],
+  "author": "Sungjin Park <sungjin9288@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sungjin9288/design-ai.git"
+  },
+  "homepage": "https://github.com/sungjin9288/design-ai#readme",
+  "bugs": {
+    "url": "https://github.com/sungjin9288/design-ai/issues"
+  },
+  "files": [
+    "cli/",
+    "install.sh",
+    "AGENTS.md",
+    "AGENTS.ko.md",
+    "CLAUDE.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "README.ko.md",
+    ".claude-plugin/",
+    "knowledge/",
+    "examples/",
+    "skills/",
+    "agents/",
+    "commands/",
+    "docs/",
+    "!docs/case-study.md",
+    "!docs/evidence-checklist.md",
+    "!docs/evidence-gallery.md",
+    "!docs/implementation-evidence.md",
+    "!docs/interview-story.md",
+    "!docs/project-card.md",
+    "!docs/project-roadmap.md",
+    "!docs/readme-improvement.md",
+    "!docs/resume-bullets.md",
+    "tools/audit/",
+    "tools/migrations/",
+    "tools/preview/",
+    "!**/__pycache__/**",
+    "!**/*.pyc",
+    "!cli/**/*.test.mjs",
+    "!cli/**/*.test.js",
+    "!cli/**/*.spec.mjs",
+    "!cli/**/*.spec.js"
+  ]
+}

package/skills/README.md

@@ -0,0 +1,39 @@
+# Skills
+
+Task-focused playbooks. Each skill is a directory containing:
+
+- `SKILL.md` — Claude Code-compatible manifest (frontmatter + body). Auto-loaded if dropped under `~/.claude/skills/`.
+- `PLAYBOOK.md` — Plain-markdown version for Codex CLI / any agent. Same content as `SKILL.md`.
+- `TEMPLATE.md` — Optional output template.
+- `examples/` — Optional worked examples.
+
+| Skill | When to use |
+| --- | --- |
+| [design-system-builder](design-system-builder/PLAYBOOK.md) | Bootstrap a complete design system from a brand brief or single brand color. |
+| [component-spec-writer](component-spec-writer/PLAYBOOK.md) | Produce a developer-ready spec sheet for a single component. |
+| [color-palette](color-palette/PLAYBOOK.md) | Generate a full palette (ramps + semantic aliases + dark mode) from inputs. |
+| [ux-audit](ux-audit/PLAYBOOK.md) | Audit a screen, flow, or page against UX best practices and a11y. |
+| [design-critique](design-critique/PLAYBOOK.md) | Senior-designer feedback on a design proposal. |
+| [handoff-spec](handoff-spec/PLAYBOOK.md) | Produce a developer handoff document from a finalized design. |
+| [design-system-qa](design-system-qa/PLAYBOOK.md) | Audit a design system across 5 testing layers (types / tokens / contract / a11y / visual) and recommend CI integration. |
+| [design-pr-review](design-pr-review/PLAYBOOK.md) | Review a GitHub PR for design system compliance. Uses GitHub MCP when connected. |
+| [website-improvement](website-improvement/PLAYBOOK.md) | Plan a website improvement control tower with Site Profile, audit pipeline, MCP readiness, refactor tasks, prompts, and handoff report. |
+| [figma-token-sync](figma-token-sync/PLAYBOOK.md) | Sync tokens between Figma and code. Uses Figma MCP. |
+| [design-broadcast](design-broadcast/PLAYBOOK.md) | Post artifacts to Slack / Notion. Uses Slack + Notion MCPs. |
+| [document-author](document-author/PLAYBOOK.md) | Write technical / product documentation. Picks the right Diátaxis type, applies template, follows technical-writing voice rules. Korean-aware. |
+| [slide-deck-author](slide-deck-author/PLAYBOOK.md) | Outline a slide deck (talk / pitch / reading). Message-led titles, brand-applied, Korean-aware. |
+| [motion-designer](motion-designer/PLAYBOOK.md) | Spec motion for a screen / component / page. Picks tool (CSS / Framer Motion / GSAP / Lottie / Rive), durations, easings, choreography. Reduced-motion-safe by default. |
+| [illustration-designer](illustration-designer/PLAYBOOK.md) | Design or spec an illustration system (or single illustration). Style, voice, color, format (SVG / Lottie / PNG), accessibility, SVG optimization. Korean-market-aware. |
+| [print-designer](print-designer/PLAYBOOK.md) | Spec a print piece — business card, brochure, poster, packaging, stationery. CMYK + Pantone, bleed, finish, regulatory content; Korean print conventions. |
+| [video-designer](video-designer/PLAYBOOK.md) | Spec video for marketing, social, or in-product use. Length, format, aspect, codec, captions, voiceover; Korean ad disclosure + KFDA compliance. |
+| [game-ui-designer](game-ui-designer/PLAYBOOK.md) | Spec game UI — HUD, menus, inventory, store — across genres + platforms. Korean gaming conventions (확률 표시, 본인인증, PC bang) + accessibility. |
+| [conversational-ui-designer](conversational-ui-designer/PLAYBOOK.md) | Spec a conversational UI — voice assistant, chatbot, AI chat (LLM), or live agent. Modality, persona (해요체 / 합쇼체), intents, flows, Korean conventions (Bixby / Clova / KakaoTalk channel). |
+| [spatial-designer](spatial-designer/PLAYBOOK.md) | Spec spatial / AR / VR / MR experiences. Platform (Vision Pro / Quest / HoloLens / mobile AR / WebXR), anchoring, locomotion (teleport / smooth / snap turn), comfort, accessibility, Korean Galaxy XR. |
+
+## Invoking a skill
+
+**Claude Code**: skills are auto-discovered. Reference by name: "Use the `color-palette` skill to..."
+
+**Codex CLI** (or any other agent): paste the contents of `PLAYBOOK.md` into your prompt, or have the agent `cat` it.
+
+**Self-hosted prompt**: include the playbook in your system prompt. Each playbook is self-contained.

package/skills/color-palette/PLAYBOOK.md

@@ -0,0 +1,175 @@
+# color-palette — playbook
+
+Generate a complete, accessible color palette from a single seed (brand color, mood word, or product category).
+
+## When to use
+
+- "Build me a color palette for a fintech app" → product category input.
+- "I have brand red `#E63946`, build the system" → seed color input.
+- "Generate a calm, premium palette" → mood input.
+
+## Inputs (ask if missing)
+
+1. **Seed** — one of:
+   - A hex (brand primary).
+   - A product category (e.g., `e-commerce`, `health-tech`, `developer-tools`).
+   - A mood (e.g., `playful`, `editorial`, `brutalist`).
+2. **Light + dark, or light only?** — default both.
+3. **Target framework** — `tailwind v4`, `shadcn-ui`, `mui`, `antd`, `css variables`. Default: tailwind v4.
+4. **Korean / CJK content?** — affects neutral choice (slight warm bias often reads cleaner with Hangul).
+
+## Steps
+
+### 1. If seed is a category or mood, find a reference
+
+Open [`knowledge/colors/palettes-by-product-type.md`](../../knowledge/colors/palettes-by-product-type.md). Match by **Product type** column. Pull the row's tokens as a starting point. Do **not** copy verbatim — adapt.
+
+If mood-based, open [`knowledge/patterns/styles-catalog.md`](../../knowledge/patterns/styles-catalog.md) and pull the matching style's `Primary Colors` and `Secondary Colors`.
+
+#### Mood → hue mapping (when no reference matches)
+
+When neither a hex nor a category is given — only mood words like "trustworthy", "energetic", "calm" — translate to a starting hue + chroma + lightness range. These are starting points; adjust based on differentiation needs (every fintech being blue is the trap).
+
+| Mood | Hue family (OKLCH H) | Chroma | Lightness anchor (step 600) |
+| --- | --- | --- | --- |
+| Trustworthy / financial | Blue 230–250°, teal 170–195° | 0.18–0.24 | L ~ 50% |
+| Energetic / playful | Red-orange 20–60°, magenta 0–30°, yellow 70–100° | 0.20–0.28 (high) | L ~ 55–65% |
+| Calm / wellness | Green 130–160°, soft blue 200–230°, sage | 0.10–0.16 (muted) | L ~ 50–60% |
+| Premium / luxury | Near-monochrome — purple 290–320° low chroma, charcoal | 0.05–0.12 | L ~ 35–50% (darker anchor) |
+| Editorial / refined | Burgundy 0–20°, sage 130–160°, deep blue 230–260° | 0.12–0.18 | L ~ 40–50% |
+| Youthful / approachable | Coral 10–30°, mint 160–180°, lavender 280–300° | 0.16–0.22 | L ~ 60–70% (lighter) |
+| Tech / futuristic | Electric blue 240–260°, cyan 195–215°, magenta 290–320° | 0.20–0.28 | L ~ 55–65% |
+| Natural / organic | Earth green 100–140°, brown 30–60°, ochre 70–90° | 0.10–0.16 | L ~ 45–55% |
+| Brutalist / bold | Pure primaries 0°/240°/60°, plus near-black + white | 0.25+ (max) | L ~ 50% |
+| Minimal / Swiss | Near-neutral, single accent | < 0.05 | L ~ 30% (dark accent on white) |
+
+Combining moods: bias by primary mood, then adjust toward secondary. "Trustworthy + Youthful" → start at trustworthy blue/teal, shift L up to ~60%, slightly raise C.
+
+#### Differentiation check
+
+Before committing to the mood-derived anchor, check the local market's dominant brands in the same category:
+
+```
+Korean fintech competitors:
+- Toss: blue #3182F6
+- KakaoBank: yellow + accent #FFEB00
+- Naver Pay: green
+- Shinhan: blue
+- KB Star: blue
+
+→ Avoid: another blue at L=50%, H=230°. Differentiate with teal,
+  warmer accent, or shift hue 30°+ from competitors.
+```
+
+Cite [`knowledge/patterns/brand-references.md`](../../knowledge/patterns/brand-references.md) for visual peer comparison if available.
+
+#### Korean considerations
+
+For Korean-primary apps:
+- Slight warm bias on neutrals (slate H ~ 240–260° preferred over cool steel-gray) — reads cleaner with Hangul.
+- For stock/trading apps: account for Korean color convention (red=up, blue=down) — see [`knowledge/patterns/money-and-amount.md`](../../knowledge/patterns/money-and-amount.md).
+- For consumer/B2C: avoid pure yellow primary (Kakao-coded) and pure green (Naver-coded) unless intentional brand alignment.
+
+### 2. Convert seed to OKLCH
+
+Stay in OKLCH for the entire generation. Only convert to HEX/RGB at output. See [`knowledge/colors/color-theory.md`](../../knowledge/colors/color-theory.md) for why.
+
+### 3. Build the primary ramp
+
+11 stops: `50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950`.
+
+- `L` (lightness) starts at ~98% (step 50), decreases by ~8% per step, ending at ~12% (step 950).
+- `C` (chroma) peaks at step 500–600 (where the brand sits) and falls toward both ends.
+- `H` (hue) **stays constant**.
+
+Validate: step 600 must clear **4.5:1 against white** for body text. If not, the seed is too light — raise the seed's chroma or shift the ramp anchor up by one step.
+
+### 4. Pick semantic anchors from the ramp
+
+```
+--color-primary-default: <step that hits 4.5:1 on white, usually 600>
+--color-primary-hover:   <one step darker, 700>
+--color-primary-active:  <two steps darker, 800>
+--color-primary-subtle:  <step 50 or 100, for backgrounds>
+--color-on-primary:      <white if primary-default L < 60%, else step 950>
+```
+
+### 5. Build accent and neutrals
+
+- **Accent**: rotate hue by 60–120° in OKLCH from primary, hold L/C constant. Build a parallel 11-step ramp.
+- **Neutrals**: build a gray ramp with **slight chroma matching primary's hue** (C ≈ 0.01–0.02). Pure C=0 reads cold.
+- **Semantic non-brand**: green-600 (success), amber-500 (warning), red-600 (error), blue-600 or primary (info). Build full ramps for each.
+
+### 6. Validate WCAG
+
+Build a contrast matrix:
+
+```
+            on white  on neutral-50  on neutral-900
+primary-600    X.X       X.X            X.X
+text-primary   X.X        ✓              ✓
+text-secondary X.X        ✓              ✓
+border         3.0+      3.0+           3.0+
+```
+
+Every cell that hosts UI must hit:
+- 4.5:1 if it's text on a background.
+- 3:1 if it's a border, icon, or large text.
+
+Cite [`knowledge/a11y/contrast.md`](../../knowledge/a11y/contrast.md) when explaining failures.
+
+### 7. Build dark mode
+
+Don't invert. Recompute:
+
+- New `background-default`: OKLCH(0.18 0.005 H_neutral) — near-black with the neutral hue.
+- New `background-elevated`: +0.02 L from default.
+- Increase chroma on accents by 10–20% — low-light eye is less saturated.
+- `primary-default` for dark mode = a step closer to step 400 from the original ramp (lighter so it reads against the dark BG).
+- Re-run the contrast matrix for dark mode.
+
+### 8. Output
+
+Use the [TEMPLATE.md](TEMPLATE.md) format. Always emit:
+
+1. **Reasoning paragraph** — why this palette fits the brief.
+2. **Token table** — all named tokens with hex values.
+3. **Code blocks** — one per requested framework (CSS vars + Tailwind config + JSON).
+4. **Contrast matrix** — pass/fail for every UI-relevant pair.
+5. **Use guidance** — when to use primary vs accent, what NOT to do.
+6. **Dark mode** (if requested) — same shape, separate section.
+
+## Source files this skill reads
+
+- [`knowledge/colors/color-theory.md`](../../knowledge/colors/color-theory.md)
+- [`knowledge/colors/palettes-by-product-type.md`](../../knowledge/colors/palettes-by-product-type.md)
+- [`knowledge/colors/mui-palette-structure.md`](../../knowledge/colors/mui-palette-structure.md)
+- [`knowledge/a11y/contrast.md`](../../knowledge/a11y/contrast.md)
+- [`knowledge/design-tokens/ant-design.md`](../../knowledge/design-tokens/ant-design.md)
+- [`knowledge/patterns/styles-catalog.md`](../../knowledge/patterns/styles-catalog.md) — only when mood-based input
+- [`knowledge/patterns/brand-references.md`](../../knowledge/patterns/brand-references.md) — for differentiation against peers
+- [`knowledge/patterns/money-and-amount.md`](../../knowledge/patterns/money-and-amount.md) — when palette is for fintech / money-aware UI
+
+## Verification phase (run before declaring done)
+
+Self-check the output against this checklist. If any answer is "no" or "unsure", revise.
+
+- [ ] Did I cite at least one knowledge file for each major claim category (palette construction, contrast, dark mode)?
+- [ ] Does every UI-relevant text-on-bg pair have an explicit contrast ratio in the matrix?
+- [ ] Does the matrix flag ✓ for AA where required and identify failures (rather than silently omit)?
+- [ ] If mood-based: did I document **why** I picked this hue family (which mood mapping)?
+- [ ] If category-based: did I cite the source row from `palettes-by-product-type.md`?
+- [ ] Is the differentiation check articulated (which competitors I'm avoiding)?
+- [ ] Is dark mode recomputed (separate values) or just stated to be inverted? (Should be recomputed.)
+- [ ] Is the focus-ring color verified at 3:1 against BOTH page bg AND the primary button bg?
+- [ ] Are money-positive / money-negative tokens included if the palette is for fintech?
+- [ ] Are the code blocks for the target framework actually paste-ready (no placeholder values)?
+
+## Done when
+
+- Every token has a name, a hex, and a role.
+- Every UI-relevant pair has a contrast number.
+- Code blocks for at least one target framework are paste-ready.
+- A "use guidance" section tells the user when to reach for primary vs accent vs neutral.
+- Dark mode is recomputed (if requested), not inverted.
+- The verification phase checklist passes.

package/skills/color-palette/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: color-palette
+description: Generate a complete, accessible color palette with ramps, semantic aliases, dark mode, and WCAG-validated contrast from a seed (brand color, product category, or mood).
+---
+
+See [PLAYBOOK.md](PLAYBOOK.md) — same content. The playbook is the source of truth. This file exists so Claude Code's skill loader recognizes the directory.