Tokens

Design tokens

A canonical, versioned decision system that keeps design and code consistent across themes, platforms, components, and releases.

W3C DTCG JSON13 categories4 resolution layersWeb + Flutter + Figma + MCP

Introduction

Design tokens are the source of truth for visual and behavioral decisions. They replace repeated literal values with stable, meaningful names that can be validated, transformed, distributed, and consumed across design and engineering platforms.

Use a token whenever a decision must remain consistent across components, themes, platforms, or releases. A published token path is an API contract, not merely a variable.

Installation

Web

@import '@design-system/web/tokens.css';

.surface {
  color: var(--ds-color-text-primary);
  background: var(--ds-color-surface-primary);
}

Flutter

import 'package:design_system/
  design_system.dart';

final color = DsColor.of(context).textPrimary;

Import generated outputs through the package entry points. Never edit generated CSS, JavaScript, Dart, or Figma artifacts directly.

Types of Tokens

Tokens resolve through four layers. Each layer narrows context while preserving a traceable alias chain.

global

Global tokens

Context-neutral source values that establish the visual vocabulary.

color.neutral.900Other tokens; direct product use is restricted to low-level foundation work.

semantic

Semantic tokens

Intent-based aliases whose meaning remains stable across themes.

color.text.primaryApplication layouts, content, and reusable patterns.

component

Component tokens

Scoped aliases that connect semantic decisions to a governed component contract.

component.button.primary.backgroundDesign-system component implementations only.

instance

Instance tokens

A resolved value consumed by a specific interface instance.

var(--he-component-button-primary-background)Runtime output; instances do not introduce new token definitions.

Consumption rule

Product composition uses semantic tokens. Governed component implementations use component tokens. Global tokens primarily feed aliases, and instance values do not create a new token definition.

Token Categories

Each category owns one kind of decision and declares its DTCG type. Category-specific foundation guidance defines selection, composition, and testing.

Color

color

Primitive ramps, semantic surfaces, text, actions, status, focus, and data encodings.

Typography

fontFamily, fontWeight, dimension, number

Families, sizes, weights, line heights, letter spacing, and text roles.

Space

dimension

Inner padding, outer margin, layout gaps, and flow rhythm.

Size

dimension

Controls, icons, targets, containers, and other governed dimensions.

Border

dimension and color

Border widths, focus geometry, and semantic edge color.

Radius

dimension

Corner geometry from square through fully rounded.

Shadow

shadow

Governed elevation and separation without structural ambiguity.

Opacity

number

Disabled, scrim, overlay, and subtle presentation states.

Motion

duration and cubicBezier

Feedback durations and easing curves with reduced-motion handling.

Breakpoint

dimension

Content-driven responsive thresholds and media-query aliases.

Layout

dimension

Maximum measures, gutters, and structural layout dimensions.

Z-index

number

Named stacking layers for predictable overlap.

Icon

dimension and color

Governed icon optical sizes and semantic colors.

Complete reference

The first 10 sections mirror the reference information architecture. Motion, Z-index, and All tokens are transparent system extensions, not reference categories.

Why Tokens Are Required

Consistency

One named decision replaces repeated literals and keeps design and implementation aligned.

Change propagation

An accessibility or brand improvement can update every valid consumer through one reviewed source change.

Cross-platform parity

Web, Flutter, Figma, and agent tooling receive equivalent decisions from the same canonical source.

Tokens and the Design System

The build is deterministic: canonical sources are validated, aliases are resolved, and platform outputs are regenerated from a clean checkout.

1
AuthorW3C DTCG JSONEdit canonical source files only.
2
ValidateSchema, reference, type, and accessibility checksReject unknown, circular, invalid, or inaccessible decisions.
3
TransformResolved platform dictionariesResolve aliases without changing semantic paths.
4
DistributeCSS, JavaScript, Flutter, and Figma outputsGenerated files are reproducible and are never edited directly.
5
ConsumeComponents and product interfacesConsume semantic or component roles instead of literals.

Naming Tokens

Names proceed from general to specific using category.role.variant.state.scale. JSON paths use camel case and generated CSS custom properties use kebab case. Names describe stable purpose rather than the current literal value.

Generalcolor→action→primary→hoverSpecific

Name tokens by purpose rather than their current literal value.
Keep semantic paths stable when a theme changes the resolved value.
Use state suffixes such as hover, active, selected, disabled, and focus only when the state has a distinct decision.
Do not encode a platform, page, team, or temporary implementation detail in a canonical token name.

Aliases

Aliases preserve intent while underlying values change. Semantic aliases may reference globals; component aliases may reference semantic tokens. Application code must not bypass the alias chain when an appropriate role exists.

color.atlantic.600global→color.action.primary.backgroundsemantic→component.button.primary.backgroundcomponent

Themes

Atlantic and Pasture expose identical semantic paths. Theme selection changes alias resolution, never anatomy, hierarchy, behavior, or accessibility requirements.

Atlantic

Same semantic contractcolor.surface.primary

Pasture

Same semantic contractcolor.surface.primary

Architectural Integration

Platform	Canonical output	Usage
Web	`packages/web/health-eye-tokens.css`	Import the CSS once at the application root and consume custom properties through semantic or component aliases.
Flutter	`packages/flutter/lib/src/generated/he_tokens.g.dart`	Consume generated constants and theme extensions; preserve logical text scaling and platform density behavior.
Figma	`dist/figma/health-eye.tokens-studio.json`	Import generated token sets and select exactly one semantic expression with the global and component sets.

Governance and Versioning

Canonical .tokens.json files are the source of truth. Every addition receives semantic and accessibility review. Removing or renaming a published path requires a migration alias, a deprecation window, release notes, regenerated artifacts, and cross-platform validation.

Do

Use semantic or component roles at the appropriate layer.
Name tokens by stable intent.
Validate every theme, state, and platform.
Add missing decisions through the governed source.

Don't

Do not introduce raw values when a canonical role exists.
Do not name tokens after current literals.
Do not edit generated artifacts.
Do not remove a path without migration.

Accessibility

Token changes preserve WCAG 2.2 AA contrast across expressions and states, support 200% text scaling and 320 CSS pixel reflow, retain structure in forced-colors mode, and honor reduced-motion preferences. Color, opacity, motion, and elevation never carry essential meaning alone.

MCP Server Context

Resolve the canonical token layer before generating UI: prefer component tokens inside governed components and semantic tokens in product composition; never emit raw values when a canonical role exists. Follow the general-to-specific naming grammar, preserve aliases across Atlantic and Pasture, and treat every published token path as a versioned API. When a required decision is absent, report the gap and propose a token addition through governance instead of inventing an arbitrary local value.