@design-ai/cli 4.55.0

package/skills/figma-token-sync/PLAYBOOK.md

@@ -0,0 +1,149 @@
+# figma-token-sync — playbook
+
+Sync design tokens between Figma and code. When Figma MCP is connected, reads/writes Variables directly. Without MCP, falls back to Tokens Studio plugin export workflow.
+
+## When to use
+
+- "Pull tokens from this Figma file"
+- "Export our code tokens to Figma"
+- "Verify Figma tokens match our code"
+- Pre-release: confirm Figma + code are in sync.
+
+## Inputs (ask if missing)
+
+1. **Direction**:
+   - `figma → code`: pull from Figma into code's `tokens/source.json`.
+   - `code → figma`: push from code into Figma Variables.
+   - `verify`: read both, diff, report.
+2. **Figma file URL** (with `file_key`).
+3. **Code token path**: usually `tokens/source.json` in the consuming project.
+4. **Mode mapping**: which Figma mode = light, which = dark?
+
+## Steps
+
+### 1. Detect MCP availability
+
+```
+if mcp__Figma is connected:
+  proceed with full read/write workflow
+else:
+  walk through Tokens Studio plugin manual flow
+```
+
+### 2. Read tokens from Figma
+
+```
+mcp__Figma__get_variable_defs(file_key=<...>)
+→ returns all Variables grouped by collection
+```
+
+Transform into design-ai's W3C DTCG / Style Dictionary format:
+
+```json
+{
+  "color": {
+    "brand": {
+      "primary": {
+        "600": { "$value": "#7C3AED", "$type": "color" }
+      }
+    }
+  }
+}
+```
+
+Notes:
+- Figma's collection name → top-level key.
+- Variable name (with slashes for hierarchy) → dot-separated nested keys.
+- Multi-mode (light/dark) → separate output OR `$value` map per mode.
+
+### 3. Read tokens from code
+
+```
+read tokens/source.json from the consuming project
+```
+
+Already in W3C DTCG format (assumption).
+
+### 4. Diff (verify mode)
+
+For each token path:
+
+| Status | Action |
+| --- | --- |
+| In both, value matches | ✓ in sync |
+| In both, value differs | ⚠ drift — show both values, ask user which is canonical |
+| In Figma only | Code is missing this token — add or warn |
+| In code only | Figma is missing — push or warn |
+
+Output report:
+
+```
+Token sync report
+
+✓ 38 tokens in sync
+⚠ 4 tokens drifted:
+  - color.primary.default: code=#7C3AED, figma=#8B5CF6
+  - spacing.md: code=12px, figma=16px
+  - ...
+
+→ 2 tokens in code only (not in Figma):
+  - color.money-positive
+  - color.money-negative
+
+← 1 token in Figma only (not in code):
+  - color.experimental.purple
+```
+
+### 5. Push tokens code → Figma
+
+For each token in `tokens/source.json`:
+
+```
+mcp__Figma__... (write Variable in the appropriate collection)
+```
+
+⚠ As of mid-2025, Figma MCP's WRITE operations for Variables are limited. The Tokens Studio plugin is more capable for true bidirectional sync.
+
+For now: agent can READ from Figma reliably; for WRITE, recommend Tokens Studio.
+
+### 6. Without MCP — fallback to Tokens Studio
+
+```
+1. User: install Tokens Studio for Figma plugin (free tier OK).
+2. In Figma: Plugins → Tokens Studio → Import → paste tokens/source.json.
+3. Apply to Figma.
+4. Output: "Imported via Tokens Studio. Verify in Variables panel."
+```
+
+For verify mode without MCP:
+1. User: in Tokens Studio, Export → Tokens Studio JSON.
+2. Save to /tmp/figma-tokens.json.
+3. Agent: diff against tokens/source.json. Output report.
+
+### 7. Apply changes (or stop and ask)
+
+For destructive operations (push, overwrite), stop after diff and confirm before proceeding. Read-only diff/verify operations can complete without confirmation.
+
+## Verification phase (run before declaring done)
+
+- [ ] Did I confirm direction (figma→code / code→figma / verify) before acting?
+- [ ] Did I check for write access before pushing (read-only auth = abort)?
+- [ ] Did I show the diff to user before applying changes?
+- [ ] Did I cite the source-of-truth strategy ([`docs/TOKEN-SYNC.md`](../../docs/TOKEN-SYNC.md))?
+- [ ] Did I warn about MCP write limitations when relevant?
+- [ ] Did I produce a final report with synced / drifted / extra counts?
+
+## Source files this skill reads
+
+- [`docs/TOKEN-SYNC.md`](../../docs/TOKEN-SYNC.md) — three-tier source-of-truth strategy
+- [`docs/integrations/figma-mcp.md`](../../docs/integrations/figma-mcp.md) — MCP usage details
+- [`docs/FIGMA-INTEGRATION.md`](../../docs/FIGMA-INTEGRATION.md) — broader Figma workflows
+- [`knowledge/design-tokens/ant-design.md`](../../knowledge/design-tokens/ant-design.md) — token format references
+
+## Done when
+
+- Tokens are in sync OR diff is shown for user to resolve.
+- Direction was explicit (no surprise writes).
+- Tokens Studio fallback used cleanly when MCP unavailable.
+- Output includes summary stats (counts: synced / drifted / extra).
+- Verification phase passes.

package/skills/figma-token-sync/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: figma-token-sync
+description: Sync design tokens between Figma and code. Reads Figma Variables via MCP (or Tokens Studio fallback), diffs against tokens/source.json, applies changes in the requested direction (figma→code / code→figma / verify-only).
+---
+
+See [PLAYBOOK.md](PLAYBOOK.md).

package/skills/game-ui-designer/PLAYBOOK.md

@@ -0,0 +1,209 @@
+# game-ui-designer — playbook
+
+Design and spec game UI — HUD, menus, inventory, store, settings, in-world UI. Output is a UI spec a game designer / engineer can implement against, accounting for genre conventions, target platform(s), input methods, and accessibility.
+
+## When to use
+
+- "Design the HUD for our top-down RPG."
+- "Spec the inventory system for our gacha mobile game."
+- "What menu structure should our FPS use?"
+- "Design the Korean gacha store with 확률 표시."
+- "Plan accessibility for our action game."
+
+## Inputs (ask if missing)
+
+1. **Genre** — FPS / RPG / MMO / gacha / casual / strategy / racing / fighting.
+2. **Platform(s)** — PC / console / mobile / VR; combinations.
+3. **Input method(s)** — keyboard+mouse / controller / touch / mixed.
+4. **Audience** — Korean / international / mixed; casual / hardcore.
+5. **Surface** — HUD / main menu / pause / inventory / settings / store / character screen.
+6. **Monetization** — F2P + gacha / premium / battle pass / ads.
+7. **Brand voice** — cinematic realistic / anime / cartoon / pixel.
+8. **Accessibility scope** — full WCAG / minimum / target features.
+
+## Steps
+
+### 1. Classify genre + surface
+
+| Genre | Read |
+| --- | --- |
+| FPS / TPS / Action | [`hud-design.md`](../../knowledge/game-ui/hud-design.md) §FPS HUD |
+| RPG / MMO | [`hud-design.md`](../../knowledge/game-ui/hud-design.md) §MMO HUD + [`menu-systems.md`](../../knowledge/game-ui/menu-systems.md) |
+| Mobile gacha | [`hud-design.md`](../../knowledge/game-ui/hud-design.md) §Mobile gacha + [`korean-gaming-conventions.md`](../../knowledge/game-ui/korean-gaming-conventions.md) |
+| Casual / puzzle | [`hud-design.md`](../../knowledge/game-ui/hud-design.md) §Casual |
+| Strategy | [`hud-design.md`](../../knowledge/game-ui/hud-design.md) §Strategy |
+
+Always read [`game-ui-fundamentals.md`](../../knowledge/game-ui/game-ui-fundamentals.md). If Korean: [`korean-gaming-conventions.md`](../../knowledge/game-ui/korean-gaming-conventions.md). Always plan accessibility per [`game-accessibility.md`](../../knowledge/game-ui/game-accessibility.md).
+
+### 2. Spec platform(s)
+
+For each platform:
+
+| Platform | UI scale | Reading distance | Input |
+| --- | --- | --- | --- |
+| PC monitor | 1× | 50-100cm | Mouse + keyboard |
+| Console (TV) | 1.3-1.5× | 2-4m | Controller |
+| Mobile portrait | 1× | 30cm | Touch (thumb zones) |
+| Mobile landscape | 1× | 30-50cm | Touch (both thumbs) |
+| VR | per platform | (visual angle) | Motion controllers |
+
+For cross-platform: design UI that scales without retooling.
+
+### 3. Pick layout per genre
+
+Use canonical layouts from `hud-design.md`. Don't reinvent unless specific game design requires.
+
+For HUD, anchor major elements:
+- **Bottom-left**: typically player status (HP/MP).
+- **Bottom-right**: ammo / resources.
+- **Bottom-center**: hotbar (RPG/MMO).
+- **Top-left** OR **top-right**: mini-map.
+- **Top-center**: objective.
+- **Center**: crosshair (FPS) or empty.
+
+For menus, pick standard structure. Settings menu has near-universal section breakdown.
+
+### 4. Spec input handling
+
+Per platform:
+
+- **Keyboard**: define hotkeys; consistent with genre conventions.
+- **Controller**: button-prompt mappings (Xbox / PS variants); focus management.
+- **Touch**: thumb zones; tap targets ≥ 44pt; gesture support.
+
+Show button prompts for the active input. Detect at runtime.
+
+### 5. Spec interaction states
+
+For every interactive element:
+- **Default** — resting.
+- **Hovered / focused** — visible cue.
+- **Pressed** — feedback.
+- **Disabled** — grayed.
+- **Selected** — current.
+
+Plus genre-specific:
+- **Cooldown** — sweep / fade for skills.
+- **Locked** — for unowned items / unranked features.
+- **New** — badge for unviewed.
+
+### 6. Plan accessibility
+
+Per [`game-accessibility.md`](../../knowledge/game-ui/game-accessibility.md):
+
+- [ ] Subtitles + closed captions toggle + size + background options
+- [ ] Color-blind mode (protanopia / deuteranopia / tritanopia)
+- [ ] High contrast mode
+- [ ] UI scale (50-200%)
+- [ ] Remappable controls
+- [ ] Toggle vs hold for sustained actions
+- [ ] Reduced motion option
+- [ ] Audio sliders per channel (master, music, dialogue, SFX)
+- [ ] Visual sound indicators (for hearing-impaired in critical genres)
+- [ ] Difficulty options (story mode for cognitive accessibility)
+
+### 7. Korean compliance (if KR market)
+
+- [ ] **확률 표시** — gacha probability disclosure (REQUIRED).
+- [ ] **본인인증** — real-name verification flow.
+- [ ] **GRAC rating** — game rating shown.
+- [ ] 자막 default ON.
+- [ ] **PC bang** detection + bonuses (PC games).
+- [ ] **누적 보상 / 천장** — pity counter visible.
+- [ ] **출석 / VIP** — daily login + tier system.
+
+### 8. Spec performance
+
+Game UI renders every frame. Performance matters:
+
+- [ ] Sprite-based rendering (texture atlas)
+- [ ] Update only on state change
+- [ ] GPU animations
+- [ ] Mobile: target 60fps with HUD overhead < 5ms / frame
+- [ ] Console: scale tested at 4K
+- [ ] Ultra-wide / multi-aspect-ratio tested
+
+### 9. Spec audio
+
+- [ ] Click / hover sounds defined
+- [ ] Confirmation / error tones
+- [ ] Notification sounds per type (level up, item drop, achievement)
+- [ ] Spatial audio for VR
+
+### 10. Output
+
+```markdown
+# Game UI spec: <surface>
+
+> Genre: <FPS / RPG / MMO / gacha / casual / etc>
+> Platform(s): <PC / console / mobile / VR>
+> Input(s): <keyboard / controller / touch>
+> Audience: <KR / international>
+
+## Layout
+<anchored regions, element positioning>
+
+## Elements
+<HUD elements OR menu sections, each with size, color, behavior>
+
+## Interaction states
+<default / hover / focused / pressed / disabled / etc>
+
+## Input handling
+<keyboard / controller / touch mappings>
+
+## Accessibility
+<subtitles, color-blind, contrast, scale, reduce-motion, remap>
+
+## Korean compliance (if applicable)
+<확률 표시, 본인인증, GRAC, 자막, PC bang>
+
+## Performance budget
+<frame ms, draw calls, mobile target>
+
+## Audio
+<UI sounds defined>
+
+## Don't
+<2-3 specific misuses>
+```
+
+## Source files this skill reads
+
+- [`knowledge/game-ui/game-ui-fundamentals.md`](../../knowledge/game-ui/game-ui-fundamentals.md)
+- [`knowledge/game-ui/hud-design.md`](../../knowledge/game-ui/hud-design.md)
+- [`knowledge/game-ui/menu-systems.md`](../../knowledge/game-ui/menu-systems.md)
+- [`knowledge/game-ui/korean-gaming-conventions.md`](../../knowledge/game-ui/korean-gaming-conventions.md)
+- [`knowledge/game-ui/game-accessibility.md`](../../knowledge/game-ui/game-accessibility.md)
+- [`knowledge/a11y/contrast.md`](../../knowledge/a11y/contrast.md)
+- [`knowledge/a11y/keyboard-and-focus.md`](../../knowledge/a11y/keyboard-and-focus.md)
+- [`knowledge/motion/principles.md`](../../knowledge/motion/principles.md)
+- [`knowledge/i18n/korean-payments.md`](../../knowledge/i18n/korean-payments.md) — for 본인인증
+- [`examples/component-game-hud.md`](../../examples/component-game-hud.md)
+- [`examples/component-game-menu.md`](../../examples/component-game-menu.md)
+
+## Verification phase (run before declaring done)
+
+- [ ] Is the genre + surface explicit?
+- [ ] Is the platform list explicit + UI scaling addressed?
+- [ ] Does layout follow genre convention OR justify deviation?
+- [ ] Are all input methods (keyboard / controller / touch) supported with prompts?
+- [ ] Are interaction states (default / focus / press / disabled) defined?
+- [ ] Are accessibility options addressed (subtitles, color-blind, scale, remap, reduce-motion)?
+- [ ] If Korean: is 확률 표시 / 본인인증 / GRAC / 자막 covered?
+- [ ] Is performance budget specified?
+- [ ] Are UI audio sounds defined?
+- [ ] Does "Don't" section catch 2-3 specific misuses?
+
+## Done when
+
+- One markdown spec, < 500 lines.
+- Genre, platform(s), input(s), audience explicit.
+- Layout (anchored regions / sections) defined.
+- Interaction states specified.
+- Input handling per platform.
+- Accessibility plan.
+- Korean compliance if applicable.
+- Performance budget.
+- "Don't" section.
+- Verification passes.

package/skills/game-ui-designer/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: game-ui-designer
+description: Design and spec game UI — HUD, menus, inventory, store, settings — across genres (FPS, MMO, gacha, casual). Picks layout per genre + platform (PC, console, mobile), input handling, accessibility, and Korean conventions (확률 표시, 본인인증, PC bang).
+---
+
+See [PLAYBOOK.md](PLAYBOOK.md).

package/skills/handoff-spec/PLAYBOOK.md

@@ -0,0 +1,170 @@
+# handoff-spec — playbook
+
+Produce a developer handoff document from a finalized design. The output is a single markdown file an engineer can implement against without follow-up questions.
+
+## When to use
+
+- Design is approved and ready to ship; engineering needs a spec.
+- A Figma file has 6+ screens and devs keep DM'ing for clarifications.
+- Cross-team handoff (design → another team's eng).
+
+## Inputs (ask if missing)
+
+1. **Designs** — Figma link or screenshots of the final state.
+2. **Scope** — single feature, full screen, multi-screen flow.
+3. **Tech stack** — for code-side conventions (Tailwind class hints, MUI props, etc.).
+4. **Existing design system?** — if yes, name it and let the spec reference tokens; if no, inline the values.
+5. **Audience** — frontend dev, full-stack, design engineer.
+
+## Steps
+
+### 1. Inventory
+
+List every screen and every reusable component on each. If components are repeated, note them once and reference.
+
+### 2. For each screen, document
+
+- **Purpose** — one sentence on what the screen accomplishes.
+- **Entry points** — how the user reaches it (route, button, deep link).
+- **Exit points** — what actions navigate away and where.
+- **Layout** — wireframe diagram + breakpoints behavior.
+- **States** — empty, loading, error, success, partial data.
+- **Edge cases** — what happens with very long content, zero items, network failure.
+
+### 3. For each component, document
+
+If it's an existing system component, just reference it: "Use `<Button intent='primary' size='lg'>` from our system." Don't re-spec.
+
+If it's new, follow the [`component-spec-writer`](../component-spec-writer/PLAYBOOK.md) skill's playbook to produce a full sub-spec.
+
+### 4. Document interactions
+
+For every interactive element, document:
+
+| Element | Trigger | Action |
+| --- | --- | --- |
+| `Save` button | click / `Enter` while focused | Persist form, show toast on success, redirect to detail page |
+| `Discard` link | click | Open confirmation modal; on confirm, route to list |
+
+### 5. Document data and content
+
+- **Data shape** — what does the server return? What's required vs optional?
+- **Content rules** — character limits, validation rules, empty-string behavior.
+- **i18n** — keys used, plurals, RTL considerations.
+- **Tone** — formal/casual; example copy that hits the bar.
+
+### 6. Document responsive behavior
+
+For each breakpoint (xs/sm/md/lg/xl), describe:
+- Layout changes (column count, sidebar collapse, nav transformation).
+- Component swaps (e.g., "tabs become accordion below `md`").
+- Hidden / shown elements.
+
+### 7. Document a11y requirements
+
+- Semantic HTML expected (which `<h1>` / `<nav>` / `<main>` lives where).
+- Keyboard interaction map (what `Tab` reaches, in what order).
+- ARIA roles / properties for complex widgets.
+- Focus management (where focus goes on route change, modal open/close).
+- Announcements (live regions for toast/error).
+
+### 8. Document analytics events (if applicable)
+
+| Event name | Trigger | Properties |
+| --- | --- | --- |
+| `signup_completed` | After successful signup | `method`, `referrer`, `plan` |
+
+### 9. Open questions (be explicit)
+
+Don't leave decisions implicit. List anything ambiguous:
+
+> **Open**: When the user has 0 saved items, do we show the empty state OR auto-redirect to onboarding? Need product to decide before ship.
+
+### 10. Output
+
+```markdown
+# Handoff: <feature name>
+
+> Designs: <link>
+> System: <existing? name?>
+> Stack: <stack>
+> Owner: <name>
+> Status: ready-for-implementation
+
+## Summary
+<3 sentences: what this is, who it's for, what done looks like>
+
+## Screens
+### <Screen 1 name>
+- Purpose:
+- Entry/Exit:
+- Layout (with sketch):
+- States:
+- Edge cases:
+
+### <Screen 2 name>
+...
+
+## Components
+### <Component A>
+- (existing system component, no re-spec) | (full sub-spec inline)
+
+## Interactions
+<table>
+
+## Data and content
+- ...
+
+## Responsive
+- xs: ...
+- md: ...
+- xl: ...
+
+## Accessibility
+- ...
+
+## Analytics
+<table or skip>
+
+## Open questions
+- [ ] <question>
+
+## References
+- Designs: <link>
+- Component system: <link>
+- Token reference: knowledge/design-tokens/...
+```
+
+## Source files this skill reads
+
+- [`knowledge/components/INDEX.md`](../../knowledge/components/INDEX.md)
+- [`knowledge/a11y/keyboard-and-focus.md`](../../knowledge/a11y/keyboard-and-focus.md)
+- [`knowledge/a11y/contrast.md`](../../knowledge/a11y/contrast.md)
+- [`knowledge/layout/spacing-and-grid.md`](../../knowledge/layout/spacing-and-grid.md)
+- [`knowledge/motion/principles.md`](../../knowledge/motion/principles.md) — animation specs
+- [`knowledge/patterns/form-design.md`](../../knowledge/patterns/form-design.md) — when forms are involved
+- [`knowledge/i18n/korean-product-conventions.md`](../../knowledge/i18n/korean-product-conventions.md) — Korean apps
+
+## Verification phase (run before declaring done)
+
+- [ ] Every screen has: purpose, entry/exit, layout, states, edge cases?
+- [ ] Every component is either a system reference OR has an inline sub-spec?
+- [ ] Are interactions documented as a table (element / trigger / action)?
+- [ ] Is responsive behavior named per breakpoint (xs / sm / md / lg / xl)?
+- [ ] Are a11y requirements explicit (semantic HTML, ARIA, keyboard, focus management)?
+- [ ] Are analytics events listed (or explicitly "none for v1")?
+- [ ] Are open questions listed (not implicit)?
+- [ ] Could an engineer implement without DM'ing the designer? (If unsure, you've left an open question.)
+- [ ] Are design tokens referenced by name, not inlined as hex?
+
+## Done when
+
+- One markdown file, end-to-end.
+- Every screen has purpose, layout, states, edge cases.
+- Every component has a system-reference OR a sub-spec.
+- Interactions table is complete.
+- Responsive behavior is named per breakpoint.
+- A11y requirements are explicit.
+- Open questions are listed (or "none").
+- An engineer would not need to ask design follow-up questions to implement.
+- The verification phase checklist passes.

package/skills/handoff-spec/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: handoff-spec
+description: Produce a developer-handoff document from a finalized design — screens, components, interactions, data, responsive behavior, a11y, analytics, and open questions in one markdown.
+---
+
+See [PLAYBOOK.md](PLAYBOOK.md).