@design-ai/cli 4.55.0

package/examples/component-zoom.md

@@ -0,0 +1,92 @@
+# `Zoom` — spec
+
+> Synthesized from MUI `Zoom`. Transition primitive — wraps a child to fade-and-zoom in / out on mount / unmount. Sibling to `Fade`, `Grow`, `Slide`, `Collapse`.
+
+## When to use
+
+- Floating action button entrance / exit.
+- Modal / Popover entrance.
+- Notification card entrance.
+- Anywhere "zoom + fade" feels right (vs "slide" or "fade").
+
+When NOT to use:
+- Page transitions (use `Slide` or fade).
+- Scroll-into-view animations (use `ScrollReveal`).
+
+## API
+
+```tsx
+<Zoom in={open} timeout={250}>
+  <div className="floating-content">
+    Content here
+  </div>
+</Zoom>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `in` | `boolean` | required | Show / hide trigger |
+| `timeout` | `number \| { enter, exit }` | `225` | Ms |
+| `easing` | `string \| { enter, exit }` | per Material | CSS easing |
+| `appear` | `boolean` | `false` | Animate on first mount |
+| `mountOnEnter` | `boolean` | `false` | Don't render until first true |
+| `unmountOnExit` | `boolean` | `false` | Remove from DOM after exit |
+
+## CSS
+
+```css
+.zoom-enter { transform: scale(0); opacity: 0; }
+.zoom-enter-active {
+  transform: scale(1); opacity: 1;
+  transition: transform 250ms cubic-bezier(0.4, 0, 0.2, 1),
+              opacity 200ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+.zoom-exit { transform: scale(1); opacity: 1; }
+.zoom-exit-active {
+  transform: scale(0); opacity: 0;
+  transition: transform 195ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+```
+
+## Reduced motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .zoom-enter-active, .zoom-exit-active {
+    transition: none;
+  }
+}
+```
+
+## Tokens consumed
+
+```
+--motion-medium                   (default duration)
+--ease-out
+```
+
+## Code example — FAB entrance
+
+```tsx
+<Zoom in={!loading} appear>
+  <SpeedDial ariaLabel="새로 만들기" icon={<PlusIcon />}>
+    <SpeedDial.Action ... />
+  </SpeedDial>
+</Zoom>
+```
+
+## Don't
+
+- Don't zoom large content (jarring). Use Fade for big surfaces.
+- Don't zoom from `scale(0.01)` to `scale(1)` — exits feel wrong. Stay near full scale (0.7-1).
+- Don't ignore reduced motion.
+
+## References
+
+- MUI: [`Zoom`](../refs/mui/packages/mui-material/src/Zoom)
+- Material Design: motion easing
+
+## Cross-reference
+
+- [`knowledge/motion/principles.md`](../knowledge/motion/principles.md)
+- [`examples/component-spinner.md`](component-spinner.md)

package/examples/doc-explanation-example.md

@@ -0,0 +1,196 @@
+# Worked example: explanation
+
+> Generated by `skills/document-author` with type=`explanation`. Demonstrates the canonical Diátaxis explanation format — discursive, motivation-driven, justifies design decisions.
+
+---
+
+```markdown
+---
+title: Why design-ai uses W3C DTCG token format (and not Tokens Studio's native format)
+description: The decision behind design-ai's choice of W3C DTCG (Style Dictionary–compatible) for token serialization, the alternatives we considered, and the tradeoffs accepted.
+type: explanation
+audience: Engineers and designers extending design-ai or integrating it with another token system
+last_updated: 2026.05.08
+---
+
+# Why design-ai uses W3C DTCG token format
+
+## The problem
+
+A design token is a key-value pair: `color.primary.600 = #7C3AED`. The data model is trivial. The hard part is **the format**: how do you serialize this so that it's:
+
+1. Readable by humans
+2. Convertible across platforms (CSS, iOS, Android, Figma)
+3. Compatible with existing tooling
+4. Stable as the token system evolves
+
+Several formats exist. design-ai picks one — W3C DTCG (Design Tokens Community Group format). This doc explains why.
+
+## What we considered
+
+### Option A: Tokens Studio's native JSON
+
+```json
+{
+  "global": {
+    "color": {
+      "primary": {
+        "600": {
+          "value": "#7C3AED",
+          "type": "color",
+          "description": "Brand primary"
+        }
+      }
+    }
+  }
+}
+```
+
+Pros: well-supported by the Tokens Studio Figma plugin. Has 5+ years of evolution. Many consumers.
+
+Cons: vendor-specific. Tokens Studio has been promising migration to W3C DTCG. Format isn't a standard.
+
+### Option B: Style Dictionary's traditional format
+
+```json
+{
+  "color": {
+    "primary": {
+      "600": {
+        "value": "#7C3AED",
+        "type": "color"
+      }
+    }
+  }
+}
+```
+
+Pros: enormous tooling ecosystem. Style Dictionary is from 2018, widely adopted at Amazon/Salesforce/etc. Battle-tested transformations.
+
+Cons: pre-dates the W3C effort. Not technically a standard. `type` is sometimes `attributes.category`.
+
+### Option C: W3C DTCG format (the chosen one)
+
+```json
+{
+  "color": {
+    "primary": {
+      "600": {
+        "$value": "#7C3AED",
+        "$type": "color"
+      }
+    }
+  }
+}
+```
+
+Note the `$value` / `$type` (with `$` prefix) — that's the W3C distinction.
+
+Pros: emerging W3C standard. Tokens Studio is migrating to it. Style Dictionary v4 supports it natively. Future-proof.
+
+Cons: less mature than Style Dictionary's traditional format. Some tools still in transition.
+
+### Option D: Vendor formats (Material Tokens, Primer, etc.)
+
+Each large design system (Material 3, Primer, Polaris, Carbon) has its own token format. For consumers of those systems, native is fine. For a generic system like design-ai? Wrong choice — locks consumers into the parent vendor.
+
+## What we chose
+
+**W3C DTCG format** (Option C).
+
+```json
+{
+  "color": {
+    "brand": {
+      "primary": {
+        "50":  { "$value": "#F5F3FF", "$type": "color" },
+        "600": { "$value": "#7C3AED", "$type": "color" }
+      }
+    },
+    "semantic": {
+      "primary": { "$value": "{color.brand.primary.600}", "$type": "color" }
+    }
+  }
+}
+```
+
+The reasoning:
+
+1. **Standard track.** The W3C DTCG group includes Adobe, Figma, Atlassian, GitHub, and others. The format will likely become a real standard within 2 years.
+
+2. **Tools converge here.** Style Dictionary v4 reads it. Tokens Studio is migrating to it. Custom tooling we write today will keep working.
+
+3. **Distinguishable from JSON-data.** The `$value` prefix prevents collision with regular JSON keys. `{ "value": ... }` was ambiguous.
+
+4. **Already widely supported.** The major upstream design systems are publishing tokens in this format.
+
+## Tradeoffs accepted
+
+### Tradeoff 1 — early-adopter ecosystem
+
+Some Figma plugins haven't migrated yet. Specifically: older Tokens Studio versions still use the non-`$` format. Workaround: convert at the boundary using `tokens-studio-format` npm package.
+
+**Impact**: minor. The Tokens Studio team has signaled migration.
+
+### Tradeoff 2 — slightly more verbose
+
+`$value` + `$type` adds 4 chars per entry over the bare `value` + `type`. For a 200-token system that's ~800 chars of bytes. Negligible.
+
+**Impact**: nil.
+
+### Tradeoff 3 — older docs reference the non-$ format
+
+Some older Style Dictionary tutorials say `"value": ...`. New users may copy-paste and get the old format. Workaround: design-ai's docs explicitly use `$value` everywhere, with a "if you see `value`, that's the old format" note.
+
+**Impact**: minor — primarily a docs / onboarding cost.
+
+## What this means in practice
+
+- design-ai's `tokens/source.json` examples use `$value` / `$type`.
+- The Figma plugin (`tools/figma-plugin/`) reads `$value` directly.
+- The `figma-token-sync` skill outputs `$value` format.
+- Tokens Studio plugin: "When importing the JSON to Tokens Studio, use the W3C DTCG import option."
+
+## What might change
+
+If the W3C DTCG format diverges significantly from current expectations (e.g., dramatic schema changes), we'll re-evaluate. The transformation is mechanical — switching is a one-time change to the extractor scripts.
+
+If Tokens Studio decides not to support W3C DTCG (unlikely as of mid-2025), we may need to bridge formats per consumer.
+
+For now: **W3C DTCG is the bet**.
+
+## Related decisions
+
+- **Why nested vs flat**: nested matches the way tokens are reasoned about (hierarchy). Flat (`color.brand.primary.600 = #7C3AED`) loses that semantic.
+- **Why JSON not YAML**: JSON has stronger machine-tooling. YAML's whitespace sensitivity bites here.
+- **Why allow references**: `{color.brand.primary.600}` aliases let semantic tokens cleanly point to primitives without duplicating values.
+
+## See also
+
+- [W3C DTCG specification](https://design-tokens.github.io/community-group/format/)
+- [Style Dictionary v4 docs](https://styledictionary.com/)
+- [`docs/TOKEN-SYNC.md`](../docs/TOKEN-SYNC.md) — three-tier token strategy
+- [`knowledge/design-tokens/ant-design.md`](../knowledge/design-tokens/ant-design.md) — token reference docs per upstream system
+- `tools/figma-plugin/src/code.ts` — implementation
+```
+
+---
+
+## Why this is a good explanation example
+
+- **Problem stated up front** — frames the decision space.
+- **Options enumerated** — A through D, each with pros + cons.
+- **Choice declared, with reasoning** — not just "we chose C", but why.
+- **Tradeoffs accepted** — what we gave up; honest.
+- **What might change** — when this decision should be revisited.
+- **Related decisions** — links the broader rationale.
+- **Discursive but rigorous** — not preachy, not academic. Conversational with structure.
+
+Cite [`knowledge/patterns/technical-writing.md`](../knowledge/patterns/technical-writing.md) — explanation voice is more discursive than tutorial / how-to.
+
+## Cross-reference
+
+- [`examples/doc-tutorial-example.md`](doc-tutorial-example.md)
+- [`examples/doc-how-to-example.md`](doc-how-to-example.md)
+- [`skills/document-author/PLAYBOOK.md`](../skills/document-author/PLAYBOOK.md)
+- [`knowledge/patterns/information-architecture.md`](../knowledge/patterns/information-architecture.md) — Diátaxis 4 types

package/examples/doc-how-to-example.md

@@ -0,0 +1,205 @@
+# Worked example: how-to
+
+> Generated by `skills/document-author` with type=`how-to`. Demonstrates the canonical Diátaxis how-to format — direct, problem-driven, no fluff.
+
+---
+
+```markdown
+---
+title: How to add Korean copy to existing English-only components
+description: Translate component copy to Korean while preserving design-ai conventions for honorific level, IME handling, and Daum Postcode integration.
+type: how-to
+audience: Developers shipping a Korean version of an English product
+last_updated: 2026.05.08
+---
+
+# How to add Korean copy to existing English-only components
+
+When you need to: ship a Korean locale for a product currently in English only.
+
+## TL;DR
+
+```ts
+// 1. Wrap copy in a t() function
+<button>{t("Save")}</button>
+
+// 2. Use Korean-aware t() with honorific level
+import { t } from "@/lib/i18n";
+t("Save");  // → "저장" (consumer) or "저장하기" (formal)
+```
+
+Set `LOCALE=ko` and `HONORIFIC=informal` (해요체) or `formal` (합쇼체) per app configuration. Default `formal` for fintech / B2B; `informal` for consumer.
+
+## Steps
+
+### 1. Inventory the copy
+
+Find every literal string in your components. Tools:
+
+```bash
+# Quick grep
+grep -r "Save\|Cancel\|Submit" src/
+
+# Better: use react-i18next's extractor
+i18next-scanner --config i18next-scanner.config.js
+```
+
+Output: a JSON file mapping every English string to a key.
+
+### 2. Pick honorific level for your product
+
+Use [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) to decide:
+
+- **Consumer mobile / friendly**: 해요체 (~해요)
+- **B2B / formal / fintech / banking**: 합쇼체 (~합니다)
+- **Government / legal / healthcare**: 합쇼체 always
+
+Decision sticks for the entire app — don't mix.
+
+### 3. Translate using design-ai conventions
+
+For UI strings, use the canonical Korean per [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md):
+
+| English | 해요체 | 합쇼체 |
+| --- | --- | --- |
+| Save | 저장 | 저장하기 |
+| Cancel | 취소 | 취소 |
+| Submit | 제출 / 등록 | 제출하기 |
+| Delete | 삭제 | 삭제하기 |
+| Sign in | 로그인 | 로그인 |
+| Sign up | 가입 | 회원가입 |
+| Loading | 로딩 중 | 불러오는 중 |
+| Try again | 다시 시도 | 다시 시도해 주세요 |
+
+Don't direct-translate — Korean has different defaults. Example: "Submit" rarely means 제출 in Korean apps; it usually means 등록 or 저장.
+
+### 4. Replace English in components
+
+For each component:
+
+```diff
+- <Button>Save</Button>
++ <Button>{t("save")}</Button>
+```
+
+Where `t()` reads from your locale JSON.
+
+### 5. Handle Korean IME for input components
+
+If your component has typeahead / autocomplete / mention features, IME composition must be respected. Update existing components:
+
+```diff
++ const [isComposing, setIsComposing] = useState(false);
+
+- <input onChange={(e) => onChange(e.target.value)} />
++ <input
++   onChange={(e) => !isComposing && onChange(e.target.value)}
++   onCompositionStart={() => setIsComposing(true)}
++   onCompositionEnd={(e) => {
++     setIsComposing(false);
++     onChange(e.target.value);
++   }}
++ />
+```
+
+Cite [`examples/component-input.md`](component-input.md) for the full pattern.
+
+### 6. Replace address inputs with Daum Postcode
+
+Korean users won't tolerate free-form address. Replace any `<AddressInput>` with the Daum Postcode-integrated version:
+
+```bash
+# Install
+npm install react-daum-postcode
+```
+
+```tsx
+import { DaumPostcode } from "react-daum-postcode";
+// ...use the Daum widget; see knowledge/i18n/korean-product-conventions.md
+```
+
+Cite [`examples/component-address-input.md`](component-address-input.md).
+
+### 7. Apply Korean typography
+
+Add Pretendard to your font stack:
+
+```css
+:root {
+  --font-family-base: 'Pretendard', -apple-system, BlinkMacSystemFont,
+                      'Apple SD Gothic Neo', 'Noto Sans KR', sans-serif;
+}
+```
+
+Bump body line-height to 1.6 (Korean +10% adjustment) per [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md):
+
+```css
+body { line-height: 1.6; }
+```
+
+Contrast check: translated Korean body text must keep at least **4.5:1** against the page background, and focus indicators on locale switchers or copy controls must keep **3:1** per [`knowledge/a11y/contrast.md`](../knowledge/a11y/contrast.md). Screen reader output must announce the active locale and any language switcher state via `aria-current` or equivalent text.
+
+### 8. Add Korean-specific patterns
+
+If your app has:
+- **Payment**: replace generic with Toss/KakaoPay/NaverPay buttons. See [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md).
+- **Phone auth**: add SMS verification flow with InputOTP — see [`examples/component-input-otp.md`](component-input-otp.md).
+- **Identity verification**: integrate PASS — see [`examples/component-pass-auth.md`](component-pass-auth.md).
+- **Money display**: use KRWAmount or AmountInput — see [`examples/component-krw-amount.md`](component-krw-amount.md).
+
+## Variations
+
+### Just translation, no Korean-specific UX
+
+If you're only translating words (e.g., a documentation site), skip steps 5–8. The result will work but won't feel native.
+
+### Multi-locale (en + ko in one app)
+
+Use a locale switcher in settings. Persist to localStorage + send via Accept-Language header.
+
+```ts
+const locale = useLocale();  // "en" | "ko"
+```
+
+### Korean-only product
+
+Skip the en stage entirely. Don't ship english-strings-with-Korean-fallback — just write Korean directly.
+
+## Common pitfalls
+
+| Pitfall | Fix |
+| --- | --- |
+| Mixed 합쇼체 + 해요체 in same screen | Pick one. Document in style guide. |
+| Translation breaks layout (Korean longer or shorter) | Use `flex-grow` not fixed widths; allow wrap. |
+| Phone validation regex assumes US format | Update to Korean: `/^01[0-9]-?\d{3,4}-?\d{4}$/` |
+| English error messages slip through | Add a CI check via `tools/audit/korean-copy-check.py`. |
+| Date format mm/dd/yyyy | Switch to yyyy.MM.dd (KR convention). |
+
+## See also
+
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — broader UX conventions
+- [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md) — type rules
+- [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md) — payment patterns
+- [`knowledge/i18n/korean-publishing.md`](../knowledge/i18n/korean-publishing.md) — store submission
+- `tools/audit/korean-copy-check.py` — automated check
+```
+
+---
+
+## Why this is a good how-to example
+
+- **Problem stated up front** ("when you need to…").
+- **TL;DR with code snippet** — for the reader who'll only read 5 seconds.
+- **Numbered steps with concrete actions.**
+- **Variations section** for adjacent cases.
+- **Common pitfalls** save debug time.
+- **No motivation/background** — that's an explanation doc.
+- **Imperative voice throughout** ("install", "replace", "switch").
+
+Cite [`knowledge/patterns/technical-writing.md`](../knowledge/patterns/technical-writing.md) for voice rules.
+
+## Cross-reference
+
+- [`examples/doc-tutorial-example.md`](doc-tutorial-example.md) — tutorial format (different)
+- [`skills/document-author/PLAYBOOK.md`](../skills/document-author/PLAYBOOK.md)
+- [`knowledge/patterns/information-architecture.md`](../knowledge/patterns/information-architecture.md)

package/examples/doc-tutorial-example.md

@@ -0,0 +1,162 @@
+# Worked example: tutorial
+
+> Generated by `skills/document-author` with type=`tutorial`. Demonstrates the canonical Diátaxis tutorial format.
+
+---
+
+```markdown
+---
+title: Build your first design token set
+description: Learn the design-ai workflow by generating, customizing, and exporting a complete design token set in 15 minutes.
+type: tutorial
+audience: New users — designers or front-end developers familiar with their design system but new to design-ai
+last_updated: 2026.05.08
+---
+
+# Build your first design token set
+
+> Time: 15 minutes · Audience: New to design-ai
+
+In this tutorial you'll generate a fintech-flavored color palette, customize it for your brand, and export it as Tailwind v4 + shadcn-ui tokens.
+
+## What you'll build
+
+By the end you'll have:
+- A `tokens/source.json` with your brand palette
+- A `src/styles/tokens.css` with CSS custom properties
+- A working `palette.preview.html` you can open in a browser to verify
+
+## Prerequisites
+
+- Node 20+
+- A terminal
+- A brand color (or a mood — we'll pick one if you don't have one)
+
+## Step 1 — Clone design-ai
+
+```bash
+git clone https://github.com/your-org/design-ai
+cd design-ai
+```
+
+You should see `knowledge/`, `skills/`, `examples/` — the design-ai system layout.
+
+## Step 2 — Generate a palette
+
+Run the `palette-from-brand` command in your AI agent (Claude Code, Codex, or paste into a chat):
+
+```
+/palette-from-brand "B2C Korean fintech, calming + youthful, teal seed #0D9488"
+```
+
+The agent reads `skills/color-palette/PLAYBOOK.md` and generates a full palette spec at `examples/my-palette.md`.
+
+Open it. You should see:
+- An 11-step ramp (50–950) for primary, accent, and neutrals
+- Light + dark mode semantic aliases
+- A WCAG contrast matrix
+- Code blocks for Tailwind v4 / shadcn-ui / Style Dictionary
+
+> ℹ Note: if your contrast matrix shows ✗ for any pair, the palette needs adjustment. The agent should flag this.
+
+## Step 3 — Visually verify
+
+Generate the HTML preview:
+
+```bash
+python3 tools/preview/render-tokens.py examples/my-palette.md
+```
+
+Open `examples/my-palette.preview.html`. You'll see:
+- Token swatches (light + dark)
+- Live Button/Input/Alert/Card with your tokens
+- A theme toggle at the top
+
+Click the theme toggle. The whole preview switches. **If anything looks wrong** (low-contrast text, washed-out buttons), revise via `/iterate`.
+
+## Step 4 — Export to Style Dictionary
+
+Save the JSON code block from your palette doc to `tokens/source.json`:
+
+```bash
+# Copy the JSON block from examples/my-palette.md → tokens/source.json
+```
+
+Install Style Dictionary:
+
+```bash
+npm init -y
+npm install -D style-dictionary
+```
+
+Create `style-dictionary.config.json`:
+
+```json
+{
+  "source": ["tokens/source.json"],
+  "platforms": {
+    "css": {
+      "transformGroup": "css",
+      "buildPath": "src/styles/",
+      "files": [
+        { "destination": "tokens.css", "format": "css/variables" }
+      ]
+    }
+  }
+}
+```
+
+Build:
+
+```bash
+npx style-dictionary build
+```
+
+You should see `src/styles/tokens.css` with your tokens as CSS custom properties.
+
+## Step 5 — Use the tokens
+
+Reference them in any CSS:
+
+```css
+.my-button {
+  background: var(--color-primary-default);
+  color: var(--color-on-primary);
+  padding: var(--space-md);
+  border-radius: var(--radius-md);
+}
+```
+
+The button now uses your brand-derived tokens.
+
+## What's next
+
+You generated tokens. Now:
+
+- **Spec your first component** with `/component-spec Button` — see [`skills/component-spec-writer`](../skills/component-spec-writer/PLAYBOOK.md).
+- **Bootstrap a full design system** with `/design-from-brief` — see [`commands/design-from-brief.md`](../commands/design-from-brief.md).
+- **Sync with Figma** via Tokens Studio plugin — see [`docs/integrations/figma-mcp.md`](../docs/integrations/figma-mcp.md).
+
+If you got stuck, check [`docs/USING.md`](../docs/USING.md) for agent-specific setup.
+```
+
+---
+
+## Why this is a good tutorial example
+
+- **Time + audience stated up top** — sets expectations.
+- **"What you'll build" with concrete deliverables** — motivates.
+- **Numbered steps** — easy to follow.
+- **Each step has visible outcome** ("you should see…") — confirms progress.
+- **Callout for warning** when contrast fails.
+- **What's next section** — bridges to next learning.
+- **No throat-clearing.** Tutorials are encouraging but direct.
+
+Cite [`knowledge/patterns/information-architecture.md`](../knowledge/patterns/information-architecture.md) for the canonical tutorial structure.
+
+## Cross-reference
+
+- [`skills/document-author/PLAYBOOK.md`](../skills/document-author/PLAYBOOK.md) — skill that generates this
+- [`commands/document-from-brief.md`](../commands/document-from-brief.md)
+- [`knowledge/patterns/information-architecture.md`](../knowledge/patterns/information-architecture.md) — Diátaxis types
+- [`knowledge/patterns/technical-writing.md`](../knowledge/patterns/technical-writing.md) — voice rules