Themes

Themes let you customize the look and feel of your site with a single attribute. Choose from color themes that change the palette, or personality themes that transform the entire design.

Using Themes

Apply a theme by adding the data-theme attribute to the <html> element.

<html data-theme="ocean">  <html data-theme="ocean" data-mode="dark">  <html data-mode="light"> <html data-mode="dark">

Theme Categories

Vanilla Breeze includes three types of themes:

Color Themes

Change the brand color palette. Shape, shadows, and typography remain default.

Ocean
Forest
Sunset

Personality Themes

Transform colors, shape, shadows, typography, and motion for distinct design feels.

Modern
Minimal
Classic

Extreme Themes

Dramatic visual transformations for creative projects and artistic expression.

Brutalist, Swiss, Cyber, Organic
Editorial, Terminal, Kawaii, 8-bit
NES, Win9x

Color Themes

Color themes override hue values to change the brand palette. They preserve the default shape, shadows, and typography.

Ocean

A calm, professional teal-blue palette.

Primary (Hue 200) Secondary (Hue 180) Accent (Hue 45)

Property	Value	Color
`--hue-primary`	200	Teal-blue
`--hue-secondary`	180	Cyan
`--hue-accent`	45	Gold

Forest

Natural, earthy green palette.

Primary (Hue 145) Secondary (Hue 120) Accent (Hue 30)

Property	Value	Color
`--hue-primary`	145	Green
`--hue-secondary`	120	Forest green
`--hue-accent`	30	Orange/amber

Sunset

Warm, vibrant orange-red palette.

Primary (Hue 25) Secondary (Hue 350) Accent (Hue 50)

Property	Value	Color
`--hue-primary`	25	Orange-red
`--hue-secondary`	350	Pink-red
`--hue-accent`	50	Yellow

Personality Themes

Personality themes transform the entire design system, overriding colors, border radius, shadows, typography, and motion.

Modern

Clean, sharp aesthetic with subtle shadows and fast animations.

Modern Card

Sharp corners, subtle shadows, fast transitions.

Characteristics:

Smaller border radius for sharp, clean edges
Subtle, diffuse shadows
Fast transitions (150ms)
Modern system fonts

Minimal

Stripped-down aesthetic focusing on content and whitespace.

Minimal Card

No shadows, subtle borders, generous spacing.

Characteristics:

No shadows (replaced with subtle borders)
Very small border radius
Muted color palette
Focus on typography and whitespace

Classic

Traditional, refined aesthetic with generous curves and deeper shadows.

Classic Card

Rounded corners, pronounced shadows, elegant feel.

Characteristics:

Larger border radius for softer edges
Deeper, more pronounced shadows
Slower, more deliberate transitions
Serif font option for headings

Extreme Themes

Extreme themes dramatically transform the entire look and feel. Use these for creative projects, branding, or artistic expression.

Brutalist

Raw, bold, honest design with harsh shadows and monospace typography.

BRUTALIST

Raw, exposed structure. No decoration.

Swiss

Clean, precise, grid-based design inspired by Swiss typography.

SWISS STYLE

Precision. Grid. Typography.

Cyber

Dark, neon cyberpunk aesthetic with glowing effects.

// CYBER

Neon lights in the digital night.

Organic

Warm, flowing design with earthy colors and organic shapes.

Organic Nature

Warm, flowing, handcrafted feel.

Editorial

Elegant magazine aesthetic with refined typography.

Editorial

Classic magazine typography.

Terminal

Green-on-black CRT terminal aesthetic.

root@system:~# TERMINAL

> Retro computing aesthetics.

Kawaii

Japanese cute aesthetic with pastels and playful animations.

Kawaii

Playful, cute, colorful design.

8-bit

Retro pixel art gaming aesthetic.

8-BIT

> PRESS START TO CONTINUE

NES

Console-inspired pixel borders with authentic NES.css aesthetic.

NES

Pixel-perfect retro gaming interface.

Win9x

Classic Windows 95/98 desktop aesthetic with beveled 3D borders.

Win9x

Classic desktop computing interface.

Theme Tools

Want to create your own theme? Use the Theme Composer to build a complete theme from scratch or start from any of the 28 built-in themes. The Composer connects to the Color Schemer, Type Explorer, and Fluid Sizing tools for deeper exploration of each dimension.

Accessibility Themes

Accessibility themes are functional themes that improve usability for users with specific needs. Unlike other themes, these are composable: you can combine them with any decorative theme.

Composable Design

Apply multiple themes together: data-theme="forest a11y-high-contrast a11y-large-text"

High Contrast

WCAG AAA compliant contrast (7:1+) for users who need maximum readability. Removes decorative shadows and simplifies visual elements.

High Contrast Theme

19:1 contrast ratio for body text, 7:1 for muted text.

Links are clearly visible with enhanced underlines.

Features:

Text contrast: 19:1 (body), 7:1+ (muted)
Enhanced 3px focus rings
Shadows disabled for clearer boundaries
Visible borders on all elements
Works in light and dark modes

Large Text

25% larger fonts and 44px minimum touch targets for users with low vision or motor impairments.

Large Text Theme

Base font size is 20px instead of 16px.

Features:

Base font: 20px (25% larger)
Touch targets: 44px minimum (WCAG 2.5.8)
Increased spacing throughout
Generous line height (1.7)
Adjusted content widths for comfortable reading

Dyslexia-Friendly

Typography optimized for readers with dyslexia, using the Atkinson Hyperlegible font and increased spacing.

Dyslexia-Friendly Theme

Atkinson Hyperlegible font with extra letter and word spacing for easier reading.

Similar letters like b d p q and I l 1 are more distinguishable.

Features:

Atkinson Hyperlegible font (free from Braille Institute)
Extra letter spacing (0.05em)
Extra word spacing (0.16em)
Generous line height (1.8)
Shorter line lengths (55ch max)
No italics for emphasis (uses bold instead)

Combining Themes

Accessibility themes work alongside decorative themes using space-separated values:

Forest + High Contrast

Green palette with AAA contrast.

Sunset + Large Text

Warm colors with larger fonts.

Ocean + Dyslexia

Teal palette with readable typography.

Automatic Activation

Vanilla Breeze also responds to user system preferences automatically via CSS media queries:

Media Query	Automatic Enhancement
`prefers-contrast: more`	Increased text and border contrast
`prefers-reduced-transparency`	Removes blur/transparency effects
`forced-colors: active`	Full Windows High Contrast Mode support

These enhancements apply automatically when users enable accessibility settings in their operating system, without requiring any theme attribute.

Dark Mode

Vanilla Breeze automatically adapts to the user's system preference via color-scheme: light dark and the light-dark() CSS function.

Override Mode

Force a specific mode with the data-mode attribute:

Attribute	Effect
`data-mode="light"`	Force light mode
`data-mode="dark"`	Force dark mode
(no attribute)	Follow system preference

Theme + Mode Combinations

Themes can be combined with mode overrides:

Ocean + Light

Ocean + Dark

Dark Mode Adjustments

In dark mode, Vanilla Breeze automatically:

Brightens primary colors for better contrast
Uses deeper shadows with higher opacity
Adjusts surface colors for proper hierarchy

Creating Custom Themes

Create your own brand theme by overriding hue values and optionally recalculating colors.

Basic Color Theme

The simplest approach: override the three hue variables.

/* Custom brand theme */ :root[data-theme="my-brand"], [data-theme="my-brand"] { --hue-primary: 210; /* Blue */ --hue-secondary: 280; /* Purple */ --hue-accent: 45; /* Gold */ /* Recalculate brand colors with new hues */ --color-primary: oklch(50% 0.2 var(--hue-primary)); --color-primary-hover: oklch(from var(--color-primary) calc(l - 0.08) calc(c + 0.02) h); --color-primary-subtle: oklch(from var(--color-primary) 0.95 0.03 h); --color-secondary: oklch(50% 0.08 var(--hue-secondary)); --color-accent: oklch(65% 0.18 var(--hue-accent)); --color-interactive: var(--color-primary); --color-interactive-hover: var(--color-primary-hover); }

Dark Mode Support

Add dark mode adjustments for your custom theme:

/* Dark mode adjustments for your theme */ :root[data-theme="my-brand"][data-mode="dark"], [data-theme="my-brand"][data-mode="dark"] { color-scheme: dark; /* Brighter primary for dark mode contrast */ --color-primary: oklch(65% 0.15 var(--hue-primary)); /* Optional: tinted surfaces */ --color-background: oklch(12% 0.02 var(--hue-primary)); --color-surface: oklch(16% 0.02 var(--hue-primary)); }

Personality Theme

For a complete transformation, override shape, shadows, typography, and motion:

/* Personality theme overrides more than just colors */ :root[data-theme="modern"] { /* Shape */ --radius-s: 0.5rem; --radius-m: 0.75rem; --radius-l: 1rem; /* Shadows */ --shadow-sm: 0 2px 8px oklch(0% 0 0 / 0.08); /* Typography */ --font-sans: "Inter", system-ui, sans-serif; /* Motion */ --duration-normal: 150ms; --ease-default: cubic-bezier(0.2, 0, 0, 1); }

Token Reference

Tokens commonly overridden in themes:

Category	Tokens
Color Hues	`--hue-primary`, `--hue-secondary`, `--hue-accent`
Brand Colors	`--color-primary`, `--color-secondary`, `--color-accent`
Surfaces	`--color-background`, `--color-surface`, `--color-surface-raised`
Border Radius	`--radius-s`, `--radius-m`, `--radius-l`
Shadows	`--shadow-sm`, `--shadow-md`, `--shadow-lg`
Typography	`--font-sans`, `--font-serif`
Motion	`--duration-normal`, `--ease-default`

Fluid Scaling

Add data-fluid to the <html> element to make type sizes and spacing scale continuously across viewports. Instead of breakpoint jumps, values interpolate smoothly from 320px to 1440px using clamp().

<html data-fluid>  <html data-fluid="compact"> <html data-fluid="spacious">  <html data-theme="ocean" data-fluid>

Presets

Preset	Type Ratio	Space Swing	Character
`compact`	1.067 → 1.2	±11%	Tight, uniform hierarchy
`default`	1.125 → 1.25	±10%	Balanced, general-purpose
`spacious`	1.2 → 1.333	±11%	Generous, dramatic headings

Fluid scaling composes with all themes. The a11y-large-text accessibility theme includes its own fluid compound rules so the larger base sizes also scale fluidly.

For custom fluid parameters, see the Fluid Sizing tool and Theme Composer.

Extensions

Theme extensions are opt-in enhancements that add specialized capabilities beyond the core design tokens. They're included in Vanilla Breeze core but default to minimal/disabled values for progressive adoption.

Available Extensions

Motion Effects

Hover transforms, named easing presets, staggered animations, and enter/exit keyframe animations.

Surfaces

Texture overlays, glassmorphism effects, and gradient presets for backgrounds and cards.

Custom Fonts

Font slots for display, heading, body, and code typography with external font support.

Rough Borders

SVG filter displacement and border-image patterns for sketchy, hand-drawn effects.

Sound Effects

Web Audio API patterns for UI feedback sounds with accessibility controls.

Extension Tokens Reference

All extension tokens can be overridden in custom themes. See src/tokens/themes/_theme-template.css for the full list with documentation.

Extension	Key Tokens	Default
Motion Effects	`--motion-hover-lift`, `--motion-bounce`, `--motion-stagger-delay`	Active
Surfaces	`--glass-blur`, `--surface-texture-opacity`, `--gradient-subtle`	Minimal (blur: 0)
Custom Fonts	`--font-display`, `--font-heading`, `--font-body`, `--font-code`	System fonts
Rough Borders	`--border-roughness`, `--filter-rough`, `--shadow-sketch`	Disabled (0)

Theme Picker Integration

The Theme Builder includes an Extensions panel where you can toggle and customize extension features. Changes are applied in real-time and can be exported as CSS.

Using Extensions in Custom Themes

Override extension tokens in your theme to enable or customize features:

/* Custom theme with extensions */ :root[data-theme="my-theme"] { /* Enable glassmorphism */ --glass-blur: 12px; --glass-opacity: 0.2; /* Custom hover behavior */ --motion-hover-lift: translateY(-4px); /* External fonts (load via HTML) */ --font-display: "Playfair Display", Georgia, serif; --font-heading: "Inter", system-ui, sans-serif; }

Wireframe Mode

A design iteration overlay that transforms your production markup into wireframe views at multiple fidelity levels. Toggle it on during design review, then turn it off — your HTML stays unchanged.

Fidelity Levels

Level	Description	Font
`lo`	Sketch aesthetic — rough, hand-drawn feel	Redacted Script
`mid`	Clean blocks — readable structure	Flow Block
`hi`	Near-production — mostly normal with muted chrome	System font
`annotate`	Full design with visible labels on every labeled element	System font

HTML Activation

Labeling Elements

Add contextual labels to any element with data-wf-label. Images auto-use their alt text.

JavaScript API

import { wireframe } from '/src/lib/wireframe.js'; wireframe.toggle('mid'); // Toggle wireframe mode wireframe.setFidelity('lo'); // Set specific fidelity wireframe.label('.hero', 'Hero'); // Label elements programmatically wireframe.isActive(); // Check state

Interactive Demo

Article Title

Sample content demonstrating how wireframe mode abstracts text while preserving layout structure.

Rough Borders

Hand-drawn, sketchy border effects using SVG filters and border-image patterns. Great for wireframe themes, organic aesthetics, or playful designs.

Roughness Levels

Three SVG displacement filters provide increasing levels of roughness:

Light

Subtle wobble (scale: 2)

Medium

Sketchy feel (scale: 4)

Heavy

Torn paper effect (scale: 8)

Usage

/* SVG filter displacement */ .card { filter: url(#vb-rough-medium); } /* Border-image for hand-drawn lines */ .sketch-border { border: 8px solid transparent; border-image: var(--border-image-sketch) 10 stretch; } /* Box-shadow sketch effect */ .sketch-card { box-shadow: var(--shadow-sketch); }

See the full Rough Borders extension demo for all six techniques including mask edges, gradient borders, and pseudo-element decorations.