chore: add design-audit slash command

[eddiman]

What

Adds a /design-audit slash command (.claude/commands/design-audit.md) that audits UI screenshots against the EDS design system and produces a structured Markdown report.

Given one or more screenshots, it runs the EDS 2.0 audit methodology and writes a single report to apps/design-system-docs/audits/{YYYY-MM-DD}-{scope}.md:

• Screen-level audit for fewer than 3 screenshots; multi-screen audit (inventory, pattern analysis, variant-gap detection) for 3 or more.
• Composition pattern scan (Phase 0) before component inventory, so page-level layouts (page header, filter bar, empty state, etc.) that sit between named components aren't missed.
• Severity rubric (P0–P3) applied to every finding, gap, and recommendation, with explicit instance-count and screen-coverage triggers.
• Component recommendations that take a position — favouring existing primitives (Banner, Chip) and composition over new variants, and density via the [data-density] ancestor rather than a size prop.
• A fixed output template and section order so reports are consistent and comparable across audits.

Why

Repeatable, opinionated design audits are useful as standalone tooling, independent of any one feature branch. This command was originally bundled into an unrelated docs-redesign commit; this PR isolates it so it can be reviewed and merged on its own.

Scope

• One new file: .claude/commands/design-audit.md (+510)
• No code or build changes; no impact on published packages.

[pomfrida]

@claude review

[claude]

Claude finished @pomfrida's task in 1m 49s —— View job

---

Review: /design-audit slash command

• Read the new command file
• Check consistency with repo conventions (AGENTS.md, existing commands)
• Review methodology, output paths, and severity rubric
• Post review feedback

This is a well-thought-out command. The Phase 0 composition scan is a genuinely good idea, the opinionated recommendations align with EDS philosophy (favour primitives over new variants, density via the [data-density] ancestor rather than a size prop, matching AGENTS.md exactly), and the house-style rules (British English, no em dashes) are correct. Comments below, roughly in priority order.

---

1. Diverges from the repo's "thin command + canonical doc" convention (main point)

Every other audit-style capability in this repo keeps the command file thin and points to a canonical doc in documentation/agent-instructions/, which is then referenced by parallel entry points for all three harnesses (Claude, Copilot, OpenCode). For example accessibility-audit.md is ~16 lines and does:

@../../documentation/agent-instructions/ACCESSIBILITY_AUDIT.md

AGENTS.md states this repeatedly, e.g.:

Harness entry points (/accessibility-audit in Claude Code, the accessibility-audit prompt in Copilot, the accessibility-audit agent in OpenCode) all reference that doc.

This PR instead inlines all 510 lines of methodology into the Claude-only command. Consequences:

• No documentation/agent-instructions/DESIGN_AUDIT.md, so Copilot and OpenCode users get nothing — the capability is Claude-exclusive, unlike every other audit in the repo.
• The methodology can't be shared/referenced from AGENTS.md the way the others are.
• A future /audit-harnesses run will flag this as drift, since it expects the canonical-doc + three-harness pattern.

Suggestion: move the methodology to documentation/agent-instructions/DESIGN_AUDIT.md, reduce design-audit.md to a thin wrapper that @-imports it (like accessibility-audit.md), and add the matching Copilot prompt + OpenCode agent. If Claude-only tooling is intentional for now, it's worth a one-line note in the PR description saying so.

Restructure this →

2. Not registered anywhere

• The Slash Commands table in .claude/CLAUDE.md isn't updated (it currently lists only /new-component and /create-component-doc). For discoverability and to match how new capabilities are added, register it there — and ideally in the relevant AGENTS.md section.

3. Severity rubric boundaries overlap

The instance triggers are inclusive on both ends, so the boundary values belong to two buckets at once:

• P0 50+, P1 10–50 → 50 is both P0 and P1
• P1 10–50, P2 3–10 → 10 is both P1 and P2
• P2 3–10, P3 1–2 → boundary at 3 is fine, but the pattern repeats

The Usage Frequency Buckets have the same issue (75, 50, 20, 5 each land in two buckets). Given the command explicitly says "Never invent severity - apply the rubric", ambiguous edges undercut the goal. Recommend exclusive ranges, e.g. P1 10–49, P2 3–9, and 50–74%, 20–49%, 5–19% for the buckets.

4. Output frontmatter vs. non-published location

The output template emits Docusaurus-style frontmatter (title, sidebar_position):

---
title: [Scope] Design Audit
date: [YYYY-MM-DD]
sidebar_position: [number if provided, otherwise omit]
---

But reports are written to apps/design-system-docs/audits/, which sits outside the served docs/ directory (Docusaurus serves from docs/, docsRouteBasePath: '/docs'), so they won't be built or published — confirmed they won't leak onto the docs site, which is good. The flip side is that sidebar_position is meaningless there. Either drop the docs-style frontmatter, or if these are meant to be published, the location/sidebar wiring needs to change. Worth a sentence clarifying intent.

5. Minor

• Date source: the template uses {YYYY-MM-DD} for the filename and frontmatter but never tells the agent how to obtain today's date. A one-liner (e.g. "use the current date") avoids the model guessing.
• audits/ committed into a published package: dropping generated audit reports inside apps/design-system-docs/ means they ride along in that package's tree. That's fine if intended, but consider whether they belong in a top-level audits/ or should be .gitignored.

---

None of these block the command from working; #1 and #2 are the consistency items that matter most for a repo that puts a lot of weight on cross-harness parity. Nice command overall.
· branch design-audit-command