A Corporate Design System: Tokens, Component Library and Governance

Setting up a design system: two-layer tokens and CSS variables, a component library with Storybook, SemVer versioning, the contribution process and when you don’t need one.
Technical summary
Technology
Design Tokens, CSS Custom Properties, Style Dictionary, Storybook, SemVer, npm
Topic
Setting up and governing a code-based corporate design system
Level
Intermediate–advanced
Prerequisites
  • Knowledge of CSS variables and component-based front-end development
  • Basic knowledge of npm package publishing and CI
In this article7 sections

Four shades of the same blue, three different button heights, a date picker rewritten from scratch in every project. This is what the interface becomes when several web applications, customer portals and corporate sites are developed by separate teams in an organization. A design system stops this fragmentation by turning design decisions and components into a versioned, documented, shared product. Below, we explain the setup of a code-based system, from tokens to the component library and from versioning to the contribution process, and when it shouldn’t be set up.

The scope of a design system

“Design system” means something different in every team. The designer thinks of the Figma library, the front-end developer of the npm package, the product manager of the style guide. If you don’t define the scope in writing from the start, mismatched expectations and half-finished work are inevitable. The typical layers are:

Layer Content Owner
Foundations Color, typography, spacing, border radius, shadow, motion tokens Design + front end
Components Button, form field, modal, table, notification; their states and variants Front-end team
Patterns Form layout, list–detail screen, empty state, error page Design + product
Content rules Error message language, button labels, date/currency format Content / product
Governance Versioning, contribution process, decision records, support channel System team

Start small: shipping the first version with the foundations and the 8–10 most-used components is healthier than trying to finish all layers at once. To find the priority components, it’s enough to take a screenshot inventory of existing apps and group the recurring elements. The inventory ends the debate.

Design tokens and CSS variables

A token is the named, platform-independent form of a design decision. A healthy structure has two layers: primitive tokens hold the raw value (color.blue.600), and semantic tokens express the purpose of use and reference a primitive token (color.action.primary). Components use only semantic tokens; when the brand color changes or a dark theme is added, component code isn’t touched. The mistake we see most often in the field is components bound directly to primitive tokens such as blue-600. On the day a theme arrives, hundreds of files change.

{
  "color": {
    "blue":  { "600": { "$type": "color", "$value": "#1d4ed8" } },
    "gray":  { "900": { "$type": "color", "$value": "#111827" } },
    "action": {
      "primary": { "$type": "color", "$value": "{color.blue.600}" }
    },
    "text": {
      "default": { "$type": "color", "$value": "{color.gray.900}" }
    }
  },
  "space": {
    "2": { "$type": "dimension", "$value": "8px" },
    "4": { "$type": "dimension", "$value": "16px" }
  }
}

This format follows the $type/$value structure recommended by the W3C Design Tokens Community Group. Token source files are kept in Git and converted to target platforms with a build tool. Style Dictionary is a widely used open-source tool for this; support for reading the $type/$value format directly came with major version 4, while older versions expect a value key. The configuration below produces the basic CSS output in both versions:

// style-dictionary configuration (config.json)
{
  "source": ["tokens/**/*.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "dist/css/",
      "files": [{ "destination": "tokens.css", "format": "css/variables" }]
    }
  }
}

The output is a file containing CSS custom properties such as --color-action-primary under :root. For theme support, the semantic layer is redefined with a second set of values:

:root {
  --color-action-primary: #1d4ed8;
  --color-text-default: #111827;
  --color-surface: #ffffff;
}
[data-theme="dark"] {
  --color-action-primary: #60a5fa;
  --color-text-default: #f3f4f6;
  --color-surface: #0f172a;
}
.btn-primary {
  background: var(--color-action-primary);
  padding: var(--space-2) var(--space-4);
}

Verify contrast at the token level: the WCAG thresholds (at least 4.5:1 for normal text) for every semantic text/background pair can be checked with a script at build time. Let a pair that doesn’t meet the threshold break the build rather than be discovered on screen. For other accessibility requirements at the component level, see the WCAG 2.2 developer guide.

Syncing Figma and code

If designers work with variables in Figma, decide where the single source of truth for tokens will sit. There are two common models: tokens are kept in Git and exported to Figma, or they’re edited in Figma and arrive in Git as a pull request via a plugin or API. Whichever you choose, the change should go through code review, and nobody should update two places by hand. Otherwise, within a few months the design file and the live interface diverge, and nobody knows which one is right.

Component library and documentation

In a component library, API design decides the fate of the work. Props are a contract across versions; adding a new boolean prop for every team’s special need soon creates an unmanageable surface. A button with seventeen props isn’t a button anymore. Principles that reduce this risk:

  • Define variants with constrained union types instead of free text: variant: 'primary' | 'secondary' | 'danger'.
  • Offer style overrides (style, arbitrary className) in a controlled way; otherwise consistency scatters again.
  • For complex components, use a compound structure instead of one giant component: <Dialog>, <Dialog.Title>, <Dialog.Actions>.
  • Solve accessibility inside the component: focus management, ARIA attributes and keyboard behavior shouldn’t be left to the consuming team.
  • Instead of writing from scratch, consider building your own visual layer on top of an unstyled (headless) library with ready-made behavior; writing the keyboard and ARIA behavior of complex components correctly takes serious effort.

Storybook is the common choice for documentation: each component’s variants are written as “stories”, the prop table is generated automatically from TypeScript types and can be tried interactively. The accessibility addon (@storybook/addon-a11y) runs an axe-core scan on every story. Visual regression testing (comparing story screenshots) catches unwanted style changes before release; it’s often here that you first see which components a token change affects.

// Button.stories.tsx (Storybook, CSF 3)
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
  args: { children: 'Save' },
};
export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = { args: { variant: 'primary' } };
export const Danger: Story = { args: { variant: 'danger' } };
export const Disabled: Story = { args: { variant: 'primary', disabled: true } };

For configuration and addon details, the official Storybook documentation should be the reference; package names and the configuration format can change between versions.

Versioning and distribution

Apps consuming the design system use it as a dependency. That’s why semantic versioning (SemVer) discipline isn’t negotiable:

Change Version Example
Bug fix, visual tweak Patch (1.4.2 → 1.4.3) A fix to the focus ring thickness
Backward-compatible new feature Minor (1.4.3 → 1.5.0) A new size value for the button
Breaking change Major (1.5.0 → 2.0.0) A prop rename, a token deletion

Practices that work in the field:

  • Publish tokens and components as separate packages (e.g. @company/tokens, @company/react). React and Next.js apps can use the component package, while a project that doesn’t use React or a WordPress theme can use only the token CSS.
  • Publish the packages to an internal npm registry (GitHub Packages, GitLab Package Registry, Azure Artifacts or Verdaccio).
  • Generate the changelog not by hand but with a tool such as Changesets on every pull request; the version type is decided during the contribution.
  • Before a breaking change, keep the old API alive with a “deprecated” warning for at least one minor version and, if possible, provide an automatic migration script (codemod).
  • Run the release pipeline in CI: don’t let a package be published unless type checks, unit tests, the accessibility scan and visual regression pass. For setting up the pipeline, see the CI/CD pipeline with GitHub Actions guide.

Contribution and decision process

Design systems usually collapse for organizational rather than technical reasons: a team can’t find the component it needs in the system, the contribution process takes weeks and everyone writes their own copy. Six months later, the system exists only on paper. To prevent this, the process should be written down and lightweight:

  1. Request: A need for a new component or variant is opened with a template: the use case, a screenshot, how many products need it.
  2. Assessment: The system team checks whether the need can be met with an existing component. A need specific to a single product stays within that product; if it recurs in two or more products, it’s taken into the system.
  3. Design and API proposal: Before code is written, props, states and accessibility behavior are agreed in a short document.
  4. Implementation: The requesting team can also make the contribution; the system team reviews it and approves conformance with the standards.
  5. Record: Important decisions (e.g. “why the date picker calendar starts the week on Monday”) are kept as decision records; the same debate isn’t reopened.

To measure adoption, a simple script that scans consuming repositories for the use of system components and local copies is enough. Ways to head off local copies with code-level module boundaries and lint rules are explained in the TypeScript codebase standards guide.

When you don’t need a design system

A design system is a permanent maintenance burden: it requires at least one person’s regular time, up-to-date documentation and continuous communication with consuming teams. In the following cases, a lightweight approach is enough instead of a full system:

  • A single product, a single team: Shared components sit in a folder within the app; a separate package and versioning add unnecessary load.
  • The product is still taking shape: If the interface changes every sprint, early abstraction makes the wrong APIs permanent.
  • A ready-made library meets the need: Defining a theme with tokens only on top of a mature component library is enough for many internal apps.
  • No ownership: If there’s no clear person or team to take on maintenance, the system goes out of date within a few months and teams start avoiding it. An ownerless system rots.

Even in these cases, setting up the token layer is a low-cost, high-return first step: gathering color and typography decisions in a single file makes a later move to a full system easier. On WordPress-based sites, similar consistency is achieved with Elementor global styles; this approach is explained in the scalable site structure with Elementor guide, and the token CSS can be the common denominator between these two environments.

If you’re planning to build a shared interface language for several applications and sites, we approach the UI/UX and corporate design system work together with its scope and ownership model.

Frequently asked questions

Are a design system and a component library the same thing?

No. A component library is part of a design system. A design system also covers tokens, usage patterns, content rules, documentation and governance, including versioning and the contribution process.

Why are tokens split into primitive and semantic?

Primitive tokens hold the raw value, semantic tokens the purpose of use. If components use only semantic tokens, a brand color change or a dark theme is done by remapping only the semantic layer, without touching component code.

At what stage should a design system be set up?

It makes sense to set one up once you start seeing the same interface elements rewritten by two or more products or teams. In single-product projects whose interface is still changing rapidly, starting with the token layer is enough.

How are breaking changes in a design system managed?

Semantic versioning is used; a breaking change increments the major version number. The old API is kept with a deprecation warning for at least one minor version, migration steps are written in the changelog and, where possible, an automatic codemod is provided.

Support

Contact us for support or a discovery session on this topic.

Contact form
[email protected]

Eretek Web

We build and maintain corporate websites, WordPress and CMS platforms, intranet and SharePoint portals, document management, and form and approval workflows, and keep them secure and up to date.

Knowledge Center

Other articles