---
name: auditing-design-system-conformance
description: Audits generated or edited UI against a design system and reports what drifted — components invented rather than imported, literal values where tokens exist, deprecated APIs, and unmet accessibility preconditions. Use after generating UI, before opening a pull request, when reviewing a diff that touches components or styles, or when the user asks whether code follows the design system. Applies as the verification step for any UI generation task.
license: CC0-1.0
---

# Auditing design system conformance

None of the teams doing this well trust generation. They check it mechanically
and make the agent fix what fails. This skill is that check.

Run it on your own output before you claim a task is done.

## Fill this in first

- Package: `{{@scope/design-system}}`
- Allow-list source: `{{npm run components:list}}`
- Token source: `{{tokens/tokens.json}}`
- Deterministic gates: `{{pnpm typecheck && pnpm lint}}`

## The five checks

Work through all five. Report each as pass or fail with the specific line,
not as a summary judgement.

### 1. Invented components

Every component rendered in the diff must appear in the allow-list.

```
rg "<[A-Z][A-Za-z0-9]*" -o --no-filename {{changed files}} | sort -u
```

Compare against the allow-list. Anything not on it is invented. Flag it with
the file and line — do not quietly substitute something else.

### 2. Literal values where tokens exist

```
rg "#[0-9a-fA-F]{3,8}\b|\b\d+px\b|rgba?\(" {{changed files}}
```

Every hit is a finding unless it is inside a token definition file itself.

### 3. Deprecated APIs

Cross-check every imported symbol against the deprecation table. Report the
replacement, not just the violation.

### 4. Accessibility preconditions

Run the linter, then read for the things it cannot see. Load the
semantic-accessibility skill for that pass — a green axe run on generated UI
is close to meaningless on its own.

### 5. Duplicate components

For each new component in the diff, search the existing library for something
that does the same job. "Does something like this already exist?" is the
question no shipped tool answers, and it is where the drift comes from.

## Report shape

One table. Findings first, most severe first. No prose preamble.

| Check | File:line | Found | Expected |
|---|---|---|---|
| Invented component | `Card.tsx:42` | `Stack` | not in the system — use `{{layout primitive}}` |
| Literal value | `Card.tsx:58` | `#2563EB` | `var(--color-action-primary)` |

If everything passes, say so in one line and stop. Do not pad a clean audit.

## Keep the LLM out of the enforcement path

This skill is advisory. The merge-blocking check must stay deterministic —
typecheck, lint, the token rule. Meta draws this line explicitly in Astryx and
it is the right one: an agent that both writes and approves the code has no
independent signal in it.