@skra/ui 0.2.0

package/consumer-guide/overlays.md

@@ -0,0 +1,100 @@
+# Overlays
+
+> Load this for: opening a dialog, tooltip, popover, or menu in the native top layer, and the
+> shadow/iframe limits. Governed by ADR 0044 (native top-layer substrate — no CDK portal, no
+> z-index). For `select` / `combobox` / `datepicker` **value binding**, see `forms-and-binding.md`
+> (they are value-owned overlays).
+
+## Shared model
+
+All Skra overlays render in the **browser top layer** via native platform APIs (`<dialog>` +
+the Popover API), not a `document.body` portal. Consequences for you:
+
+- **No z-index management.** Stacking is invocation-order; nesting is always correct.
+- **Escape, light-dismiss, `::backdrop`** are platform-owned (per overlay, below).
+- They open correctly **from inside a Shadow DOM root**; per-context limits at the bottom.
+
+## Dialog (modal) — `dialog[skraDialog]`
+
+A Component on the native `<dialog>`, opened with the **native** `showModal()` and closed with
+`close()`. `role="dialog"`, `aria-modal`, Escape, the `::backdrop` scrim, scroll-lock and focus
+containment are native:
+
+```html
+<button skraButton (click)="dlg.showModal()">Delete…</button>
+
+<dialog skraDialog #dlg aria-labelledby="confirm-title" size="sm">
+  <h2 id="confirm-title">Delete item?</h2>
+  <p>This can't be undone.</p>
+  <button skraButton autofocus (click)="dlg.close()">Cancel</button>
+  <button skraButton (click)="confirm(); dlg.close()">Delete</button>
+</dialog>
+```
+
+- **Name it** with `aria-labelledby` → a projected heading (no `ariaLabel` input — ADR 033).
+- **Initial focus** is the consumer-placed native `autofocus` attribute.
+- `size` is `sm | md | lg` (ADR 035).
+
+## Tooltip — `[skraTooltip]` on your own trigger
+
+A supplementary, non-interactive **description** shown on hover AND focus. It is **not** the
+accessible name — it merges into the trigger's `aria-describedby`:
+
+```html
+<button skraButton [skraTooltip]="'Open settings'" aria-label="Settings">⚙</button>
+```
+
+An icon-only trigger **still needs its own accessible name** (Path 3 — see
+`accessible-names.md`); the tooltip never substitutes for it.
+
+## Popover (non-modal panel) — `skra-popover`
+
+A Component on the panel with projected interactive content. The trigger is **your own button**
+linked by the native `popovertarget`; toggle, light-dismiss, Escape, and stacking are
+platform-owned. **You MUST give the panel an `id`:**
+
+```html
+<button skraButton popovertarget="account-menu">Account</button>
+<skra-popover id="account-menu" aria-labelledby="account-menu-title">
+  <h3 id="account-menu-title">Signed in as…</h3>
+  <!-- interactive content -->
+</skra-popover>
+```
+
+Focus is **not** trapped/force-moved (non-modal). Name via `aria-labelledby` → projected
+heading.
+
+## Menu (commands) — `skra-menu` + `button[skraMenuItem]`
+
+A WAI-ARIA APG menu-button: a homogeneous command set, arrow-key navigated, activating an item
+closes it. Trigger is your own button with `popovertarget` + `aria-haspopup="menu"`; **give the
+panel an `id`**. Focus moves **into** the menu on open:
+
+```html
+<button skraButton popovertarget="row-actions" aria-haspopup="menu">Actions</button>
+<skra-menu id="row-actions">
+  <button skraMenuItem (click)="edit()">Edit</button>
+  <button skraMenuItem disabled (click)="archive()">Archive</button>
+  <button skraMenuItem (click)="remove()">Delete</button>
+</skra-menu>
+```
+
+- **Side effects on open/close:** bind the **native `(toggle)`** event — there is no Skra
+  output (native-first).
+- A right-click context menu is **not** a menu trigger mode — use a visible button (SRP +
+  WCAG 2.1.1).
+
+## Selection overlays — value binding lives elsewhere
+
+`skra-select`, `skra-multi-select`, `skra-combobox`, `skra-datepicker` render their listbox
+in the top layer like the above, **but their value is consumer-owned** — bind with the
+`[value]`/`(valueChange)` bridge documented in `forms-and-binding.md` (class B). The combobox
+filters with consumer-owned data (ADR 0049): you own the filtered option list.
+
+## Limits across boundaries (same as theming — recap)
+
+- Overlays **open** from inside a Shadow DOM root (top layer + positioning cross the boundary,
+  F-10). But the global-slice pieces — `::backdrop` scrim and `html:has()` scroll-lock — need
+  the bridge / don't pierce the boundary (F-6/F-7). See `theming-and-encapsulation.md`.
+- **iframe**: overlays are contained to the frame's own top layer — they cannot overlay the
+  parent app (F-11).

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

@@ -0,0 +1,103 @@
+# 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.

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

@@ -0,0 +1,115 @@
+# 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.

package/consumer-guide/wrapping-patterns.md

@@ -0,0 +1,90 @@
+# Wrapping Skra in Your Own Components
+
+> Load this for: building project-specific components on top of Skra atoms to simplify the
+> API down to the inputs your app actually needs. Governed by the *atoms-agnostic* doctrine +
+> ADR 037 (consumer owns value/ergonomics).
+
+## Why wrap, and where the wrapper belongs
+
+Skra atoms are deliberately low-level and semantic-only — they ship a11y + tokens + binding
+seams, not app ergonomics. The intended consumption shape is: **your app wraps Skra atoms in
+higher-level components** that expose just the inputs your domain needs.
+
+The hard rule: **the wrapper lives in YOUR app (or a consumer library), never back inside
+`@skra/*`.** Pulling app ergonomics into the atom breaks the agnostic contract (ADR 037). If a
+wrapper becomes reusable across several of your apps, promote it to **your own library built ON
+Skra** (`@yourorg/ui`), not into Skra core.
+
+## Pattern 1 — a field wrapper (collapse the field boilerplate)
+
+The `<skra-field>` + label + control + hint + error + binding cluster is verbose to repeat.
+Wrap it once:
+
+```ts
+// app-text-field.component.ts  (YOUR code)
+@Component({
+  selector: 'app-text-field',
+  standalone: true,
+  imports: [SkraField, SkraInput, SkraLabelFor, SkraHint, SkraError],
+  template: `
+    <skra-field>
+      <label skraLabelFor>{{ label() }}</label>
+      <input skraInput [formField]="field()" />
+      @if (hint()) { <skra-hint>{{ hint() }}</skra-hint> }
+      @if (errorText()) { <skra-error>{{ errorText() }}</skra-error> }
+    </skra-field>
+  `,
+})
+export class AppTextField {
+  readonly label = input.required<string>();
+  readonly field = input.required<Field<string>>(); // your Signal Forms node type
+  readonly hint = input<string>();
+  readonly errorText = input<string>();
+}
+```
+
+```html
+<!-- call site: domain-minimal API -->
+<app-text-field label="Email" [field]="form().email" hint="We never share it." />
+```
+
+**What NOT to break when wrapping:**
+
+- Don't re-implement a11y — keep the control inside `<skra-field>` so the DI context still
+  wires `id`/`for`/`aria-describedby` (ADR 013). Don't add `aria-label` (ADR 033).
+- Don't introduce inline styles to theme — scope tokens with a class (ADR 021).
+- Keep the accessible-name path intact (the projected `<label skraLabelFor>` IS the name).
+
+## Pattern 2 — a value-bridge adapter for class-B overlays
+
+The class-B overlays (`skra-select`, `skra-datepicker`, `skra-star-rating`, …) need the
+two-binding `[value]`/`(valueChange)` bridge (see `forms-and-binding.md`). If that recurs, the
+sanctioned shape is a **consumer-side adapter directive** that maps a form node ↔
+value/valueChange, so the call site goes back to one binding:
+
+```ts
+// app-control.directive.ts  (YOUR interop layer — a sketch)
+@Directive({ selector: '[appControl]', standalone: true })
+export class AppControl<T> {
+  readonly appControl = input.required<Field<T>>();
+  // read [value] from the host element + write back on (valueChange),
+  // syncing this.appControl().value() ↔ the field node
+}
+```
+
+```html
+<skra-select [appControl]="form().country">…</skra-select>
+```
+
+This adapter is **yours**, in your interop layer — it must not live in the atom (ADR 037). The
+friction journal calls this candidate `[skraControl]` (F-3).
+
+## The open question — `@skra/angular-interop`? (resolved: not now)
+
+If *every* Angular consumer needs the same value-bridge adapter, there is an argument that
+Skra could ship an **optional, opt-in** `@skra/angular-interop` package — separate from the
+agnostic atoms (atoms stay pure; interop is a voluntary layer on top). **Resolved 2026-06-25
+(ADR 037 §7): DECLINED for now** — with one consumer and a still-iterating Signal Forms API,
+the bridge stays consumer-owned (Pattern 2). The trigger to revisit, then via its own ADR:
+several real consumers feeling the friction AND a stabilised Angular forms API (that ADR must
+first resolve strategy-agnosticism — Signal Forms AND Reactive via a seam, never bless one).