@design-ai/cli

v5.0.0

Published

17 hours ago

Senior product designer for any AI coding agent. Installs design-ai (21 skills, 16 commands, 4 agents) into Claude Code globally. Korean market depth plus interface craft and website improvement workflows.

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-07: local npm run release:check passes, GitHub Pages docs are live, GitHub Release v4.65.0 is published, @design-ai/[email protected] is public on npm (latest) with provenance, and the live npm run registry:smoke passes cleanly against @design-ai/[email protected]. The Homebrew formula is pinned to v4.65.0, and [email protected] 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 | | 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

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, 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. | | 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/               # 96 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:

| 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 | | OpenTag | Agentic inline results and human-gated action workflow reference | | WWIT | Korean app pattern taxonomy reference | | React Bits | Animated React component adoption-gate reference |

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. v4.65.0 remains the published baseline with CLI–SDK–MCP parity and 14 MCP tools. The current source is the v5.0.0 release candidate: it adds the agentic-design-development route, the read-only design_ai_site_bundle_handoff, design_ai_site_linked_preview, and design_ai_artifact tools (17 source MCP tools total), the SDK artifact() adapter (10 exports total), 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. It also restores dashboard chart knowledge, makes token extraction clone-only, and strengthens public-contract and PR verification. The major version records removal of the former public extract-tokens command.

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