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
- Confirm the canonical sources, versions, sample boundary, coverage declaration, timezone
if relevant, and as-of date/time.
- Inspect the declared sample read-only. Record exact canonical component/token usage by
stable artifact and location, and mark unreadable or ambiguous cases unknown.
- Apply the declared adoption definition. Reconcile numerator and denominator from eligible
artifacts only; report excluded, duplicate, and uncountable items separately.
- Compare observed usage with the canonical version. Classify a deviation only when the
canonical rule supports that classification and no approved exception covers it.
- 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.
- Identify repeated patterns and coverage gaps, state confidence and evidence, and offer
recommendations as proposals. Do not approve a component, exception, or roadmap item.
- Show a complete report preview before any requested save or downstream action and obtain
explicit confirmation from the human authority.
Truth and uncertainty rules
- Observed: canonical version, component/token usage, artifact membership, exception
record, or count directly present in a dated source.
- Inferred: likely equivalence, adoption barrier, or repeated pattern derived from the
sample; state the reasoning and confidence.
- Unknown: missing canonical rule, unreadable artifact, incomplete sample, denominator,
exception rationale, or authority.
- Stale: usage or exception evidence tied to an older canonical version or outside the
requested as-of boundary.
- Contradictory: canonical sources, artifact records, or exception records disagree;
show versions and dates instead of resolving the conflict silently.
Never invent dates, metrics, percentages, owners, intent, money, causes, status, or
evidence. A recommendation is not an approval or human decision. Do not report an adoption
percentage when the denominator is not reliable.
Output contract
Return an audit with:
- canonical component/token sources, versions, source dates, as-of date/time, and authority;
- declared sample, coverage, eligibility rule, exclusions, and inspection limitations;
- component/token usage findings with artifact/version/source/date trace and confidence;
- adoption numerator, denominator, calculation rule, uncountable items, or an explicit
unknown when calculation is unsupported;
- deviations, documented intentional exceptions, stale evidence, unknowns, contradictions,
and recommendations separated from approvals or implementation decisions.
Safety and write boundaries
Default to read-only. Do not change canonical components, tokens, artifacts, code, exception
records, or adoption metrics. Any requested write or downstream action requires a precise
preview, explicit confirm, and human authority; execute only that approved scope. A gap
recommendation does not authorize refactoring or exception approval.
Verification and recovery
Read back the canonical versions, sample manifest, artifact references, exception records,
and counts, then reconcile duplicate handling, numerator, denominator, and coverage before
delivery. After an authorized save, read back the destination and reconcile it with the
confirmed preview. If a canonical source changes, mark affected findings stale and rerun
the impacted sample; if a source or artifact cannot be read, mark the result unknown. If a
write fails or partially succeeds, stop, preserve the preview and error, report the exact
state, and obtain human authority before retrying or recovering.
1---2name: design-system-audit-23description: Use when assessing use of named design-system components or tokens across a defined sample of product artifacts, including adoption and deviation questions.4---56# Design-system audit78## When to use910Use this skill when a named design system has a canonical component or token source and11the requester can define the artifact sample and as-of boundary. It can assess adoption,12coverage, repeated patterns, deviations, and documented exceptions without changing them.1314Do not use it to define a new system, refactor product work, approve an exception, or15claim organization-wide adoption from an undeclared sample. Not for editing components,16tokens, design files, code, or adoption records without a separately confirmed action.1718## Inputs and source discipline1920- Identify the canonical component and token sources, version, source date, and as-of21 date/time. Record the rule that makes a component or token canonical; if the source is22 missing or contradictory, keep adoption unknown.23- Declare the sample and coverage: population if known, eligibility rule, included and24 excluded artifacts, artifact/version dates, and inspection method. Do not call a sample25 representative without evidence for that claim.26- Define adoption numerator and denominator before counting. Record the adoption source,27 source date, retrieval/as-of date, and items that are uncountable; never invent a28 denominator or percentage.29- Locate exception records and their rationale, authority, version, and date. Treat a30 local pattern as an observation, not an approved exception, unless the source says so.3132## Method33341. Confirm the canonical sources, versions, sample boundary, coverage declaration, timezone35 if relevant, and as-of date/time.362. Inspect the declared sample read-only. Record exact canonical component/token usage by37 stable artifact and location, and mark unreadable or ambiguous cases unknown.383. Apply the declared adoption definition. Reconcile numerator and denominator from eligible39 artifacts only; report excluded, duplicate, and uncountable items separately.404. Compare observed usage with the canonical version. Classify a deviation only when the41 canonical rule supports that classification and no approved exception covers it.425. Classify an intentional exception only with an explicit rationale, authority, source,43 and date. Otherwise distinguish unsupported deviation, possible equivalence, stale44 documentation, and unknown rather than guessing intent.456. Identify repeated patterns and coverage gaps, state confidence and evidence, and offer46 recommendations as proposals. Do not approve a component, exception, or roadmap item.477. Show a complete report preview before any requested save or downstream action and obtain48 explicit confirmation from the human authority.4950## Truth and uncertainty rules5152- **Observed:** canonical version, component/token usage, artifact membership, exception53 record, or count directly present in a dated source.54- **Inferred:** likely equivalence, adoption barrier, or repeated pattern derived from the55 sample; state the reasoning and confidence.56- **Unknown:** missing canonical rule, unreadable artifact, incomplete sample, denominator,57 exception rationale, or authority.58- **Stale:** usage or exception evidence tied to an older canonical version or outside the59 requested as-of boundary.60- **Contradictory:** canonical sources, artifact records, or exception records disagree;61 show versions and dates instead of resolving the conflict silently.6263Never invent dates, metrics, percentages, owners, intent, money, causes, status, or64evidence. A recommendation is not an approval or human decision. Do not report an adoption65percentage when the denominator is not reliable.6667## Output contract6869Return an audit with:7071- canonical component/token sources, versions, source dates, as-of date/time, and authority;72- declared sample, coverage, eligibility rule, exclusions, and inspection limitations;73- component/token usage findings with artifact/version/source/date trace and confidence;74- adoption numerator, denominator, calculation rule, uncountable items, or an explicit75 unknown when calculation is unsupported;76- deviations, documented intentional exceptions, stale evidence, unknowns, contradictions,77 and recommendations separated from approvals or implementation decisions.7879## Safety and write boundaries8081Default to read-only. Do not change canonical components, tokens, artifacts, code, exception82records, or adoption metrics. Any requested write or downstream action requires a precise83preview, explicit confirm, and human authority; execute only that approved scope. A gap84recommendation does not authorize refactoring or exception approval.8586## Verification and recovery8788Read back the canonical versions, sample manifest, artifact references, exception records,89and counts, then reconcile duplicate handling, numerator, denominator, and coverage before90delivery. After an authorized save, read back the destination and reconcile it with the91confirmed preview. If a canonical source changes, mark affected findings stale and rerun92the impacted sample; if a source or artifact cannot be read, mark the result unknown. If a93write fails or partially succeeds, stop, preserve the preview and error, report the exact94state, and obtain human authority before retrying or recovering.
davekilleen