generate-tokens

name

generate-tokens

description

Change Equal Experts brand COLOURS at the source and regenerate the downstream artifacts. Use when adding/editing a brand colour, scale step, or semantic alias — anything in reference/design-language/tokens/colors.tokens.json. Edits colours HERE (the SoT), regenerates the human-readable colours.md, runs the drift check, and hands off the kuat-core variables.css half. Contributor-only; repo-local. NOT for applying colours in a deck/app (that's the consumer skills).

Generate colour tokens (the SoT → artifacts)

Equal Experts brand colours have one source of truth: reference/design-language/tokens/colors.tokens.json (W3C design tokens). Everything else is generated from it:

Artifact	Repo	Generated by
reference/design-language/colours.md	kuat-agent-rules (here)	skills/scripts/generate-tokens.mjs
@equal-experts/kuat-core src/variables.css	kuat-mono (downstream)	the mono-side generator (Run B)

The one rule that matters: change colours in the token file, then regenerate. Never hand-edit colours.md or variables.css — that hand-sync is exactly how EE Blue once drifted to #0066CC. The drift check fails CI if a generated artifact diverges from the tokens.

Step 1 — Edit the token SoT

Open tokens/colors.tokens.json and make the change there:

• A brand value / scale step — edit the color.<scale>.<step> $value (hex) and keep $extensions.oklch in step. Scales run 50 (light) → 950 (dark); …-500 is the canonical brand value.
• A semantic role — edit alias.<role>.$value. Use a reference ({brand.ee-blue} / {color.ee-blue.500}), not a raw hex, unless the role is a non-brand support colour (e.g. destructive).
• Direction is one-way: tokens (upstream) → colours.md + kuat-core (downstream). Never invert.
• Support scales (slate/red/indigo) are not brand colours and live only in kuat-core — don't add them here.

Step 2 — Regenerate + verify (upstream)

npm run tokens:generate    # rewrites reference/design-language/colours.md from the tokens
npm run tokens:check       # exits 1 if colours.md has drifted from the tokens (CI gate)

tokens:check is the durable guard — it's wired into reference:check and .github/workflows/drift-check.yml. A green tokens:check means colours.md matches the SoT.

colours.md carries a GENERATED FILE — DO NOT EDIT BY HAND banner. If you ever need to change the prose (usage guidance, accessibility notes), edit the template in skills/scripts/generate-tokens.mjs and regenerate — not the markdown.

Step 3 — Propagate downstream (kuat-mono variables.css)

The downstream half lives in kuat-mono and is not run from here:

1. The token file syncs to kuat-mono via the upstream→mono sync (the 1b direction).
2. kuat-mono's generator emits @equal-experts/kuat-core src/variables.css from the synced tokens.
3. kuat-mono CI runs its own drift check (variables.css vs the synced tokens).

When you change a colour here, flag the kuat-mono sync so variables.css regenerates in the same release — see docs/migration/phase-7-kuat-mono-handoff.md. Until that lands, this token file is the authority and variables.css follows.

Step 4 — Stamp + hand off

• Note the change in the deliverable/PR with the reference ref — see version-stamp.
• If the change moves or renames a reference path, run review-reference-change before merging.

Related

• Part of the contribution model — this is the Medium · token path (Heavy for token structure) (proposing a token change).
• Reference (the WHAT): reference/design-language/colours.md — generated; read, don't edit.
• Review gate: review-reference-change
• Downstream contract: docs/migration/phase-7-kuat-mono-handoff.md