Debugging Guide

Having trouble with Vanilla Breeze? This guide covers common issues and how to fix them.

CSS Issues

Styles aren't loading at all

Symptoms: Page looks unstyled, elements have browser defaults.

Check these things:

  1. Is the CSS file loading? Open DevTools Network tab, filter by CSS, and look for vanilla-breeze.css. Check for 404 errors.
  2. Is the path correct? For CDN usage: <link rel="stylesheet" href="https://unpkg.com/vanilla-breeze/dist/cdn/vanilla-breeze.css">
  3. Is the link tag in the head? CSS must be in <head>, not <body>.
  4. Check the console for errors. CSS parse errors will appear there.
Some styles work but others don't

Symptoms: Basic elements styled, but layout elements or tokens don't work.

Possible causes:

  1. You might be using an old cached version. Hard refresh with Cmd/Ctrl + Shift + R.
  2. CSS custom properties aren't inherited. Make sure you're not setting all: initial on parent elements.
  3. Check if layers are supported. Vanilla Breeze uses @layer. Very old browsers may not support this.
CSS variables show as invalid

Symptoms: DevTools shows custom properties as invalid or crossed out.

Check these things:

  1. Spelling: Token names are case-sensitive. Use var(--color-text) not var(--Color-Text).
  2. Correct prefix: Size tokens use --size-, not --space-.
  3. Browser DevTools issue: Some browsers incorrectly mark valid OKLCH colors as invalid. The colors still work.

Reference the Design Tokens documentation for exact token names.

Custom Elements (CSS-Only)

Layout elements have no effect

Symptoms: <layout-stack>, <layout-grid> etc. don't apply layout.

Check these things:

  1. CSS is loaded: Custom elements are styled purely with CSS. No JavaScript needed, but the CSS must be loaded.
  2. Check the element in DevTools: Select the element and look at computed styles. You should see display: flex or display: grid.
  3. Data attributes are correct: Use data-layout-gap="m" not gap="m" or class="gap-m".
  4. Valid values: Gap accepts t-shirt sizes (xs, s, m, l, xl), not arbitrary values.
<!-- Correct --> <layout-stack data-layout-gap="m"> <p>Child 1</p> <p>Child 2</p> </layout-stack> <!-- Wrong: missing data- prefix --> <layout-stack gap="m">...</layout-stack> <!-- Wrong: invalid value --> <layout-stack data-layout-gap="20px">...</layout-stack>
layout-grid doesn't create columns

Symptoms: Items stack vertically instead of forming a grid.

Check these things:

  1. Container is too narrow: layout-grid uses auto-fit with a minimum item width. If the container is narrower than data-min, items will stack.
  2. Set data-min correctly: The value should be a CSS length. <!-- Items need at least 200px each --> <layout-grid data-layout-min="200px" data-layout-gap="m"> <div>Item</div> <div>Item</div> <div>Item</div> </layout-grid>
  3. Resize your window: Narrow viewports may legitimately show single column.
Elements show but have wrong styling

Symptoms: Custom element renders but doesn't match expected appearance.

Check these things:

  1. Attribute values are quoted: HTML attribute values with special characters need quotes. <layout-grid data-layout-min="200px">
  2. Parent styles interfering: Check if parent has display: contents or all: unset that might override.
  3. CSS specificity conflict: See the Specificity section below.

Web Components (JavaScript)

Web component doesn't work / not interactive

Symptoms: <accordion-wc>, <tabs-wc> etc. render but don't respond to clicks.

Check these things:

  1. JavaScript is loaded: Check Network tab for vanilla-breeze.js. <script type="module" src="https://unpkg.com/vanilla-breeze/dist/cdn/vanilla-breeze.js"></script>
  2. Check console for errors: JavaScript errors prevent components from initializing.
  3. Script must be type="module": Web components use ES modules.
  4. Check if component is defined: In console, type: customElements.get('accordion-wc') // Should return the class, not undefined
Component works but animations are jerky

Symptoms: Accordion/tabs animate but not smoothly.

Possible causes:

  1. prefers-reduced-motion is set: Animations are disabled when the user has requested reduced motion. This is intentional.
  2. Heavy content: Complex content inside animated regions may cause jank. Consider simplifying.
  3. Browser DevTools open: DevTools can slow down animations. Try with DevTools closed.
Icons don't appear

Symptoms: <icon-wc> elements are empty or show wrong icon.

Check these things:

  1. JavaScript is loaded: Icons require the JS bundle.
  2. Icon name is valid: Icons use Lucide names. Check the icon documentation for available names. <!-- Valid icon names --> <icon-wc name="home"></icon-wc> <icon-wc name="search"></icon-wc> <icon-wc name="settings"></icon-wc> <!-- Invalid: wrong name --> <icon-wc name="house"></icon-wc> <!-- Use "home" -->
  3. Inspect the element: The shadow DOM should contain an SVG.
Dropdown opens in wrong position

Symptoms: Dropdown menu appears offset or in unexpected location.

Possible causes:

  1. Parent has transform: CSS transforms create new containing blocks. Dropdowns may position relative to transformed ancestor.
  2. Overflow hidden on parent: If a parent has overflow: hidden, the dropdown may be clipped.
  3. Try different position: <drop-down data-position="bottom-start"> <drop-down data-position="bottom-end"> <drop-down data-position="top-start">

Theme Issues

Dark mode doesn't work

Symptoms: Page stays in light mode regardless of system preference.

Check these things:

  1. System preference: Open System Preferences and check your appearance setting.
  2. Manual override: If using theme-picker, it may have stored a preference. Try clearing localStorage: localStorage.removeItem('vb-theme'); location.reload();
  3. Check html attribute: The <html> element should have data-theme="dark" when in dark mode.
Colors look wrong in dark mode

Symptoms: Text is hard to read or colors don't look right in dark mode.

Check these things:

  1. Using hardcoded colors: If you've written custom CSS with hardcoded colors, they won't adapt. Use semantic tokens: /* Good: adapts to dark mode */ color: var(--color-text); background: var(--color-surface); /* Bad: doesn't adapt */ color: #333; background: white;
  2. Custom theme issue: If you've created a custom theme, verify dark mode variants are defined.
Theme picker doesn't persist

Symptoms: Selected theme resets on page reload.

Check these things:

  1. JavaScript loaded: Theme persistence requires the JS bundle.
  2. localStorage access: If in private/incognito mode, localStorage may be restricted.
  3. Check localStorage: console.log(localStorage.getItem('vb-theme')); // Should show your selected theme

CSS Specificity

My custom styles aren't applying

Symptoms: You've written custom CSS but Vanilla Breeze styles take precedence.

Solutions:

  1. Load your CSS after Vanilla Breeze: <!-- Vanilla Breeze first --> <link rel="stylesheet" href="vanilla-breeze.css"> <!-- Your styles second --> <link rel="stylesheet" href="my-styles.css">
  2. Use CSS layers: Vanilla Breeze uses layers. Put your styles in a higher-priority layer or no layer: /* Your styles outside layers win */ button.my-button { background: purple; } /* Or define your layer after VB's layers */ @layer vb, my-overrides; @layer my-overrides { button.my-button { background: purple; } }
  3. Avoid !important: It works but creates maintenance headaches. Prefer proper cascade management.
Styles work in dev but not production

Symptoms: Local development looks right, but production build has style issues.

Check these things:

  1. CSS order changed: Build tools may reorder CSS. Ensure Vanilla Breeze loads first.
  2. CSS purging: Tools like PurgeCSS may remove "unused" CSS. Configure to keep Vanilla Breeze classes and custom elements.
  3. Minification issues: Some minifiers don't handle modern CSS well. Test with minification disabled.

Build Tool Issues

Vite/Webpack can't find the package

Symptoms: Build error about missing module or unresolved import.

Note: npm package is available. For CDN usage:

<!-- In your HTML --> <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>
Custom elements not working with SSR

Symptoms: Server-rendered pages don't style custom elements.

Solutions:

  1. CSS-only elements work: <layout-stack> etc. work server-side because they're pure CSS.
  2. Web components need client JS: Components like <accordion-wc> enhance on the client. The native HTML (<details>) works before JS loads.
  3. Check Astro/Eleventy integration: See the integration guides for framework-specific instructions.

Browser Support

Vanilla Breeze targets modern evergreen browsers:

Browser Supported Versions
Chrome Last 2 versions
Firefox Last 2 versions
Safari Last 2 versions
Edge Last 2 versions

Known Limitations

Required Browser Features

Vanilla Breeze uses these modern features:

Still Stuck?

If this guide didn't solve your problem:

  1. Search existing issues: Someone may have had the same problem. Check GitHub Issues.
  2. Create a minimal reproduction: Isolate the problem in the simplest possible example.
  3. Open a new issue: Include browser, OS, steps to reproduce, and expected vs. actual behavior.

Open an Issue