@skra/ui 0.5.0 → 0.7.0

package/consumer-guide/README.md

@@ -1,85 +1,90 @@
-# Consuming Skra — Agent Guide (Core)
-
-> **DRAFT (2026-06-25).** All 7 sections drafted. Snippets are grounded in source (verified
-> against `libs/ui/*`) + the `apps/dogfood` friction journal (`F-n`) + the Iron Boundaries.
-> Still draft: not yet referenced from a real consumer repo, not lint-gated against ADR drift,
-> and cross-engine/Safari caveats inherit Skra's own open item O-9.
-
-This guide is for an **agent working inside a repository that consumes Skra** (imports
-`@skra/*`), not for authoring Skra itself. It is written to be **copied into / referenced
-from a consumer repo**.
-
----
-
-## How to use this guide (read this first — it is the point)
-
-This file is **tiered on purpose** (same model as `FORGE_ADR_SUMMARY.md`). To keep token
-cost low:
-
-1. **Always load this core** (it is small) — the Iron Rules + the Section Router below.
-2. Then load **at most the ONE section** that matches your current task (the Router maps
-   task → file). Do **not** read every section "to be safe" — that defeats the design.
-3. Open the full Skra ADR / spec only when a section explicitly points you there.
-
----
-
-## Iron Rules of Consumption (the 6 a consumer breaks on day one)
-
-Violating these is a review blocker in a consumer repo just as inside Skra.
-
-1. **Import only from public `@skra/ui/*` entry points** — never a deep relative `libs/...`
-   path. Skra ships as one package, `@skra/ui`, with a secondary entry point per component
-   (e.g. `@skra/ui/button`, `@skra/ui/typography`, `@skra/ui/select`); the primary
-   `@skra/ui` exports nothing. (Full entry-point list → `setup-and-gotchas.md`.)
-2. **You own the value.** Skra form atoms do **not** implement `ControlValueAccessor` /
-   `FormValueControl` (ADR 037). Native-host atoms take `[formField]`/`[formControl]`/
-   `[(ngModel)]`; value-owned overlays need an explicit `[value]`/`(valueChange)` bridge.
-   (How → `forms-and-binding.md`.)
-3. **Accessible name has exactly ONE path** (ADR 033). No Skra atom exposes an `ariaLabel`
-   input; never put `aria-label` next to visible text on the same host. (Paths →
-   `accessible-names.md`.)
-4. **Inside `<skra-field>`, do not pass `id` / `for` / `aria-describedby` by hand** — the
-   DI context wires label↔control↔hint↔error automatically (ADR 013).
-5. **Under Signal Forms, native constraint attributes go in the schema, not the template.**
-   `name` on grouped radios and `maxlength` / `min` / `pattern` on a `[formField]` host raise
-   `NG8022` — Signal Forms owns them (F-1/F-2). (Details → `forms-and-binding.md`.)
-6. **Never theme with inline styles.** No `[style.--skra-*]` bindings or `style="…"` (breaks
-   CSP, ADR 021). Override tokens via a CSS class / `data-skra-*` scope; components are
-   `margin: 0` (ADR 022) — spacing comes from layout atoms, never a margin on the component.
-
----
-
-## Section Router — load the ONE that matches your task
-
-| Section                     | File                           | Load when                                                                                                   | Status   |
-| --------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------- | -------- |
-| **Setup & gotchas**         | `setup-and-gotchas.md`         | First integration; import fails; which `@skra/*` package exports what; boolean-attribute & theming pitfalls | ✅ draft |
-| **Forms & value binding**   | `forms-and-binding.md`         | Wiring an input / select / checkbox / rating to Signal Forms, Reactive Forms, or `ngModel`                  | ✅ draft |
-| **Accessible names**        | `accessible-names.md`          | Naming buttons, icon-only controls, overlays; using `skra-sr-only`                                         | ✅ draft |
-| **Theming & encapsulation** | `theming-and-encapsulation.md` | Skins, dark mode, density; mounting under Shadow DOM / a microfrontend / an iframe                          | ✅ draft |
-| **Overlays**                | `overlays.md`                  | Dialog / tooltip / popover / menu / select in the top layer; shadow & iframe limits                         | ✅ draft |
-| **Layout**                  | `layout.md`                    | Spacing & composition with Stack / Box / Surface / Grid; building a card; the gap scale                                                | ✅ draft |
-| **Wrapping Skra**          | `wrapping-patterns.md`         | Building your own higher-level components over Skra atoms (simplified API)                                 | ✅ draft |
-
----
-
-## Quick reference — task → section
-
-| I want to…                                                                 | Go to                                     |
-| -------------------------------------------------------------------------- | ----------------------------------------- |
-| Add `@skra/ui/*` to a project and import an atom                           | `setup-and-gotchas.md`                    |
-| Bind a text input / textarea to a form                                     | `forms-and-binding.md`                    |
-| Bind a `skra-select` / `skra-datepicker` / `skra-star-rating` to a form | `forms-and-binding.md` (the value bridge) |
-| Name an icon-only button                                                   | `accessible-names.md`                     |
-| Switch skin / dark mode at runtime                                         | `theming-and-encapsulation.md`            |
-| Mount Skra inside a Web Component / microfrontend                         | `theming-and-encapsulation.md`            |
-| Open a dialog or tooltip                                                   | `overlays.md`                             |
-| Space components apart                                                     | `layout.md`                               |
-| Build a card / panel / tile (there is no `skra-card`)                      | `layout.md` (Surface)                     |
-| Wrap a Skra atom in a project-specific component                          | `wrapping-patterns.md`                    |
-
----
-
-_Source of truth for the rules: Skra `FORGE_ADR_SUMMARY.md` + `adr/decisions/`. Real
-consumption evidence: `apps/dogfood/FRICTION_JOURNAL.md`. This guide restates the consumer
-slice of those — on divergence, the ADRs win._
+# Consuming Skra — Agent Guide (Core)
+
+> **DRAFT (2026-06-25; 8th section added 2026-08-30; 9th — Feedback — 2026-09-27).** All 9 sections drafted. Snippets are grounded in source (verified
+> against `libs/ui/*`) + the `apps/dogfood` friction journal (`F-n`) + the Iron Boundaries.
+> Still draft: not yet referenced from a real consumer repo, not lint-gated against ADR drift,
+> and cross-engine/Safari caveats inherit Skra's own open item O-9.
+
+This guide is for an **agent working inside a repository that consumes Skra** (imports
+`@skra/*`), not for authoring Skra itself. It is written to be **copied into / referenced
+from a consumer repo**.
+
+---
+
+## How to use this guide (read this first — it is the point)
+
+This file is **tiered on purpose** (same model as `FORGE_ADR_SUMMARY.md`). To keep token
+cost low:
+
+1. **Always load this core** (it is small) — the Iron Rules + the Section Router below.
+2. Then load **at most the ONE section** that matches your current task (the Router maps
+   task → file). Do **not** read every section "to be safe" — that defeats the design.
+3. Open the full Skra ADR / spec only when a section explicitly points you there.
+
+---
+
+## Iron Rules of Consumption (the 6 a consumer breaks on day one)
+
+Violating these is a review blocker in a consumer repo just as inside Skra.
+
+1. **Import only from public `@skra/ui/*` entry points** — never a deep relative `libs/...`
+   path. Skra ships as one package, `@skra/ui`, with a secondary entry point per component
+   (e.g. `@skra/ui/button`, `@skra/ui/typography`, `@skra/ui/select`); the primary
+   `@skra/ui` exports nothing. (Full entry-point list → `setup-and-gotchas.md`.)
+2. **You own the value.** Skra form atoms do **not** implement `ControlValueAccessor` /
+   `FormValueControl` (ADR 037). Native-host atoms take `[formField]`/`[formControl]`/
+   `[(ngModel)]`; value-owned overlays need an explicit `[value]`/`(valueChange)` bridge.
+   (How → `forms-and-binding.md`.)
+3. **Accessible name has exactly ONE path** (ADR 033). No Skra atom exposes an `ariaLabel`
+   input; never put `aria-label` next to visible text on the same host. (Paths →
+   `accessible-names.md`.)
+4. **Inside `<skra-field>`, do not pass `id` / `for` / `aria-describedby` by hand** — the
+   DI context wires label↔control↔hint↔error automatically (ADR 013).
+5. **Under Signal Forms, native constraint attributes go in the schema, not the template.**
+   `name` on grouped radios and `maxlength` / `min` / `pattern` on a `[formField]` host raise
+   `NG8022` — Signal Forms owns them (F-1/F-2). (Details → `forms-and-binding.md`.)
+6. **Never theme with inline styles.** No `[style.--skra-*]` bindings or `style="…"` (breaks
+   CSP, ADR 021). Override tokens via a CSS class / `data-skra-*` scope; components are
+   `margin: 0` (ADR 022) — spacing comes from layout atoms, never a margin on the component.
+
+---
+
+## Section Router — load the ONE that matches your task
+
+| Section                     | File                           | Load when                                                                                                              | Status   |
+| --------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -------- |
+| **Setup & gotchas**         | `setup-and-gotchas.md`         | First integration; import fails; which `@skra/*` package exports what; boolean-attribute & theming pitfalls            | ✅ draft |
+| **Forms & value binding**   | `forms-and-binding.md`         | Wiring an input / select / checkbox / rating to Signal Forms, Reactive Forms, or `ngModel`                             | ✅ draft |
+| **Accessible names**        | `accessible-names.md`          | Naming buttons, icon-only controls, overlays; using `skra-sr-only`                                                     | ✅ draft |
+| **Theming & encapsulation** | `theming-and-encapsulation.md` | Skins, dark mode, density; mounting under Shadow DOM / a microfrontend / an iframe                                     | ✅ draft |
+| **Feedback**                | `feedback.md`                  | Alert vs toast vs badge vs field error; `live` announcing; dismissal; an alert with a next-step action                  | ✅ draft |
+| **Overlays**                | `overlays.md`                  | Dialog / tooltip / popover / menu / select in the top layer; shadow & iframe limits                                    | ✅ draft |
+| **Layout**                  | `layout.md`                    | Spacing & composition with Stack / Box / Surface / Grid; building a card; the gap scale                                | ✅ draft |
+| **Wrapping Skra**           | `wrapping-patterns.md`         | Building your own higher-level components over Skra atoms (simplified API)                                             | ✅ draft |
+| **Custom components**       | `custom-components.md`         | Authoring a net-new widget Skra does not ship (nothing to wrap) on Skra tokens — own token tier, state, promotion path | ✅ draft |
+
+---
+
+## Quick reference — task → section
+
+| I want to…                                                              | Go to                                     |
+| ----------------------------------------------------------------------- | ----------------------------------------- |
+| Add `@skra/ui/*` to a project and import an atom                        | `setup-and-gotchas.md`                    |
+| Bind a text input / textarea to a form                                  | `forms-and-binding.md`                    |
+| Bind a `skra-select` / `skra-datepicker` / `skra-star-rating` to a form | `forms-and-binding.md` (the value bridge) |
+| Name an icon-only button                                                | `accessible-names.md`                     |
+| Switch skin / dark mode at runtime                                      | `theming-and-encapsulation.md`            |
+| Mount Skra inside a Web Component / microfrontend                       | `theming-and-encapsulation.md`            |
+| Show an alert / toast / badge, or add a "Try again" button to an alert  | `feedback.md`                             |
+| Open a dialog or tooltip                                                | `overlays.md`                             |
+| Space components apart                                                  | `layout.md`                               |
+| Build a card / panel / tile (there is no `skra-card`)                   | `layout.md` (Surface)                     |
+| Wrap a Skra atom in a project-specific component                        | `wrapping-patterns.md`                    |
+| Build a widget Skra does not ship (scrubber, timeline, domain visual)   | `custom-components.md`                    |
+| Keep an app-local component on-skin, on-density, dark-mode-correct      | `custom-components.md`                    |
+
+---
+
+_Source of truth for the rules: Skra `FORGE_ADR_SUMMARY.md` + `adr/decisions/`. Real
+consumption evidence: `apps/dogfood/FRICTION_JOURNAL.md`. This guide restates the consumer
+slice of those — on divergence, the ADRs win._

package/consumer-guide/accessible-names.md

@@ -42,7 +42,8 @@ must be loaded (and bridged into any shadow root — see `theming-and-encapsulat
 or the text renders visibly.
 
 > The same pattern names other built-in sr-only slots, e.g. `[skra-alert-close-label]` on
-> `skra-alert`'s dismiss button.
+> `skra-alert`'s dismiss button. An alert **action** (`[skra-alert-actions]`) names itself by its
+> visible text (Path 1); in a live alert that label is announced with the message (`feedback.md`).
 
 ## Path 3 — `aria-label` on an icon-only host
 

package/consumer-guide/custom-components.md

@@ -0,0 +1,154 @@
+# Building Your Own Component on Skra Tokens
+
+> Load this for: authoring a **net-new widget that Skra does not ship and that has no Skra atom
+> to wrap** — a scrubber, a timeline, a domain visual — while keeping it inside the design
+> system's guarantees (skin, dark scheme, density, contrast, CSP).
+>
+> If you are simplifying the API of an atom Skra _does_ ship, you want `wrapping-patterns.md`
+> instead. This page is for the case where there is nothing to wrap.
+
+## Step 0 — decompose before you build
+
+Most "I need a component Skra doesn't have" cases are not one component. Split the widget into
+three buckets first, because two of them are already solved:
+
+| Bucket                                                                   | Where it belongs                                                        |
+| ------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| Parts that ARE Skra atoms — buttons, icons, text, a painted container    | `@skra/ui` (`skraButton`, `skra-icon`, `skraTypography`, `skraSurface`) |
+| Domain logic — media elements, state machines, data fetching, formatting | your app's services/stores. Not a design-system concern at any level    |
+| The genuinely novel visual — the part with no atom and no analogue       | this page                                                               |
+
+The third bucket is usually much smaller than it first looks. Build only that.
+
+## The rule — own your tier 3, resolve it to tier 2
+
+Skra's token engine has four layers: **1 `ref`** (raw values) → **2 `sys`** (semantic) →
+**3 `comp`** (component-scoped) → **4 API** (per-instance overrides).
+
+Layer 3 can only be _minted_ inside the Skra repo, because a `--skra-comp-*` token needs a value
+in every skin. That does **not** mean your component drops to layer 2. It means your component
+**owns its own layer 3**, in its own namespace, with defaults that resolve to layer 2:
+
+```scss
+/* app-scrubber.component.scss */
+:host {
+  /* Your tier 3 — one block, the only place a value is decided. */
+  --app-scrubber-track-background: var(--skra-sys-color-surface-muted);
+  --app-scrubber-track-radius: var(--skra-sys-radius-full);
+  --app-scrubber-track-size: var(--skra-sys-spacing-2);
+  --app-scrubber-thumb-background: var(--skra-sys-color-primary-base);
+  --app-scrubber-thumb-size: var(--skra-sys-size-interactive-sm);
+  --app-scrubber-padding-inline: var(--skra-sys-spacing-3);
+  --app-scrubber-focus-ring-color: var(--skra-sys-color-focus-ring);
+  --app-scrubber-focus-ring-width: 0.125rem; /* no sys token for this — core keeps it literal too */
+
+  display: block;
+  margin: 0; /* ADR 022 — outer spacing is the container's job, never the component's */
+  padding-inline: var(--app-scrubber-padding-inline);
+}
+
+/* State comes from an attribute, never from a bound style (ADR 021 — CSP-safe). */
+:host(:hover) {
+  --app-scrubber-thumb-background: var(--skra-sys-color-primary-base-hover);
+}
+:host([data-app-dragging]) {
+  --app-scrubber-thumb-background: var(--skra-sys-color-primary-base-active);
+}
+:host([data-app-disabled]) {
+  --app-scrubber-track-background: var(--skra-sys-color-neutral-soft);
+  --app-scrubber-thumb-background: var(--skra-sys-color-neutral-base);
+}
+
+.app-scrubber-track {
+  background: var(--app-scrubber-track-background);
+  border-radius: var(--app-scrubber-track-radius);
+  block-size: var(--app-scrubber-track-size);
+}
+.app-scrubber-thumb {
+  background: var(--app-scrubber-thumb-background);
+  inline-size: var(--app-scrubber-thumb-size);
+  block-size: var(--app-scrubber-thumb-size);
+}
+.app-scrubber-thumb:focus-visible {
+  outline: var(--app-scrubber-focus-ring-width) solid var(--app-scrubber-focus-ring-color);
+}
+```
+
+```ts
+// app-scrubber.component.ts — state reaches CSS as attributes, not as style bindings.
+@Component({
+  selector: 'app-scrubber',
+  host: {
+    '[attr.data-app-dragging]': 'dragging() ? "" : null',
+    '[attr.data-app-disabled]': 'disabled() ? "" : null',
+  },
+  // …
+})
+```
+
+Why not read `sys` directly at each property? Because then the value is scattered across the
+file, per-instance overrides have nothing to target, and promoting the widget into Skra later
+becomes a rewrite instead of a rename.
+
+**Namespace:** use **your own prefix** (`--app-*`, `--acme-*`). Do **not** declare
+`--skra-comp-*` or `--skra-sys-*` values of your own — that namespace belongs to the token
+engine, a skin may overwrite it at any time, and a future Skra component of the same name
+would collide with you.
+
+## What you get for free
+
+Everything below follows from resolving your defaults to `sys` — no work on your side:
+
+| Capability             | Why it works                                                                                                                                                                                                         |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Every skin**         | `sys` is redefined per skin; your widget re-paints when the skin changes                                                                                                                                             |
+| **Dark scheme**        | the dark layer redefines the same `sys` names                                                                                                                                                                        |
+| **Density**            | `[data-skra-density]` remaps `--skra-sys-spacing-*` and `--skra-sys-size-interactive-*` at the **sys** layer — so a widget sized from those follows density automatically. Hardcoding `padding: 0.5rem` opts you out |
+| **Interaction states** | the build synthesises `-hover` / `-active` for `sys` colours too (`--skra-sys-color-primary-base-hover`), scaled by each skin's interaction profile                                                                  |
+| **Shadow DOM / CSP**   | custom properties inherit across shadow boundaries; attribute-driven state needs no inline styles                                                                                                                    |
+
+## What you do NOT get — plan around it
+
+1. **No build-time contrast gate on your pairs.** Skra fails its own build on a bad
+   foreground/background pair; your widget's pairs are not measured. Prefer pairs Skra already
+   gates (`*-strong` / `*-soft`, `on-*` foregrounds) over improvised combinations, and check
+   any novel pair manually.
+2. **No state synthesis from a colour of your own.** You cannot generate a hover ramp from a
+   bespoke base — pick a `sys` colour that already ships `-hover` / `-active`. In practice this
+   is a healthy constraint: it keeps you inside the skin's palette.
+3. **No skin-surface manifest.** Your tokens are invisible to skin/preset tooling.
+4. **No per-skin bespoke treatment.** Your widget inherits what flows through `sys` (each
+   skin's own radius scale, palette and interaction strength) — not a hand-tuned variant.
+
+## The floor — non-negotiable, whatever the widget
+
+These are the rules that make a component _reusable_ rather than _copy-pasteable_. A hardcoded
+`#FFD700` cannot be re-skinned by your next app; that is the whole difference.
+
+- **Every value maps to a token.** No colour literals, no magic pixel values where a
+  `--skra-sys-*` exists. Structural constants (a `1.4s` pulse, a `50%` split) are fine.
+- **CSP-safe state.** State reflects as an attribute on the host and is styled by an attribute
+  selector. Never `[style.--var]="signal()"`, never runtime style mutation.
+- **Zero outer margin.** `margin: 0` on the host; spacing between components belongs to the
+  layout atoms (`skraStack` / `skraBox`).
+- **Accessible name and keyboard behaviour before paint.** Follow the WAI-ARIA APG pattern the
+  widget actually is; see `accessible-names.md`.
+- **No `!important`, no `::ng-deep`, no skin names in selectors.**
+
+## Promotion path — when the widget outgrows the app
+
+Location is deliberately reversible: a widget whose defaults resolve to `sys` moves without a
+single token change.
+
+1. **App-local** — the default, and where it stays while exactly one app uses it.
+2. **Your own shared library** (`@yourorg/ui`, built ON Skra) — when a **second** app genuinely
+   needs it. Do not build the shared package for a widget that exists in one app; that is
+   speculative generality.
+3. **Skra core** — only if it stops being domain-specific: no domain vocabulary, no third-party
+   runtime dependency, and a consumer in a _different_ domain would use it as-is. That is a
+   feature request against Skra, not something you can do from outside.
+
+---
+
+_See also: `wrapping-patterns.md` (simplifying a Skra atom's API), `theming-and-encapsulation.md`
+(loading token layers, skin/scheme/density switching), `accessible-names.md`, `layout.md`._

package/consumer-guide/feedback.md

@@ -0,0 +1,100 @@
+# Feedback — Alerts, Toasts, Badges
+
+> Load this for: telling the user what happened — an in-page alert, a transient toast, a status
+> badge — and putting a next step ("Try again") inside an alert.
+> Governed by ADR 0052 (live-region semantics), ADR 035 (intent / emphasis) and ADR 0059
+> (actions on an intent-tinted ground).
+
+## Which one?
+
+| You need to…                                               | Use                                                                    |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Say something about a page or a section, and keep it there | `<skra-alert>` (`@skra/ui/alert`)                                      |
+| Confirm an action briefly without moving focus ("Saved")   | `<skra-toast>` inside one `<skra-toast-region>` (`@skra/ui/toast`)     |
+| Label a thing with a short status ("Draft", "3 new")       | `<skra-badge>` (`@skra/ui/badge`)                                      |
+| Say what is wrong with ONE form value                      | `<skra-error>` inside `<skra-field>` (`@skra/ui/field`) — not an alert |
+
+The alert, the toast and the badge take the same two look-free axes (`<skra-error>` is always an error): `intent` (`neutral` · `info` · `success` · `warning` ·
+`danger`) and `emphasis` (`high` = filled, `medium` = soft; the default). Put the severity in the
+**text** too — colour and icon alone do not carry meaning (WCAG 1.4.1).
+
+## Announcing (`live`)
+
+`live` decides whether a screen reader announces the content when it appears; it maps to the
+implicit `role` (`polite` → `status`, `assertive` → `alert`). It is about **how the content
+arrives**, not how severe it is:
+
+- present when the page loads → leave `live="off"` (alert default);
+- inserted after the user did something → `live="polite"`, or `"assertive"` for a failure that
+  blocks them.
+
+Skra sets the role only — never add `aria-live` / `aria-atomic` yourself. A live region announces
+its whole text, **including the labels of the controls inside it** (the dismiss label, an action).
+
+## Dismissal is yours
+
+`dismissible` renders a close control and emits `(dismissed)`. The alert does **not** remove
+itself — you do, with `@if`, the same way you showed it. Name the control with a projected
+`[skra-alert-close-label]` (visually hidden text; `accessible-names.md`). If the close control had
+focus, move focus somewhere sensible before you remove the alert.
+
+```html
+@if (saveFailed()) {
+<skra-alert intent="danger" live="assertive" dismissible (dismissed)="saveFailed.set(false)">
+  Could not save.
+  <span skra-alert-close-label class="skra-sr-only">Dismiss</span>
+</skra-alert>
+}
+```
+
+## An alert with an action
+
+Mark each next-step button `[skra-alert-actions]`. The alert places the actions **below the
+message**, as a row that wraps on a narrow container, and never lets them collide with the close
+control. Several actions are fine; they keep your order.
+
+```html
+<skra-alert intent="danger" live="assertive">
+  <span skra-alert-title>Could not save</span>
+  Your changes are kept on this device. Check your connection and try again.
+  <button skraButton skra-alert-actions emphasis="medium" type="button" (click)="retry()">Try again</button>
+</skra-alert>
+```
+
+**The action keeps its own meaning.** The alert does not pass its `intent` to the button. A retry
+inside a `danger` alert is not a destructive action, so it must not be a `danger` button — that
+colour means "this deletes something". Choose the button's `intent` for what the button **does**,
+exactly as anywhere else.
+
+**What is guaranteed legible on the alert's colour.** Skra measures these combinations in every
+state (rest, hover, pressed, focus), both colour schemes and every shipped skin:
+
+| Alert                         | Guaranteed actions                                                              |
+| ----------------------------- | ------------------------------------------------------------------------------- |
+| `emphasis="medium"` (default) | a `neutral` button at any emphasis; a button of any intent at `emphasis="high"` |
+| `emphasis="high"` (filled)    | a button of any intent at `emphasis="high"` **other than the alert's own**      |
+
+- The zero-config `<button skraButton skra-alert-actions>` (`neutral`, `high`) is guaranteed on
+  every alert except a `neutral` + `high` one.
+- **Not supported:** a coloured `medium`/`low` button; a `medium`/`low` button on a filled alert
+  (it measured as low as 1.2:1); a `high` button in the alert's own intent (it has the alert's
+  exact colour — no visible button). Nothing stops you writing them; nothing guarantees them either.
+- Only `button[skraButton]` is measured in the actions row. A link or a badge there is on you.
+- The focus ring of the actions follows the alert (on a filled alert it switches to the alert's
+  text colour, because the page ring disappears on the fill). To re-colour it, target the alert's
+  per-variant hook `--skra-comp-alert-focus-ring-color-<intent>-<emphasis>` in a skin overlay preset
+  (the only tier its manifest allows) — never the button's ring.
+- An action that **navigates** is still a `<button>` that routes — Skra has no link styled as a
+  button (ADR 032).
+
+## Toasts
+
+One `<skra-toast-region>` near the app root announces every toast from persistent live regions;
+each `<skra-toast>` sets `intent`, `emphasis`, `live` (default `polite`), `duration` (ms; pauses on
+hover / focus) and `dismissible` → `(dismissed)`. Removal is yours, as for the alert. Toasts do
+not take actions yet.
+
+## Badges
+
+`<skra-badge>` is a small, inline, non-interactive status label (`intent`, `emphasis`, optional
+`[skra-badge-icon]`). Leave `live="off"` unless the badge changes while the user watches it.