Consuming the Brand System

There are two ways Vandoko-controlled systems consume a brand: the shadcn CLI (developers and CI installing code + tokens) and the runtime API (the Portal pulling versioned brand packages — see Versions & Snapshots). This page covers the CLI path.

1. Issue an API key

Generate a registry key at registry.vandoko.com/admin/api-keys. Registry keys are prefixed vk_ and are shown once on creation (only a sha-256 hash is stored). Use a namespace-scoped key for a single tenant's items; the platform scope is reserved for the Portal server.

Add the key to your project's .env.local:

# .env.local
VANDOKO_REGISTRY_TOKEN=vk_...

2. Configure components.json

Add the @vandoko namespace to your project's components.json. The URL must use the {name}.json item template so the CLI can resolve individual items, and the Authorization header carries the token:

{
  "$schema": "https://ui.shadcn.com/schema",
  "style": "new-york",
  "tailwind": {
    "baseColor": "neutral"
  },
  "registries": {
    "@vandoko": {
      "url": "https://registry.vandoko.com/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${VANDOKO_REGISTRY_TOKEN}"
      }
    }
  }
}

For a customer namespace, the URL is https://registry.vandoko.com/r/{ns}/{name}.json with that tenant's namespace-scoped key.

3. Install the brand system

Install the canonical brand-system base, then import it in globals.css:

npx shadcn@latest add @vandoko/vandoko-brand-system

@import "tailwindcss";
@import "./vandoko-brand-system.css";

This installs the full oklch token set (the 67-token contract values), typography tokens, and the cool data-series chart palette. See Token Contract for what each token means and Vandoko Dark Theme for the annotated reference.

4. Add components

Brand-aligned components resolve their colors from the installed CSS variables, so they inherit the brand automatically:

npx shadcn@latest add @vandoko/glass-card
npx shadcn@latest add @vandoko/icp-overview-strip
npx shadcn@latest add @vandoko/channel-kpi-strip

For celebratory accents, opt into campaign tokens separately.

Auth & cache behavior

Every registry response is Cache-Control: no-store and auth is enforced in middleware (static public/r/ files would otherwise shadow the route handler). The full behavior matrix — status codes for every credential class, namespace scoping, the Clerk legacy bridge — is the Registry Auth & Cache Contract (docs/registry-auth-contract.md).

Related

• Token Contract — the 67-token contract and brand:lint.
• Multi-Tenant Model — namespaces and isolation.
• Installation — the general component install guide.