BHDicaire

Generated categories

Governance rules Implementation details

Category pages are generated from tokens/core.tokens.json through a derived Hugo data file. Manual token tables are not allowed because they drift the moment a value changes.

This follows the broader data-driven page pattern: structured data owns the facts, Hugo owns the rendering, and validation fails when required metadata is missing.

The token pipeline now has two outputs: assets/css/generated/tokens.css for runtime CSS variables and data/brand/tokens.yml for documentation tables. Hugo bundles the CSS into the site stylesheet and renders the data file through the token-table shortcode.

Current category pages#

These pages are generated from token data:

Add more category pages only when the source token group exists and has metadata:

  • Motion
  • Radius
  • Shadow
  • Icon size

Source contract#

Every token rendered by a category page must have:

  • a stable token path
  • a CSS custom property name generated from that path
  • a value
  • a type
  • a short description or use case
  • a category or group
  • a predictable sort order
  • a kind: primitive, scale, semantic, or component-scoped

The generator must:

  • read tokens/core.tokens.json as the source of truth
  • fail on missing required metadata
  • build reusable data consumed by Hugo
  • include source path, generated CSS name, value, type, and use case
  • avoid writing generated pages by hand
  • run in a normal check command without warnings

The current guard is npm run tokens:check: it proves the CSS output is current, the generated Hugo data is current, every source token has required metadata, and the site CSS does not depend on a missing generated token.

Changelog

Most recent check of all entries: August 17, 2026

    • Generated token reference data and category pages from token metadata, with npm run tokens:check enforcing data drift.
    • Accepted ADR 0005: token category documentation must be generated from token metadata or Style Dictionary output, not maintained as manual tables.
    • Expanded Foundations > Tokens into a small section with Introduction, Types of tokens, Naming, Pipeline, and Generated categories.
    • Activated generated token CSS in the Hugo stylesheet bundle and added npm run tokens:check to guard generated output and CSS references.
    • Added npm run tokens:update as the safe token workflow: rebuild generated CSS, then verify it.
    • Added the dormant Style Dictionary pipeline: source tokens, generated CSS output, and npm run tokens:build.