Diagnosing StencilJS Shadow DOM Styling and CSS Variable Issues

Recognizable Condition

Component styles are missing, global CSS leaks into the shadow tree, or CSS variables defined at :root or :host-context() do not cross the shadow boundary. Symptoms include unstyled elements, unexpected inheritance, or theme switching having no effect inside the component. This occurs with shadow: true (the default) across output targets www, dist, and dist-custom-elements.

Cause and Diagnostic Table

Ordered Diagnostic Checks

1. Confirm @Component({ shadow: true, styleUrl: './comp.css' }) — shadow defaults to true but verify explicitly.
2. Open DevTools, expand the component element, confirm #shadow-root exists and contains a <style> with your rules.
3. In Console run document.querySelector('my-comp').shadowRoot.querySelector('style').textContent to see applied CSS.
4. Check Computed styles on an inner element for expected CSS variable values.
5. Verify build output: ls dist/custom-elements/my-comp.css and ls www/build/my-comp/entry.js for inline styles.
6. Test :host { --primary: red } inside component CSS vs setting on :root in global CSS.

Fixes Tied to Findings

Shadow DOM and Style Configuration

• Wrong styleUrl path → Correct relative path from component .tsx file.
• Shadow disabled → Remove shadow:false or set shadow:true; use shadowDelegatesFocus for focus management if needed.
• CSS variable not crossing boundary → Define variable on :host in component CSS or on parent with :host-context(.theme-dark) { --var: val }.

Output Target Configuration

• dist-custom-elements missing CSS → Ensure outputTargets includes:

  { type: 'dist-custom-elements', externalRuntime: false, copy: [{ from: 'globals.css', to: 'globals.css' }] }

  Import globals via @import in component CSS.
• Global styles needed inside shadow → Use ::part() on slotted elements or adopt Constructible Stylesheets (Stencil 3.2+) via this.shadowRoot.adoptedStyleSheets = [sheet].

Escalation Criteria

Escalate when:

1. Styles work in www but absent in dist-custom-elements despite correct config — possible rollup-plugin-stencil bug.
2. CSS variable inheritance differs across Chrome, Firefox, Safari shadow DOM — file browser bug if spec violation.
3. AdoptedStyleSheets cause FOUC or memory leak — profile with Chrome DevTools Memory panel.
4. SSR HTML shows style mismatch on hydration — verify @stencil/core/server renderToString includes inline critical CSS.

Verification Steps

1. Create minimal reproduction: npm init stencil@latest test-shadow, add component with shadow: true, styleUrl, CSS variable on :host, and global CSS on :root. Run npm run build and npm run dev, inspect shadowRoot styles in each output target.
2. Check Stencil version: npx stencil --version — behavior consistent since 2.13 for shadow DOM, but dist-custom-elements CSS handling refined in 3.0+.
3. Validate output targets in stencil.config.ts: ensure www, dist, dist-custom-elements all produce expected .css files; diff file sizes.
4. Test cross-browser: open dev build in Chrome, Firefox, Safari; verify CSS variable inheritance and ::part() styling parity.
5. Profile hydration: add ?hydrate to dev URL, check Network tab for style requests, and Performance tab for style recalculation cost.

Limitations and Cautions

• Stencil 2.x vs 3.x: dist-custom-elements output changed default externalRuntime behavior; verify migration guide for your version.
• CSS variable fallback syntax var(--token, fallback) works inside shadow but fallback only used if variable undefined in shadow tree, not from light DOM.
• ::part() only styles elements with explicit part attribute; cannot style arbitrary descendants inside shadow root.
• Hot module replacement (HMR) in Stencil dev server may cache old shadow styles; hard refresh or restart dev server after styleUrl changes.
• Using @import in component CSS resolves relative to component file at build time; imported file must be in same repo or copied via copyTasks.
• Server-side rendering with @stencil/core/server requires inlineCriticalCss: true in hydrateApp options to avoid flash of unstyled content.