How I Set Up — and Keep Alive — a Multi-Brand Design System

• must Atoms bind visual properties to semantic tokens only.
• must Molecules compose atoms — they add spacing tokens, never new color decisions.
• must Organisms own layout & responsive rules; content arrives via slots/props.
• should Templates are the mode-QA surface — review all brand modes here before publish.
• never Pages define new components — gaps get contributed back down the ladder.
• note The mental model matters more than the folder names — many 2026 systems ship a flat components/ + patterns/ layout while still enforcing these composition rules.

Atomic design predates design tokens — Frost’s 2013 model starts at atoms. Modern component-driven teams add the token layer underneath: change a particle (brand-500) and every atom, molecule, and organism repaints without a single component edit. That’s the property the three-tier cascade in Act 01 guarantees, and it is exactly how the mode switch in the Modes act repaints this entire page.

• setup Primitives collection → 1 mode. Raw values never fork per brand.
• setup Semantic collection → modes brand-a · brand-b · dark · hc. Each mode rebinds aliases to different primitives.
• scope Scope variables (fill, stroke, radius…) so semantics appear only in relevant pickers — and hide primitives from publishing.
• apply Modes are set per frame or page and cascade — a whole brand preview is one dropdown change.

For brand portfolios beyond mode counts, Figma’s extended collections(Enterprise) let a child brand collection inherit a published parent and override only brand-specific values — updates flow down automatically.

• format W3C DTCG token spec released its first stable version—2025.10—on October 28, 2025. This establishes the industry-standard JSON format for cross-platform tokens.
• build Style Dictionary v5 natively supports DTCG 2025.10 (managing the transition to .tokens.json extensions), while Terrazzo (formerly Cobalt UI) provides a streamlined DTCG-native alternative.
• sync Figma REST API pulls variables programmatically. For compliance and consistency, CI checks like Check Designs validate usage while Tokens Studio handles GitHub PR syncs for team contribution.
• release Automated versioning via Changesets aligns token releases with semantic versioning: additive changes trigger minor, value tweaks patch, and name changes major releases.

[category]-[concept]-[property]-[state]

color-action-primary-hover
color-text-on-brand
spacing-inline-sm
radius-control

Purpose-driven paths (color-bg-surface-hover) have replaced the older Category/Type/Item taxonomy — the token name should say what it’s for, never what it looks like.

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from '@org/react';

const meta: Meta<typeof Button> = {
  component: Button,
  parameters: {
    design: { // Figma embed
      type: 'figma',
      url: 'figma.com/file/…?node-id=42',
    },
  },
};
export default meta;

export const Primary: StoryObj<typeof Button> = {
  args: { variant: 'primary', children: 'Continue' },
  play: async ({ canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button'));
  },
};

Controls mirror the Figma variant properties, the design parameter embeds the source frame, and the play function turns the story into an interaction test that runs in CI.

Since Storybook 9, interaction, a11y, and visual checks run as one Vitest-powered test suite; Chromatic’s TurboSnap only re-snapshots stories a change actually affects, and its UI Review step is the designer sign-off gate before merge.

📁 DS · Foundations (Published Library)
   ├─ 🎨 Variables
   │   ├─ Primitives      · brand-500, neutral-100, space-4…
   │   ├─ Semantics       · color-surface-primary, spacing-inline-sm
   │   └─ Component       · button-background, card-border
   ├─ 🔤 Type styles
   └─ 🌓 Modes            · Brand A · Brand B · Dark · HC

📁 DS · Components (Published Library)
   ├─ 🧩 Base             · Button, Input, Badge, Chip
   ├─ 🧩 Patterns         · Card, Alert, Form row, Nav item
   └─ 🧩 Templates        · Page shells, empty states

📁 DS · Icons (Published Library)
   └─ 🔣 Icon set (24px base)

📁 DS · Docs
   └─ 📝 Usage, do / don't, accessibility notes

Rule of thumb: components bind to semantics only. Semantics bind to primitives. No component should reference a raw primitive — that's how you keep modes repaintable.

• devmode Set per-platform Code syntax in the Variable details panel to map Figma variables directly to codebase token names.
• bridge Use Code Connect UI / CLI to map Figma component props directly to code parameters, surfacing exact imports and production-ready snippets in Dev Mode.
• multibrand Apply Extended Collections (Enterprise) to inherit a published parent foundations collection and override specific values for brand and sub-product overrides without splitting files.
• architecture Adopt a Variable-First Architecture, leveraging variable modes to control spacing, sizing, and motion, minimizing complex component variants.

• must Bind via semantic tokens · never raw primitives.
• must New components land in a branch with a sandbox frame + cases.
• must All 4 Modes visually reviewed before publish.
• should Contrast ratios checked against WCAG 2.2 AA.
• should Breaking changes bump the major version in the token package.
• never Hard-code hex values inside components.

• compliance WCAG 2.2 AA serves as the legal compliance standard (ADA / European Accessibility Act), mandating strict color contrast ratios (e.g. 4.5:1 / 3:1) and visible focus indicators.
• perceptual Internal token checks evaluate contrast using APCA (Advanced Perceptual Contrast Algorithm) to ensure real-world readability based on font weight, size, and background context.
• token color-focus-ring maps to a 2px solid brand-500 line with 2px offset, satisfying the WCAG 2.2 focus appearance criteria.
• rule All interactive components expose :focus-visible via focus-ring token. Tab order strictly follows the semantic DOM tree.
• never Override focus-visible with outline: none without providing a token-bound focus indicator.