---
author: [Teemu Lahjalahti](https://www.linkedin.com/in/teemulahjalahti/)
index: https://salty-css.dev/llms.txt
---
# Advanced setup
[Basic setup](/react/docs/getting-started/basic-setup) ends with one component on screen, and everything it needs lives in one file: one `styled` call, a handful of hard-coded values, no knowledge of the rest of your app. That's the right place to stop when you're checking the install works.
This page is the layer after that — the small set of shared files that turn one component into part of a system. Values it can reference by name. A theme it responds to without being touched. Breakpoints, fonts, templates, document-level styles. None of it is required to ship, all of it can be added the day you need it, and none of it changes what the browser does at runtime, because it all compiles into the same static stylesheet.
Each section is a glimpse rather than a full treatment: what the thing is for, how you define it, how you use it, and where the page that goes deep on it lives.
---
## Where this stuff lives
One decision and one rule come before any of the APIs, and both are about files rather than functions.
**Shared styles get their own folder.** Component styles stay next to the component; the things every component draws from get one home, usually `/styles`:
```bash
src/
styles/
variables.css.ts design tokens
themes.css.ts the switchable layer on top of them
media.css.ts named breakpoints
fonts.css.ts @font-face and font tokens
templates.css.ts reusable style bundles
global.css.ts document-level base styles
components/
button.css.ts
```
Nothing enforces this and Salty doesn't care where the files sit — it cares about the suffix. But splitting by *what a file defines* keeps each one small, and it means you always know which file to open. [File structure](/react/docs/getting-started/file-structure) covers the variations as a project grows.
**The compiler finds files by suffix, not by import.** There's no barrel file, no registration step, and nothing to re-export. Drop `variables.css.ts` into `/styles` and its tokens are on `:root` on the next build; your components never import it, because tokens are referenced as `{path}` strings and breakpoints as `@name` strings. Two things a definition file does need, and they're the same two from Basic setup:
- **The suffix.** `variables.css.ts` compiles; `variables.ts` type-checks perfectly and emits nothing.
- **A top-level `export`.** The compiler collects exported calls, so an unexported `defineVariables(...)` produces no CSS — and doesn't warn.
Miss either one and the failure is quiet: tokens print literally as `{colors.brand.blue}` in the output, and named breakpoints emit as at-rules that silently never match.
The other place these can live is `salty.config.ts`, which takes the same objects directly:
```ts
import { defineConfig } from "@salty-css/core/config";
export const config = defineConfig({
strict: true,
variables: {
colors: { brand: { blue: "#0070f3" } },
},
});
```
It's a layout choice rather than a functional one — the two merge, so it's config for what you'd rather keep next to the rest of your setup, files for everything else. [Configuration](/react/docs/getting-started/configuration) has the full list of what can live in there.
One flag worth setting while you're in that file: **`strict: true`**. Salty's failure modes tend to be quiet — a mistyped token path passes through as a literal string rather than stopping the build — and strict mode is how you make them loud. `'warn'` is the softer version if you're adding Salty to a codebase that already has plenty of CSS and you'd rather not have the build going red on the first afternoon.
---
## The shared layer
### Variables
A token is a value you name once and reference everywhere. Define it with `defineVariables` and it compiles into a real CSS custom property on `:root` — so what ships is exactly what you'd have hand-written, plus a TypeScript layer that autocompletes the paths and fails the build on a typo.
**Define:**
```ts
import { defineVariables } from "@salty-css/core/factories";
export default defineVariables({
colors: {
grey: { light: "#f0f0f0" },
black: "#0a0a0a",
brand: { blue: "#0070f3" },
},
spacing: { small: "8px", medium: "16px", large: "32px" },
});
```
**Use** — `{path.to.token}` works anywhere a Salty style takes a value, in `styled`, `className`, globals, templates, all the same:
```ts
export const Card = styled("div", {
base: {
background: "{colors.brand.blue}",
padding: "{spacing.large}",
},
});
```
The habit worth forming now, because it's expensive to undo later: name a token for the role it plays, not the value it holds. `spacing.pageMargin` survives the day the margin changes; `spacing.px120` becomes a small lie you maintain forever.
→ [Variables & tokens](/react/docs/basics/variables) — static, responsive, and conditional scopes in full.
### Theming
Theming is a switchable layer on top of those tokens: the same names, different values behind them depending on an attribute. Flip the attribute on an ancestor and everything below repaints through the browser's own variable cascade — no provider, no context, no re-render.
**Define** — token sets under `conditional`, where each one declares the *same names*:
```ts
import { defineVariables } from "@salty-css/core/factories";
export const themes = defineVariables({
conditional: {
theme: {
light: { bg: "{colors.grey.light}", text: "{colors.black}", bgAlt: "#e4e4e4" },
dark: { bg: "{colors.black}", text: "{colors.grey.light}", bgAlt: "#1a1a1a" },
},
},
});
```
**Use** — components read the group's namespace and never know which set is active:
```ts
export const Section = styled("section", {
base: { background: "{theme.bg}", color: "{theme.text}" },
});
```
```html
```
The rule that makes this work is one layer of indirection: your fixed palette entries are what you *define* themes from, and the role-named values are what you *build against*. A component that reads `{theme.bg}` can become any color scheme without being edited. A component that reads `{colors.brand.blue}` is pinned to blue forever.
→ [Theming](/react/docs/basics/theming) — user toggles, following the OS, nested and multi-axis themes, avoiding the first-paint flash.
### Breakpoints
Name a condition once, then reference it by `@name` the same way you reference a token by `{path}`.
**Define:**
```ts
import { defineMediaQuery } from "@salty-css/react/config";
export const tabletUp = defineMediaQuery((media) => media.minWidth(768));
export const largeMobileDown = defineMediaQuery((media) => media.maxWidth(900));
export const reducedMotion = defineMediaQuery((media) => media.reducedMotion);
```
**Use** — as a key inside any style object, with nothing to import at the call site:
```ts
export const Grid = styled("div", {
base: {
display: "grid",
gridTemplateColumns: "1fr 1fr",
gap: "{spacing.medium}",
"@largeMobileDown": { gridTemplateColumns: "1fr" },
},
});
```
Worth noticing the import path: `defineMediaQuery` comes from the framework package rather than core — `@salty-css/react/config` here, `@salty-css/astro/config` on Astro. Most of what's on this page comes from `@salty-css/core/*` and behaves identically wherever you use it.
→ [Breakpoints & responsive layouts](/react/docs/basics/breakpoints) — the full query builder, container queries, and when to swap a value instead of a block of styles.
### Fonts
`defineFont` writes the `@font-face` rules and hands back something you can drop straight into a style object.
**Define** — one entry per face:
```ts
import { defineFont } from "@salty-css/core/factories";
export const inter = defineFont({
name: "Inter",
fallback: "system-ui, sans-serif",
display: "swap",
variants: [
{ src: "/fonts/Inter-Regular.woff2", weight: 400, style: "normal" },
{ src: "/fonts/Inter-Bold.woff2", weight: 700, style: "normal" },
],
});
```
**Use** — the returned object stringifies to its `font-family`, fallback already appended:
```ts
export const Heading = styled("h1", {
base: { fontFamily: inter, fontWeight: 700 },
});
```
Being straight about the boundary: `defineFont` writes correct `@font-face` CSS, and that's the whole job. If you've come from `next/font`, the subsetting and automatic preloading it did behind the scenes aren't happening here — the loading-performance work stays yours. `defineImport` is the companion for CSS you only need *present*: a vendor reset, a syntax-highlight theme, a hosted stylesheet.
→ [Fonts & imports](/react/docs/basics/fonts) — hosted fonts, exposing a font as a token, and the loading practices that matter.
### Templates
A template bundles properties that always travel together, under one name. Think of the `font` or `border` shorthands — one declaration, several properties, expanded for you.
This is *not* the tool for "make a card template." A plain styled component already is your card. Templates are for the smaller, fiddlier job: the group of four properties you'd otherwise retype on every heading and get subtly wrong on the third one.
**Define** — a shared `base` per group, with leaves saying only what differs:
```ts
import { defineTemplates } from "@salty-css/core/factories";
import { inter } from "./fonts.css";
export default defineTemplates({
textStyle: {
headline: {
base: { fontFamily: inter, fontWeight: "300", lineHeight: "1.2em" },
regular: { fontSize: "2rem" },
large: { fontSize: "3.5rem" },
},
},
});
```
**Use** — the template name becomes a key inside `base`:
```ts
export const Title = styled("h1", { base: { textStyle: "headline.large" } });
```
Templates resolve in their own cascade layer, below your component styles — so anything you set directly on the component still wins, and you're never fighting a template to override one property of it.
→ [Templates](/react/docs/basics/templates) — template variants, function templates, and the text-styles pattern worked all the way out.
### Global styles
Salty scopes everything by default. Global styles are the deliberate exception for the handful of rules that belong to the document rather than to a component.
**Define:**
```ts
import { defineGlobalStyles } from "@salty-css/core/factories";
export const globalStyles = defineGlobalStyles({
body: {
margin: 0,
background: "{theme.bg}",
color: "{theme.text}",
},
a: { color: "currentcolor" },
});
```
There's no **use** step. No `` to render, no class to attach — once the file exists with the right suffix, the rules are simply there.
The line to hold: if a rule is about the document, it's a global; if it's about a component, it isn't. And globals sit in a *lower* cascade layer than component styles, which means a broad global selector can never out-muscle a `styled` component no matter how specific it looks. That's the same guarantee that stops global CSS leaking into your components, working in the direction people don't expect.
→ [Global styles](/react/docs/basics/global-styles) — the layer order, the built-in reset, and what belongs here versus a dedicated factory.
---
## Back in the component
The rest of the list isn't setup — there's nothing to wire, no file to register. It's what the layer above unlocks, and it's here so you know the tools exist before you go hand-roll them.
### Variants
A variant is a named branch of styles that becomes a typed prop. This is where most of the day-to-day work happens once tokens exist.
**Define:**
```ts
import { styled } from "@salty-css/react/styled";
export const Button = styled("button", {
base: {
padding: "{spacing.small} {spacing.medium}",
borderRadius: "6px",
cursor: "pointer",
},
variants: {
tone: {
solid: { background: "{theme.text}", color: "{theme.bg}" },
ghost: { background: "transparent", color: "{theme.text}" },
},
size: {
small: { fontSize: "0.875rem" },
large: { fontSize: "1.125rem", padding: "{spacing.medium} {spacing.large}" },
},
},
defaultVariants: { tone: "solid", size: "small" },
});
```
**Use:**
```tsx
{/* solid, small */}
```
Two things happen here that are easy to miss. `defaultVariants` means the bare `