actual-css 0.3.1 → 0.4.1

package/docs/pages/forms/labels.md

@@ -4,11 +4,11 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.field` | Composition | Field wrapper; canonical on `<label>` or `<div>`. |
-| `.field-label` | Composition | Label text, element-agnostic — works on `<span>`, a detached `<label for>`, or a `<legend>`. |
-| `.required-mark` | Composition | Visual required marker (`aria-hidden`) added inside a label. |
+| Class            | Kind        | Description                                                                                  |
+|------------------|-------------|----------------------------------------------------------------------------------------------|
+| `.field`         | Composition | Field wrapper; canonical on `<label>` or `<div>`.                                            |
+| `.field-label`   | Composition | Label text, element-agnostic — works on `<span>`, a detached `<label for>`, or a `<legend>`. |
+| `.required-mark` | Composition | Visual required marker (`aria-hidden`) added inside a label.                                 |
 
 Use a **wrapped label** for simple hand-authored forms. The whole label area becomes the click target, there is no `id` noise, and the markup is harder to break.
 
@@ -39,4 +39,4 @@ Use **`for`/`id`** when the layout needs the label and control in different grid
 </div>
 ```
 
-The mixed shape `<label for="x">…<input id="x"></label>` is allowed by the spec but rarely useful. Prefer either pure wrapped or pure `for`/`id`.
+The mixed shape `<label for="x">…<input id="x"></label>` is allowed by the spec but rarely useful. Prefer either pure wrapped or pure `for`/`id`.

package/docs/pages/forms/otp.md

@@ -1,6 +1,6 @@
 # One-time code input
 
-> **Optional** — import `actual-css/css/optional/otp` or `actual-css/css/optional/index`.
+> **Module** — import `actual-css/css/forms/otp` or `actual-css/css/forms/all`.
 
 OTP presents one native input as separate visual cells. Keeping a single input
 preserves paste, selection, autofill, password-manager, and
@@ -40,6 +40,38 @@ The component follows shared `.sm` and `.lg` density through `--control-size`.
 Use `aria-invalid="true"` for explicit invalid state, or place it in the
 standard `.needs-validation.was-validated` form flow.
 
+The `<input>` must be the **first** direct child, with one `<span>` per
+character after it — the state rules (focus, invalid, disabled) select the
+cells as following siblings, so that order is part of the contract.
+
+## Disabled
+
+Set `disabled` on the input. The cells rest on `--surface-subtle` with a muted
+`--state-disabled` border at `--disabled-opacity`, the code glyph turns
+`--state-disabled`, and the cursor is `not-allowed` — a clearly distinct,
+non-interactive look that follows the shared disabled contract. A disabled
+`<fieldset>` disables it the same way.
+
+```html demo
+<div class="otp" aria-label="Disabled verification code">
+  <input
+    class="input"
+    type="text"
+    autocomplete="one-time-code"
+    inputmode="numeric"
+    maxlength="6"
+    disabled
+    aria-label="Disabled verification code"
+  />
+  <span aria-hidden="true"></span>
+  <span aria-hidden="true"></span>
+  <span aria-hidden="true"></span>
+  <span aria-hidden="true"></span>
+  <span aria-hidden="true"></span>
+  <span aria-hidden="true"></span>
+</div>
+```
+
 ## CSS hooks
 
 - `--otp-cell-size` — width and height of every cell; follows `--control-size`.

package/docs/pages/forms/overview.md

@@ -12,23 +12,23 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.input` | Component | Text input; shares the text-control recipe with `.textarea` and `.select`. |
-| `.textarea` | Component | Multi-line text control. |
-| `.select` | Component | Dropdown — native baseline with a CSS chevron and an opt-in enhanced picker. |
-| `.check` | Component | Styled checkbox. |
-| `.radio` | Component | Styled radio button. |
-| `.switch` | Component | Toggle switch on a checkbox input with `role="switch"`. |
-| `.range` | Component | Native range slider with a theme-aware accent color. |
-| `.file` | Component | Native file input with a themed picker button. |
-| `.color` | Component | Native color picker in a control-sized box. |
-| `.field` | Composition | Field wrapper that works on `<label>` and `<div>`. |
-| `.field-label` | Composition | Label text; element-agnostic — `<span>`, detached `<label>`, or `<legend>`. |
-| `.field-help` | Composition | Supporting helper text under a control. |
-| `.field-error` | Composition | Inline error message shown while the field is invalid. |
-| `.field-group` | Composition | Grouped `<fieldset>` container with a tunable legend gutter. |
-| `.choice` | Composition | Choice-label layout wrapping a `.check`, `.radio`, or `.switch`. |
+| Class           | Kind        | Description                                                                   |
+|-----------------|-------------|-------------------------------------------------------------------------------|
+| `.input`        | Component   | Text input; shares the text-control recipe with `.textarea` and `.select`.    |
+| `.textarea`     | Component   | Multi-line text control.                                                      |
+| `.select`       | Component   | Dropdown — native baseline with a CSS chevron and an opt-in enhanced picker.  |
+| `.check`        | Component   | Styled checkbox.                                                              |
+| `.radio`        | Component   | Styled radio button.                                                          |
+| `.switch`       | Component   | Toggle switch on a checkbox input with `role="switch"`.                       |
+| `.range`        | Component   | Native range slider with a theme-aware accent color.                          |
+| `.file`         | Component   | Native file input with a themed picker button.                                |
+| `.color`        | Component   | Native color picker in a control-sized box.                                   |
+| `.field`        | Composition | Field wrapper that works on `<label>` and `<div>`.                            |
+| `.field-label`  | Composition | Label text; element-agnostic — `<span>`, detached `<label>`, or `<legend>`.   |
+| `.field-help`   | Composition | Supporting helper text under a control.                                       |
+| `.field-error`  | Composition | Inline error message shown while the field is invalid.                        |
+| `.field-group`  | Composition | Grouped `<fieldset>` container with a tunable legend gutter.                  |
+| `.choice`       | Composition | Choice-label layout wrapping a `.check`, `.radio`, or `.switch`.              |
 | `.form-actions` | Composition | Class-only flex row that closes a form; works inside or outside the `<form>`. |
 
 ## Example form
@@ -91,7 +91,7 @@ A full form using the control classes, field wrappers, and form actions:
 
     <fieldset class="field-group">
       <legend class="field-label">Availability</legend>
-      <div class="stack">
+      <div class="stack sm">
         <label class="choice">
           <input class="radio" type="radio" name="availability" value="available" checked />
           <span>Available for work</span>
@@ -185,4 +185,4 @@ form[data-required-marks="auto"]
 }
 ```
 
-`required` remains the accessible source of truth; this recipe adds only a visual cue. Use `data-required-mark="none"` on a `.field` when a required control should not receive the generated marker.
+`required` remains the accessible source of truth; this recipe adds only a visual cue. Use `data-required-mark="none"` on a `.field` when a required control should not receive the generated marker.

package/docs/pages/forms/password.md

@@ -37,4 +37,4 @@ the attribute instead:
 A revealed value does not survive navigation: a non-canceled form submit and
 `pagehide` both revert the input to hidden, so back navigation cannot land on
 a readable password. A canceled submit (failed validation, ajax) keeps the
-value revealed.
+value revealed.

package/docs/pages/forms/range.md

@@ -14,4 +14,4 @@ Core: native range, enhanced by `accent-color`. Optional richer skin may come la
 ## CSS hooks
 
 - `--range-thumb-size` — thumb diameter.
-- `--range-track-height` — track thickness.
+- `--range-track-height` — track thickness.

package/docs/pages/forms/states-and-sizes.md

@@ -4,21 +4,28 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
+| Class | Kind     | Description                                                                              |
+|-------|----------|------------------------------------------------------------------------------------------|
 | `.sm` | Modifier | Compact control height and spacing rhythm; sets `--control-size` to `--control-size-sm`. |
-| `.lg` | Modifier | Large control height and spacing rhythm; sets `--control-size` to `--control-size-lg`. |
+| `.lg` | Modifier | Large control height and spacing rhythm; sets `--control-size` to `--control-size-lg`.   |
 
 Use `readonly` for text-like values that can still be focused, selected, and submitted. Use `disabled` for unavailable controls that should not receive focus or submit a value.
 
-The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, selects, textareas, buttons, and switches. Put the modifier on the control itself, or on a `.field` wrapper when the whole field should share that size.
+The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, selects, textareas, and buttons. Put the modifier on the control itself, or on a `.field` wrapper when the whole field should share that size.
+
+Inline choices — `.check`, `.radio`, `.switch` — are the exception. They sit on
+a line of text rather than standing as a field, so they are sized off the
+control typography (`--choice-control-size`, an em value) and `.sm` / `.lg`
+leave them alone: density changes field heights, not type. Resizing the control
+without its label would only break the alignment. Scale them by scaling their
+type instead.
 
 ```html demo
 <form novalidate>
   <fieldset class="field-group">
     <legend class="field-label">Text control states</legend>
-    <div class="stack container-query">
-      <div class="grid-3 items-start">
+    <div class="stack" style="--grid-min: 14rem;">
+      <div class="grid items-start">
         <label class="field">
           <span class="field-label">Editable</span>
           <input class="input" type="text" value="Ocean Beach Clinic" />
@@ -37,7 +44,7 @@ The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, sele
         </label>
       </div>
 
-      <div class="grid-3 items-start">
+      <div class="grid items-start">
         <label class="field">
           <span class="field-label">Editable notes</span>
           <textarea class="textarea">Patient asked for an invoice copy.</textarea>
@@ -58,8 +65,8 @@ The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, sele
 
   <fieldset class="field-group">
     <legend class="field-label">Choice and select states</legend>
-    <div class="stack container-query">
-      <div class="grid-3 items-start">
+    <div class="stack" style="--grid-min: 14rem;">
+      <div class="grid items-start">
         <label class="field">
           <span class="field-label">Editable select</span>
           <select class="select">
@@ -89,7 +96,7 @@ The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, sele
         </label>
       </div>
 
-      <div class="grid-5 items-start">
+      <div class="grid items-start">
         <label class="choice">
           <input class="check" type="checkbox" />
           <span>
@@ -126,12 +133,12 @@ The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, sele
           <input class="check" type="checkbox" id="indet-demo" />
           <span>
             <span class="field-label">Indeterminate checkbox</span>
-            <span class="field-help">Partially selected — set via <code>element.indeterminate = true</code>. Try it: <button class="btn text sm" type="button" onclick="document.getElementById('indet-demo').indeterminate = !document.getElementById('indet-demo').indeterminate">toggle</button></span>
+            <span class="field-help">Partially selected — set via <code>element.indeterminate = true</code>. Try it: <button class="btn link sm" type="button" onclick="document.getElementById('indet-demo').indeterminate = !document.getElementById('indet-demo').indeterminate">toggle</button></span>
           </span>
         </label>
       </div>
 
-      <div class="grid-4 items-start">
+      <div class="grid items-start">
         <label class="choice">
           <input class="radio" type="radio" name="demo-radio-state" />
           <span>
@@ -165,7 +172,7 @@ The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, sele
         </label>
       </div>
 
-      <div class="grid-4 items-start">
+      <div class="grid items-start">
         <label class="choice">
           <input class="switch" type="checkbox" role="switch" />
           <span>
@@ -203,8 +210,8 @@ The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, sele
 
   <fieldset class="field-group">
     <legend class="field-label">Control sizes</legend>
-    <div class="stack container-query">
-      <div class="grid-3 items-start">
+    <div class="stack" style="--grid-min: 14rem;">
+      <div class="grid items-start">
         <label class="field sm">
           <span class="field-label">Small field</span>
           <input class="input" type="text" value="sm" />
@@ -221,7 +228,7 @@ The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, sele
         </label>
       </div>
 
-      <div class="grid-3 items-start">
+      <div class="grid items-start">
         <label class="field sm">
           <span class="field-label">Small select</span>
           <select class="select">
@@ -244,7 +251,7 @@ The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, sele
         </label>
       </div>
 
-      <div class="grid-3 items-start">
+      <div class="grid items-start">
         <label class="field sm">
           <span class="field-label">Small textarea</span>
           <textarea class="textarea" rows="2">Short note</textarea>
@@ -261,61 +268,50 @@ The `.sm` and `.lg` modifiers set the shared control tokens used by inputs, sele
         </label>
       </div>
 
-      <div class="grid-3 items-start">
+      <div class="grid items-start">
         <button class="btn outline sm" type="button">Small</button>
         <button class="btn outline" type="button">Default</button>
         <button class="btn outline lg" type="button">Large</button>
       </div>
 
-      <div class="grid-4 items-start">
+      <!-- Density is a deliberate no-op on inline choices: these three are
+           identical even though the modifiers differ. -->
+      <div class="grid items-start">
         <label class="choice sm">
           <input class="check" type="checkbox" checked />
-          <span>Small checkbox</span>
+          <span>.sm checkbox</span>
         </label>
         <label class="choice">
-          <input class="check" type="checkbox" checked />
-          <span>Default checkbox</span>
+          <input class="radio" type="radio" name="demo-radio-size" checked />
+          <span>Default radio</span>
         </label>
         <label class="choice lg">
-          <input class="check" type="checkbox" checked />
-          <span>Large checkbox</span>
+          <input class="switch" type="checkbox" role="switch" checked />
+          <span>.lg switch</span>
         </label>
         <label class="choice">
           <input class="check" type="checkbox" id="indet-size" />
-          <span>Indeterminate <button class="btn text sm" type="button" onclick="document.getElementById('indet-size').indeterminate = !document.getElementById('indet-size').indeterminate">toggle</button></span>
+          <span>Indeterminate <button class="btn link sm" type="button" onclick="document.getElementById('indet-size').indeterminate = !document.getElementById('indet-size').indeterminate">toggle</button></span>
         </label>
       </div>
 
-      <div class="grid-3 items-start">
-        <label class="choice sm">
-          <input class="radio" type="radio" name="demo-radio-size" checked />
-          <span>Small radio</span>
-        </label>
+      <!-- Typography is the knob that does resize them — control and label
+           together, so the alignment survives. -->
+      <div class="grid items-start" style="--control-font-size: var(--font-size-sm);">
         <label class="choice">
-          <input class="radio" type="radio" name="demo-radio-size" />
-          <span>Default radio</span>
-        </label>
-        <label class="choice lg">
-          <input class="radio" type="radio" name="demo-radio-size" />
-          <span>Large radio</span>
-        </label>
-      </div>
-
-      <div class="grid-3 items-start">
-        <label class="choice sm">
-          <input class="switch" type="checkbox" role="switch" checked />
-          <span>Small switch</span>
+          <input class="check" type="checkbox" checked />
+          <span>Smaller type</span>
         </label>
         <label class="choice">
-          <input class="switch" type="checkbox" role="switch" checked />
-          <span>Default switch</span>
+          <input class="radio" type="radio" name="demo-radio-type" checked />
+          <span>Smaller type</span>
         </label>
-        <label class="choice lg">
+        <label class="choice">
           <input class="switch" type="checkbox" role="switch" checked />
-          <span>Large switch</span>
+          <span>Smaller type</span>
         </label>
       </div>
     </div>
   </fieldset>
 </form>
-```
+```

package/docs/pages/forms/sticky-actions.md

@@ -57,7 +57,7 @@ Scroll the page to see the actions stay reachable.
 
     <fieldset class="field-group">
       <legend class="field-label">Theme</legend>
-      <div class="stack">
+      <div class="stack sm">
         <label class="choice">
           <input class="radio" type="radio" name="theme" value="light" checked />
           <span>Light</span>
@@ -141,7 +141,7 @@ Scroll the page to see the detached footer stay reachable.
 
     <fieldset class="field-group">
       <legend class="field-label">Theme</legend>
-      <div class="stack">
+      <div class="stack sm">
         <label class="choice">
           <input class="radio" type="radio" name="theme-detached" value="light" checked />
           <span>Light</span>
@@ -184,4 +184,4 @@ Scroll the page to see the detached footer stay reachable.
 }
 ```
 
-A sticky footer can cover the last field on short pages. That is a page-layout concern, not a framework concern. Add bottom padding to the page or scroll container if needed.
+A sticky footer can cover the last field on short pages. That is a page-layout concern, not a framework concern. Add bottom padding to the page or scroll container if needed.

package/docs/pages/forms/switch.md

@@ -21,11 +21,119 @@
        onchange="this.setAttribute('aria-checked', this.checked)" />
 ```
 
+Wrap a switch in `.choice` to pair it with a label. The switch stays
+top-aligned with the first line of text, so labels that wrap onto two lines —
+naturally or via an explicit line break — still sit cleanly.
+
+```html demo
+<label class="choice">
+  <input class="switch" type="checkbox" role="switch" checked />
+  <span>
+    Release alerts
+    <span class="field-help">Send status changes to the release channel.</span>
+  </span>
+</label>
+```
+
+```html demo
+<!-- Multi-line labels keep the switch aligned with the first line. -->
+<label class="choice">
+  <input class="switch" type="checkbox" role="switch" />
+  <span>
+    Send a summary of account activity for the past month, including any
+    unusual sign-ins, to the address on file.
+    <span class="field-help">A long label that wraps onto a second line.</span>
+  </span>
+</label>
+```
+
+```html demo
+<!-- Explicit line break, top-aligned with the first line. -->
+<label class="choice">
+  <input class="switch" type="checkbox" role="switch" />
+  <span>
+    Weekly summary with a<br />manual line break
+    <span class="field-help">A forced two-line label.</span>
+  </span>
+</label>
+```
+
+## Sizing and alignment
+
+A switch is sized off the control typography, not field density. Its track
+comes from `--choice-control-size` — the same token a checkbox and a radio use
+— so the three sit on a line of text at matching weight. `.sm` and `.lg` change
+`--control-size`, which is field height, and deliberately leave inline choices
+alone.
+
+The offset that centers each control on the first line of its label is derived
+from that control's own height, so a checkbox and a taller switch land on the
+same optical line. Change the type or the control size and they stay level:
+
+```html demo
+<!-- Same row, three heights: 18px checkbox, 18px radio, 20px switch track. -->
+<div class="cluster">
+  <label class="choice">
+    <input class="check" type="checkbox" checked />
+    <span>Checkbox</span>
+  </label>
+  <label class="choice">
+    <input class="radio" type="radio" name="align-default" checked />
+    <span>Radio</span>
+  </label>
+  <label class="choice">
+    <input class="switch" type="checkbox" role="switch" checked />
+    <span>Switch</span>
+  </label>
+</div>
+```
+
+```html demo
+<!-- A looser line-height re-centers every control by the same rule. -->
+<div class="cluster" style="line-height: 2.2;">
+  <label class="choice">
+    <input class="check" type="checkbox" checked />
+    <span>Checkbox</span>
+  </label>
+  <label class="choice">
+    <input class="radio" type="radio" name="align-tall" checked />
+    <span>Radio</span>
+  </label>
+  <label class="choice">
+    <input class="switch" type="checkbox" role="switch" checked />
+    <span>Switch</span>
+  </label>
+</div>
+```
+
+```html demo
+<!-- Scaling --choice-control-size grows the checkbox and the switch
+     track together, and the row stays aligned. -->
+<div class="cluster" style="--choice-control-size: 1.5em;">
+  <label class="choice">
+    <input class="check" type="checkbox" checked />
+    <span>Checkbox</span>
+  </label>
+  <label class="choice">
+    <input class="radio" type="radio" name="align-big" checked />
+    <span>Radio</span>
+  </label>
+  <label class="choice">
+    <input class="switch" type="checkbox" role="switch" checked />
+    <span>Switch</span>
+  </label>
+</div>
+```
+
 ## CSS hooks
 
+- `--choice-control-size` — shared size for inline choices; the switch track is
+  this plus `0.125em`, so scaling it scales the checkbox and the switch together.
 - `--switch-width` — track width.
 - `--switch-block-size` — track height.
 - `--switch-knob-margin` — inset between knob and track.
 
-Knob size and travel distance are derived from these three; set the three rather
-than the derived values. Prefer `.sm` / `.lg`, which change `--control-size`.
+Knob size and travel distance are derived from the three `--switch-*` hooks; set
+those rather than the derived values. The knob is concentric in its track: the
+inset is measured inside the border on both axes, so it clears the rails by the
+same distance it clears the ends.

package/docs/pages/forms/validation.md

@@ -4,14 +4,14 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.field-error` | Composition | Canonical inline error message; shown while the field is invalid. |
-| `.field-help` | Composition | Canonical helper text; carries supporting copy before and after validation. |
-| `.field.danger` | Modifier | Manual invalid marking on the field wrapper. |
-| `.needs-validation` | Modifier | Opt-in class for the validation enhancer and `:user-invalid` styling. |
-| `.was-validated` | Modifier | Added to the form by the enhancer after the first submit attempt. |
-| `.status-bar` | Component | Optional status element that shows `data-validation-message` on invalid submit. |
+| Class               | Kind        | Description                                                                     |
+|---------------------|-------------|---------------------------------------------------------------------------------|
+| `.field-error`      | Composition | Canonical inline error message; shown while the field is invalid.               |
+| `.field-help`       | Composition | Canonical helper text; carries supporting copy before and after validation.     |
+| `.field.danger`     | Modifier    | Manual invalid marking on the field wrapper.                                    |
+| `.needs-validation` | Modifier    | Opt-in class for the validation enhancer and `:user-invalid` styling.           |
+| `.was-validated`    | Modifier    | Added to the form by the enhancer after the first submit attempt.               |
+| `.status-bar`       | Component   | Optional status element that shows `data-validation-message` on invalid submit. |
 
 - `.field-error` is the canonical error message. It is wired to `aria-invalid="true"` via the input, so the visual border and the assistive-tech announcement move together.
 - `.field-help` is the canonical helper text. It carries supporting copy before and after validation.
@@ -238,4 +238,4 @@ Invalid visuals converge across the three ways a field can be flagged:
 `:user-invalid`. Each sets the danger border, and a checked or indeterminate
 `.check`, `.radio`, or `.switch` also flips its fill to danger so border and
 fill signal together. Choice cards surface the same invalid state on the card
-border. The exact selector coverage is asserted by `tests/validation.test.js`.
+border. The exact selector coverage is asserted by `tests/validation.test.js`.

package/docs/pages/foundations/philosophy.md

@@ -85,4 +85,4 @@ instead of consuming the shared tokens.
 
 When using a component, child elements follow the semantic pattern of that component. For example, `.avatar` accepts `<img>`, `<picture>`, text content, an empty `.badge` for status dots, and can be a `<button>` or `<a>`.
 
-No child classes like `.avatar-img` are needed.
+No child classes like `.avatar-img` are needed.

package/docs/pages/foundations/theming.md

@@ -20,7 +20,7 @@ Set `--cluster-align`.
 
 ### Change spacing without changing control size
 
-Set `--gap` locally on the layout primitive. The optional `utilities-extra.css` layer ships `.gap-sm` / `.gap-md` / `.gap-lg` for row/column containers.
+Set `--gap` locally on the layout primitive. The extra utilities (`src/css/utilities/extra.css`) ship `.gap-sm` / `.gap-md` / `.gap-lg` for row/column containers.
 
 → Layout
 
@@ -56,7 +56,7 @@ Set `--form-actions-justify` (and `--form-actions-align`).
 
 ### Customize a switch's size
 
-Change `--switch-width`, `--switch-block-size`, and `--switch-knob-margin`; knob size and travel are derived from them. Prefer `.sm` / `.lg` first.
+Change `--switch-width`, `--switch-block-size`, and `--switch-knob-margin`; knob size and travel are derived from them. To rescale the whole row of inline choices at once, set `--choice-control-size` instead — the checkbox, the radio, and the switch track all follow it. `.sm` / `.lg` are field density and leave inline choices alone.
 
 → Forms · Switch
 
@@ -64,6 +64,12 @@ Change `--switch-width`, `--switch-block-size`, and `--switch-knob-margin`; knob
 
 Set `--disabled-opacity`. All disabled-prone components — buttons, tabs, menu items, badges, avatars, choice cards, native inputs, and range sliders — read it for their dimmed state.
 
+### Keep bare native controls on-theme / accent-color
+
+Native controls that no component class restyles — a bare checkbox, radio, range, or `<progress>` — follow the theme through `accent-color: var(--primary)`, declared on `:root` and every `[data-theme]` island so each island recomputes it from its own palette. Component classes (`.check`, `.radio`, `.range`) paint their own rendering and do not read it.
+
+→ Forms · Overview · Foundations · Tokens (theme contract)
+
 ### Loading / busy overlay on a container
 
 Use `aria-busy="true"` with a direct last-child `.spinner`; tint the overlay with `--busy-overlay-bg`.
@@ -97,3 +103,12 @@ surfaces — must use another palette. More specific component states or explici
 surface variants (`.card.subtle`) still take precedence.
 
 → Components · Card · Foundations · Tokens (theme contract)
+
+### Use or adapt a preset palette
+
+`src/css/themes/` holds example palettes (`ocean`, `spruce`, `neon`, `brutalist`, …) as
+reference material to copy into your own `[data-theme]` island — they are demo
+assets, not package entrypoints. Each sets the intent/surface/text tokens and
+lets the core derive everything else. In browsers with `color-mix()` support,
+`--focus-ring` follows each island's `--focus` automatically; re-declare it only
+for a deliberate visual override or a matching legacy fallback.