@skra/ui 0.5.0 → 0.6.0

package/consumer-guide/README.md

@@ -1,85 +1,88 @@
-# 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).** All 8 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 |
+| **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`            |
+| 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/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/wrapping-patterns.md

@@ -1,90 +1,98 @@
-# 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).
+# 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.
+
+**If there is no atom to wrap** — a net-new widget Skra does not ship at all (a scrubber, a
+timeline, a domain visual) — this page does not cover it. Go to `custom-components.md`, which
+gives the token contract that keeps such a component on-skin, on-density and dark-mode-correct.
+
+## 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).