brand-to-tokens · diff
git:20261013.503b4e9 to git:20261016.7559f13
15 added, 36 removed. Audit A to A.
---
model_tier: inherit
name: brand-to-tokens
- description: "Turn a confirmed brand identity into a DTCG .tokens.json source of truth — emit CSS vars + Tailwind via design-tokens, export locked brand deck templates."
+ description: "Turn a confirmed brand identity into a DTCG tokens.json source of truth — emit CSS vars + Tailwind via design-tokens, export locked brand deck templates."
domain: engineering
personas: []
workspaces:
- engineering
packs:
- brand
trust:
level: professional
install:
removable: true
scope:
write: []
verification_reason: "execution declares no handler, so this skill runs nothing of its own — every write is the calling agent's, under the rules that govern it. No command can prove a scope the skill never executes."
execution:
type: manual
---
# brand-to-tokens
> The brand→token derivation — the **first consumer demand** that closes the
> ADR-061 §8 deferral. Takes a confirmed [`brand-identity`](../brand-identity/SKILL.md)
- > constraint set and produces a DTCG `.tokens.json` **source of truth**, then
+ > constraint set and produces a DTCG `tokens.json` **source of truth**, then
> hands it to the [`design-tokens`](../design-tokens/SKILL.md) toolchain to emit
- > CSS vars + Tailwind. The same `.tokens.json` is the export that pack-ai-image
+ > CSS vars + Tailwind. The same `tokens.json` is the export that pack-ai-image
> brand-asset generation and the greenfield scaffold seed consume (B → A;
> contract: [`brand-token-consumption`](../../../docs/contracts/brand-token-consumption.md)).
- ## Known contradiction — the filename this skill authors is not the one the resolver reads
-
- **Recorded, not resolved.** This skill's prose says to author `.tokens.json`,
- and the only resolver in the tree reads `tokens.json` — `BRAND_TOKEN_PATHS`
- searches `tokens.json`, `assets/tokens.json`, `resources/tokens.json` and
- `agents/settings/brand/tokens.json` <!-- ref-ignore -->, none of them
- dot-prefixed. A consumer
- following this skill literally therefore produces a file nothing loads.
-
- The authoring name is a consumer-visible decision and is deliberately not
- changed here. What closes the gap in the meantime is
- `agent-config brand:status`, which reports which of the four paths holds a file
- — and separately flags a dot-prefixed `.tokens.json`, which is exactly the file
- a reader of this skill would plausibly have created.
-
- Moved here from [`brand-source-of-truth`](../../rules/brand-source-of-truth.md)
- on 2026-09-09: it is a note about this skill, and its 6 lines in a standing rule
- were paid for on every subagent spawn. The substitution funded that rule's
- artifact-versus-brand pointer, per the council verdict on
- `blocker: standing-payload-headroom`.
-
## When to use
- A confirmed brand identity (colour story, type story, spacing) needs to become
a maintained token system.
- A consumer asks to "turn the brand into tokens / CSS variables / a theme."
- Before pack-ai-image brand-asset generation or a greenfield scaffold needs the
- `.tokens.json` export.
+ `tokens.json` export.
## Procedure
1. **Take the confirmed brand-identity constraint set** — colour story (roles +
values), type story (heading/body classes), spacing/radius intent. If a
consumer brand profile already registers values, those win
([`brand-source-of-truth`](../../rules/brand-source-of-truth.md)).
- 2. **Author `.tokens.json`** on the `design-tokens` 3-layer DTCG model
+ 2. **Author `tokens.json`** on the `design-tokens` 3-layer DTCG model
(`$value` / `$type`): brand palette → `primitive.color.*`; brand roles
(primary, accent, surface, destructive) → `semantic.color.*` referencing the
primitives; per-widget needs → `component.*`. Add `dark.semantic.*` overrides.
Type tokens come from [`typography-system`](../typography-system/SKILL.md)
stage-2 (archetype → pairing-filter), added under the `typography` section.
3. **Generate** CSS vars + Tailwind through the toolchain:
```bash
node <skills-root>/design-tokens/scripts/tokens.mjs generate \
- --config .tokens.json -o assets/design-tokens.css
+ --config tokens.json -o assets/design-tokens.css
node <skills-root>/design-tokens/scripts/tokens.mjs generate \
- --config .tokens.json --format tailwind
+ --config tokens.json --format tailwind
```
4. **Validate** — `node <skills-root>/design-tokens/scripts/tokens.mjs
validate --dir src/` until clean (exit 0 is the evidence); convert
hardcoded values to `var(--token)`.
5. **Export the deck templates** — emit the locked-variable brand deck
templates from [`templates/`](templates/) — `marp-brand-deck.md.example`
(copy to `.md` to use) and `reveal-brand-deck.yaml` — substituting the brand
- variables from `.tokens.json`. No render engine is owned (decision 7); the
+ variables from `tokens.json`. No render engine is owned (decision 7); the
templates feed the user's own deck tool.
- 6. **Publish `.tokens.json`** as the source of truth other surfaces read
+ 6. **Publish `tokens.json`** as the source of truth other surfaces read
(pack-ai-image generation, greenfield scaffold) per the consumption contract.
## Output format
- 1. `.tokens.json` — DTCG 3-layer (primitive → semantic → component) + `dark.semantic` + `typography`, every value `{$value, $type}`.
+ 1. `tokens.json` — DTCG 3-layer (primitive → semantic → component) + `dark.semantic` + `typography`, every value `{$value, $type}`.
2. Generated `design-tokens.css` + the Tailwind `theme.extend` snippet.
3. `validate` evidence — exit 0, or the `token_violation` findings handed to polish.
4. The exported brand deck templates (Marp + reveal) with brand variables locked from the tokens.
## Gotcha
- - **`.tokens.json` is the single source — never hand-edit the generated CSS or a
+ - **`tokens.json` is the single source — never hand-edit the generated CSS or a
consumer-side copy.** pack-ai-image generation and the greenfield scaffold read
this file; a hand-edited downstream copy silently drifts from the brand.
- **Derive, do not invent.** Every token traces to a brand-identity decision or
the consumer's existing brand; a value with no brand provenance is off-brand
- ([`brand-consistency`](../../rules/brand-consistency.md) will flag it).
+ ([`brand-source-of-truth`](../../rules/brand-source-of-truth.md) § Iron Law 2 flags it).
- Deck templates **lock** brand variables — never inline a raw hex/font in a
template; reference the token so the deck stays on-brand when tokens change.
## Do NOT
- Do NOT generate marks or assets here — this skill emits tokens + templates;
[`logo-generation`](../logo-generation/SKILL.md) / `brand-asset-generation`
generate the marks from the tokens (B → A, never inverted).
- - Do NOT hand-edit generated CSS — `.tokens.json` is the source.
+ - Do NOT hand-edit generated CSS — `tokens.json` is the source.
- Do NOT let components reference primitives directly — semantic layer between.
- Do NOT own a slide-render engine — export validated templates only (decision 7).
## See also
- [`design-canon.md`](../../../docs/guidelines/design-canon.md) § Colour references — culturally-situated palettes + a11y-contrast grounding when deriving brand colour tokens.
- [`brand-identity`](../brand-identity/SKILL.md) — supplies the constraint set this skill derives tokens from.
- - [`design-tokens`](../design-tokens/SKILL.md) — the DTCG toolchain that emits CSS/Tailwind from `.tokens.json`.
+ - [`design-tokens`](../design-tokens/SKILL.md) — the DTCG toolchain that emits CSS/Tailwind from `tokens.json`.
- [`typography-system`](../typography-system/SKILL.md) — brand-aware stage-2 supplies the type tokens.
- [`brand-token-consumption`](../../../docs/contracts/brand-token-consumption.md) — the read contract pack-ai-image and greenfield scaffold consume.
- - [`brand-consistency`](../../rules/brand-consistency.md) — validates emitted artifacts against this token source of truth.
+ - [`brand-source-of-truth`](../../rules/brand-source-of-truth.md) § Iron Law 2 — the checklist emitted artifacts are read against this token source of truth.