How it fits together
One source of truth, in code: the token files, the CSS made from them, and the components that read it.
How it fits together
- Token files in
tokens/hold every value in the W3C Design Tokens format: primitives, then light and dark semantic files, then one file per extra brand. - A build step (
npm run tokens, also run before every dev and production build) turns them intosrc/styles/tokens.cssand a JSON file these pages read. - Components use the semantic CSS variables. Change a token, rebuild, and every page, example and table here follows.
There is no copy of a value anywhere else. The contrast table on Colour and the swatches throughout these pages are calculated from the same files as the live site.
In code
Import the generated stylesheet once, then refer to semantic tokens by name.
/* Generated from tokens/*.json: never edit by hand */
@import "./tokens.css";
.my-panel{
background: var(--somnia-color-surface-raised);
color: var(--somnia-color-text-primary);
border: 1px solid var(--somnia-color-border-subtle);
border-radius: var(--somnia-radius-card);
padding: var(--somnia-space-6);
} Light and dark come for free: the semantic variables change value when the visitor's system or the site setting switches theme. To force a theme or brand on part of a page, set an attribute on any element:
<section data-theme="dark">…</section>
<section data-brand="spotlight">…</section> Changing a token
Edit the JSON, not the CSS. Semantic tokens point at primitives with a reference in braces:
{
"color": {
"text": {
"secondary": { "$value": "{color.ink.600}" }
}
}
} The build stops with an error if a reference points at nothing, or if the light and dark files stop having the same names. Then check the contrast table and record the change in the changelog.
In design files
Somnia DS is code-first: the tokens and components in code are the source of truth, and there is no Figma library kept in step with them. When a project needs design files, the token JSON is in the W3C Design Tokens format, which a tokens plugin can bring into Figma as variables, with light, dark and each brand as modes. We set that up for the project. Use semantic variables in frames and components, never primitives, for the same reason as in code.
Naming
| Tier | Pattern | Example |
|---|---|---|
| Primitive | category, family, step | --somnia-color-ember-600 |
| Semantic | category, role, variant | --somnia-color-text-secondary |
| Short alias | the site's original names, kept so existing components keep working | --ink-soft |
The short aliases are a bridge, not a second system. New work uses the --somnia- names.