Design System Best Practices for Scalable Design

Most design system best practices sound reasonable on paper, and plenty of them get ignored anyway. The test that holds up is whether product teams adopt the result.

Sparkbox’s 2021 survey of in-house teams shows how big the gap can be. 50% of the systems their teams rated very successful supplied more than 75% of their websites or applications. None of the systems rated slightly successful or not successful reached that share.

Audit the Existing UI Before Building Anything

Count what already exists before you build a single component. The first deliverable is an inventory of every distinct button, color, type size and spacing value across live screens and Figma files. A component library comes later.

You’ll find near-duplicates. Grays that differ by a few hex digits, buttons with different heights and radii. Each one is design debt the system has to resolve.

At minimum, log the following.

• every color value in use, with the screens that use it
• type sizes, weights and line heights
• spacing and radius values
• repeating interactive patterns (buttons, inputs, modals, tabs)

Group the duplicates into candidates for tokens and design system components, then rank them by how many products repeat them. Anything used in one place stays out for now.

Record the starting counts too (shared components, detached instances, off-system colors). You’ll want a before number once adoption measurement begins.

An audit with no rule for what gets standardized produces a catalog, not a system. Set the rule first. A pattern enters the system when two or more products use it.

How Should Design Tokens Be Named and Structured?

Primitive tokens hold the raw values. Semantic tokens map a role onto one of those values, and component tokens come last, only for cases where a component needs something the semantic layer can’t say. Whatever the tier, name the token after its purpose and never after its value.

Material Design 3 calls the tiers reference, system and component. Primer’s version is base, functional and component/pattern. Underneath, the structure is the same.

Atlassian’s token names show the naming pattern well. Take color.background.danger.bold.hovered. “Color” is the foundation, “background” is the property, and “danger.bold.hovered” are modifiers (Atlassian Design System documentation).

Atlassian also documents a base token, Purple800 (#5E4DB2), that the semantic token color.text.discovery points to. Repoint the alias and every product follows along. The hex can change without the role name going stale.

Component tokens multiply quickly, and that’s the usual way this structure goes wrong. Primer’s documentation keeps them limited and says functional tokens are preferred. It also bars base tokens from direct use in code or design.

I’d skip component tokens until a component needs a value the semantic layer cannot express.

Token format and tooling

The Design Tokens Community Group, a W3C Community Group, published the first stable version of its specification (2025.10) on October 28, 2025.

The specification defines how JSON represents tokens so tools can exchange them. The release added theming and multi-file support, along with modern color spaces such as Display P3 and Oklch. Style Dictionary, Tokens Studio and Terrazzo serve as reference implementations (W3C Design Tokens Community Group, 2025).

On the design side, Figma Variables cover collections, modes and aliasing, and they import DTCG-format JSON that carries Figma-specific extension keys (Figma Help Center). Style Dictionary transforms token files into platform output such as CSS variables, and Tokens Studio manages tokens inside Figma.

Setting up variables and modes in Figma takes a few minutes once the collections are planned. The designtokens.org FAQ lists the stable version as safe to use in production.

Theming, dark mode and multi-brand tokens

Theming works by remapping semantic tokens to different primitives. Component tokens never change, which is why they hold no hard-coded values.

• Light and dark themes, and high-contrast ones too, all become modes of one collection in Figma
• How many modes a collection can hold depends on the Figma plan (Figma Help Center, as of June 2025)
• Primer reserves a “brand” prefix for marketing-specific tokens, so a second visual identity does not collide with product tokens

Each new theme adds one more semantic-to-primitive mapping to maintain, and every semantic token needs a value in it.

What Component Documentation Needs to Include

Every component page should cover anatomy, usage and non-usage rules, variants, states, code props and accessibility notes.

Write the non-usage rule. It tells a designer which component to pick instead.

GOV.UK’s January 2023 accessibility strategy plans to improve the accessibility documentation for individual styles, components and patterns, so the notes sit on the component page instead of in a separate audit (GOV.UK Design System team).

DWP’s design system adds a caveat worth copying. Using standard GOV.UK components does not guarantee an accessible implementation, so teams still test.

That’s the minimum. Anything beyond it, such as a full documentation structure for the system, adds changelog links and migration notes to each page.

Documentation split across Figma, Storybook and a wiki drifts apart, and nobody can say which page is right.

Where documentation lives

Storybook is where rendered states and props belong. According to its current documentation, Autodocs generates a page from stories, and MDX adds prose and layout around it (Storybook documentation).

Usage guidelines and design rules written as prose fit better in zeroheight, a documentation platform. Component specs and the variants designers pick from stay in Figma.

One rule stops them contradicting each other. Every fact has one home. Props live in code, usage rules live in prose, and the other tools link to them.

Accessibility Requirements for Design System Components

Target WCAG 2.2 Level AA for every component. Run automated tests in CI, then add manual checks with assistive technology for whatever the tools miss.

WCAG 2.2 became a W3C Recommendation on 5 October 2023 and added 9 success criteria. Three of them are Level AA and land directly on components.

• Under 2.4.11 Focus Not Obscured (Minimum), a focused element can’t be entirely hidden by author-created content
• 2.5.7 Dragging Movements requires a single-pointer alternative for drag actions
• 2.5.8 Target Size (Minimum) sets pointer targets at 24 by 24 CSS pixels, with spacing exceptions

Most of the work still comes from older criteria, namely keyboard operation, visible focus and text contrast. Check the color contrast of every foreground and background token pair once, in the system, and every product inherits the result.

Custom components such as menus, tabs and comboboxes need ARIA roles and states plus keyboard patterns, documented on the component page. Native HTML elements already carry their roles, so reach for them first.

The contrast numbers are grim, and the automation numbers are lower than most people assume.

• 83.9% of the top million home pages had low-contrast text in 2026, up from 79.1% in 2025 (WebAIM Million, February 2026)
• About 57% of issues, counted by volume, are found by automated testing (Deque, 2021)
• About 29% of the barriers on GDS’s deliberately inaccessible test page were missed by all ten automated tools tested, and no single tool found more than 41% (GDS Accessibility team, 2017, cited in the jest-axe README)
• Minimum pointer target of 24 by 24 CSS pixels (WCAG 2.2, W3C, 2023)

The two automation figures are not directly comparable. Deque counts issues by volume across real audits, which lets frequent failure types weigh heavily, and it argues that counting by WCAG criteria understates what tools find. GDS tested ten tools against a page built to hold 143 deliberate failures.

Neither number certifies a component, so automated checks are a floor, not a sign-off.

GOV.UK Frontend shows how this goes wrong. As of November 2022, its jest-axe tests covered only the first example snippet of each component and only the static HTML, so JavaScript-driven states went untested (alphagov/govuk-frontend, issue 3041). The project has since moved to running axe-core through Puppeteer against every component and example (alphagov/govuk-frontend, PR 3522).

Test every documented state, not just the default.

Which Governance Model Fits Your Organization?

The right model depends on how many product teams use the system and how much contributor time they can spare. With only a few products, a centralized core team usually works. Once there are many, a federated group makes more sense, and a hybrid sits between the two.

The failure modes come from zeroheight’s governance guidance, Nathan Curtis’s team models and a 2016 GOV.UK design notes post on why centralized teams stop scaling. Magic Patterns (2026) supplies the hybrid case.

Sources disagree on the menu of models. Nathan Curtis (2015) names solitary, centralized and federated, while zeroheight names federated, centralized and hybrid.

The gap is one of timing. Curtis lists the one-team starting point, and zeroheight describes the models it sees once teams scale.

Hybrid existed before the label. Salesforce’s Lightning Design System team described a centralized core plus federated contributors in October 2015 (Jina Bolton), the arrangement zeroheight now files under hybrid.

Teams in practice lean central. Sparkbox’s 2021 survey of 136 in-house respondents found 46% with a dedicated centralized team, 26% solitary and 24% federated.

Cost is a real issue too. Staffing was a top challenge for 39% of in-house teams in the same survey, and funding for 23%.

Federated does not remove the cost. zeroheight advises a Design System Manager to lead the federated team and warns that engineers’ time can be difficult to carve out.

Centralized is the pick when product teams cannot spare contributor time. If they can, and the products sit at different maturity levels, federated fits better. Hybrid comes in when contributors are plentiful but the shared libraries still need a core team to build them.

The model does not have to be permanent, per zeroheight. It should change as the organization grows.

How to Run Contributions Without Creating a Bottleneck

Give contributors one written path from request to release, with fixed acceptance criteria and a named owner at each step. Without it, product teams stop waiting and build their own components.

1. Open an issue that states the rationale and the intended behavior.
2. The maintainer triages it, checking whether the component adds value across products and who will own it.
3. The core team compares the proposal with existing patterns in a design review before anyone writes code.
4. The contributor builds usable code and a Figma component, both using tokens and both documented.
5. A system developer tests the pull request by hand as well as through CI.
6. The change ships under the next version number with a changelog entry.

Carbon’s contribution documentation (updated September 2026) says every contribution follows a defined process, and that larger ones such as new components and patterns need a more rigorous one. Experimental components in discovery go through Carbon Labs, and a net-new component must complete the Product Development Lifecycle and component checklist before it counts as done.

Carbon’s earlier v10 contribution guide asked for a rationale and the intended behavior in the opening GitHub issue.

The B.C. Design System states its acceptance criteria up front, asking for React code plus a Figma component, token use and full documentation (Government of British Columbia, last updated November 2025).

Alberta’s design system points newcomers the other way. Full components are complex to contribute, so it recommends starting with bug fixes, documentation updates and enhancements to existing components.

Plenty of teams have no path at all. In Sparkbox’s 2022 survey, 36% of maintainers had no defined process for accepting contributions (162 responses).

The usual failure is a path that exists on paper and stalls in review. One respondent in Sparkbox’s 2021 survey said some brands built micro design systems to get around the central team.

Put a review deadline on the path and report every miss.

How to Version a Design System and Retire Components

Semantic Versioning fits design systems well. Breaking changes get a major release. Backward-compatible additions and deprecations go in a minor one, and bug fixes are patches. Removing a prop or deleting a component is breaking, and so is renaming a token.

The Semantic Versioning 2.0.0 specification requires a minor bump when public API functionality is marked deprecated. It also treats 0.y.z as initial development, where anything may change.

The specification also gives a reason to make major bumps feel heavy. Incompatible changes should not reach code with many dependents lightly, because upgrading is expensive, and a design system consumed by many products is exactly that case.

The classic mistake is a breaking change shipped as a minor version. The specification’s remedy is a new minor version that restores backward compatibility.

Changesets handles the bookkeeping. A changeset holds a version type following semver plus a changelog note, and the version command consumes them, updates package versions and writes the changelog entries (Changesets documentation).

Contributors add the changeset file in the pull request, so the version decision happens at review time instead of release day.

Deprecation windows are where published policies disagree.

Adobe’s Spectrum Web Components considers removal in the next major release after the one that marked the item deprecated. When that is not possible, the minimum is 2 releases or six months, whichever is smaller.

Esri’s Calcite Design System keeps components for at least 2 major release cycles. Component APIs go in the closest or next major, and design tokens in 1 to 2 major cycles (guidance edited May 2026).

Siemens Industrial Experience ships one major release every six months, removes deprecated components in the next major version and supports each major for about 12 months.

The windows only compare once the cadence is known. Two major cycles is about a year at Siemens’ six-month cadence, and longer for any system that ships majors less often.

Write each deprecation as a version pair, the way Esri does, with something like deprecated in v2.0.0 and removal targeted for v3.0.0. Add a calendar date for the removal, because a version number alone hides the wait.

How to Measure Design System Adoption

Adoption shows up in two places. Code reveals it through component imports and package versions, and design files reveal it through the share of layers that come from the library. Detachment data and a survey belong on top of that, because usage counts alone do not say whether the system works.

Pinterest’s Gestalt team defines design adoption as the share of layers on a page that come from the library. A page with 7 Gestalt layers out of 15 scores 46.7% (Figma’s write-up prints 46.6%), calculated per frame and then totaled (Figma, Ravi Lingineni).

A nightly service called FigStats reads every file through the Figma REST API. It only counts files edited in the last two weeks and pages marked “handoff”, because other Figma files are too noisy to score.

As of February 2025, Figma Library Analytics covers components, styles and Figma Variables for Organization and Enterprise plans. The Library Analytics API, available since February 11, 2025, is for Enterprise plans.

athenahealth’s Forge team watches detachment because it usually points to a bug or a missing enhancement, or sometimes just people combining elements in ways nobody planned. An uptick on a container component exposed an auto layout bug before anyone reported it (Figma, 2025).

Figma’s announcement of Design System Analytics describes Squarespace’s design platform team planning to use the compare libraries view to track adoption of a new shared library across teams and to confirm the old version was deprecated. That gives a team evidence for when an older version can be retired.

Few teams measure at all. Sparkbox’s two editions put the share at 31% of 160 in-house respondents in 2021 and 16% of 134 respondents in 2022. The 2022 write-up calls the result consistent with 2021, and in both editions most teams tracked nothing.

A high adoption score can still sit next to a poor experience. Pinterest notes there is no ideal adoption number, because the score depends on how complete the system is and how people use it.

Pair the score with a satisfaction survey.

When a Design System Is Not Worth the Cost

A design system does not pay off for a single product built by one small team, or for any team that cannot reserve time for upkeep. A token file and a small shared component set cover those cases.

• One product, one team, one repository
• A team that does not feel inconsistency or communication problems today
• No owner with reserved maintenance time

Sparkbox’s Bryan Braun (2018) notes that small teams often share standups, a Kanban board and a code repository, and that one product owner approves their work. The communication problems a system solves barely exist there, and he calls a dedicated system team more a cost center than a profit center.

Cost shows up as debt, for one thing. In Sparkbox’s 2021 survey, 53% of 136 in-house respondents said their design system created design or technical debt.

Then there’s staffing. Maintainers in the 2022 edition ranked it a top challenge (35%) far more often than a top priority (13%), the widest gap in the survey.

Opentrons describes the small-team version of the mistake. The designer who led its design system unification read mostly about systems built by large, well-resourced teams, assumed Opentrons needed the same complexity, and later advised studying teams that match your size and constraints.

A style guide with agreed tokens is the cheaper middle step. The difference between a style guide and a design system is that the system adds shipped code and someone funded to maintain it.

Design System Best Practices FAQ

What does a design system include?

Tokens, components and usage documentation, all kept in a shared library that product teams build from. In Sparkbox’s 2022 survey of 219 respondents, 98% included typefaces, colors and styles, 95% components, and 85% component documentation.

How is a design system different from a component library?

A component library covers only one part of the system. It supplies coded interface parts, while the full system adds design tokens, usage rules, design files and the process for changing them.

How long does it take to build a design system?

No sourced benchmark exists, because scope sets the timeline. A token file with a few components is a different project from a full system with documentation and governance.

Sparkbox’s 2019 survey found that design systems are an ongoing investment, so plan for upkeep instead of a finish date.

Should a team adapt an open-source design system instead of building one?

Yes, when the products serve a similar audience. New Zealand’s all-of-government design system alpha was built on GOV.UK styles and components, and its team said it was adding features GOV.UK did not offer, such as switching between dark and light colors.

Carbon, Primer and Material Design 3 are public too, but your tokens, brand and governance stay your own.

Does visual regression testing belong in the release process?

Yes, for a shared library. Chromatic, made by the Storybook team, turns every story into a visual test that compares rendered pixels against baselines and flags changes on pull requests (Storybook documentation).

A reviewer approves the intentional changes, so a spacing or color tweak cannot reach every product unseen.

What to Fix First in a Half-Adopted Design System

Start with adoption evidence. The contribution path comes second, and tokens and documentation come last. Measurement shows where product teams bypass the system, so the rebuild targets real detachments.

• Baseline code and Figma adoption
• Publish the contribution path
• Rewrite tokens and documentation where detachments cluster

Sparkbox’s survey data on contribution processes and metric tracking shows both gaps are common. A system missing both gets no signal about why product teams build around it.

The trade-off is that the first phase produces a baseline and a written path, not new components.

This order holds as of October 2026. A change to Figma Library Analytics coverage, or a release after the stable 2025.10 token specification, would move the first and last steps.

A Figma design system tutorial covers the component and variable setup for the rebuild.

• Author
• Recent Posts

Bogdan Sandu

Bogdan Sandu specializes in web and graphic design, focusing on creating user-friendly websites, innovative UI kits, and unique fonts.

Many of his resources are available on various design marketplaces. Over the years, he's worked with a range of clients and contributed to design publications like Designmodo, WebDesignerDepot, and Speckyboy, Slider Revolution among others.

Latest posts by Bogdan Sandu (see all)

• How to Convert Figma to React [Step-by-Step] - November 6, 2026
• How to Insert Image in Figma With Ease - November 3, 2026
• How to Download Figma Files Fast and Free - October 30, 2026