Toolbox

Shadow DOM token scoping rules

Let tokens into shadow roots and keep styles from leaking: 24 rules, a 12-check linter for CSS and Lit templates, and a browser probe.

What it is

Field Guide 14: 24 rules for web components that read design tokens as CSS custom properties through the shadow boundary without redefining the theme or leaking selectors. The kit has a zero-dependency checker that reads plain CSS and Lit css templates (12 checks: 17 errors and 1 warning on the failing example, none on the clean one), a document-level CSS example and a 16-row probe page that shows what crosses a shadow boundary in any browser.

When to use

When building or auditing web components that consume a token system, before opening a styling API with parts and custom properties, or when a theme change does not reach inside components.

How to use

Open boundary-probe.html in every browser you support and compare with Appendix C
Run node scripts/check-shadow-css.mjs on your components folder
Fix raw values, redefined tokens and global selectors first
Move fonts, @property and token values into the document stylesheet
Document each part and --tag-* hook, then add the checker to CI

Before you start

Prerequisites and when to skip this.

Prerequisites

Components that render into shadow roots
Design tokens delivered as CSS custom properties

When NOT to use this

Light-DOM custom elements with no shadow root (page CSS applies directly)
A library still choosing between shadow DOM and framework components

Consider instead

You need the token layering itself, not the shadow boundary rules: Use Token layer rules (Field Guide 03) for the core, semantic and component layers

Downloads

Guide (PDF)Full kit (ZIP): checker, examples, boundary probe

Framework decision matrixLit and Storybook starterWeb Components for design systems: when and why

The share link includes source tracking so LinkedIn traffic stays measurable in analytics.

Share on LinkedIn