Shadow DOMtokenscoping rules.

1. Load token values once, in the document

   T01PROBECHECKER

   Custom properties inherit through every shadow boundary, so one token stylesheet on the page reaches every component. Importing tokens inside each shadow root duplicates them and breaks theme switching.

   Evidence: P01 reads the :root value inside a shadow root. SD10 flags @import in component CSS.

   CSS Shadow: the flat tree is used for inheritance (S01); Lit styles docs (S02).

2. Components read semantic tokens only

   T02CHECKER

   --ds-color-bg-brand, never --ds-core-color-blue-600. A component may read its own component tokens (--ds-comp-button-*) and no one else's. The layering is Field Guide 03's, unchanged by the shadow root.

   Evidence: SD04 flags --ds-core-* and other components' --ds-comp-*.

   Field Guide 03, rules R11 and R13.

3. A component never sets a global token

   T03CHECKERSPEC

   Slotted elements inherit from their slot, not from their light-DOM parent. A button that sets --ds-color-text-default on :host re-themes the consumer's own markup slotted into it.

   Evidence: SD05 flags any --ds-* declaration that is not the component's documented hook.

   CSS Shadow: elements assigned to a slot inherit from that slot (S01).

4. Private state lives in --_ properties on :host

   T04CHECKER

   Variants switch private properties (--_bg, --_fg); the inner elements read only those. One place per variant, and no name that can collide with the page.

   Evidence: SD06 flags a custom property that is neither --_* nor --<tag>-*.

   Lea Verou, pseudo-private custom properties (S14).

5. No raw colours or lengths

   T05CHECKER

   No hex, no colour functions, no named colours, no px or rem in spacing, sizing, radius, border, outline or font size. transparent, currentColor, 0, em and percentages stay allowed.

   Evidence: SD01 and SD02. The clean example and the Field Guide 15 styles pass with zero findings.

   Field Guide 03, rule R15, applied inside the shadow root.

6. System colours only in forced-colors mode

   T06CHECKER

   ButtonText, Canvas and the other system colours belong inside @media (forced-colors: active). Elsewhere they bypass the theme.

   Evidence: SD01 allows system colours only inside the forced-colors block.

   Kit rule.

7. No literal fallbacks in var()

   T07CHECKER

   var(--ds-radius-control, 6px) copies today's value into the component and hides a missing token sheet. Fall back to another token or not at all, so a broken theme fails loudly in review.

   Evidence: SD03 flags a fallback that is not itself a var().

   Recommended practice.

8. Do not register tokens with inherits: false

   T08PROBECHECKER

   A registered property that does not inherit stops at every boundary, and browsers honour @property only from the document. Register tokens in the document with inherits: true, or not at all.

   Evidence: P06 shows 0px (the initial value) inside the shadow root; P07 shows a shadow-root @property ignored. SD10 flags @property in component CSS.

   MDN @property; the spec says registrations are global, but csswg issue 10541 records that browsers disagree (S05, S06, S07).

9. Reset with all, knowing tokens survive it

   T09PROBE

   all: unset on the inner control removes browser button styles and leaves every custom property in place, because all does not reset custom properties.

   Evidence: P05: the token is still readable after all: unset.

   MDN all (S04).

The page owns the theme. The component only reads it.

1. No global selectors in component CSS

   T10CHECKERPROBE

   :root, html, body and a bare * match nothing useful inside a shadow root. Style the host with :host and the internals by their own selectors.

   Evidence: SD07. P04: a :root rule inside the shadow root matches nothing.

   Selectors are limited to a single tree (S01).

2. Theme by tokens on an ancestor, not :host-context()

   T11CHECKERKIT TEST

   :host-context() is Chromium-only: Firefox and Safari do not support it, and MDN marks it deprecated. Switch the theme by changing token values on an ancestor such as [data-theme].

   Evidence: SD08. Field Guide 15 test "follows the theme without re-rendering" flips data-theme and reads the new brand colour.

   MDN :host-context and browser-compat-data (S09).

3. Style slotted content lightly, with compound selectors

   T12CHECKERPROBE

   ::slotted() takes one compound selector and matches only top-level slotted elements; slotted nodes belong to the page, whose rules win. Use it for spacing and icon size, not for typography the consumer controls.

   Evidence: SD11. P12: ::slotted(span b) matches nothing.

   MDN ::slotted; CSS Cascade 5 context (S12, S08).

4. Ship your own minimal reset

   T13PROBE

   The page's reset, utility classes and component classes never reach inside. Put a small reset in @layer reset in each component, not a copy of the page's.

   Evidence: P03: a page class selector does not match an inner element with the same class.

   S01, S02, S03.

5. Fonts are declared in the document

   T14CHECKERPROBE

   @font-face inside a shadow root is unreliable (a long-standing Chromium issue). Declare fonts in the page; font-family then inherits into every component, or read it from a token.

   Evidence: SD10 flags @font-face in component CSS. P16: a font family set on body reaches shadow text.

   S01, S17.

What the page cannot select, it cannot break.

1. :host styles are defaults the page can override

   T15CHECKERPROBE

   For normal declarations the outer context wins, whatever the specificity. !important inside the shadow root reverses that and takes the override away.

   Evidence: P08: page beats :host. P09: :host !important beats the page. SD09.

   CSS Cascade 5, context (S08).

2. Expose parts by role, and document them

   T16SPECKIT TEST

   part="control" on the native button, @csspart control in the JSDoc, so the manifest and Storybook list it.

   Evidence: The Field Guide 15 manifest lists one part, control. P11: the page styles it with ::part(control).

   MDN ::part (S10).

3. Forward nested parts with exportparts

   T17SPEC

   ::part() cannot be chained, so a nested component's part is unreachable unless the outer one forwards it: exportparts="control: button-control".

   Evidence: Every nested part a consumer needs is in the outer exportparts and manifest.

   MDN ::part, exportparts (S10, S11).

4. Public hooks are --<tag>-*, default to a token

   T18CHECKERPRACTICE

   var(--ds-button-radius, var(--ds-radius-control)): the name says who owns it, @cssprop documents it, the default keeps the theme in charge.

   Evidence: SD06 allows --ds-button-* only in ds-button; SD03 allows the token fallback.

   Web Awesome scopes component properties per component (S15).

5. A theme changes tokens, not parts

   T19PRACTICE

   Parts are per-component escape hatches. A theme that reaches for ::part() across components has become a second design system.

   Evidence: Theme files contain token declarations only.

   CSS Shadow on ::part() (S01); Shoelace token guidance (S16).

Three levels of override, and each one is written down.

1. Order component CSS with @layer

   T20PROBE

   @layer reset, component, state; keeps state styles winning over variants without specificity games. The page's layer order does not apply inside.

   Evidence: P13: the page's @layer b, a order does not reach inside.

   CSS Cascade 5: layers are scoped to their context (S08).

2. Share one stylesheet across instances

   T21PROBESPEC

   A constructed stylesheet adopted by many shadow roots is parsed once and updates everywhere. Lit's static styles does this.

   Evidence: P14: one replaceSync updates both adopting roots.

   MDN adoptedStyleSheets, Baseline 2023; Lit styles (S13, S02).

3. Budget for style duplication in server rendering

   T22KIT TEST

   Declarative shadow DOM repeats the styles in every server-rendered instance: 2,671 of 3,087 bytes per ds-button. Declarative sharing is only in a Chrome origin trial.

   Evidence: npm run ssr in the Field Guide 15 starter.

   Kit run; blink-dev intent to experiment (S19).

4. Set color-scheme with the theme

   T23PROBE

   color-scheme inherits into shadow roots, so light-dark() and native controls inside follow the theme.

   Evidence: P15: light-dark() picks the dark value when the host has color-scheme: dark.

   MDN light-dark() (S18).

5. Every animation has a reduced-motion answer

   T24CHECKER

   Spinners and transitions live inside the component, so the reduced-motion override must too.

   Evidence: SD12 warns when a stylesheet animates without a prefers-reduced-motion block.

   Kit rule; WCAG 2.2 SC 2.3.3 (AAA) intent.

Parse once, share everywhere, and measure what the server sends.

Maintenance: re-run the probe in every supported browser at each major release and update Appendix C. Recheck csswg issue 10541 (@property scoping) and the declarative stylesheet origin trial; if either lands, rules T08 and T22 change. Update the PDF, HTML, Markdown and JSON together.