Solution Pack: Enterprise Design System Platform
Architecture summary
Decision: evolve from component library to UI platform: design tokens, headless primitives, styled components, product wrappers, accessibility contracts, versioned packages, adoption scorecards, and migration tooling.
Platform sketch
Package boundaries
| Package | Owns | Must not own |
|---|---|---|
| tokens | semantic color, spacing, typography, motion | product-specific meaning |
| primitives | behavior, keyboard, ARIA, state machines | brand visuals or data fetching |
| components | styled accessible components | domain-specific logic |
| product wrappers | domain naming and data mapping | primitive behavior changes |
| docs/testing | examples, fixtures, contracts | hidden policy outside packages |
Quality gates
- keyboard and focus fixtures
- docs examples for all required states
- visual regression for core themes
- accessibility checks plus manual walkthrough for complex components
- API review for durable primitives
- migration guide for breaking changes
ADR bundle
ADR 1: Headless primitives under styled components
Context: product teams need consistent behavior and accessibility, but brands and product surfaces need visual flexibility.
Decision: split behavior primitives from styled components. Primitives own state machines, keyboard behavior, ARIA, and test fixtures. Styled components own tokens, density, theming, and visual states.
Consequences:
- stronger accessibility reuse
- cleaner theming
- more package boundaries to document
- product teams need wrapper guidance
Verification:
- primitive accessibility test coverage
- product wrapper count and owner
- component defect rate by primitive
ADR 2: Semantic token taxonomy
Context: raw color and spacing tokens cause brand leakage and inconsistent product meaning.
Decision: use semantic tokens for product surfaces and map them to brand values through themes.
Consequences:
- better multi-brand support
- more naming discipline
- initial migration cost
Verification:
- raw token usage violations
- theme coverage tests
- design review exceptions
ADR 3: Adoption through migration tooling, not mandate alone
Context: teams fork components when the official system is difficult to adopt.
Decision: pair deprecation policy with codemods, examples, migration guides, office hours, and scorecards.
Consequences:
- adoption is slower at first but more durable
- platform team must support migrations
- exceptions become visible
Verification:
- deprecated usage trend
- migration lead time
- support ticket themes
- exception register age
Scorecard
Track:
- adoption by app/team
- deprecated component usage
- accessibility defect rate by component
- design token drift
- breaking-change migration time
- support issue age
- product wrapper count and owner
Review gates
| Gate | Evidence |
|---|---|
| Accessibility | component contract and manual walkthrough for complex primitives |
| API durability | prop/state/event model review with rejected alternatives |
| Theming | semantic token mapping and forced-colors/high-contrast behavior |
| Package boundaries | import rules and ownership |
| Adoption | migration plan, deprecation dates, and support owner |
| GenUI readiness | registry-safe prop schema for components exposed to generated UI |
Rollout plan
- Inventory duplicate components and accessibility defects.
- Select three high-leverage primitives: dialog, combobox, data table.
- Pilot with two product teams.
- Stabilize APIs after pilot feedback.
- Publish migration guides and codemods.
- Add adoption scorecard.
- Deprecate legacy components with removal dates.
Strong reviewer concerns
- Do not expose product-specific logic in shared components.
- Do not allow visual variants that break accessibility contracts.
- Do not publish primitives without keyboard/focus fixtures.
- Do not mandate migration before support and tooling exist.
Portfolio artifacts
- package architecture diagram
- completed design-system API review
- token taxonomy ADR
- component accessibility contract
- migration plan
- adoption scorecard