Design Customization

Customize the design system to match your brand identity. VibeReady uses shadcn/ui with Tailwind CSS and OKLCH color tokens, so changing a design variable updates the entire application automatically.

---

Quick Workflow

The customization process is straightforward:

1. Colors — Edit CSS variables in the global stylesheet, updating --primary in both :root and .dark
2. Fonts — Change font imports in the root layout file
3. Test — Run the dev server and check light/dark modes

Tools: OKLCH Converter | Google Fonts

Once you update design tokens, the AI development framework picks them up automatically. Any AI-generated UI will follow your new brand styles without additional configuration.

---

Prerequisites

• Completed setup and AI framework configuration (see Setup Guide)
• Familiarity with the development workflow (see Build Your First Feature)

---

Phase 1: Change Brand Colors

Step 1: Choose Your Brand Color

Pick your brand’s primary color in hex format. For example, #0070f3 (blue).

Need inspiration? Coolors.co | Realtime Colors

Step 2: Convert to OKLCH

Why OKLCH? The OKLCH color space provides better perceptual uniformity than HSL or RGB. This means your brand color looks consistently vibrant in both light and dark modes without manual tweaking per theme.

1. Go to oklch.com
2. Paste your hex color (e.g., #0070f3)
3. Copy the OKLCH value (e.g., oklch(0.5 0.22 250))

Step 3: Update the Global Stylesheet

Open the global CSS file and find the :root section. Update the --primary variable with your OKLCH value:

:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);

  /* Your brand color */
  --primary: oklch(0.5 0.22 250);
  --primary-foreground: oklch(0.99 0 0); /* White text on primary */

  /* ... other color tokens */
}

You must also update the dark mode section. If you only update one section, theme switching will show your brand color in one theme but the default color in the other:

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);

  /* Lighter value for dark mode (better contrast) */
  --primary: oklch(0.7 0.22 250);
  --primary-foreground: oklch(0.205 0 0); /* Dark text on light primary */

  /* ... other color tokens */
}

Tip: For dark mode, increase the lightness component (the first number in OKLCH) while keeping the chroma and hue the same. A light-mode value of 0.5 typically maps to 0.7 in dark mode for good contrast.

Step 4: Test the Changes

Start the dev server and visit http://localhost:3000. All buttons, links, and active states now use your brand color. Toggle between light and dark modes to verify both themes.

Step 5: Verify AI Integration

Generate a page using your AI coding tool to confirm it picks up the new design tokens:

In plan mode:

"Generate a simple user profile page with:
- Page title
- Avatar placeholder
- Edit button (primary)
- Cancel button (outline)

Follow design system."

The AI reads the design system context, uses your --primary token, and generates UI that matches your brand color automatically.

---

Phase 2: Customize Typography

Choose Fonts

Popular font combinations for SaaS applications:

• Modern SaaS: Inter + Roboto Mono
• Professional: IBM Plex Sans + IBM Plex Mono
• Friendly: DM Sans + Fira Code

Browse options at Google Fonts.

Update Fonts

In the root layout file, replace the font imports. The default configuration uses Geist Sans and Geist Mono:

// Default setup:
import { Geist, Geist_Mono } from 'next/font/google'

// Replace with your chosen fonts:
import { Inter, Roboto_Mono } from 'next/font/google'

const inter = Inter({
  variable: '--font-geist-sans', // Keep the same CSS variable name
  subsets: ['latin'],
})

const robotoMono = Roboto_Mono({
  variable: '--font-geist-mono', // Keep the same CSS variable name
  subsets: ['latin'],
})

Important: Keep the CSS variable names (--font-geist-sans, --font-geist-mono) unchanged. Tailwind is configured to reference these variables, so the new fonts are applied everywhere automatically.

Restart the dev server after changing fonts.

---

Validation Checklist

After customization, verify the following:

• Dev server starts without errors
• Existing pages display colors correctly
• Dark mode toggle works and both themes look correct
• AI-generated pages use the new design tokens
• Text contrast meets accessibility minimums

Contrast checker: WebAIM Contrast Checker

Minimum contrast ratios: Normal text: 4.5:1 | Large text (18px+): 3:1

---

Troubleshooting

Issue	Solution
Colors wrong in dark mode	Update both :root and .dark sections in the global stylesheet. Dark mode needs higher lightness values (e.g., 0.7 vs 0.5).
Font not loading	Verify: (1) Font imported in the root layout file, (2) CSS variable names match the originals, (3) Dev server restarted.
AI not using new colors	Ensure: (1) Global stylesheet saved, (2) Plan mode active, (3) Prompt includes “follow design system.”
Inconsistent colors across components	Check that all relevant CSS variables are updated, not just --primary. Some components use --accent, --muted, or --destructive.

---

Key Takeaways

1. Design tokens in CSS — Change a variable once and it updates everywhere across the application.
2. OKLCH color space — Provides consistent, perceptually uniform colors across light and dark modes.
3. AI follows your design — The AI framework reads your design tokens and automatically generates matching UI.
4. Simple workflow — Edit CSS variables, and the AI generates UI that matches. No additional configuration needed.

---

Next Steps

• AI Framework — Understand how the AI discovers and follows your design system
• AI Prompt Library — Skills for generating UI components and pages
• Stack Customization — Swap technologies and update stack references