Design AI
🇺🇸 English / 🇰🇷 한국어
Archived (2026-10). This repository is read-only and no longer
maintained. The published v5.4.0 stays available on npm, Homebrew, and the
VS Code Marketplace as-is, and the documentation site stays online. The
case study summarizes what was built and verified.
Not a model. Not a fine-tune. A structured corpus of design expertise + agent-ready instructions that turn a general-purpose LLM into an expert.
v5.4.0 is public. npm Trusted Publishing, SLSA provenance, GitHub Release,
and public registry smoke are verified against the published package, and the
Homebrew formula targets the v5.4.0 tag. See the
external publication status for exact evidence.
v5.4.0 moves review comparisons to schemaVersion 2, so a fix that static
inspection cannot pass reads attention-required instead of regressed; stored
version 1 comparisons stay valid.
Coverage at a glance
| Domain | Knowledge | Worked examples | Skill |
|---|
| Design tokens (W3C DTCG, OKLCH) | ✓ | ✓ | color-palette |
| Components (Ant + MUI + shadcn synthesis) | ✓ | 210 component specs | component-spec-writer |
| UX patterns (auth, pricing, hero, forms, etc.) | ✓ | ✓ | ux-audit, design-critique |
| Web/app interface craft (response, frequency, continuity, interruptibility) | ✓ | ✓ | design-engineering-review |
| Agentic design workflows (MCP, artifact contracts, human gates) | ✓ | ✓ | agentic-design-development, website-improvement, design-system-builder |
| Website improvement control tower | ✓ | ✓ | website-improvement |
| Korean i18n (Hangul, payments, app store, fintech) | ✓ | ✓ | (cross-cutting) |
| Documentation (Diátaxis, slide deck, report, email) | ✓ | ✓ | document-author, slide-deck-author |
| Motion (CSS / Framer / GSAP / Lottie / Rive) | ✓ | 4 specs | motion-designer |
| Illustration (spot / hero / mascot / SVG) | ✓ | 2 specs | illustration-designer |
| Print (CMYK, bleed, KFDA, 분리배출) | ✓ | 2 specs | print-designer |
| Video (codecs, captions, KR ad disclosure) | ✓ | 2 specs | video-designer |
| Game UI (HUD / menu / 확률 표시 / PC bang) | ✓ | 2 specs | game-ui-designer |
| Conversational (voice, chatbot, AI chat / 해요체) | ✓ | 2 specs | conversational-ui-designer |
| Spatial (VR / AR / Vision Pro / comfort) | ✓ | 2 specs | spatial-designer |
Install (Claude Code)
Option A: Git clone / local install
git clone https://github.com/sungjin9288/design-ai.git
cd design-ai
./install.sh
Option B: NPM
Use this path for the public npm package.
npx @design-ai/cli install
Or globally:
npm install -g @design-ai/cli
design-ai install
Option C: Homebrew tap
brew tap sungjin9288/design-ai https://github.com/sungjin9288/design-ai.git
brew install design-ai
design-ai install
The current source installs 21 skills, 16 public slash commands, and 4 agents under ~/.claude/ with the design- prefix. Restart Claude Code; try:
/design-component-spec Banner
/design-motion-design landing hero loop
/design-spatial Vision Pro productivity app
/design-website-improvement Korean SaaS homepage conversion and SEO control tower
/design-from-brief Korean fintech for freelancers
CLI commands include design-ai start <brief|--from-file file|--stdin> ..., the canonical design-ai review <source.html> --brief text ... workflow, self-validating design-ai review-handoff <review-workflow.json> --recipient name ..., consumer-side design-ai review-handoff-verify <review-handoff.json> --consumer name ..., bounded design-ai review-intake <receipt.json> --target-root path --consumer name ..., immutable design-ai review-scope <intake.json> --request request.json --consumer name ..., separate design-ai review-scope-approve <proposal.json> ... --yes, read-only design-ai review-evidence <approval.json> --request request.json --target-root path --consumer name ..., source-linked design-ai review-pilot <implementation-evidence.json> --workflow review-workflow.json --record pilot-record.json ..., design-ai review-pack [id], the lower-level design-ai inspect <source.html> --brief text --review-pack <id> ..., approval-gated design-ai verify-browser <quality-report.json> ..., and local design-ai image serve alongside the existing install, route, prompt, artifact, pack, learn, check, workspace, site, corpus, audit, MCP, version, and help workflows. Run design-ai help --json for the complete machine-readable catalog or design-ai help <command> for exact options.
Local Image Console
design-ai image serve starts a loopback-only, approval-gated image workflow. Prompt Guide credentials remain server-side; generation or editing creates a read-only validated draft before the configured provider-neutral local subprocess can run. See Prompt Guide Image Console for the server-only environment contract and synthetic fixtures.
Image Console release hardening shipped in v5.2.0; v5.4.0 only improves its
required-field errors and completion message.
Its published registry smoke passed. The verified flow is the deterministic local
mock loopback, which makes no Prompt Guide/provider-network call; a live Prompt
Guide call and a real provider generation/edit remain unverified.
See docs/DISTRIBUTION.md for the full distribution guide.
Install (other agents)
| Agent | Setup |
|---|
| Codex CLI | Open this dir as project root. AGENTS.md is read automatically. Walkthrough. |
| Claude Code / Codex via MCP | Add design-ai mcp as a local stdio MCP server. MCP server guide. |
| Cursor | Open this dir; symlink or copy AGENTS.md to .cursorrules. Walkthrough. |
| Aider | Pass AGENTS.md as system prompt. Walkthrough. |
| Anthropic / OpenAI SDK | Embed relevant skill PLAYBOOK.md files in your prompt. Walkthrough. |
| VS Code | Install the public Marketplace extension for sidebar trees + quick-pick commands. Walkthrough. |
| Node.js / Agent SDK | import { artifact, start, reviewHtml, reviewHandoff, verifyReviewHandoff, recordPilotEvidence, inspectHtml, route, prompt, pack, search, recall, check, routes, version } from "@design-ai/cli/sdk" — call design-ai's deterministic verbs as functions, no CLI shell-out or MCP server needed. Read-only except the explicit learn.* namespace. SDK reference. Walkthrough. |
See docs/USING.md for per-agent setup details, or the linked walkthroughs for concrete example sessions.
What you get
design-ai/
├── AGENTS.md # Universal entry point (any AI coding agent)
├── CLAUDE.md # Claude Code overlay
├── README.md # You are here
├── CHANGELOG.md # Release notes
├── install.sh # Symlink installer for Claude Code
│
├── .claude-plugin/ # Plugin manifest (plugin.json)
│
├── refs/ # Sparse-cloned upstream sources (gitignored)
│
├── knowledge/ # 98 hand-written + extracted knowledge files
│ ├── design-tokens/ # Token systems (W3C DTCG, OKLCH, HCT)
│ ├── components/ # Component synthesis (Ant + MUI + shadcn)
│ ├── patterns/ # Auth, pricing, landing hero, brand, email, ...
│ ├── colors/ # Palette systems, accessibility
│ ├── typography/ # Type scales, font pairings (Pretendard + ...)
│ ├── layout/ # Grid, spacing, responsive
│ ├── icons/ # Icon system metadata
│ ├── a11y/ # WCAG, keyboard, focus, contrast
│ ├── motion/ # Principles + 5 deep dives
│ ├── illustration/ # System / spot / hero / mascot / SVG
│ ├── print/ # Fundamentals / stationery / brochures / ...
│ ├── video/ # Fundamentals / marketing / social / ...
│ ├── game-ui/ # Fundamentals / HUD / menus / accessibility
│ ├── conversational/ # Voice / chatbot / AI chat / Korean
│ ├── spatial/ # VR / AR / panels / comfort
│ └── i18n/ # Korean typography, payments, app store, ...
│
├── examples/ # 226 worked outputs (what "good" looks like)
│
├── skills/ # 21 reusable playbooks (task-focused)
│ ├── design-system-builder/ illustration-designer/
│ ├── component-spec-writer/ print-designer/
│ ├── color-palette/ video-designer/
│ ├── ux-audit/ game-ui-designer/
│ ├── design-critique/ conversational-ui-designer/
│ ├── handoff-spec/ spatial-designer/
│ ├── design-system-qa/ document-author/
│ ├── design-pr-review/ website-improvement/
│ ├── design-engineering-review/
│ ├── figma-token-sync/ slide-deck-author/
│ ├── motion-designer/
│ └── design-broadcast/
│
├── agents/ # 4 sub-agents (parallel reviews)
│ ├── design-critic.md a11y-reviewer.md
│ ├── component-architect.md token-extractor.md
│
├── commands/ # 16 public slash commands
│ ├── design-from-brief.md motion-design.md
│ ├── component-spec.md illustration.md
│ ├── design-review.md website-improvement.md
│ ├── print.md
│ ├── palette-from-brand.md video.md
│ ├── document-from-brief.md game-ui.md
│ ├── slide-deck.md conversational.md
│ ├── iterate.md spatial.md
│ └── stability-review.md
│
├── tools/ # Maintenance pipeline
│ ├── extractors/ # 11 source extractors + component drift tooling
│ ├── audit/ # 8 active audits + package/release smoke helpers
│ └── preview/ # HTML token swatches + contrast matrix
│
└── docs/ # Architecture + integration guides
├── QUICKSTART.md ROADMAP.md
├── ARCHITECTURE.md USING.md
├── CONTRIBUTING.md PLUGIN-PACKAGING.md
├── CODEX-INTEGRATION.md FIGMA-INTEGRATION.md
├── CURSOR-INTEGRATION.md MCP-INTEGRATION.md
├── AIDER-INTEGRATION.md TOKEN-SYNC.md
└── DOGFOOD-FINDINGS.md
First-time tour (5 minutes)
See docs/QUICKSTART.md. The shortest path:
- Install (
./install.sh).
- In Claude Code, try
/design-component-spec Banner. You get a developer-ready spec for a Banner component (anatomy, API, variants, states, tokens, ARIA, keyboard, edge cases).
- Run
/design-design-review against a Figma link or screenshot. You get a parallel UX + a11y + design critique.
Korean market focus
design-ai is built for the Korean market with parity for international:
- Hangul typography — Pretendard / NanumSquare / 본명조 defaults; size + leading rules differ from Latin.
- Korean payments — Toss / KakaoPay / NaverPay / Apple Pay / Samsung Pay flows; PASS / NICE / KCB 본인인증.
- Voice — 합쇼체 (formal) vs 해요체 (friendly) selection per brand.
- Print — 명함 90×50mm, KFDA / KATS regulatory, 분리배출 표시 recycling marks.
- Video — 자막 conventions, 표시광고법 ad disclosure, KFDA / KFTC compliance.
- Game — PC bang culture, 확률 표시 mandatory, GRAC ratings, gacha pity / 천장.
- Stock charts — KR red=up / blue=down (opposite of West) — encoded in design tokens.
International defaults remain available; Korean conventions are opt-in via skill / command parameters.
Source material
The knowledge is synthesized from battle-tested sources, not invented:
Maintainers can refresh refs/ with ./tools/extractors/run-all.sh; token extraction is clone-only tooling, documented at tools/extractors/README.md.
Status
See docs/ROADMAP.md for the full phase log and docs/PRODUCT-READINESS.md for the current completion boundary. v5.0.0 established the major-version baseline with 21 skills, 16 public commands, 4 review agents, 17 MCP tools, and 10 SDK exports. It added the agentic-design-development route, the read-only design_ai_site_bundle_handoff, design_ai_site_linked_preview, and design_ai_artifact tools, the SDK artifact() adapter, and the design-engineering-review skill/route for evidence-grounded web/app interface craft review. The linked-preview operation reads only root project metadata and prepares an operator-controlled preview loop without starting a process, probing a URL, scanning source files, or mutating the target repo. The shared artifact operation produces implementation-plan, critique-loop, and agent-readable DESIGN.md contracts across CLI, SDK, MCP, and Website Console. The release also restored dashboard chart knowledge, made token extraction clone-only, strengthened public-contract and PR verification, and recorded removal of the former public extract-tokens command at the major-version boundary.
The v5.1.0 release adds the read-only design-ai start entry flow, an evidence-backed HTML inspector, five opt-in Korean product review packs, the optional CLI-only browser evidence runner, and design-ai benchmark for repeatable specialization proof. design-ai review, SDK reviewHtml(), MCP design_ai_review_html, and Website Console combine the start plan and static report into one canonical session with exact source identity, artifact linkage, ordered stages, and a pending human decision. P7 through P12 then preserve handoff, consumer validation, target intake, scope approval, implementation evidence, and one consented pilot without turning missing proof into a success claim. P13 adds CLI design-ai review-compare, SDK compareReviews(), MCP design_ai_compare_reviews, and Website Console comparison import. It compares two exact canonical quality reports for the same subject and context, records all eight lens transitions, and classifies findings as resolved, persistent, introduced, or uncertain. A finding disappears only as verified resolution when its candidate lens passes; otherwise uncertainty remains visible. Full and compact artifacts retain exact source references, SHA-256 digests, byte counts, approval gates, and claim boundaries. None of these operations establishes external adoption or production quality. Commit, push, deployment, migration execution, and external writes remain separate. The published contract contains 29 MCP tools and 20 SDK exports. See Verified design iteration.
Core design consulting workflows are locally release-ready. The website improvement control tower ships as a zero-dependency static Web App plus a website-improvement route/skill/command, covering Site Profiles, audit checklists, MCP readiness, refactor prompts, handoff evidence tracking, bundle export/verify/repair, linked-code preview readiness, and an explicit read-only intake → human approval → target-repo implementation → browser evidence contract. Greenfield homepage work can create a strict handoff from a repo URL or local path before a live URL exists; design-ai site <workspace.json> --linked-preview --json then detects the existing manual start command from root metadata. Browser and deployment evidence remains required after the operator starts a preview. Local learning preferences are available through design-ai learn — profile bootstrap, feedback capture, a read-only signals registry, skill-proposal generation from repeated QA signals, and full backup/restore/curate/audit tooling, all local-only and opt-in. AI model training or fine-tuning remains outside the shipped scope.
Full assertion-level detail for every one of the surfaces above — including every learn, site, and workspace flag and what it verifies — lives in docs/RELEASE-GATES.md.
The corpus has been audited under CI checks since v1.7. It currently runs 8 audits:
- Frontmatter validity
- Internal link resolution
- Korean copy quality
- Raw hex color hygiene in examples
- Integration walkthrough completeness
- Stale-content freshness
- Component coverage report freshness
- Top worked example QA for every routed workflow
All 8 pass on every commit to main.
Contributing
See docs/CONTRIBUTING.md. The bar:
- Install the documentation toolchain once with
pip install -r docs/requirements.txt; release:check includes the MkDocs build and warning policy.
- Run
npm run release:check as the core gate before release PRs or tags. It wraps npm test (CLI unit tests), npm run audit:strict (all 8 audits), git diff --check (whitespace), npm run package:check (package contents), npm run release:metadata (release metadata + Product Readiness guard), npm run release:self-test (release assertion self-tests), and npm run package:smoke (packed-tarball smoke covering install, site, workspace, learn, and help/version/audit surfaces for both installed-bin and one-shot npm exec --package <tarball> paths).
- After npm publish completes, run
npm run registry:smoke to verify the same surfaces against the public npm exec --package install path.
- Knowledge files use
<!-- hand-written --> marker if hand-authored.
- Skill PLAYBOOKs include a verification phase checklist.
npm run skills:check
also enforces Agent Skills metadata, activation wording, progressive-disclosure
linkage, playbook structure, durable guidance, and manifest inventory parity.
- Korean strings spelled out in Korean (no machine translation passing through).
- All audits pass.
- Before pushing for CI, run
npm run ci:local when you need local parity with the non-publishing GitHub workflows. It wraps release:check, Python syntax checks, knowledge size budget, VS Code extension compile/unit tests, the MkDocs build, and the MkDocs warning policy used by the docs deployment workflow: no non-refs/ warnings, with refs-only warnings capped at the accepted baseline.
The exhaustive list of every command and flag that release:check, packed-tarball smoke, and registry smoke assert on is preserved in docs/RELEASE-GATES.md.
License
MIT. See LICENSE.
Changelog
See CHANGELOG.md. Highlights:
- v3.0 — Stabilization: plugin manifest, install.sh, CHANGELOG, README overhaul, QUICKSTART.
- v2.7 — AR / VR / spatial design.
- v2.6 — Voice / conversational UI.
- v2.5 — Game UI.
- v2.4 — Video content.
- v2.3 — Print / physical design.
- v2.2 — Illustration systems.
- v2.1 — Motion design depth.
- v2.0 — Documentation worked examples + 7 component specs.
- v1.x — MCP integrations, document design + brand + email, coverage push, foundations.
