Brand-mandatory tokens

mandatory

Subset of design tokens flagged as brand-mandatory — must NEVER be overridden by a product preset or downstream consumer. Verge default tokens are overridable per product; brand-mandatory tokens (Koder logomark hue, primary brand-mark hex, official typography roles) are inherited from `meta/brand/koder-design/palette/mandatory/`. Modeled after NSW DS brand-compliance badge convention.

Spec — Brand-mandatory tokens

*tatus* v0.1.0 — Draft. Bootstraps the brand-mandatory layer of the token system. Manifest file at meta/brand/koder-design/palette/mandatory/manifest.json is the source of truth; this spec ratifies the contract.

R1 — What's brand-mandatory

The manifest in meta/brand/koder-design/palette/mandatory/manifest.json lists tokens flagged as brand-mandatory. For Koder Stack v0:

Token Rationale
--brand-koder-mark Koder logomark hex — never overridable
--brand-koder-mark-on Reverse for logomark on dark surfaces
--brand-font-display Official display typeface family
--brand-font-mono Official monospace typeface family

(Verge --kdr-accent is NOT brand-mandatory by default — Koder Stack defaults to Adwaita blue, but products MAY override to match their own accent. The Koder logomark stays the same regardless of accent.)

R2 — Override rules

  • Brand-mandatory tokens MUST be applied verbatim wherever the

    Koder logomark / display typeface appears.

  • Product presets MAY define their own --kdr-accent / --kdr-bg /

    --kdr-surface / typography roles for in-product UI.

  • Marketing surfaces (landing pages, Hub product cards, README OG

    images) MUST honor brand-mandatory tokens regardless of preset.

R3 — Visual marker on kds.koder.dev

KDS site renders a small badge marker (blue diamond, per NSW DS convention) next to every token flagged in the manifest, on:

  • The Verge token table at /verge/.
  • Any per-preset token comparison page.
  • The shared tokens reference at /api/v1/tokens.json (JSON field

    brand_mandatory: true).

Implementation: tools/design-gen reads the manifest at gen time and emits the badge inline in templ output. Backlog: a sub-ticket in design-gen for the rendering integration once this spec ratifies.

R4 — Enforcement

  • CI gate on koder_kit / koder_web_kit: any preset whose generated

    token output overrides a brand-mandatory token fails the build.

  • Test suite spec: tests/regression/brand-mandatory-tokens.test.ts

    (consumer SDK; not KDS-level).

R5 — Adding / removing brand-mandatory tokens

Changes to the manifest MUST go through:

  1. RFC explaining why the token is (or no longer is) brand-mandatory.
  2. 7day feedback window per `policies/designgovernance.kmd`.
  3. Owner approval (in this Koder Stack phase: Rodrigo).

Não-escopo

  • Perproduct brand overrides (e.g., whitelabeled Koder Talk for a

    partner) — separate spec when the use case becomes real.

  • Trademark legal handling (out of KDS scope).

Source: ../home/koder/dev/koder/meta/docs/stack/specs/themes/brand-mandatory-tokens.kmd