Quick Start

Get up and running with Vanilla Breeze in minutes. This guide covers installation, basic setup, and core concepts.

Installation

Choose the installation method that works best for your project.

Option 1: CDN (Quickest)

Add Vanilla Breeze directly to any HTML file with no build step required.

Option 2: npm

Install via npm for build tool integration.

Then import in your project:

Option 3: Direct Download

Download the files and include them locally in your project.

Download from GitHub Releases
Extract vanilla-breeze.css and vanilla-breeze.js to your project
Link them in your HTML

Basic Page Setup

Here is a minimal HTML boilerplate with Vanilla Breeze.

Welcome

Your content here.

Add Fonts (Recommended)

Core ships with system fonts for zero network cost. For polished typography, add the foundation font pack — one line, three variable fonts (Inter, Literata, Recursive).

The font pack overrides --font-sans, --font-serif, and --font-mono tokens. Every element that uses those tokens gets upgraded automatically — no additional changes needed.

Two more font packs are available for specialized use:

Display Fonts — Fraunces, Cormorant, Bodoni Moda for editorial and marketing
Expressive Fonts — Nabla, Honk, Kablammo for creative hero sections

Using Design Tokens

Vanilla Breeze provides CSS custom properties (design tokens) for consistent styling. These work automatically with light and dark modes.

Colors

Use semantic color tokens that adapt to the user's theme preference.

Spacing

Use t-shirt size spacing tokens for consistent layouts.

Spacing scale:

xs s m l xl

See the complete Design Tokens documentation for all available tokens.

Styling Native HTML Elements

Vanilla Breeze styles 84+ native HTML elements out of the box. Just use semantic HTML and it looks great.

Buttons

Style variants are applied with simple class names.

Forms and Inputs

Form elements are styled consistently and accessibly.

Name

Tables

Name	Role	Status
Alice Johnson	Developer	Active
Bob Smith	Designer	Active

See the full Elements documentation for all styled elements.

Using Layout Custom Elements

Vanilla Breeze provides CSS-only custom elements for common layout patterns. No JavaScript required.

layout-stack

Vertical stacking with consistent gaps. The fundamental building block for vertical rhythm.

Card 1

Card 2

Card 3

layout-grid

Responsive grid that auto-fits columns based on minimum item width.

Card 1

Card 2

Card 3

layout-cluster

Horizontal grouping with wrapping. Perfect for button groups, tags, and inline items.

Common Attributes

Attribute	Values	Description
`data-gap`	`none`, `xs`, `s`, `m`, `l`, `xl`	Controls spacing between child elements
`data-align`	`start`, `center`, `end`, `stretch`	Controls alignment of child elements

See the full Custom Elements documentation for all layout elements.

Adding Web Components for Interactivity

For interactive features, Vanilla Breeze provides JavaScript web components. These require the JS bundle.

Accordion

Collapsible content sections with proper ARIA support.

What is Vanilla Breeze?

Vanilla Breeze is a layered HTML component system. Build with native HTML, enhance with CSS, add interactivity with JavaScript - each layer optional.

Do I need JavaScript?

No! The CSS-only layers work without JavaScript. Add JS only when you need interactive components.

Tabs

Tabbed interface for organizing content.

HTML

Write semantic HTML5 markup. Vanilla Breeze styles it automatically.

CSS

Use CSS custom properties (design tokens) for consistent styling.

JavaScript

Add JavaScript only when you need interactive components.

Icons

Access 200+ Lucide icons with the icon-wc component.

Progressive Enhancement Philosophy

Vanilla Breeze is built on progressive enhancement. Each layer adds capabilities without breaking the previous layer.

The Three Layers

Layer 1: HTML

Start with semantic HTML5. Content is accessible and functional with no styling.

Layer 2: CSS

Add styling with design tokens and CSS custom elements. Works without JavaScript.

Layer 3: JavaScript

Enhance with web components for interactivity. Gracefully degrades if JS fails.

Why This Matters

Resilience: If CSS or JS fails to load, content remains accessible
Performance: Critical content renders without waiting for JS
SEO: Search engines can index all content
Accessibility: Screen readers and assistive tech work on all layers

Next Steps

Now that you understand the basics, explore more: