@adia-ai/web-components 0.8.13 → 0.8.15

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog — @adia-ai/web-components
 
+## [0.8.15] — 2026-07-26
+
+### Changed
+- **Hover fills darken toward the ladder in both schemes** (`styles/colors/material-static.css`) — all 8 families' `--md-sys-color-<family>-hover` move from `light-dark(<family>-650, <family>-350)` to `light-dark(<family>-600, <family>-550)` (base fill is `<family>-500` in both modes; ladder stops are 50 points, higher = darker). Light-mode hover lands two stops darker than base (`500 → 600`, softened from the old three-stop `-650`); dark-mode hover lands one stop darker (`500 → 550`), where it previously *lightened* three stops to `-350`. Measured with the gate's own culori converter: light-mode white hover text is 6/8 families ≥ AA 4.5:1 (from 8/8 at the old stronger jump); dark-mode — which failed AA for **all 8 families** at `-350` (ratios ≈ 2.0–2.5) — now passes for 5/8. Flows through the `--a-*-hover` alias layer and all 12 `[theme]` recolors with no component changes. Filled buttons bypassed this role via `--a-<family>-strong` — corrected in the Fixed entry below, same release.
+
+### Fixed
+- **Filled buttons hover on the hover role, not the active role** (`components/button/button.css`) — `button-ui[variant="primary"]` and the `danger`/`success`/`info` filled colors set their hover fill from `--a-<family>-strong`, which aliases `--md-sys-color-<family>-active` (`light-dark(750, 250)`). In dark mode that meant hover *lightened five stops* to the pale `-250` tint — the washed-out hover the role change above couldn't reach, because these rules bypassed the hover role entirely. They now ride `--a-<family>-hover` (`light-dark(600, 550)`). Verified live in dark mode: primary idle computes exactly `primary-500`, hover exactly `primary-550`. `warning` keeps its documented `-bg` tint exception (dark-label contrast, dogfood-audited); ghost/outline **text** hovers keep `-strong` deliberately — lighter text on a dark canvas is more contrast, not less; `-strong` remains the pressed/active fill.
+
+### Maintenance
+- **`dist/` bundles rebuilt** from the token change above.
+
+## [0.8.14] — 2026-07-25
+
+### Changed
+- **Every theme's neutral chrome now carries its own hue** (`styles/themes.css`; PR #414) — canvas, borders and on-surface text stayed a fixed cool grey across all 12 `[theme]` identities while only the accent families rotated. The same hue-rotation mechanism (own L/C curve untouched, hue shifted by a constant delta, per-theme chroma multiplier) now extends to the neutral family, targeting each theme's own primary hue. Neutral's chroma stays low (≈0.002–0.044, the top end being signal's 1.3× and arcade's 1.4×), so the tint reads as a whisper rather than a recolor — chrome belongs to the theme's identity instead of sitting as a fixed grey under a rotating accent. `npm run verify:contrast` still passes 42/42 WCAG AA 4.5:1 pairs in both schemes for every theme (L values are byte-identical to the shipped ramp; only hue and chroma moved).
+- **All floating overlays share one elevated surface** (`components/{popover,menu,context-menu}/`) — `popover-ui` used `--md-sys-color-neutral-surface-dimmer` (neutral-925, *darker* than the neutral-875 page it floats over, so a popover panel read near-black), while `menu-ui` and `context-menu-ui` sat at page level (`--a-bg-subtle` = `neutral-surface`). All three now use `--md-sys-color-neutral-surface-bright`, matching `select-ui`'s own dropdown exactly: a select menu and a popover panel opened from the same topbar sit on one plane. Verified live in dark mode — both surfaces measure the identical computed color. `drawer-ui` deliberately keeps `surface-dimmer` (edge-anchored, not floating) and `tooltip-ui` keeps its inverted surface.
+
+### Fixed
+- **`nav-item-ui`'s selected state is distinguishable from hover again** (`components/nav-item/nav-item.css`) — v0.8.13 (PR #417) unified both states onto `--a-bg-muted` (container-low). Wherever no *other* selected affordance shows, that made them pixel-identical: a `[variant="section"]` item with no icon — the docs-site subnav shape — suppresses the accent bar and resolves `--a-ui-text-selected` and `--a-ui-text-hover` to the same `--a-fg-strong`, leaving the background as the only signal. Selected now reads `--a-bg-selected` (`neutral-container-active`) while hover keeps container-low, so v0.8.13's actual win — dropping the `--a-canvas-0-scrim` opacity synth from hover — is preserved. Verified live in dark mode: plain / hovered / selected measure transparent, α0.1, α0.4.
+- **55 drifted or missing `.examples.md` regenerated, plus a drift gate** (gh#395; PR #416) — the size-model migration (PR #396) edited ~100 components' `.examples.html` without re-running `generate-examples-md.mjs`, so 42 committed `.md` files still described pre-migration markup and 13 components had no `.md` at all. Nothing caught either gap: unlike `.a2ui.json`, this generator had no drift check. `generate-examples-md.mjs --verify` (mirroring `components.mjs --verify`) and the new `check:examples-md-fresh` script close it.
+- **Stale token-table defaults in the docs** — `menu.examples.html` documented a `--menu-bg` token that does not exist (the shipped token is `--menu-popover-bg`), `popover.examples.html` documented a default the CSS had not used for two releases, and `context-menu.yaml`'s `--context-menu-bg` default was equally stale. All three now state the shipped value.
+
+### Maintenance
+- **`dist/` bundles rebuilt** — CSS + JS + `theme-provider.min.js`, which inlines the changed component CSS.
+
 ## [0.8.13] — 2026-07-25
 
 ### Added

package/components/adia-mark/adia-mark.examples.md

@@ -6,19 +6,10 @@
 <adia-mark-ui></adia-mark-ui>
 ```
 
-## Sizes
+## size
 
 ```html
-<adia-mark-ui size="sm"></adia-mark-ui>
-<adia-mark-ui size="md"></adia-mark-ui>
-<adia-mark-ui size="lg"></adia-mark-ui>
-```
-
-## Topbar brand slot
-
-```html
-<row-ui gap="2" align="center">
+<div scale="ui-sm">
   <adia-mark-ui size="sm"></adia-mark-ui>
-  <text-ui variant="heading">Adia</text-ui>
-</row-ui>
+</div>
 ```

package/components/adia-wordmark/adia-wordmark.examples.md

@@ -6,18 +6,10 @@
 <adia-wordmark-ui></adia-wordmark-ui>
 ```
 
-## Sizes
+## size
 
 ```html
-<adia-wordmark-ui size="sm"></adia-wordmark-ui>
-<adia-wordmark-ui size="md"></adia-wordmark-ui>
-<adia-wordmark-ui size="lg"></adia-wordmark-ui>
-```
-
-## Login header
-
-```html
-<row-ui gap="2" align="center">
-  <adia-wordmark-ui size="lg"></adia-wordmark-ui>
-</row-ui>
+<div scale="ui-sm">
+  <adia-wordmark-ui size="sm"></adia-wordmark-ui>
+</div>
 ```

package/components/agent-artifact/agent-artifact.examples.md

@@ -17,12 +17,3 @@
   <div style="font-size: var(--a-ui-sm); color: var(--a-fg-muted); line-height: 1.5;">Validation score 62/100 — the output is missing a price badge and has an unlabeled button. Retrying would help.</div>
 </agent-artifact-ui>
 ```
-
-## Usage
-
-```html
-<agent-artifact-ui title="product-card" kind="A2UI" icon="layout">
-  <button-ui slot="primary" text="Open in canvas" icon="arrows-out-simple"></button-ui>
-  <button-ui slot="secondary" text="Copy" icon="copy"></button-ui>
-</agent-artifact-ui>
-```

package/components/agent-feedback-bar/agent-feedback-bar.examples.md

@@ -11,14 +11,3 @@
 ```html
 <agent-feedback-bar-ui id="demo-save" save-label="Save pattern"></agent-feedback-bar-ui>
 ```
-
-## Usage
-
-```html
-<agent-feedback-bar-ui save-label="Save pattern"></agent-feedback-bar-ui>
-el.addEventListener('feedback-rate', (e) => persist(e.detail.rating));
-el.addEventListener('feedback-save', async () => {
-  const name = await savePattern(...);
-  el.setStatus(`Saved as "${name}"`, { lock: 'save' });
-});
-```

package/components/alert/alert.examples.md

@@ -6,7 +6,7 @@
 <alert-ui text="Default alert message"></alert-ui>
 ```
 
-## closable
+## closable · dismissible
 
 ```html
 <alert-ui text="This can be dismissed" closable></alert-ui>

package/components/badge/badge.examples.md

@@ -6,14 +6,45 @@
 <badge-ui text="Default"></badge-ui>
 ```
 
-## size
+## Typography registers
 
 ```html
-<badge-ui text="Small" size="sm"></badge-ui>
+<row-ui gap="6" align="start" wrap>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">verse</text-ui>
+    <div verse>
+      <row-ui gap="2">
+        <badge-ui text="New" variant="success"></badge-ui>
+        <badge-ui text="Beta" variant="info"></badge-ui>
+        <badge-ui text="3" variant="danger"></badge-ui>
+      </row-ui>
+    </div>
+  </col-ui>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">regular</text-ui>
+    <div>
+      <row-ui gap="2">
+        <badge-ui text="New" variant="success"></badge-ui>
+        <badge-ui text="Beta" variant="info"></badge-ui>
+        <badge-ui text="3" variant="danger"></badge-ui>
+      </row-ui>
+    </div>
+  </col-ui>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">prose</text-ui>
+    <div prose>
+      <row-ui gap="2">
+        <badge-ui text="New" variant="success"></badge-ui>
+        <badge-ui text="Beta" variant="info"></badge-ui>
+        <badge-ui text="3" variant="danger"></badge-ui>
+      </row-ui>
+    </div>
+  </col-ui>
+</row-ui>
 ```
 
-## text
+## tone
 
 ```html
-<badge-ui text="New"></badge-ui>
+<badge-ui text="Info" variant="info" tone="solid"></badge-ui>
 ```

package/components/block/block.examples.md

@@ -3,7 +3,7 @@
 ## padding
 
 ```html
-<block-ui padding="none" style="border:1px dashed var(--a-border);">
+<block-ui padding="none" style="border:1px dashed var(--md-sys-color-neutral-outline);">
   <p>padding: none</p>
 </block-ui>
 ```
@@ -11,8 +11,8 @@
 ## margin
 
 ```html
-<div style="background:var(--a-accent-10-tint); display:inline-block;">
-  <block-ui margin="none" padding="sm" style="border:1px dashed var(--a-border); background:var(--a-canvas-bg);">
+<div style="background:var(--a-primary-10-tint); display:inline-block;">
+  <block-ui margin="none" padding="sm" style="border:1px dashed var(--md-sys-color-neutral-outline); background:var(--a-canvas-bg);">
     <p>margin: none</p>
   </block-ui>
 </div>
@@ -21,8 +21,8 @@
 ## Combinations
 
 ```html
-<div style="background:var(--a-accent-10-tint); display:inline-block;">
-  <block-ui padding="lg" margin="md" style="border:1px dashed var(--a-border); background:var(--a-canvas-bg);">
+<div style="background:var(--a-primary-10-tint); display:inline-block;">
+  <block-ui padding="lg" margin="md" style="border:1px dashed var(--md-sys-color-neutral-outline); background:var(--a-canvas-bg);">
     <p>padding: lg + margin: md</p>
   </block-ui>
 </div>

package/components/blockquote/blockquote.examples.md

@@ -0,0 +1,22 @@
+# blockquote — Examples
+
+## default
+
+```html
+<blockquote-ui>Stay hungry. Stay foolish.</blockquote-ui>
+```
+
+## cite (attribute)
+
+```html
+<blockquote-ui cite="Steve Jobs, Stanford Commencement, 2005">Stay hungry. Stay foolish.</blockquote-ui>
+```
+
+## cite (slot — rich attribution)
+
+```html
+<blockquote-ui>
+  The best way to predict the future is to invent it.
+  <link-ui slot="cite" href="https://en.wikipedia.org/wiki/Alan_Kay">Alan Kay (1971)</link-ui>
+</blockquote-ui>
+```

package/components/button/button.css

@@ -19,10 +19,16 @@ button-ui:active { transform: scale(0.97); }
    untouched (primary/danger/etc. keep their light label). */
 button-ui:not([disabled]):hover { --button-bg: var(--button-bg-hover); }
 
-button-ui[variant="primary"]:not([disabled]):hover { --button-bg: var(--a-primary-strong); }
-button-ui[color="danger"]:not([disabled]):hover     { --button-bg: var(--a-danger-strong); }
-button-ui[color="success"]:not([disabled]):hover    { --button-bg: var(--a-success-strong); }
-button-ui[color="info"]:not([disabled]):hover       { --button-bg: var(--a-info-strong); }
+/* Filled hovers ride the HOVER role (light-dark 600/550 — one rule: darker
+   than the 500 base in both schemes). They previously rode `-strong`, which
+   aliases the ACTIVE role (750/250): in dark mode that hover LIGHTENED five
+   stops to the pale -250 tint — the washed-out hover the 600/550 role change
+   couldn't reach because these rules bypassed it. `-strong` remains the
+   pressed/active fill. */
+button-ui[variant="primary"]:not([disabled]):hover { --button-bg: var(--a-primary-hover); }
+button-ui[color="danger"]:not([disabled]):hover     { --button-bg: var(--a-danger-hover); }
+button-ui[color="success"]:not([disabled]):hover    { --button-bg: var(--a-success-hover); }
+button-ui[color="info"]:not([disabled]):hover       { --button-bg: var(--a-info-hover); }
 /* warning fill → -bg (NOT -strong like the rest): warning's -strong mid-tone
    reads muddy under the dark --a-warning-fg, so the hover surface uses the
    -20 tint (--a-warning-bg) for clean contrast. (dogfood-audit: warning-strong-vs-bg) */

package/components/button/button.examples.md

@@ -6,14 +6,14 @@
 <button-ui text="Default"></button-ui>
 ```
 
-## size
+## color
 
 ```html
-<button-ui text="Small" size="sm"></button-ui>
+<button-ui text="Info" color="info"></button-ui>
 ```
 
-## icon-only
+## size
 
 ```html
-<button-ui icon="plus" size="sm"></button-ui>
+<button-ui text="Small" size="sm"></button-ui>
 ```

package/components/card/card.examples.md

@@ -11,7 +11,7 @@
 ## size
 
 ```html
-<card-ui size="sm">
+<card-ui>
   <section>Small card</section>
 </card-ui>
 ```

package/components/check/check.examples.md

@@ -6,14 +6,33 @@
 <check-ui label="Unchecked"></check-ui>
 ```
 
-## indeterminate
+## Typography registers
 
 ```html
-<check-ui label="Select All" indeterminate></check-ui>
+<row-ui gap="6" align="start" wrap>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">verse</text-ui>
+    <div verse>
+      <check-ui label="Notify me" checked></check-ui>
+    </div>
+  </col-ui>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">regular</text-ui>
+    <div>
+      <check-ui label="Notify me" checked></check-ui>
+    </div>
+  </col-ui>
+  <col-ui gap="2">
+    <text-ui variant="caption" color="muted">prose</text-ui>
+    <div prose>
+      <check-ui label="Notify me" checked></check-ui>
+    </div>
+  </col-ui>
+</row-ui>
 ```
 
-## disabled
+## indeterminate
 
 ```html
-<check-ui label="Disabled Unchecked" disabled></check-ui>
+<check-ui label="Select All" indeterminate></check-ui>
 ```

package/components/col/col.examples.md

@@ -9,3 +9,32 @@
   <button-ui text="Sign in" variant="solid" stretch></button-ui>
 </col-ui>
 ```
+
+## Responsive (@bp)
+
+```html
+<!-- Mobile: center-aligned single column; md+: start-aligned with larger gap -->
+<col-ui gap="sm lg@md" align="center start@md">
+  <card-ui>...</card-ui>
+  <card-ui>...</card-ui>
+</col-ui>
+```
+
+## Rendered demos
+
+```html
+<col-ui gap="3">
+  <field-ui label="Full name">
+    <input-ui placeholder="Maya Chen"></input-ui>
+  </field-ui>
+  <field-ui label="Email">
+    <input-ui type="email" placeholder="maya@example.com"></input-ui>
+  </field-ui>
+  <field-ui label="Role">
+    <select-ui value="member">
+      <option value="admin">Admin</option>
+      <option value="member">Member</option>
+    </select-ui>
+  </field-ui>
+</col-ui>
+```

package/components/combobox/combobox.examples.md

@@ -11,6 +11,8 @@
     <option value="fr">France</option>
     <option value="es">Spain</option>
     <option value="it">Italy</option>
+    <option value="jp">Japan</option>
+    <option value="kr">South Korea</option>
   </combobox-ui>
 </field-ui>
 ```
@@ -23,16 +25,22 @@
     <optgroup label="Americas">
       <option value="nyc">New York</option>
       <option value="sf">San Francisco</option>
+      <option value="toronto">Toronto</option>
     </optgroup>
     <optgroup label="Europe">
       <option value="london">London</option>
       <option value="paris">Paris</option>
+      <option value="berlin">Berlin</option>
+    </optgroup>
+    <optgroup label="Asia">
+      <option value="tokyo">Tokyo</option>
+      <option value="singapore">Singapore</option>
     </optgroup>
   </combobox-ui>
 </field-ui>
 ```
 
-## creatable tag picker
+## creatable
 
 ```html
 <field-ui label="Tag">
@@ -43,17 +51,3 @@
   </combobox-ui>
 </field-ui>
 ```
-
-Typing "regression" + Enter fires the `create` event with `detail.value === "regression"`.
-
-## clearable
-
-```html
-<field-ui label="Role">
-  <combobox-ui clearable value="user" placeholder="Pick a role…">
-    <option value="user">User</option>
-    <option value="admin">Admin</option>
-    <option value="guest">Guest</option>
-  </combobox-ui>
-</field-ui>
-```

package/components/command/command.examples.md

@@ -3,7 +3,7 @@
 ## inline (not in dialog)
 
 ```html
-<command-ui placeholder="Search commands..." style="width:32rem; max-height:24rem; border:1px solid var(--a-border); border-radius:var(--a-radius-lg);">
+<command-ui placeholder="Search commands..." style="width:32rem; max-height:24rem; border:1px solid var(--md-sys-color-neutral-outline); border-radius:var(--a-radius-lg);">
   <optgroup label="Pages">
     <option value="home" data-icon="house">Home</option>
     <option value="dashboard" data-icon="chart-bar">Dashboard</option>
@@ -19,7 +19,7 @@
 ## grouped options with icons
 
 ```html
-<command-ui placeholder="Type a command..." style="width:32rem; max-height:24rem; border:1px solid var(--a-border); border-radius:var(--a-radius-lg);">
+<command-ui placeholder="Type a command..." style="width:32rem; max-height:24rem; border:1px solid var(--md-sys-color-neutral-outline); border-radius:var(--a-radius-lg);">
   <optgroup label="Navigation">
     <option value="home" data-icon="house">Go to Home</option>
     <option value="projects" data-icon="folder">Go to Projects</option>
@@ -41,7 +41,7 @@
 ## with shortcuts
 
 ```html
-<command-ui placeholder="Search..." style="width:32rem; max-height:24rem; border:1px solid var(--a-border); border-radius:var(--a-radius-lg);">
+<command-ui placeholder="Search..." style="width:32rem; max-height:24rem; border:1px solid var(--md-sys-color-neutral-outline); border-radius:var(--a-radius-lg);">
   <optgroup label="Actions">
     <option value="new-file" data-icon="file-plus" data-shortcut="&#8984;N">New File</option>
     <option value="open" data-icon="folder-open" data-shortcut="&#8984;O">Open File</option>

package/components/context-menu/context-menu.a2ui.json

@@ -138,7 +138,7 @@
     "tokens": {
       "--context-menu-bg": {
         "description": "Menu surface background color.",
-        "default": "var(--a-bg-subtle)"
+        "default": "var(--md-sys-color-neutral-surface-bright)"
       },
       "--context-menu-border": {
         "description": "Menu surface border color.",

package/components/context-menu/context-menu.css

@@ -28,7 +28,9 @@
   padding: var(--a-space-1);
   border: 1px solid var(--md-sys-color-neutral-outline-variant);
   border-radius: var(--a-radius-lg);
-  background: var(--a-bg-subtle);
+  /* surface-bright — same elevated-overlay plane as menu-ui (whose surface
+     this must match), select-ui's dropdown, and popover-ui. */
+  background: var(--md-sys-color-neutral-surface-bright);
   box-shadow: var(--a-shadow-lg);
   min-width: 10rem;
   font-family: var(--context-menu-font-family, var(--a-font-family-ui));

package/components/context-menu/context-menu.examples.md

@@ -0,0 +1,50 @@
+# context-menu — Examples
+
+## Wrap mode — target is the first non-item child
+
+```html
+<context-menu-ui>
+  <div tabindex="0" style="padding: var(--a-space-3); border: 1px dashed var(--md-sys-color-neutral-outline); border-radius: var(--a-radius-md); background: var(--md-sys-color-neutral-background); cursor: context-menu; outline: none;">
+    <icon-ui name="file-text"></icon-ui>
+    <strong>Q4-budget-draft.xlsx</strong>
+    <text-ui color="subtle" size="sm">— right-click me</text-ui>
+  </div>
+  <menu-item-ui value="open" text="Open"></menu-item-ui>
+  <menu-item-ui value="rename" text="Rename…"></menu-item-ui>
+  <menu-item-ui value="download" text="Download"></menu-item-ui>
+  <menu-divider-ui></menu-divider-ui>
+  <menu-item-ui value="delete" text="Delete" variant="danger"></menu-item-ui>
+</context-menu-ui>
+```
+
+## [for] selector mode — point at existing targets
+
+```html
+<div style="display: grid; gap: var(--a-space-2);">
+  <div data-row tabindex="0" style="padding: var(--a-space-3); border: 1px solid var(--md-sys-color-neutral-outline); border-radius: var(--a-radius-sm); background: var(--md-sys-color-neutral-background);">Row A — right-click</div>
+  <div data-row tabindex="0" style="padding: var(--a-space-3); border: 1px solid var(--md-sys-color-neutral-outline); border-radius: var(--a-radius-sm); background: var(--md-sys-color-neutral-background);">Row B — right-click</div>
+  <div data-row tabindex="0" style="padding: var(--a-space-3); border: 1px solid var(--md-sys-color-neutral-outline); border-radius: var(--a-radius-sm); background: var(--md-sys-color-neutral-background);">Row C — right-click</div>
+</div>
+<context-menu-ui for='[data-chunk="context-menu-for"] [data-row]'>
+  <menu-item-ui value="edit" text="Edit"></menu-item-ui>
+  <menu-item-ui value="duplicate" text="Duplicate"></menu-item-ui>
+  <menu-divider-ui></menu-divider-ui>
+  <menu-item-ui value="archive" text="Archive" variant="warning"></menu-item-ui>
+</context-menu-ui>
+```
+
+## open · long-press-ms
+
+```html
+<context-menu-ui open long-press-ms="800">
+  <div tabindex="0" style="padding: var(--a-space-3); border: 1px dashed var(--md-sys-color-neutral-outline); border-radius: var(--a-radius-md); background: var(--md-sys-color-neutral-background); cursor: context-menu; outline: none;">
+    <icon-ui name="dots-three"></icon-ui>
+    <strong>Canvas object</strong>
+    <text-ui color="subtle" size="sm">— long-press 800 ms, or open programmatically</text-ui>
+  </div>
+  <menu-item-ui value="front" text="Bring to front"></menu-item-ui>
+  <menu-item-ui value="back" text="Send to back"></menu-item-ui>
+  <menu-divider-ui></menu-divider-ui>
+  <menu-item-ui value="delete" text="Delete" variant="danger"></menu-item-ui>
+</context-menu-ui>
+```

package/components/context-menu/context-menu.yaml

@@ -85,7 +85,7 @@ traits: []
 tokens:
   --context-menu-bg:
     description: Menu surface background color.
-    default: var(--a-bg-subtle)
+    default: var(--md-sys-color-neutral-surface-bright)
   --context-menu-border:
     description: Menu surface border color.
     default: var(--a-border-subtle)

package/components/date-range-picker/date-range-picker.examples.md

@@ -4,34 +4,22 @@
 
 ```html
 <field-ui label="Report period">
-  <date-range-picker-ui
-    name="report-period"
-    min="2026-01-01"
-    max="2026-12-31">
-  </date-range-picker-ui>
+  <date-range-picker-ui name="report-period" min="2026-01-01" max="2026-12-31"></date-range-picker-ui>
 </field-ui>
 ```
 
-## Comparison mode
+## Pre-selected
 
 ```html
-<date-range-picker-ui
-  name="period"
-  comparison
-  value='{"from":"2026-05-01","to":"2026-05-31"}'
-  compare-value='{"from":"2026-04-01","to":"2026-04-30"}'>
-</date-range-picker-ui>
+<field-ui label="Booking dates">
+  <date-range-picker-ui value='{"from":"2026-03-01","to":"2026-03-15"}'></date-range-picker-ui>
+</field-ui>
 ```
 
-## Custom presets
+## Comparison mode
 
 ```html
-<date-range-picker-ui id="dr" name="period"></date-range-picker-ui>
-<script>
-  document.getElementById('dr').presets = [
-    { label: 'Q1', range: { from: '2026-01-01', to: '2026-03-31' } },
-    { label: 'Q2', range: { from: '2026-04-01', to: '2026-06-30' } },
-    { label: 'YTD', range: { from: '2026-01-01', to: '2026-05-24' } },
-  ];
-</script>
+<field-ui label="Analytics period">
+  <date-range-picker-ui name="period" comparison value='{"from":"2026-05-01","to":"2026-05-31"}' compare-value='{"from":"2026-04-01","to":"2026-04-30"}'></date-range-picker-ui>
+</field-ui>
 ```

package/components/datetime-picker/datetime-picker.examples.md

@@ -4,43 +4,22 @@
 
 ```html
 <field-ui label="Appointment">
-  <datetime-picker-ui
-    name="appointment"
-    min="2026-01-01T00:00"
-    max="2026-12-31T23:59">
-  </datetime-picker-ui>
+  <datetime-picker-ui name="appointment" min="2026-01-01T00:00" max="2026-12-31T23:59"></datetime-picker-ui>
 </field-ui>
 ```
 
-## Second precision
+## Pre-selected
 
 ```html
-<datetime-picker-ui
-  precision="second"
-  step="1"
-  value="2026-05-24T14:30:45">
-</datetime-picker-ui>
-```
-
-## Forced 24-hour cycle
-
-```html
-<datetime-picker-ui hour-cycle="h23"></datetime-picker-ui>
-```
-
-## Explicit commit (Apply / Cancel)
-
-```html
-<datetime-picker-ui name="explicit">
-  <div slot="footer">
-    <button-ui data-action="cancel" variant="ghost" text="Cancel"></button-ui>
-    <button-ui data-action="apply" variant="primary" text="Apply"></button-ui>
-  </div>
-</datetime-picker-ui>
+<field-ui label="Meeting start">
+  <datetime-picker-ui value="2026-05-24T14:30"></datetime-picker-ui>
+</field-ui>
 ```
 
-## Readonly
+## precision
 
 ```html
-<datetime-picker-ui readonly value="2026-05-24T14:30"></datetime-picker-ui>
+<field-ui label="Minute precision">
+  <datetime-picker-ui value="2026-05-24T14:30"></datetime-picker-ui>
+</field-ui>
 ```

package/components/demo-toggle/demo-toggle.examples.md

@@ -5,7 +5,7 @@
 ```html
 <demo-toggle-ui label-on="With trait" label-off="Without trait" initial="off">
   <div slot="off" style="padding:var(--a-space-4);text-align:center;color:var(--a-fg-muted);">Bare surface — no trait attached.</div>
-  <div slot="on" style="padding:var(--a-space-4);text-align:center;color:var(--a-fg);">Same surface, with trait attached.</div>
+  <div slot="on" style="padding:var(--a-space-4);text-align:center;color:var(--md-sys-color-neutral-on-surface);">Same surface, with trait attached.</div>
 </demo-toggle-ui>
 ```