Brand System
How the Vandoko Registry distributes and governs brand systems — the oklch token contract, ownership boundaries, and the multi-tenant model.
Brand System
The Vandoko Registry is the governed distribution hub for brand systems. It ships the design-system tokens, the schema that defines them, and the default UI that consumes them — versioned, git-reviewed, and gated. This section documents what the Registry owns, how brands are partitioned across tenants, and how downstream systems consume a brand at install time and at runtime.
Customers never touch the Registry directly. Its callers are Vandoko-controlled systems: developers and CI (via the shadcn CLI), the Portal server (via the runtime API), and Remotion (via the Portal). Customers experience their brand through the Portal. See Ownership Boundary.
What the brand system is
A brand system is a complete instance of one CSS-variable contract. The contract is a fixed set of token names (brand colors, the obsidian surface ladder, semantic tokens, chart/gauge/heatmap palettes, sidebar tokens, and the prestige editorial layer). A brand provides the values for exactly those names — no more, no less.
The Vandoko design system is dark-only and oklch-first: every token is an oklch value, with no HSL or hex in token definitions. The current brand lock (v2.2, 2026-06-02) is:
- Signal cyan
#00EEFF—oklch(0.865 0.1475 204.0)— the primary brand accent. - Obsidian neutral surfaces — a chroma-0 surface ladder (
--backgroundthrough--surface-3). - Sand as the paired warm accent (replaced the retired lime).
- Cool data spectrum — chart colors derive from cyan / azure / teal.
- Lime is retired from the core system; it is opt-in only via
@vandoko/vandoko-campaign-tokens. See Campaign Tokens.
Sections
Token Contract
The canonical Zod/JSON token manifest — 67 tokens, date-based contract version, the exact-match rule, and pnpm brand:lint.
Ownership Boundary
What the Registry owns (schema + default UI) vs the Portal (tenant runtime data) vs the Tenant (their brand profile values).
Multi-Tenant Model
Governed distribution, serving namespaces, per-tenant {ns}-brand-system instances, and cross-tenant isolation.
Versions & Snapshots
Date-based immutable version snapshots, brand:snapshot, and the Portal runtime API endpoints.
Campaign Tokens
Lime and other celebratory accents — opt-in via @vandoko/vandoko-campaign-tokens, never in the core palette.
Consuming the Brand System
Install via the shadcn CLI, issue API keys, and configure components.json for the @vandoko namespace.
Authority
The architecture is defined by ADR 0002 — Multi-Tenant Registry Architecture (docs/adr/0002-multi-tenant-architecture.md, Accepted 2026-06-03). The auth and cache behavior of every registry endpoint is the Registry Auth & Cache Contract (docs/registry-auth-contract.md). This section summarizes those documents for brand-system consumers; where they go deeper, it links rather than duplicates.