design-tokens on Socle

Naming

Mon, 01 Jan 0001 00:00:00 +0000

A token name is an API. Once a project references --color-text-muted, renaming it is a breaking change, so the grammar below is worth following closely.

Semantic tokens

--{category}-{subcategory?}-{variant?}-{state?}

Pattern	Example
`--{category}`	`--color`
`--{category}-{subcategory}`	`--color-text`
`--{category}-{subcategory}-{variant}`	`--color-text-muted`
`--{category}-{subcategory}-{state}`	`--color-text-disabled`

Component tokens

--{component}-{property}-{sub-property?}-{state?}

The property mirrors the CSS property name, so the token reads the same way as the declaration it controls. Colors are the exception: color leads and the role follows, for the reason given in the rules below.

Colors

Mon, 01 Jan 0001 00:00:00 +0000

Color space, OKLCH

Every primitive color is defined in OKLCH.

Channel	Range	Meaning
`L`	0 to 1	Perceptual lightness, 0 is black and 1 is white
`C`	0 to about 0.4	Chroma, or colorfulness, where 0 is gray
`H`	0 to 360 degrees	Hue angle

Why OKLCH rather than hex or HSL:

Perceptually uniform. Equal steps in L produce equal perceived brightness differences, whatever the hue. HSL does not guarantee this: hsl(60, 100%, 50%) yellow looks far brighter than hsl(240, 100%, 50%) blue at the same stated lightness.
Predictable contrast. You can reason about WCAG contrast by comparing L values, without converting to relative luminance first.
Better interpolation. Gradients and animations between two OKLCH colors do not pass through muddy grays.
Composable. The relative color syntax, oklch(from var(--color-text) l c h / 0.6), lets a token derive from another without duplicating its value. Several semantic tokens in this package rely on it.

Browser support is Chrome 111, Firefox 113 and Safari 15.4 and above. No sRGB fallback is generated, so every value ships as oklch() and anything older needs a fallback of its own.

Dark mode

Mon, 01 Jan 0001 00:00:00 +0000

The dark theme is an overlay, not a second palette. tokens/themes/dark.json re-declares 13 semantic tokens and nothing else. Every other token, including the whole primitive palette, is shared.

That is the point of the semantic layer: if a component reads --color-background rather than --color-white, it needs no dark-mode branch of its own.

What it overrides

Token	Light	Dark
`--color-background`	white	gray-950
`--color-background-disabled`	gray-100	gray-900
`--color-background-media`	gray-200	gray-800
`--color-background-muted`	gray-100	gray-900
`--color-background-muted-hover`	gray-200	gray-800
`--color-border`	gray-200	gray-800
`--color-heading`	black	white
`--color-shadow`	black	white
`--color-text`	gray-900	gray-200
`--color-text-disabled`	gray-300	gray-600
`--color-text-hover`	gray-700	gray-300
`--color-text-muted`	derived from `--color-text`	gray-400
`--form-color-background`	white	gray-900

Two of these do more work than they look. --color-shadow flipping to white inverts the entire shadow system in one line, because --color-shadow-light, -medium and -strong all derive from it with relative color syntax. And --color-background-surface is not in the list at all, because it aliases --color-background and follows for free.

Customizing

Mon, 01 Jan 0001 00:00:00 +0000

There are two ways to change what this package produces. Pick by how deep the change goes, not by preference.

Need	Approach
Change the brand, the typography, a handful of tokens	CSS `@layer tokens`
Add a few project-specific tokens	CSS `@layer tokens`
Redefine the primitive palette entirely	JSON plus build
Add many project tokens, or generate other formats	JSON plus build

1. CSS override

Every token lives in @layer tokens, the lowest-priority layer in the recommended order. Any @layer tokens block imported after this package wins on source order, with no specificity tricks required.

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Every table below is generated at build time from dist/tokens.json, which Style Dictionary produces from the same JSON sources as the CSS. Nothing here is written by hand, so a token cannot appear in the reference without existing in the package, or change value without the page changing with it.

Values are shown as they are emitted. A semantic token that references a primitive shows var(--the-primitive) rather than a flattened value, because that is literally what ships, and it is what makes an override of the primitive propagate.

DTCG format

Mon, 01 Jan 0001 00:00:00 +0000

The W3C Design Token Community Group (DTCG) defines a standard interchange format for design tokens, so they can travel between tools (Figma, code, documentation) without loss of meaning.

@uncinq/design-tokens uses DTCG JSON as its source format. Style Dictionary v5 transforms those JSON files into CSS custom properties — see STYLE-DICTIONARY.md for the build pipeline. The DTCG spec informs the architecture (primitive → semantic → component, naming conventions, token types).

The DTCG format

The DTCG spec defines tokens as JSON objects with reserved $-prefixed keys:

Style Dictionary

Mon, 01 Jan 0001 00:00:00 +0000

Style Dictionary v5 transforms the DTCG JSON token files into CSS custom properties.

Run the build

npm run build

Output is written to dist/css/. One CSS file is generated per JSON source file, preserving the same directory structure:

tokens/primitive/color.json → dist/css/primitive/color.css
tokens/semantic/color.json → dist/css/semantic/color.css

Config — `style-dictionary.config.js`

The config is a single ES module. It registers a custom name transform and a custom format, then maps every JSON file to a CSS output.

Fluid scales

Mon, 01 Jan 0001 00:00:00 +0000

Source: https://utopia.fyi

Principle

Each fluid token is a clamp() expression that scales linearly between a minimum and a maximum value, with no breakpoints.

property: clamp(min, intercept + slope × 1vw, max);

slope = (max_px − min_px) / (viewport_max − viewport_min)
intercept = min_px − slope × viewport_min (÷ 16 → rem)

Viewport range

All fluid tokens use the same viewport range: 375 px → 1440 px (range = 1065).

slope = (max_px − min_px) / 1065
intercept = min_px − slope × 375 (÷ 16 → rem)

This range covers modern phones (375 px) to wide desktop screens (1440 px). Tokens are clamped at both ends — below 375 px they stay at min, above 1440 px they stay at max.

design-tokens on Socle

Naming

Semantic tokens

Component tokens

Colors

Color space, OKLCH

Dark mode

What it overrides

Customizing

1. CSS override

Reference

DTCG format

The DTCG format

Style Dictionary

Run the build

Config — style-dictionary.config.js

Fluid scales

Principle

Viewport range

Config — `style-dictionary.config.js`