@skra/ui 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,7 @@
+Skra Design System
+Copyright 2026 Bartosz Badacz
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+A copy of the License is distributed with this software in the LICENSE file
+and is available at http://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -0,0 +1,39 @@
+# @skra/ui
+
+> **Project status** — built primarily for the author's own applications and published
+> quietly. No support, roadmap, or stability guarantees beyond the documented SemVer
+> contract. Licensed under Apache-2.0 (see `LICENSE` / `NOTICE`).
+
+Skra Design System — native Angular components (Angular 21, Signals, standalone). One
+umbrella package with **per-component secondary entry points** (ADR 0054):
+
+```typescript
+import { SkraButton } from '@skra/ui/button';
+import { SkraSelect, SkraOption } from '@skra/ui/select'; // composite + re-exported satellite
+import { SkraNativeSelect } from '@skra/ui/native-select'; // native-host skinning directive
+```
+
+Import from the entry point, never from a deep path. The full entry-point list is the
+`exports` map of this package.
+
+## Companion packages (lockstep versions)
+
+- **`@skra/tokens`** (peerDependency) — the CSS value layers and structural slices. Components
+  are unstyled without a loaded skin; install the matching version and import a skin's
+  artifacts into your global stylesheet. See that package's README for import order.
+- **`@skra/shadow-dom-bridge`** — framework-agnostic style delivery into Shadow DOM roots.
+
+## SemVer contract
+
+- Symbols prefixed with `_` (e.g. `_SkraSelectBase`, `_attachPositioner`) are internal
+  machinery exported only for cross-entry-point wiring. They are **outside the SemVer
+  contract** and may change in any release (ADR 0054 R-54.5).
+- Removing/renaming an entry point or a public symbol is a major; adding an entry point is a
+  minor (ADR 010).
+
+## Consumer guide
+
+The `consumer-guide/` directory inside this package is the maintained guide for teams (and
+AI agents) building on Skra: setup and gotchas, forms and binding strategy, accessible-name
+rules, theming/encapsulation, overlays, layout, and wrapping patterns. Start at
+`consumer-guide/README.md`.

package/consumer-guide/README.md

@@ -0,0 +1,84 @@
+# 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 / Grid; 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`                               |
+| 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._

package/consumer-guide/accessible-names.md

@@ -0,0 +1,80 @@
+# Accessible Names
+
+> Load this for: naming buttons, icon-only controls, and decorative graphics; using
+> `skra-sr-only`. Governed by ADR 033 (Accessible Name Contract) + ADR 034 (icon a11y).
+
+## The one rule (ADR 033)
+
+Every interactive Skra component supports **exactly ONE** accessible-name path. Two hard
+constraints follow:
+
+- **No Skra atom exposes an `ariaLabel` input.** Don't look for one; it isn't there by design.
+- **`aria-label` must NOT coexist with visible `textContent`** on the same Skra host. Pick a
+  path, don't mix.
+
+Three paths:
+
+## Path 1 — visible text is the name (the default, ~most cases)
+
+The rendered text content *is* the accessible name. Nothing to wire:
+
+```html
+<button skraButton>Save changes</button>
+```
+
+## Path 2 — visible text + a screen-reader-only extension
+
+When the visible label is right for sighted users but a screen reader needs more context
+(e.g. *which* item a generic "Remove" acts on). Project an extra span hidden with the
+`skra-sr-only` utility. **Class and attribute are equivalent** — use whichever reads better:
+
+```html
+<!-- a remove control whose visible glyph is an ×, named "Remove {item}" for AT -->
+<skra-chip>
+  Marketing
+  <span skra-chip-remove-label class="skra-sr-only">Remove Marketing</span>
+</skra-chip>
+```
+
+The consumer **applies the utility class** and **owns the i18n** (the interpolated item name)
+— the atom only provides the slot. `skra-sr-only` lives in the `utilities.scss` slice, so it
+must be loaded (and bridged into any shadow root — see `theming-and-encapsulation.md`, F-15),
+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.
+
+## Path 3 — `aria-label` on an icon-only host
+
+When there is **no** visible text (an icon-only control), put a **native** `aria-label`
+directly on the host. This is the one sanctioned `aria-label` use (native-attr-first rule 2 —
+there is no visible text to conflict with):
+
+```html
+<button skraButton aria-label="Close dialog">
+  <!-- icon only, no text node -->
+  …icon…
+</button>
+```
+
+### Decorative vs meaningful icons (ADR 034)
+
+An icon that *is* the meaning (no adjacent text) must be exposed to AT — the icon container
+takes `role="img"` + a label. A purely decorative icon next to visible text stays
+`aria-hidden`. Never make an icon meaningful **and** leave it unlabelled.
+
+## Decorative graphics — Avatar / StatusDot / RatingDisplay
+
+These display atoms ship **two modes** (the Path-3 family, ~90% is Mode A):
+
+- **Mode A (decorative, default):** the host is `aria-hidden="true"`; meaning is carried by
+  adjacent text. Use when the graphic sits beside a name / a "4 / 5" value. **Colour is never
+  the sole carrier of status** (WCAG 1.4.1) — a lone coloured status dot needs an adjacent text
+  label.
+- **Mode B (standalone):** the consumer opts in with `role="img"` + `aria-label` when the
+  graphic stands alone with no adjacent text.
+
+## Inside `<skra-field>`
+
+A field control is named by its `<label skraLabelFor>` automatically (Path 1, via the DI
+context) — do not add `aria-label`. See `forms-and-binding.md`.

package/consumer-guide/forms-and-binding.md

@@ -0,0 +1,149 @@
+# Forms & Value Binding
+
+> Load this for: wiring a Skra form atom to **Signal Forms**, **Reactive Forms**, or
+> **`ngModel`**. The governing rule is ADR 037: **Skra atoms are agnostic — you own the
+> value and pick the binding strategy.** No atom implements `ControlValueAccessor` /
+> `FormValueControl`.
+
+## The two classes of form atom
+
+How you bind depends on which kind you are holding:
+
+### A. Native-host atoms → bind directly on the native element
+
+These are Skra directives **on a native `<input>`/`<textarea>`** (Component-on-native-host,
+ADR 040 — there is **no** `<skra-checkbox>`/`<skra-radio>` custom element). Angular's form
+directives attach to the same host, so `[formField]`, `[formControl]`/`formControlName`, and
+`[(ngModel)]` all work orthogonally with the Skra directive (it only adds a11y + skin):
+
+- `input[skraInput]`, `textarea[skraTextarea]`
+- `input[type="checkbox"][skraCheckbox]`, `input[type="radio"][skraRadio]`
+- `input[type="checkbox"][skraSwitch]`
+
+```html
+<!-- text: Signal Forms / Reactive / ngModel — all valid -->
+<input skraInput [formField]="form().email" />
+<input skraInput [formControl]="emailCtrl" />
+<input skraInput [(ngModel)]="email" />
+
+<!-- checkbox / switch: native checked + change (or any form directive) -->
+<input type="checkbox" skraCheckbox
+       [checked]="accepted()" (change)="accepted.set($any($event.target).checked)" />
+```
+
+**Radios group natively** — `<fieldset skraFieldset>` + `<legend skraLegend>`, with
+selection coordinated through the shared `name`:
+
+```html
+<fieldset skraFieldset>
+  <legend skraLegend>Choose plan</legend>
+  <skra-field>
+    <input type="radio" skraRadio name="plan" value="free"
+           [checked]="plan() === 'free'" (change)="plan.set('free')" />
+    <label skraLabelFor>Free</label>
+  </skra-field>
+</fieldset>
+```
+
+> Under **Signal Forms**, drop the native `name` on radios — SF derives it from the bound
+> field and a literal `name` raises `NG8022` (F-1; see the Signal Forms section below).
+
+### B. Value-owned overlays / composites → use the explicit value bridge
+
+These are custom-element widgets that deliberately do **not** implement `FormValueControl`
+(ADR 037), so `[formField]` does **not** apply. Bind value out + value in explicitly:
+
+- `skra-select`, `skra-multi-select`, `skra-combobox`, `skra-datepicker`,
+  `skra-star-rating`
+
+```html
+<!-- Signal Forms: the two-binding bridge (F-3, F-23) -->
+<skra-select
+  [value]="form().country().value()"
+  (valueChange)="form().country().value.set($event)">
+  …
+</skra-select>
+```
+
+```html
+<!-- Plain signal / ngModel-style -->
+<skra-star-rating [value]="rating()" (valueChange)="rating.set($event)" />
+```
+
+The verbosity gap vs class A (one attribute → two) is **intended**, not a defect — it is the
+price of the atom staying framework-agnostic. If it recurs across many fields, see
+[Reducing the bridge boilerplate](#reducing-the-bridge-boilerplate).
+
+> Reminder: there is **no** `<skra-checkbox>`/`<skra-radio>` element — those are the
+> class-A native-host directives above. `skra-counter` is not an input either (see below).
+
+## `skra-counter` — a display atom, not an input
+
+`skra-counter` renders a live character count for a sibling control; it does **not** hold
+the field's value (ADR 037 §3.3 forbids a value channel in the context). Feed it the current
+string + an optional max:
+
+```html
+<skra-field>
+  <label skraLabelFor>Bio</label>
+  <textarea skraTextarea [formField]="form().bio"></textarea>
+  <skra-counter [value]="form().bio().value()" [max]="500" />
+</skra-field>
+```
+
+It displays `{{length}}` or `{{length}}/{{max}}`. The native length cap is separate — and
+under Signal Forms `maxlength` goes in the schema (F-2), not on the host.
+
+## Signal Forms specifics — native constraints belong in the schema, not the template
+
+When `[formField]` is present, **Signal Forms owns the native constraint attributes**.
+Setting them in the template is a compile error (`NG8022`):
+
+- ✗ `name` on grouped radios (F-1) — SF derives it from the bound field.
+- ✗ `maxlength` / `min` / `max` / `pattern` on the host (F-2) — declare them in the schema.
+
+```ts
+// ✓ constraint in the schema
+maxLength(p.bio, 160);
+```
+```html
+<!-- ✗ NG8022 -->
+<textarea skraTextarea [formField]="form().bio" maxlength="160"></textarea>
+<!-- ✓ -->
+<textarea skraTextarea [formField]="form().bio"></textarea>
+```
+
+This is a Signal-Forms composition rule, not a Skra defect — but a consumer hits it on the
+first grouped radio / length-limited field.
+
+## A11y wiring is automatic inside `<skra-field>` (ADR 013)
+
+Do **not** hand-wire `id`, `for`, or `aria-describedby`. Wrapping a control in
+`<skra-field>` links label ↔ control ↔ hint ↔ error through a DI context. Just project the
+parts:
+
+```html
+<skra-field>
+  <label skraLabelFor>Email</label>
+  <input skraInput [formField]="form().email" />
+  <skra-hint>We'll never share it.</skra-hint>
+  <skra-error>{{ emailError() }}</skra-error>
+</skra-field>
+```
+
+> Confirmed against `component-field-spec.md`: the label is `<label skraLabelFor>`, hint is
+> `<skra-hint>`, error is `<skra-error>`; the context publishes `id`/`for` and folds
+> `hintId`/`errorId` into the control's `aria-describedby` (dangling refs ignored when a part
+> is absent).
+
+For the **accessible name** of a control (especially icon-only), see `accessible-names.md`
+— there is exactly one valid path and no `ariaLabel` input.
+
+## Reducing the bridge boilerplate
+
+If class-B fields are everywhere and the two-binding bridge is noisy, the sanctioned shape is
+a **consumer-side adapter directive** (e.g. `[skraControl]` mapping a form node ↔
+`value`/`valueChange`) living in **your** interop layer — **never** inside the atom (that
+would break ADR 037 / atoms-agnostic). Whether Skra should ship such an adapter as an
+optional `@skra/angular-interop` package is an open architectural question (out of scope for
+this guide). See also `wrapping-patterns.md`.

package/consumer-guide/layout.md

@@ -0,0 +1,86 @@
+# Layout
+
+> Load this for: spacing and composition with Stack / Box / Grid, and the gap scale.
+> Governed by ADR 041 (layout atoms on native hosts) + ADR 022 (layout isolation).
+
+## The rule that makes layout necessary (ADR 022)
+
+Skra components carry `margin: 0`. **Spacing between components is never a margin on the
+component** — it comes from a layout primitive. There are three, and they are **directives on
+a native host** (a bounded allowlist of `div`/`section`/`nav`/`ul`/…), **never** a
+`<skra-stack>` custom element. Put them on the semantic element you'd use anyway:
+
+```html
+<section skraStack gap="md">…</section>     <!-- not <div><skra-stack> -->
+<ul skraStack gap="sm">…</ul>                 <!-- list markers normalized, restorable -->
+```
+
+## Stack — 1D flex (`[skraStack]`)
+
+Arranges children in a row or column.
+
+| Input | Values | Default |
+| --- | --- | --- |
+| `direction` | `row` \| `column` | `column` |
+| `gap` | `none` \| `sm` \| `md` \| `lg` | `md` |
+| `align` | `start` \| `center` \| `end` \| `stretch` | `stretch` |
+| `justify` | `start` \| `center` \| `end` \| `between` \| `around` | `start` |
+| `wrap` | boolean | `false` |
+
+```html
+<div skraStack direction="row" gap="sm" wrap align="center">
+  <skra-chip>One</skra-chip>
+  <skra-chip>Two</skra-chip>
+</div>
+```
+
+(`wrap` is a bare boolean attribute — every Skra boolean input carries `booleanAttribute`, so
+the bare form works; see `setup-and-gotchas.md`.)
+
+## Box — padding / spacing (`[skraBox]`)
+
+A semantically-neutral padding primitive. Does **not** arrange children (no list hosts).
+
+| Input | Values | Default |
+| --- | --- | --- |
+| `padding` | `none` \| `sm` \| `md` \| `lg` | `none` |
+| `display` | `block` \| `inline-block` \| `flex` | `block` |
+
+```html
+<section skraBox padding="lg">…</section>
+```
+
+## Grid — 2D (`[skraGrid]`)
+
+Bucket-only CSS Grid. The default `columns="auto-fit"` + `min` gives an intrinsically
+responsive card grid (column count tracks width, **no media/container queries**):
+
+| Input | Values | Default |
+| --- | --- | --- |
+| `columns` | `1`…`6` \| `auto-fit` \| `auto-fill` | `auto-fit` |
+| `min` | `sm` \| `md` \| `lg` | — |
+| `gap` | `none` \| `sm` \| `md` \| `lg` | — |
+| `flow` | `row` \| `column` \| `dense` | — |
+| `align` | `start` \| `center` \| `end` \| `stretch` | — |
+| `justifyItems` | `start` \| `center` \| `end` \| `stretch` | — |
+
+```html
+<div skraGrid columns="auto-fit" min="md" gap="md">
+  <!-- responsive cards, no breakpoints -->
+</div>
+```
+
+Arbitrary track lists, `grid-template-areas`, named lines and per-item placement are **out of
+scope by design** (bespoke = native CSS — exposing them would force an inline-style host
+binding, ADR 021). Drop to plain CSS Grid for those.
+
+## The gap scale is coarse — `none | sm | md | lg` (F-4)
+
+There is no `xs` / `xl` / numeric / arbitrary gap. When you need a tighter or larger rhythm:
+
+- nest stacks (an outer `lg`, an inner `sm`), or
+- lean on typography line-height for sub-`sm` text pairs, or
+- drop to native CSS for a genuinely bespoke layout.
+
+This is a known coarseness (a token-scale decision for the Skra side), not something to work
+around with inline styles.