Nico Haberkorn

Tokens

Every value in the system is a token. A token name says where it lives and what it is, and its value is decided one level at a time.

Name space and token space

A token name has two halves. The name space says where it lives: sn for the system, a theme (the preset) and a domain. The token space says what it is: a design attribute, colour or text, and a level. A preset build fixes the theme, so the same names carry different values per preset. Neither theme nor domain appears in the variable names yet.

snname space
rolelevel
colorattribute
on-surface-varianttoken

The selected token is --sn-role-color-on-surface-variant. Select another below or on the colour and typography pages.

How a value resolves

Pick any token and follow it down. Each line is one level, from the name a component uses to the literal value. Ref and pal are resolved when the package is built and never ship as CSS, so this view comes from the package’s trace file.

--sn-role-color-on-surface-variantresolves down these levels to a literal

    Levels

    Tokens are organised in levels, and each may only point at the one below it, so a value is decided in exactly one place. Four levels are applied: they make decisions. Comp and role ship as CSS; ref and pal are resolved at build time. Three are generative: seed, space and scale create the possibilities the applied levels choose from. Colour and text use the same levels. The selected token is shown at every level it passes through; the generative levels are worked through on the Colour and Typography pages.

    1. compapplied · public · colour only

      Values for one component, like a filled button’s background or a stamp’s border. They point at roles, never at raw values.

    2. role· sysapplied · public

      What a colour or type style means in the interface: surface, on-surface, display, prose. Light and dark differ here.

    3. refapplied · resolved at build

      The preset’s choices: which hue drives primary, which family is the serif. Resolved at build time.

    4. palapplied · resolved at build

      A curated selection of raw values: the tones of each hue, font families, weights, scale steps. Resolved at build time.

    5. scalegenerative · documented · data in the package

      The structure of a family of values: a tonal scale of 0 to 100 for colour, a named ratio applied to a base size for type.

    6. spacegenerative · documented · data in the package

      The format the values are written in: oklch for colour, px converted to rem and clamp() for type.

    7. seedgenerative · documented · data in the package

      The input a family grows from: a hue and a chroma for colour, a base size in pixels for type.

    Domains

    A domain says which kind of product the tokens are for. It exists so one design language can serve different contexts: colours and type voices stay shared, while components differ.

    DomainStatusWhat it means
    websiteBuiltEditorial pages such as this site: generous space, long text, drawn annotations.
    webappPlannedDenser components for working screens. The same colours and voices, tighter density.
    d-appPlannedDesktop applications.
    m-appPlannedMobile applications, where available screen space is the deciding context.

    A button on a website and a button in a web application should look different while clearly belonging together. That is done by sharing the palette and roles and letting component tokens, and parts of the role level, vary by domain.

    Get the ones that don’t make the page.

    Plenty of experiments never make it onto this page. The dispatch is where the half-finished ones go first.

    Or follow along on X and LinkedIn.