@design-ai/cli 4.55.0

package/docs/integrations/github-mcp.md

@@ -0,0 +1,178 @@
+# GitHub MCP integration
+
+Use GitHub MCP to bring design-ai into pull request review workflows. Audit PRs for design system compliance, post review comments, create issues for design debt.
+
+## Available tools (when GitHub MCP connected)
+
+After authenticating via `mcp__plugin_engineering_github__authenticate`:
+
+| Tool | What it does |
+| --- | --- |
+| `get_pull_request` | Read PR metadata, files changed, diff |
+| `list_pull_requests` | List PRs (open / merged / by author) |
+| `create_pr_comment` | Post a review comment |
+| `create_review` | Post a multi-comment review |
+| `create_issue` | New issue |
+| `list_issues` | Read issues |
+| `get_repo_contents` | Read file from a repo |
+| `update_pr` | Update title/description |
+
+## Workflow A: PR design review
+
+The headline use case. Agent reviews a PR for design system compliance.
+
+```
+You: Review PR #123 in our-org/web for design system compliance.
+Agent:
+  1. github__get_pull_request(repo="our-org/web", number=123)
+     [returns diff, files changed]
+  2. For each changed file:
+     - Read content via github__get_repo_contents
+     - Apply skills/design-system-qa/ checks:
+       * Raw hex values (instead of token references)?
+       * Missing aria-* attributes on new components?
+       * Hardcoded spacing values not on the 4-base scale?
+       * Missing prefers-reduced-motion handling?
+  3. Compile findings by file with severity.
+  4. github__create_review(repo=..., pr=123, body=summary, comments=[
+       {path: "src/Button.tsx", line: 23, body: "Use --color-primary-default, not #7C3AED"},
+       ...
+     ])
+```
+
+The agent posts inline review comments. Critical issues block merge.
+
+See the new [`skills/design-pr-review/PLAYBOOK.md`](../../skills/design-pr-review/PLAYBOOK.md).
+
+## Workflow B: create issues for design debt
+
+After running a UX audit / design system audit, file each finding as an issue.
+
+```
+You: Run skills/design-system-qa on our-org/web; create issues for criticals.
+Agent:
+  1. Pull repo state via github__get_repo_contents (or clone locally).
+  2. Apply design-system-qa playbook.
+  3. For each Critical finding:
+     github__create_issue(
+       repo="our-org/web",
+       title="[design-debt] Raw hex values in Button.tsx",
+       body=<finding details + cited knowledge file>,
+       labels=["design-debt", "design-system"]
+     )
+```
+
+Pairs well with Linear MCP for teams using Linear instead of GitHub Issues.
+
+## Workflow C: track design system PR status
+
+Generate a status report of design system-related PRs.
+
+```
+You: Show me design system PRs from the last 2 weeks.
+Agent:
+  1. github__list_pull_requests(repo=..., state=all, since=2weeks_ago)
+  2. Filter by labels (design-system, design-debt)
+  3. Categorize: shipped, in review, blocked, abandoned.
+  4. Output a markdown summary.
+```
+
+## Workflow D: comment on design system token bumps
+
+When a PR bumps the design tokens, design-ai checks for breaking changes.
+
+```
+PR opens that modifies tokens/source.json:
+  - Changed: --color-primary-default from #1976D2 to #0D9488
+
+Agent (via webhook or scheduled):
+  1. github__get_pull_request(...)
+  2. Detect token diff.
+  3. Run impact analysis: how many components consume this token?
+  4. github__create_pr_comment(
+       body=`Breaking change: --color-primary-default. Affects 47 components.
+             Verify Storybook visual tests pass before merging.`
+     )
+```
+
+## Setup
+
+### Authentication
+
+```
+# In Claude Code or other agent:
+mcp__plugin_engineering_github__authenticate
+```
+
+OAuth flow opens browser; user grants the GitHub App access. Per-workspace one-time.
+
+### Required scopes
+
+For full design-ai workflow:
+- `repo` (read code, PRs, issues)
+- `pull_requests:write` (post comments, reviews)
+- `issues:write` (create design debt issues)
+
+For read-only workflows (just review): `repo:read` is enough.
+
+### App config
+
+GitHub MCP server can be:
+- Anthropic-provided (managed) — simpler.
+- Self-hosted via `@modelcontextprotocol/server-github` — for security-sensitive orgs.
+
+## Common pitfalls
+
+| Pitfall | Fix |
+| --- | --- |
+| Auth expires after 1 hour | Re-authenticate. Some MCP servers refresh automatically. |
+| Rate limit (5K req/hour for GitHub API) | Cache PR contents; don't refetch the same PR multiple times. |
+| Large diffs return truncated | Use `get_repo_contents` per-file rather than full diff. |
+| Comments post but aren't visible | Check the user has commenting permission on the repo. |
+| Bot comments spam the PR | Aggregate findings into one review, not per-finding comments. |
+
+## Aggregation strategy
+
+Don't post 50 inline comments. Instead:
+
+```
+[Single Review Comment]
+Body:
+  ## Design system review: 12 issues
+  
+  ### Critical (3)
+  - Button.tsx:23 — Raw hex `#7C3AED` should be `--color-primary-default`
+  - Card.tsx:45 — Missing `aria-label` on icon-only button
+  - ...
+  
+  ### High (4)
+  - ...
+  
+  ### Cited references
+  - [knowledge/colors/color-theory.md](https://github.com/your-org/design-ai/...)
+  - ...
+```
+
+Plus 2–3 inline comments on the most-critical specific lines (where context matters).
+
+This is humane review — actionable summary at top, deep links to specifics.
+
+## Privacy
+
+- GitHub MCP has access to whatever the auth user can see.
+- Don't grant org-wide tokens for personal work.
+- Audit installed GitHub Apps quarterly.
+- design-ai never logs the auth token.
+
+## When GitHub MCP is unavailable
+
+`design-pr-review` skill falls back to:
+- User pastes the diff manually.
+- Agent outputs the review as markdown for the user to copy into the PR.
+
+## Cross-reference
+
+- [`docs/MCP-INTEGRATION.md`](../MCP-INTEGRATION.md) — overview
+- [`skills/design-pr-review/PLAYBOOK.md`](../../skills/design-pr-review/PLAYBOOK.md) — the MCP-aware skill
+- [`docs/integrations/linear-mcp.md`](linear-mcp.md) — Linear alternative for issue tracking
+- [`knowledge/patterns/design-system-qa.md`](../../knowledge/patterns/design-system-qa.md) — what gets checked

package/docs/integrations/linear-mcp.md

@@ -0,0 +1,215 @@
+# Linear MCP integration
+
+Use Linear MCP to track design system work, audit findings, and design debt as Linear issues. Pairs with `skills/design-system-qa` and `skills/ux-audit` to convert findings into trackable work.
+
+## Available tools (when Linear MCP connected)
+
+After authenticating via `mcp__plugin_design_linear__authenticate`:
+
+| Tool | What it does |
+| --- | --- |
+| `list_issues` | Read issues (filtered by team / state / labels) |
+| `get_issue` | Single issue detail |
+| `create_issue` | New issue |
+| `update_issue` | Edit existing |
+| `list_projects` | List Linear projects |
+| `list_teams` | List teams |
+| `add_comment` | Comment on an issue |
+
+## Workflow A: convert audit findings to issues
+
+After `/design-review` or `skills/design-system-qa`, file each finding as a Linear issue.
+
+```
+You: Run skills/design-system-qa on this codebase; create Linear issues for criticals.
+Agent:
+  1. Apply skills/design-system-qa/PLAYBOOK.md.
+  2. linear__list_teams() → find the design or eng team.
+  3. For each Critical finding:
+     linear__create_issue(
+       team="DESIGN",
+       title="[design-debt] Raw hex values in Button.tsx",
+       description=<finding details + cited knowledge file links>,
+       labels=["design-debt", "critical"],
+       priority=1,        // 1=urgent
+       project="Design System"
+     )
+  4. Output: list of created issue URLs.
+```
+
+## Workflow B: track design system rollout
+
+Use Linear's project + cycle structure to track rollout of a new design system version.
+
+```
+You: Plan the v2.0 design system rollout in Linear.
+Agent:
+  1. linear__create_project(
+       name="Design System v2.0",
+       description=<scope, goals>
+     )
+  2. For each component to migrate, create a sub-issue:
+     linear__create_issue(
+       team="ENG",
+       project=<project_id>,
+       title="Migrate Button to v2 tokens",
+       description=<migration checklist>,
+       labels=["design-system-v2"]
+     )
+  3. Output: project URL + issue list.
+```
+
+## Workflow C: read team's design backlog
+
+Before applying `/design-from-brief`, agent can read existing context from Linear.
+
+```
+You: What design issues are open right now?
+Agent:
+  1. linear__list_issues(
+       team="DESIGN",
+       state="in_progress",
+       labels=["design-system"]
+     )
+  2. Summarize: <N> open, <breakdown by priority>.
+```
+
+## Workflow D: link audit reports to existing issues
+
+When the same finding has been filed before, comment on the existing issue rather than duplicating.
+
+```
+You: Audit the dashboard; file Linear issues but check for duplicates.
+Agent:
+  1. Apply skills/ux-audit/PLAYBOOK.md.
+  2. For each finding:
+     - linear__list_issues(query=<finding title fragment>)
+     - If existing issue found:
+       linear__add_comment(issue=<existing>, comment="Audit re-confirms this issue: ...")
+     - Else:
+       linear__create_issue(...)
+```
+
+## Severity → Linear priority mapping
+
+design-ai's severity model translates to Linear priorities:
+
+| design-ai severity | Linear priority |
+| --- | --- |
+| 🔴 Critical | 1 (Urgent) |
+| 🟠 High | 2 (High) |
+| 🟡 Medium | 3 (Medium) |
+| 🟢 Low | 4 (Low) |
+
+## Issue formatting
+
+Use Linear's markdown for the description:
+
+```markdown
+## Finding
+Raw hex value `#7C3AED` in `src/components/Button/Button.tsx:23` instead of `--color-primary-default` token.
+
+## Why
+Hardcoded hex values cause:
+- Inability to theme the app
+- Drift from the design system
+- Manual updates required when tokens change
+
+## Cited rule
+[knowledge/PRINCIPLES.md](https://github.com/your-org/design-ai/blob/main/knowledge/PRINCIPLES.md) rule 2:
+> Tokens by role, not by hex.
+
+## Recommended fix
+Replace `#7C3AED` with `var(--color-primary-default)` (CSS) or `tokens.color.primary.default` (JS).
+
+## Detection rule
+Stylelint with `color-no-hex` rule would catch this on PR.
+```
+
+Linear's markdown supports:
+- Headings, paragraphs, lists
+- Code blocks (with language)
+- Inline code
+- Links
+- Mentions (`@username`)
+
+## Setup
+
+### Authentication
+
+```
+# In agent:
+mcp__plugin_design_linear__authenticate
+```
+
+OAuth → user grants Linear workspace access. Per-workspace once.
+
+### Required scopes
+
+- `read` (issues, projects, teams)
+- `write` (create / update issues)
+- `admin:project` (only if creating projects)
+
+### Team selection
+
+design-ai's issues should go to a designated team:
+- Design team (if dedicated): `DESIGN-`.
+- Eng team if design-and-eng-share: `ENG-`.
+- Specific design-system team if exists: `DS-`.
+
+Confirm with team lead. Document in `.cursorrules` or project-level config.
+
+## Workflow integration with design-system-qa
+
+`skills/design-system-qa` outputs a structured findings list. Each finding has:
+- Severity
+- Title
+- Location (file/line)
+- Cited knowledge
+
+Map this 1:1 to Linear issues:
+
+```python
+# Pseudocode
+for finding in qa_report.findings:
+    linear.create_issue({
+        team="DESIGN",
+        project="Design System",
+        title=f"[{finding.severity}] {finding.title}",
+        description=format_for_linear(finding),
+        priority=severity_to_priority(finding.severity),
+        labels=["design-debt", finding.severity],
+    })
+```
+
+This is the canonical "audit → tracked work" pipeline.
+
+## Privacy
+
+- Linear auth has full workspace access. Audit installed apps quarterly.
+- Don't include customer data in issue descriptions.
+- For sensitive design (security review findings, leaked-credential issues): post privately, not in Design board.
+
+## Common pitfalls
+
+| Pitfall | Fix |
+| --- | --- |
+| Issue created in wrong team | Verify team_id before bulk-creating |
+| Duplicates after re-audit | Search-first pattern (Workflow D) |
+| Auth expires | Refresh / re-authenticate |
+| Markdown links don't render | Linear has slightly different markdown — test before bulk-creating |
+| Priority not setting | Linear uses 1=urgent, 4=low; reverse from many systems |
+
+## When Linear MCP is unavailable
+
+design-system-qa skill falls back to:
+- Outputting the findings list as a markdown report.
+- User pastes into Linear manually OR uses GitHub MCP for GitHub Issues.
+
+## Cross-reference
+
+- [`docs/MCP-INTEGRATION.md`](../MCP-INTEGRATION.md) — overview
+- [`docs/integrations/github-mcp.md`](github-mcp.md) — GitHub Issues alternative
+- [`skills/design-system-qa/PLAYBOOK.md`](../../skills/design-system-qa/PLAYBOOK.md) — generates findings
+- [`skills/ux-audit/PLAYBOOK.md`](../../skills/ux-audit/PLAYBOOK.md) — generates findings
+- [`knowledge/patterns/design-system-qa.md`](../../knowledge/patterns/design-system-qa.md)

package/docs/integrations/notion-mcp.md

@@ -0,0 +1,174 @@
+# Notion MCP integration
+
+Mirror design-ai's knowledge base to Notion so non-engineering audiences (designers, PMs, executives) can browse without GitHub access. Capture team's design decisions back into the knowledge base.
+
+## Available tools (when Notion MCP connected)
+
+| Tool | What it does |
+| --- | --- |
+| `notion-fetch` | Read a Notion page or database |
+| `notion-search` | Find pages by query |
+| `notion-create-pages` | Create new pages |
+| `notion-update-page` | Edit existing |
+| `notion-create-database` | New database (table-of-pages) |
+| `notion-update-data-source` | Modify database schema |
+| `notion-create-comment` | Comment on a page |
+| `notion-get-comments` | Read comments |
+| `notion-get-users` | List workspace users (for permissions) |
+| `notion-get-teams` | List teams |
+
+## Workflow A: mirror knowledge base to Notion
+
+Designers may not be in the GitHub repo. Sync design-ai's knowledge to a Notion site they can browse.
+
+```
+You: Sync the knowledge base to Notion under our Design page.
+Agent:
+  1. notion-search(query="Design") → find the parent page.
+  2. For each file in knowledge/:
+     - Convert markdown → Notion blocks.
+     - notion-create-pages(parent={...}, title=..., body=...)
+  3. Create an index page linking to all sub-pages.
+  4. Output the URL.
+```
+
+Run periodically (weekly) to keep Notion in sync.
+
+### Direction-of-truth
+
+Knowledge files in this repo are the **source of truth**. Notion is a mirror.
+
+If a designer edits Notion content, that's lost on next sync. Capture design decisions as **separate Notion pages** (in a "Design Decisions" database) — those don't get overwritten and feed back into knowledge as needed.
+
+## Workflow B: capture design decisions
+
+Team meeting → decisions → into Notion → into knowledge base.
+
+```
+You: Capture this decision: "We're using teal-600 (#0D9488) as our primary
+because differentiation from Toss/Shinhan blue matters more than safest-blue."
+
+Agent:
+  1. notion-create-pages(
+       database="Design Decisions",
+       title="Primary brand: teal not blue (2026-05-08)",
+       body="...",
+       properties={status: "decided", date: ..., area: "color"}
+     )
+  2. Optionally suggest updating knowledge/colors/* with the rationale.
+```
+
+Pattern: decisions live in Notion (timestamped log); knowledge files reflect the *outcome*.
+
+## Workflow C: read team's brand brief from Notion
+
+User has a brand brief in Notion; agent should read it before generating a palette.
+
+```
+You: Read our brand brief from Notion and apply /design-from-brief.
+Agent:
+  1. notion-search(query="brand brief") → page URL.
+  2. notion-fetch(url=...)
+  3. Extract structured brief from the page content.
+  4. Apply commands/design-from-brief.md.
+```
+
+## Workflow D: design system status report
+
+Auto-generate a weekly status report in Notion.
+
+```
+You: Post this week's design system update to Notion.
+Agent:
+  1. python3 tools/audit/check-coverage.py — get current numbers.
+  2. python3 tools/audit/changelog-generate.py — recent changes.
+  3. Compose update: components added, coverage %, open audit issues.
+  4. notion-update-page(url="<weekly status page URL>", content=...)
+```
+
+## Setup
+
+### Authentication
+
+Notion MCP uses Notion's official integration:
+1. Create an internal integration at notion.so/profile/integrations.
+2. Grant access to the workspace pages design-ai will modify.
+3. Configure the agent's MCP server with the integration token.
+
+```jsonc
+// ~/.codex/mcp.json or equivalent
+{
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["@notionhq/mcp-server"],
+      "env": {
+        "NOTION_TOKEN": "secret_..."
+      }
+    }
+  }
+}
+```
+
+For Claude Code: similar; add via `claude mcp add notion ...`.
+
+### Permissions
+
+Be careful with write access. Recommended:
+- **Read access** to the entire team's design pages.
+- **Write access** only to the design-ai mirror page hierarchy.
+
+This way, design-ai can't accidentally clobber unrelated content.
+
+## Markdown → Notion blocks conversion
+
+Notion's API expects structured blocks, not markdown. Conversion rules:
+
+| Markdown | Notion block |
+| --- | --- |
+| `# Heading 1` | `heading_1` |
+| `## Heading 2` | `heading_2` |
+| `### Heading 3` | `heading_3` |
+| `paragraph text` | `paragraph` |
+| `- bullet` | `bulleted_list_item` |
+| `1. numbered` | `numbered_list_item` |
+| `[link](url)` | text with link annotation |
+| `**bold**` | text with bold annotation |
+| `` `code` `` | text with code annotation |
+| ` ```block``` ` | `code` block |
+| `<!-- HTML -->` | render as paragraph or strip |
+| `\| table \|` | `table` (Notion's table API is awkward — many tools render as 2-column lists instead) |
+
+Libraries that handle this:
+- `notion-to-md` (Notion → markdown — reverse direction)
+- Custom parser for design-ai's specific markdown patterns
+
+For simple knowledge-mirror use case: a basic converter handling headings, paragraphs, lists, and code blocks is ~80% of value.
+
+## Common pitfalls
+
+| Pitfall | Fix |
+| --- | --- |
+| Notion API rate limit | Cap to 3 req/sec; batch creates |
+| Page not found after create | Notion's API is eventually consistent; wait 200ms before fetching newly-created |
+| Code blocks render as plain text | Set `language` on the code block |
+| Tables don't render | Convert to bullet list or fall back to text |
+| Auth lost | Re-share workspace pages with the integration |
+
+## Privacy
+
+- The integration token has access to whatever you grant. Audit shared pages periodically.
+- Don't include secrets in the design-ai content that gets mirrored — Notion is shared.
+- Soft delete (archive) Notion pages, don't hard delete — easier rollback.
+
+## When Notion MCP is unavailable
+
+design-ai's `design-broadcast` skill (covers Slack + Notion) detects missing MCP and falls back to:
+- Outputting markdown the user can paste into Notion manually.
+- Generating a shareable URL via the project's GitHub instead.
+
+## Cross-reference
+
+- [`docs/MCP-INTEGRATION.md`](../MCP-INTEGRATION.md) — overview
+- [`skills/design-broadcast/PLAYBOOK.md`](../../skills/design-broadcast/PLAYBOOK.md) — uses Notion MCP for sharing
+- [`docs/integrations/slack-mcp.md`](slack-mcp.md) — companion for design review summaries