Brand tokens export

Brand tokens export

Turns the tokens block in brand.md into files a codebase and a design tool can use. The brand guide stays the single source of truth; the generated files are never edited by hand.

When to use

• Setting up a new site or app and wiring in the brand's colors, fonts, sizes, spacing, and radii.
• The brand guide changed and the code needs to catch up.
• "Make Tailwind use our brand colors", "give me CSS variables for the brand", "export tokens for Figma".
• Not for writing a brand guide from scratch. Use brand-guide-builder for that.

Inputs

1. The brand guide. Look for brand.md, then docs/brand.md. If neither exists, stop and offer to create one with brand-guide-builder (or by hand from examples/brand.md).

2. A tokens block inside it: a fenced block marked ```yaml tokens (or plain yaml or json). Groups it understands:

   • color, font (a list, first choice first), text (font sizes), weight, space, radius, shadow.
   • Plural names (colors, fonts, spacing) work too. name, logo, and voice are read by other brandkit kits and ignored here.
3. Where to write. Default brand-tokens/. Ask only if the project clearly keeps styles elsewhere (for example src/styles/), and then copy from brand-tokens/ rather than writing there directly.

Steps

1. Find the guide and read the tokens block. If there is no block, show the user the format from examples/brand.md and offer to add one from the colors and fonts already described in prose. Confirm the values before adding them.

2. Run the export.

   node scripts/export-tokens.mjs brand.md brand-tokens

   Add --prefix brand- if the project already has variables like --color-primary that must not clash.

3. Read the script's warnings (for example a color that is not a valid CSS color) and fix them in brand.md, then run again.

4. Wire it in. Detect the stack and give the one step that applies:

   • Tailwind v4 (@import "tailwindcss" in CSS): @import "./brand-tokens/theme.css"; right after it. Utilities like bg-primary and font-heading then work.
   • Tailwind v3 (tailwind.config.js): theme: { extend: require("./brand-tokens/tailwind.theme.cjs") }.
   • Plain CSS: import brand-tokens/tokens.css once, then use var(--color-primary).
   • Figma: import brand-tokens/design-tokens.json with a design tokens plugin that reads the W3C format. Show the exact line to add and ask before editing any config file yourself.
5. Report in the format below.

Output format

Exported 24 tokens from brand.md to brand-tokens/

| File | Use it for |
| --- | --- |
| tokens.css | Plain CSS: `var(--color-primary)` |
| theme.css | Tailwind v4 `@theme` |
| tailwind.theme.cjs | Tailwind v3 `theme.extend` |
| design-tokens.json | Figma and other token tools |

Next step for this project: <the one line to add, and where>
Warnings: <none, or what to fix in brand.md>

Naming

Variables follow Tailwind v4 names so every output agrees: --color-*, --font-*, --text-*, --font-weight-*, --spacing-*, --radius-*, --shadow-*. Token names are lowercased with hyphens (Primary Dark becomes primary-dark).

Guardrails

• Never edit the generated files by hand. Change brand.md and run the export again; say so in the report.
• Never invent token values. If the guide describes a color in words only ("our green"), ask for the hex value.
• Do not overwrite an existing tailwind.config.* or global stylesheet. Suggest the line; edit only after the user says yes.
• If the tokens block fails to parse, show the script's error line and fix the YAML (usually a tab, or a missing space after a colon).

Brand tokens export

Keep your brand colors, fonts, and spacing in one place, brand.md, and generate the code from it. One command writes CSS variables, a Tailwind theme, and a design-tokens.json for Figma.

Who it is for: anyone with a brand guide and a website or app that keeps drifting off it. Designers who want Figma and code to match. Developers who are tired of copying hex codes.

Example

You have this in brand.md:

```yaml tokens
color:
  primary: "#1F7A5C"
  accent: "#F2A541"
font:
  heading: [Fraunces, Georgia, serif]
radius:
  md: 10px
```

Ask "export our brand tokens". Claude runs the script and writes brand-tokens/:

:root {
  --color-primary: #1F7A5C;
  --color-accent: #F2A541;
  --font-heading: Fraunces, Georgia, serif;
  --radius-md: 10px;
}

plus theme.css (Tailwind v4), tailwind.theme.cjs (Tailwind v3), and design-tokens.json (W3C format). Then it tells you the one line to add for your setup. Try it on examples/brand.md.

What it can access

• Reads brand.md or docs/brand.md.
• Writes only inside brand-tokens/.
• Runs one script, scripts/export-tokens.mjs (Node, no dependencies). No network.

Setup

None. Needs Node 18 or newer. Pairs well with brand-guide-builder (writes the tokens block) and /brand (uses it).