Vanilla Breeze

Debugging Guide

Troubleshooting common issues with Vanilla Breeze: CSS not loading, custom elements not working, theme problems, and more.

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:
  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.
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.
  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.
  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>, <tab-set> etc. render but don't respond to clicks.

Check these things:

  1. JavaScript is loaded: Check Network tab for vanilla-breeze.js.
  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:
  5. 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:

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:
  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:
  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:
  4. Use CSS layers: Vanilla Breeze uses layers. Put your styles in a higher-priority layer or no layer:
  5. 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:
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

  • Internet Explorer: Not supported. No polyfills provided.
  • Safari < 15.4: Some CSS features like :has() won't work.
  • Older mobile browsers: May have issues with CSS custom properties.

Required Browser Features

Vanilla Breeze uses these modern features:

  • CSS Custom Properties (variables)
  • CSS @layer
  • CSS Nesting
  • OKLCH colors
  • Web Components / Custom Elements v1
  • ES Modules
  • Popover API (with fallback)

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

↑