Design system review
Keep a useful system coherent without treating every exception as a defect. Inspect actual consumers and documentation; rendered behavior outranks a naming preference.
Work
- Locate token, primitive, feature-component, layout, and documentation sources. Inventory only the areas relevant to the request.
- Distinguish accidental drift from intentional differences in task, density, platform, or brand. A raw value or arbitrary utility is a review candidate, not a severity rating.
- Find duplicated behavior, inaccessible variants, missing theme pairs, unstable shared layouts, and undocumented ownership.
- Prioritize by user consequence and spread: a broken keyboard path outranks two inconsistent colors.
- For each change, decide reuse, extension, or new component; identify consumers and compatibility impact. Retire APIs only with a migration route.
- Update DESIGN.md or existing guidance when an authorized change creates a durable convention. Do not create a duplicate registry just to satisfy a template.
Deliver
For audit: finding → evidence → impact → suggested fix → verification, with confirmed facts separated from hypotheses. For implementation: make scoped fixes, update consumers/docs, and recheck affected siblings.
## System review
**Sources:** token, component, layout, docs locations
**Maturity:** ...
### Drift issues
| Issue | Evidence | Impact | Fix | Verification |
|---|---|---|---|---|
| | | | | |
### Priority fixes
1. ...
### Guardrails
- ...
Example: two dialog wrappers may legitimately differ in destructive confirmation behavior. Consolidate their shared focus and surface treatment without erasing the distinction.
Verify representative consumers across supported themes, sizes, and states. Do not claim visual improvement from source checks alone. Use $tokens for a missing token foundation and $component for one component's contract.
Worked example
System review
Sources: Tokens in src/styles/globals.css; components in src/components/ui/; no DESIGN.md yet.
Maturity: Evolving — tokens plus 40 components with no registry.
Drift issues
| Issue |
Evidence |
Impact |
Fix |
Verification |
| Inline hex in feature code |
#3b82f6 twice in features/reports |
Breaks theming |
Replace with --color-primary |
Render both themes; search for remaining hex |
| LegacyCard duplicates Card |
Two callers |
Divergent behavior |
Deprecate LegacyCard with migration path |
Update callers; confirm no visual regression |
| Page-specific gutters |
dashboard/settings uses custom padding |
Inconsistent rhythm |
Use shell gutter px-6 |
Compare routes at fixed width |
Priority fixes
- Replace stray hex values
- Deprecate LegacyCard
- Align settings page gutters
Guardrails
- Register new components in the inventory before merge; new tokens need light/dark pairs.
Gotchas
- Inspect actual consumers and docs first; do not treat every exception as drift.
- Separate evidence from hypotheses; do not claim visual improvement from source checks alone.
- Prioritize by user consequence and spread; fix broken keyboard paths before minor color variance.
- Decide reuse, extension, or new component per change; do not silently rewrite or duplicate registries.
- Retire APIs only with a migration route; record durable conventions in existing guidance.
Boundaries
- Do not use on a brand-new project with no UI yet — use
$tokens instead.
- Do not use when the question is one component's behavior — use
$component instead.
1---2name: system3description: Audit or maintain existing tokens, components, and shared layouts; resolve drift with evidence and a migration path. Use when auditing drift, deduplicating components, fixing theme or focus gaps, or updating DESIGN.md before new UI.4---56# Design system review78Keep a useful system coherent without treating every exception as a defect. Inspect actual consumers and documentation; rendered behavior outranks a naming preference.910## Work1112- Locate token, primitive, feature-component, layout, and documentation sources. Inventory only the areas relevant to the request.13- Distinguish accidental drift from intentional differences in task, density, platform, or brand. A raw value or arbitrary utility is a review candidate, not a severity rating.14- Find duplicated behavior, inaccessible variants, missing theme pairs, unstable shared layouts, and undocumented ownership.15- Prioritize by user consequence and spread: a broken keyboard path outranks two inconsistent colors.16- For each change, decide reuse, extension, or new component; identify consumers and compatibility impact. Retire APIs only with a migration route.17- Update DESIGN.md or existing guidance when an authorized change creates a durable convention. Do not create a duplicate registry just to satisfy a template.1819## Deliver2021For audit: **finding → evidence → impact → suggested fix → verification**, with confirmed facts separated from hypotheses. For implementation: make scoped fixes, update consumers/docs, and recheck affected siblings.2223```markdown24## System review2526**Sources:** token, component, layout, docs locations27**Maturity:** ...2829### Drift issues30| Issue | Evidence | Impact | Fix | Verification |31|---|---|---|---|---|32| | | | | |3334### Priority fixes351. ...3637### Guardrails38- ...39```4041Example: two dialog wrappers may legitimately differ in destructive confirmation behavior. Consolidate their shared focus and surface treatment without erasing the distinction.4243Verify representative consumers across supported themes, sizes, and states. Do not claim visual improvement from source checks alone. Use `$tokens` for a missing token foundation and `$component` for one component's contract.4445## Worked example4647## System review4849**Sources:** Tokens in `src/styles/globals.css`; components in `src/components/ui/`; no DESIGN.md yet.50**Maturity:** Evolving — tokens plus 40 components with no registry.5152### Drift issues53| Issue | Evidence | Impact | Fix | Verification |54|---|---|---|---|---|55| Inline hex in feature code | `#3b82f6` twice in `features/reports` | Breaks theming | Replace with `--color-primary` | Render both themes; search for remaining hex |56| LegacyCard duplicates Card | Two callers | Divergent behavior | Deprecate LegacyCard with migration path | Update callers; confirm no visual regression |57| Page-specific gutters | `dashboard/settings` uses custom padding | Inconsistent rhythm | Use shell gutter `px-6` | Compare routes at fixed width |5859### Priority fixes601. Replace stray hex values612. Deprecate LegacyCard623. Align settings page gutters6364### Guardrails65- Register new components in the inventory before merge; new tokens need light/dark pairs.6667## Gotchas6869- Inspect actual consumers and docs first; do not treat every exception as drift.70- Separate evidence from hypotheses; do not claim visual improvement from source checks alone.71- Prioritize by user consequence and spread; fix broken keyboard paths before minor color variance.72- Decide reuse, extension, or new component per change; do not silently rewrite or duplicate registries.73- Retire APIs only with a migration route; record durable conventions in existing guidance.7475## Boundaries7677- Do not use on a brand-new project with no UI yet — use `$tokens` instead.78- Do not use when the question is one component's behavior — use `$component` instead.
mattjmdesign