---
author: [Teemu Lahjalahti](https://www.linkedin.com/in/teemulahjalahti/)
index: https://salty-css.dev/llms.txt
---
# Variables & Tokens
A design token in Salty is just a value you name once and reuse everywhere — a color, a spacing step, a font size — written in TypeScript and compiled into a real CSS custom property. You define it with `defineVariables`, reference it anywhere a style takes a value with `{path.to.token}`, and Salty checks the path for you at build time so a typo fails the compile instead of silently unstyling an element.
Two quick notes before the examples, because they set the mindset:
**"Variables," "tokens," "custom properties" — mostly the same thing, and it's worth a word on why Salty says "variables."** The naming is a genuine mess across the ecosystem: some libraries call the whole token object the *theme*, others say *tokens*, and those systems tend to be JavaScript-based — a runtime object you thread through a provider. Salty sits closer to vanilla CSS, where *variable* is an actual, spec-defined term for exactly this thing, so that's the word it uses. Call it staying out of the fight by being friends with the [MDN spec](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties) — while keeping just enough distance, because the spec itself insists on calling them *custom properties*, which is nobody's idea of a fun word to type. 🧂 So: read "variable," "token," or "custom property" as the same mechanism throughout — Salty just picks the platform's word.
**Almost all of it resolves at build time.** `defineVariables` doesn't ship a token system to the browser — it writes plain CSS custom properties onto `:root` (or onto a conditional selector) in the static stylesheet. So the runtime cost is exactly that of hand-written CSS variables: nothing more. What you gain over hand-writing them is the TypeScript layer — autocomplete on the paths, and build-time validation that catches a mistyped token before it ever ships. If you want the deeper *why* behind that build-time line, the [Compiler concept](/concepts/compiler) is the read.
One framing that connects this to the pages on either side: a token is what a value graduates *into* when it stops being a local convenience. A one-file `const` (see [Dynamic Values](/react/docs/basics/dynamic-values), Example 1) is the right tool for a value one component uses. A *token* is the right tool when a value is shared, typed, and part of the system — one place to change it, one name everyone references. And a token is also the raw material [Theming](/react/docs/basics/theming) is built from: your fixed tokens are the atoms, theming adds a switchable layer on top. More on that in Example 3.
---
## Example 1 — Static tokens: the core case
The everyday case. Define a value once; reference it by path everywhere. "Static" means it lands on `:root` and stays put — brand colors, fixed spacing, a type scale, anything that doesn't depend on breakpoint or context.
### How you define it
Pass a plain object. Keys nest as deep as you like, and the nested path *is* the token's reference.
```ts
import { defineVariables } from "@salty-css/core/factories";
export default defineVariables({
colors: {
grey: { light: "#f0f0f0" },
black: "#0a0a0a",
brand: { blue: "#0070f3", green: "#1f9d55" },
},
spacing: {
small: "8px",
medium: "16px",
large: "32px",
},
fontFamily: {
heading: "Inter, system-ui, sans-serif",
body: "Georgia, serif",
},
});
```
### How you use it
Reference a token with `{path.to.token}` from anywhere a Salty style object accepts a value — inside `styled`, `className`, `defineGlobalStyles`, `defineTemplates`, all the same:
```ts
import { styled } from "@salty-css/react/styled";
export const Card = styled("div", {
base: {
background: "{colors.brand.blue}",
color: "{colors.grey.light}",
padding: "{spacing.large}",
fontFamily: "{fontFamily.body}",
},
});
```
That path isn't a loose string — it's validated as the file compiles. Mistype it as `{colros.brand.blue}` and the mistake surfaces in the compiler output, not as a silently unstyled `
` in the browser. (Turn on `strict: true` in [`defineConfig`](/react/docs/getting-started/configuration) if you want those treated as hard build errors from day one.)
### What actually ships
Every token you defined becomes a CSS custom property on `:root`, named by its dashed path — `colors.brand.blue` → `--colors-brand-blue`, `spacing.large` → `--spacing-large`, `fontFamily.body` → `--font-family-body`. The compiled rule for `Card` just reads the ones it uses:
```css
:root {
--colors-grey-light: #f0f0f0;
--colors-black: #0a0a0a;
--colors-brand-blue: #0070f3;
--colors-brand-green: #1f9d55;
--spacing-small: 8px;
--spacing-medium: 16px;
--spacing-large: 32px;
--font-family-heading: Inter, system-ui, sans-serif;
--font-family-body: Georgia, serif;
}
.card_hashed {
background: var(--colors-brand-blue);
color: var(--colors-grey-light);
padding: var(--spacing-large);
font-family: var(--font-family-body);
}
```
`:root` carries every token you defined; the component's rule pulls only the four it references. Inspect `:root` in DevTools to see the whole set at once — the token system is right there in the browser as ordinary custom properties, nothing exotic.
One habit worth forming early: **name a token by the role it plays, not by its raw value.** `spacing.pageMargin` ages better than `spacing.px120`, because the day the margin becomes 96px you change one definition and every call site follows — whereas a token literally called `px120` holding `96px` is a small lie you now maintain forever. Keep the nesting shallow too; two or three levels reads cleanly at the call site, deeper starts to feel like noise.
---
## Example 2 — The same token, a different value per breakpoint
Sometimes a token's *value* should change with the viewport while its *name* stays put — a gutter that tightens on mobile, a type step that shrinks. That's the `responsive` scope: one token name, values swapped by a media query, and call sites that never change.
### How you define it
Tokens under `responsive.base` are the defaults. A key named after a media query you defined with [`defineMediaQuery`](/react/docs/basics/breakpoints) — here `'@largeMobileDown'` — overrides any matching token when that query is active. You only redeclare what actually changes; everything else keeps its `base` value.
```ts
import { defineVariables } from "@salty-css/core/factories";
export default defineVariables({
responsive: {
base: {
spacing: { gutter: "24px", pageMargin: "120px" },
},
"@largeMobileDown": {
spacing: { gutter: "16px", pageMargin: "24px" },
},
},
});
```
### How you use it
Identically to a static token. The token reference is the same string; the browser picks the right value when the breakpoint matches — no `@media` block at the call site.
```ts
export const Page = styled("main", {
base: {
gap: "{spacing.gutter}", // 24px → 16px below the breakpoint
paddingInline: "{spacing.pageMargin}", // 120px → 24px below the breakpoint
},
});
```
Reach for `responsive` when a value should *step* between breakpoints. When you'd rather it scale *smoothly* — no hard jump at a threshold — that's a `clamp()`, and Salty has a helper for it: [Viewport clamp](/react/docs/basics/helpers/viewport-clamp) turns a reference size into fluid sizing you can store in exactly these responsive tokens.
---
## Example 3 — The same token, a different value per context (the theming bridge)
The third scope, `conditional`, swaps a token's value when an ancestor selector matches — a `data-theme` attribute or a class. Flip the attribute high in the tree and every consumer below it repaints, with no re-render and no component touched. This is the mechanism theming is built on, so this page shows only the shape of it and hands the full story to [Theming](/react/docs/basics/theming).
### How you define it
The structure is `conditional[group][value]: { …tokens }`. The group name is yours (`theme` is the convention); each value under it declares the *same token names* with different values. Referencing your static atoms keeps the palette in one place.
```ts
import { defineVariables } from "@salty-css/core/factories";
export const themes = defineVariables({
conditional: {
theme: {
light: { bg: "{colors.grey.light}", text: "{colors.black}" },
dark: { bg: "{colors.black}", text: "{colors.grey.light}" },
},
},
});
```
### How you use it
Consume the tokens through the group's namespace — `{theme.bg}`, `{theme.text}` — then activate a set by putting the attribute on an ancestor, usually ``:
```ts
export const Section = styled("section", {
base: { background: "{theme.bg}", color: "{theme.text}" },
});
```
```html
...
```
Salty compiles this to a `[data-theme="dark"] { … }` block that redefines those custom properties, so switching the attribute changes which block wins and the native cascade repaints — the component's own rule never knows which theme is active.
That's the whole conditional mechanism, but it's only the doorway. **[Theming](/react/docs/basics/theming) is the deep dive into this scope** — the atoms-and-molecules split (why a component should read `{theme.bg}` and never a raw `{colors.brand.blue}`), user-controlled toggles, following the OS via `prefers-color-scheme`, nesting themes, avoiding the first-paint flash, and when to use `conditional` (user- or markup-driven switches) versus `responsive` (environment-driven ones). Everything on that page is this scope, worked all the way out.
---
## Mixing scopes, and one gotcha
The three scopes are not separate features fighting for the same file — they merge into one `:root` namespace at build time, and you can freely mix them in a single `defineVariables` call or split them across many files:
```ts
defineVariables({
colors: { brand: { blue: "#0070f3" } }, // static
responsive: { // responsive
base: { spacing: { gutter: "24px" } },
"@largeMobileDown": { spacing: { gutter: "16px" } },
},
conditional: { // conditional
theme: { dark: { bg: "#0a0a0a" }, light: { bg: "#f0f0f0" } },
},
});
```
The one gotcha that catches people: **a standalone `defineVariables` file only takes effect if it reaches the build graph.** If your tokens print literally as `{colors.brand.blue}` in the output, the file was never imported anywhere Salty's build touches — re-export it from a styles barrel, or import it once. (Tokens passed inside `defineConfig({ variables })` are picked up automatically, no import needed.)
## Sharing tokens in a monorepo
Because tokens are plain TypeScript exports, they travel. In a monorepo you can keep your `defineVariables` calls in a local library package and import the values into each app's `.css.ts` files — Salty picks them up at build time exactly as it does tokens defined in-app, so every app shares one source of truth for the palette and scale.
The same caution from [Dynamic Values](/react/docs/basics/dynamic-values) applies, since your `.css.ts` files are evaluated at build: keep what you import light. A shared token module is just data, so it's cheap — but if that package drags in a heavy, browser-assuming dependency, it gets pulled into every build that imports it. Export the plain values, not a library.
---