4.63.0

Using Skylab SDK with shadow DOM

Skylab SDK is designed to work without per-shadow-root setup. Load skylab-sdk.css once from your app's outer <head> and Skylab's design tokens, theming, and fonts cascade into every shadow root your app (or its dependencies) creates — including any Skylab components mounted inside a shadow tree.

Add the standard Skylab <link> and <script> tags to the outer document. This is the same setup described in our Best practices and is what App Archetype provides out of the box.

No additional code is required when you attach a shadow root and place Skylab components inside it. Components mounted in shadow trees pick up the same T1 palette, T2 semantic tokens, T3 component tokens, and the active theme from the document-level cascade.

Why no per-shadow-root setup is needed

Three browser features combine to make this work:

  • CSS custom properties inherit through shadow boundaries. Skylab sets all of its tokens on :root (i.e. <html>), so every descendant — in the light DOM or inside any shadow root — sees the inherited values.
  • Theme switching is driven by a single attribute on <html>. The <s-theme-provider> element toggles data-sk-theme="dark" on the document root, which flips :root[data-sk-theme='dark'] in skylab-sdk.css and re-binds every T2 token. Those new values inherit straight through every shadow root with no extra plumbing.
  • @font-face declarations are scoped to a Document, not to individual style scopes. The fonts shipped in skylab-sdk.css are visible to text rendered anywhere in the page, including inside shadow trees.

Loading Skylab CSS only inside a shadow root is not supported

Attaching skylab-sdk.css only to a shadow root (without also loading it in the outer document) does not work. Skylab's semantic-token defaults and the data-sk-theme theming trigger are scoped to :root, and inside a shadow tree :root matches nothing — the shadow root is a DocumentFragment, not a Document. Components inside the shadow root would be missing T2 semantic tokens entirely, and the light/dark switch would have no effect.

If your app cannot include skylab-sdk.css in the outer <head>, please reach out on the #skylab Slack channel so we can discuss the integration constraints.