Design System

Definition: A shared library of reusable components, styles, and rules, backed by Design Tokens, that keeps a product’s design and code consistent across every screen, feature, and team building it.

How It Works

Sits on four layers, roughly by abstraction: design tokens (raw values), components (buttons, inputs, cards built from tokens), patterns (recurring combinations of components, like a search-and-filter bar), and product screens (real features assembled from patterns)
Ships as two synchronized artifacts: a design file (a Figma library with components and variants) and a coded component library (an npm package or internal repo engineers actually import)
Documentation ties the two together: usage guidelines, do/don’t examples, accessibility notes, and prop or variant tables so a designer and an engineer reach for the same thing
Governed by a small team or working group who reviews additions, deprecates old components, and versions releases like any other shared dependency
Distributed like software: components get semantic version numbers, breaking changes ship with a migration guide, and consuming teams pin a version rather than always tracking the latest
Adoption is measured, not assumed: mature design systems track what percentage of shipped screens actually use system components versus one-off custom code
Component variants (size, state, emphasis) are enumerated up front so engineers don’t invent ad hoc combinations that never existed in the design file
Accessibility, focus states, keyboard behavior, ARIA roles, gets built into the component once instead of re-solved by every feature team
Design tokens usually come in tiers: primitive tokens (blue-500), semantic tokens that name a purpose (color-primary), and component tokens that scope a value to one component (button-background)
Cross-platform teams maintain platform-specific outputs from the same token source, so color-primary compiles to a CSS variable on web, a UIColor on iOS, and a Kotlin resource on Android
Design system teams often run “office hours” or a Slack channel so consuming teams can ask “does this already exist” before building something new

Under the Hood

Each layer only depends on the layer below it. A component never hardcodes a color, it references a token. A pattern never hardcodes a button style, it composes the Button component. This one-directional dependency is what makes a rebrand or a theme change, like dark mode, a token-layer edit that ripples upward automatically, instead of a manual hunt through every screen.

The design file and the coded library are two independent implementations of the same contract. Figma components define visual variants; the coded library defines the same variants as component props. Nothing forces these to match automatically, which is why design systems assign an explicit owner to keep them synchronized, and why “Figma doesn’t match prod” is the most common failure mode teams report.

Governance is what keeps the library from becoming a junk drawer. A proposed component or variant goes through review against existing patterns before merging, the same way a pull request goes through code review, so the library grows by consolidation rather than by accretion.

Layers at a Glance

Layer	Example artifact	Changes how often
Tokens	`color-primary-500`, `space-4`	Rarely, deliberate design decisions
Components	`Button`, `TextInput`, `Card`	Occasionally, new variants added over time
Patterns	Login form, filter bar, pagination	Sometimes, as UX needs evolve
Product screens	Checkout page, settings page	Frequently, product-specific work

Worked Example 1

Given: A company rebrands its primary color from blue to purple. The design system has 40 components and the product has 300 screens.
Step: Because every component references color-primary-500 rather than a literal hex value, the token value changes once, in one file.
Answer: All 40 components and all 300 screens update automatically on the next build, zero manual edits per screen.

Worked Example 2

Given: A team building a “Bulk Export” feature needs a button variant that doesn’t exist yet, one with an icon plus a loading spinner state.
Step: They check the system’s contribution process, propose the variant against the existing Button API, and get it reviewed rather than shipping a private component.
Answer: The variant becomes a documented option; the next team that needs the same pattern reuses it instead of inventing a near-duplicate button.

Worked Example 3

Given: An audit finds three different “Card” components in the codebase, one from the design system and two ad hoc versions built by feature teams under deadline pressure.
Step: The design system team compares all three, folds the useful variations (a card with an image slot, a card with a footer action) into the official component, and deprecates the duplicates with a migration guide.
Answer: The codebase converges back to one Card component with more capability than any of the three originals had alone.

Worked Example 4

Given: A feature team proposes a one-off “Danger Modal” styled specifically for their delete-account flow, with a red header no other modal uses.
Step: Governance review asks whether “danger” as a concept should exist at the modal level or the token level; they decide it belongs as a variant="danger" prop on the existing Modal component, driven by a semantic color-danger token.
Answer: Any future destructive-action flow reuses the same variant instead of every team inventing its own red modal.

Why It Matters

Prevents the visual and functional drift that happens naturally when many designers and engineers build features independently over time
Cuts the cost of both design and engineering, a new screen assembles existing components instead of designing and coding one from scratch
Makes systemic change, a rebrand, a dark mode, a contrast fix for accessibility, a token-layer edit instead of a screen-by-screen hunt
Gives new team members a concrete reference for “how we build things here” instead of relying on tribal knowledge
Centralizes accessibility and internationalization fixes so they apply everywhere at once instead of being patched screen by screen
Speeds up prototyping, since a designer can assemble a realistic-looking flow from real components instead of drawing boxes from scratch
Reduces QA surface area, a bug fixed in the shared Button component is fixed everywhere it’s used, instead of needing 40 separate patches
Makes cross-platform consistency achievable, the same token source can drive web, iOS, and Android so a brand doesn’t look like three different products
Shortens onboarding for new designers and engineers, since the system doubles as living documentation of the product’s visual and interaction language

Common Pitfalls

Building an exhaustive design system before the product has enough real screens to know what components are actually needed, over-investing too early
Letting the design system and the coded component library drift out of sync, so Figma no longer matches what’s actually shipped
Treating the design system as a one-time project instead of an ongoing product with its own roadmap, backlog, and users, the teams consuming it
No clear contribution or governance process, so components get duplicated instead of extended
Over-abstracting components with too many configurable props, making them harder to use correctly than just writing custom CSS
Skipping deprecation planning, so removing an old component silently breaks every screen still importing it
Measuring the system’s success by component count instead of adoption rate or how much duplicate UI it actually eliminated
Adding a new component variant for a single screen’s edge case instead of asking whether the requirement generalizes
Assuming a design system removes the need for design review entirely, it standardizes the building blocks, not the judgment of how to arrange them

Comparison

	Design System	Style Guide	Component Library	Pattern Library
Scope	Tokens + components + patterns + guidelines	Visual rules only, color, type, logo usage	Coded, reusable UI components	Reusable combinations of components
Includes code	Yes	No	Yes	Sometimes
Includes rationale and guidelines	Yes	Yes	Rarely	Sometimes
Versioned like software	Yes	No	Usually	Sometimes
Typical owner	Cross-functional design system team	Brand or marketing team	Frontend engineering	Design and engineering together
Governs accessibility behavior	Yes	No	Sometimes	Rarely
Has a contribution/review process	Yes	Rarely	Sometimes	Rarely

Example

Google’s Material Design and Shopify’s Polaris are both public design systems: token-backed, versioned component libraries with documented usage rules that thousands of external teams build on, not only their own internal product teams.

Stripe’s design system takes this further by generating both the Figma components and the React components from the same underlying token source, which is the theoretical ideal the flowchart above describes: a single source of truth feeding both design and code instead of two hand-maintained copies.

Atlassian Design System documents this governance model publicly too: proposed components go through an explicit review pipeline before being promoted from “in beta” to a fully supported part of the library, and deprecated components carry a listed replacement and removal timeline.

IBM’s Carbon Design System publishes its full token set, component source, and contribution guidelines openly, which is why it’s a common reference implementation for teams designing their own system’s governance process from scratch.

Referenced by

Dig deeper

Spot an error in this note?