@design-ai/cli 4.55.0

package/skills/design-broadcast/PLAYBOOK.md

@@ -0,0 +1,146 @@
+# design-broadcast — playbook
+
+Distribute a design-ai artifact (palette, spec, audit report) to the team via Slack and/or Notion. When MCPs are connected, posts directly. Without MCP, generates pasteable formatted content.
+
+## When to use
+
+- "Share this palette with the design team"
+- "Post the audit findings to #design-system"
+- "Add this spec to our Notion design library"
+- After running other skills — broadcast their output.
+
+## Inputs (ask if missing)
+
+1. **Artifact**: the file or content to share.
+2. **Channel(s)**: Slack channel name, Notion page/database, or both.
+3. **Audience**: who should be tagged / notified?
+
+## Steps
+
+### 1. Detect available MCPs
+
+```
+slack_available = mcp__plugin_design_slack is connected
+notion_available = mcp__864aac7f-...__notion-* is connected
+```
+
+If neither: output formatted content the user can paste manually.
+
+### 2. Determine artifact type
+
+From the file name / content, identify:
+
+| Artifact | Pattern |
+| --- | --- |
+| Palette | `examples/palette-*.md` or content has token tables |
+| Component spec | `examples/component-*.md` or content has anatomy + API sections |
+| UX audit / design review | content has 🔴/🟠/🟡/🟢 severity sections |
+| Design system bootstrap | `examples/dogfood-*.md` or content has foundations sections |
+| Coverage report | `knowledge/COVERAGE.md` |
+| Token diff / changelog | content has CHANGELOG-style format |
+
+### 3. Compose audience-appropriate summary
+
+Different audiences need different framings:
+
+#### For #design Slack (designers)
+
+- Visual focus.
+- For palettes: include the preview image + key colors.
+- For specs: link to source, summarize "what this is + key API decisions".
+- For audits: "what we found + top recommendation".
+
+#### For #frontend / #engineering Slack (developers)
+
+- Code focus.
+- For palettes: include the Tailwind config / CSS vars snippet.
+- For specs: link to component reference + Code Connect manifest.
+- For audits: severity + count + impact estimate.
+
+#### For #design-system / #design-leadership
+
+- Higher-level focus.
+- Coverage stats, trend over time, what's blocking.
+
+### 4. Format for the channel
+
+#### Slack format (use Block Kit)
+
+```
+[
+  { type: "header", text: { type: "plain_text", text: "🎨 New palette: B2C SaaS — violet" }},
+  { type: "section", text: { type: "mrkdwn", text: "*Generated by design-ai* · Cited 4 knowledge files\n\nLight + dark, WCAG AA validated, Tailwind v4 + shadcn-ui formats." }},
+  { type: "divider" },
+  { type: "section", text: { type: "mrkdwn", text: "*Key tokens:*\n• Primary: `#7C3AED`\n• Accent: `#D97706`\n• Bg: `#FFFFFF`" }},
+  { type: "actions", elements: [
+    { type: "button", text: { type: "plain_text", text: "View full palette" }, url: "..." },
+    { type: "button", text: { type: "plain_text", text: "Open Storybook" }, url: "..." },
+  ]}
+]
+```
+
+Cite [`docs/integrations/slack-mcp.md`](../../docs/integrations/slack-mcp.md) for Slack formatting rules (mrkdwn vs markdown).
+
+#### Notion format
+
+For "add to design library" pattern:
+- Create a page in the Notion database.
+- Convert markdown → Notion blocks (headings, lists, code blocks, tables).
+- Add metadata properties: status, area (color/typography/component), date.
+
+Cite [`docs/integrations/notion-mcp.md`](../../docs/integrations/notion-mcp.md) for the conversion rules.
+
+### 5. Post (with confirmation)
+
+Show the user the formatted content **before** posting:
+
+```
+Agent: I'll post this to #design and create a Notion page in the Design System
+       database. Confirm? [yes/no/edit]
+```
+
+User approves → execute via MCP.
+
+### 6. Without MCP — output for manual paste
+
+```
+=== Slack message (paste into #design) ===
+[formatted text or copy-pasteable JSON for Block Kit Builder]
+
+=== Notion page content (paste into Notion editor) ===
+[markdown that Notion will partially-convert]
+
+=== Confirmation that you posted? [user replies] ===
+```
+
+### 7. Confirm + log
+
+After posting (if MCP available):
+- Echo the URL of the Slack message and/or Notion page.
+- Optionally: react to the Slack message with 🤖 to mark "posted by agent" (transparency).
+
+## Verification phase (run before declaring done)
+
+- [ ] Did I detect MCP availability before composing?
+- [ ] Did I tailor the message to the audience (designer vs eng vs leadership)?
+- [ ] For Slack: did I use Block Kit (not plain text) for richer formatting?
+- [ ] For Notion: did I convert markdown to blocks correctly?
+- [ ] Did I show the user the message **before** posting?
+- [ ] Did I include source links (knowledge files, examples) for credibility?
+- [ ] Did I avoid leaking sensitive content (Figma file URLs, internal customer data) to public channels?
+
+## Source files this skill reads
+
+- [`docs/integrations/slack-mcp.md`](../../docs/integrations/slack-mcp.md) — Slack format rules
+- [`docs/integrations/notion-mcp.md`](../../docs/integrations/notion-mcp.md) — Notion conversion
+- [`docs/MCP-INTEGRATION.md`](../../docs/MCP-INTEGRATION.md) — MCP overview
+- [`knowledge/i18n/korean-product-conventions.md`](../../knowledge/i18n/korean-product-conventions.md) — Korean tone for KR-team channels
+
+## Done when
+
+- Artifact posted (or formatted output ready for paste).
+- Audience-appropriate summary composed.
+- User explicitly confirmed before posting.
+- URL of posted content output for the user's reference.
+- Sensitive content checked + not leaked.
+- Verification phase passes.

package/skills/design-broadcast/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: design-broadcast
+description: Distribute a design-ai artifact (palette, spec, audit) via Slack and/or Notion MCPs. Composes audience-appropriate summaries, formats with Slack Block Kit / Notion blocks, requires user confirmation before posting. Falls back to formatted output for manual paste when MCPs unavailable.
+---
+
+See [PLAYBOOK.md](PLAYBOOK.md).

package/skills/design-critique/PLAYBOOK.md

@@ -0,0 +1,137 @@
+# design-critique — playbook
+
+Senior-designer feedback on a design proposal. Different from `ux-audit`: critique speaks to **craft, hierarchy, and decisions** — not just bugs and a11y.
+
+## When to use
+
+- "What do you think of this design?"
+- "Critique this mockup before I share with the team."
+- "Is this hero working?"
+
+## Inputs (ask if missing)
+
+1. **Artifact** — image, Figma link, live page.
+2. **The decision being made** — "I'm trying to pick between layout A and B" vs. "is this ready to ship?".
+3. **Audience** — who sees this?
+4. **Constraints** — brand guidelines, technical limitations, deadline.
+
+## How to critique
+
+A senior critique has four levels. Always cover all four, in order:
+
+### 1. Did this solve the problem?
+
+Before any visual feedback, name the problem and ask whether the design solves it. If not, the visual critique doesn't matter yet.
+
+> "The goal here is helping new users find the import flow. The hero CTA labeled 'Get started' doesn't communicate that. Without seeing the import path emphasized somewhere on this page, the design doesn't yet meet its goal — even though the visual execution is strong."
+
+### 2. Hierarchy — does the eye go where it should?
+
+The single most-used senior-designer move is **hierarchy critique**. Walk the artifact in **scanning order**:
+
+1. What does the eye land on first? (Should be the primary message or action.)
+2. Second?
+3. Third?
+
+If a designer's intended primary is not the actual visual primary, that's the lead with the critique.
+
+Drivers of hierarchy:
+- Size (largest wins).
+- Weight (boldest wins).
+- Color contrast (most-contrast wins).
+- Whitespace (most-isolated wins).
+- Position (top-left in LTR, top-right in RTL).
+- Motion (moving wins, but is fatiguing).
+
+### 3. Craft — is the execution at the level of the bar?
+
+| Aspect | What to check |
+| --- | --- |
+| **Spacing** | Is everything on a 4-px grid? Are gaps between unrelated elements visibly larger than gaps between related ones? |
+| **Alignment** | Optical center vs mathematical center for icons, asymmetric shapes. |
+| **Type** | Are the type sizes from a scale? Line heights tuned? No widows/orphans on important headlines? |
+| **Color use** | Is one color dominant, one accent, neutrals doing the rest? Or is it 5 brand colors competing? |
+| **Iconography** | Same stroke weight, same corner radius, same fill style? |
+| **Density** | Right for the audience? Power users prefer dense; new users prefer breathing room. |
+| **Polish** | Hover states designed? Empty states designed? Loading designed? |
+
+### 4. Tradeoffs — what was given up?
+
+Every design choice gives something up. Name it. This is what separates a critique from a takedown:
+
+> "By making the hero illustration full-bleed, you're trading off the ability to communicate the value prop in the same scroll. That's the right call for a brand-led page. If you want this to also drive activation, the prop needs to live in the next scroll within reach of the fold."
+
+### 5. The single recommendation
+
+End every critique with **one** recommendation. Not three, not five. The most important thing.
+
+> "Top recommendation: pull 'Sign up free' out of the secondary nav and make it the hero CTA. Everything else can stay."
+
+## Output format
+
+```markdown
+# Critique: <artifact>
+
+> Decision being made: <one sentence>
+> Audience: <one sentence>
+
+## What this design does well
+<2–3 bullets, specific and earned. Not "looks great". "The spacing rhythm in the feature grid is consistent and gives each card breathing room.">
+
+## Did this solve the problem?
+<answer the named problem head-on>
+
+## Hierarchy walk
+1. <what the eye lands on first>
+2. <second>
+3. <third>
+
+<If misaligned with intent, name it.>
+
+## Craft notes
+- <observation>
+- <observation>
+
+## Tradeoffs accepted
+- <named tradeoff with rationale>
+
+## Top recommendation
+<one sentence>
+```
+
+## Tone
+
+- Specific over vague. "The CTA is hard to find" → "The CTA's blue blends with the link colors above it; consider a primary button style or a hue shift."
+- Critique the decision, not the designer.
+- Praise what works, before what doesn't.
+- One recommendation, not a wishlist.
+- Avoid jargon a non-designer can't follow without context.
+
+## Source files this skill reads
+
+- [`knowledge/patterns/ux-guidelines.md`](../../knowledge/patterns/ux-guidelines.md)
+- [`knowledge/patterns/styles-catalog.md`](../../knowledge/patterns/styles-catalog.md)
+- [`knowledge/colors/color-theory.md`](../../knowledge/colors/color-theory.md)
+- [`knowledge/typography/type-scale-fundamentals.md`](../../knowledge/typography/type-scale-fundamentals.md)
+- [`knowledge/layout/spacing-and-grid.md`](../../knowledge/layout/spacing-and-grid.md)
+- [`knowledge/patterns/brand-references.md`](../../knowledge/patterns/brand-references.md) — for compare/contrast with peer brands.
+- [`knowledge/patterns/ui-reasoning.md`](../../knowledge/patterns/ui-reasoning.md) — category-level expectations vs the design
+
+## Verification phase (run before declaring done)
+
+- [ ] Did I open with the named problem (not visual feedback first)?
+- [ ] Does the hierarchy walk identify what the eye lands on 1st / 2nd / 3rd?
+- [ ] Did I praise specific things (not "looks great")?
+- [ ] Are craft observations actionable (specific element + specific change)?
+- [ ] Is the named tradeoff genuine (designer gave up something specific)?
+- [ ] Is there exactly **one** top recommendation in bold at the end?
+- [ ] No jargon a non-designer can't follow?
+- [ ] Did I critique the decision ("the CTA's blue blends"), not the designer ("you should")?
+
+## Done when
+
+- All five sections delivered: works well, problem fit, hierarchy walk, craft notes, tradeoffs, top recommendation.
+- Each observation is specific (a designer could act on it).
+- The critique is balanced (praise + concerns, not just concerns).
+- One top recommendation, not several.
+- The verification phase checklist passes.

package/skills/design-critique/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: design-critique
+description: Senior-designer feedback on a design proposal — covers problem fit, hierarchy, craft, tradeoffs, and lands on a single top recommendation.
+---
+
+See [PLAYBOOK.md](PLAYBOOK.md).

package/skills/design-pr-review/PLAYBOOK.md

@@ -0,0 +1,171 @@
+# design-pr-review — playbook
+
+Review a GitHub pull request for design system compliance. When GitHub MCP is connected, fetches the PR and posts a structured review. Without MCP: outputs a markdown review for manual paste.
+
+## When to use
+
+- "Review PR #123 for design system compliance"
+- "Audit this PR before merging"
+- Pre-merge gate as part of CI (run via Codex headlessly)
+
+## Inputs (ask if missing)
+
+1. **PR identifier**: org/repo + number, OR full URL.
+2. **Severity threshold**: which findings should block merge? (default: Critical only)
+3. **Post comments?**: yes (write back to PR) or no (just output report).
+
+## Steps
+
+### 1. Detect MCP availability
+
+```
+if mcp__plugin_engineering_github is connected:
+  proceed with full PR fetch + comment workflow
+else:
+  ask user to paste the PR diff; output review as markdown only
+```
+
+### 2. Fetch PR (MCP path)
+
+```
+github__get_pull_request(repo="org/repo", number=123)
+→ returns PR metadata, files changed, diff
+```
+
+For each changed file: `github__get_repo_contents(repo, path, ref=PR_HEAD)` to get full content (diff alone may not be enough context).
+
+### 3. Apply design system QA layers
+
+Open [`knowledge/patterns/design-system-qa.md`](../../knowledge/patterns/design-system-qa.md) — apply each layer to the PR's changed files:
+
+#### Layer 1 — TypeScript
+
+Skip in this skill (assume types exist; tsc handles separately).
+
+#### Layer 2 — Token drift
+
+For each `.tsx` / `.css` / `.scss` file changed:
+- Search for raw hex (`#[0-9A-F]{3,8}`) outside of comments.
+- Search for raw px / rem outside of token references.
+- Flag each occurrence with:
+  - Severity: 🟠 High (or 🔴 Critical if it's in a shipped component).
+  - Cited rule: [`knowledge/PRINCIPLES.md`](../../knowledge/PRINCIPLES.md) rule 2.
+
+#### Layer 3 — Component contract
+
+For new component definitions in the PR:
+- Required ARIA attributes per [`knowledge/a11y/keyboard-and-focus.md`](../../knowledge/a11y/keyboard-and-focus.md).
+- Disabled state has `aria-disabled`.
+- Loading state has `aria-busy`.
+- Buttons explicitly `type="button"` (not the default submit).
+
+#### Layer 4 — A11y
+
+Static checks the agent can do:
+- `<img>` without `alt`.
+- `<button>` without text or `aria-label` for icon-only.
+- `<div onClick>` without `role` and tab support.
+- Color used as the only meaning signal.
+
+For deeper a11y: defer to runtime axe-core (mention in review).
+
+#### Layer 5 — Visual regression
+
+Skip (requires CI / Storybook).
+
+### 4. Read related design-ai knowledge
+
+For each finding type, cite the knowledge file. Common ones:
+
+| Finding | Cite |
+| --- | --- |
+| Raw hex | `knowledge/PRINCIPLES.md` (rule 2), `knowledge/colors/color-theory.md` |
+| Missing aria | `knowledge/a11y/keyboard-and-focus.md` |
+| Wrong contrast | `knowledge/a11y/contrast.md` |
+| Korean copy missing | `knowledge/i18n/korean-product-conventions.md` |
+| Money color wrong | `knowledge/patterns/money-and-amount.md` |
+
+Use deep links so the PR reviewer can click through.
+
+### 5. Compose the review
+
+Aggregate by severity, not by file:
+
+```markdown
+## Design system review — PR #123
+
+> Reviewed by design-ai (skills/design-pr-review)
+> Files changed: 12
+> Findings: 2 Critical, 4 High, 3 Medium
+
+### 🔴 Critical (2 — must fix)
+
+1. **Raw hex `#7C3AED` in `Button.tsx:23`** instead of `--color-primary-default`.
+   Why: tokens by role per [PRINCIPLES.md rule 2](https://github.com/your-org/design-ai/blob/main/knowledge/PRINCIPLES.md).
+   Fix: replace with `var(--color-primary-default)`.
+
+2. **Missing `aria-label` on icon-only button in `Header.tsx:45`**.
+   Why: WCAG 2.1 4.1.2 — controls need accessible name.
+   Fix: add `aria-label="Open menu"`.
+
+### 🟠 High (4 — should fix)
+
+...
+
+### 🟡 Medium (3 — consider)
+
+...
+
+### Things that look good
+
+- Form fields use `<label>` correctly throughout.
+- Card components consume `--space-md` consistently.
+- Korean fonts loaded via Pretendard.
+```
+
+### 6. Post the review (MCP path)
+
+```
+github__create_review(
+  repo="org/repo",
+  pr=123,
+  body=<full review>,
+  event="REQUEST_CHANGES"  // or "COMMENT" for non-blocking
+  comments=[
+    { path: "Button.tsx", line: 23, body: "Use --color-primary-default" },
+    ...
+  ]
+)
+```
+
+Limit inline comments to **2–3 most-critical** specifics. The full review body has the rest.
+
+### Without MCP
+
+Output the full review as markdown. User copies it into the PR review UI manually.
+
+## Verification phase (run before declaring done)
+
+- [ ] Did I check all 5 QA layers?
+- [ ] Did I cite knowledge files for every finding?
+- [ ] Did I aggregate by severity (not file-by-file noise)?
+- [ ] Did I include "Things that look good" (constructive)?
+- [ ] Did I keep inline comments ≤ 3?
+- [ ] If posting via MCP: did I confirm "post" with user (don't auto-post critical reviews without ack)?
+
+## Source files this skill reads
+
+- [`knowledge/patterns/design-system-qa.md`](../../knowledge/patterns/design-system-qa.md) — full QA model
+- [`knowledge/PRINCIPLES.md`](../../knowledge/PRINCIPLES.md) — citation source
+- [`knowledge/a11y/contrast.md`](../../knowledge/a11y/contrast.md)
+- [`knowledge/a11y/keyboard-and-focus.md`](../../knowledge/a11y/keyboard-and-focus.md)
+- [`docs/integrations/github-mcp.md`](../../docs/integrations/github-mcp.md) — MCP usage details
+
+## Done when
+
+- One review posted (or output as markdown).
+- Severity-aggregated, with citations.
+- Inline comments capped at 3 most-critical.
+- "Things that look good" included.
+- User confirmed before posting (when posting via MCP).
+- Verification phase passes.

package/skills/design-pr-review/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: design-pr-review
+description: Review a GitHub pull request for design system compliance. When GitHub MCP is connected, fetches the PR and posts a structured review with citations to design-ai knowledge files. Without MCP, outputs a markdown review for manual paste.
+---
+
+See [PLAYBOOK.md](PLAYBOOK.md).