@design-ai/cli 4.55.0

package/skills/color-palette/TEMPLATE.md

@@ -0,0 +1,103 @@
+# Palette: <name>
+
+> Seed: `<input>` · Mood: `<adjective list>` · Target: `<framework>`
+
+## Why this palette
+
+<2–4 sentences. What problem this solves, what brand position it claims, what tradeoffs were accepted.>
+
+## Tokens
+
+### Brand ramps
+
+| Step | Primary | Accent | Neutral |
+| --- | --- | --- | --- |
+| 50 | `#...` | `#...` | `#...` |
+| 100 | `#...` | `#...` | `#...` |
+| ...
+| 950 | `#...` | `#...` | `#...` |
+
+### Semantic aliases — light
+
+| Token | Value | Notes |
+| --- | --- | --- |
+| `--color-primary-default` | `#...` | hits 4.5:1 on white |
+| `--color-primary-hover` | `#...` | |
+| `--color-primary-active` | `#...` | |
+| `--color-primary-subtle` | `#...` | background |
+| `--color-on-primary` | `#...` | text/icon on primary |
+| `--color-bg-default` | `#...` | |
+| `--color-bg-elevated` | `#...` | |
+| `--color-text-primary` | `#...` | |
+| `--color-text-secondary` | `#...` | |
+| `--color-text-disabled` | `#...` | |
+| `--color-border-default` | `#...` | |
+| `--color-success` | `#...` | |
+| `--color-warning` | `#...` | |
+| `--color-error` | `#...` | |
+| `--color-info` | `#...` | |
+
+### Semantic aliases — dark
+
+<same shape, recomputed values>
+
+## Contrast matrix
+
+| Pair | Ratio | AA | AAA |
+| --- | --- | --- | --- |
+| text-primary on bg-default | 13.8:1 | ✓ | ✓ |
+| primary-default on white | 4.6:1 | ✓ | — |
+| primary-default on bg-default | 4.5:1 | ✓ | — |
+| text-secondary on bg-default | 7.1:1 | ✓ | ✓ |
+| border-default on bg-default | 3.0:1 | ✓ (UI) | — |
+| ...
+
+## Output: Tailwind v4
+
+```css
+@theme {
+  --color-primary-50:  #...;
+  --color-primary-100: #...;
+  /* ... */
+}
+```
+
+## Output: shadcn-ui (CSS vars)
+
+```css
+:root {
+  --primary: #...;
+  --primary-foreground: #...;
+  /* ... */
+}
+
+.dark {
+  /* ... */
+}
+```
+
+## Output: Style Dictionary (JSON)
+
+```json
+{
+  "color": {
+    "primary": {
+      "50":  { "value": "#..." },
+      "100": { "value": "#..." }
+    }
+  }
+}
+```
+
+## Use guidance
+
+- Reach for **primary** for: <list>
+- Reach for **accent** for: <list>
+- Reach for **neutral** for: <list>
+- **Don't**: <list common misuses>
+
+## Cited sources
+
+- [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/a11y/contrast.md](../../knowledge/a11y/contrast.md)

package/skills/component-spec-writer/PLAYBOOK.md

@@ -0,0 +1,169 @@
+# component-spec-writer — playbook
+
+Produce a developer-ready spec sheet for a single UI component. Output is a markdown document that a frontend engineer can implement against without asking follow-up questions.
+
+## When to use
+
+- "Spec a `Banner` component for me."
+- "We're adding a `MultiSelect`. Document the API."
+- "Help me design the anatomy of a `CommandPalette`."
+
+## Inputs (ask if missing)
+
+1. **Component name** (canonical, kebab-case).
+2. **Goal** — what user need it serves.
+3. **Target framework** — `react`, `vue`, `svelte`, framework-agnostic. Default: react.
+4. **Style system** — `tailwind`, `css vars`, `mui theme`, `antd token`. Default: css vars.
+5. **Existing components in the system?** — to check naming consistency.
+
+## Steps
+
+### 1. Find references
+
+Open [`knowledge/components/INDEX.md`](../../knowledge/components/INDEX.md). For the canonical name, locate the row. Open the source files for **all three** libraries that have it. Read enough to understand:
+
+- Required vs optional props.
+- Variants (size, color, type).
+- States (default, hover, active, focus, disabled, loading, error).
+- Composition (does it have sub-components like `Card.Header`, `Card.Body`?).
+- Edge cases the libraries handle (empty state, overflow, RTL, long text).
+
+If the component is **not** in the index, find the closest analogous component (e.g., `MultiSelect` ≈ shadcn `Select` + custom multi-mode).
+
+### 2. Choose the canonical API
+
+Compare APIs across the three references. Pick the cleanest. Bias rules:
+
+- Boolean flags > enum strings when there are ≤ 2 options. (`disabled` not `state="disabled"`.)
+- Enum strings > booleans when there are 3+ options. (`size="sm" | "md" | "lg"` not `small={bool}, medium={bool}`.)
+- Composition > prop overload for layout-rich components. (`<Card><Card.Header /></Card>` not `<Card title={...} />`.)
+- One callback per event type. (`onChange(value)` not `onChange(event)` for form fields where event is rarely needed.)
+
+### 3. Define anatomy
+
+Diagram the component's parts in markdown. Name each part:
+
+```
+Card
+├── Card.Header
+│   ├── Card.Title
+│   └── Card.Actions
+├── Card.Body
+└── Card.Footer
+```
+
+Each part needs:
+- A purpose sentence.
+- Whether it's required.
+- Default content if omitted.
+
+### 4. Define states
+
+For every interactive component, enumerate:
+
+| State | Trigger | Visual change |
+| --- | --- | --- |
+| Default | resting | base styles |
+| Hover | mouse over | slight bg shift, cursor change |
+| Focus-visible | keyboard tab | 2px focus ring (cite [keyboard-and-focus.md](../../knowledge/a11y/keyboard-and-focus.md)) |
+| Active | press | deeper bg shift |
+| Disabled | `disabled` prop | reduced opacity, no events, `aria-disabled="true"` |
+| Loading | `loading` prop | spinner replaces or overlays content |
+| Error | `error` prop or invalid value | red border + error text |
+| Read-only | `readOnly` prop | no border emphasis, no edit affordance |
+
+Not every state applies to every component. Mark N/A.
+
+### 5. Define variants
+
+| Variant axis | Values | When to use |
+| --- | --- | --- |
+| `size` | `sm` / `md` / `lg` | sm in dense forms, md default, lg in marketing |
+| `color` | `primary` / `secondary` / `danger` / `ghost` | one CTA per surface uses primary |
+| `shape` | (component-specific) | |
+
+### 6. Accessibility requirements
+
+For each component, list:
+
+- Semantic element (e.g., `<button>` not `<div role="button">`).
+- ARIA attributes (`aria-label`, `aria-expanded`, `aria-haspopup`, `aria-controls`).
+- Keyboard interactions (cite [keyboard-and-focus.md](../../knowledge/a11y/keyboard-and-focus.md) for the canonical pattern).
+- Screen reader announcement on state change.
+- Touch target size (≥ 44×44 for primary actions).
+
+### 7. Tokens consumed
+
+List every design token the component reads:
+
+```
+--color-primary-default
+--color-primary-hover
+--color-on-primary
+--space-md
+--radius-md
+--transition-default
+```
+
+If a token does not exist in the system, **flag it** — don't silently invent.
+
+### 8. Edge cases
+
+- Empty state (no data, no value).
+- Overflow (text too long, list too tall).
+- Long content (truncate vs wrap).
+- RTL behavior.
+- Reduced motion (`prefers-reduced-motion`).
+- High contrast mode.
+- Print.
+
+### 9. Output
+
+Use [TEMPLATE.md](TEMPLATE.md). Verify:
+
+- Every prop has a type, default, and one-line description.
+- Every state has a visual rule.
+- Every keyboard interaction is listed.
+- Code example covers the most common usage.
+- Don't section addresses 2–3 misuses.
+
+## Source files this skill reads
+
+- [`knowledge/components/INDEX.md`](../../knowledge/components/INDEX.md)
+- [`knowledge/components/shadcn-registry.md`](../../knowledge/components/shadcn-registry.md)
+- [`knowledge/a11y/keyboard-and-focus.md`](../../knowledge/a11y/keyboard-and-focus.md)
+- [`knowledge/a11y/contrast.md`](../../knowledge/a11y/contrast.md)
+- [`knowledge/motion/principles.md`](../../knowledge/motion/principles.md) — for animation specs
+- [`knowledge/i18n/korean-typography.md`](../../knowledge/i18n/korean-typography.md) — when Korean IME is relevant
+- [`knowledge/platforms/react-native.md`](../../knowledge/platforms/react-native.md) — when target is RN
+- Source files in `refs/` (cite the exact paths).
+- Existing worked specs in [`examples/README.md`](../../examples/README.md) — reference for shape and depth.
+
+## Verification phase (run before declaring done)
+
+- [ ] Did I cite at least 2 of the 3 reference libraries (Ant / MUI / shadcn)?
+- [ ] Are API choices explained ("API choices made" section) — not just listed?
+- [ ] Do all states (default/hover/focus/active/disabled/loading/error) have visual rules?
+- [ ] Is every keyboard interaction listed for the WAI-ARIA pattern this component implements?
+- [ ] Are the required ARIA attributes spelled out (not just "use ARIA")?
+- [ ] Is there a touch-target size note (≥ 44pt mobile / ≥ 24px web AA)?
+- [ ] Does the spec address reduced-motion handling?
+- [ ] Are at least 3 edge cases covered (empty, long content, RTL, etc.)?
+- [ ] Does the "Don't" section have at least 2 specific misuses?
+- [ ] If RN-targeted: are tokens as numbers and is `Pressable` used (not `<button>`)?
+- [ ] If Korean-relevant input: is IME composition handling addressed?
+
+## Done when
+
+- One markdown file, < 600 lines.
+- Anatomy diagram + parts table.
+- API table (props, types, defaults, descriptions).
+- States table.
+- Variants table.
+- Tokens consumed list.
+- Keyboard interactions.
+- ARIA requirements.
+- Code example.
+- Edge cases section.
+- "Don't" section.
+- The verification phase checklist passes.

package/skills/component-spec-writer/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: component-spec-writer
+description: Produce a developer-ready spec sheet for a UI component — API, anatomy, states, variants, tokens, ARIA, keyboard, and edge cases — by comparing implementations across Ant Design, MUI, and shadcn-ui.
+---
+
+See [PLAYBOOK.md](PLAYBOOK.md).

package/skills/component-spec-writer/TEMPLATE.md

@@ -0,0 +1,115 @@
+# `<Component>` — spec
+
+> Status: <draft / accepted / shipped> · Owner: <name> · Last updated: <date>
+
+## Purpose
+
+<2 sentences. The user need this serves and the canonical context.>
+
+## Anatomy
+
+```
+<Component>
+├── <Part1>
+├── <Part2>
+└── <Part3>
+```
+
+| Part | Purpose | Required | Default if omitted |
+| --- | --- | --- | --- |
+| `<Part1>` | ... | yes | — |
+
+## API
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | — | Controlled value. |
+| `onChange` | `(value: string) => void` | — | Fires on change. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+| `disabled` | `boolean` | `false` | |
+
+## States
+
+| State | Trigger | Visual |
+| --- | --- | --- |
+| Default | resting | base |
+| Hover | mouse-over | bg lighten 4% |
+| Focus-visible | keyboard tab | 2px ring `--color-focus-ring`, offset 2px |
+| Active | press | bg darken 6% |
+| Disabled | `disabled` | opacity 0.5, no pointer-events |
+| Loading | `loading` | content swapped for spinner |
+
+## Variants
+
+### Size
+| Size | Height | Font | Padding |
+| --- | --- | --- | --- |
+| `sm` | 28px | 13px | 8px 12px |
+| `md` | 32px | 14px | 8px 16px |
+| `lg` | 40px | 16px | 12px 20px |
+
+### Color (or "intent")
+| Value | Use | Background | Text |
+| --- | --- | --- | --- |
+| `primary` | primary CTA | `--color-primary-default` | `--color-on-primary` |
+| `secondary` | non-primary action | `--color-bg-elevated` | `--color-text-primary` |
+| `ghost` | low-emphasis action | transparent | `--color-text-primary` |
+| `danger` | destructive | `--color-error` | `white` |
+
+## Tokens consumed
+
+```
+--color-primary-default
+--color-primary-hover
+--color-on-primary
+--space-md
+--radius-md
+--transition-default
+--color-focus-ring
+```
+
+## Accessibility
+
+- **Semantic element**: `<button type="button">`. Never `<div onClick>`.
+- **ARIA**:
+  - `aria-label` if no visible text.
+  - `aria-disabled="true"` when `disabled` (in addition to native `disabled`).
+  - `aria-busy="true"` when `loading`.
+- **Keyboard**: `Enter` and `Space` activate. `Tab` reaches.
+- **Touch**: minimum 44×44 hit area on mobile (use padding to extend if visual size is smaller).
+- **Focus**: 2px ring with 3:1 contrast against both element and adjacent background.
+
+## Code example
+
+```tsx
+<Button
+  size="md"
+  intent="primary"
+  onClick={handleSubmit}
+  disabled={isPending}
+  loading={isPending}
+>
+  Save changes
+</Button>
+```
+
+## Edge cases
+
+- **Long text**: truncates with `…` if exceeds container; full text in `title` attribute.
+- **Empty state**: `<Component>` with no children renders nothing (does not crash, does not reserve space).
+- **RTL**: icon swap, padding mirror.
+- **Reduced motion**: omit fade transitions, keep instant state changes.
+- **Print**: hidden by default (`@media print { display: none; }`) unless explicitly requested.
+
+## Don't
+
+- Don't pass icons as `children` AND as `icon` prop.
+- Don't use `intent="primary"` for more than one button per surface.
+- Don't use `loading` and `disabled` simultaneously — pick one.
+
+## References
+
+- Ant Design: <link to refs/ant-design/components/...>
+- MUI: <link to refs/mui/...>
+- shadcn-ui: <link to refs/shadcn-ui/...>
+- Knowledge: [a11y/keyboard-and-focus.md](../../knowledge/a11y/keyboard-and-focus.md), [components/INDEX.md](../../knowledge/components/INDEX.md)

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

@@ -0,0 +1,231 @@
+# conversational-ui-designer — playbook
+
+Design and spec a conversational UI — voice assistant, chatbot, AI chat (LLM-based), or live-agent chat. Output is a markdown spec covering modality, intent model, persona, error handling, accessibility, and Korean conventions where applicable.
+
+## When to use
+
+- "Design a chatbot for our customer support."
+- "Spec a voice search feature for our app."
+- "Plan AI chat onboarding for our product."
+- "Build a Bixby Capsule for our service."
+- "Design KakaoTalk Channel chatbot."
+
+## Inputs (ask if missing)
+
+1. **Type** — voice assistant / chatbot / AI chat / live agent / hybrid.
+2. **Modality** — voice-only / voice + visual / text-only / multimodal.
+3. **Use case** — customer support / FAQ deflection / lead capture / transactional / AI help.
+4. **Audience** — Korean / international / mixed.
+5. **Brand voice** — formal (합쇼체) / friendly (해요체) / casual.
+6. **Backend** — rule-based / intent-based (Dialogflow / Rasa) / LLM (GPT / Claude / HyperCLOVA) / hybrid.
+7. **Platform** — own app / KakaoTalk channel / Bixby Capsule / Slack / web embed.
+8. **Existing brand** — voice + persona constraints.
+
+## Steps
+
+### 1. Pick the type
+
+| Type | Read |
+| --- | --- |
+| Voice assistant / smart speaker / IVR | [`voice-ui-patterns.md`](../../knowledge/conversational/voice-ui-patterns.md) |
+| Chatbot (rule / intent / hybrid) | [`chatbot-design.md`](../../knowledge/conversational/chatbot-design.md) |
+| AI chat (LLM) | [`ai-chat-interfaces.md`](../../knowledge/conversational/ai-chat-interfaces.md) |
+| Korean market | [`korean-voice-conventions.md`](../../knowledge/conversational/korean-voice-conventions.md) |
+
+Always read [`conversational-ui-fundamentals.md`](../../knowledge/conversational/conversational-ui-fundamentals.md).
+
+### 2. Spec the modality
+
+| Modality | Affordance |
+| --- | --- |
+| Voice-only | Wake word OR push-to-talk; auditory feedback |
+| Voice + visual | Voice in, visual out; tap-to-talk |
+| Text-only | Persistent input; suggested chips |
+| Multimodal AI | Text + image + voice; streaming |
+
+Make modality explicit. Affects everything downstream.
+
+### 3. Define persona
+
+| Dimension | Decide |
+| --- | --- |
+| Honorific level (KR) | 합쇼체 / 해요체 |
+| Formality | Formal / friendly / casual |
+| Verbosity | Terse / discursive |
+| Warmth | Professional / warm |
+| Emoji use | Never / rare / frequent |
+| Address user | 고객님 / 회원님 / [name]님 |
+| Bot self-identity | "저는 [봇 이름]" / "[브랜드] 봇" |
+
+For Korean B2C fintech: 해요체, friendly, terse-warm, 고객님, no emoji.
+For Korean B2B: 합쇼체, formal, professional, 회원님.
+
+### 4. Spec turn-taking model
+
+For voice / IVR:
+- Wake word OR tap-to-talk activation.
+- End-of-utterance detection (silence timeout).
+- Multi-turn dialogue with slot-filling.
+- Confirmation for destructive actions.
+
+For chat:
+- Persistent input.
+- Send on Enter / button.
+- Bot responds with typing indicator → message.
+- Suggested chips reduce typing.
+
+For AI chat:
+- Streaming response (token-by-token).
+- Stop / regenerate / continue.
+- Markdown render.
+- Long context handling.
+
+### 5. Plan intent / NLU
+
+For rule-based:
+- Decision tree of buttons.
+
+For intent-based:
+- Top intents (5-30 typically).
+- Slot definitions per intent.
+- Training utterances per intent (10-50 each).
+- Fallback intent.
+
+For LLM-based:
+- System prompt defining persona + constraints.
+- Tool definitions (if function calling).
+- Context window management.
+- Hallucination mitigations (citations, confidence).
+
+For hybrid: buttons + intent + LLM fallback + human handoff.
+
+### 6. Plan error recovery
+
+For each failure type:
+- Misheard / no speech → retry prompt.
+- Misclassified intent → "Did you mean X?" with options.
+- No matching intent → fallback to LLM OR human handoff.
+- Backend error → graceful retry / alternate path.
+- Repeated failures (2-3) → human handoff.
+
+### 7. Plan multi-turn flows
+
+For complex tasks (booking, troubleshooting):
+- Slot-filling order.
+- Confirmation step.
+- Cancel / restart at any point.
+- Save partial progress.
+
+Sketch as a flow diagram.
+
+### 8. Plan handoff to human (if applicable)
+
+- Always-available "human" request.
+- Context transfer (agent sees prior conversation).
+- Wait time displayed.
+- Off-hours behavior.
+- Escalation triggers (failed N times, sensitive topic, user request).
+
+### 9. Korean compliance (if applicable)
+
+- **개인정보보호법** — voice recording / chat history consent + retention.
+- **정보통신망법** — proactive marketing messages disclosed.
+- **자본시장법 / 금융소비자보호법** — financial product disclaimers.
+- **KakaoTalk Channel** rules (if deployed there).
+- 자막 / TTS in Korean — verify pronunciation of brand / product names.
+
+### 10. Plan accessibility
+
+- Voice + text alt always available.
+- Visual feedback for listening / processing.
+- Transcript visible (deaf users).
+- Reduced-motion handling.
+- Adjustable TTS speed.
+- High contrast / large text support.
+- Keyboard navigation.
+
+### 11. Output
+
+```markdown
+# Conversational UI spec: <surface>
+
+> Type: <voice / chatbot / AI chat / live agent>
+> Modality: <voice-only / voice+visual / text-only / multimodal>
+> Use case: <support / FAQ / transactional / AI help>
+> Audience: <KR / international>
+> Backend: <rule / intent / LLM / hybrid>
+> Platform: <own app / KakaoTalk / Bixby / web>
+
+## Persona
+<honorific level, formality, warmth, emoji, user addressing>
+
+## Modality + affordances
+<wake word / tap-to-talk / persistent input>
+
+## Top intents (or LLM system prompt summary)
+<5-30 intents with sample utterances>
+
+## Conversation flows
+<key multi-turn flows: support, transaction, AI ask>
+
+## Error recovery
+<for each failure: retry / fallback / handoff>
+
+## Human handoff
+<trigger criteria, transition UX>
+
+## Korean compliance (if applicable)
+<개인정보보호법, 정보통신망법, 자본시장법>
+
+## Accessibility
+<text alt, transcript visible, reduced motion, keyboard>
+
+## UI components needed
+<reference component-chat-interface, component-voice-input, etc>
+
+## Don't
+<2-3 specific misuses>
+```
+
+## Source files this skill reads
+
+- [`knowledge/conversational/conversational-ui-fundamentals.md`](../../knowledge/conversational/conversational-ui-fundamentals.md)
+- [`knowledge/conversational/voice-ui-patterns.md`](../../knowledge/conversational/voice-ui-patterns.md)
+- [`knowledge/conversational/chatbot-design.md`](../../knowledge/conversational/chatbot-design.md)
+- [`knowledge/conversational/ai-chat-interfaces.md`](../../knowledge/conversational/ai-chat-interfaces.md)
+- [`knowledge/conversational/korean-voice-conventions.md`](../../knowledge/conversational/korean-voice-conventions.md)
+- [`knowledge/i18n/korean-document-style.md`](../../knowledge/i18n/korean-document-style.md) — honorific level
+- [`knowledge/i18n/korean-typography.md`](../../knowledge/i18n/korean-typography.md) — IME, fonts
+- [`knowledge/patterns/email-design.md`](../../knowledge/patterns/email-design.md) — KR ad disclosure
+- [`examples/component-chat-interface.md`](../../examples/component-chat-interface.md)
+- [`examples/component-voice-input.md`](../../examples/component-voice-input.md)
+
+## Verification phase (run before declaring done)
+
+- [ ] Is the type (voice / chatbot / AI / live) explicit?
+- [ ] Is the modality (voice / text / multi) explicit?
+- [ ] Is the persona defined (honorific level, formality, warmth, emoji)?
+- [ ] Is turn-taking model explicit (wake word / tap / persistent / streaming)?
+- [ ] Are top intents OR LLM system prompt summary documented?
+- [ ] Are key conversation flows mapped?
+- [ ] Is error recovery specified for each failure type?
+- [ ] Is human handoff path defined?
+- [ ] If Korean: are 개인정보보호법 / 정보통신망법 / 자본시장법 addressed?
+- [ ] If Korean: is honorific level + 고객님 / 회원님 / [name]님 specified?
+- [ ] Is accessibility addressed (text alt, transcript, reduced motion)?
+- [ ] Are required UI components listed?
+- [ ] Does "Don't" catch 2-3 specific misuses?
+
+## Done when
+
+- One markdown spec, < 500 lines.
+- Type + modality + use case + audience explicit.
+- Persona defined.
+- Turn-taking model specified.
+- Top intents / system prompt documented.
+- Conversation flows mapped.
+- Error recovery + human handoff defined.
+- Korean compliance addressed if applicable.
+- Accessibility addressed.
+- "Don't" section.
+- Verification passes.

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

@@ -0,0 +1,6 @@
+---
+name: conversational-ui-designer
+description: Design and spec conversational UI — voice assistants, chatbots, AI chat (LLM), live agent. Picks modality, intent model, persona, honorific level (해요체 / 합쇼체), error handling, accessibility, Korean conventions (Bixby / Clova / KakaoTalk channel).
+---
+
+See [PLAYBOOK.md](PLAYBOOK.md).