From c4a95d36906524ba1912059890f3371ab24825f9 Mon Sep 17 00:00:00 2001 From: Euan Morgan Date: Mon, 20 Jul 2026 12:51:50 +0100 Subject: [PATCH 1/4] feat: merge zeroheight-audit-docs DSDS audit into the Claude Code plugin (OAK-302) Copies the dsds-audit skill and /audit-docs command verbatim from zeroheight-demos/zeroheight-audit-docs into the zeroheight-mcp plugin. The plugin stays login-only: a userConfig-templated URL supporting MCP via link was built and tested but rejected over the config dialog UX. Also documents desktop-app (Cowork) install steps and bumps the plugin to 0.1.0 so existing installs auto-update. Co-Authored-By: Claude Fable 5 --- README.md | 39 ++- claude-code/.claude-plugin/plugin.json | 6 +- claude-code/commands/audit-docs.md | 21 ++ claude-code/skills/dsds-audit/SKILL.md | 181 ++++++++++++++ .../dsds-audit/reference/dsds-0.12.0-model.md | 115 +++++++++ .../reference/entity-block-rules.md | 87 +++++++ .../skills/dsds-audit/reference/rubric.md | 169 +++++++++++++ .../reference/zeroheight-authoring-pattern.md | 227 ++++++++++++++++++ .../reference/zeroheight-mapping.md | 79 ++++++ .../dsds-audit/templates/audit-report.md | 121 ++++++++++ .../dsds-audit/templates/paste-pack.html | 124 ++++++++++ 11 files changed, 1162 insertions(+), 7 deletions(-) create mode 100644 claude-code/commands/audit-docs.md create mode 100644 claude-code/skills/dsds-audit/SKILL.md create mode 100644 claude-code/skills/dsds-audit/reference/dsds-0.12.0-model.md create mode 100644 claude-code/skills/dsds-audit/reference/entity-block-rules.md create mode 100644 claude-code/skills/dsds-audit/reference/rubric.md create mode 100644 claude-code/skills/dsds-audit/reference/zeroheight-authoring-pattern.md create mode 100644 claude-code/skills/dsds-audit/reference/zeroheight-mapping.md create mode 100644 claude-code/skills/dsds-audit/templates/audit-report.md create mode 100644 claude-code/skills/dsds-audit/templates/paste-pack.html diff --git a/README.md b/README.md index d88e8f1..47ecd3a 100644 --- a/README.md +++ b/README.md @@ -47,24 +47,53 @@ Then sign in to zeroheight (this opens a browser): codex mcp login zeroheight ``` -## Claude Code +## Claude Code and the Claude desktop app (Cowork) -Connects Claude Code to zeroheight via a plugin. The first time you use it, -Claude Code opens a browser so you can sign in. +Connects Claude to zeroheight via a plugin. Works in both the Claude Code CLI +and the Claude desktop app. What's included: - **MCP server** (`claude-code/.mcp.json`): the connection to zeroheight. Claude Code surfaces the server's own guidance automatically, so it treats your styleguide as the source of truth when working on UI. +- **DSDS audit** (`claude-code/skills/dsds-audit/`, `/audit-docs`): audits your + styleguide's documentation for machine-readability against the + [Design System Documentation Spec](https://designsystemdocspec.org) and + returns a prioritised, page-by-page list of authoring moves plus + ready-to-paste segments. + +### Install in the terminal (Claude Code CLI) Add this repository as a plugin marketplace, then install the plugin: ``` -/plugin marketplace add zeroheight/ai-plugins -/plugin install zeroheight-mcp@zeroheight +claude plugin marketplace add zeroheight/ai-plugins +claude plugin install zeroheight-mcp@zeroheight ``` +### Install in the desktop app (Cowork) + +1. Open the **Plugins** panel (the **+** menu → **Plugins** → **Manage Plugins**). +2. Choose **Add** → **Marketplace** → **Add from a repository** and enter + `zeroheight/ai-plugins`. +3. Find **zeroheight-mcp** in that marketplace and click **Install** (then + enable it if it isn't enabled automatically). + +The first time you use the plugin, a browser opens so you can sign in with +your zeroheight account ([MCP via login](https://help.zeroheight.com/hc/en-us/articles/48004395674011)). + +### Audit your docs + +``` +/audit-docs +/audit-docs just Components +``` + +Or just ask — e.g. "audit our design system docs for machine-readability". +Built on the [Design System Documentation Spec](https://designsystemdocspec.org) +by [PJ Onori](https://pjonori.blog). + ## Usage Once connected, just ask the AI about your design system: diff --git a/claude-code/.claude-plugin/plugin.json b/claude-code/.claude-plugin/plugin.json index 5a19945..1e98631 100644 --- a/claude-code/.claude-plugin/plugin.json +++ b/claude-code/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "zeroheight-mcp", - "version": "0.0.1", + "version": "0.1.0", "description": "Use your design system directly in Claude Code. Search components, retrieve implementation guidance, and generate code that reflects your design system.", "author": { "name": "zeroheight", @@ -14,6 +14,8 @@ "design-system", "design-tokens", "mcp", - "documentation" + "documentation", + "dsds", + "audit" ] } diff --git a/claude-code/commands/audit-docs.md b/claude-code/commands/audit-docs.md new file mode 100644 index 0000000..867a21c --- /dev/null +++ b/claude-code/commands/audit-docs.md @@ -0,0 +1,21 @@ +--- +description: Audit a zeroheight design system's docs for machine-readability against DSDS 0.12.0 and produce a prioritised, page-by-page list of authoring moves plus ready-to-paste segments. +argument-hint: "[styleguide or page scope, e.g. \"just Components\"]" +--- + +Run the **dsds-audit** skill to audit the user's zeroheight design system documentation +against the Design System Documentation Spec (DSDS, pinned to 0.12.0). + +Scope for this run (optional, may be empty): $ARGUMENTS + +Follow the skill's procedure exactly: + +1. Confirm the **zeroheight MCP is connected** (tools `list-pages`, `search-pages`, + `get-page`, `list-releases`, `get-page-asset`). If it is not, stop and tell the user + to set their personal zeroheight remote MCP URL — see the plugin README. Do not + substitute a generic checklist. +2. Read all six source files in the skill (`reference/` + `templates/`) before auditing. +3. If a scope was given above, audit that subset; otherwise call `list-pages` and confirm + scope with the user before auditing everything. +4. Produce the two deliverables the skill specifies: the Markdown audit report and the + companion `paste-pack.html`. Omit `[Platform]` findings entirely. diff --git a/claude-code/skills/dsds-audit/SKILL.md b/claude-code/skills/dsds-audit/SKILL.md new file mode 100644 index 0000000..22901df --- /dev/null +++ b/claude-code/skills/dsds-audit/SKILL.md @@ -0,0 +1,181 @@ +--- +name: dsds-audit +description: >- + Audit a zeroheight design system's documentation for machine-readability + against the Design System Documentation Spec (DSDS, designsystemdocspec.org). + Use this whenever someone wants to check, score, or improve how parseable, + structured, or "agent-ready" / "AI-ready" their zeroheight docs are — phrases + like "audit our design system docs", "are our docs machine-readable", "check + our styleguide against DSDS", "how AI-ready is our documentation", "what should + we change to make our components parseable", or "run a DSDS conformance check". + Reads the live styleguide through the zeroheight MCP, classifies each page to a + DSDS entity, and produces a granular, prioritised list of the exact changes to + make. Use it even if the user doesn't say "DSDS" by name but is asking about + documentation structure, machine/agent readability, or design-system docs QA. +--- + +# DSDS machine-readability audit + +This skill audits a design system documented in **zeroheight** against the +**Design System Documentation Spec (DSDS)** and returns a concrete, page-by-page +list of changes that would make the docs machine-readable — parseable by tools and +consumable by agents, not just readable by people. + +It targets a **pinned DSDS version** (currently **0.12.0**) so results are +reproducible. The spec is a draft and changes; this skill audits against the +frozen model in `reference/`, not against the live site. + +**The core principle:** zeroheight authors cannot emit DSDS JSON — they write +pages. But DSDS's value isn't the JSON syntax, it's the conventions it enforces +(stable names, controlled vocabularies, consistent tables, explicit relationships, +testable statements), and every one of those is authorable in zeroheight. So this +audit never tells a customer to "add an `identifier` field." It recommends the +**zeroheight authoring move** that produces the same machine-readable effect, names +the DSDS intent behind it, and tags who can act ([Author] / [Platform] / [New +content]). Findings only zeroheight can fix stay out of the customer action list. + +## What you need + +- The **zeroheight MCP** connected (tools `list-pages`, `search-pages`, + `get-page`, `list-releases`, `get-page-asset`). It exposes the user's styleguide. +- The reference files in this skill: + - `reference/dsds-0.12.0-model.md` — the entity/block/criteria model, pinned. + - `reference/entity-block-rules.md` — which blocks each entity accepts and the + structured shape each needs (the DSDS-intent layer behind the moves). + - `reference/zeroheight-mapping.md` — how to classify a zeroheight page to a DSDS + entity kind and map its sections onto blocks. + - `reference/zeroheight-authoring-pattern.md` — **the heart of the audit**: each + DSDS construct translated to the next-best zeroheight authoring move, the + controlled vocabularies, and the "For Agents" tab spec. Recommendations come + from here. + - `reference/rubric.md` — the Pass/Partial/Missing rating, who-can-act tagging, + P1/P2/P3 severity, scoring, and how to phrase findings. + - `templates/audit-report.md` — the deliverable structure. + +Read all six before auditing. They are the source of truth; do not audit from +memory of the spec, do not invent block kinds or levels, and do not recommend a +change a customer can't make in the zeroheight editor. + +If the zeroheight MCP is not connected, stop and tell the user — the audit reads +their live docs and cannot run without it. Don't substitute a generic checklist. + +## Procedure + +### 1. Scope the audit +Call `list-pages` to get the styleguide name and full navigation tree. Confirm +with the user: audit the whole styleguide, or a subset (e.g. just Components)? +For large systems, agree a scope rather than silently auditing everything. If the +user wants a specific release, use `list-releases` first, then pass that +`releaseId` consistently to `list-pages` and `get-page` (page IDs differ per +release). + +### 2. Read each page +For each in-scope page, call `get-page` and read the returned Markdown. Don't +infer content from the navigation title — open the page. Image annotations are +coordinate metadata only; you can list anatomy labels but not infer what they +point at without the image, so note that limit rather than guessing +(see `reference/zeroheight-mapping.md`). + +### 3. Classify to a DSDS entity +Using `reference/zeroheight-mapping.md`, assign each page a `kind` +(component / token / token-group / theme / foundation / pattern / guide). Record +the classification and flag any page that's ambiguous or spans two kinds — let a +human correct it rather than burying the uncertainty. Intros, changelogs, and +"welcome" pages are `guide`s, not broken components. + +### 4. Rate against the authoring moves +Map the page's sections to DSDS blocks (`zeroheight-mapping.md`), then run the +entity's check set from `reference/rubric.md`, scoring against the **zeroheight +authoring moves** in `reference/zeroheight-authoring-pattern.md`. For each check: + +- **Pass** — the authoring move is in place; the MCP extracts it reliably. +- **Partial** — content present but not via the move; not parseable. +- **Missing** — absent. +- **N/A** — doesn't apply to this kind. + +Tag every finding **[Author]** / **[Platform]** / **[New content]**. Drop +**[Platform]** items from the action list (appendix only). Most real findings are +**Partial, [Author]** — the writing is good, the convention is missing. Phrase that +as "you're close, here's the move," not failure. Look specifically for the recurring +high-value gaps: colliding/duplicate titles, empty pages, raw hex instead of token +names, no Level column on guidance, inconsistent props/variants tables, unnamed +states/anatomy, no linked alternatives, and no For Agents tab. + +### 5. Make every finding a concrete authoring move +This is the whole value of the audit. Never write "add a guidelines block." Write +the specific zeroheight move, on the named page, referencing the page's own content, +and name the DSDS intent: + +> **Button › Guidelines ([Author], P2, Partial).** "Use a link for navigation" and +> "one primary per surface" are prose. Put them in a guidelines **table with a Level +> column** — `Must not` / `Must` — reusing the Required/Encouraged pattern already +> on your Color page. *DSDS intent: RFC 2119 levels so parsers separate hard rules +> from soft.* + +Cite their own pages where a good pattern already exists (Color/Theming use a Level +column; Button has a clean props table; the Component Status matrix has a status +vocabulary) so findings read as "standardise what you already do." Order each page's +findings P1 → P2 → P3 so a customer can work top-down and stop when budget runs out. + +### 6. Draft ready-to-paste snippets (Markdown report + paste pack) +For each page, after the findings table, write a **Ready to paste** section: the +actual segments to drop into the editor, built from the page's own content, one per +actionable finding (`rubric.md` → "Draft ready-to-paste snippets"). Real content, +never placeholders, never JSON. **Always draft a For Agents tab** when the page lacks +one — fill it with the page's real hard rules, disambiguation, and acceptance +criteria. This is what lets a customer update piece by piece while the MCP is still +read-only. + +Produce the snippets in **two forms**: +- In the Markdown report, as fenced code blocks (readable record). +- In a companion **`paste-pack.html`** built from `templates/paste-pack.html` — + one `.card` per snippet, each `.snippet` containing rendered, semantic HTML + (``, `

`, `

//,

,

+ + + + +
GuidanceWhyLevel
{{real rule}}{{real rationale}}{{Must / Should / …}}
+ + + + + + + + From 68b4dd40426e7c63a9e4bbcfc4c6577b3ab06ef2 Mon Sep 17 00:00:00 2001 From: Euan Morgan Date: Mon, 20 Jul 2026 12:54:32 +0100 Subject: [PATCH 2/4] docs: split Claude Code and Claude desktop app into separate README sections Co-Authored-By: Claude Fable 5 --- README.md | 40 +++++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 47ecd3a..1295c19 100644 --- a/README.md +++ b/README.md @@ -47,10 +47,10 @@ Then sign in to zeroheight (this opens a browser): codex mcp login zeroheight ``` -## Claude Code and the Claude desktop app (Cowork) +## Claude Code -Connects Claude to zeroheight via a plugin. Works in both the Claude Code CLI -and the Claude desktop app. +Connects Claude Code to zeroheight via a plugin. The first time you use it, +Claude Code opens a browser so you can sign in. What's included: @@ -59,11 +59,9 @@ What's included: styleguide as the source of truth when working on UI. - **DSDS audit** (`claude-code/skills/dsds-audit/`, `/audit-docs`): audits your styleguide's documentation for machine-readability against the - [Design System Documentation Spec](https://designsystemdocspec.org) and - returns a prioritised, page-by-page list of authoring moves plus - ready-to-paste segments. - -### Install in the terminal (Claude Code CLI) + [Design System Documentation Spec](https://designsystemdocspec.org) by + [PJ Onori](https://pjonori.blog), and returns a prioritised, page-by-page + list of authoring moves plus ready-to-paste segments. Add this repository as a plugin marketplace, then install the plugin: @@ -72,7 +70,18 @@ claude plugin marketplace add zeroheight/ai-plugins claude plugin install zeroheight-mcp@zeroheight ``` -### Install in the desktop app (Cowork) +To audit your docs: + +``` +/audit-docs +/audit-docs just Components +``` + +Or just ask — e.g. "audit our design system docs for machine-readability". + +## Claude desktop app (Cowork) + +The same plugin works in the Claude desktop app: 1. Open the **Plugins** panel (the **+** menu → **Plugins** → **Manage Plugins**). 2. Choose **Add** → **Marketplace** → **Add from a repository** and enter @@ -81,18 +90,7 @@ claude plugin install zeroheight-mcp@zeroheight enable it if it isn't enabled automatically). The first time you use the plugin, a browser opens so you can sign in with -your zeroheight account ([MCP via login](https://help.zeroheight.com/hc/en-us/articles/48004395674011)). - -### Audit your docs - -``` -/audit-docs -/audit-docs just Components -``` - -Or just ask — e.g. "audit our design system docs for machine-readability". -Built on the [Design System Documentation Spec](https://designsystemdocspec.org) -by [PJ Onori](https://pjonori.blog). +your zeroheight account. ## Usage From 93f628ec2feeae9fe5792b305e975b4715f815d2 Mon Sep 17 00:00:00 2001 From: Euan Morgan Date: Mon, 20 Jul 2026 12:55:19 +0100 Subject: [PATCH 3/4] docs: drop preamble from Cowork section Co-Authored-By: Claude Fable 5 --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 1295c19..32d894e 100644 --- a/README.md +++ b/README.md @@ -81,8 +81,6 @@ Or just ask — e.g. "audit our design system docs for machine-readability". ## Claude desktop app (Cowork) -The same plugin works in the Claude desktop app: - 1. Open the **Plugins** panel (the **+** menu → **Plugins** → **Manage Plugins**). 2. Choose **Add** → **Marketplace** → **Add from a repository** and enter `zeroheight/ai-plugins`. From fc47c01b379af259170dde7f8ad38e1e5bdbe83f Mon Sep 17 00:00:00 2001 From: Euan Morgan Date: Mon, 20 Jul 2026 14:35:31 +0100 Subject: [PATCH 4/4] refactor: move skills to repo root, expose in cursor plugin, document skills CLI install MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses PR #7 review: skills/ now lives at the repo root (claude-code/skills is a relative symlink — verified the plugin installer dereferences it into the cache), the cursor plugin manifest picks up the same directory via its skills field, and the README documents standalone install with npx skills add. Co-Authored-By: Claude Fable 5 --- .cursor-plugin/plugin.json | 5 ++- README.md | 31 ++++++++++++++++--- claude-code/skills | 1 + .../skills => skills}/dsds-audit/SKILL.md | 0 .../dsds-audit/reference/dsds-0.12.0-model.md | 0 .../reference/entity-block-rules.md | 0 .../dsds-audit/reference/rubric.md | 0 .../reference/zeroheight-authoring-pattern.md | 0 .../reference/zeroheight-mapping.md | 0 .../dsds-audit/templates/audit-report.md | 0 .../dsds-audit/templates/paste-pack.html | 0 11 files changed, 31 insertions(+), 6 deletions(-) create mode 120000 claude-code/skills rename {claude-code/skills => skills}/dsds-audit/SKILL.md (100%) rename {claude-code/skills => skills}/dsds-audit/reference/dsds-0.12.0-model.md (100%) rename {claude-code/skills => skills}/dsds-audit/reference/entity-block-rules.md (100%) rename {claude-code/skills => skills}/dsds-audit/reference/rubric.md (100%) rename {claude-code/skills => skills}/dsds-audit/reference/zeroheight-authoring-pattern.md (100%) rename {claude-code/skills => skills}/dsds-audit/reference/zeroheight-mapping.md (100%) rename {claude-code/skills => skills}/dsds-audit/templates/audit-report.md (100%) rename {claude-code/skills => skills}/dsds-audit/templates/paste-pack.html (100%) diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 000eba6..6a390e8 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -14,9 +14,12 @@ "design-system", "design-tokens", "mcp", - "documentation" + "documentation", + "dsds", + "audit" ], "logo": "assets/logo.svg", "rules": "cursor/rules", + "skills": "skills", "mcpServers": "cursor/mcp.json" } diff --git a/README.md b/README.md index 32d894e..38f8640 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,10 @@ What's included: - **MCP server** (`cursor/mcp.json`): the connection to zeroheight. - **Rule** (`cursor/rules/zeroheight.mdc`): nudges the AI to treat your styleguide as the source of truth and look things up before writing UI code. +- **DSDS audit** (`skills/dsds-audit/`): audits your styleguide's documentation + for machine-readability against the + [Design System Documentation Spec](https://designsystemdocspec.org) — see + [DSDS audit skill](#dsds-audit-skill). Install it from the Cursor plugin store, or point Cursor at this repository. @@ -57,11 +61,9 @@ What's included: - **MCP server** (`claude-code/.mcp.json`): the connection to zeroheight. Claude Code surfaces the server's own guidance automatically, so it treats your styleguide as the source of truth when working on UI. -- **DSDS audit** (`claude-code/skills/dsds-audit/`, `/audit-docs`): audits your - styleguide's documentation for machine-readability against the - [Design System Documentation Spec](https://designsystemdocspec.org) by - [PJ Onori](https://pjonori.blog), and returns a prioritised, page-by-page - list of authoring moves plus ready-to-paste segments. +- **DSDS audit** (`skills/dsds-audit/`, `/audit-docs`): audits your + styleguide's documentation for machine-readability — see + [DSDS audit skill](#dsds-audit-skill). Add this repository as a plugin marketplace, then install the plugin: @@ -90,6 +92,25 @@ Or just ask — e.g. "audit our design system docs for machine-readability". The first time you use the plugin, a browser opens so you can sign in with your zeroheight account. +## DSDS audit skill + +The `skills/dsds-audit/` skill audits your styleguide's documentation for +machine-readability against the +[Design System Documentation Spec](https://designsystemdocspec.org) by +[PJ Onori](https://pjonori.blog), and returns a prioritised, page-by-page list +of authoring moves plus ready-to-paste segments. + +It ships inside the Cursor and Claude Code plugins above, but you can also +install it on its own into any agent that supports skills using the +[skills CLI](https://skills.sh): + +``` +npx skills add zeroheight/ai-plugins +``` + +The skill needs the zeroheight MCP connection to read your styleguide, so +install one of the plugins above (or connect the MCP server yourself) first. + ## Usage Once connected, just ask the AI about your design system: diff --git a/claude-code/skills b/claude-code/skills new file mode 120000 index 0000000..42c5394 --- /dev/null +++ b/claude-code/skills @@ -0,0 +1 @@ +../skills \ No newline at end of file diff --git a/claude-code/skills/dsds-audit/SKILL.md b/skills/dsds-audit/SKILL.md similarity index 100% rename from claude-code/skills/dsds-audit/SKILL.md rename to skills/dsds-audit/SKILL.md diff --git a/claude-code/skills/dsds-audit/reference/dsds-0.12.0-model.md b/skills/dsds-audit/reference/dsds-0.12.0-model.md similarity index 100% rename from claude-code/skills/dsds-audit/reference/dsds-0.12.0-model.md rename to skills/dsds-audit/reference/dsds-0.12.0-model.md diff --git a/claude-code/skills/dsds-audit/reference/entity-block-rules.md b/skills/dsds-audit/reference/entity-block-rules.md similarity index 100% rename from claude-code/skills/dsds-audit/reference/entity-block-rules.md rename to skills/dsds-audit/reference/entity-block-rules.md diff --git a/claude-code/skills/dsds-audit/reference/rubric.md b/skills/dsds-audit/reference/rubric.md similarity index 100% rename from claude-code/skills/dsds-audit/reference/rubric.md rename to skills/dsds-audit/reference/rubric.md diff --git a/claude-code/skills/dsds-audit/reference/zeroheight-authoring-pattern.md b/skills/dsds-audit/reference/zeroheight-authoring-pattern.md similarity index 100% rename from claude-code/skills/dsds-audit/reference/zeroheight-authoring-pattern.md rename to skills/dsds-audit/reference/zeroheight-authoring-pattern.md diff --git a/claude-code/skills/dsds-audit/reference/zeroheight-mapping.md b/skills/dsds-audit/reference/zeroheight-mapping.md similarity index 100% rename from claude-code/skills/dsds-audit/reference/zeroheight-mapping.md rename to skills/dsds-audit/reference/zeroheight-mapping.md diff --git a/claude-code/skills/dsds-audit/templates/audit-report.md b/skills/dsds-audit/templates/audit-report.md similarity index 100% rename from claude-code/skills/dsds-audit/templates/audit-report.md rename to skills/dsds-audit/templates/audit-report.md diff --git a/claude-code/skills/dsds-audit/templates/paste-pack.html b/skills/dsds-audit/templates/paste-pack.html similarity index 100% rename from claude-code/skills/dsds-audit/templates/paste-pack.html rename to skills/dsds-audit/templates/paste-pack.html