# Web Styling Design Tokens > Design token architecture - primitive/semantic/component tiers, naming grammar, CSS custom property delivery, and DTCG build pipelines - Skill: `agents-inc/web-styling-design-tokens` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add agents-inc/web-styling-design-tokens` - Raw SKILL.md: https://api.skillmd.com/api/skills/agents-inc/web-styling-design-tokens/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: agents-inc (https://skillmd.com/u/agents-inc) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/agents-inc/web-styling-design-tokens --- # Design Token Patterns > **Quick Guide:** A token system is a one-way dependency graph — primitives hold raw values, semantic tokens name intent, component tokens hold local exceptions, and consumers only ever touch the top two tiers. Deliver tokens as CSS custom properties: primitives in `:root`, semantic aliases reassigned per scope, component tokens on the component's own selector. Name a token for its **role**, never for the mode it happens to appear in (`--color-surface-raised`, never `--color-dark-bg`). Store complete colour values rather than bare channel triplets. Where tokens must exist in more than one language, generate every output from one DTCG source. **Detailed Resources:** - [examples/core.md](examples/core.md) — tier construction, aliasing, naming grammar, custom property delivery, `@property` registration - [examples/scales.md](examples/scales.md) — generated spacing and type series, modular scales, fluid type, density multipliers - [examples/pipeline.md](examples/pipeline.md) — DTCG source files, build platforms, typed TypeScript export, publishing outside the owning repository - [examples/utility-framework-bridge.md](examples/utility-framework-bridge.md) — projecting tokens into a layer that generates utility classes - [reference.md](reference.md) — naming grammar table, DTCG `$type` reference, build config shape, authoring checklist --- ## Which path applies - **Tokens live only in this repository and are only ever read from CSS** — hand-write the custom properties. Follow [examples/core.md](examples/core.md) and [examples/scales.md](examples/scales.md); a build step producing one file nobody else reads is cost with no payoff. - **Tokens must exist in a second language or platform, or ship outside the repository that owns them** — author a DTCG source and generate every output from it. Follow [examples/pipeline.md](examples/pipeline.md); the tiers and names are identical, the source is JSON instead of CSS. --- ## Before writing design token code **Route every component style through a semantic or component token.** A component that reads a primitive or a raw literal has bypassed the indirection layer, so a rebrand has to visit it individually. **Name tokens for their role.** `--color-surface-raised` stays true in every mode; `--color-dark-bg` is only true in one, and every additional mode forks the name and every consumer. **Store complete colour values.** A bare channel triplet (`0 0% 100%`) is not a colour, so `color-mix()`, `oklch()` interpolation and every opacity modifier produce invalid CSS that is dropped rather than reported. **Keep the dependency flow one-way: primitive → semantic → component.** A primitive that references a semantic token has inverted the graph and made the palette un-regenerable; a cycle resolves to nothing at runtime. **Generate every additional output from one source once tokens exist in more than one language.** A TypeScript constant maintained beside a CSS variable drifts on the first edit made in only one of them, and nothing fails loudly. --- **Auto-detection:** design tokens, primitive tokens, semantic tokens, component tokens, token tiers, token aliasing, DTCG, Design Tokens Community Group, `$value`, `$type`, Style Dictionary, `transformGroup`, `buildPath`, `css/variables`, `outputReferences`, `@property`, `--color-`, `--space-`, modular scale, density tokens **Applies to:** - Standing up the token layer a design system sits 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 custom properties with correct scoping - Building tokens from a DTCG source into CSS, TypeScript, or other platform outputs - Generating spacing and type series rather than hand-listing every step - Auditing an existing set for tier leaks, mode-named tokens, or drift between languages **Handled elsewhere:** - Runtime mode selection — how a theme is chosen, persisted and applied without a flash of the wrong one. This skill defines the token _contract_ those mechanics switch between - Writing markup against generated utility classes — this skill covers where tokens are _declared_, not how a generated class is _used_ - Mapping component props to class combinations — a variant API consumes component tokens and defines none - A project with a handful of colours and no theming ambition — a short `:root` block is the right amount of structure, and tiers would be indirection nobody reads --- A token system is not a list of values. It is a one-way dependency graph with a naming contract, and its purpose is to put a layer of indirection between what a value _is_ and what a value _means_, so the two can change independently. The three tiers separate three kinds of change: | Tier | Answers | Changes when | Who reads it | | ------------- | ---------------------------- | ------------------------------------- | -------------------------------- | | **Primitive** | "What is this value?" | The palette or scale is regenerated | Semantic tokens only | | **Semantic** | "What is this value _for_?" | The design language shifts, or a mode | Components, and component tokens | | **Component** | "What does _this part_ use?" | One component needs a local exception | That component only | - **Consumers touch semantics, never primitives.** `background: var(--color-surface-raised)` survives a rebrand; `var(--color-gray-100)` does not. - **Every tier is indirection paid for on every read.** Three is the ceiling, not the target — component tokens are exceptions rather than a mirror of the component tree. - **The token set is the contract; the delivery format is an implementation detail.** Custom properties, a typed TypeScript object and a native platform file are three renderings of one graph, which is exactly why they are generated rather than typed twice. **A value used in one place still deserves a semantic token** when the question "will everyone using this want it to change together?" has the answer yes. A token is a statement that a set of usages share a fate. **Two tiers suffice** for a single brand, a single mode and no white-labelling: components read semantics directly. --- ## Core patterns ### Pattern 1: Token tiers and the one-way graph Primitives are the only tier holding literals. Semantic tokens alias primitives and name intent. Component tokens alias semantics and exist only where a component diverges. ```css :root { /* Tier 1 — 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 — names intent, aliases a primitive */ --color-surface-default: var(--palette-slate-50); --color-text-default: var(--palette-slate-900); /* Tier 3 — a local exception, aliases a semantic */ --card-surface: var(--color-surface-default); } ``` A primitive references nothing, a semantic holds no literal, and a component token never reaches past the semantic tier. Cycles are a hard error in every conforming pipeline; in hand-written CSS they resolve to nothing at runtime. A component token that overrides nothing anywhere is indirection earning nothing — delete it and read the semantic directly. Full code: [examples/core.md](examples/core.md#pattern-1-token-tiers-and-the-one-way-graph) --- ### Pattern 2: Naming grammar A name is a path read left to right, general to specific. Fix the segment order once and every name becomes predictable. ``` [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) ``` Category first so tokens sort into groups; state always last so `-hover` and `-pressed` read consistently; an absent segment means "default". The mode belongs in the _scope that assigns the value_, never in the identifier: ```css --color-surface-default: var(--palette-slate-50); [data-theme="dark"] { --color-surface-default: var(--palette-slate-900); } ``` Numeric steps (`50`–`950`) suit primitive ramps where the number is a real position; t-shirt sizes (`xs`–`xl`) suit semantic steps where a number would imply arithmetic that does not hold. One convention per namespace. Full code: [examples/core.md](examples/core.md#pattern-2-naming-grammar) --- ### Pattern 3: CSS custom properties as the delivery format Custom properties are the delivery format because they participate in the cascade — reassigning a semantic token inside a scope re-themes every descendant with no rebuild and no re-render. ```css :root { --palette-blue-600: oklch(0.55 0.19 258); --color-action-default: var(--palette-blue-600); /* semantic 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 a semantic */ padding: var(--card-padding); } ``` Primitives live in `:root` and are never reassigned. Semantic tokens are the only tier a scope selector touches. Component tokens are declared on the component's own selector, so they inherit into its subtree and nowhere else. **Register a token with `@property`** when it is animated, or when unintended inheritance would be a bug. `syntax` and `inherits` are both required descriptors, and `initial-value` is required for any `syntax` other than `*`: ```css @property --card-elevation-alpha { syntax: ""; inherits: false; initial-value: 0%; } ``` Registration buys typed interpolation — an unregistered custom property cannot be transitioned — plus a fallback to `initial-value` instead of an inherited garbage value. It costs a declaration per token, so register the animated and the leak-prone ones rather than the whole set. Full code: [examples/core.md](examples/core.md#pattern-3-css-custom-properties-as-delivery) --- ### Pattern 4: Projecting tokens into a generated-class layer Where something generates classes from a theme surface, that surface is a **projection** of the token set rather than a second place values are typed. Three decisions make the projection safe, and they hold whatever generates the classes: ```css /* 1. The tokens. Literal values and every mode swap live here. */ :root { --app-canvas: oklch(0.98 0.003 250); } [data-theme="dark"] { --app-canvas: oklch(0.21 0.02 250); } /* 2. The theme surface aliases them — one entry per token that should become a class. Nothing is re-typed. */ ``` - **Alias, never redeclare.** A value written in both places drifts on the first edit that lands in one of them, and the mismatch surfaces as a subtle colour difference no checker catches. - **Project only what should become a class.** Internal plumbing — a focus-ring width, an interaction duration — stays in `:root` and is read directly, so the generated surface stays to things anyone would write in markup. - **Replace the generator's default palette rather than extending it.** Defaults left in place are an untracked parallel token set, and every default colour class is a value that bypasses the semantic tier. Full code: [examples/utility-framework-bridge.md](examples/utility-framework-bridge.md) --- ### Pattern 5: DTCG source and a build pipeline Source lives in DTCG format (`$value` / `$type` / `$description`, `{alias}` references), and every output — CSS, typed TypeScript, native files — is generated from it. ```json { "color": { "$type": "color", "palette": { "slate-50": { "$value": "#f8fafc" } }, "surface": { "default": { "$value": "{color.palette.slate-50}", "$description": "Page background in the default mode" } } } } ``` ```javascript // 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` hoists to the closest ancestor group that declares it, so declare it once per group. A `{group.token}` alias always resolves to a whole `$value` — property-level access needs JSON Pointer (`#/color/blue/$value`). DTCG (`$value`) and the original format (`value`) cannot be combined in one instance. `outputReferences: true` is what keeps `var()` aliasing in the CSS output instead of flattening every semantic token to a literal. Full code: [examples/pipeline.md](examples/pipeline.md) --- ### Pattern 6: Scales as generated series Spacing and type are series, not sets. Express the generator — a base and a ratio, or a base and a multiplier — so every step is derivable and no step can be individually wrong. ```css :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); } ``` **Density is a multiplier on the semantic tier, not a second scale.** Applied where primitives become semantics, one token re-scales the system and component tokens inherit density for free: ```css :root { --density-scale: 1; --space-inline-md: calc(var(--space-4) * var(--density-scale)); } [data-density="compact"] { --density-scale: 0.75; } ``` Type scales take the same shape with a ratio in place of the multiplier, and fluid steps use `clamp()` with both bounds derived from the scale rather than hand-picked. A `calc()` chain much past three levels becomes hard to debug — resolve those in the pipeline instead. Full code: [examples/scales.md](examples/scales.md) --- ## Decision framework ### How many tiers? ``` Does the product need more than one visual mode, brand, or tenant? |-- NO --> Does any component need a value that diverges from the system default? | |-- NO --> Two tiers: primitive + semantic | |-- YES --> Two tiers, plus component tokens for the divergent components only |-- YES --> Three tiers. Semantic tokens are the swap point; primitives never move. ``` ### Which tier does this value belong to? ``` Is it a literal (a hex, a rem, a ms)? |-- YES --> Primitive. It gets a position-in-a-ramp name, not a meaning name. |-- NO --> Does more than one component share this decision? |-- YES --> Semantic. Name the role. |-- NO --> Is the component genuinely diverging, or just the only current user? |-- Diverging --> Component token |-- Only user --> Semantic. One user today is still a shared decision tomorrow. ``` ### Where does this token get declared? ``` Is it a primitive? |-- YES --> :root, once, never reassigned |-- NO --> Does it change per mode, density, or tenant? |-- YES --> :root for the default, reassigned on the scope selector |-- NO --> Is it local to one component? |-- YES --> On the component's own selector |-- NO --> :root alongside the other semantics ``` --- ## Red flags **Breaks at runtime:** - **Channel triplets as token values** (`--color-surface: 0 0% 100%`) — not a colour, so `color-mix()`, `oklch()` interpolation and every opacity modifier produce invalid CSS that is silently dropped. Store complete colour values. - **An inverted or cyclic graph** — a primitive referencing a semantic, or two tokens aliasing each other. Pipelines error on cycles; hand-written CSS resolves to nothing and the declaration disappears. - **A `@property` rule missing `syntax` or `inherits`** — the whole rule is invalid and ignored, so the property stays unregistered and the transition that depended on it does nothing. - **`initial-value` that is not computationally independent** (`3em`) — same outcome: the rule is dropped whole with nothing in the console. - **Fallbacks in consumers** (`var(--color-surface, #fff)`) — hides a missing token behind a plausible value, so the bug ships looking almost right. **Costs a rebrand:** - **A component reading a primitive** (`background: var(--palette-slate-100)`) — the indirection layer is bypassed, so a palette change has to visit every component instead of one semantic file. - **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 name** (`--color-dark-bg`, `--text-light-muted`) — the token count multiplies by the number of modes and every consumer needs a conditional. Reassign one role-named token per scope. - **Semantic names that describe appearance** (`--color-blue-action`) — half a semantic token. The role survives a rebrand; the colour word becomes a lie. - **Parallel hand-maintained copies** in TypeScript and CSS — they drift on the first one-sided change and nothing fails. - **Skipping `outputReferences` in a generated CSS platform** — every semantic token flattens to a literal, so the aliasing the tiers were built for disappears from the output. **Surprising behaviour:** - **Custom properties inherit by default**, so a component token declared on a component selector reaches every descendant including slotted children. `inherits: false` via `@property` is the fix where that matters. - **`CSS.registerProperty()` takes precedence over `@property`** for the same name, so a stray JS registration silently overrides the stylesheet. - **`calc()` chains through several tiers resolve at use time**, so a unit error three aliases up surfaces as a dropped declaration at the consumer with no indication of which link broke. - **DTCG `{alias}` always resolves to a complete `$value`.** Reaching into part of a composite needs JSON Pointer; referencing a group is an error. - **`$type` flows from the closest ancestor group that declares it**, and a node must never carry 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 paths, so a name containing one produces an unresolvable reference. - **Mixing DTCG (`$value`) with the original format (`value`) in one instance** makes the unrecognised half read as plain groups, so a half-finished migration looks like tokens that simply vanished. **Sprawl:** - **Token-per-usage** (`--button-primary-hover-icon-margin-left`) — a token per property per element is a stylesheet with extra steps. Tokens encode shared decisions; a value shared with nothing is just a value. - **A component tier mirroring the component tree** — component tokens are exceptions, not coverage. - **Mixed scale conventions in one namespace** (`--space-sm` beside `--space-400`) — every lookup becomes a guess about which convention applies. - **Density as a second spacing scale** rather than a multiplier applied where primitives become semantics — the token count multiplies by the number of density levels and every component gains a branch.