Tailwind CSS

What it does

• stoaken export with the tailwind4 format writes a CSS file with one @theme block. Tailwind 4 turns each theme variable into utilities (docs): --color-brand-primary gives bg-brand-primary, text-brand-primary and border-brand-primary, and --spacing-md gives p-md, m-md and gap-md.
• stoaken export --check in CI fails a pull request when the committed file is behind the live release.
• On Tailwind 3, use the tailwind format instead. It writes a tailwind.config.js with theme.extend (see /docs/exports).

Before you start

• Tailwind CSS v4 through its Vite plugin, PostCSS plugin or CLI, with a stylesheet that starts @import "tailwindcss";.
• A Stoaken API key and a stoaken.config.json from npx stoaken init (see /docs/cli).

Setup

1. Add a saved target to stoaken.config.json. Mode names are your Brand's own (axis:mode). They're listed in /docs/exports and in every exported file.

{
  "brandId": "…",
  "brandName": "Acme",
  "serverUrl": "https://www.stoaken.com",
  "exports": [
    { "theme": "Default", "format": "tailwind4", "mode": "scheme:light", "out": "src/styles/tokens.theme.css" }
  ]
}

2. Run npx stoaken export. For Stoaken's sample theme the file looks like this:

 * Mode: scheme: light. Export each mode as its own file.
 *
 * Notes (2):
 * - motion-duration-fast is a transitionDuration value, which Tailwind 4 has no theme namespace for, so it was left out.
 …
@theme {
  --color-brand-primary: #007c2b;
  …
  --color-button-primary-background: #007c2b;
  --color-button-primary-text: #ffffff;
  …
  --spacing-md: 8px;
  …
  --spacing-button-padding: 8px;
  --radius-button-radius: 12px;
  …
  --font-typography-family-body: Geist, -apple-system, "Segoe UI", sans-serif;
  …
  --shadow-elevation-1: 0px 3px 10px -3px rgb(6 40 29 / 0.1);
  …
  --ease-motion-easing-out: cubic-bezier(0.2, 0, 0, 1);
}

3. Import it right after Tailwind:

@import "tailwindcss";
@import "./styles/tokens.theme.css";

4. Use the utilities:

<button class="bg-button-primary-background text-button-primary-text px-button-padding py-sm rounded-button-radius shadow-elevation-1 font-typography-family-body">Save</button>

5. Commit the file, and add npx stoaken export --check to CI (see the GitHub, GitLab or Bitbucket guide, or /docs/cli).

Configuration

• Each token type goes to the namespace Tailwind reads it from:

• Only your colours: clear Tailwind's palette between the two imports. After the import it would clear yours too.

@import "tailwindcss";
@theme {
  --color-*: initial;
}
@import "./styles/tokens.theme.css";

• Every variable in :root: Tailwind only writes the theme variables your utilities use. Import the file with theme(static) to write them all, for plain var(--color-brand-primary) in your own CSS: @import "./styles/tokens.theme.css" theme(static);.
• Font sizes are written as --spacing-* (for example --spacing-typography-body-size: 15px), not --text-*, so there is no text-typography-body-size. Use text-(length:--spacing-typography-body-size).

Try it

1. Build the app and inspect the button: its background-color is the release's button.primary.background (#007c2b in the sample), and its padding is 8px across.
2. Change a colour in Stoaken, publish, run npx stoaken export and rebuild. The button follows. Without the export, npx stoaken export --check exits 1.

Troubleshooting

• A class has no styles: the token's namespace decides the prefix. text-text-default is right for color.text.default. Check the variable name in the exported file.
• A token is missing: read the Notes at the top of the file. Durations are left out, because Tailwind 4 has no theme namespace for them.
• Tailwind's own rounded-md changed: your radius.md replaces Tailwind's of the same name, by design.
• stoaken export errors (401, unknown theme or mode) are explained in /docs/cli.

Limits

• One mode per file. @theme can't sit inside a selector, so this file can't switch light and dark at runtime. For that, use the CSS variables export (see the Storybook guide), or build one stylesheet per mode.
• The file is written by Stoaken. Don't edit it by hand: the next export overwrites it, and --check fails until it does.