Quick Guide: A design token system is a one-way dependency graph: primitives hold raw values, semantic tokens name intent, component tokens hold local exceptions. Consumers only ever touch the top two tiers. Deliver tokens as CSS custom properties -- primitives in

:root

, semantic aliases per scope, component tokens reading semantics. Name tokens for their role, never for the mode they happen to appear in (

--color-surface-raised

, never

--color-dark-bg

). Store complete color values, never bare channel triplets. When tokens must exist in more than one language, generate every output from one DTCG source rather than hand-maintaining parallel copies.

• examples/core.md - Tier construction, aliasing, naming grammar, CSS custom property delivery,

  @property

  registration
• examples/scales.md - Generated spacing and type series, modular scales, fluid type, density multipliers
• examples/pipeline.md - DTCG source files, Style Dictionary platforms, typed TypeScript export
• examples/utility-framework-bridge.md - Feeding tokens into a utility-class framework without duplicating the source of truth
• reference.md - Naming grammar table, DTCG

  $type

  reference, format names, authoring checklist

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,

import type

, named constants)

--color-surface-raised

--color-dark-bg

--color-gray-900-bg

0 0% 100%

color-mix()

oklch()

$value

$type

transformGroup

buildPath

css/variables

--color-

@property

• Standing up the token layer a design system will sit on
• Deciding how many tiers a token set needs and what belongs in each
• Naming tokens so they survive a rebrand, a new mode, or a density change
• Delivering tokens as CSS custom properties with correct scoping
• Building tokens from a DTCG source into CSS, TypeScript, or other platform outputs
• Generating spacing and type series instead of hand-listing every step
• Auditing an existing token set for tier leaks, mode-named tokens, or drift between languages

• A project with a handful of colors and no theming ambitions -- a short

  :root

  block is the right amount of structure
• A single-surface prototype that will not outlive the sprint
• A codebase whose values are already fully derived from an upstream system you do not own

• Runtime theme application, mode switching, and FOUC prevention -- how a theme gets selected, persisted, and applied without a flash is a separate concern (

  web-styling-theming

  ). This skill defines the token contract those mechanics switch between.
• Utility-class authoring and usage -- writing markup with utility classes, variants, and responsive prefixes (

  web-styling-tailwind

  ). This skill covers where tokens are declared; that skill covers how the generated classes are used.
• Component variant APIs -- mapping props to class combinations (

  web-styling-cva

  ). Variants consume component tokens; they do not define them.

• Token tiers: primitive -> semantic -> component, and when two tiers are enough
• Naming grammar: category-property-variant-state, scale conventions, mode-free names
• CSS custom properties as the delivery format, with scope-aware semantic aliases

• @property

  registration where typed, animatable, non-inherited tokens earn it
• Feeding tokens into a utility-class framework without forking the source of truth
• DTCG-format source plus a build pipeline producing CSS and typed TypeScript
• Scales as generated series, and density as a multiplier token

• One-way flow. Primitive -> semantic -> component. A primitive that references a semantic token has inverted the graph and made the palette un-regenerable.
• Consumers touch semantics, never primitives.

  background: var(--color-surface-raised)

  survives a rebrand.

  background: var(--color-gray-100)

  does not.
• Names encode role, not appearance, and never mode. The moment a token is called

  --color-dark-bg

  , it can only ever be correct in one mode, and every additional mode forks the name.
• Every tier you add is indirection you pay for on every read. Three tiers is the ceiling, not the target. Component tokens are exceptions, not a mirror of the component tree.
• The token set is the contract; the delivery format is an implementation detail. CSS custom properties, a typed TypeScript object, and a native platform file are three renderings of the same graph -- which is exactly why they must be generated, not typed twice.

:root {
  /* Tier 1 - primitives: literal values, no meaning attached */
  --palette-slate-50: oklch(0.98 0.003 250);
  --palette-slate-900: oklch(0.21 0.02 250);

  /* Tier 2 - semantic: names intent, aliases a primitive */
  --color-surface-default: var(--palette-slate-50);
  --color-text-default: var(--palette-slate-900);

  /* Tier 3 - component: a local exception, aliases a semantic */
  --card-surface: var(--color-surface-default);
}

--card-surface: var(--color-surface-default)

See examples/core.md for a full three-tier set, the two-tier collapse, and the inverted-graph anti-pattern.

[namespace-]category-concept[-variant][-state][-scale]

--color-text-default            category=color  concept=text   variant=default
--color-text-danger-hover       + variant=danger + state=hover
--space-inline-sm               category=space  concept=inline scale=sm
--acme-color-surface-raised     namespace=acme (only when tokens ship outside the app)

-hover

-pressed

--color-dark-bg

/* Bad - the name is only true in one mode */
--color-dark-bg: oklch(0.21 0.02 250);

/* Good - one name, value reassigned per scope */
--color-surface-default: var(--palette-slate-50);
[data-theme="dark"] {
  --color-surface-default: var(--palette-slate-900);
}

50

950

xs

xl

See examples/core.md for the full segment table, scale conventions, and the mode-in-name refactor.

:root {
  --palette-blue-600: oklch(0.55 0.19 258);
  --color-action-default: var(
    --palette-blue-600
  ); /* semantic, global default */
}

/* A scope reassigns semantics; primitives never move */
[data-density="compact"] {
  --space-inline-md: var(--space-2);
}

.card {
  --card-padding: var(--space-inline-md); /* component token reads semantic */
  padding: var(--card-padding);
}

:root

var(--color-x, #fff)

@property

syntax

inherits

initial-value

syntax

*

@property --card-elevation-alpha {
  syntax: "<percentage>";
  inherits: false;
  initial-value: 0%;
}

initial-value

See examples/core.md for scoping rules, inheritance traps, and

@property

registration in full.

@theme

@theme inline

@import "tailwindcss";

/* 1. Real tokens live here, mode-swappable, framework-agnostic */
:root {
  --app-canvas: oklch(0.98 0.003 250);
}
[data-theme="dark"] {
  --app-canvas: oklch(0.21 0.02 250);
}

/* 2. Projection - the framework consumes tokens, it does not define them */
@theme inline {
  --color-canvas: var(--app-canvas);
}

@theme

:root

[data-theme]

@theme

inline

@theme

:root

color-mix(in oklab, var(--color-canvas) 50%, transparent)

0 0% 100%

See examples/utility-framework-bridge.md for the full bridge, namespace resets, and the duplicated-source-of-truth anti-pattern.

$value

$type

$description

{alias}

{
  "color": {
    "$type": "color",
    "palette": { "slate-50": { "$value": "#f8fafc" } },
    "surface": {
      "default": {
        "$value": "{color.palette.slate-50}",
        "$description": "Page background in the default mode"
      }
    }
  }
}

// style-dictionary config: one source, many platforms
export const config = {
  source: ["tokens/**/*.json"],
  platforms: {
    css: {
      transformGroup: "css",
      buildPath: "build/css/", // trailing slash is required
      files: [
        {
          destination: "tokens.css",
          format: "css/variables",
          options: { outputReferences: true }, // preserves var() aliasing
        },
      ],
    },
    ts: {
      transformGroup: "js",
      buildPath: "build/ts/",
      files: [{ destination: "tokens.ts", format: "javascript/es6" }],
    },
  },
};

$type

{group.token}

$value

#/color/blue/$value

$value

value

outputReferences: true

var()

See examples/pipeline.md for the full DTCG source tree, platform configs, typed TypeScript export, and the drift anti-pattern.

:root {
  --space-base: 0.25rem;
  --space-1: calc(var(--space-base) * 1);
  --space-2: calc(var(--space-base) * 2);
  --space-4: calc(var(--space-base) * 4);
  --space-8: calc(var(--space-base) * 8);
}

:root {
  --density-scale: 1;
}
[data-density="compact"] {
  --density-scale: 0.75;
}

:root {
  --space-inline-md: calc(var(--space-4) * var(--density-scale));
}

clamp()

calc()

See examples/scales.md for modular type scales, fluid

clamp()

steps, density multipliers, and generated-vs-hand-listed comparisons.

• A component reading a primitive (

  background: var(--palette-slate-100)

  ) -- the indirection layer is bypassed, so a rebrand has to touch every component instead of one semantic file. Alias a semantic token and use that.
• Hex or px literals in component CSS -- an untracked token. It will not move with the system, will not respond to a mode change, and will not appear in any audit.
• Mode baked into the token name (

  --color-dark-bg

  ,

  --text-light-muted

  ) -- the name is only true in one mode, so every additional mode forks the name and every consumer needs a conditional. Reassign one role-named token per scope instead.
• Channel triplets as token values (

  --color-surface: 0 0% 100%

  ) -- not a color, so

  color-mix()

  ,

  oklch()

  interpolation, and every opacity modifier produce invalid CSS that silently drops the declaration. Store complete color values.
• TypeScript constants and CSS variables maintained side by side -- they drift on the first change made in only one of them, and nothing fails loudly. Generate both from one source or keep only one.
• An inverted or cyclic graph -- a primitive referencing a semantic token, or two tokens aliasing each other. Conforming pipelines error on cycles; hand-written CSS just resolves to nothing at runtime.

• Token-per-usage sprawl (

  --button-primary-hover-icon-margin-left

  ) -- a token per property per element is a stylesheet with extra steps. Tokens encode shared decisions; a value used in exactly one declaration and shared with nothing is just a value.
• A component tier that mirrors the component tree -- component tokens are exceptions, not coverage. A pass-through token that overrides nothing anywhere is indirection with no payoff.
• Fallbacks in consumers (

  var(--color-surface, #fff)

  ) -- hides a missing token behind a plausible value, so the bug ships. Let it be visibly broken.
• Mixed scale conventions in one namespace (

  --space-sm

  beside

  --space-400

  ) -- callers cannot predict which convention a given name uses, so every lookup is a guess.
• Semantic names that describe appearance (

  --color-blue-action

  ) -- half a semantic token. The role survives a rebrand; the colour name does not.
• Skipping

  outputReferences

  in a generated CSS platform -- every semantic token flattens to a literal, so the aliasing that made the tier system worth building disappears from the output.

• Adding the component tier preemptively rather than at the first genuine divergence
• Regenerating a primitive ramp and expecting semantics to follow, when semantics hold literals instead of aliases
• Declaring

  $type

  on every token when it hoists from the closest ancestor group that declares it
• Naming a state segment somewhere other than last, so

  -hover-danger

  and

  -danger-hover

  both exist
• Treating density as a second spacing scale instead of a multiplier applied where primitives become semantics

• @theme

  cannot be nested under a selector or media query -- it is top-level only. Mode-swappable values therefore live in

  :root

  /

  [data-theme]

  , and only the alias goes in

  @theme inline

  . Omitting

  inline

  makes the generated utility resolve the reference at the wrong scope, and the mode swap fails silently rather than erroring.

• @property

  requires both

  syntax

  and

  inherits

  ; if either is missing the whole rule is invalid and ignored.

  initial-value

  is required for every

  syntax

  except

  *

  , and must be computationally independent --

  10px

  is valid,

  3em

  is not.
• An unregistered custom property cannot be transitioned or animated. It is treated as an untyped token and jumps between values. Registration is the only way to interpolate one.

• CSS.registerProperty()

  takes precedence over

  @property

  for the same name, so a stray JS registration silently overrides the stylesheet.
• DTCG

  {alias}

  syntax always resolves to a complete

  $value

  . Reaching into part of a composite token needs JSON Pointer (

  #/color/blue/$value

  ). Referencing a group rather than a token is an error in current tooling.
• DTCG (

  $value

  ) and the original format (

  value

  ) cannot be combined in one instance -- a half-migrated token tree fails in ways that look like missing tokens.

• $type

  inheritance flows from the closest ancestor group that declares it, and a group must never contain both

  $value

  and child tokens -- that shape is neither a group nor a token.
• Token names cannot start with

  $

  or contain

  {

  ,

  }

  , or

  .

  -- the period is reserved for alias path construction, so a name containing one produces an unresolvable reference.
• Custom properties inherit by default, so a component token declared on a component selector leaks into every descendant including slotted children.

  inherits: false

  via

  @property

  is the fix when that matters.

• calc()

  chains through several tiers resolve at use time, not at declaration time -- a unit error three aliases up surfaces as a silently dropped declaration at the consumer, with no indication of which link broke.

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,

import type

, named constants)

--color-surface-raised

--color-dark-bg

--color-gray-900-bg

0 0% 100%

color-mix()

oklch()