@codenhub/styles 0.5.0 → 0.6.0

package/docs/usage/content-and-layout.md

@@ -14,14 +14,11 @@ Layout helpers use the shared `--layout-gap` token. `.tight` sets it to `0.5rem`
 - `.stack` is a vertical flex stack.
 - `.cluster` is a wrapping horizontal flex row; `.between` adds `space-between` alignment.
 - `.auto-grid` is a responsive auto-fit grid using `--layout-grid-min`.
-- `.tight` and `.loose` set the shared gap to `0.5rem` or `1.5rem` on views, stacks, clusters, and auto-grids.
 - `.section` adds responsive block padding and an inline gutter.
 - `.section-content` centers content at `--container-max`; `.narrow` and `.wide` select the corresponding container tokens.
 - `.divider` is horizontal; `.vertical` makes it self-stretch vertically. It takes intent, but presentation classes do not affect it.
 - `.visually-hidden` hides content visually while keeping it in the accessibility tree, using the standard clip-based recipe. Not named `.sr-only`: on a `/tw` entry the consumer's own Tailwind build already ships a real `.sr-only`, and a same-named utility of this package's own would silently collide with it in the cascade — the same reason `.data-table` is not named `.table`.
 
-The removed `--layout-stack-gap` and `--layout-cluster-gap` tokens have no compatibility aliases.
-
 ## Content
 
 | Class           | Purpose                                                                                  | Intent affects         |
@@ -48,24 +45,24 @@ A table draws three kinds of line, and `.ruled` and `.ruleless` move all of them
 
 ```html
 <table class="data-table">
-  Head and foot boundaries only
+  <!-- Head and foot boundaries only -->
 </table>
 <table class="data-table ruled">
-  Every row separated
+  <!-- Every row separated -->
 </table>
 <table class="data-table ruleless">
-  No lines inside the table at all
+  <!-- No lines inside the table at all -->
 </table>
 ```
 
-The boundaries under a head and above a foot separate the parts of a table from each other, so they are drawn by default where the row rules are not. Rules between body rows used to arrive on their own, because the component's published edge default is `edged` and the edge axis wrote the rules along with the boundary — so whether you got them depended on a registry default rather than on anything in your markup.
+The boundaries under a head and above a foot separate the parts of a table from each other, so they are drawn by default where the row rules are not. Rules between body rows are asked for by `.ruled` or `--ui-rule`, never by the edge axis, so whether you get them depends on your markup and not on a default you cannot see.
 
 `--ui-rule` is the token behind both classes, so a container can set the answer for a whole region without classing each table:
 
 ```html
 <section style="--ui-rule: 100%">
   <table class="data-table">
-    Ruled by the region
+    <!-- Ruled by the region -->
   </table>
 </section>
 ```
@@ -93,10 +90,10 @@ This is the one place intent cascades, because a table's rows are parts of the t
 
 ```html
 <table class="data-table success soft edged">
-  ...
+  <!-- ... -->
 </table>
-<table class="data-table">
-  A ghost table: rules and type, no header plate
+<table class="data-table ghost">
+  <!-- A ghost table: rules and type, no header plate -->
 </table>
 <kbd class="kbd primary solid">Ctrl</kbd>
 <kbd class="kbd primary soft edged">Shift</kbd>
@@ -131,6 +128,10 @@ Use `.table-wrap` around `.data-table` when table width may exceed its container
 </div>
 ```
 
+A table takes the surface corner, like a card beside it. Nothing clips it: the four corner cells take the corners, so a `<caption>` sits above the table untouched in every engine. A cell that spans rows down into a bottom corner leaves that corner square.
+
+`.table-wrap` scrolls, and a scroll container clips whatever paints outside it. Under an aesthetic that draws a halo -- cyber's glow -- the wrapper pads itself by the halo's reach and pulls itself out by the same amount, so the glow fits inside it and the table stays where it would be. The wrapper then reaches that far past its parent, which only shows when the parent is flush with the viewport. Depth shadows, such as a `.raised` table's, are not given room and are still cut. The wrapper can only make room for a halo it is inside, so put the aesthetic class on `.table-wrap` or an ancestor rather than on a wrapped table alone: `<table class="data-table cyber">` inside a plain wrapper glows, and the wrapper cuts the glow. Leave the wrapper off a table that can never outgrow its container; keep it wherever one can, or a wide table widens the whole page.
+
 ## Surfaces
 
 | Class          | Purpose                                                                               |

package/docs/usage/customizing.md

@@ -54,6 +54,7 @@ Components read each with a fallback, so leaving them unset produces the default
 | `--ui-border-max`         | Ceiling on computed edge width.                                                                                                                      | `100px`                                   |
 | `--ui-ink`                | Neutral line color when no intent is set.                                                                                                            | `--color-border`                          |
 | `--ui-control-ink`        | Neutral line color of fields, selects, checkboxes, radios, and switches when no intent is set.                                                       | `--ui-ink`, then `--color-control-border` |
+| `--ui-rule-ink`           | Neutral line color of a table's frame and rules when no intent is set.                                                                               | `--ui-ink`, then `--color-border`         |
 | `--ui-rule`               | Lines inside a table. Unset draws the head and foot boundaries only; `0%` draws none; `100%` rules every row.                                        | unset                                     |
 | `--ui-shadow-x`           | Shadow horizontal offset.                                                                                                                            | `0px`                                     |
 | `--ui-shadow-y`           | Shadow vertical offset.                                                                                                                              | `0px`                                     |
@@ -72,9 +73,9 @@ Components read each with a fallback, so leaving them unset produces the default
 | `--ui-shadow-edge`        | Declared, even empty, when the shadow is the element's edge rather than its depth. Read for presence.                                                | Unset                                     |
 | `--ui-elevation`          | Unitless multiplier over shadow geometry.                                                                                                            | `1`                                       |
 | `--ui-surface-shadow`     | Complete multi-layer shadow accepted by surfaces only.                                                                                               | Unset                                     |
-| `--ui-surface-ground`     | Ground a surface sits on.                                                                                                                            | `--color-background`                      |
-| `--ui-bg-alpha`           | Multiplier over fill for translucent materials.                                                                                                      | `1`                                       |
-| `--ui-backdrop`           | Backdrop filter accepted by surfaces only.                                                                                                           | `none`                                    |
+| `--ui-surface-ground`     | Ground a surface, or a default or `.soft` table, sits on.                                                                                            | `--color-background`                      |
+| `--ui-bg-alpha`           | Multiplier over every fill, `.solid` included. No shipped aesthetic sets it.                                                                         | `1`                                       |
+| `--ui-backdrop`           | Backdrop filter accepted by surfaces, and by a default or `.soft` table, only.                                                                       | `none`                                    |
 | `--ui-surface-image`      | A painted layer over a surface's plate: any `background-image` value. Surfaces only.                                                                 | `none`                                    |
 | `--ui-hover-transform`    | Transform while an interactive element is hovered.                                                                                                   | `none`                                    |
 | `--ui-clip`               | Structural component silhouette.                                                                                                                     | `none`                                    |
@@ -148,8 +149,8 @@ The shipped [aesthetic classes](./aesthetics.md) set material tokens for you. On
 | Token                             | Aesthetic                    | Purpose                                                                                         | Default                                                            |
 | --------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
 | `--neo-offset`                    | `.neobrutalism`              | Hard shadow offset and distance the press travels.                                              | `4px`                                                              |
-| `--glass-radius`                  | `.glass`                     | Control corner radius.                                                                          | `0.75rem`                                                          |
-| `--glass-radius-surface`          | `.glass`                     | Surface corner radius.                                                                          | `1rem`                                                             |
+| `--glass-radius`                  | `.glass`, `.glass-liquid`    | Control corner radius. `1rem` under `.glass-liquid`.                                            | `0.75rem`                                                          |
+| `--glass-radius-surface`          | `.glass`, `.glass-liquid`    | Surface corner radius. `1.5rem` under `.glass-liquid`.                                          | `1rem`                                                             |
 | `--pixel-unit`                    | `.pixel`                     | One pixel of the grid. The corner cut and the ring are one.                                     | `4px`                                                              |
 | `--font-pixel`                    | `.pixel`                     | Consumer-supplied pixel font stack.                                                             | Falls back to the monospace stack                                  |
 | `--tile-radius`                   | `.chunky-tile`               | Corner radius, on controls and surfaces alike.                                                  | `0.75rem`                                                          |
@@ -186,7 +187,7 @@ Every aesthetic's knobs reach the same way: each knob is _read_ with its default
 
 Knobs and material tokens reach in opposite directions, and telling them apart matters. A knob resolves once at the aesthetic's own class and inherits down already-resolved, so it reaches the aesthetic **from above**: setting it on the element or any ancestor works, but setting it on a _descendant_ of the aesthetic class changes nothing — the value has already been read. `--ui-radius` and the other material tokens above are read fresh by each component as it draws, so they reach **at or below** the element carrying them, which is how you round one card differently from its neighbours without touching the knob at all.
 
-Shipped aesthetics set the shared material tokens above. Every shipped aesthetic sets `--ui-ink` for its neutral line. `.glass` and `.chunky-tile` also set `--ui-control-ink`, so their controls keep a heavier line than their surfaces; the others clear it and their controls take `--ui-ink`. Intent classes still override the intent slots on each component.
+Shipped aesthetics set the shared material tokens above. Every shipped aesthetic sets `--ui-ink` for its neutral line. Every shipped aesthetic also sets `--ui-control-ink`: `.glass` and `.chunky-tile` to a line of their own, heavier than their surfaces', and the others to `--color-control-border`, since their ink is the primary colour in both themes. `.glass` sets `--ui-rule-ink` too, so a table's lines read on its plate; the others clear it. Intent classes still override the intent slots on each component.
 
 The same knobs tune each aesthetic's [solo class](./aesthetics.md#solo-classes), which reads them on its own element.
 
@@ -213,7 +214,7 @@ Naming: `--palette-<intent>-<presentation>-<slot>`, where `<intent>` is one of t
 - A ground qualifier (`page` or `subtle`) inserted before the slot, present only on `.soft`/`.ghost`'s `bg` and `edge` -- `.solid` is ground-independent at full fill, and `fg` never varies by ground. No qualifier means the `transparent` ground (`.badge`/`.btn`'s ground): `--palette-success-soft-bg`. `page` is `.alert`'s ground (`--color-background`): `--palette-success-soft-page-bg`. `subtle` is `.pre`/`.code`/`.kbd`/`.tooltip-bubble`'s ground (that intent's own `--intent-subtle`): `--palette-success-soft-subtle-bg`.
 - A `-hover` suffix on `bg` and `edge` only -- `fg` never changes on hover: `--palette-success-soft-page-bg-hover`.
 
-Dark values are scoped the same way `@codenhub/styles`' own explicit theme override is: `.dark`, `.theme-dark`, and `[data-theme="dark"]`, on the element or an ancestor. There is no `prefers-color-scheme` fallback in this file -- a consumer reaching for a standalone palette is already handling its own theme switching, so the OS-preference case is left to `@codenhub/styles`' own `light-dark()`-based tokens when that package is actually in use.
+Light values sit on `:root` and dark values are scoped the same way `@codenhub/styles`' own explicit theme override is: `.dark`, `.theme-dark`, and `[data-theme="dark"]`, on the element or an ancestor. The light values also answer `.light`, `.theme-light`, and `[data-theme="light"]`, so the nearest explicit theme wins at any depth -- a light subtree nested inside a dark one reads the light values. There is no `prefers-color-scheme` fallback in this file -- a consumer reaching for a standalone palette is already handling its own theme switching, so the OS-preference case is left to `@codenhub/styles`' own `light-dark()`-based tokens when that package is actually in use.
 
 Three more tokens sit alongside the intent cells for the same reason, without an intent, presentation, ground, or hover axis of their own: `--palette-border`, `--palette-surface`, and `--palette-text`, flat values for `--color-border`, `--color-surface`, and `--color-text` -- the resting colors anything that is not intent-colored needs (a container's border, a dialog's background, its text), which an optional-peer consumer needs just as much as the intent cells.
 
@@ -223,6 +224,4 @@ Component classes may define scoped implementation variables such as `--surface-
 
 Consumers should customize broad behavior through color, foundation, motion, elevation, radius, layout, and focus tokens first. The only supported component-scoped input is `--progress-value` on the `.progress` element, because consumers must provide a value such as `64%`.
 
-`--layout-gap` replaces the removed `--layout-stack-gap` and `--layout-cluster-gap` tokens. No compatibility aliases are provided.
-
 Next: [Aesthetics](./aesthetics.md) covers each shipped aesthetic's complete look and its documented exceptions.

package/docs/usage/feedback.md

@@ -33,7 +33,7 @@ Activity indicator modifier classes compose with `.loader`:
 | `.bars-wave`           | Three vertical bars scaling in a wave.  |
 | `.pulse-ring`          | Two concentric rings pulsing outward.   |
 
-These variants retain their embedded SVG animations normally. Under `prefers-reduced-motion: reduce`, loader CSS substitutes a corresponding static mask. This fallback is part of focused loader, button, and components imports; it does not depend on the global reset. See [Accessibility](../accessibility.md).
+These variants retain their embedded SVG animations normally. Under `prefers-reduced-motion: reduce`, loader CSS substitutes a corresponding static mask. This fallback ships wherever the loader does -- the complete, native, and `/components` entrypoints, `/tw/components`, and `/tw/loader` -- and does not depend on the global reset. `/tw/button` does not include the loader; pair it with `/tw/loader`. See [Accessibility](../accessibility.md).
 
 Loader size modifiers:
 
@@ -43,7 +43,7 @@ Loader size modifiers:
 | `.sm`    | Small (`1.25rem`).   |
 | `.lg`    | Large (`2.25rem`).   |
 
-Alerts, badges, progress bars, skeletons, and loaders accept `.primary`, `.secondary`, `.success`, `.warning`, `.destructive`, and `.info`. Without an intent, they use the text palette, except `.loader`, which keeps `currentColor` so it matches whatever content surrounds it.
+Alerts, badges, progress bars, skeletons, and loaders accept `.primary`, `.secondary`, `.success`, `.warning`, `.destructive`, and `.info`. Without an intent, alerts and badges use the text palette, while the indicators -- `.loader`, `.skeleton`, and `.progress` -- take `currentColor`, so they match whatever content surrounds them.
 
 Skeletons, loaders, and dividers are indicators: they read intent but ignore fill and edge [presentation](./composing.md#presentation). `.progress` is not one of them — its track reads both, `.soft.edgeless` by default; only the moving value fill stays intent-colored at full strength regardless of presentation. `.solid` is unsupported on the track, and `.ghost.edgeless` renders but is discouraged, since neither leaves the track a visible frame. See [Composing → Component axis reference](./composing.md#component-axis-reference) for the full table.
 
@@ -51,7 +51,9 @@ Skeletons, loaders, and dividers are indicators: they read intent but ignore fil
 <span class="loader success" aria-hidden="true"></span> <span class="skeleton info"></span>
 ```
 
-The package ships no icon of its own: `.alert` is already `flex`, so an icon dropped in as a child is spaced from the message by its `gap-3` with nothing to trigger. `.alert-icon` only sizes and aligns whatever icon element you provide — an inline `<svg>`, an `<img>`, or a class from an icon set such as `@codenhub/icons` — the same contract [`.input-group`](./forms.md#icons) documents.
+The package ships no icon of its own: `.alert` is already `flex`, so an icon dropped in as a child is spaced from the message by its `gap-3`. `.alert-icon` only sizes and aligns whatever icon element you provide — an inline `<svg>`, an `<img>`, or a class from an icon set such as `@codenhub/icons` — the same contract [`.input-group`](./forms.md#icons) documents.
+
+`.alert-icon` sizes the icon to `1.25rem`. A `@codenhub/icons` glyph sizes itself in an unlayered rule that no class of this package can outrank, so `.alert-icon` sets that set's `--ic-size` as well; an icon set with a different prefix keeps its own size unless you set its knob. Resize an alert icon with an ordinary rule of your own, and set `--ic-size` along with `width` and `height` for a `@codenhub/icons` glyph.
 
 Alerts and badges read the shared [presentation](./composing.md#presentation) classes. Without one they use a tinted surface, intent-colored text, and a mixed intent border -- except a neutral `.alert` (no named intent), which rests untinted instead, the same no-named-intent carve-out `.card.soft` and `.panel` use: a plain `--color-foreground` plate rather than 12% of near-black ink over the page. A named intent (`.alert.success`, `.alert.destructive`, and so on) keeps its ordinary tint. `.badge` is unaffected either way -- it has no border to fall back on at rest, so untinting it would make a neutral badge disappear rather than read quieter.
 

package/docs/usage/forms.md

@@ -6,55 +6,69 @@ order: 6
 
 # Forms
 
-| Class or Selector                                                     | Purpose                                                                  |
-| --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| `.field`                                                              | Vertical field wrapper.                                                  |
-| `.label`                                                              | Form label text.                                                         |
-| `.hint`                                                               | Secondary helper text.                                                   |
-| `.hint.destructive`                                                   | Helper text with destructive intent.                                     |
-| `.surface`                                                            | Shared public container composition utility.                             |
-| `.text-control`                                                       | Shared public text-control composition utility.                          |
-| `.ipt`                                                                | Input control styling.                                                   |
-| `.input-group`                                                        | Wrapper that owns the field box so a control can carry an icon or affix. |
-| `.textarea`                                                           | Textarea control styling.                                                |
-| `.select`                                                             | Select control styling.                                                  |
-| `input[type="checkbox"].checkbox`                                     | Custom checkbox control styling.                                         |
-| `input[type="radio"].radio`                                           | Custom radio control styling.                                            |
-| `input[type="checkbox"].switch`                                       | Custom switch control styling.                                           |
-| `[aria-invalid="true"]` on controls                                   | Destructive border and focus color.                                      |
-| `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` on controls | Disabled styling.                                                        |
+| Class or Selector                                                     | Purpose                                                                                                        |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `.field`                                                              | Vertical field wrapper.                                                                                        |
+| `.label`                                                              | Form label text.                                                                                               |
+| `.hint`                                                               | Secondary helper text.                                                                                         |
+| `.hint.destructive`                                                   | Helper text with destructive intent.                                                                           |
+| `.surface`                                                            | Shared public container composition utility.                                                                   |
+| `.text-control`                                                       | Shared public text-control composition utility.                                                                |
+| `.ipt`                                                                | Input control styling.                                                                                         |
+| `.input-group`                                                        | Wrapper that owns the field box so a control can carry an icon or affix.                                       |
+| `.unadorned`                                                          | Removes the browser's own field decorations, on the control or on its `.input-group`.                          |
+| `.textarea`                                                           | Textarea control styling.                                                                                      |
+| `.select`                                                             | Select control styling. With `multiple` or a `size` above 1 it is a list box: no chevron, as tall as its rows. |
+| `input[type="checkbox"].checkbox`                                     | Custom checkbox control styling.                                                                               |
+| `input[type="radio"].radio`                                           | Custom radio control styling.                                                                                  |
+| `input[type="checkbox"].switch`                                       | Custom switch control styling.                                                                                 |
+| `[aria-invalid="true"]` on controls                                   | Destructive border and focus color.                                                                            |
+| `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` on controls | Disabled styling.                                                                                              |
 
 ## Icons
 
-No icon is shipped for text inputs — that's what this section covers. It used to paint one per input type as a `background-image` — a `data:` URI, which cannot read `currentColor` or a custom property, so every glyph shipped a light and a dark copy and a theme selector chose between them. That put icon artwork, and the package's only theme-by-selector branch, inside a CSS-only design system whose glyphs did not fit every aesthetic. Icons for `.input-group` are the consumer's to choose now.
-
-This is separate from the toggle marks below, which stay small, fixed, built-in glyphs. `.alert`'s icon followed the same path since — see [Feedback → Icon](./feedback.md#example) — the package no longer paints one there either.
+The package ships no icon for text inputs. Icons for `.input-group` are the consumer's to choose: artwork painted as a `data:` URI could not read `currentColor` or a custom property, so it could not follow the theme or fit every aesthetic. The toggle marks below are the exception: small, fixed, built-in glyphs. `.alert` likewise takes a consumer-supplied icon; see [Feedback](./feedback.md#example).
 
 `.input-group` is the wrapper for a control that carries one. It owns the field box — border, radius, fill, focus ring, invalid and disabled state — and the control inside it goes flush, so the boundary is drawn once. Any icon element works, placed before the control for a leading icon or after it for a trailing one: an inline `<svg>`, an `<img>`, or a class from an icon set such as `@codenhub/icons`.
 
 ```html
-<label class="field">
-  <span class="label">Email</span>
+<div class="field">
+  <label class="label" for="contact-email">Email</label>
   <div class="input-group">
     <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" aria-hidden="true">
       <rect width="20" height="16" x="2" y="4" rx="2" />
       <path d="m22 7-8.991 5.727a2 2 0 0 1-2.009 0L2 7" />
     </svg>
-    <input class="ipt" type="email" />
+    <input class="ipt" type="email" id="contact-email" />
   </div>
-</label>
-<label class="field">
-  <span class="label">Search</span>
+</div>
+<div class="field">
+  <label class="label" for="site-search">Search</label>
   <div class="input-group">
-    <input class="ipt" type="search" />
+    <input class="ipt" type="search" id="site-search" />
     <i class="ic-search" aria-hidden="true"></i>
   </div>
-</label>
+</div>
 ```
 
 The group reads intent and both [presentation](./composing.md#presentation) axes the same way a lone `.ipt` does — `.input-group.soft.edgeless` is the sunk variant, `.input-group.primary` colors the boundary — and follows whichever [aesthetic](./aesthetics.md) is in scope. `aria-invalid` or `disabled` on the control inside propagates to the group; so does either on the group itself. Focus is shown with `:focus-within`, so unlike a lone field the ring also appears on a mouse click.
 
-Non-icon input types keep the browser's native `date` and `datetime-local` pickers. WebKit's native `search` decorations are still suppressed on `.text-control` to keep them from overlapping the value.
+Text controls keep the browser's own decorations: the date and time picker button, a number field's spin buttons, and a search field's clear button and magnifier. Each one is also behaviour -- the picker button is the only pointer route to the picker, and the clear button empties the field.
+
+`.unadorned` removes all of them, for a field whose adornments you draw yourself. Put it on the control, or on its `.input-group` to reach the control inside. Removing a decoration removes what it did, so wire the behaviour back to your own adornment: `input.showPicker()` for a picker, `stepUp()`/`stepDown()` for spin buttons, and setting `value` to `""` and dispatching an `input` event for a clear button. Keyboard entry keeps working either way. Firefox exposes no way to remove its date picker button, so it stays there.
+
+```html
+<div class="field">
+  <label class="label" for="query">Search</label>
+  <div class="input-group unadorned">
+    <i class="ic-search" aria-hidden="true"></i>
+    <input class="ipt" type="search" id="query" />
+    <button type="button" class="btn icon ghost p-xs" aria-label="Clear search">
+      <i class="ic-x" aria-hidden="true"></i>
+    </button>
+  </div>
+</div>
+```
 
 The slot works the same way for a text affix — a URL host, a currency symbol, a unit — not just an icon:
 
@@ -91,6 +105,8 @@ All three toggles rest at `.soft`. Presentation decides the _unchecked_ plate; c
 
 A checked checkbox and a checked switch cut their mark out of that pinned plate. A checked radio thickens its ring to twice the resting line and takes the intent whole on it, and the dot follows the same pinned plate, so `.radio.soft` and `.radio.solid` render the same filled circle once checked — presentation only changes what the radio looks like before it's picked.
 
+A checkbox whose `indeterminate` property is set -- a group some of whose items are checked -- takes the same pinned plate with a dash for its mark, and keeps the dash while it is also `checked`, as the browser's own checkbox does. The property is set from script (`input.indeterminate = true`); there is no attribute for it.
+
 ## Text controls
 
 Text controls also take intent, which colors the resting border and the focus-visible border, and both [presentation](./composing.md#presentation) axes. `.ghost` fills nothing, `.soft` takes `12%`, and `.solid` takes `20%` — quiet enough that typed text still reads on it, and ordered so the louder name draws the stronger tint. None of them touches the line.
@@ -123,11 +139,11 @@ The boundary is the edge axis's, and it splits the same way. A container's `.edg
 ## Example
 
 ```html
-<label class="field">
-  <span class="label">Email</span>
-  <input class="ipt" type="email" aria-invalid="true" aria-describedby="email-error" />
+<div class="field">
+  <label class="label" for="email">Email</label>
+  <input class="ipt" type="email" id="email" aria-invalid="true" aria-describedby="email-error" />
   <span class="hint destructive" id="email-error">Enter a valid email.</span>
-</label>
+</div>
 <label style="display: flex; gap: 0.5rem; align-items: center">
   <input type="checkbox" class="checkbox success" />
   <span>Accept terms</span>
@@ -137,9 +153,9 @@ The boundary is the edge axis's, and it splits the same way. A container's `.edg
   <span>Standard plan</span>
 </label>
 <label style="display: flex; gap: 0.5rem; align-items: center">
-  <input type="checkbox" class="switch destructive" />
+  <input type="checkbox" class="switch destructive" role="switch" />
   <span>Enable</span>
 </label>
 ```
 
-Use labels, `type`, validation logic, `aria-describedby`, and error message relationships; see [Accessibility](../accessibility.md).
+Keep a hint or error message outside the `<label>` and point `aria-describedby` at it, so it is announced as a description rather than read as part of the field's name. Give a `.switch` `role="switch"`. Use labels, `type`, validation logic, `aria-describedby`, and error message relationships; see [Accessibility](../accessibility.md).

package/docs/usage/theming.md

@@ -72,15 +72,15 @@ Every row is an override point: set it on `:root` to retheme globally, or on any
 
 Intent classes set these seven slots; components read them. Because every supporting component reads the same seven names, an intent works on every component that supports intent, and a custom intent needs no component changes.
 
-| Token               | Purpose                                                                               |
-| ------------------- | ------------------------------------------------------------------------------------- |
-| `--intent-color`    | The intent's base color. What a fill is made of.                                      |
-| `--intent-contrast` | Readable color on top of a filled `--intent-color`.                                   |
-| `--intent-hover`    | The intent's hovered base color.                                                      |
-| `--intent-strong`   | The intent printed on a page. Text, icon, or border wherever the fill is not full.    |
-| `--intent-subtle`   | Low-emphasis tone. Tinted surfaces and tracks. Neutral resolves to `--color-surface`. |
-| `--intent-border`   | Line color. Resolves to `--color-border` when no intent is set.                       |
-| `--intent-fill-max` | How far a fill of this intent is allowed to go. `100%` for every intent but neutral.  |
+| Token               | Purpose                                                                                                                                                                                                                                |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--intent-color`    | The intent's base color. What a fill is made of.                                                                                                                                                                                       |
+| `--intent-contrast` | Readable color on top of a filled `--intent-color`.                                                                                                                                                                                    |
+| `--intent-hover`    | The intent's hovered base color.                                                                                                                                                                                                       |
+| `--intent-strong`   | The intent printed on a page. Text, icon, or border wherever the fill is not full.                                                                                                                                                     |
+| `--intent-subtle`   | Low-emphasis tone. Tinted surfaces and tracks. Neutral resolves to `--color-surface`.                                                                                                                                                  |
+| `--intent-border`   | Line color. With no intent it resolves to the aesthetic's `--ui-ink`, then `--color-border`; text controls and toggles read `--ui-control-ink`, then `--ui-ink`, then `--color-control-border`, and tables read `--ui-rule-ink` first. |
+| `--intent-fill-max` | How far a fill of this intent is allowed to go. `100%` for every intent but neutral.                                                                                                                                                   |
 
 `--intent-color` and `--intent-strong` are two ends of the same family and not interchangeable. The base is a ground, chosen to be filled with; the strong tone is chosen to be read against a page. A `.soft` or `.ghost` component prints the strong one, which is why an unfilled warning reads in amber-800 rather than the amber-600 its solid sibling is filled with.
 
@@ -92,7 +92,7 @@ The strong tone has to stay recognisably its own hue, not just readable. On a da
 
 The foreground is gated by the plate rather than tied to the fill. `--intent-contrast` is the ink for a _full_ fill, so printing it at full strength on a fifth of one puts white on light grey. Contrast ink therefore appears only once the fill is past halfway and reaches full at a full fill; below that a component prints `--intent-strong`, the tone chosen to be read.
 
-That means a capped neutral takes the strong tone whole rather than a fraction of the way toward the page. Tying it to the fill instead cost a neutral `.solid` button four points of contrast and a neutral tooltip nearly ten. A state that lifts the cap on purpose — a checked checkbox is filled with its own intent by definition — reaches a full fill and gets the contrast whole.
+So a capped neutral takes the strong tone whole rather than a fraction of the way toward the page. A state that lifts the cap on purpose — a checked checkbox is filled with its own intent by definition — reaches a full fill and gets the contrast whole.
 
 Set them directly to define an intent this package does not ship. **State every slot**, including `--intent-fill-max`: components reset all seven to the neutral values, so a slot your intent leaves out keeps neutral's — and an intent that omits the cap fills to 20% of its color instead of 100%.
 
@@ -120,35 +120,34 @@ Foundation tokens are not aliases for one color. They define layout, shape, moti
 
 The four `--elevation-*` values below are raw shadows for elements you style yourself. They are a separate thing from `.flat`/`.raised`/`.floating`, which scale a _component's own_ shadow geometry and default to no shadow at all until an aesthetic or one of those classes asks for depth — see [Composing → Elevation](./composing.md#elevation) for that system. The two share `none`/`sm`/`md`/`lg` naming for the same weight of depth, but one is a fixed value and the other multiplies shadow parts, so they will not always paint identically.
 
-| Token                      | Purpose                                                                 |
-| -------------------------- | ----------------------------------------------------------------------- |
-| `--font-default`           | Default app font family.                                                |
-| `--container-narrow`       | Narrow content width.                                                   |
-| `--container-max`          | Default content width.                                                  |
-| `--container-wide`         | Wide content width.                                                     |
-| `--layout-gutter`          | Responsive inline page padding.                                         |
-| `--layout-section-block`   | Responsive section vertical padding.                                    |
-| `--layout-gap`             | Shared gap for `.view`, `.stack`, `.cluster`, and `.auto-grid`.         |
-| `--layout-grid-min`        | Minimum column width for `.auto-grid`.                                  |
-| `--radius-small`           | Small radius for compact utility surfaces such as code elements.        |
-| `--radius-control`         | Radius for buttons, inputs, tooltips, and compact UI.                   |
-| `--radius-surface`         | Radius for cards, panels, and alerts.                                   |
-| `--control-height`         | Default minimum height for controls.                                    |
-| `--border-width`           | Default border width.                                                   |
-| `--elevation-color`        | Shadow color the four elevations compose from. Heavier in dark themes.  |
-| `--elevation-none`         | No shadow. Use on an element that should read as flat against its page. |
-| `--elevation-sm`           | A light shadow for your own surface-level elements, such as cards.      |
-| `--elevation-md`           | A shadow for your own raised elements, such as dropdowns and popovers.  |
-| `--elevation-lg`           | A shadow for your own full overlays, such as modal dialogs.             |
-| `--focus-ring`             | Focus-visible ring color.                                               |
-| `--focus-ring-offset`      | Focus-visible outline offset. Negative, so the ring lands on the edge.  |
-| `--focus-ring-width`       | Focus-visible outline/ring width.                                       |
-| `--motion-duration-fast`   | Fast transition for buttons and input interactions (`120ms`).           |
-| `--motion-duration-normal` | Normal transition for layout and modals (`200ms`).                      |
-| `--motion-duration-slow`   | Slow animation for skeleton loaders and progress bars (`400ms`).        |
-| `--motion-ease`            | Default easing curve.                                                   |
-| `--z-popover`              | Popover/tooltip z-index.                                                |
-| `--breakpoint-xs`          | Extra-small Tailwind responsive breakpoint.                             |
-| `--breakpoint-2xl`         | Extended large Tailwind responsive breakpoint.                          |
+| Token                      | Purpose                                                                                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--font-default`           | Default app font family.                                                                                                                    |
+| `--container-narrow`       | Narrow content width.                                                                                                                       |
+| `--container-max`          | Default content width.                                                                                                                      |
+| `--container-wide`         | Wide content width.                                                                                                                         |
+| `--layout-gutter`          | Responsive inline page padding.                                                                                                             |
+| `--layout-section-block`   | Responsive section vertical padding.                                                                                                        |
+| `--layout-gap`             | Shared gap for `.view`, `.stack`, `.cluster`, and `.auto-grid`.                                                                             |
+| `--layout-grid-min`        | Minimum column width for `.auto-grid`.                                                                                                      |
+| `--radius-small`           | Small radius for compact utility surfaces such as code elements.                                                                            |
+| `--radius-control`         | Radius for buttons, inputs, tooltips, and compact UI.                                                                                       |
+| `--radius-surface`         | Radius for cards, panels, and alerts.                                                                                                       |
+| `--control-height`         | Default minimum height for controls.                                                                                                        |
+| `--border-width`           | Default border width.                                                                                                                       |
+| `--elevation-color`        | Shadow color the four elevations compose from. Heavier in dark themes.                                                                      |
+| `--elevation-none`         | No shadow. Use on an element that should read as flat against its page.                                                                     |
+| `--elevation-sm`           | A light shadow for your own surface-level elements, such as cards.                                                                          |
+| `--elevation-md`           | A shadow for your own raised elements, such as dropdowns and popovers.                                                                      |
+| `--elevation-lg`           | A shadow for your own full overlays, such as modal dialogs.                                                                                 |
+| `--focus-ring`             | Focus-visible ring color.                                                                                                                   |
+| `--focus-ring-offset`      | Focus-visible outline offset. Unset: the negative of the focused element's line width, so the ring lands on the edge under every aesthetic. |
+| `--focus-ring-width`       | Focus-visible outline/ring width.                                                                                                           |
+| `--motion-duration-fast`   | Fast transition for a table row's hover (`120ms`).                                                                                          |
+| `--motion-duration-normal` | Every component's colour, border, shadow, and press transitions, toggle marks, and the tooltip bubble (`200ms`).                            |
+| `--motion-duration-slow`   | Progress value changes, and the base of the skeleton and progress shimmer cycle (`400ms`).                                                  |
+| `--motion-ease`            | Default easing curve.                                                                                                                       |
+| `--z-popover`              | Popover/tooltip z-index.                                                                                                                    |
+| `--breakpoint-xs`          | Extra-small Tailwind responsive breakpoint.                                                                                                 |
 
 Next: [Customizing](./customizing.md) covers presentation and material tokens — how much of an intent shows, and what a component is made of.

package/docs/usage/tooltips.md

@@ -6,24 +6,25 @@ order: 8
 
 # Tooltips
 
-| Class or Attribute                     | Purpose                                                                  |
-| -------------------------------------- | ------------------------------------------------------------------------ |
-| `.tooltip`                             | Wrapper around a trigger and a bubble. Paints nothing itself.            |
-| `.tooltip-bubble`                      | The message. A real element, styled like any other surface.              |
-| `.tooltip-icon`                        | Circular icon-style trigger, for a message with nothing else to hang on. |
-| `[data-tooltip-position="top"]`        | Positions the bubble above the trigger, on `.tooltip`.                   |
-| `[data-tooltip-position="bottom"]`     | Positions the bubble below the trigger, on `.tooltip`.                   |
-| `[data-tooltip-position="left"]`       | Positions the bubble left of the trigger, on `.tooltip`.                 |
-| `[data-tooltip-position="right"]`      | Positions the bubble right of the trigger, on `.tooltip`.                |
-| No `data-tooltip-position`             | Defaults to top placement.                                               |
-| `[data-state="open"]`                  | Shows the bubble without hover, on `.tooltip`.                           |
-| `.tooltip-bubble.raised` / `.floating` | Adds one or two units of depth. The bubble is flat by default.           |
-
-A tooltip is composition, not a single class: `.tooltip` wraps a trigger element and a `.tooltip-bubble`, and shows the bubble on hover or focus within the wrapper. This replaced a `::after` pseudo-element that carried the message as `content: attr(data-tooltip)` — CSS generated content is not reliably exposed to assistive tech, and cannot be the target of an `aria-describedby`, since that needs a real element with a real `id`. A real bubble can be. Wire the association yourself: give the bubble an `id`, give the trigger `aria-describedby` pointing at it, and put `role="tooltip"` on the bubble.
+| Class or Attribute                     | Purpose                                                                                                                                                                     |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.tooltip`                             | Wrapper around a trigger and a bubble. Paints nothing itself.                                                                                                               |
+| `.tooltip-bubble`                      | The message. A real element, styled like any other surface.                                                                                                                 |
+| `.tooltip-icon`                        | Round icon-style trigger, for a message with nothing else to hang on. It takes the aesthetic's corner: square under `.neobrutalism` and `.pixel`, a diamond under `.cyber`. |
+| `[data-tooltip-position="top"]`        | Positions the bubble above the trigger, on `.tooltip`.                                                                                                                      |
+| `[data-tooltip-position="bottom"]`     | Positions the bubble below the trigger, on `.tooltip`.                                                                                                                      |
+| `[data-tooltip-position="left"]`       | Positions the bubble left of the trigger, on `.tooltip`.                                                                                                                    |
+| `[data-tooltip-position="right"]`      | Positions the bubble right of the trigger, on `.tooltip`.                                                                                                                   |
+| No `data-tooltip-position`             | Defaults to top placement.                                                                                                                                                  |
+| `[data-state="open"]`                  | Shows the bubble without hover, on `.tooltip`.                                                                                                                              |
+| `[data-state="closed"]`                | Hides the bubble even while hovered or focused, on `.tooltip`. For an Escape handler.                                                                                       |
+| `.tooltip-bubble.raised` / `.floating` | Adds one or two units of depth. The bubble is flat by default.                                                                                                              |
+
+A tooltip is composition, not a single class: `.tooltip` wraps a trigger element and a `.tooltip-bubble`, and shows the bubble on hover or focus within the wrapper. The bubble is a real element because CSS generated content is not reliably exposed to assistive tech and cannot be the target of an `aria-describedby`, which needs a real element with a real `id`. Wire the association yourself: give the bubble an `id`, give the trigger `aria-describedby` pointing at it, and put `role="tooltip"` on the bubble.
 
 A tooltip bubble's fill, ground color, and floor behavior are covered in [Composing → Presentation](./composing.md#presentation), and its material follows whichever [aesthetic](./aesthetics.md) is in scope. Intent, presentation, aesthetic, and elevation classes go on `.tooltip-bubble` — the element that actually paints — not on `.tooltip`, the same rule every component in this package follows: put the class on the element that shows it.
 
-The bubble rests flat. It draws no shadow of its own on a plain page, and zeroes an aesthetic's part-based depth (such as `.neobrutalism`'s slab) the same way `.flat` does elsewhere. Add [`.raised` or `.floating`](./composing.md#elevation) to lift it, on the bubble itself — `.tooltip-bubble.floating` is the pre-0.1.0 look. An aesthetic whose shadow is a complete value, like `.glass`, still reaches the bubble as it reaches any surface.
+The bubble rests flat. It draws no shadow of its own on a plain page, and zeroes an aesthetic's part-based depth (such as `.neobrutalism`'s slab) the same way `.flat` does elsewhere. Add [`.raised` or `.floating`](./composing.md#elevation) to lift it, on the bubble itself. An aesthetic whose shadow is a complete value, like `.glass`, still reaches the bubble as it reaches any surface.
 
 Intent works on a tooltip bubble the same way it works on a filled component: `.tooltip-bubble.primary` fills the bubble with the primary color, black text on a light page and white on a dark one; `.tooltip-bubble.destructive` is a red bubble with the same logic. With no intent, the bubble uses `--color-tooltip`, a plate chosen per theme rather than derived from an intent; see [Composing → Presentation](./composing.md#presentation) for why.
 
@@ -51,15 +52,34 @@ Intent works on a tooltip bubble the same way it works on a filled component: `.
 </span>
 
 <span class="tooltip" data-tooltip-position="right">
-  <span class="tooltip-icon" tabindex="0" aria-label="More details" aria-describedby="icon-bubble">?</span>
+  <button type="button" class="tooltip-icon" aria-label="More details" aria-describedby="icon-bubble">?</button>
   <span class="tooltip-bubble" role="tooltip" id="icon-bubble">More details</span>
 </span>
 ```
 
 The first two show plain triggers with default (top) and explicit bottom placement. The third combines an intent with `.raised` on the bubble to show they compose freely — the intent decides the bubble's fill, `.raised` decides whether it casts depth. The fourth uses `data-state="open"` on the wrapper to keep a tooltip visible without a hover or focus interaction, useful for a tooltip that should be demonstrated or tested without simulating pointer input. The fifth uses `.tooltip-icon` as the trigger, for a message with no other element to hang it on.
 
-`.tooltip` composes with any trigger: wrap an existing `.btn` or `.badge` in it and both keep their own look, gaining a bubble beside them. `.tooltip-icon` is only the circular chip for the case where there is nothing else to be the trigger.
+`.tooltip` composes with any trigger: wrap an existing `.btn` or `.badge` in it and both keep their own look, gaining a bubble beside them. `.tooltip-icon` is only the round chip for the case where there is nothing else to be the trigger.
 
 Showing and hiding the bubble is CSS-only — `:hover` and `:focus-within` on `.tooltip` — but that is presentational. It is not a complete accessible tooltip implementation by itself: provide the `id`/`aria-describedby`/`role="tooltip"` association outside the CSS; see [Accessibility](../accessibility.md).
 
+The bubble is hoverable, as WCAG 1.4.13 asks of content that appears on hover: once the pointer leaves the trigger, the bubble stays for `--tooltip-linger` (`300ms`, set on `.tooltip`) and then fades, so the pointer can cross the gap onto it, and it stays open for as long as the pointer is over it. A closed bubble is `visibility: hidden`, so it is nothing under the pointer. It stays in the accessibility tree through `aria-describedby`, which reads hidden content, but a bubble with no `aria-describedby` pointing at it is no longer read in place while hidden.
+
+1.4.13 also asks that the message can be dismissed without moving the pointer or focus, which takes a key handler. Write `data-state="closed"` on `.tooltip` on Escape, and clear it when the pointer and focus leave:
+
+```js
+for (const tooltip of document.querySelectorAll(".tooltip")) {
+  const reopen = () => tooltip.removeAttribute("data-state");
+  tooltip.addEventListener("pointerleave", reopen);
+  tooltip.addEventListener("focusout", reopen);
+}
+
+document.addEventListener("keydown", (event) => {
+  if (event.key !== "Escape") return;
+  for (const tooltip of document.querySelectorAll(".tooltip:hover, .tooltip:focus-within")) {
+    tooltip.dataset.state = "closed";
+  }
+});
+```
+
 Next: [Content and layout](./content-and-layout.md) covers layout helpers, content chips and tables, surfaces, and typography utilities.