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.

<link rel="stylesheet" href="https://unpkg.com/vanilla-breeze/dist/cdn/vanilla-breeze.css">  <script type="module" src="https://unpkg.com/vanilla-breeze/dist/cdn/vanilla-breeze.js"></script>

Option 2: npm

Install via npm for build tool integration.

npm install vanilla-breeze

Then import in your project:

// Import CSS import 'vanilla-breeze/css'; // Import JS (optional) import 'vanilla-breeze';

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.

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>My Vanilla Breeze Page</title> <link rel="stylesheet" href="https://unpkg.com/vanilla-breeze/dist/cdn/vanilla-breeze.css"> </head> <body> <header> <h1>Welcome</h1> </header> <main> <layout-stack data-layout-gap="l"> <p>Your content here.</p> <button type="button">Get Started</button> </layout-stack> </main> <footer> <p>© 2026 Your Name</p> </footer>  <script type="module" src="https://unpkg.com/vanilla-breeze/dist/cdn/vanilla-breeze.js"></script> </body> </html>

Welcome

Your content here.

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.

.my-card { /* Semantic colors adapt to light/dark mode */ background: var(--color-surface); color: var(--color-text); border: var(--border-width-thin) solid var(--color-border); } .my-button { /* Interactive colors for buttons and links */ background: var(--color-interactive); } .my-button:hover { background: var(--color-interactive-hover); }

Spacing

Use t-shirt size spacing tokens for consistent layouts.

.my-section { /* T-shirt sizes: 3xs, 2xs, xs, s, m, l, xl, 2xl, 3xl */ padding: var(--size-l); margin-block-end: var(--size-xl); gap: var(--size-m); }

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.

<button type="button">Primary</button> <button type="button" class="secondary">Secondary</button> <button type="button" class="ghost">Ghost</button> <button type="button" disabled>Disabled</button>

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-stack data-layout-gap="m"> <layout-card>Card 1</layout-card> <layout-card>Card 2</layout-card> <layout-card>Card 3</layout-card> </layout-stack>

layout-grid

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

Card 1

Card 2

Card 3

<layout-grid data-layout-min="150px" data-layout-gap="m"> <layout-card>Card 1</layout-card> <layout-card>Card 2</layout-card> <layout-card>Card 3</layout-card> </layout-grid>

layout-cluster

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

<layout-cluster data-layout-gap="s"> <button type="button">Save</button> <button type="button" class="secondary">Cancel</button> <button type="button" class="ghost">Reset</button> </layout-cluster>

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.

<accordion-wc> <details> <summary>What is Vanilla Breeze?</summary> <p>A layered HTML component system...</p> </details> <details> <summary>Do I need JavaScript?</summary> <p>No! The CSS-only layers work without JavaScript...</p> </details> </accordion-wc>

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.

<tabs-wc> <details open name="quick-start-tabs"> <summary>HTML</summary> <p>HTML content here...</p> </details> <details name="quick-start-tabs"> <summary>CSS</summary> <p>CSS content here...</p> </details> <details name="quick-start-tabs"> <summary>JavaScript</summary> <p>JavaScript content here...</p> </details> </tabs-wc>

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: