System cleanup
Consolidate decisions from foundations to complete patterns
Do not begin by renaming every class. Inventory rendered use, choose semantic roles and migrate one product journey while testing behavior and accessibility.
Foundations
Define type, color, spacing, radius, elevation and motion roles.
- Keep
- Values tied to hierarchy and accessibility
- Merge
- Near-identical accidental values
- Avoid
- One token per existing pixel value
Primitives
Standardize accessible text, control and layout behavior.
- Keep
- Semantic HTML and state behavior
- Merge
- Duplicated buttons, inputs and containers
- Avoid
- Generic div component for every role
Variants
Preserve meaningful differences with explicit contracts.
- Keep
- Priority, danger, density and context
- Merge
- Style-only variants without purpose
- Avoid
- Boolean prop combinations with unclear output
Patterns
Compose repeated journeys, not arbitrary page fragments.
- Keep
- Form, table, navigation and feedback patterns
- Merge
- Repeated behavior with different markup
- Avoid
- Huge component owning unrelated features
Migration
Replace usage with evidence and a deletion path.
- Keep
- Visual regression, keyboard and state checks
- Merge
- One bounded route at a time
- Avoid
- Parallel old and new systems forever
Governance
Give new patterns an owner and acceptance threshold.
- Keep
- Contribution criteria and examples
- Merge
- Review with ordinary product workflow
- Avoid
- Design-system team as approval bottleneck
Operating principle
Distinctiveness comes from product-specific composition
A design system should make basic quality predictable, not make every screen visually identical. Distinctive product experience comes from information hierarchy, real artifacts, content, interaction and deliberate composition.
Consolidate low-level accidents so the team has more capacity for those product-specific decisions. Do not use extra colors or component variants to simulate originality.
- Audit rendered use before deleting
- Use semantic token names
- Test states and keyboard behavior
- Remove the superseded path
Applied example
Cleanup example: fourteen green buttons
The codebase contains fourteen button components with slightly different green values and padding. Several also implement loading and disabled states differently.
- Visual drift hides behavioral inconsistency
- Color alone does not define component purpose
- One accessible primitive can reduce defects
- Destructive and quiet actions still need semantic variants
Plain answers
Questions to resolve before shipping
Should every component enter the design system?+
No. Promote patterns that repeat in behavior and meaning; keep product-specific compositions local until a real reusable contract emerges.
Can a component library be the design system?+
It can supply primitives, but your semantic tokens, product patterns, content rules and governance remain specific to the product.
How do we measure cleanup progress?+
Track migrated usage, removed duplicates, state coverage, accessibility regressions and the time needed to implement a representative change.