Design AI¶

🇺🇸 English / 🇰🇷 한국어

A model-agnostic design knowledge base + skill system. Drop it in front of any AI coding agent (Claude Code, Codex CLI, Cursor, Aider) and it becomes a senior product designer with 20+ years of experience — opinionated, accessible-by-default, Korean-market-fluent.

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.

Distribution status, checked 2026-07-04: local npm run release:check passes, GitHub Pages docs are live, GitHub Release v4.59.0 is published, @design-ai/cli@4.59.0 is public on npm (latest) with provenance, and the live npm run registry:smoke passes cleanly against @design-ai/cli@4.59.0. The Homebrew formula is pinned to v4.59.0, and sungjin.design-ai-vscode@0.4.1 is public on the VS Code Marketplace. See docs/external-status.md.

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`
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

Any available path installs all 20 skills, 17 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

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 { 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 (Phase A). SDK reference.
Plain prompt	Paste any `skills/*/PLAYBOOK.md` body — each is self-contained.

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/               # 94 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/                # 221 worked outputs (what "good" looks like)
│
├── skills/                  # 20 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/
│   ├── 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/                # 17 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
│   ├── extract-tokens.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:

Source	Why
ant-design	Mature enterprise component API, dense token system
mui/material-ui	Material Design React reference
shadcn-ui	Modern Radix-based copy-paste model
material-design-icons	Canonical icon set
nerd-fonts	Developer typography glyph metadata
material-design-lite	Historical CSS-first Material reference
awesome-design-md	Curated design markdown guides
ui-ux-pro-max	UI/UX patterns + palettes + font pairings
open-design	Open source design system reference

Refresh refs/ on demand: ./tools/extractors/run-all.sh.

Status¶

See docs/ROADMAP.md for the full phase log and docs/PRODUCT-READINESS.md for the current completion boundary. Currently at v4.59.0: the read-only Agent SDK (@design-ai/cli/sdk), public npm publish, provenance-backed GitHub Actions release, public registry smoke, Website Console MCP readiness, workspace learning restore/eval coverage, handoff bundle verification, and 90%+ component coverage are complete.

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, and bundle export/verify/repair. 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: - 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  marker if hand-authored. - Skill PLAYBOOKs include a verification phase checklist. - 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.