Packs

Mental Model

Vanilla Breeze core ships tokens, layouts, and web components. A pack extends this with:

All three layers are optional. A pack can ship just a theme, just effects, just components, or any combination.

Token Inheritance

This is the key insight: pack components consume the same tokens as core. When you switch from data-theme="retro" to data-theme="ocean", every pack component re-renders with ocean's colors, fonts, and spacing. No code changes needed.

Loading a Pack

CDN (static)

Load the full pack alongside core:

Granular Loading

Load only the parts you need:

Runtime Activation

Load a pack dynamically from JavaScript:

activateBundle injects a <link> for the CSS and import()s the JS. It returns a Promise that resolves when both are loaded.

Layer Architecture

Vanilla Breeze uses CSS @layer to manage cascade priority. Pack layers sit after core layers, ensuring pack styles always win over core defaults without specificity battles:

When no pack is loaded, the three bundle layers are empty declarations — zero cost.

Pack Anatomy

An aesthetic pack lives in src/packs/{name}/ and follows a strict file convention:

The build pipeline produces granular and combined outputs:

Theme File

The theme file overrides core tokens inside a @layer bundle-theme block, scoped by a [data-theme~="name"] selector:

Because it uses the ~= (word match) selector, users can combine themes: data-theme="retro dark".

Writing Effects

CSS Effects

CSS effects are data-* attribute selectors in the bundle-effects layer. They must:

• Scope custom properties to their own selector (no :root pollution)
• Consume core tokens via var(--color-primary) so they adapt to theme changes
• Provide prefers-reduced-motion and [data-motion-reduced] overrides
• Include @media print resets

JS Effects

JS effects use the registerEffect API. The pack registry provides a shared MutationObserver that auto-initializes effects on dynamically added elements:

Writing Components

Registration

Components use registerComponent for priority-based conflict resolution. Since customElements.define() is permanent, the registry uses first-wins semantics with priority tiebreaking:

Token Contract

Every pack component documents which tokens it consumes and which it exposes. This makes the dependency chain explicit and enables tooling:

Usage

Component Rules

1. Shadow DOM required — isolates component styles from the page
2. ::part() API — expose named parts for external styling
3. Consume tokens, not hard values — use var(--color-primary) not oklch(70% 0.28 145)
4. Progressive enhancement — slot a native <audio> for JS-off fallback
5. Static metadata — declare bundle, contract, version, token arrays

Available Packs

Try the packs in the interactive explorer, or load them individually in your projects.

Functional Packs

Add capabilities beyond core. Work with any theme.

Font Packs

Opt-in variable font bundles. One file per typographic role — no multi-weight loading.

Full Packs

Theme + effects + components — a complete visual identity in one package.

Try Them

Next Steps