Cookbook

Client Site Component Install

Install @vandoko registry components with client-specific brand tokens and design system

A client site (Meridian Robotics from New Client — Full Pipeline) installs @vandoko components with their own brand theme, not the Vandoko theme. The CSS custom property system means no component code needs to change — only the token values differ.

Prerequisites

Before starting, confirm you have: - Client Next.js project initialized with shadcn/ui - BrandStrategy artifact from the go-vandoko pipeline (Recipe 1 output) - brand-config.json generated (or BrandStrategy available to generate it)

Flow

Step 1: Generate brand-config.json

Run the brand-config-generator skill:

Prompt
/generate brand config

The skill asks for inputs. For Meridian Robotics, provide:

FieldValue
Company nameMeridian Robotics
TaglinePrecision at Work
DescriptionIndustrial automation and cobot integration for mid-market manufacturers
Primary color#1E3A5F
Secondary color#4A6FA5
Accent color#FF6B35
Background#0D1117
Foreground#FAFAFA
Display fontSpace Grotesk
Display font sourcegoogle
Body fontInter

Output: ./brand-config.json

Step 2: Export design tokens

Run the design-token-export skill, providing the path to brand-config.json and selecting all formats:

Prompt
/export design tokens

Output written to ./tokens/:

FileFormatContent
variables.cssCSS custom properties--brand-primary: #1E3A5F; --brand-primary-oklch: oklch(0.35 0.06 245); etc.
tokens.jsonW3C DTCG JSON{ "brand": { "color": { "primary": { "$value": "#1E3A5F", "$type": "color" } } } }
figma-variables.jsonFigma Variables APIRGBA float values for programmatic Figma import

Step 3: Apply tokens to the client project

In the client's Next.js project, import the CSS variables and override the shadcn/ui theme:

app/globals.css
@import "./tokens/variables.css";

/* Override shadcn/ui theme variables with brand tokens */
:root {
  --primary: var(--brand-primary-oklch);
  --secondary: var(--brand-secondary-oklch);
  --accent: var(--brand-accent-oklch);
  --background: var(--brand-background-oklch);
  --foreground: var(--brand-foreground-oklch);
  --muted: var(--brand-muted-oklch);
  --border: var(--brand-border-oklch);
}

The import must come before any shadcn theme definitions so the overrides take effect correctly.

Step 4: Install @vandoko components

Install components using the standard shadcn CLI — no special flags needed:

Terminal
# Install individual components
npx shadcn@latest add @vandoko/hero-industrial
npx shadcn@latest add @vandoko/pricing-saas

# Components inherit the client's brand tokens via CSS custom properties
# No code changes needed -- oklch tokens resolve from globals.css

The installed components use Tailwind classes like bg-primary, text-foreground, border-border — which resolve to Meridian's colors through the CSS custom property override chain defined in Step 3.

Step 5: Verify theme customization

Start the dev server:

Terminal
pnpm dev

Inspect the hero component in the browser and confirm:

  • Background should be #0D1117 (Meridian's background), not #0A0A0A (Vandoko's)
  • Primary CTA should be #1E3A5F (Meridian's industrial blue), not #00EEFF (Vandoko's cyan)
  • Typography should render Space Grotesk headings with Inter body text

Verification Checklist

  • brand-config.json contains all hex values (no oklch/HSL at this stage)
  • tokens/variables.css has both hex and oklch decompositions
  • tokens/tokens.json follows W3C DTCG structure
  • Installed @vandoko components render with Meridian's brand colors
  • No hardcoded Vandoko cyan or lime visible in the client site
  • Font rendering matches Space Grotesk (headings) + Inter (body)

Troubleshooting

SymptomLikely CauseFix
Components show Vandoko cyan instead of client blueCSS custom property override not appliedVerify globals.css imports variables.css BEFORE shadcn theme definitions
Font not loadingGoogle Fonts not configuredAdd <link> tag for Space Grotesk in layout.tsx, or use next/font/google
oklch values look wrongHex-to-oklch conversion errorCross-check with culori library: import { oklch } from 'culori'; oklch('#1E3A5F')
Figma import failsMissing API token or file keyProvide FIGMA_TOKEN env var and file key in the curl command from references/design-tokens.md
Components break with missing dependenciesregistryDependencies not installedRun npx shadcn@latest add button card badge for base primitives first

On this page