Vanilla Breeze

Building Design Systems

A design system is a theme with documentation. Learn how to go from brand values to a living design system using Vanilla Breeze.

A Design System Is a Theme with Documentation

Every VB theme already defines colors, typography, spacing, shape, shadows, and motion through token overrides. A design system adds the why — brand identity, usage guidelines, voice, and component documentation.

In Vanilla Breeze, themes and design systems are not separate systems. They are the same system at different levels of maturity:
LevelWhat You CreateEffortOutputWhen
Quick Theme Override a few token seeds (hue, font, radius) 15 minutes A CSS file that changes the look Prototypes, hackathons, personal projects
Branded Theme Full token overrides + light/dark modes + component adjustments 2–4 hours A complete visual identity Product launch, client project, startup MVP
Design System Branded theme + documentation page + voice/tone + usage guidelines 1–2 days A living reference for your team Team of 3+, multi-product, agency handoff
Research-Driven DS All of the above + user personas, empathy maps, journey maps embedded in documentation 3–5 days A defensible, user-grounded system Enterprise products, regulated industries, design-led orgs

How to Choose Your Level

  • Solo developer? — Quick Theme. Override --hue-primary and --font-sans. Ship.
  • Small team, one product? — Branded Theme. Cover light/dark modes and all six token categories.
  • Multiple developers or designers? — Design System. Document so others can contribute without breaking consistency.
  • Users with specific needs? — Research-Driven DS. Use the Brand-to-Design-System guide to connect UX research to every token choice.
Key Insight You do not need to build all four levels at once. Start with a quick theme, evolve it into a branded theme as your product matures, add documentation when you have a team that needs it, and ground it in research when the stakes justify the investment.

From Brand Values to Design System

The workflow moves from abstract brand values to concrete token overrides to living documentation.

Step 1: Define Your Brand

Before writing any CSS, answer these questions:
  • Who are your users? — The UX Planning Pack’s <user-persona> and <empathy-map> components can help you formalize this.
  • What personality should the interface convey? — Professional and restrained? Playful and bold? Technical and precise?
  • What are your brand colors? — Usually a primary color from your logo, plus 1–2 supporting colors.
  • What typefaces represent you? — A heading font for impact, a body font for readability, a monospace font for code.

Step 2: Create a Theme

A VB theme is a CSS file that overrides token seeds. The framework derives all interactive states, surfaces, and responsive behaviors automatically from your seeds.

Start from src/tokens/themes/_theme-template.css for the full list of overridable tokens. See the Themes documentation for details.

Step 3: Document It

Use the Design System Pack components to build a living reference page. These components read your theme’s tokens at runtime, so the documentation always reflects the current state of your design.

See the Meridian Labs example for a complete design system page using all these components.

How Tokens Flow

VB uses a seed-and-derive architecture. You set a few seeds; the framework calculates everything else.

You SetThe Framework Derives
--hue-primary: 220 --color-primary, --color-primary-hover, --color-primary-subtle, --color-interactive, hover/active backgrounds
--font-sans: "Inter" All body text, nav labels, form controls, button text
--radius-m: 8px Cards, buttons, inputs, dropdowns, modals — anything that uses var(--radius-m)
--duration-normal: 200ms Transitions, view transitions, hover effects, accordion animations

This means a single hue change propagates to every interactive surface, status color, and hover state automatically. No manual color picking for each component.

Real-World Examples

These examples show the spectrum from quick themes to complete design systems.

Branded Themes (Theme-Level)

The Alpenglow Gear demo shows three real-world brands — McDonald’s, Anthropic, and IBM — each implemented as a VB theme override. Same components, same layout, completely different visual identity.

Full Design System

The Meridian Labs example is a complete design system page for a fictional climate research company. It demonstrates brand identity, color palettes, typography, spacing, shapes, motion, component showcase, and voice/tone guidelines — all built with the Design System Pack components.

Corporate SaaS

The Nuvaris Therapeutics demo and the Luminary SaaS demo show mobile-first branded applications with custom tokens, scroll-driven animations, and frosted glass effects.

Composing Design Systems

VB design systems compose with accessibility layers, color accents, and sizing presets.

Your theme CSS defines the visual identity. On top of it, users can layer:
  • Accessibility themes — high contrast, large text, dyslexia-friendly. These compose with any brand theme via space-separated data-theme values.
  • Color accents — OKLCH seed overrides applied via JavaScript. Users can personalize hue without breaking your brand system.
  • Sizing presets — compact, default, spacious. Adjust density while keeping your spacing ratios.
  • Color modes — light, dark, auto. Your theme should support both; the framework handles the switching.
Design for Composition When building a design system, always test with accessibility layers active. Your brand colors must maintain contrast when high-contrast mode is enabled. The VB accessibility themes are designed to compose with any decorative theme.

Next Steps
↑