component-tokens on Socle

Naming

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

Every component token follows one pattern:

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

Pattern	Example
`--{component}`	`--btn`
`--{component}-{property}`	`--btn-padding-inline`
`--{component}-{property}-{sub-property}`	`--btn-color-text-decoration`
`--{component}-{property}-{state}`	`--btn-color-background-hover`

The property mirrors the CSS property name, so a token reads the same way as the declaration it controls. --btn-padding-inline drives padding-inline. Colors are the one exception, explained below.

Rules

Lowercase kebab-case, always.

Component name first: --btn-*, --badge-*, --hero-*. This is what makes the tokens greppable and what keeps them sorted together in the generated CSS.

Customizing

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

CSS override

Every token is declared in @layer tokens, the lowest-priority layer in the recommended order. Re-declare any of them in your own @layer tokens block after the import. Same layer, later source order wins, and no specificity escalation is needed.

@import '@uncinq/design-tokens';
@import '@uncinq/component-tokens';

@layer tokens {
 :root {
 --btn-color-background: var(--color-light);
 --btn-border-radius: 0;
 --hero-height: 80svh;
 }
}

Choosing the right layer to override

This is the decision that matters, and it is easy to get wrong in a way that only shows up later.

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 ship. A token that references a semantic token shows var(--the-semantic-token) rather than a resolved color or length, because that reference is what makes an override of the semantic layer propagate. See Style Dictionary for why the build keeps it that way.

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/components/. One CSS file is generated per JSON source file.

tokens/components/button.json → dist/css/components/button.css
tokens/components/badge.json → dist/css/components/badge.css

dist/css/index.css is auto-generated too, in a step that runs after Style Dictionary. It discovers the token files from disk, so adding a JSON source needs no manual edit anywhere. Each generated file declares its own @layer tokens, which is why a plain @import is enough and no layer() qualifier is used.