brand-to-tokens git:20260909.c0fa95dA

Immutable. This exact content is served forever at /api/v1/blob/e802efa930018a8f.

---
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."
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
> 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
> 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`, 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.

## 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
   (`$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
   ./scripts-run <skills-root>/design-tokens/scripts/tokens generate \
     --config .tokens.json -o assets/design-tokens.css
   ./scripts-run <skills-root>/design-tokens/scripts/tokens generate \
     --config .tokens.json --format tailwind
   ```

4. **Validate** — `./scripts-run <skills-root>/design-tokens/scripts/tokens
   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
   templates feed the user's own deck tool.
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}`.
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
  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).
- 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 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`.
- [`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.