---
title: Tokens in code
description: Pull your brand's tokens into a repository as CSS your build imports, use them as variables or Tailwind classes, and keep them current with pull requests.
---

> Source: https://www.heyarchetype.com/docs/developers/tokens

Your tokens are decided in Archetype. Pull them into your repository and your build uses the same colors, type, spacing, radius and shadows your agents and your team see, and every brand change arrives as a diff you can review.

## Pull the tokens in

Run `init` once at the root of your repository:

```bash title="Terminal"
npx archetype-os init --url https://www.heyarchetype.com --brand <brand-slug>
```

It signs you in, saves the brand to `archetype.json` and writes the `archetype/` folder. Three of its files are tokens:

| File | What it is | Use it when |
| --- | --- | --- |
| `archetype/tokens.css` | Every token as a CSS custom property on `:root`. | Plain CSS, Sass, CSS modules, or Tailwind 3 and earlier. |
| `archetype/tailwind.css` | The same tokens as a Tailwind 4 `@theme` block, which generates utilities such as `bg-…`, `rounded-…` and `text-…`. | Tailwind 4. |
| `archetype/tokens.json` | The tokens as W3C Design Tokens (DTCG) JSON. | Build pipelines and other tools that read DTCG. |

See [The CLI](/docs/developers/cli) for sign-in, flags and CI.

## Import them

Import one stylesheet, once, from your global CSS. `init` prints the line to use: it picks `tailwind.css` when your `package.json` depends on Tailwind 4 and the brand has a theme, and `tokens.css` otherwise.

```css title="app/globals.css (Tailwind 4)"
@import "../archetype/tailwind.css";
```

```css title="styles/global.css (plain CSS)"
@import "../archetype/tokens.css";
```

Adjust the path to where your stylesheet lives. Import one file or the other, never both: they define the same custom properties.

> [!WARNING]
> `tailwind.css` starts with its own `@import "tailwindcss"`. Use it in place of your existing `@import "tailwindcss"`, or Tailwind's base styles load twice.

Then reference values by name instead of writing them out:

```css title="Using the tokens"
.card {
  background: var(--color-semantic-canvas);
  border-radius: var(--radius-card);
  padding: var(--spacing-24);
  box-shadow: var(--shadow-card);
}
```

The names follow the token's path in Archetype: `--color-…`, `--radius-…`, `--spacing-…`, `--shadow-…`, `--font-…`, and `--gradient-…` for gradients (used as `background-image`). `tailwind.css` also turns each text style into `--text-…`, so a class like `text-…` sets its size, line height, weight and letter spacing together. The exact names your brand has are listed in `archetype/tokens.css`, each with its name in Archetype as a comment.

### Spacing in Tailwind 4

Spacing steps named like Tailwind's own numbered steps (`--spacing-4`, `--spacing-16`) stay out of the `@theme` block, so `p-4` keeps meaning Tailwind's 16px. Use them as `var(--spacing-16)`, or as an arbitrary value such as `p-[var(--spacing-16)]`.

### Light and dark modes

If your brand has modes, `:root` holds the default one and each other mode is a block keyed on a `data-mode` attribute. Set `data-mode="dark"` (the mode's name as a slug) on an element, usually `<html>`, and every semantic color inside it switches. Paint anything that should follow the mode with the semantic tokens (`--color-semantic-…`). A palette shade is the same in every mode.

## Keep them current

The folder is a snapshot. When the brand changes, pull again:

```bash title="Terminal"
npx archetype-os pull
```

It rewrites only the files that changed and removes what the brand no longer has. A file that differs only by its generated date counts as unchanged, so pulling an unchanged brand leaves an empty diff. Commit the result: the diff is your record of what changed in the brand, and when.

To see where you stand without changing anything, run `npx archetype-os status`. In CI:

- `npx archetype-os pull --check` fails the build when `archetype/` is behind the brand.
- The GitHub Actions workflow at `/ci/archetype-pull.yml` on your Archetype address pulls every weekday at 06:00 UTC and opens a pull request when the brand changed. It needs an API key from **Settings → Agents → API** as the repository secret `ARCHETYPE_TOKEN`.

**Settings → Agents**, on the **Repository** tab, sets this up for you: copy the prompt into your coding agent, or choose **Do it by hand instead** and keep **Automatic updates** on. Once a pull has landed, the tab shows what the repository's connection does.

> [!TIP]
> Change a token in Archetype, not in `archetype/`. The CLI owns that folder and the next pull overwrites any hand edit.

## How Archetype's own app does it

Archetype's app is built on its own brand this way. Its global stylesheet imports the Tailwind theme in place of Tailwind, and tells Tailwind not to scan the rest of the folder:

```css title="app/globals.css"
@import "../archetype/tailwind.css";
/* The rest of the folder is Markdown with class names in it: scanned,
   it would generate utilities nothing uses. */
@source not "../archetype";
```

The app keeps its own older variable names as aliases of the brand's, such as `--brand-600: var(--color-brand-600)` on `:root`, so existing code keeps working while the values come from the brand. Where the brand's theme already declares the key a class reads, such as `--radius-card` for `rounded-card`, the brand owns that class outright.

> [!WARNING]
> Don't declare a key the brand's `@theme` already has again in a `@theme inline` block of your own. It points the variable at itself, and the value resolves to nothing.

## Next steps

:::cards
- [The CLI](/docs/developers/cli): Every command, flag and file the CLI uses.
- [Check](/docs/create/check): Grade code against the brand's tokens, in the app, over MCP or in CI.
- [Foundations](/docs/brand/foundations): Where the tokens are edited in Archetype.
:::