Design tokens glossary for teams shipping React Native and web

Design tokens are easy to explain and easy to get wrong. The idea fits in one sentence: store each design decision once, with a name, and generate the code every platform needs from that one place. The trouble starts when a designer, a web engineer and a React Native engineer each use the same word for a different thing.

This glossary is the shared vocabulary we use on projects where one token set feeds a React Native app and a web product. It follows the Design Tokens Community Group (DTCG) format where that format has a word for something, and says so when a term is common practice rather than spec. The last section shows how we lay out tokens ourselves.

The basics

Design token

A named design decision stored as data: a colour, a spacing step, a font size, a duration. In DTCG files a token is any object that has a $value. The name is the path to it, so color.action.bg is the token at color → action → bg.

Group

An object in the token file that holds tokens or other groups but has no $value itself. Groups give tokens their dotted names and can carry a $type that every token inside inherits.

Token file

A JSON file in DTCG format. The 2025.10 spec suggests the .tokens or .tokens.json extension and the application/design-tokens+json media type, though most tools also accept plain .json.

Source of truth

The one place a token value is edited. Everything else (CSS, TypeScript, Figma variables, native resources) is generated from it. Teams argue about whether that place is Figma or the repository; what matters is that there is exactly one.

Design system

The wider set of components, patterns, guidance and tokens. Tokens are the lowest layer: they hold values, not behaviour.

Tiers: primitive, semantic, component

Almost every mature token set has three tiers, even if the names differ. Material Design 3 calls them reference, system and component tokens; other teams say base, alias and component. The point of the tiers is that a component never knows the hex value it ends up with.

Primitive token (also base, core, global or reference token)

A raw value with a name that describes the value, not its use: color.blue.600, space.4, radius.md. Primitives form the palette and the scales. Components should never use them directly.

Semantic token (also alias or system token)

A token named for its role, whose value is a reference to a primitive: color.action.bg → {color.blue.600}. This is the tier that changes between light and dark or between brands, so it is where most theming happens.

Component token

A token scoped to one component, usually pointing at a semantic token: button.primary.bg → {color.action.bg}. Useful when a component needs to diverge from the system; noise when it simply mirrors the semantic layer one to one.

Alias / reference

A token whose value points at another token instead of holding a literal. In DTCG the syntax is the full dotted path in curly braces, as a whole string: "$value": "{color.blue.600}". A reference resolves to the target's $value, and chains are allowed as long as they do not loop.

JSON Pointer reference ($ref)

The 2025.10 spec also allows {"$ref": "#/color/blue/600/$value"}, which can point inside a value, for example at one component of a colour. Tool support is newer than for the curly-brace syntax, so check before you rely on it.

Token properties

$value

The token's value. Required. Either a literal of the right shape for its type or a reference.

$type

What kind of value it is: color, dimension, fontFamily, fontWeight, duration, cubicBezier and number are the simple types; strokeStyle, border, transition, shadow, gradient and typography are composites. Set on a token or inherited from the nearest group that sets it.

$description

Plain-text explanation for humans. Build tools can write it into generated code as a comment, which is where engineers actually see it.

$deprecated

true, or a string explaining what to use instead. Lets you retire a token without breaking every consumer on the same day.

$extensions

A place for tool-specific data, keyed by a reverse-domain name such as com.example.tool. Tools must keep data they do not understand.

$root

A token named $root inside a group stands for the group itself, so color.accent can have a value while color.accent.light and color.accent.dark also exist.

Composite tokens

Composite token

A token whose value is an object of sub-values that only make sense together. Each sub-value can be a literal or a reference.

Typography token

fontFamily, fontSize, fontWeight, letterSpacing and lineHeight in one value. In the spec lineHeight is a plain number, a multiple of the font size, which maps cleanly to CSS but not to React Native, where lineHeight is an absolute value; your build has to multiply it out.

Shadow token

color, offsetX, offsetY, blur, spread and an optional inset, or an array of these for layered shadows. On the web it becomes box-shadow. React Native has historically split shadows into iOS shadow props and Android elevation, and newer versions add a CSS-style boxShadow style prop, so check what your version supports.

Border token

color, width and style, where style is a strokeStyle value such as solid or dashed.

Transition token

duration, delay and timingFunction (a cubicBezier). Durations are objects such as { "value": 200, "unit": "ms" }.

Themes and modes

Mode

One set of values for the same token names: light and dark, compact and comfortable, high contrast. The names stay the same so components do not change; only the semantic values do.

Theme

Often used as a synonym for mode. We use it for brand-level variation (two products sharing one component library) and mode for user-facing settings like dark.

Resolver

The DTCG 2025.10 Resolver Module describes how to combine token files for a given context. Sets are groups of token files merged in order; modifiers are named choices (theme: light or dark) that swap in different sets; the resolution order decides what overrides what. Terrazzo 2 supports resolvers; in Style Dictionary support is still in progress at the time of writing, so check your build tool before adopting it.

Figma variable mode

Figma's own per-collection modes. They map well to DTCG modes, but a Figma file is not a token file; you still need an export step or a plugin to produce DTCG JSON.

Units and platforms

This is where React Native and web teams trip most often, because the same number means different things on each platform.

dimension

The DTCG type for sizes. Its value is an object with a number and a unit: { "value": 16, "unit": "px" }. The 2025.10 format allows only px and rem.

px (CSS)

The CSS reference pixel. It is a logical unit, not a hardware pixel; on a 3x phone screen one CSS px covers about three device pixels.

rem

A multiple of the root element's font size, 16 px by default in browsers. Using rem for type lets text follow the user's browser font setting.

pt (iOS)

Apple's layout point. Like CSS px it is logical: one point is one, two or three physical pixels depending on the screen scale. Apple's 44×44 pt minimum hit target is in points.

dp (Android)

Density-independent pixel. One dp is roughly one physical pixel on a 160 dpi screen, and Android scales it for every other density. Material's 48×48 dp minimum touch target is in dp.

sp (Android)

Same size as dp by default, but it also scales with the user's font size setting. For text only.

React Native units

React Native style values are unitless numbers that the docs describe as density-independent pixels, so 16 is 16 pt on iOS and 16 dp on Android. Text also scales with the user's font size unless you turn that off, which we do not recommend. In practice: author dimensions in px, and have the build strip the unit for the React Native output.

Platform transform

A step in the build that changes a token for one platform: renaming color.action.bg to --color-action-bg for CSS or colorActionBg for TypeScript, converting 16px to 1rem for the web or to 16 for React Native, turning an OKLCH colour into hex. Style Dictionary and Terrazzo are both built around this idea.

Colour

Color token value

In DTCG 2025.10 a colour is an object, not a string: colorSpace, an array of components, an optional alpha (0–1) and an optional hex fallback. The Color Module lists 14 colour spaces, including srgb, display-p3, oklch and oklab.

sRGB

The standard colour space of the web and of most screens. Every hex code you have ever written is sRGB.

Display P3

A wider-gamut RGB space used by recent Apple devices and many current phones and monitors. It can show more saturated greens and reds than sRGB. On the web it is written as color(display-p3 r g b).

OKLCH

A perceptual colour space with three components: lightness, chroma (colourfulness) and hue angle. Steps of equal lightness look equally light to the eye, which makes it a good space for building tonal scales and checking contrast pairs. CSS supports it as oklch().

Gamut

The range of colours a space or a screen can show. A colour defined in OKLCH or P3 can fall outside sRGB, which is why the hex fallback exists.

Hex fallback

The pre-computed sRGB value in a DTCG colour object. We always fill it in, because it is what we ship to React Native and to any platform that cannot handle wide-gamut colour yet.

How we structure tokens at Ainur

Our default layout is boring on purpose. Tokens live in the app's repository as DTCG JSON, split by tier, and a single build script generates CSS custom properties for the web and a typed TypeScript module for React Native.

• primitives.tokens.json: palette and scales, named by value (color.blue.600, space.4).
• semantic.light.tokens.json and semantic.dark.tokens.json: the same role names in both, each pointing at primitives.
• components.tokens.json: only for components that genuinely diverge from the semantic layer.
• Generated output, never edited by hand: tokens.css with var() references kept, and tokens.ts with resolved, unitless values for React Native.

A trimmed example in one file, showing each tier and a typography composite:

{
  "color": {
    "$type": "color",
    "blue": {
      "600": {
        "$value": { "colorSpace": "oklch", "components": [0.546, 0.215, 262.9], "hex": "#2563eb" }
      }
    },
    "white": {
      "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" }
    },
    "action": {
      "bg": { "$value": "{color.blue.600}", "$description": "Primary button and link fill" },
      "fg": { "$value": "{color.white}" }
    }
  },
  "space": {
    "$type": "dimension",
    "4": { "$value": { "value": 16, "unit": "px" } }
  },
  "font": {
    "body": {
      "$type": "typography",
      "$value": {
        "fontFamily": ["Inter", "sans-serif"],
        "fontSize": { "value": 16, "unit": "px" },
        "fontWeight": 400,
        "letterSpacing": { "value": 0, "unit": "px" },
        "lineHeight": 1.5
      }
    }
  },
  "button": {
    "primary": {
      "bg": { "$type": "color", "$value": "{color.action.bg}" },
      "label": { "$type": "color", "$value": "{color.action.fg}" },
      "padding-x": { "$type": "dimension", "$value": "{space.4}" }
    }
  }
}

Three rules keep this layout healthy. Components only ever read semantic or component tokens. Every semantic token exists in every mode, and the build fails if one is missing. And colours carry both an OKLCH value for the design work and a hex fallback for the platforms that need it.

Sources

1. Design Tokens specification reaches first stable version · W3C Design Tokens Community Group
2. Design Tokens Format Module 2025.10 · Design Tokens Community Group
3. Design Tokens Color Module 2025.10 · Design Tokens Community Group
4. Design Tokens Resolver Module 2025.10 · Design Tokens Community Group
5. Height and Width · React Native
6. Support different pixel densities · Android Developers
7. Design tokens overview · Material Design 3
8. oklch() CSS function · MDN