@codenhub/styles 0.1.0 → 0.2.0

package/docs/usage/aesthetics.md

@@ -1,22 +1,19 @@
 ---
 title: Aesthetics
 description: The four shipped aesthetics in depth, including their documented exceptions.
+order: 4
 ---
 
 # Aesthetics
 
-An aesthetic decides what a component is _made of_: its radius, border
-thickness, shadow, and shape. Aesthetics ship from opt-in entrypoints, so
-importing the stylesheet is what makes the classes available:
+An aesthetic decides what a component is _made of_: its radius, border thickness, shadow, and shape. Aesthetics ship from opt-in entrypoints, so importing the stylesheet is what makes the classes available:
 
 ```css
 @import "@codenhub/styles";
 @import "@codenhub/styles/aesthetics";
 ```
 
-Import them after the base stylesheet. `.neobrutalism` and `.pixel` replace
-the neutral border color, and they do so at zero specificity, so source order
-is what lets them win.
+Import them after the base stylesheet. `.neobrutalism` and `.pixel` replace the neutral border color, and they do so at zero specificity, so source order is what lets them win.
 
 Like presentation, an aesthetic class cascades to any subtree:
 
@@ -34,33 +31,19 @@ Like presentation, an aesthetic class cascades to any subtree:
 | `.pixel`        | Corners cut by one grid unit, a chunky outline drawn as an inset ring, and the consumer-supplied `--font-pixel` over monospace. |
 | `.chunky-tile`  | Rounded slabs seated on a darker shade of themselves, with a press that moves the element down into its own bar.                |
 
-Aesthetics compose with every supported fill and edge pair. `.ghost.edgeless`
-intentionally removes the visible material traits from components whose
-aesthetic is expressed only through their fill, edge, or elevation.
+Aesthetics compose with every supported fill and edge pair. `.ghost.edgeless` intentionally removes the visible material traits from components whose aesthetic is expressed only through their fill, edge, or elevation.
 
-An explicit presentation on the element still wins over the aesthetic's
-defaults. The aesthetic supplies edge thickness; presentation only decides
-whether that edge is drawn.
+An explicit presentation on the element still wins over the aesthetic's defaults. The aesthetic supplies edge thickness; presentation only decides whether that edge is drawn.
 
-An aesthetic directly on a component likewise wins over an inherited
-aesthetic. This includes tooltip pseudo-elements: `.tooltip.glass` gets the
-complete glass bubble under a pixel ancestor, and `.tooltip.pixel` gets the
-complete stepped bubble under a glass ancestor.
+An aesthetic directly on a component likewise wins over an inherited aesthetic. This includes tooltip bubbles: `.tooltip-bubble.glass` gets the complete glass bubble under a pixel ancestor, and `.tooltip-bubble.pixel` gets the complete stepped bubble under a glass ancestor.
 
-Each aesthetic that scales from one number publishes it as a knob — see
-[Customizing → Aesthetic tokens](./customizing.md#aesthetic-tokens) for how
-knobs resolve and where they can be set. This page covers what each
-aesthetic looks like and where it makes documented exceptions.
+Each aesthetic that scales from one number publishes it as a knob — see [Customizing → Aesthetic tokens](./customizing.md#aesthetic-tokens) for how knobs resolve and where they can be set. This page covers what each aesthetic looks like and where it makes documented exceptions.
 
 ## Neobrutalism
 
-The shadow is cast in the component's own intent, so a success button throws
-a green shadow and a destructive card a red one. With no intent, both the
-outline and the shadow use the ink, which follows the theme rather than the
-palette.
+The shadow is cast in the component's own intent, so a success button throws a green shadow and a destructive card a red one. With no intent, both the outline and the shadow use the ink, which follows the theme rather than the palette.
 
-`--neo-offset` is the knob: the shadow offset and the distance the press
-travels are the same number, so scaling the look scales both at once.
+`--neo-offset` is the knob: the shadow offset and the distance the press travels are the same number, so scaling the look scales both at once.
 
 ```html
 <section class="neobrutalism" style="--neo-offset: 6px">
@@ -70,26 +53,15 @@ travels are the same number, so scaling the look scales both at once.
 
 **Exceptions:**
 
-- Content chips are left alone. A `.kbd`, `.code`, or `.pre` is content
-  rather than structure, and an ink edge on one reads as a defect: a key cap
-  keeps the quiet border color and a code chip keeps no border at all.
-- Only `.btn` and `.card.interactive` respond to hover and press. A card
-  becomes a control when it opts in with `.interactive`; a plain card, an
-  alert, or a panel is a container and stays put.
-- An alert rests on the slab under this aesthetic and nowhere else. Here the
-  slab is a second ink line rather than depth, and an alert is the only
-  container the package rests flat, so without it a neobrutalist alert is
-  the one box on the page that reads as unfinished. It is a resting default,
-  so `.flat` still takes it off and `.floating` still doubles it.
+- Content chips are left alone. A `.kbd`, `.code`, or `.pre` is content rather than structure, and an ink edge on one reads as a defect: a key cap keeps the quiet border color and a code chip keeps no border at all.
+- Only `.btn` and an opted-in `.card` respond to hover and press. A card opts in with `.interactive`, or with one of its halves — `.hoverable` for the hover response alone, `.pressable` for the press alone; a plain card, an alert, or a panel is a container and stays put.
+- An alert rests on the slab under this aesthetic and nowhere else. Here the slab is a second ink line rather than depth, and an alert is the only container the package rests flat, so without it a neobrutalist alert is the one box on the page that reads as unfinished. It is a resting default, so `.flat` still takes it off and `.floating` still doubles it.
 
 ## Glass
 
-`.glass` needs something behind it to blur. On a flat page background it
-renders as a plain translucent panel.
+`.glass` needs something behind it to blur. On a flat page background it renders as a plain translucent panel.
 
-`--glass-radius` and `--glass-radius-surface` are the corners, at `0.75rem`
-and `1rem`. Glass is rounder than the base geometry because a translucent
-panel with a tight corner reads as a cut-out rather than as a pane.
+`--glass-radius` and `--glass-radius-surface` are the corners, at `0.75rem` and `1rem`. Glass is rounder than the base geometry because a translucent panel with a tight corner reads as a cut-out rather than as a pane.
 
 ```html
 <section class="glass" style="--glass-radius-surface: 1.5rem">
@@ -99,18 +71,12 @@ panel with a tight corner reads as a cut-out rather than as a pane.
 
 **Exceptions:**
 
-- The blur applies to `.card`, `.panel`, `.alert`, and the tooltip bubble
-  only. Controls stay solid and sit on the glass: a blur under every control
-  of a dense cluster costs a composited layer apiece and reads as noise.
-  Controls still take the aesthetic's radius, border, and shadow.
-- Under `prefers-reduced-transparency: reduce`, glass surfaces drop the blur
-  and become opaque.
+- The blur applies to `.card`, `.panel`, `.alert`, and the tooltip bubble only. Controls stay solid and sit on the glass: a blur under every control of a dense cluster costs a composited layer apiece and reads as noise. Controls still take the aesthetic's radius, border, and shadow.
+- Under `prefers-reduced-transparency: reduce`, glass surfaces drop the blur and become opaque.
 
 ## Pixel
 
-`--pixel-unit` is one pixel of the imaginary low-resolution grid, `4px` by
-default. One square unit is cut from each corner and the outline is one unit
-thick, so the cut and what covers it are the same size.
+`--pixel-unit` is one pixel of the imaginary low-resolution grid, `4px` by default. One square unit is cut from each corner and the outline is one unit thick, so the cut and what covers it are the same size.
 
 ```html
 <section class="pixel" style="--pixel-unit: 6px">
@@ -120,44 +86,17 @@ thick, so the cut and what covers it are the same size.
 
 **Exceptions:**
 
-- Corners are one unit or nothing. Chips square instead of stepping —
-  badges, key caps, code, checkboxes, and switches all read
-  `--ui-clip-tight`, which this aesthetic sets to none, because one unit off
-  each corner of a 24px badge is a bite rather than a corner. Tables,
-  progress bars, and skeletons square too, each for its own reason: a
-  table's `overflow: hidden` fights the clip and the corners square off
-  where the two meet, and progress and skeleton never read a clip at all —
-  a squaring aesthetic reaches them through `border-radius` alone. `.pre` is
-  the one exception that steps: it carries no clip override, so it inherits
-  the same polygon a button or a card gets, and with no border by default
-  the cut shows with no ring around it.
-- The outline is an inset ring, because a clip removes a real border — and
-  the focus ring, for the same reason, is a second inset layer rather than
-  an outline. Both are the element's own edge rather than a shadow, so the
-  border answers `.edged` and `.edgeless` the way a border does: a
-  `.edgeless` badge and a `.solid` button draw none, a `.edged` card draws
-  one, and a field keeps one whatever a container asks for.
-- The tooltip trigger and `.radio` are hardcoded past the clip rather than
-  reached by it. `.tooltip-icon` forces `clip-path: none`, since a stepped
-  badge would clip its own bubble away with it. `.radio` forces the same,
-  because the circle is the only thing telling it from a checkbox at a
-  glance, and a stepped polygon would square it.
-- `--font-pixel` is yours to supply. The package ships no font binary, so the
-  aesthetic has no network side effect and falls back to the monospace
-  stack.
+- Corners are one unit or nothing. Chips square instead of stepping — badges, key caps, code, checkboxes, and switches all read `--ui-clip-tight`, which this aesthetic sets to none, because one unit off each corner of a 24px badge is a bite rather than a corner. Tables, progress bars, and skeletons square too, each for its own reason: a table's `overflow: hidden` fights the clip and the corners square off where the two meet, and progress and skeleton never read a clip at all — a squaring aesthetic reaches them through `border-radius` alone. `.pre` is the one exception that steps: it carries no clip override, so it inherits the same polygon a button or a card gets, and with no border by default the cut shows with no ring around it.
+- The outline is an inset ring, because a clip removes a real border — and the focus ring, for the same reason, is a second inset layer rather than an outline. Both are the element's own edge rather than a shadow, so the border answers `.edged` and `.edgeless` the way a border does: a `.edgeless` badge and a `.solid` button draw none, a `.edged` card draws one, and a field keeps one whatever a container asks for.
+- The tooltip trigger and `.radio` are hardcoded past the clip rather than reached by it. `.tooltip-icon` forces `clip-path: none` because the docs call it a circular fixed identity, the same reason `.radio` forces it: the circle is the only thing telling it from a checkbox at a glance, and a stepped polygon would square either one.
+- `--font-pixel` is yours to supply. The package ships no font binary, so the aesthetic has no network side effect and falls back to the monospace stack.
+- Numeral legibility depends on the face you pick. At UI sizes -- pagination, counters, small badges -- some pixel/bitmap faces render lookalike digits such as `2`/`8` or `3`/`9` closely enough to misread at a glance; this is a property of the font, not something the aesthetic's CSS can correct. Prefer a face with clearly distinct digit shapes wherever small numeric text matters.
 
 ## Chunky tile
 
-Rounded slabs sitting on a darker shade of themselves, pressed flat on
-click. The look mobile learning and game apps use; it is named for what it
-is made of rather than for any one product.
+Rounded slabs sitting on a darker shade of themselves, pressed flat on click. The look mobile learning and game apps use; it is named for what it is made of rather than for any one product.
 
-`--tile-lift` is how deep the bar is and how far a press travels, `4px` by
-default. One number drives both, so the top edge drops by exactly the bar's
-depth and the bottom edge does not move. `--tile-radius` is the corner,
-`0.75rem`, and it is one value rather than a control/surface pair on
-purpose — the shared corner is what makes a button and the card it sits in
-read as the same object.
+`--tile-lift` is how deep the bar is and how far a press travels, `4px` by default. One number drives both, so the top edge drops by exactly the bar's depth and the bottom edge does not move. `--tile-radius` is the corner, `0.75rem`, and it is one value rather than a control/surface pair on purpose — the shared corner is what makes a button and the card it sits in read as the same object.
 
 ```html
 <section class="chunky-tile" style="--tile-lift: 6px; --tile-radius: 0.5rem">
@@ -165,33 +104,18 @@ read as the same object.
 </section>
 ```
 
-The bar is a darker shade of the element's own colour rather than a shadow
-under it, so it follows every intent: a success button sits on a dark green
-edge, a destructive one on a dark red edge, and a plain card on a grey edge
-that matches the line it already draws. Measured on the light palette,
-`.btn.success` is `#007a55` on `#004c34`. On a dark page a near-black
-surface cannot go darker, so its bar lands lighter and reads as a rim.
+The bar is a darker shade of the element's own colour rather than a shadow under it, so it follows every intent: a success button sits on a dark green edge, a destructive one on a dark red edge, and a plain card on a grey edge that matches the line it already draws. Measured on the light palette, `.btn.success` is `#007a55` on `#004c34`. On a dark page a near-black surface cannot go darker, so its bar lands lighter and reads as a rim.
 
 **Exceptions:**
 
-- Only what the registry rests above zero sits on a bar — buttons and cards.
-  A badge, chip, field, or tooltip is flat until it asks for depth with
-  `.raised`, and `.flat` takes the bar off anything:
+- Only what the registry rests above zero sits on a bar — buttons and cards. A badge, chip, field, or tooltip is flat until it asks for depth with `.raised`, and `.flat` takes the bar off anything:
 
   ```html
   <div class="card soft edgeless info flat">Promo panel, deliberately flat</div>
   ```
 
-- `--font-rounded` is yours to supply. A heavy rounded grotesque is most of
-  this look and the package ships no font binary, so with nothing supplied
-  the page's own stack is used.
-- Action labels are drawn heavier and slightly tracked. Casing is left
-  alone: how a label is worded is the application's decision, so if you want
-  uppercase buttons, write that rule in your own stylesheet.
-- `.card.interactive` presses like a `.btn`, so a chunky answer tile drops
-  onto its bar on click. A plain `.card` stays put.
-- The shipped `.primary` is a near-black monochrome, which leaves a primary
-  button's bar almost invisible against its own plate; give `.primary` a hue
-  if it is the call to action.
-- Depth in this aesthetic is the bar, never a blurred drop shadow. Anything
-  the registry rests flat sits flush on the page.
+- `--font-rounded` is yours to supply. A heavy rounded grotesque is most of this look and the package ships no font binary, so with nothing supplied the page's own stack is used.
+- Action labels are drawn heavier and slightly tracked. Casing is left alone: how a label is worded is the application's decision, so if you want uppercase buttons, write that rule in your own stylesheet.
+- `.card.interactive` presses like a `.btn`, so a chunky answer tile drops onto its bar on click; `.card.pressable` gets the same press on its own. A plain `.card` stays put.
+- The shipped `.primary` is a near-black-or-near-white monochrome depending on theme, and the bar mixes toward a fixed black regardless of theme. In light theme this leaves a primary button's bar almost invisible against its own near-black plate (measured `1.04:1`, 10 units of sRGB distance); in dark theme the near-white plate against the same black-anchored bar reads fine (`2.48:1`, 154 units). Give `.primary` a hue of its own if it is the call to action and needs the depth cue in both themes.
+- Depth in this aesthetic is the bar, never a blurred drop shadow. Anything the registry rests flat sits flush on the page.

package/docs/usage/buttons.md

@@ -1,18 +1,14 @@
 ---
 title: Buttons
 description: Button classes, intents, sizes, and states.
+order: 5
 ---
 
 # Buttons
 
-Use `.btn` with one optional intent class, one optional fill class, one
-optional edge class, optional size class, and optional state. See
-[Composing](./composing.md) for how the intent, presentation, and aesthetic
-axes combine on any component.
+Use `.btn` with one optional intent class, one optional fill class, one optional edge class, optional size class, and optional state. See [Composing](./composing.md) for how the intent, presentation, and aesthetic axes combine on any component.
 
-Intent classes map color tokens into button tone slots.
-[Presentation](./composing.md#presentation) decides how much of that intent
-reaches background, text, border, and hover.
+Intent classes map color tokens into button tone slots. [Presentation](./composing.md#presentation) decides how much of that intent reaches background, text, border, and hover.
 
 Intent classes:
 
@@ -26,29 +22,22 @@ Intent classes:
 | `.destructive`, `.danger`, `.error` | Destructive or error action.   |
 | `.info`                             | Informational action.          |
 
-Every component that supports intent accepts the same list and reads the
-same [intent tokens](./theming.md#intent-tokens), so a custom intent class
-works everywhere without touching a component.
+Every component that supports intent accepts the same list and reads the same [intent tokens](./theming.md#intent-tokens), so a custom intent class works everywhere without touching a component.
 
-`.neutral` is the only intent that does not fill all the way. Its color is
-the page's own text color, so a full fill of it would be a black or white
-slab — the loudest element on the page, for the intent that means nothing in
-particular. It stops at `--intent-fill-max`, which is why a `.solid` neutral
-is a quiet plate a step past `.soft` rather than a block of ink. Set the slot
-on your own intent classes; see [Theming → Intent tokens](./theming.md#intent-tokens).
+`.neutral` is the only intent that does not fill all the way. Its color is the page's own text color, so a full fill of it would be a black or white slab — the loudest element on the page, for the intent that means nothing in particular. It stops at `--intent-fill-max`, which is why a `.solid` neutral is a quiet plate a step past `.soft` rather than a block of ink. Set the slot on your own intent classes; see [Theming → Intent tokens](./theming.md#intent-tokens).
 
 Size and shape classes:
 
-| Class                                                                  | Purpose                                                     |
-| ---------------------------------------------------------------------- | ----------------------------------------------------------- |
-| `.pill`                                                                | Fully rounded button corners (`border-radius: 9999px`).     |
-| `.sm`                                                                  | Smaller button.                                             |
-| `.lg`                                                                  | Larger button.                                              |
-| `.p-sm`, `.compact`                                                    | Compact padding modifier (`px-2.5 py-1`).                   |
-| `.p-lg`, `.spacious`                                                   | Spacious padding modifier (`px-6 py-3`).                    |
-| `.icon`                                                                | Square icon button. Use an accessible name in HTML.         |
-| `.loading`                                                             | Loading state. Hides text and shows CSS activity indicator. |
-| `.disabled`, `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` | Disabled styling.                                           |
+| Class                                                                  | Purpose                                                                                                                                                                                                                                   |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.pill`                                                                | Fully rounded button corners (`border-radius: 9999px`).                                                                                                                                                                                   |
+| `.sm`                                                                  | Smaller button.                                                                                                                                                                                                                           |
+| `.lg`                                                                  | Larger button.                                                                                                                                                                                                                            |
+| `.p-xs`, `.dense`                                                      | Tightest padding modifier (`px-2 py-0.5`; icon `p-0.5`). Also drops the `--control-height` minimum so a chip-sized button fits a table cell or a dense toolbar; every other size and padding class keeps that floor for a labeled button. |
+| `.p-sm`, `.compact`                                                    | Compact padding modifier (`px-2.5 py-1`; icon `p-1`).                                                                                                                                                                                     |
+| `.p-lg`, `.spacious`                                                   | Spacious padding modifier (`px-6 py-3`; icon `p-3`).                                                                                                                                                                                      |
+| `.icon`                                                                | Square icon button, sized to its own padding rather than to `--control-height`. Use an accessible name in HTML.                                                                                                                           |
+| `.disabled`, `[disabled]`, `[aria-disabled="true"]`, `[data-disabled]` | Disabled styling.                                                                                                                                                                                                                         |
 
 Examples:
 
@@ -58,17 +47,16 @@ Examples:
 <button class="btn warning soft">Warning soft</button>
 <button class="btn destructive ghost edgeless">Danger ghost</button>
 <button class="btn icon primary" aria-label="Create">+</button>
-<button class="btn primary loading" disabled>Saving</button>
+<button class="btn primary" disabled>
+  <span class="loader sm" aria-hidden="true"></span>
+  Saving
+</button>
 ```
 
-`.loading` is a state, not a color or presentation class. Prefer combining
-it with disabled behavior so users cannot trigger duplicate work. Loading
-buttons keep only opacity and transform transitions active so spinner and
-surface colors stay synchronized when theme tokens change.
+## Loading
 
-On the base look a press scales the button down a little
-(`--ui-active-transform`, `scale(0.97)`). [Aesthetics](./aesthetics.md) swap
-in their own press gesture, and `prefers-reduced-motion` turns it off.
+The package ships no loading state of its own: a loading button is a disabled `.btn` composed with a real [`.loader`](./feedback.md) child, the same activity indicator every other component uses. Disable the button so users cannot trigger duplicate work, and drop a `.loader` in beside the label — any of its variants (`.dots-wave`, `.bars-wave`, and so on) work the same way. Whether to also hide the label is your call; the package has no built-in mechanism for that.
 
-Use `<button>` for actions or an accessible link for navigation; see
-[Accessibility](../accessibility.md).
+On the base look a press scales the button down a little (`--ui-active-transform`, `scale(0.97)`). [Aesthetics](./aesthetics.md) swap in their own press gesture, and `prefers-reduced-motion` turns it off.
+
+Use `<button>` for actions or an accessible link for navigation; see [Accessibility](../accessibility.md).

package/docs/usage/composing.md

@@ -1,13 +1,12 @@
 ---
 title: Composing
 description: Combining intent, presentation, and aesthetic on a component, and the axis-support matrix.
+order: 1
 ---
 
 # Composing the three axes
 
-See [Concepts](../concepts.md#the-three-axes) for what each axis means. This
-page covers how they combine in markup, what the presentation classes mean in
-depth, which components support which axis, and elevation.
+See [Concepts](../concepts.md#the-three-axes) for what each axis means. This page covers how they combine in markup, what the presentation classes mean in depth, which components support which axis, and elevation.
 
 ## Combining axes
 
@@ -19,25 +18,13 @@ depth, which components support which axis, and elevation.
 </div>
 ```
 
-A declaration on the element always beats one inherited from a container, so
-a container sets the default look for its subtree and any element opts out.
+A declaration on the element always beats one inherited from a container, so a container sets the default look for its subtree and any element opts out.
 
-Intent classes do not cascade. `.primary` and its siblings stay on the
-element that shows the intent, because a container silently recoloring every
-descendant is a trap rather than a feature — see
-[Theming → Intent tokens](./theming.md#intent-tokens). Use `.neutral` to opt
-an element back out of an inherited intent context. Presentation and
-[material tokens](./customizing.md#material-tokens) do cascade, so a
-container can set the look of its whole subtree while any element overrides
-it.
+Intent classes do not cascade. `.primary` and its siblings stay on the element that shows the intent, because a container silently recoloring every descendant is a trap rather than a feature — see [Theming → Intent tokens](./theming.md#intent-tokens). Use `.neutral` to opt an element back out of an inherited intent context. Presentation and [material tokens](./customizing.md#material-tokens) do cascade, so a container can set the look of its whole subtree while any element overrides it.
 
 ## Presentation
 
-Presentation has two independent axes. `.solid`, `.soft`, and `.ghost`
-decide how much intent fills a component; `.edged` and `.edgeless` decide
-whether it draws a boundary. They set
-[presentation tokens](./customizing.md#presentation-tokens) and nothing
-else, so they work on the component itself or on any ancestor.
+Presentation has two independent axes. `.solid`, `.soft`, and `.ghost` decide how much intent fills a component; `.edged` and `.edgeless` decide whether it draws a boundary. They set [presentation tokens](./customizing.md#presentation-tokens) and nothing else, so they work on the component itself or on any ancestor.
 
 | Class       | Look                                                       |
 | ----------- | ---------------------------------------------------------- |
@@ -57,6 +44,8 @@ Values each class ships:
 | `.edged`    |             |                   | `100%`        |
 | `.edgeless` |             |                   | `0%`          |
 
+`.card`, `.panel`, `.alert`, `.kbd`, `.code`, and `.pre` override `.soft`'s fill at rest to `0%` for the no-named-intent case only, and reveal it on `.card`'s own `:hover`/`.interactive`/`.hoverable` -- the one place a component remaps what a presentation class resolves to for part of its intent range, the same way text controls cap it at `6%` cascaded. A named intent on any of the six keeps the ordinary `12%`. `.badge` reads the identical intent/presentation classes but keeps its 12% wash at rest even with no named intent, since it has no border to fall back on and would otherwise disappear rather than read quieter. See [Content and layout → Surfaces](./content-and-layout.md#surfaces) and [Feedback](./feedback.md).
+
 The combinations mean exactly what they spell:
 
 ```html
@@ -68,21 +57,11 @@ The combinations mean exactly what they spell:
 <!-- A field sunk into the page -->
 ```
 
-A fill class never decides an edge and an edge class never decides a fill.
-Use `.solid.edgeless` for a filled box with no line — and prefer it on a
-neutral one, because a capped fill leaves the box translucent and the edge
-blend then paints a second coat of the same tint rather than disappearing
-into it (measured 1.53:1 against its own plate in light, 1.82:1 in dark).
+A fill class never decides an edge and an edge class never decides a fill. Use `.solid.edgeless` for a filled box with no line — and prefer it on a neutral one, because a capped fill leaves the box translucent and the edge blend then paints a second coat of the same tint rather than disappearing into it (measured 1.53:1 against its own plate in light, 1.82:1 in dark).
 
-The edge is the silhouette and nothing else. Rules _inside_ a component that
-has an inside are a separate switch — see
-[Content and layout → Table rules](./content-and-layout.md#table-rules) —
-because tying them to this axis made them arrive by implication rather than
-by request.
+The edge is the silhouette and nothing else. Rules _inside_ a component that has an inside are a separate switch — see [Content and layout → Table rules](./content-and-layout.md#table-rules) — because tying them to this axis made them arrive by implication rather than by request.
 
-With no presentation class in scope, each component keeps its own default:
-buttons are filled, alerts and badges are tinted, surfaces and controls are
-neutral and bordered.
+With no presentation class in scope, each component keeps its own default: buttons are filled, alerts and badges are tinted, surfaces and controls are neutral and bordered.
 
 | Component                                       | Reads                                       |
 | ----------------------------------------------- | ------------------------------------------- |
@@ -94,15 +73,10 @@ neutral and bordered.
 | `.checkbox`, `.radio`                           | A capped fill, checked and unchecked.       |
 | `.switch`                                       | Border, border width, and a capped fill.    |
 | `.quote`                                        | Fill, text, border, and width.              |
-| `.code`, `.pre`, `.tooltip`                     | Fill, text, border, and material.           |
+| `.code`, `.pre`, `.tooltip-bubble`              | Fill, text, border, and material.           |
 | `.loader`, `.skeleton`, `.progress`, `.divider` | Intent only, not presentation.              |
 
-Text controls and toggles cap a **cascaded** fill at `6%`, keeping typed
-text legible when a `.solid` container reaches a field nobody classed. A
-fill class written on the control itself names its own cap instead, because
-that is a consumer describing what they want: `.soft` takes `12%` and
-`.solid` takes `20%`. A switch caps at `40%`, where its three fills separate
-far enough to read on a track.
+A text control caps a **cascaded** fill at `6%`, keeping typed text legible when a `.solid` container reaches a field nobody classed. A fill class written on the control itself names its own cap instead, because that is a consumer describing what they want: `.soft` takes `12%` and `.solid` takes `20%`.
 
 | On a text control | fill |
 | ----------------- | ---- |
@@ -111,45 +85,21 @@ far enough to read on a track.
 | `.soft`           | 12%  |
 | `.solid`          | 20%  |
 
-The same split governs the edge: a cascaded `.edgeless` is floored and the
-element's own is honoured — except on `.checkbox` and `.radio`, which never
-drop their line at all. See [Forms](./forms.md) for the full toggle and text
-control reference.
-
-A tooltip bubble is filled, over a tinted ground. An intent fills it with
-that intent's own color: `.tooltip.primary` is the primary color, black on a
-light page and white on a dark one, and `.tooltip.destructive` is a red
-bubble.
-
-With no intent the bubble is `--color-tooltip`, the one plate in the package
-chosen per theme rather than derived from an intent. Composed like
-everything else it was `20%` of the page's ink over the surface tone, which
-steps _lighter_ than the surface on a dark page and _darker_ on a light
-one — so the dark bubble read as lifted and the light one as a mid-grey
-slab two steps darker than every card on the screen. The token states each
-direction instead: near-white over a light page, a mid grey over a dark
-one. `--color-tooltip-contrast` is its ink.
-
-Near-white is only 1.04:1 against a light page, so the bubble draws a
-hairline as well, and floors it: a container's `.solid` or `.edgeless`
-cannot take the boundary away from a bubble nobody classed, while
-`.tooltip.edgeless` still can. The ground keeps the bubble opaque at every
-fill, so a cascaded presentation leaves it readable over whatever it floats
-above. It reads the material tokens too, so an [aesthetic](./aesthetics.md)
-in scope shapes the bubble like any other component. See
-[Tooltips](./tooltips.md) for the full tooltip reference.
+A toggle's cap does not have that split: it is `40%` whether the presentation class is on the checkbox/radio/switch itself or cascaded from a container, the same value for all three. That is where an unchecked `.ghost` (0%), `.soft`/default (12%), and `.solid` (the cap) read as three distinct plates instead of shades of the same wash. Being checked pins the fill to `100%` instead, whatever the presentation class asks — a checkbox, a radio, and a switch each have one "on" look, and presentation only shapes them unchecked. See [Forms](./forms.md) for the full toggle reference.
+
+The same split governs the edge: a cascaded `.edgeless` is floored and the element's own is honoured — except on `.checkbox` and `.radio`, which never drop their line at all, and on `.switch.ghost`, which keeps its line specifically against its own `.edgeless`: `.ghost` already asks for zero fill, so removing the line too would leave nothing marking the track but the knob. `.switch.ghost.edgeless` renders the same as `.switch.ghost.edged` rather than as a distinct, boundary-less look. See [Forms](./forms.md) for the full toggle and text control reference.
+
+A tooltip bubble is filled, over a tinted ground. An intent fills it with that intent's own color: `.tooltip-bubble.primary` is the primary color, black on a light page and white on a dark one, and `.tooltip-bubble.destructive` is a red bubble.
+
+With no intent the bubble is `--color-tooltip`, the one plate in the package chosen per theme rather than derived from an intent. Composed like everything else it was `20%` of the page's ink over the surface tone, which steps _lighter_ than the surface on a dark page and _darker_ on a light one — so the dark bubble read as lifted and the light one as a mid-grey slab two steps darker than every card on the screen. The token states each direction instead: near-white over a light page, a mid grey over a dark one. `--color-tooltip-contrast` is its ink.
+
+Near-white is only 1.04:1 against a light page, so the bubble draws a hairline as well, and floors it: a container's `.solid` or `.edgeless` cannot take the boundary away from a bubble nobody classed, while `.tooltip-bubble.edgeless` still can. The ground keeps the bubble opaque at every fill, so a cascaded presentation leaves it readable over whatever it floats above. It reads the material tokens too, so an [aesthetic](./aesthetics.md) in scope shapes the bubble like any other component. See [Tooltips](./tooltips.md) for the full tooltip reference.
 
 ## Component axis reference
 
-This table is the authoritative axis map for demonstrated components. "Shape"
-means the component reads applicable radius, border-width, shadow, hover, or
-clip/edge material tokens; an aesthetic may intentionally affect only the
-materials that component draws.
+This table is the authoritative axis map for demonstrated components. "Shape" means the component reads applicable radius, border-width, shadow, hover, or clip/edge material tokens; an aesthetic may intentionally affect only the materials that component draws.
 
-Presentation is two independent axes, so they get a column each. A `Yes` means
-the class changes what the component computes, which
-`tests/browser/axes.spec.ts` asserts against `registry.json` in both
-directions: an axis marked `Yes` must move, and an axis marked `No` must not.
+Presentation is two independent axes, so they get a column each. A `Yes` means the class changes what the component computes, which `tests/browser/axes.spec.ts` asserts against `registry.json` in both directions: an axis marked `Yes` must move, and an axis marked `No` must not.
 
 | Components                                                | Intent | Fill | Edge | Aesthetic material |
 | --------------------------------------------------------- | ------ | ---- | ---- | ------------------ |
@@ -165,27 +115,18 @@ directions: an axis marked `Yes` must move, and an axis marked `No` must not.
 | `.switch`                                                 | Yes    | Yes  | Yes  | Radius and edge    |
 | `.progress`                                               | Yes    | No   | No   | No                 |
 | `.code`, `.pre`                                           | Yes    | Yes  | Yes  | Radius and clip    |
-| `.tooltip`                                                | Yes    | Yes  | Yes  | Shape and overlay  |
+| `.tooltip-bubble`                                         | Yes    | Yes  | Yes  | Shape and overlay  |
 | `.table-wrap`, `.quote-inline`, layout and text utilities | No     | No   | No   | No                 |
 
-`.checkbox` and `.radio` are the only components that read one axis and not
-the other. Their line is the only thing marking an unchecked box, so it is
-drawn whatever the edge class says, from a container or from the element
-itself. `.edgeless` on either is unsupported rather than merely discouraged.
+`.checkbox` and `.radio` are the only components that read one axis and not the other. Their line is the only thing marking an unchecked box, so it is drawn whatever the edge class says, from a container or from the element itself. `.edgeless` on either is unsupported rather than merely discouraged.
 
-Every other text control floors a _cascaded_ `.edgeless` and honours its own:
-a `.edgeless` toolbar will not erase the line of a field nobody classed, while
-`.ipt.edgeless` is a consumer describing what they want and gets it.
+Every other text control floors a _cascaded_ `.edgeless` and honours its own: a `.edgeless` toolbar will not erase the line of a field nobody classed, while `.ipt.edgeless` is a consumer describing what they want and gets it.
 
-Intent aliases such as `.danger` and `.error` occupy the same intent axis as
-`.destructive`; they do not add component behavior. State and modifier
-classes such as `.interactive`, `.loading`, `.invalid`, `.compact`, and
-`.vertical` sit above this map and are documented with their component.
+Intent aliases such as `.danger` and `.error` occupy the same intent axis as `.destructive`; they do not add component behavior. State and modifier classes such as `.interactive`, `.hoverable`, `.pressable`, `.invalid`, `.compact`, and `.vertical` sit above this map and are documented with their component.
 
 ## Elevation
 
-Depth is a modifier, not an axis. Nothing is raised until an
-[aesthetic](./aesthetics.md) draws depth or one of these classes asks for it.
+Depth is a modifier, not an axis. Nothing is raised until an [aesthetic](./aesthetics.md) draws depth or one of these classes asks for it.
 
 | Class             | Alias       | Depth                                                                    |
 | ----------------- | ----------- | ------------------------------------------------------------------------ |
@@ -193,17 +134,9 @@ Depth is a modifier, not an axis. Nothing is raised until an
 | `.elevation-sm`   | `.raised`   | One unit of the depth in scope. Cards, tiles, popovers that sit close.   |
 | `.elevation-md`   | `.floating` | Twice it, for menus and popovers.                                        |
 
-Both names in a row are equivalent, interchangeable classes — `.elevation-sm`
-and `.raised` are aliases, not a canonical form and a deprecated one, the way
-`.destructive` and `.danger` are on the intent axis. The `none`/`sm`/`md`
-naming matches the raw `--elevation-*` tokens in
-[Theming](./theming.md#foundation-tokens) for the same weight of depth, even
-though the two are read from different places.
+Both names in a row are equivalent, interchangeable classes — `.elevation-sm` and `.raised` are aliases, not a canonical form and a deprecated one, the way `.destructive` and `.danger` are on the intent axis. The `none`/`sm`/`md` naming matches the raw `--elevation-*` tokens in [Theming](./theming.md#foundation-tokens) for the same weight of depth, even though the two are read from different places.
 
-Each is one unitless multiplier over whatever shadow geometry is in scope, so
-the same class reads as a soft blur on a plain page and as a hard offset slab
-under `.neobrutalism` — the aesthetic decides what depth looks like, the
-class decides how much of it this element takes.
+Each is one unitless multiplier over whatever shadow geometry is in scope, so the same class reads as a soft blur on a plain page and as a hard offset slab under `.neobrutalism` — the aesthetic decides what depth looks like, the class decides how much of it this element takes.
 
 ```html
 <article class="card elevation-sm">Lifted</article>
@@ -211,8 +144,4 @@ class decides how much of it this element takes.
 <article class="card elevation-none">Flat, whatever the page or container says</article>
 ```
 
-The multiplier is a plain number, so it inherits: a container lifts or
-flattens a whole region and any element inside it still opts out on itself.
-Spread is deliberately left out of the multiplication, because an aesthetic
-that draws its edge as an inset ring spends spread on it and scaling that
-would erase the edge.
+The multiplier does not inherit: an elevation class lifts or flattens the element it is written on only, and an unclassed element inside it takes no depth of its own. Give each element that needs depth its own elevation class. Spread is deliberately left out of the multiplication, because an aesthetic that draws its edge as an inset ring spends spread on it and scaling that would erase the edge.