Brand-mandatory tokens

themes specs/themes/brand-mandatory-tokens.kmd

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.

When this spec applies

Primary triggers

Override or extend any token in Verge / canonical presets

All triggers

Create a product preset that derives from Verge
Author a landing page that uses brand-marked tokens
Audit a Koder surface for unauthorized brand-token overrides

Spec — Brand-mandatory tokens

Status: 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:

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

Não-escopo

Per-product brand overrides (e.g., white-labeled Koder Talk for a partner) — separate spec when the use case becomes real.
Trademark legal handling (out of KDS scope).

References

specs/themes/verge.kmd
specs/themes/ui-style.kmd
meta/brand/koder-design/palette/mandatory/manifest.json