@design-ai/cli 4.55.0

package/docs/MCP-INTEGRATION.md

@@ -0,0 +1,243 @@
+# MCP integration overview
+
+design-ai is an MCP-aware system. When MCP servers are connected to your AI agent, design-ai's skills and commands invoke them directly to read from / write to external tools (Figma, Notion, GitHub, Slack, Linear).
+
+design-ai can also run as its own local stdio MCP server. Use this when you want Claude Code or Codex to call design-ai tools directly instead of asking the agent to read files manually. See [`integrations/design-ai-mcp-server.md`](integrations/design-ai-mcp-server.md).
+
+## Two MCP modes
+
+| Mode | What connects | Use when |
+| --- | --- | --- |
+| design-ai uses external MCPs | Claude/Codex loads Figma, GitHub, Slack, Notion, or Linear MCP servers; design-ai skills use those tools when available. | You need live product workflow context or write-back to external tools. |
+| design-ai as an MCP server | Claude/Codex loads `design-ai mcp`; design-ai exposes route, prompt, pack, search, show, examples, check, and Website Improvement readiness tools. | You want agents to call design-ai through MCP without manually opening repo files. |
+
+## What MCP enables for design-ai
+
+Without MCP, design-ai produces markdown deliverables. The user manually pastes/copies them into other tools.
+
+With MCP, design-ai can:
+
+| MCP | Input from | Output to |
+| --- | --- | --- |
+| **Figma** | Read Variables, components, frames | Write Variables, comment on frames |
+| **Notion** | Read team's design decisions, brand briefs | Sync knowledge base to a Notion site |
+| **GitHub** | Read PRs for design review | Comment on PRs with audit findings |
+| **Slack** | — | Post design review summaries to a channel |
+| **Linear** | Read design system tasks | Create issues for design debt |
+| **Atlassian (Jira/Confluence)** | Read briefs, design decisions | Mirror knowledge to Confluence |
+
+This turns design-ai from "a document generator" into "an agent that operates on real product workflows."
+
+## Supported MCPs
+
+### Tier 1 — high-value, well-supported
+
+| MCP | Status | Use cases |
+| --- | --- | --- |
+| **Figma** | ✓ stable, official | Token sync, component spec extraction, code-connect mapping |
+| **Notion** | ✓ stable | Knowledge mirror, design-decision capture |
+| **GitHub** | ✓ stable | PR design review, issue creation |
+| **Slack** | ✓ stable | Posting design review summaries, sharing artifacts |
+
+### Tier 2 — useful, mature
+
+| MCP | Use cases |
+| --- | --- |
+| **Linear** | Track design system debt as issues |
+| **Atlassian** (Jira/Confluence) | Enterprise alternative to Linear+Notion |
+| **Asana** | Alternative project tracking |
+| **Intercom** | Read user feedback for design audits |
+
+### Tier 3 — situational
+
+| MCP | Use cases |
+| --- | --- |
+| **Canva** | Asset reference (less common for design systems) |
+| **Apollo / Common Room** | Sales/CRM — not design |
+| **Hubspot** | Marketing — UX feedback only |
+
+design-ai's per-MCP integration guides cover Tier 1 + 2.
+
+## Per-integration guides
+
+| Guide | What it covers |
+| --- | --- |
+| [`integrations/design-ai-mcp-server.md`](integrations/design-ai-mcp-server.md) | Running design-ai itself as a stdio MCP server for Claude Code and Codex |
+| [`integrations/figma-mcp.md`](integrations/figma-mcp.md) | Reading variables/components, writing tokens, code-connect via MCP |
+| [`integrations/notion-mcp.md`](integrations/notion-mcp.md) | Mirror knowledge base to a Notion site, capture design decisions |
+| [`integrations/github-mcp.md`](integrations/github-mcp.md) | PR design review, issue creation, design system change tracking |
+| [`integrations/slack-mcp.md`](integrations/slack-mcp.md) | Post review summaries, share artifacts, notify on token changes |
+| [`integrations/linear-mcp.md`](integrations/linear-mcp.md) | Create/update issues, track design debt |
+
+## Setup overview
+
+Each MCP requires:
+1. **Server installation** (per-MCP — see vendor docs).
+2. **Auth** (OAuth flow per MCP — done once per workspace).
+3. **Agent configuration** (e.g., `~/.codex/mcp.json`, Claude Code's MCP settings).
+
+After setup, MCP tools appear in your agent's available tools. design-ai's skills detect and use them.
+
+### Claude Code
+
+```bash
+# Add design-ai itself as a local stdio MCP server
+claude mcp add --transport stdio design-ai -- design-ai mcp
+
+# Install Figma MCP (example)
+claude mcp add figma -- node /path/to/figma-mcp-server
+# Auth flow opens browser
+```
+
+### Codex CLI
+
+Use the CLI:
+
+```bash
+codex mcp add design-ai -- design-ai mcp
+```
+
+Or edit `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.design-ai]
+command = "design-ai"
+args = ["mcp"]
+```
+
+### Cursor
+
+Cursor's MCP settings UI (mid-2025+). Add server, complete auth.
+
+## When MCP is unavailable (graceful fallback)
+
+design-ai's skills are designed to work **without** MCPs. When an MCP is missing:
+
+- Figma read → user provides Figma export JSON manually
+- Notion sync → user copies the markdown manually
+- GitHub PR comment → user pastes the audit into the PR review
+
+Skills detect MCP availability and choose path:
+
+```
+[skill check]
+- mcp__Figma__get_variable_defs available? Use it.
+- Else? Ask user for the exported JSON or paste of token list.
+```
+
+This keeps design-ai useful in environments without MCP setup.
+
+## MCP-aware skills
+
+These skills explicitly leverage MCPs when present:
+
+| Skill | MCP used (when available) |
+| --- | --- |
+| `design-pr-review` | GitHub (read PR), Figma (compare designs) |
+| `figma-token-sync` | Figma (read/write Variables) |
+| `design-broadcast` | Slack (post), Notion (page) |
+
+See [`skills/README.md`](../skills/README.md) for full playbooks.
+
+## MCP catalog with design-ai relevance
+
+For each MCP, note **what design-ai can do with it** (concrete actions):
+
+### Figma MCP
+
+```
+mcp__Figma__get_metadata          # File structure
+mcp__Figma__get_design_context    # Selected node's tokens, styles, components
+mcp__Figma__get_variable_defs     # All Figma Variables
+mcp__Figma__get_screenshot        # Render frame as image
+mcp__Figma__get_code_connect_map  # Existing Code Connect mappings
+mcp__Figma__add_code_connect_map  # Add new mapping
+mcp__Figma__create_design_system_rules  # Apply rules to a file
+```
+
+design-ai uses these for:
+- Extracting tokens from a real Figma file
+- Auditing a Figma design against the spec
+- Generating component specs from existing Figma components
+
+### Notion MCP
+
+```
+mcp__864aac7f-...__notion-fetch          # Read page/database
+mcp__864aac7f-...__notion-search         # Find pages
+mcp__864aac7f-...__notion-create-pages   # Create new
+mcp__864aac7f-...__notion-update-page    # Edit existing
+mcp__864aac7f-...__notion-create-database
+mcp__864aac7f-...__notion-create-comment
+mcp__864aac7f-...__notion-get-users
+```
+
+design-ai uses these for:
+- Mirroring knowledge files as Notion pages
+- Reading team's design decisions / brand briefs
+- Creating the design-ai knowledge index in Notion
+
+### GitHub MCP
+
+```
+mcp__plugin_engineering_github__authenticate
+# After auth:
+github__get_pull_request
+github__list_pull_requests
+github__create_pr_comment
+github__create_issue
+github__list_issues
+github__get_repo_contents
+```
+
+design-ai uses these for:
+- Reading PR diff to audit design system compliance
+- Posting review comments on PRs
+- Creating issues for design debt found in audits
+
+### Slack MCP
+
+```
+mcp__plugin_design_slack__authenticate
+# After auth:
+slack__send_message
+slack__list_channels
+slack__find_user
+slack__upload_file
+```
+
+design-ai uses these for:
+- Posting design review summaries
+- Sharing palette / spec artifacts to a `#design` channel
+- Pinging the right people on token changes
+
+### Linear MCP
+
+```
+mcp__plugin_design_linear__authenticate
+# After auth:
+linear__list_issues
+linear__create_issue
+linear__update_issue
+linear__list_projects
+```
+
+design-ai uses these for:
+- Creating issues for each gap found in a design system audit
+- Tracking the rollout of a new design system version
+- Querying status of design debt items
+
+## Privacy considerations
+
+- **Figma file URLs are sensitive**. Don't commit to public repos.
+- **Notion / GitHub auth tokens** are stored per-agent in their respective config files. Don't share.
+- **Don't post auth secrets to chat or commit logs**.
+- design-ai's skills should never log or echo MCP auth tokens.
+
+## Cross-reference
+
+- [`docs/USING.md`](USING.md) — multi-agent setup
+- [`docs/CODEX-INTEGRATION.md`](CODEX-INTEGRATION.md) — Codex MCP setup
+- [`docs/CURSOR-INTEGRATION.md`](CURSOR-INTEGRATION.md) — Cursor MCP setup
+- [`docs/AIDER-INTEGRATION.md`](AIDER-INTEGRATION.md) — Aider (no MCP yet)
+- [`docs/integrations/figma-mcp.md`](integrations/figma-mcp.md) — per-MCP guide examples

package/docs/MIGRATION-v4.md

@@ -0,0 +1,121 @@
+# Migration to v4.0.0
+
+v4.0 is a **graduation release**, not a breaking-change release. Everything that worked at v3.12 keeps working at v4.0 — the major bump signals that the corpus is now stable, audited, and release-checklisted.
+
+## TL;DR
+
+- **No code changes required.** v3.x adopters can `npm install -g @design-ai/cli@4` and everything continues to work.
+- **No knowledge file paths changed.** Imports, references, and link-check all stable.
+- **No skill / command / agent renames.**
+- **CLI surface unchanged.** `design-ai install`, `design-ai status`, `design-ai list ...` all identical.
+- **Plugin manifest schema unchanged.** Existing plugin consumers see only the version bump.
+
+## What v4.0 means
+
+| Surface | Promise |
+|---|---|
+| **Knowledge files (91)** | Frozen at `version: 1.0.0`, `stability: stable`. Future content edits bump per-file `last_updated`; structural changes bump per-file `version`. |
+| **Skills (19)** | API-stable. New skills can be added in 4.x minor releases; removals require a deprecation cycle (deprecate in 4.x, remove in 5.0). |
+| **Slash commands (15)** | API-stable. Same deprecation policy. |
+| **Review agents (4)** | API-stable. |
+| **CLI (`@design-ai/cli`)** | Argv contract stable. Adopters can pin to `^4.0.0`. |
+| **Plugin manifest (`.claude-plugin/plugin.json`)** | Schema stable. Field additions are non-breaking; field removals require a major bump. |
+| **VS Code extension** | Configuration keys stable (`design-ai.path`, `design-ai.language`). |
+| **Doc site URL structure** | `/skills/`, `/knowledge/<domain>/`, `/examples/`, `/integrations/`, `/ko/...` paths frozen. |
+
+## What v4.0 does NOT promise
+
+- **Knowledge content stability.** Individual knowledge files can be edited freely (typo fixes, example additions, Korean polish, factual corrections). Edits bump `last_updated`. Structural rewrites of a single file bump that file's `version`.
+- **Component coverage stability.** New component specs can be added in 4.x minors; the canonical-coverage percentage will continue rising.
+- **Korean translation completeness.** More `*.ko.md` files will arrive in 4.x; not breaking when they do.
+
+## Stability levels (recap)
+
+All v3.12 knowledge files were at `stability: stable` already; v4.0 retains that.
+
+| Level | Meaning | v4.0 policy |
+|---|---|---|
+| `stable` | Reviewed; canonical | Removed only with deprecation cycle |
+| `beta` | Substantively complete; pending polish | Can be promoted to `stable` mid-4.x |
+| `experimental` | Active iteration | May change significantly within 4.x |
+| `deprecated` | Superseded | Removed in 5.0 |
+
+No file currently sits at `experimental` or `deprecated` — those will appear during 4.x evolution.
+
+## Deprecation policy (effective from v4.0)
+
+Anything publicly documented (skills, commands, CLI flags, plugin fields, knowledge file IDs) follows:
+
+1. **Deprecate in 4.x:** Add `deprecated: true` (or stability `deprecated` for knowledge), update docs, log a deprecation warning.
+2. **Maintain in 4.x:** All deprecated surfaces keep working through the 4.x line.
+3. **Remove in 5.0:** Only at the next major bump.
+
+Adopters get at least one full minor cycle of warnings before anything disappears.
+
+## How to upgrade
+
+### NPM CLI
+
+```bash
+npm install -g @design-ai/cli@4
+design-ai version  # should print 4.0.0
+design-ai status
+```
+
+### Plugin (manual / git clone)
+
+```bash
+cd ~/.claude/plugins/design-ai  # or wherever you installed
+git pull
+git checkout v4.0.0
+```
+
+### Homebrew
+
+```bash
+brew update
+brew upgrade design-ai
+```
+
+(Note: the Homebrew formula update happens after the v4.0 GitHub release tarball is published — see `docs/RELEASE-CHECKLIST.md` "For Homebrew formula updates".)
+
+### VS Code extension
+
+The extension is not yet on the marketplace as of v4.0.0 tag. Install from `.vsix`:
+
+```bash
+cd vscode-extension
+npm install
+npx @vscode/vsce package
+code --install-extension design-ai-*.vsix
+```
+
+## Verification after upgrade
+
+```bash
+design-ai version             # 4.0.0
+design-ai list skills         # 19 skills
+design-ai list commands       # 15 commands
+design-ai list knowledge      # 91 files
+```
+
+If any count is lower, the install is incomplete — re-run `design-ai install`.
+
+## Why v4.0 (and not v3.13)?
+
+The v3.x line accumulated:
+- A whole-corpus invariant (all knowledge files versioned, all stable).
+- A pre-release ritual (RELEASE-CHECKLIST.md).
+- Six audits gating CI.
+- Four distribution channels.
+- Two languages.
+- A documented session log.
+
+That's a different *kind* of project than v3.0 was. The major bump signals the maturity transition to adopters considering whether to adopt — they're now adopting a release-engineered tool, not an evolving prototype.
+
+## Cross-reference
+
+- [`CHANGELOG.md`](../CHANGELOG.md) — full v4.0.0 release notes
+- [`docs/RELEASE-CHECKLIST.md`](RELEASE-CHECKLIST.md) — pre-release ritual
+- [`docs/SESSION-LOG.md`](SESSION-LOG.md) — narrative v2.0 → v4.0
+- [`docs/ROADMAP.md`](ROADMAP.md) — per-phase detail

package/docs/PLUGIN-PACKAGING.md

@@ -0,0 +1,240 @@
+# Plugin packaging
+
+Packaging design-ai as a Claude Code plugin so others can install it via `/plugin install`. Future-state — Claude Code's plugin format is evolving; this guide reflects the current symlink approach + likely future direction.
+
+## Current state — symlink approach (works today)
+
+Claude Code reads skills/agents/commands from `~/.claude/`. To "install" design-ai globally:
+
+```bash
+# From the design-ai project root
+cd /path/to/design-ai
+
+mkdir -p ~/.claude/skills ~/.claude/agents ~/.claude/commands
+
+# Skills
+for d in skills/*/; do
+  name=$(basename "$d")
+  ln -sf "$(pwd)/$d" "$HOME/.claude/skills/design-$name"
+done
+
+# Agents
+for f in agents/*.md; do
+  base=$(basename "$f")
+  [ "$base" = "README.md" ] && continue
+  ln -sf "$(pwd)/$f" "$HOME/.claude/agents/$base"
+done
+
+# Slash commands
+for f in commands/*.md; do
+  base=$(basename "$f")
+  [ "$base" = "README.md" ] && continue
+  ln -sf "$(pwd)/$f" "$HOME/.claude/commands/design-${base}"
+done
+```
+
+After symlink:
+- `/design-design-from-brief`, `/design-palette-from-brand`, etc. available globally
+- `design-color-palette`, `design-component-spec-writer`, etc. available as skills
+- `design-critic`, `design-system-qa`, etc. available as agents
+
+Pulling latest design-ai updates them automatically (symlinks point to the working copy).
+
+## Trade-offs of symlinks
+
+| Pro | Con |
+| --- | --- |
+| Auto-updates as you `git pull` design-ai | User must manually run the symlink script |
+| No packaging overhead | Doesn't survive `~/.claude/` reset |
+| Knowledge files (`knowledge/`) aren't installed (referenced by skill files) | Skill files reference paths relative to `design-ai/` — works only when the symlink target is intact |
+
+For solo / team use, this works fine. For wider distribution, a real plugin is needed.
+
+## Future state — Claude Code plugin format
+
+Claude Code's plugin format is evolving (as of mid-2025). Likely components:
+
+```
+design-ai-plugin/
+├── plugin.json              # manifest
+├── README.md
+├── LICENSE
+├── skills/                  # auto-loaded skills
+├── agents/                  # auto-loaded agents
+├── commands/                # auto-loaded slash commands
+├── knowledge/               # bundled knowledge files
+└── examples/                # bundled examples
+```
+
+A `plugin.json` manifest something like:
+
+```json
+{
+  "name": "design-ai",
+  "version": "1.5.0",
+  "description": "Senior product designer for any LLM agent — knowledge base + skills for design system, palette, components, UX audits.",
+  "author": "your-name",
+  "license": "MIT",
+  "homepage": "https://github.com/your-org/design-ai",
+  "exposes": {
+    "skills": ["color-palette", "design-system-builder", "component-spec-writer", "ux-audit", "design-critique", "handoff-spec", "design-system-qa"],
+    "agents": ["design-critic", "a11y-reviewer", "token-extractor", "component-architect"],
+    "commands": ["design-from-brief", "iterate", "design-review", "palette-from-brand", "component-spec", "extract-tokens"]
+  },
+  "knowledge_bases": ["knowledge"],
+  "claude_code": {
+    "minVersion": "0.x.x"
+  }
+}
+```
+
+(Exact schema TBD — check Claude Code's plugin SDK when published.)
+
+### Installation by users
+
+Once packaged:
+
+```bash
+# In Claude Code:
+/plugin install design-ai
+```
+
+Or:
+
+```bash
+/plugin install https://github.com/your-org/design-ai
+```
+
+Plugin manager handles fetch, version pinning, and integration.
+
+## Distribution channels
+
+| Channel | Use |
+| --- | --- |
+| **Claude Code marketplace** (when available) | Public, discoverable, version-managed |
+| **Public GitHub** (current) | Direct install from URL; manual symlink |
+| **Internal GitHub** | Same as public but private |
+| **npm-style package** (when available) | Versioned distribution via package manager |
+
+For this project (currently): GitHub + symlink approach is the right level.
+
+## Versioning strategy
+
+Semantic versioning with explicit breaking-change policy:
+
+| Bump | Triggers |
+| --- | --- |
+| Patch (1.5.0 → 1.5.1) | Bug fixes, knowledge file updates, extractor improvements |
+| Minor (1.5.0 → 1.6.0) | New skills, new agents, new knowledge files, new extractors |
+| Major (1.5.0 → 2.0.0) | Breaking changes to skill APIs, knowledge file schema changes, removal of skills |
+
+Tag releases:
+
+```bash
+git tag -a v1.5.0 -m "v1.5.0 — Phase 6: token references + design-system-qa skill + Codex/plugin docs"
+git push origin v1.5.0
+```
+
+## CI for releases
+
+A simple release pipeline:
+
+```yaml
+# .github/workflows/release.yml
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Run audit to verify state
+      - run: python3 tools/audit/check-coverage.py
+      - run: bash tools/extractors/run-all.sh
+
+      # Verify knowledge/COVERAGE.md is in sync
+      - run: git diff --exit-code knowledge/COVERAGE.md
+
+      # Lint frontmatter on knowledge files
+      - run: python3 tools/lint/frontmatter-check.py
+
+      # Optional: build a tarball / zip for plugin distribution
+      - run: tar czf design-ai-$(git describe --tags).tar.gz \
+          AGENTS.md CLAUDE.md README.md \
+          knowledge/ skills/ agents/ commands/ examples/ docs/
+
+      # Optional: upload to release
+      - uses: softprops/action-gh-release@v1
+        with:
+          files: design-ai-*.tar.gz
+```
+
+The lint and audit gates ensure no PR ships a half-built knowledge file.
+
+## CHANGELOG
+
+For users tracking updates: maintain a top-level `CHANGELOG.md`:
+
+```markdown
+# Changelog
+
+## [1.5.0] — 2026-XX-XX
+
+### Added
+- Tailwind v4, Material 3, Polaris+Carbon token references
+- design-system-qa skill (5-layer test pyramid)
+- Codex CLI integration guide (docs/CODEX-INTEGRATION.md)
+- Plugin packaging guide (docs/PLUGIN-PACKAGING.md)
+
+### Changed
+- AGENTS.md lookup table extended with new entries
+- knowledge/PRINCIPLES.md updated
+
+### Fixed
+- (none)
+
+## [1.4.0] — 2026-05-XX
+...
+```
+
+Generated by `git log` filtered to user-impacting commits — the existing commit messages already follow this discipline.
+
+## License + attribution
+
+Currently no LICENSE file. For public distribution, add MIT or similar permissive license (matches the upstream design system source materials' general permissiveness).
+
+For attribution: the knowledge base draws from Ant Design (MIT), MUI (MIT), shadcn-ui (MIT), Material Design (Apache 2.0), Polaris (MIT), Carbon (Apache 2.0), and others. Include an `ACKNOWLEDGEMENTS.md` listing source projects and their licenses.
+
+## Migration when plugin format is finalized
+
+When Claude Code publishes the plugin SDK:
+
+1. Add `plugin.json` per the schema.
+2. Create a `release/` branch with bundled `knowledge/` + symlink rules.
+3. Submit to marketplace.
+
+The current repo structure already maps cleanly to the likely plugin layout — minimal restructuring expected.
+
+## For now: what to actually do
+
+If you're a single user / small team:
+
+1. Use the symlink approach above.
+2. Treat the repo as your "plugin" — pull updates via `git pull`.
+3. Don't worry about `plugin.json` until the format is real.
+
+If you want to share with others:
+
+1. Push to public GitHub.
+2. Document the symlink steps in the README.
+3. Tag releases (`git tag v1.x`).
+4. When plugin format ships, repackage.
+
+## Cross-reference
+
+- [`docs/USING.md`](USING.md) — multi-agent setup (includes symlink instructions)
+- [`docs/CODEX-INTEGRATION.md`](CODEX-INTEGRATION.md) — Codex-specific integration
+- [`README.md`](https://sungjin9288.github.io/design-ai/) — project overview