Capstone: Enterprise Design System Platform

Product scenario

Design a design system platform for several product teams building dashboards, account flows, marketing surfaces, and AI-assisted features. The system must support multiple brands, dark mode, accessibility contracts, versioned packages, documentation, and migration from legacy components.

Functional requirements

• Token system for color, typography, spacing, elevation, radius, state, and density.
• Component primitives for button, field, dialog, tabs, menu, tooltip, table, card, notification, and theme switcher.
• Storybook or equivalent documentation with states and examples.
• Package release workflow and changelog.
• Migration path from legacy components.
• GenUI-safe component registry subset.

Non-functional requirements

Concern	Requirement
Accessibility	Keyboard, focus, name, state, contrast, and announcement contracts for every primitive.
Stability	Breaking changes require migration guidance and deprecation window.
Theming	Brand and theme variation must not require component forks.
Adoption	Product teams need examples, recipes, and support model.
GenUI readiness	AI-generated UI may only select approved components and schema props.

Architecture constraints

• Tokens must be semantic, not raw brand aliases.
• Components must not expose internal implementation details as public API.
• Accessibility contracts are part of API compatibility.
• Local product overrides must be detectable and governable.

Required diagrams

• Token layer hierarchy.
• Package dependency graph.
• Component API ownership map.
• Contribution and release workflow.
• GenUI registry boundary.

Sample package graph

Sample token hierarchy

Layer	Example	Rule
Base	color.blue.600	implementation value, not used directly by products
Semantic	color.action.primary.background	product-safe intent
Component	button.primary.background	component-specific mapping
State	button.primary.background.hover	interaction state mapping
Brand	brand.acme.action.primary.background	brand override of semantic intent

Sample contribution workflow

Implementation milestones

1. Define token taxonomy and naming rules.
2. Specify primitive contracts for behavior, accessibility, theming, and state.
3. Design package boundaries and exports.
4. Define documentation and visual regression workflow.
5. Create contribution and review process.
6. Define release, deprecation, and migration policies.
7. Add adoption scorecard.
8. Define GenUI-safe registry subset and schema rules.

ADRs to write

• ADR: Semantic token architecture.
• ADR: Headless primitive and styled component boundary.
• ADR: Package release and breaking-change policy.
• ADR: GenUI-safe component registry.

Gates

Gate	Evidence
Accessibility	Manual and automated checks for high-risk primitives.
API durability	Component prop review and migration examples.
Theming	Multi-brand and dark-mode examples.
Adoption	Consumer migration plan and support model.
Governance	Contribution, review, release, and deprecation workflow.

Failure-mode review

• Product team forks a component for missing behavior.
• Token names leak brand-specific meaning.
• Dialog focus behavior regresses.
• Breaking change ships without migration guidance.
• AI surface generates inaccessible component combinations.

Architecture drills

Drill	Expected architect-level answer	Common weak answer
Three teams fork Dialog because the shared component lacks a workflow variant.	Identify missing use case, review primitive contract, add extension point or new composed pattern, publish migration guidance, and track adoption.	Tell teams not to fork it.
Brand tokens leak into product code and block white labeling.	Split primitive and semantic tokens, add lint/CI enforcement, define migration path, and document token ownership.	Rename the colors manually.
A GenUI surface generates an inaccessible component combination.	Restrict registry schemas to approved accessible primitives, validate payloads, add eval fixtures, and provide deterministic fallback UI.	Tell the model to be accessible.

Final review rubric

Use rubrics/design-system-architect-rubric. Passing requires level 4 in component API design, accessibility contracts, token architecture, package architecture, and adoption.

Portfolio deliverables

• Token taxonomy.
• Component contract examples.
• Package graph.
• Storybook structure.
• Accessibility verification plan.
• Release governance document.
• GenUI registry contract.

Completed artifact targets

By the end, the capstone should include:

• one completed component contract for dialog, tabs, or data table
• one completed ADR using part-xii/completed-examples/completed-adr-examples
• one GenUI-safe registry subset using part-xii/completed-examples/completed-genui-registry-contract
• one adoption plan with migration, deprecation, and owner fields

Use capstones/solution-packs/capstone-solution-pack-enterprise-design-system and part-xii/completed-examples/completed-design-system-api-review as calibrated examples of a strong final answer.