Skip to main content

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​

  1. Semetrika defines every token on :root inside a single @layer tokens block - the first and therefore weakest layer in the bundle.
  2. Your my-variables.css defines the same tokens on :root without a layer.
  3. Unlayered declarations beat every layer, so your :root override wins regardless of stylesheet order.
  4. 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 overrideCannot override
Every --* primitive (colors, spacing, border-radius, fonts)Breakpoint values - @media cannot consume var() yet
Every --* semantic tokenKeyframe 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 */
}
  • 0 disables a feature entirely.
  • 1 enables at full strength.
  • Any fraction in between scales proportionally - 0.5 halves the border-radius, 0.25 softens 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:

OptionValuesDefault
--option-loading-modeoverlay, spinner, pulse, shell, noneoverlay
--option-reveal-modefade, slide-up, slide-down, zoom, nonenone

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.