design-system-audit

Design-system audit

When to use

Use this skill when a named design system has a canonical component or token source and the requester can define the artifact sample and as-of boundary. It can assess adoption, coverage, repeated patterns, deviations, and documented exceptions without changing them.

Do not use it to define a new system, refactor product work, approve an exception, or claim organization-wide adoption from an undeclared sample. Not for editing components, tokens, design files, code, or adoption records without a separately confirmed action.

Inputs and source discipline

• Identify the canonical component and token sources, version, source date, and as-of date/time. Record the rule that makes a component or token canonical; if the source is missing or contradictory, keep adoption unknown.
• Declare the sample and coverage: population if known, eligibility rule, included and excluded artifacts, artifact/version dates, and inspection method. Do not call a sample representative without evidence for that claim.
• Define adoption numerator and denominator before counting. Record the adoption source, source date, retrieval/as-of date, and items that are uncountable; never invent a denominator or percentage.
• Locate exception records and their rationale, authority, version, and date. Treat a local pattern as an observation, not an approved exception, unless the source says so.

Method

1. Confirm the canonical sources, versions, sample boundary, coverage declaration, timezone if relevant, and as-of date/time.
2. Inspect the declared sample read-only. Record exact canonical component/token usage by stable artifact and location, and mark unreadable or ambiguous cases unknown.
3. Apply the declared adoption definition. Reconcile numerator and denominator from eligible artifacts only; report excluded, duplicate, and uncountable items separately.
4. Compare observed usage with the canonical version. Classify a deviation only when the canonical rule supports that classification and no approved exception covers it.
5. Classify an intentional exception only with an explicit rationale, authority, source, and date. Otherwise distinguish unsupported deviation, possible equivalence, stale documentation, and unknown rather than guessing intent.
6. Identify repeated patterns and coverage gaps, state confidence and evidence, and offer recommendations as proposals. Do not approve a component, exception, or roadmap item.
7. Show a complete report preview before any requested save or downstream action and obtain explicit confirmation from the human authority.