Design system audit

---
name: auditing-design-system-conformance
description: Audits a component, page, or stylesheet against the project's own design system, flagging arbitrary values where a token exists, off-scale spacing, inconsistent radius tiers, alpha modifiers on semantic tokens, and markup hand-rolled from divs that duplicates a component the kit already ships. Use when the user shares code, a file, or a directory and asks whether it follows the design system, matches the tokens, or stays consistent with the rest of the app, and when they say a component looks slightly off, was pasted in from somewhere else, or needs tidying before it merges. This reads code, not screenshots, and judges conformance rather than usability.
metadata:
  category: design
---
# Design system audit

Audit code against the design system it is supposed to be using. The question is conformance, not taste: every finding names the token, scale step, or component variant the code should have used instead. If a finding is "this is hard to use" rather than "this does not match the system", it belongs in a usability review, not here.

## Find the system before judging the code

An audit without the source of truth is just a style opinion. Load these three things first, and if none of them exist, say so and stop rather than inventing a scale to measure against:

1. The token definitions. The theme block, CSS custom properties, or config file that names the spacing, color, radius, type, shadow, and z-index scales.
2. The component library. What it already ships, and which variants each component exposes.
3. Two or three files the team treats as correct. These encode conventions the tokens never state, like which radius tier a card gets.