Naming
The naming grammar for semantic and component tokens, the rules that keep it consistent, and the scales in use.
Read more
Search
Search
Framework-agnostic primitive and semantic design tokens, authored in DTCG JSON and shipped as CSS custom properties.
Design tokens are the atomic decisions of a design system: colors, spacing, typography, motion. Instead of hardcoding #ae003f or 1rem throughout a codebase, you name the decision, --color-brand or --spacing-md, and reference that name everywhere.
@uncinq/design-tokens holds the primitive and semantic layers of that vocabulary. It is authored in DTCG JSON and compiled to CSS custom properties by Style Dictionary. It works anywhere CSS does: Hugo, Symfony, Shopify, or a plain HTML page.
The package follows the DTCG three-layer model.
primitive → semantic → component
(raw values) (purpose) (component-scoped, not in this package)
Raw, context-free values. No opinion about where they are used.
--color-indigo-600: oklch(0.511 0.262 276.966);
--size-16: 1rem;
--font-weight-bold: 700;
A primitive token answers “what is the value?”.
Named by purpose rather than by appearance. References a primitive through var().
--color-brand: var(--color-sienna-600);
--spacing-md: var(--size-30);
--font-weight-heading: var(--font-weight-bold);
A semantic token answers “what is this value for?”.
This is the layer that gives portability. Every project consuming this package shares the same semantic API, so when the brand color changes you update one primitive and every semantic token referencing it follows.
Scoped to a single component. The generic ones live in @uncinq/component-tokens; project-specific ones belong in each project’s own design system.
--alert-border-radius: var(--radius-none);
--btn-padding-inline: var(--spacing-control);
npm install @uncinq/design-tokens
/* everything */
@import '@uncinq/design-tokens';
/* or by layer */
@import '@uncinq/design-tokens/css/primitive.css';
@import '@uncinq/design-tokens/css/semantic.css';
/* or file by file */
@import '@uncinq/design-tokens/css/semantic/color.css';
Without a build step, over a CDN:
<link rel="stylesheet" href="https://unpkg.com/@uncinq/design-tokens">
Every generated file declares @layer tokens itself, so the package never fixes the layer order. Declaring that order is the consuming project’s job, and it has to happen before any import. See cascade layers in css-base.
| Page | Covers |
|---|---|
| Naming | The naming grammar, the rules, the scales, the full category list |
| Colors | OKLCH, the primitive palette, semantic color roles, WCAG guidance |
| Dark mode | How the dark theme overlay works and how to opt out |
| Customizing | The two override strategies and when each applies |
| Reference | Every token, generated from the JSON sources |
| DTCG format | The authoring format |
| Style Dictionary | The build pipeline |
| Fluid scales | The Utopia method behind the fluid tokens |
The JSON sources under tokens/ are the only files to edit. Everything under dist/ is generated by npm run build.
tokens/
primitive/ blur, color, font, shadow, size
semantic/ blur, border, color, focus, form, gradient, grid, icon,
motion, opacity, radius, ratio, shadow, size, spacing,
typography, z-index
themes/ dark
dist/css/
index.css imports primitive, semantic, themes/dark
primitive.css barrel
semantic.css barrel
primitive/ semantic/ themes/ one CSS file per JSON source