Naming
The component token naming grammar, the rules behind it, and why colors invert the usual property order.
Read more
Search
Search
Component-scoped CSS design tokens, layer 3 of the architecture, mapping semantic values onto the parts of a component.
Component tokens are CSS custom properties scoped to a single UI component. They sit at the top of the DTCG three-layer model.
primitive → semantic → component
(raw values) (purpose) (component-scoped)
Where primitive and semantic tokens come from @uncinq/design-tokens, component tokens map those semantic values onto specific parts of a component.
/* semantic token, from @uncinq/design-tokens */
--color-brand: var(--color-sienna-600);
/* component token, from this package */
--btn-color-background: var(--color-brand);
A component token answers “which semantic value does this part of this component use?”.
A component could read --color-brand directly. The extra hop buys two things.
A seam to override. A project can restyle buttons alone by setting --btn-color-background, without touching the brand color and therefore without moving every other branded element.
A place to record intent. --btn-color-text: var(--color-text-on-brand) documents that button text has to contrast against the brand color, which is an accessibility decision. Read directly, that decision would be invisible.
The rule that keeps the indirection honest: a component token always references a semantic token, never a raw value and never a primitive. When you find yourself wanting a raw value, the semantic layer is usually missing a token.
26 components, one JSON source and one generated CSS file each, 390 tokens in total.
alert | figure | map |
badge | heading | media |
breadcrumb | hero | modal |
button | item | nav |
card | items | pagination |
carousel | link | surtitle |
container | list | table |
details | logo | |
drawer | ||
dropdown | ||
embed |
card is an alias layer over item, which is the canonical card-like unit. See the Reference for what each one actually declares.
This package resolves its references against @uncinq/design-tokens, which must be imported first.
npm install @uncinq/design-tokens @uncinq/component-tokens
@import '@uncinq/design-tokens';
@import '@uncinq/component-tokens';
Per component, when you only need a few:
@import '@uncinq/design-tokens';
@import '@uncinq/component-tokens/css/components/button.css';
@import '@uncinq/component-tokens/css/components/badge.css';
Without a build step:
<link rel="stylesheet" href="https://unpkg.com/@uncinq/design-tokens">
<link rel="stylesheet" href="https://unpkg.com/@uncinq/component-tokens">
Import order matters here in a way it does not for most packages. These tokens are var() references, resolved by the browser at use time rather than at import time, so a missing design-tokens import does not error: it silently yields invalid values and unstyled components.
| Page | Covers |
|---|---|
| Naming | The naming grammar and the rules that keep it consistent |
| Customizing | Overriding a component token, and when to add one |
| Reference | Every token for all 26 components, generated from the sources |
| DTCG format | The authoring format, including group-level types |
| Style Dictionary | The build, and how cross-package references resolve |