@design-ai/cli 4.55.0

package/docs/integrations/vscode-walkthrough.ko.md

@@ -0,0 +1,202 @@
+# VS Code 워크스루
+
+[design-ai-vscode 확장](https://github.com/sungjin9288/design-ai/tree/main/vscode-extension)을 통해 **VS Code**에서 design-ai 사용. 확장은 코퍼스를 사이드바 트리 + 빠른 선택 명령어로 노출. 어떤 AI 어시스턴트 (Copilot Chat, Continue, Cursor 등)와도 페어링해서 완전한 디자인 인식 코딩.
+
+## 사전 준비
+
+```bash
+# design-ai 소스 설치 (현재 추천)
+git clone https://github.com/sungjin9288/design-ai.git ~/dev/design-ai && cd ~/dev/design-ai && ./install.sh
+
+# public publish 이후에는 npm/Homebrew 설치 경로로 local clone을 대체할 수 있어요.
+
+# VS Code 확장 설치 (Marketplace publish 이후)
+# code --install-extension sungjin.design-ai-vscode
+# 또는 개발 중에는 .vsix 사이드로드
+```
+
+## 설치 (60초)
+
+1. design-ai 소스 설치 (위).
+2. design-ai VS Code 확장 설치 또는 sideload.
+3. VS Code 열기; design-ai 활동 표시줄 항목 표시 (아이콘: gradient "D").
+4. 클릭 — 4개 사이드바 트리가 Skills / Knowledge / Component specs / Walkthroughs로 채워져요.
+
+확장이 design-ai를 못 찾으면 **"Open settings"** 배너 표시 — `design-ai.path`를 설치 위치로 설정.
+
+## 워크스루 1: 채팅에서 브라우징 + 참조
+
+목표: AI 어시스턴트로 Banner 컴포넌트를 작성하면서 design-ai의 spec을 진리의 소스로 사용.
+
+### 세션
+
+```
+1. design-ai 활동 표시줄 → Component specs.
+2. 트리에서 component-banner.md 찾기 → 클릭 → 에디터에서 열림.
+3. Copilot Chat (또는 Cursor / Continue / Claude Chat) 열기.
+4. 열린 파일 참조:
+
+You ▸ #file:component-banner.md  이 Banner spec을 src/components/Banner.tsx에
+      React 컴포넌트로 구현. 우리 토큰 시스템 (var(--color-banner-bg-info) 등) 사용.
+
+AI  ▸ [spec에 충실한 Banner.tsx 구현 생성]
+```
+
+패턴: **design-ai spec이 권위**, AI가 구현 엔진. 출력 품질 = 참조되는 spec의 품질.
+
+## 워크스루 2: 기존 컴포넌트 감사
+
+목표: 오래된 `Alert.tsx`를 design-ai의 spec에 맞춰 끌어올리기.
+
+```
+1. 프로젝트의 src/components/Alert.tsx 열기.
+2. design-ai 사이드바 → Component specs → component-alert.md → 클릭.
+3. 이제 두 파일 나란히 열림.
+4. AI 어시스턴트에서:
+
+You ▸ 두 파일 비교. Alert.tsx를 component-alert.md에 맞추기 위해 필요한
+      구체적 diff 나열. CRITICAL / HIGH / MEDIUM 분류.
+
+AI  ▸ [감사 발견사항]
+```
+
+## 워크스루 3: 스킬 PLAYBOOK에서 생성
+
+목표: design-ai 스킬을 사용해 컬러 팔레트 부트스트랩.
+
+```
+1. design-ai 사이드바 → Skills → color-palette → 클릭 (PLAYBOOK 열림).
+2. AI 어시스턴트에서:
+
+You ▸ #file:PLAYBOOK.md  이 스킬 적용해서 프리랜서를 위한 한국 핀테크용
+      팔레트 생성. 브랜드: 신뢰감, 차분함, 모던. Seed: oklch(56% 0.16 244).
+      출력은 src/tokens/colors.css와 tailwind.config.ts.
+
+AI  ▸ [플레이북을 단계별 따름; 두 파일 모두 생성]
+```
+
+PLAYBOOK 끝에 verification phase 체크리스트 있음 — 출력 후 AI에 적용 요청.
+
+## 워크스루 4: 코퍼스 전체에서 빠른 선택
+
+목표: 적절한 지식 파일 빨리 찾기.
+
+```
+Cmd+Shift+P → "design-ai: Open knowledge file..."
+```
+
+빠른 선택이 92개 지식 파일을 경로와 함께 나열. 입력으로 필터 — "korean", "motion", "spatial", "typography" 등. Enter로 열기.
+
+같은 패턴:
+- "design-ai: Open component spec..." → 142개 spec
+- "design-ai: Open skill PLAYBOOK..." → 20개 스킬
+- "design-ai: Open integration walkthrough..." → 5개 워크스루
+
+## 워크스루 5: 멀티 파일 디자인 시스템 부트스트랩
+
+목표: 브리프에서 전체 디자인 시스템 생성, 파일로 머터리얼라이즈.
+
+```
+1. design-ai 사이드바 → Skills → design-system-builder → 클릭.
+2. design-ai 사이드바 → Skills → color-palette → cmd+클릭 (두 번째 탭에서 열기).
+3. design-ai 사이드바 → Knowledge → i18n/korean-typography.md → cmd+클릭.
+4. AI 어시스턴트에서:
+
+You ▸ 스킬 순서로 적용: color-palette, design-system-builder.
+      브리프: 프리랜서를 위한 한국 핀테크. 신뢰감, 차분함. Pretendard.
+      Seed oklch(56% 0.16 244). 출력:
+      - src/tokens/colors.css
+      - src/tokens/typography.css
+      - src/tokens/spacing.css
+      - tailwind.config.ts
+
+AI  ▸ [3개 참조된 파일 읽기; 4개 출력 파일 원자적 생성]
+```
+
+VS Code의 멀티 파일 편집 지원 (특히 Cursor / Copilot Edits / Continue)이 이를 깔끔히 처리.
+
+## 설정
+
+| 설정 | 기본값 | 사용 |
+|---|---|---|
+| `design-ai.path` | _(자동 탐지)_ | design-ai가 비표준 위치에 있을 때 설정 |
+| `design-ai.language` | `en` | `ko`로 설정해 README / QUICKSTART / DISTRIBUTION / AGENTS의 한국어 번역 열기 |
+
+Cmd+Shift+P → "design-ai: Open extension settings".
+
+## 한국 팀
+
+한국 1순위 팀의 경우:
+
+```jsonc
+// .vscode/settings.json
+{
+  "design-ai.language": "ko"
+}
+```
+
+이제 확장을 통해 README / QUICKSTART 등을 열면 한국어 버전이 보여요. 스킬 + 지식 파일은 언어 무관 (코퍼스의 한국어 커버리지는 콘텐츠 안에 있고 별도 번역 아님).
+
+## VS Code + AI 어시스턴트 페어링
+
+design-ai는 **모든** AI 어시스턴트와 작동. 테스트된 조합:
+
+| AI 어시스턴트 | design-ai 페어링 |
+| --- | --- |
+| **Copilot Chat** | `#file:` 참조 |
+| **Cursor Chat** | `@file` 참조 |
+| **Continue** | `@File` 슬래시 명령 |
+| **Claude in VS Code** (사용 가능 시) | `#file:` 참조 |
+| **CodeWhisperer** | 파일 열기; 채팅이 현재 파일 참조 |
+
+패턴은 모두에서 일관: design-ai가 콘텐츠 열기; AI가 참조. 벤더 종속 없음.
+
+## 문제 해결
+
+### 사이드바에 "design-ai source not found" 표시
+
+확장이 design-ai를 못 찾음. 배너의 "Open settings" 클릭, `design-ai.path`를 설치 위치로 설정:
+
+```bash
+# design-ai 설치 위치 찾기
+npm root -g  # → /path/to/global/node_modules
+# design-ai는 /path/to/global/node_modules/@design-ai/cli에 있음
+
+# 또는 git clone의 경우
+ls ~/dev/design-ai/.claude-plugin/plugin.json  # 마커 파일 확인
+```
+
+절대 경로 설정; VS Code 재시작.
+
+### 트리가 비어 있음
+
+design-ai 소스가 온전한지 확인:
+
+```bash
+ls ~/dev/design-ai/{knowledge,examples,skills,docs}
+```
+
+비어 있으면 재설치:
+
+```bash
+cd ~/dev/design-ai && git pull && ./install.sh
+```
+
+### 업데이트 반영 안 됨
+
+```bash
+# VS Code:
+Cmd+Shift+P → "design-ai: Refresh tree"
+```
+
+### 한국어 파일 안 열림
+
+`design-ai.language` 설정 확인. 한국어 변형 존재해야 함 (`README.ko.md`, `docs/QUICKSTART.ko.md` 등). 모든 파일에 한국어 번역 있는 건 아니에요.
+
+## 다음
+
+- [`docs/integrations/codex-walkthrough.ko.md`](codex-walkthrough.ko.md) — Codex CLI 변형
+- [`docs/integrations/cursor-walkthrough.ko.md`](cursor-walkthrough.ko.md) — Cursor 변형
+- [`docs/integrations/aider-walkthrough.ko.md`](aider-walkthrough.ko.md) — Aider 변형
+- [`docs/integrations/sdk-walkthrough.ko.md`](sdk-walkthrough.ko.md) — Anthropic / OpenAI SDK
+- [VS Code 확장 소스](https://github.com/sungjin9288/design-ai/tree/main/vscode-extension)

package/docs/integrations/vscode-walkthrough.md

@@ -0,0 +1,205 @@
+# VS Code walkthrough
+
+How to use design-ai inside **VS Code** via the [design-ai-vscode extension](https://github.com/sungjin9288/design-ai/tree/main/vscode-extension). The extension surfaces the corpus as sidebar trees + quick-pick commands; pair with any AI assistant (Copilot Chat, Continue, Cursor, etc.) for full design-aware coding.
+
+## Prerequisites
+
+```bash
+# Install design-ai source (currently recommended)
+git clone https://github.com/sungjin9288/design-ai.git ~/dev/design-ai && cd ~/dev/design-ai && ./install.sh
+
+# After public publish, npm/Homebrew install paths can replace the local clone.
+
+# Install VS Code extension (after Marketplace publish)
+# code --install-extension sungjin.design-ai-vscode
+# Or sideload from .vsix during development
+```
+
+## Setup (60 seconds)
+
+1. Install the design-ai source (above).
+2. Install or sideload the design-ai VS Code extension.
+3. Open VS Code; the design-ai activity bar entry appears (icon: gradient "D").
+4. Click it — 4 sidebar trees populate with Skills / Knowledge / Component specs / Walkthroughs.
+
+If the extension can't find design-ai, it shows a banner with **"Open settings"** — set `design-ai.path` to your install location.
+
+## Walkthrough 1: Browse + reference in chat
+
+Goal: write a Banner component with your AI assistant, using design-ai's spec as the source of truth.
+
+### Session
+
+```
+1. Click design-ai activity bar → Component specs.
+2. Find component-banner.md in the tree → click → opens in editor.
+3. Open Copilot Chat (or Cursor / Continue / Claude Chat).
+4. Reference the open file:
+
+You ▸ #file:component-banner.md  Implement this Banner spec as a React
+      component in src/components/Banner.tsx. Use our token system
+      (var(--color-banner-bg-info) etc).
+
+AI  ▸ [generates Banner.tsx implementation faithful to the spec]
+```
+
+The pattern: **design-ai spec is the authority**, AI is the implementation engine. Quality of output = quality of spec being referenced.
+
+## Walkthrough 2: Audit existing component
+
+Goal: bring an old `Alert.tsx` up to design-ai's spec.
+
+```
+1. Open src/components/Alert.tsx in your project.
+2. design-ai sidebar → Component specs → component-alert.md → click.
+3. Now you have both files open side-by-side.
+4. In your AI assistant:
+
+You ▸ Compare the two files. List concrete diffs needed to make
+      Alert.tsx match component-alert.md. Categorize as CRITICAL /
+      HIGH / MEDIUM.
+
+AI  ▸ [audit findings]
+```
+
+## Walkthrough 3: Generate from skill PLAYBOOK
+
+Goal: bootstrap a color palette using the design-ai skill.
+
+```
+1. design-ai sidebar → Skills → color-palette → click (opens PLAYBOOK).
+2. In your AI assistant:
+
+You ▸ #file:PLAYBOOK.md  Apply this skill to generate a palette for a
+      Korean fintech for freelancers. Brand: trustworthy, calm, modern.
+      Seed: oklch(56% 0.16 244). Output to src/tokens/colors.css and
+      tailwind.config.ts.
+
+AI  ▸ [follows the playbook step-by-step; produces both files]
+```
+
+The PLAYBOOK has a verification phase checklist at the end — ask the AI to apply it after producing output.
+
+## Walkthrough 4: Quick-pick across the corpus
+
+Goal: find the right knowledge file fast.
+
+```
+Cmd+Shift+P → "design-ai: Open knowledge file..."
+```
+
+A quick-pick lists all 92 knowledge files with their paths. Filter by typing — "korean", "motion", "spatial", "typography", etc. Hit Enter to open.
+
+Same pattern for:
+- "design-ai: Open component spec..." → 142 specs
+- "design-ai: Open skill PLAYBOOK..." → 20 skills
+- "design-ai: Open integration walkthrough..." → 4 walkthroughs
+
+## Walkthrough 5: Multi-file design system bootstrap
+
+Goal: generate a full design system from a brief, materialize as files.
+
+```
+1. design-ai sidebar → Skills → design-system-builder → click.
+2. design-ai sidebar → Skills → color-palette → cmd+click (open in 2nd tab).
+3. design-ai sidebar → Knowledge → i18n/korean-typography.md → cmd+click.
+4. In your AI assistant:
+
+You ▸ Apply skills in order: color-palette, then design-system-builder.
+      Brief: 프리랜서를 위한 한국 핀테크. Trustworthy, calm. Pretendard.
+      Seed oklch(56% 0.16 244). Output:
+      - src/tokens/colors.css
+      - src/tokens/typography.css
+      - src/tokens/spacing.css
+      - tailwind.config.ts
+
+AI  ▸ [reads all 3 referenced files; generates 4 output files atomically]
+```
+
+VS Code's multi-file edit support (especially in Cursor / Copilot Edits / Continue) handles this cleanly.
+
+## Settings
+
+| Setting | Default | Use |
+|---|---|---|
+| `design-ai.path` | _(auto-probe)_ | Set if design-ai is at non-standard location |
+| `design-ai.language` | `en` | Set to `ko` to open Korean translations of README / QUICKSTART / DISTRIBUTION / AGENTS |
+
+Cmd+Shift+P → "design-ai: Open extension settings".
+
+## Korean teams
+
+For Korean primary teams:
+
+```jsonc
+// .vscode/settings.json
+{
+  "design-ai.language": "ko"
+}
+```
+
+Now opening README / QUICKSTART / etc. via the extension shows Korean versions when available. Skills + knowledge files are language-agnostic (the corpus' Korean coverage is in the content, not a separate translation).
+
+## VS Code + AI assistant pairing
+
+design-ai works with **any** AI assistant. Tested combinations:
+
+| AI assistant | Design-ai pairing |
+| --- | --- |
+| **Copilot Chat** | `#file:` references |
+| **Cursor Chat** | `@file` references |
+| **Continue** | `@File` slash command |
+| **Claude in VS Code** (when avail.) | `#file:` references |
+| **CodeWhisperer** | Open files; chat references current file |
+
+The pattern is consistent across all: design-ai opens content; AI references it. No vendor lock-in.
+
+## Troubleshooting
+
+### Sidebar shows "design-ai source not found"
+
+The extension can't find design-ai. Click "Open settings" in the banner, set `design-ai.path` to your install location:
+
+```bash
+# Find where design-ai installed
+npm root -g  # → /path/to/global/node_modules
+# So design-ai is at /path/to/global/node_modules/@design-ai/cli
+
+# Or for git clone
+ls ~/dev/design-ai/.claude-plugin/plugin.json  # confirm marker file
+```
+
+Set the absolute path; restart VS Code.
+
+### Trees are empty
+
+Ensure design-ai source is intact:
+
+```bash
+ls ~/dev/design-ai/{knowledge,examples,skills,docs}
+```
+
+If empty, re-install:
+
+```bash
+cd ~/dev/design-ai && git pull && ./install.sh
+```
+
+### Updates not reflected
+
+```bash
+# In VS Code:
+Cmd+Shift+P → "design-ai: Refresh tree"
+```
+
+### Korean file doesn't open
+
+Check `design-ai.language` setting. The Korean variant must exist (`README.ko.md`, `docs/QUICKSTART.ko.md`, etc.). Not all files have Korean translations yet.
+
+## Next
+
+- [`docs/integrations/codex-walkthrough.md`](codex-walkthrough.md) — Codex CLI variant
+- [`docs/integrations/cursor-walkthrough.md`](cursor-walkthrough.md) — Cursor variant
+- [`docs/integrations/aider-walkthrough.md`](aider-walkthrough.md) — Aider variant
+- [`docs/integrations/sdk-walkthrough.md`](sdk-walkthrough.md) — Anthropic / OpenAI SDK
+- [VS Code extension source](https://github.com/sungjin9288/design-ai/tree/main/vscode-extension)

package/docs/requirements.txt

@@ -0,0 +1,16 @@
+# mkdocs-material requirements for the design-ai doc site.
+#
+# Local preview:
+#   pip install -r docs/requirements.txt
+#   ./tools/build-docs.sh   # populate site-src/ with symlinks
+#   mkdocs serve
+#
+# Pinned to floor versions known to work as of 2026-05.
+# Older versions (mkdocs-material 9.5 + pymdown-extensions 10.12) had a
+# pygments/pymdown interaction bug; the versions below resolve it.
+
+mkdocs>=1.6.1
+mkdocs-material>=9.7.0
+mkdocs-static-i18n>=1.3.0
+pymdown-extensions>=10.21.0
+pygments>=2.18.0

package/docs/site-overrides/extra.css

@@ -0,0 +1,83 @@
+/* design-ai mkdocs-material theme overrides */
+
+/* Pretendard for Korean + Latin (variable font from CDN) */
+@font-face {
+  font-family: "Pretendard";
+  font-weight: 45 920;
+  font-style: normal;
+  font-display: swap;
+  src: url("https://cdn.jsdelivr.net/gh/orioncactus/pretendard/dist/web/variable/woff2/PretendardVariable.woff2") format("woff2-variations");
+}
+
+/* Apply Pretendard to Korean characters; keep Inter for Latin readability */
+:root {
+  --md-text-font: "Inter", "Pretendard", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", sans-serif;
+  --md-code-font: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+
+/* Korean character font fallback (for content that mixes scripts) */
+:lang(ko), :lang(ko-KR), .md-typeset :is(*[lang="ko"], *[lang="ko-KR"]) {
+  font-family: "Pretendard", "Apple SD Gothic Neo", "Noto Sans KR", sans-serif;
+}
+
+/* Brand color tweak — slightly more saturated indigo for headlines */
+:root {
+  --md-primary-fg-color: #4f46e5;
+  --md-primary-fg-color--light: #6366f1;
+  --md-primary-fg-color--dark: #3730a3;
+  --md-accent-fg-color: #7c3aed;
+}
+
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: #818cf8;
+  --md-primary-fg-color--light: #a5b4fc;
+  --md-primary-fg-color--dark: #6366f1;
+  --md-accent-fg-color: #c4b5fd;
+}
+
+/* Code blocks: tighter line-height for dense knowledge files */
+.md-typeset pre code {
+  line-height: 1.55;
+}
+
+/* Tables: bring out the headers a bit */
+.md-typeset table:not([class]) th {
+  font-weight: 600;
+  background-color: rgba(99, 102, 241, 0.05);
+}
+
+/* Korean-specific reading optimization */
+.md-typeset {
+  font-feature-settings: "kern", "ss01", "ss02";
+  word-break: keep-all;
+  overflow-wrap: break-word;
+}
+
+/* Preserve Korean word boundaries (don't break mid-syllable) */
+.md-typeset h1, .md-typeset h2, .md-typeset h3 {
+  word-break: keep-all;
+}
+
+/* Coverage banner on home page */
+.md-content__inner h1:first-of-type + p strong {
+  display: inline-block;
+  background: linear-gradient(135deg, #4f46e5 0%, #7c3aed 100%);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+/* Header search field tweak for Korean input */
+.md-search__input {
+  font-family: var(--md-text-font);
+}
+
+/* Korean copy in admonitions */
+.md-typeset .admonition :lang(ko) {
+  line-height: 1.7; /* Korean needs more leading */
+}
+
+/* Footer */
+.md-footer-meta {
+  background: linear-gradient(135deg, #1e1b4b 0%, #312e81 100%);
+}

package/docs/site-overrides/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <rect width="32" height="32" rx="6" fill="#4f46e5"/>
+  <path d="M9 9h6c4.418 0 8 3.134 8 7s-3.582 7-8 7H9V9zm3 3v8h3c2.761 0 5-1.79 5-4s-2.239-4-5-4h-3z" fill="white"/>
+</svg>

package/docs/site-overrides/logo.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <rect width="32" height="32" rx="8" fill="url(#bg)"/>
+  <path d="M9 9h6c4.418 0 8 3.134 8 7s-3.582 7-8 7H9V9zm3 3v8h3c2.761 0 5-1.79 5-4s-2.239-4-5-4h-3z" fill="white"/>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="32" y2="32" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#4f46e5"/>
+      <stop offset="1" stop-color="#7c3aed"/>
+    </linearGradient>
+  </defs>
+</svg>

package/docs/site-overrides/main.html

@@ -0,0 +1,18 @@
+{% extends "base.html" %}
+
+{# Custom announcement bar #}
+{% block announce %}
+  Looking for an AI design partner? Run <code>npx @design-ai/cli install</code> — 20 skills, 17 commands, Korean market depth. <a href="{{ 'docs/QUICKSTART/' | url }}">5-minute quickstart</a>.
+{% endblock %}
+
+{# Hero / extra above-the-fold content for the home page #}
+{% block extrahead %}
+  {{ super() }}
+  <meta name="description" content="A model-agnostic design knowledge base + skill system. Senior product designer for any AI coding agent. 92 knowledge files covering UI/UX, website improvement, design systems, motion, illustration, print, video, game UI, conversational, and spatial design. Korean market depth.">
+  <meta property="og:title" content="design-ai — Senior product designer for any AI coding agent">
+  <meta property="og:description" content="92 knowledge files, 223 worked examples, 20 skills, 17 commands. Korean market depth across all domains. Open-source MIT.">
+  <meta property="og:type" content="website">
+  <meta name="twitter:card" content="summary">
+  <meta name="twitter:title" content="design-ai">
+  <meta name="twitter:description" content="Senior product designer for any AI coding agent. Korean market depth.">
+{% endblock %}