DOCS · REFERENCE · COMMANDS · BUILD

design-system-audit/synthex:design-system-audit

Build

Audit code for token compliance and component governance.

Invocation

Run from inside Claude Code in any project where Synthex is installed:

/synthex:design-system-audit

Some commands accept parameters; see the source-of-truth file linked below for the full parameter list and workflow.

Lifecycle phase

Build. Parallel-executed, peer-reviewed task delivery.

  • Tech Lead · Full-stack orchestrator. Breaks tasks down, delegates to specialists, rolls up the result.
  • Lead Frontend Engineer · Coordinates frontend delivery, enforces UX quality, accessibility, and design-system fidelity.
  • Architect · System design, ADRs, plan-review feasibility, technology trade-offs.
  • Code Reviewer · Craftsmanship review — correctness, maintainability, reuse, conventions.
  • Security Reviewer · Mandatory gate. Secrets, injection, auth, supply chain, OWASP.
  • Quality Engineer · Test strategy, gap analysis, behavior-driven test authoring.
  • Design System · Token ownership, component governance, compliance audit.
  • Technical Writer · API docs, guides, migrations, changelogs verifiable against code.

Source

The command's parameters, workflow, and sub-agent invocations are defined in markdown at bluminal/lumenai/blob/main/plugins/synthex/commands/design-system-audit.md.

Last modified:

What it does, end-to-end

design-system-audit/synthex:design-system-audit has the Design System Agent check your frontend against your design system spec: hardcoded values that should be tokens, wrong component usage, and accessibility violations. It's advisory — it never edits files.

  1. Loads config for the spec path, scan paths, and review-loop settings.
  2. Reads the design system spec — tokens (colors, spacing, typography, breakpoints), the component catalog, and the pattern library. If there's no spec, it stops and offers ways to create one (have the Design System Agent generate one from your code, write it yourself, or point design_system.spec_path elsewhere) instead of producing an empty audit.
  3. Collects files from scope, or from design_system.scan_paths when no scope is given, keeping only frontend files: .tsx, .jsx, .vue, .svelte, .css, .scss, .less, .module.css.
  4. Runs the Design System Agent in Compliance Review mode with the spec, the file list, and your CLAUDE.md.
  5. Compliance loop. On a FAIL verdict (any CRITICAL or HIGH finding) it presents what must be fixed and waits for you to make the changes. Then it spawns a fresh Design System Agent to re-audit, passing only a one-line summary of each unresolved finding. It repeats until the verdict is PASS or WARN, or max_cycles is reached. WARN (MEDIUM-only) never triggers the loop.
  6. Presents the final report and summary.

Parameters

ParameterDescriptionDefaultRequired
scopeFile paths or directory to auditconfigured design_system.scan_pathsNo
config_pathPath to synthex project config.synthex/config.yamlNo

Configuration

KeyDefault
design_system.spec_pathdocs/specs/design-system.md
design_system.scan_paths[src/]
design_system.review_loops.max_cyclesInherits review_loops.max_cycles (2)
design_system.review_loops.min_severity_to_addressInherits review_loops.min_severity_to_address (high)

Review-loop settings resolve from design_system.review_loops first, then the global review_loops, then the hardcoded defaults.

Output

A Design System Compliance Review with a PASS / WARN / FAIL verdict and:

  • Token Violations table — file:line, the violation, the current value (e.g. #3b82f6), and the token it should be (e.g. var(--color-primary)). Every hardcoded value that has a matching token is flagged.
  • Component Usage Issues — location, problem, and the design system component to use.
  • Accessibility Findings — severity, location, the specific WCAG 2.1 criterion, and the fix.
  • Recommendations.

The closing summary gives the verdict, files audited, counts of token violations, component issues, and accessibility findings by severity, and the top three fixes.

Examples

/synthex:design-system-audit
/synthex:design-system-audit src/components/checkout
/synthex:design-system-audit app/ui/Button.tsx

See also