Tokens
Every visual decision in Semetrika is a CSS custom property. Colors, spacing, border-radius values, font families, line heights, transition durations - they all live as --* variables on :root. To re-theme the whole design system you load a second stylesheet after semetrika.min.css and override the tokens you care about.
Three tiers
Semetrika uses a three-tier model. Each tier references the one above it, and never skips a level:
Primitive tokens raw values --color-primary-5, --space-x-4, --font-size-md
↓
Foundation tokens shared --background-color-neutral, --component-padding-block-md
↓
Component tokens per-component --btn-background-color, --card-padding
Primitives are flat values on a defined scale. No var() references, no opinion about where they should be used. Examples: --space-x-4, --font-size-lg, --color-primary-5, --radius-md.
Foundation tokens are the shared UI decisions every component can start from. Two families live here. The element-facing families carry an emphasis tier (subtle, neutral, accent) or an intent (danger, info, success, warning): --text-color-neutral, --border-color-danger, --background-color-subtle. Alongside them sits the reserved --component-* family - the conventional value for a capability, so a size or a shape always has something to fall back to: --component-padding-block-md, --component-font-size-lg, --component-radius-pill.
Component tokens live in the component's own file and carry only what that component decides for itself: --btn-background-color, --card-padding, --modal-backdrop-background-color.
Components consume foundation and component tokens, never primitives directly. Swap a primitive (say --color-primary-5) and every token that references it cascades automatically.
How a component token resolves
A component slot names its own per-value token first and the foundation token as the fallback, so the foundation supplies the conventional value until the component overrides it:
--btn-background-color: var(--btn-neutral-background-color, var(--background-color-neutral));
--btn-neutral-background-color is undeclared by default, so a plain button resolves straight through to --background-color-neutral. A component only declares the per-value token where it genuinely deviates, which is why button.variables.css is ten declarations rather than a hundred. As a consumer you can override at any point in that chain: the primitive to move the whole palette, the foundation token to restyle every component at once, or the component token to change buttons alone.
Override on :root
Load a second stylesheet after Semetrika's CSS. Override the tokens you care about on :root:
<link rel="stylesheet" href="semetrika.min.css" /> <link rel="stylesheet" href="my-variables.css" />
/* my-variables.css */
:root {
/* Override a primitive - cascades through every semantic token that references it */
--color-primary-5: #ff6b00;
--radius-md: 12px;
--font-family-primary: 'Inter', sans-serif;
/* Or override a foundation or component token directly */
--background-color-neutral: #fafafa;
--btn-background-color: #ff6b00;
}
/* Optional: dark-scheme overrides */
:root[data-color-scheme='dark'] {
--background-color-neutral: #1a1a1a;
--text-color-neutral: #f0f0f0;
}
A font-family override may need more than a token. Semetrika ships @font-face
rules for the faces it names, and nothing more. Naming a family the visitor's
device already has - a system face, or one installed locally - is enough on its
own. Naming a web font you host means supplying its @font-face in the same
override stylesheet, or the browser falls through to the generic that ends the
stack.
Why this works
- Semetrika defines every token on
:rootinside a single@layer tokensblock - the first and therefore weakest layer in the bundle. - Your
my-variables.cssdefines the same tokens on:rootwithout a layer. - Unlayered declarations beat every layer, so your
:rootoverride wins regardless of stylesheet order. - Components reference
var(--…)at render time, not at definition time..btn { background: var(--btn-background-color); }resolves against your overridden value immediately.
What you can override
| Can override | Cannot override |
|---|---|
Every --* primitive (colors, spacing, border-radius, fonts) | Breakpoint values - @media cannot consume var() yet |
Every --* semantic token | Keyframe animation shapes (you can disable with --option-animations) |
--option-* feature flags (see below) | Structural layout rules that do not reference tokens |
Any token in either :root or :root[data-color-scheme='dark'] |
Order-independent overrides
Semetrika declares its tokens in @layer tokens, the first and weakest layer in the bundle. An unlayered :root override in my-variables.css therefore beats it no matter where the file loads - before or after semetrika.min.css. Loading after is still the tidy convention, but load order no longer decides the winner. Inside a single unlayered file the usual rule still applies: a later :root declaration overrides an earlier one.
Scoped overrides
CSS custom properties scope to their declaring element. Override a section of the page without affecting the rest:
.brand-section {
--background-color-neutral: #ffebd5;
--btn-background-color: #8b4513;
}
Every component inside .brand-section inherits the override. Components outside keep their defaults. This is the same cascade mechanism the data-color-scheme attribute uses to flip schemes for the whole page.
Scoped overrides work with any token in the system - colors, spacing, border-radius, motion. You can give one section a wider type ramp, another section a different border-radius, a third section a quieter focus ring, without forking CSS or duplicating selectors.
Options - runtime feature flags
Semetrika exposes runtime feature flags as --option-* custom properties. They sit alongside tokens and toggle or scale framework-wide behavior without rebuilding the CSS.
Most options are numeric scalars in [0, 1] consumed via calc() as multipliers:
:root {
--option-animations: 0; /* disable animations site-wide */
--option-rounded-corners: 0; /* square corners everywhere */
--option-elevation: 0; /* flatten every elevated surface */
--option-card-elevation: 0; /* disable card hover lift in grids */
}
0disables a feature entirely.1enables at full strength.- Any fraction in between scales proportionally -
0.5halves the border-radius,0.25softens corners by a quarter.
A small number of options are enum modes resolved through @container style() queries on the options container. Each names a presentation rather than a strength, and each ships a none value that disables the feature:
| Option | Values | Default |
|---|---|---|
--option-loading-mode | overlay, spinner, pulse, shell, none | overlay |
--option-reveal-mode | fade, slide-up, slide-down, zoom, none | none |
The reveal utility is opt-in: it defaults to none and animates nothing until a consumer sets a mode. A per-element data-reveal="<value>" attribute overrides the option.
Border radius
--option-rounded-corners is a multiplier applied to every base --{component}-radius (and equivalent semantic radius) Semetrika ships. Setting it to 0 squares every softly rounded surface across the framework and fractional values scale proportionally.
Explicit shape values (.circle, .pill) and intrinsic identity-shapes - radio inputs, switch and range thumbs, status and indicator dots, the loading spinner and pulse - deliberately ignore this option. Squaring a radio button or losing the chip's pill identity would break the component's meaning, so those shapes stay constant regardless of --option-rounded-corners. If a consumer wants the chip pill to square along with everything else, they override --chip-pill-border-radius (or the matching shape-value token) directly.
Per-component overrides still work and can be scoped to any ancestor element, the same way data-color-scheme is scoped:
.brand-section {
--card-border-radius: 1.5rem; /* override one component */
--option-rounded-corners: 0; /* square everything else */
}
Elevation
--option-elevation is a multiplier applied to every base --{component}-shadow, --{component}-raised-shadow, and --{component}-elevated-shadow Semetrika ships, as well as the .elevation-raised and .elevation-elevated utility classes. Setting it to 0 flattens every elevated surface across the framework (the offset and blur of every wrapped declaration collapse to zero) and fractional values scale proportionally.
Focus rings (radio, range, button :focus-visible) consume box-shadow syntactically but signal keyboard focus rather than decorative elevation. They deliberately bypass this option so accessibility cues stay visible when the global option is 0.
The card's hover-lift behavior inside a grid chains its dedicated --option-card-elevation flag with --option-elevation, so either factor can collapse the lift independently:
.brand-section {
--card-raised-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.2); /* keep one elevated */
--option-elevation: 0; /* flatten everything else */
}
When you override a wrapped shadow token, wrap the new value yourself if you want to keep the multiplier - the override replaces the token, not just its values.
Reduced motion
--option-animations is automatically set to 0 when the user has prefers-reduced-motion: reduce enabled. You do not need to handle this yourself - Semetrika reads the OS preference and zeroes the option for you.
The full token list
The canonical list of tokens (every primitive, every semantic token, every option) lives in src/variables.css and is documented on the Foundation pages in Storybook. Each Foundation page is generated from the same machine-readable token registry the bundle is built from, so the documentation is always in sync with the CSS.
Generate a brand palette
Need to seed a new project's color tokens from scratch? The Palette generator takes your brand hex codes, expands each into a perceptually uniform OKLCH ramp, and emits a block of --color-*-N declarations you can paste directly into the override stylesheet above.
Next steps
- Color schemes - opt in to the bundled dark scheme.
- Extending - reuse Semetrika's tokens in consumer components.
- Vocabulary - the value words that compose on top of the token system.