design-audit

Design Audit Skill

Audits src/app/(dashboard)* for design system compliance and src/ui/ for documentation coverage. Reports findings without modifying any source files or opening PRs.

How to run the audit

This skill is read-only. Never edit source files, create branches, or open PRs.

Step 1 — Load context

1. Read src/app/(internal)/design/_common/sidebar-data.ts to extract:
   • The ignore list (files that should not be documented: _common, layout.tsx, shared.ts, page.tsx, todo)
   • The alias map (e.g. "avatar team" → "avatar", "command" → "combobox")
2. Read src/app/(internal)/design/_common/documented-components.json for the list of documented components
3. Read src/app/(internal)/design/_common/documented-patterns.json for the list of documented patterns
4. Get the current commit SHA: git rev-parse HEAD

Step 2 — Run rubric checks

Read references/rubric.md for the category index, then run every category listed there by following its linked file under references/rubric/ exactly.

Cross-reference the resend-design-system skill to verify whether a DS primitive exists for a flagged use case before marking it a violation.

For judgment-based findings (e.g. "this dialog should probably be a stepper", "this column is mostly empty", "this disabled button has no explanation"), cite the relevant file under design-system/references/heuristics/ as the design_ref. Heuristics are guidelines, not rules — phrase the finding as a suggestion, not a violation, and route it to the rubric candidates category when there is no existing rule to cite.

Step 3 — Build the report

Emit the structured JSON defined in references/report-format.md, then render it as markdown per the template in that file.

Step 4 — Deliver via Linear

Follow references/linear-delivery.md to file or update the Linear issue. Before creating any tickets, run the triage-backlog preflight in that doc — if 10+ tickets are already pending in Triage, defer non-error tickets this run.

References

Load these when running the audit:

• design-audit/references/rubric.md — category index + the merged rule/pattern/heuristic table
• design-audit/references/rubric/ — one file per category with what counts as a violation and how to detect it
• design-audit/references/report-format.md — exact JSON + markdown report structure
• design-audit/references/linear-delivery.md — Linear MCP playbook for filing the issue