Design Systems

Component Architecture

How to structure a component library that is consistent, extensible, and usable by both designers and developers.

#components#design system#component library#variants#props#atoms#molecules#patterns

What is it?

Component architecture refers to how a design system's UI components are structured, categorized, named, and organized. It encompasses the component hierarchy (atoms → molecules → organisms), variant system, prop definitions, and documentation standards. Good component architecture makes the system predictable and easy to contribute to.

Why it matters

A component library without architectural standards becomes inconsistent over time. New components are added that don't fit the pattern. Variants proliferate without naming conventions. Designers and developers end up with different mental models of the same component. Architecture is what keeps a design system maintainable at scale.

Best Practices

Atomic Design hierarchy: Atoms (Button, Input, Icon), Molecules (FormField, SearchBar), Organisms (Header, Sidebar).
Each component has one clear responsibility — avoid "god components" that do too many things.
Variant naming: Size (sm/md/lg), Variant (primary/secondary/ghost/danger), State (default/hover/focus/disabled/loading).
Props: prefer composition over configuration. A Button accepts children rather than having separate icon prop + label prop.
Documentation: every component needs — description, when to use/avoid, props table, visual examples of all states.
Accessible by default — every component should handle keyboard navigation, focus management, and ARIA attributes correctly.
Visual testing (Storybook) for every variant and state — catches regressions before they ship.
Version components — when a component changes fundamentally, a new version allows gradual migration.
Shared components should have a clear owner — who approves changes and additions?
Design and code parity — every component in Figma should have a code counterpart with the same name and variants.

Common Mistakes

Components that are too specific — built for one use case, not reusable.
Inconsistent naming between Figma and code components.
No variant system — ad-hoc variations added without pattern.
Documentation that describes what a component is, not when to use or avoid it.
No visual regression testing — components break silently.
Monolithic components that handle too many edge cases — should be split.
No clear contribution process — components get added without review.

Checklist

Components organized in Atomic Design hierarchy (atoms/molecules/organisms)

Each component has one clear responsibility

Variant naming is consistent across components (size/variant/state)

Every component is accessible by default

All states documented and visually tested (Storybook)

Figma and code components have matching names and variants

Documentation covers: description, usage, props, when to use/avoid

Clear ownership and contribution process defined

Components are versioned for breaking changes

Research & Theory

Atomic Design (Brad Frost, 2013)

Brad Frost's methodology for creating design systems from atoms (smallest UI elements) to molecules, organisms, templates, and pages.

Why it's relevant

Atomic Design provides the vocabulary for discussing component hierarchy. It's the most widely-adopted organizational framework for design systems.

Real-World Examples

Radix UI

Headless component library with correct accessibility built in. Components are behavior-only — styling is the consumer's responsibility. Architecture-first approach.

Shadcn/ui

Built on Radix, uses Tailwind for styling, owned by the consuming project. The fastest way to a professional component library in 2024.

Linear

Internal design system visible through their product — consistent components, clear variant system, dark/light mode parity. Used as a reference for SaaS component quality.