Tokens in code

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:

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:

See The 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.

@import "../archetype/tailwind.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.

Then reference values by name instead of writing them out:

.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:

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.

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:

@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.

Next steps#