Design Systems

A design system bundles design language, tokens, coded components, patterns, usage guidance and governance, run as a product. A component library is its coded parts; a style guide documents rules; a pattern library catalogues reusable solutions; a UI kit is design-file assets.

A dedicated team brings focus, quality and a roadmap but costs more and can drift from product needs. Part-time contributors are cheap and close to real problems but lose time to deadlines. A hybrid, a small core plus allocated contributors, balances both.

A design system promises consistency, faster delivery through reuse, and accessibility and quality fixed once for every consumer. It costs a standing team, ongoing upkeep, migrating existing products, documentation and support, so it pays off only when many teams reuse it.

Beyond engineers and visual designers, a design system needs accessibility expertise, content design for labels and guidance, product management to prioritise, interaction design, quality assurance, and engineers for each platform it serves. Small teams borrow these roles part-time.

Compare the system's full cost with the value it creates: effort saved when teams reuse parts instead of building them, fewer UI and accessibility defects, and cheaper cross-cutting changes. It is hard because the counterfactual is unobservable and benefits lag costs.

Extraction harvests patterns already proven in production, so the system fits real needs and has a first consumer, but it inherits inconsistency and debt. Greenfield allows a clean, coherent model but risks untested abstractions nobody adopts and a costly retrofit.

An interface inventory is a systematic catalogue of the colors, type styles, spacing, icons and components a product actually uses, grouped and counted. It exposes duplication and inconsistency, grounds the system's scope in evidence, and helps win stakeholder support.

A published reference system encodes another organisation's brand, products, platforms and constraints. Copying it imports decisions without their reasons; studying it supplies proven structures, accessibility behaviour and naming ideas to adapt deliberately to your own users.

Ship foundations first, then choose components by how widely they are used and how much pain their inconsistency causes, weighed against effort and the pilot's upcoming work. Keep the release small but complete rather than broad and shallow.

A screenshot audit captures what users actually see — visual inconsistency, combinations, platform differences — but misses exact values and hard-to-reach states. A code audit finds declared values and near-duplicates, including unused ones, but cannot show how they combine on screen.

Consumers bind to a token's name, not its value. A value change flows through every existing reference and restyles apps, while a rename leaves every reference pointing at nothing, so builds fail or styles silently fall back.

In the Design Tokens Community Group format any JSON object with a $value is a token and any object without one is a group; $value holds the value, $type declares its kind, and $description explains its purpose in plain text.

An intent name such as breaking-news text color stays true when its value changes; a value name like red-text either lies after a rebrand or forces a rename in every consumer, and it couples unrelated roles that merely looked alike.

Primitive tokens hold raw options such as every blue in the palette, semantic tokens alias them by purpose such as the primary-action color, and component tokens scope a decision to one component. Product screens reference semantic tokens.

Add the new token, turn the old name into a deprecated alias that references it, and ship that as a minor release. Remove the old name only in a later major release, once consumers have had at least one release to migrate.

Components reference semantic names such as surface, primary text and border, and a mode supplies different values for those names. One mapping switches every component at once, while per-component dark styles multiply the work and drift apart.

Build-time theming bakes each theme's values into its own output: simple and fast, but switching means loading another output. Runtime theming resolves values while the app runs, allowing instant switching and nested scopes, at the cost of indirection and startup work.

Default to following the operating system's appearance preference, and offer three choices: system, light and dark. An explicit choice overrides the preference; system keeps tracking it live. Contrast settings are a separate axis that combines with either mode.

A density switch may tighten padding, gaps, row and control heights, and occasionally secondary text. Pointer targets must still meet WCAG 2.2 criterion 2.5.8 (24 by 24 CSS pixels or enough spacing), and legible text, focus indicators, contrast and content stay.

Multi-brand serves a known set of brands your own designers curate; white-label serves clients who bring their own branding, unknown in advance. White-label therefore needs a narrow override surface, derived values and automatic validation instead of hand review.

Beyond working code: accessibility conformance, responsive and localisation readiness, support for every theme, usage docs, automated tests, parity with the design asset, and design and engineering sign-off - each backed by evidence, so consumers meet no surprises in any supported context.

A component spec covers anatomy, variants, states, behaviour, content rules, spacing and sizing redlines, and accessibility notes. Each closes a gap that different teams would otherwise fill differently: unnamed parts, missing states, invented behaviour, broken copy, drifting spacing and inaccessible builds.

Experimental may change or disappear without notice. Beta is settling, with breaking changes announced ahead. Stable changes incompatibly only in a major release. Deprecated still works but gains nothing new and names its replacement and removal plan.

A shared component's defects multiply: every consuming team inherits them, cannot easily fix them locally, and starts distrusting the system. So its bar covers every context consumers use - themes, locales, screen sizes, assistive technology - not just the first screen.

Variants are options chosen when placing a component, such as size or emphasis; states are conditions it enters at runtime, such as hover, focus, disabled or error. Keeping them separate makes every variant-by-state combination specifiable. Error is a state.

Overview, usage, anatomy, variants and states, API, accessibility and content guidance, in the same order on every page. A fixed template lets readers jump straight to what they need and makes missing sections obvious to authors.

Docs kept beside the component change in the same review as its code, are versioned and released with it, and can be checked by the build, so an API change without a docs update is caught instead of drifting silently.

Each answers a different question. Foundations hold shared rules - color, type, spacing, motion, icons, accessibility principles. Components document each reusable part. Patterns show how parts combine for recurring tasks. Separating them lets readers find answers by the kind of question.

A useful usage guideline says when to use a component, when not to and what to use instead. Pairing each do with a don't and a stated reason shows the boundary and lets readers judge cases the page never listed.

Hand-copied property tables and pasted snippets go wrong the moment a property changes. Generated tables read names, types and defaults from the component's source, and examples the docs build renders turn API drift into a build failure.

Deprecation keeps the component working while warning consumers and naming its replacement, giving teams a support window to migrate on their own schedule; removal comes later in a major release, so no product breaks without warning.

Changes grouped by impact: first anything requiring consumer action, with the exact steps; then visible visual changes, new features and fixes, each naming the component, platforms and design-library counterpart, with links to docs and migration notes.

Measure adoption from several signals: component usage in code scans and design files, the share of product UI built from system parts, detach and override rates, and consumer satisfaction surveys. An install proves only that a dependency exists.

Keep it local unless several teams need the same thing, it can be specified without one feature's business logic, and its design has settled; otherwise it stays a documented local component, built from system parts, that can be promoted later.

Map the old button's options to the new one, write a syntax-aware codemod that rewrites mechanical cases and flags the rest, test it on real usages, then have teams dry-run it and track what remains.

A raw redline records what one drawn frame measured, so engineers hardcode it and it drifts when a mode or the system changes. Naming the component, variant and token says what to reuse and keeps every theme and future update working.

Annotate what one frame hides: loading, empty, error and permission states; content extremes and truncation; how the layout resizes; data rules such as default sort; and what changes after an action. Left out, each becomes the engineer's guess.

Design-file variables should mirror the coded tokens: same names, same tiers and aliases, same modes, ideally generated from one source. Maintained by hand on both sides, values and names drift, so designs show colours or spacing the product never renders.

An overridden instance keeps its link to the library component but changes some properties locally; a detached one cuts the link and becomes loose shapes. Style overrides and detachments stop following library updates and depict components that code does not have.

Raw values bypass tokens, so themes, modes and system updates skip them. A lint rule catches them as code is written and suggests the token for that role — not auto-applied, since one value can serve several roles.