Skip to main content

Design Systems & UI Architecture

(Designing UI platforms, not just components)

Architect rule:

A design system is a UI platform with rules, constraints, and evolution paths.

Why Design Systems Are Architectural​

1.1 The Common Misconception​

A design system is not only:

  • a reusable component library
  • a Storybook site
  • a Figma file

Those assets matter, but the real architectural value is that the system defines what is allowed, what is discouraged, and how change happens safely.

1.2 Why Architects Belong Here​

Design systems sit at the intersection of:

  • consistency
  • accessibility
  • performance
  • developer experience
  • organizational scale

That is architecture territory.

The Design System Stack​

2.1 The Layered Model​

LayerPurpose
Design tokensencode semantic decisions
Foundationsdefine typography, spacing, color, motion, elevation
Primitivesprovide low-level accessible building blocks
Patternsencode recurring UI arrangements
Templates or recipeshelp teams apply the system coherently

2.2 Why Skipping Layers Fails​

When teams jump straight to components:

  • theming becomes brittle
  • rebrands become rewrites
  • accessibility depends on luck
  • API sprawl accelerates

Tokens, APIs, and Theming​

3.1 Tokens Encode Intent​

Prefer semantic tokens over raw value naming.

Example:

  • weaker: --blue-500
  • stronger: --color-action-primary

The point is not naming purity. The point is preserving design meaning as implementation changes.

3.2 Component APIs Are Contracts​

Good component APIs optimize for:

  • clarity
  • composability
  • accessibility defaults
  • stable extension points

Avoid APIs that are merely thin wrappers around CSS knobs.

3.3 Composition Over Configuration​

Composition usually ages better than sprawling prop surfaces because it:

  • reduces invalid states
  • keeps behavior easier to reason about
  • makes migration more predictable

This is a default, not a religion. Some components genuinely need constrained configuration.

3.4 Theming Model​

A credible theming model usually looks like:

LayerResponsibility
Tokensemantic meaning
Themeconcrete value mapping
Componentconsumes tokens, not raw values

That makes white-labeling, accessibility tuning, and regional variation much safer.

Accessibility and Internationalization​

4.1 Accessibility Is a System Property​

Architects should expect the design system to guarantee:

  • semantic defaults
  • focus visibility
  • keyboard support
  • contrast-aware tokens
  • motion-respectful behavior

4.2 Internationalization Impacts the Design System​

UI architecture needs to account for:

  • longer translated strings
  • bidirectional layout support
  • locale-aware number and date presentation
  • typography differences across scripts

If the design system assumes English-length copy and left-to-right layout only, it is incomplete.

Versioning and Adoption​

5.1 Versioning Rules​

Define:

  • what is breaking
  • what can change safely
  • deprecation window length
  • migration expectations

5.2 Deprecation as a First-Class Capability​

Teams trust a design system when deprecated components:

  • remain usable during the stated window
  • emit visible migration guidance
  • have clear replacements

5.3 Adoption Is an Architectural Problem​

Teams do not adopt systems because a standards document exists. They adopt systems when:

  • the recommended path is faster
  • the docs are clear
  • generators and examples reduce friction
  • ownership is obvious

Storybook, Testing, and Governance​

6.1 Storybook as a Platform Surface​

Storybook and similar tools are useful when they serve as:

  • documentation
  • contract verification
  • visual review surface
  • onboarding path

6.2 Testing Expectations​

For design-system components, verify:

  • accessibility defaults
  • visual stability
  • usage examples for intended composition
  • migration behavior for deprecated APIs

6.3 Governance Checklist​

  • Who can add or remove tokens?
  • Who approves breaking changes?
  • How are adoption and misuse measured?
  • How are accessibility regressions caught before release?

Review Checklist​

  • Are tokens semantic rather than tied to raw values?
  • Do component APIs prevent obvious misuse?
  • Does theming flow through tokens instead of ad-hoc overrides?
  • Are localization and accessibility built into the model?
  • Is there a versioning and deprecation policy?
  • Is the design system easier to adopt than to bypass?

Exercises​

Exercise 1 - Token Audit​

Review twenty tokens and label each as:

  • semantic
  • raw-value driven
  • redundant

Exercise 2 - Component API Review​

Take one complex component and identify:

  • the core use case
  • misuses the API currently allows
  • which props could become composition points

Exercise 3 - Adoption Review​

Interview two consuming teams and document:

  • where the system saves time
  • where it causes friction
  • what would make bypassing less attractive

Further Reading​