@skra/ui 0.2.0 → 0.3.1

package/consumer-guide/setup-and-gotchas.md

@@ -1,103 +1,165 @@
-# Setup & Gotchas
-
-> Load this for: first integration, import errors, "which package exports what", and the
-> boolean-attribute / inline-style pitfalls. Core rules live in `README.md` — this is the detail.
-
-## Public entry points (`@skra/ui/*`)
-
-Import **only** from these. Never a deep `libs/ui/...` path (not part of the public API;
-will break on any internal refactor). Skra ships as **one package, `@skra/ui`**, with a
-secondary entry point per component (ADR 0054 / O-31 consolidation). The primary `@skra/ui`
-entry exports nothing — always import from a `@skra/ui/<entry>` subpath.
-
-| Entry point                  | Exports (representative)                                                                                                              |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `@skra/ui/button`            | `button[skraButton]`                                                                                                                 |
-| `@skra/ui/link`              | `a[skraLink]`                                                                                                                        |
-| `@skra/ui/icon`              | icon container atom                                                                                                                   |
-| `@skra/ui/typography`        | `[skraTypography]`                                                                                                                   |
-| `@skra/ui/layout`            | `[skraStack]`, `[skraBox]`, `[skraGrid]`                                                                                           |
-| `@skra/ui/kbd`               | `kbd[skraKbd]`                                                                                                                       |
-| `@skra/ui/field`             | `<skra-field>`, `[skraLabel]`, `[skraHint]`, `[skraError]`, `fieldset[skraFieldset]`, `legend[skraLegend]`, `SkraFieldContext` |
-| `@skra/ui/input`             | `input[skraInput]`                                                                                                                   |
-| `@skra/ui/textarea`          | `textarea[skraTextarea]`, auto-resize                                                                                                |
-| `@skra/ui/checkbox`          | `input[skraCheckbox]`                                                                                                                |
-| `@skra/ui/radio`             | `input[skraRadio]`                                                                                                                   |
-| `@skra/ui/switch`            | `input[skraSwitch]`                                                                                                                  |
-| `@skra/ui/counter`           | `skra-counter`                                                                                                                       |
-| `@skra/ui/star-rating`       | `skra-star-rating`                                                                                                                   |
-| `@skra/ui/native-select`     | `select[skraSelect]` (`SkraNativeSelect`)                                                                                           |
-| `@skra/ui/dialog`            | `dialog[skraDialog]`                                                                                                                 |
-| `@skra/ui/tooltip`           | `[skraTooltip]`                                                                                                                      |
-| `@skra/ui/popover`           | `skra-popover`                                                                                                                       |
-| `@skra/ui/menu`              | `skra-menu`, `skra-menu-item`                                                                                                       |
-| `@skra/ui/select`            | `skra-select` (+ `SkraOption` & option directives, re-exported)                                                                     |
-| `@skra/ui/multi-select`      | `skra-multi-select` (+ `SkraOption` & option directives, re-exported)                                                               |
-| `@skra/ui/combobox`          | `skra-combobox` (+ `SkraOption` & option directives, re-exported)                                                                   |
-| `@skra/ui/datepicker`        | `skra-datepicker`                                                                                                                    |
-| `@skra/ui/alert`             | `skra-alert`                                                                                                                         |
-| `@skra/ui/badge`             | `skra-badge`                                                                                                                         |
-| `@skra/ui/chip`              | `skra-chip`                                                                                                                          |
-| `@skra/ui/toast`             | `skra-toast`, `skra-toast-region`                                                                                                   |
-| `@skra/ui/tabs`              | `[skraTabs]`, `[skraTablist]`, `button[skraTab]`, `[skraTabPanel]`                                                                |
-| `@skra/ui/accordion`         | `[skraAccordion]` family                                                                                                             |
-| `@skra/ui/progress`          | `progress[skraProgress]`                                                                                                             |
-| `@skra/ui/skeleton`          | `skra-skeleton`                                                                                                                      |
-| `@skra/ui/loading-indicator` | `[skraLoadingIndicator]`                                                                                                             |
-| `@skra/ui/avatar`            | `skra-avatar`                                                                                                                        |
-| `@skra/ui/status-dot`        | `skra-status-dot`                                                                                                                    |
-| `@skra/ui/rating-display`    | `skra-rating-display`                                                                                                                |
-
-> `@skra/ui/core` exists for cross-component shared satellites (`SkraOption` & option
-> directives, `SkraSelectTrigger`, `SKRA_LISTBOX_PANEL`). Prefer the re-exports from
-> `select` / `multi-select` / `combobox`; you rarely import `core` directly.
->
-> `@skra/shadow-dom-bridge` is a delivery utility, not a component — see
-> `theming-and-encapsulation.md`.
-
-## Gotcha 1 — boolean attributes: write the bare form
-
-Skra boolean inputs carry `{ transform: booleanAttribute }` (lint-enforced across `libs/ui`
-by `boolean-input-validator.mjs`), so the **native bare attribute works** — write it the
-HTML-idiomatic way:
-
-```html
-<skra-toast dismissible>…</skra-toast>
-<!-- ✓ -->
-<div skraStack wrap>…</div>
-<!-- ✓ -->
-```
-
-`[dismissible]="true"` also compiles but is unnecessary. (Historically the transform was
-missing and the bare form broke under `strictTemplates` — F-18; closed library-wide in
-session 10, so the workaround is no longer needed.)
-
-## Gotcha 2 — never style with inline `style` or `[style.--var]`
-
-Skra reflects state as `data-skra-*` attributes and maps them to tokens in CSS (ADR 021,
-CSP-safe). To override a token for a subtree, scope it with a **CSS class or a data-attribute
-on an ancestor**, never inline:
-
-```html
-<!-- ✗ CSP-violating, and not how the token cascade is meant to work -->
-<skra-badge style="--skra-comp-badge-background: red">…</skra-badge>
-
-<!-- ✓ scope on an ancestor, in a stylesheet -->
-<div class="danger-zone"><skra-badge>…</skra-badge></div>
-```
-
-```css
-.danger-zone {
-  --skra-comp-badge-background: var(--skra-sys-color-danger-base);
-}
-```
-
-## Gotcha 3 — components carry `margin: 0` (ADR 022)
-
-Spacing between components is **never** a margin on the component. Use a layout atom
-(`[skraStack]`/`[skraBox]`/`[skraGrid]`) — see `layout.md`.
-
-## Gotcha 4 — don't reach for relative imports as an escape hatch
-
-If something you need isn't on a public `@skra/ui/*` entry point, that is a finding (raise it),
-not a reason to import from `libs/`. The public surface is the contract.
+# Setup & Gotchas
+
+> Load this for: first integration, import errors, "which package exports what", and the
+> boolean-attribute / inline-style pitfalls. Core rules live in `README.md` — this is the detail.
+
+## Public entry points (`@skra/ui/*`)
+
+Import **only** from these. Never a deep `libs/ui/...` path (not part of the public API;
+will break on any internal refactor). Skra ships as **one package, `@skra/ui`**, with a
+secondary entry point per component (ADR 0054 / O-31 consolidation). The primary `@skra/ui`
+entry exports nothing — always import from a `@skra/ui/<entry>` subpath.
+
+| Entry point                  | Exports (representative)                                                                                                              |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `@skra/ui/button`            | `button[skraButton]`                                                                                                                 |
+| `@skra/ui/link`              | `a[skraLink]`                                                                                                                        |
+| `@skra/ui/icon`              | icon container atom                                                                                                                   |
+| `@skra/ui/typography`        | `[skraTypography]`                                                                                                                   |
+| `@skra/ui/layout`            | `[skraStack]`, `[skraBox]`, `[skraGrid]`                                                                                           |
+| `@skra/ui/kbd`               | `kbd[skraKbd]`                                                                                                                       |
+| `@skra/ui/field`             | `<skra-field>`, `[skraLabel]`, `[skraHint]`, `[skraError]`, `fieldset[skraFieldset]`, `legend[skraLegend]`, `SkraFieldContext` |
+| `@skra/ui/input`             | `input[skraInput]`                                                                                                                   |
+| `@skra/ui/textarea`          | `textarea[skraTextarea]`, auto-resize                                                                                                |
+| `@skra/ui/checkbox`          | `input[skraCheckbox]`                                                                                                                |
+| `@skra/ui/radio`             | `input[skraRadio]`                                                                                                                   |
+| `@skra/ui/switch`            | `input[skraSwitch]`                                                                                                                  |
+| `@skra/ui/counter`           | `skra-counter`                                                                                                                       |
+| `@skra/ui/star-rating`       | `skra-star-rating`                                                                                                                   |
+| `@skra/ui/native-select`     | `select[skraSelect]` (`SkraNativeSelect`)                                                                                           |
+| `@skra/ui/dialog`            | `dialog[skraDialog]`                                                                                                                 |
+| `@skra/ui/tooltip`           | `[skraTooltip]`                                                                                                                      |
+| `@skra/ui/popover`           | `skra-popover`                                                                                                                       |
+| `@skra/ui/menu`              | `skra-menu`, `skra-menu-item`                                                                                                       |
+| `@skra/ui/select`            | `skra-select` (+ `SkraOption` & option directives, re-exported)                                                                     |
+| `@skra/ui/multi-select`      | `skra-multi-select` (+ `SkraOption` & option directives, re-exported)                                                               |
+| `@skra/ui/combobox`          | `skra-combobox` (+ `SkraOption` & option directives, re-exported)                                                                   |
+| `@skra/ui/datepicker`        | `skra-datepicker`                                                                                                                    |
+| `@skra/ui/alert`             | `skra-alert`                                                                                                                         |
+| `@skra/ui/badge`             | `skra-badge`                                                                                                                         |
+| `@skra/ui/chip`              | `skra-chip`                                                                                                                          |
+| `@skra/ui/toast`             | `skra-toast`, `skra-toast-region`                                                                                                   |
+| `@skra/ui/tabs`              | `[skraTabs]`, `[skraTablist]`, `button[skraTab]`, `[skraTabPanel]`                                                                |
+| `@skra/ui/accordion`         | `[skraAccordion]` family                                                                                                             |
+| `@skra/ui/progress`          | `progress[skraProgress]`                                                                                                             |
+| `@skra/ui/skeleton`          | `skra-skeleton`                                                                                                                      |
+| `@skra/ui/loading-indicator` | `[skraLoadingIndicator]`                                                                                                             |
+| `@skra/ui/avatar`            | `skra-avatar`                                                                                                                        |
+| `@skra/ui/status-dot`        | `skra-status-dot`                                                                                                                    |
+| `@skra/ui/rating-display`    | `skra-rating-display`                                                                                                                |
+
+> `@skra/ui/core` exists for cross-component shared satellites (`SkraOption` & option
+> directives, `SkraSelectTrigger`, `SKRA_LISTBOX_PANEL`). Prefer the re-exports from
+> `select` / `multi-select` / `combobox`; you rarely import `core` directly.
+>
+> `@skra/shadow-dom-bridge` is a delivery utility, not a component — see
+> `theming-and-encapsulation.md`.
+
+## Gotcha 1 — boolean attributes: write the bare form
+
+Skra boolean inputs carry `{ transform: booleanAttribute }` (lint-enforced across `libs/ui`
+by `boolean-input-validator.mjs`), so the **native bare attribute works** — write it the
+HTML-idiomatic way:
+
+```html
+<skra-toast dismissible>…</skra-toast>
+<!-- ✓ -->
+<div skraStack wrap>…</div>
+<!-- ✓ -->
+```
+
+`[dismissible]="true"` also compiles but is unnecessary. (Historically the transform was
+missing and the bare form broke under `strictTemplates` — F-18; closed library-wide in
+session 10, so the workaround is no longer needed.)
+
+## Gotcha 2 — never style with inline `style` or `[style.--var]`
+
+Skra reflects state as `data-skra-*` attributes and maps them to tokens in CSS (ADR 021,
+CSP-safe). To override a token for a subtree, scope it with a **CSS class or a data-attribute
+on an ancestor**, never inline:
+
+```html
+<!-- ✗ CSP-violating, and not how the token cascade is meant to work -->
+<skra-badge style="--skra-comp-badge-background: red">…</skra-badge>
+
+<!-- ✓ scope on an ancestor, in a stylesheet -->
+<div class="danger-zone"><skra-badge>…</skra-badge></div>
+```
+
+```css
+.danger-zone {
+  --skra-comp-badge-background: var(--skra-sys-color-danger-base);
+}
+```
+
+## Gotcha 3 — components carry `margin: 0` (ADR 022)
+
+Spacing between components is **never** a margin on the component. Use a layout atom
+(`[skraStack]`/`[skraBox]`/`[skraGrid]`) — see `layout.md`.
+
+## Gotcha 4 — `skraTypography` takes its role **on the selector**, not a `role` input
+
+`[skraTypography]` is the one atom whose main input is aliased to its own selector. The
+property is called `role`, but you never write `role="…"` — that would collide with the
+native ARIA `role` attribute, which is exactly why it is aliased:
+
+```html
+<!-- ✓ the role goes on the selector attribute -->
+<h1 skraTypography="headline-medium">Materials</h1>
+<p skraTypography="body-small">Everything uploaded this month.</p>
+
+<!-- ✓ bare = the default role, `body-medium` -->
+<span skraTypography>Plain body text</span>
+
+<!-- ✗ `role` is the ARIA attribute here; the type error is TS2322 on an unknown input -->
+<h1 skraTypography role="headline-medium">Materials</h1>
+```
+
+Roles (ADR 036): `display-{large,medium,small}` · `headline-*` · `title-*` · `body-*` ·
+`label-*`. The other inputs are plain and unaliased:
+
+```html
+<p skraTypography="body-small" severity="error">Upload failed.</p>
+<p skraTypography="body-medium" truncate="multi" [lineClamp]="3">Long description…</p>
+```
+
+`skraTypography` is a **component on a native host** — put it on the element that already
+carries the right semantics (`<h1>`, `<p>`, `<span>`). It sets no heading level and no role
+of its own; the visual scale and the document outline stay independent.
+
+## Gotcha 5 — form atoms work standalone; `<skra-field>` is what adds label/hint/error wiring
+
+`input[skraInput]`, `textarea[skraTextarea]` and `select[skraSelect]` inject
+`SkraFieldContext` **optionally** (ADR 013 §3.7), exactly like `skraCheckbox` / `skraRadio` /
+`skraSwitch`. Outside a field they render the skin and touch nothing else — your `id`,
+`disabled` and `readonly` are left alone:
+
+```html
+<!-- ✓ toolbar search: native implicit label, no field ceremony -->
+<label>Search <input skraInput type="search" placeholder="Filter by name…" /></label>
+
+<!-- ✓ genuinely label-less control: aria-label on the native host (ADR 033 Path 3) -->
+<input skraInput type="search" aria-label="Search materials" />
+```
+
+Reach for `<skra-field>` when you need what the field actually provides — a visible label
+associated by DI, a hint, an error, and the `required`/`disabled`/`readonly`/`hasError`
+cascade across all of them:
+
+```html
+<skra-field [hasError]="!email().valid">
+  <label skraLabelFor>Email</label>
+  <input skraInput type="email" />
+  <skra-hint>We only use this for receipts.</skra-hint>
+  <skra-error>Enter a valid address.</skra-error>
+</skra-field>
+```
+
+> The field does **not** guarantee an accessible name — `<skra-field><input skraInput /></skra-field>`
+> with no `label[skraLabelFor]` renders an unnamed control. Naming is on you either way; run
+> axe over your screens.
+
+## Gotcha 6 — don't reach for relative imports as an escape hatch
+
+If something you need isn't on a public `@skra/ui/*` entry point, that is a finding (raise it),
+not a reason to import from `libs/`. The public surface is the contract.

package/consumer-guide/theming-and-encapsulation.md

@@ -1,115 +1,129 @@
-# Theming & Encapsulation
-
-> Load this for: loading the token layers, switching skin / dark mode / density at runtime,
-> and mounting Skra under Shadow DOM / a microfrontend / an iframe. Governed by ADR 002
-> (token cascade), ADR 042 §3.4 (value/structure split), ADR 012 §5 (delivery), ADR 036 §3.7
-> (baseline hook), ADR 0047 (runtime-scoped skins).
-
-## Mental model — values inherit, structure does not
-
-Skra styling has two layers, and they behave differently across DOM boundaries:
-
-- **Token VALUES** (`--skra-*` custom properties) — set by the theme/comp/skin artifacts.
-  They **inherit** through the DOM, **including across a Shadow DOM boundary**. This is what
-  lets a runtime skin swap re-paint a shadow subtree with zero component changes (F-9).
-- **STRUCTURE** (selector-bearing rules: `:host`, `data-skra-*` state, slices, the variant
-  matrix) — injected as document-scoped `<style>` (Emulated, ADR 001). These do **not** cross
-  into a shadow root; inside one you need the bridge (below).
-
-## Loading the token layers (global stylesheet)
-
-A consumer imports the built token artifacts once, globally. **Order matters** (F-14): base →
-comp → dark → slices → scoped skins → overlay presets (overlays last so they keep overriding
-a skin at equal specificity):
-
-```scss
-/* paths shown as in the repo; an external consumer imports the equivalent published artifacts */
-@import 'skra/_theme.scss'; // ref + sys token values (:root)
-@import 'skra/_comp.scss'; // component token defaults
-@import 'skra/_theme.dark.scss'; // dark-scheme value block
-@import 'skra/_baseline.scss'; // typography/canvas baseline (needs the hook — below)
-@import 'skra/_form-controls.scss'; // native control skin slice
-@import 'skra/_overlay.scss'; // ::backdrop scrim + modal scroll-lock slice
-@import 'skra/utilities.scss'; // skra-sr-only etc.
-@import 'skra/_density.compact.scss';
-@import 'skra/_density.comfortable.scss';
-
-/* additional skins ship as runtime-scoped artifacts (ADR 0047), keyed to [data-skra-skin] */
-@import 'brutal/_theme.scoped.scss';
-@import 'brutal/_theme.dark.scoped.scss';
-```
-
-> Exact import specifiers depend on how the tokens are distributed to your project (npm
-> package vs vendored `dist/`). The layer set and order are the contract; the paths are not.
-
-## Switching skin / scheme / density at runtime
-
-These are **consumer-scope attributes** on an ancestor element — NOT component inputs and NOT
-state reflection. Any subtree carrying them re-resolves its token values:
-
-| Attribute                 | Values                                             | Default (omit the attribute) |
-| ------------------------- | -------------------------------------------------- | ---------------------------- |
-| `data-skra-skin`         | `brutal`, … (whatever scoped artifacts you loaded) | the base skin                |
-| `data-skra-color-scheme` | `dark`                                             | light                        |
-| `data-skra-density`      | `compact`, `comfortable`                           | default density              |
-
-```html
-<div [attr.data-skra-skin]="skin()" [attr.data-skra-color-scheme]="scheme() === 'dark' ? 'dark' : null" [attr.data-skra-density]="density() === 'default' ? null : density()">
-  <!-- Skra subtree re-paints when any of these change -->
-</div>
-```
-
-Bind `null` for the default so you don't emit `data-skra-color-scheme="light"` etc. — the
-base values live at `:root`, the attribute only _overrides_.
-
-### The baseline hook (`data-skra-baseline`)
-
-`_baseline.scss` (document typography + canvas background) is **inert until you add the
-`data-skra-baseline` attribute** to the scope that should own it (ADR 036 §3.7). It is
-**static** — always present, not toggled like the design-context attributes above:
-
-- `<html data-skra-baseline>` — Skra owns the page (canvas bg reaches the viewport, sets the
-  rem root). Use when Skra is your whole app.
-- `<div data-skra-baseline>` — guest/microfrontend: scopes typography + canvas to the subtree
-  only, leaving the host shell's `<html>` untouched.
-
-## Mounting Skra inside a Shadow DOM root (microfrontend isolation)
-
-Inside a shadow root, token **values still inherit** (skins work), but the document-scoped
-STRUCTURE does not reach in. Adopt it with the bridge:
-
-```ts
-import { registerSkraStyles } from '@skra/shadow-dom-bridge';
-
-// after the Skra content inside the shadow root has rendered at least once
-registerSkraStyles(shadowRoot);
-// rebuild the cached aggregate if more Skra styles were injected since:
-registerSkraStyles(shadowRoot, { refresh: true });
-```
-
-`registerSkraStyles(shadowRoot, options?)` adopts Skra's **structural** stylesheets
-(per-component Emulated rules incl. the variant matrix, `_baseline`, `_form-controls`,
-`utilities`) into the root. It deliberately **skips the token value layers** — those inherit,
-and re-declaring them inside would freeze shell-driven skin morph (ADR 042 §3.4). Options:
-`marker` (default `/skra/i`), `fallback` (`<style>` injection when constructable stylesheets
-are unavailable, default `true`), `refresh`. There is also `unregisterSkraStyles(shadowRoot)`.
-
-**This applies to Angular `ViewEncapsulation.ShadowDom` too**, not only foreign `attachShadow()`
-roots: Angular replicates _component_ styles into a ShadowDom root but NOT the global slices
-(F-12) — so without the bridge, `skra-sr-only` content renders visible (e.g. the datepicker's
-per-day SR labels overflow the grid — F-15), `::backdrop`/scroll-lock are missing (F-7), etc.
-
-## Limits that do NOT cross a boundary (by design)
-
-The native top-layer substrate (ADR 0044) has per-context limits — these are architecture, not
-bugs:
-
-- **Modal scroll-lock** uses `html:has(dialog[skraDialog]:modal)`, and `:has()` does not pierce
-  a shadow boundary — a dialog opened from inside a shadow root does **not** lock the outer page
-  scroll (F-6). For shift-free locking when Skra owns the page, set
-  `html { scrollbar-gutter: stable }` globally.
-- **`::backdrop` scrim** lives in the `_overlay.scss` global slice; inside a shadow root it
-  needs the bridge (F-7).
-- **iframe** — overlays open in the **iframe's own top layer, contained to the frame** (F-11);
-  they cannot overlay the parent app. Pass design context into the frame via query params /
-  reload. This is a fundamental limit of the per-document top layer, not a defect.
+# Theming & Encapsulation
+
+> Load this for: loading the token layers, switching skin / dark mode / density at runtime,
+> and mounting Skra under Shadow DOM / a microfrontend / an iframe. Governed by ADR 002
+> (token cascade), ADR 042 §3.4 (value/structure split), ADR 012 §5 (delivery), ADR 036 §3.7
+> (baseline hook), ADR 0047 (runtime-scoped skins).
+
+## Mental model — values inherit, structure does not
+
+Skra styling has two layers, and they behave differently across DOM boundaries:
+
+- **Token VALUES** (`--skra-*` custom properties) — set by the theme/comp/skin artifacts.
+  They **inherit** through the DOM, **including across a Shadow DOM boundary**. This is what
+  lets a runtime skin swap re-paint a shadow subtree with zero component changes (F-9).
+- **STRUCTURE** (selector-bearing rules: `:host`, `data-skra-*` state, slices, the variant
+  matrix) — injected as document-scoped `<style>` (Emulated, ADR 001). These do **not** cross
+  into a shadow root; inside one you need the bridge (below).
+
+## Loading the token layers (global stylesheet)
+
+A consumer imports the built token artifacts once, globally. **Order matters** (F-14): base →
+comp → dark → slices → scoped skins → overlay presets (overlays last so they keep overriding
+a skin at equal specificity):
+
+```scss
+@use 'pkg:@skra/tokens/skra/_theme.scss' as *; // ref + sys token values (:root)
+@use 'pkg:@skra/tokens/skra/_comp.scss' as *; // component token defaults
+@use 'pkg:@skra/tokens/skra/_theme.dark.scss' as *; // dark-scheme value block
+@use 'pkg:@skra/tokens/skra/_baseline.scss' as *; // typography/canvas baseline (needs the hook — below)
+@use 'pkg:@skra/tokens/skra/_form-controls.scss' as *; // native control skin slice
+@use 'pkg:@skra/tokens/skra/_overlay.scss' as *; // ::backdrop scrim + modal scroll-lock slice
+@use 'pkg:@skra/tokens/skra/utilities.scss' as *; // skra-sr-only etc.
+@use 'pkg:@skra/tokens/skra/_density.compact.scss' as *;
+@use 'pkg:@skra/tokens/skra/_density.comfortable.scss' as *;
+
+/* additional skins ship as runtime-scoped artifacts (ADR 0047), keyed to [data-skra-skin] */
+@use 'pkg:@skra/tokens/brutal/_theme.scoped.scss' as *;
+@use 'pkg:@skra/tokens/brutal/_theme.dark.scoped.scss' as *;
+```
+
+**`as *` is mandatory, and it is the single most common first-build failure.** `@use`
+derives a namespace from the file name, so `_theme.scss` and `_theme.dark.scss` both claim
+`theme` and Sass aborts with _"There's already a module with namespace 'theme'"_ — likewise
+for the `_density.compact` / `_density.comfortable` pair and every `.scoped` pair. The layers
+declare CSS custom properties and no Sass members, so there is nothing for a namespace to
+disambiguate and `as *` costs nothing.
+
+**`pkg:` needs no build config.** It uses the Sass package importer, which `@angular/build`
+enables by default. If your toolchain does not, drop the prefix and add `node_modules` to the
+load path — `"stylePreprocessorOptions": { "includePaths": ["node_modules"] }` in the build
+target, then `@use '@skra/tokens/skra/_theme.scss' as *;`. Without one of the two, a bare
+`@skra/tokens/...` specifier does not resolve at all.
+
+**Do not use `@import`** — deprecated in Dart Sass and slated for removal.
+
+> Exact specifiers depend on how the tokens reach your project (npm package vs vendored
+> `dist/`). The layer set and order are the contract; the paths are not.
+
+## Switching skin / scheme / density at runtime
+
+These are **consumer-scope attributes** on an ancestor element — NOT component inputs and NOT
+state reflection. Any subtree carrying them re-resolves its token values:
+
+| Attribute                 | Values                                             | Default (omit the attribute) |
+| ------------------------- | -------------------------------------------------- | ---------------------------- |
+| `data-skra-skin`         | `brutal`, … (whatever scoped artifacts you loaded) | the base skin                |
+| `data-skra-color-scheme` | `dark`                                             | light                        |
+| `data-skra-density`      | `compact`, `comfortable`                           | default density              |
+
+```html
+<div [attr.data-skra-skin]="skin()" [attr.data-skra-color-scheme]="scheme() === 'dark' ? 'dark' : null" [attr.data-skra-density]="density() === 'default' ? null : density()">
+  <!-- Skra subtree re-paints when any of these change -->
+</div>
+```
+
+Bind `null` for the default so you don't emit `data-skra-color-scheme="light"` etc. — the
+base values live at `:root`, the attribute only _overrides_.
+
+### The baseline hook (`data-skra-baseline`)
+
+`_baseline.scss` (document typography + canvas background) is **inert until you add the
+`data-skra-baseline` attribute** to the scope that should own it (ADR 036 §3.7). It is
+**static** — always present, not toggled like the design-context attributes above:
+
+- `<html data-skra-baseline>` — Skra owns the page (canvas bg reaches the viewport, sets the
+  rem root). Use when Skra is your whole app.
+- `<div data-skra-baseline>` — guest/microfrontend: scopes typography + canvas to the subtree
+  only, leaving the host shell's `<html>` untouched.
+
+## Mounting Skra inside a Shadow DOM root (microfrontend isolation)
+
+Inside a shadow root, token **values still inherit** (skins work), but the document-scoped
+STRUCTURE does not reach in. Adopt it with the bridge:
+
+```ts
+import { registerSkraStyles } from '@skra/shadow-dom-bridge';
+
+// after the Skra content inside the shadow root has rendered at least once
+registerSkraStyles(shadowRoot);
+// rebuild the cached aggregate if more Skra styles were injected since:
+registerSkraStyles(shadowRoot, { refresh: true });
+```
+
+`registerSkraStyles(shadowRoot, options?)` adopts Skra's **structural** stylesheets
+(per-component Emulated rules incl. the variant matrix, `_baseline`, `_form-controls`,
+`utilities`) into the root. It deliberately **skips the token value layers** — those inherit,
+and re-declaring them inside would freeze shell-driven skin morph (ADR 042 §3.4). Options:
+`marker` (default `/skra/i`), `fallback` (`<style>` injection when constructable stylesheets
+are unavailable, default `true`), `refresh`. There is also `unregisterSkraStyles(shadowRoot)`.
+
+**This applies to Angular `ViewEncapsulation.ShadowDom` too**, not only foreign `attachShadow()`
+roots: Angular replicates _component_ styles into a ShadowDom root but NOT the global slices
+(F-12) — so without the bridge, `skra-sr-only` content renders visible (e.g. the datepicker's
+per-day SR labels overflow the grid — F-15), `::backdrop`/scroll-lock are missing (F-7), etc.
+
+## Limits that do NOT cross a boundary (by design)
+
+The native top-layer substrate (ADR 0044) has per-context limits — these are architecture, not
+bugs:
+
+- **Modal scroll-lock** uses `html:has(dialog[skraDialog]:modal)`, and `:has()` does not pierce
+  a shadow boundary — a dialog opened from inside a shadow root does **not** lock the outer page
+  scroll (F-6). For shift-free locking when Skra owns the page, set
+  `html { scrollbar-gutter: stable }` globally.
+- **`::backdrop` scrim** lives in the `_overlay.scss` global slice; inside a shadow root it
+  needs the bridge (F-7).
+- **iframe** — overlays open in the **iframe's own top layer, contained to the frame** (F-11);
+  they cannot overlay the parent app. Pass design context into the frame via query params /
+  reload. This is a fundamental limit of the per-document top layer, not a defect.