@codenhub/styles 0.1.0 → 0.2.0

package/docs/usage/forms.md

@@ -1,43 +1,36 @@
 ---
 title: Forms
 description: Field, text control, and toggle class reference.
+order: 6
 ---
 
 # Forms
 
-| Class or Selector                                                     | Purpose                                                       |
-| --------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `.field`                                                              | Vertical field wrapper.                                       |
-| `.label`                                                              | Form label text.                                              |
-| `.hint`                                                               | Secondary helper text.                                        |
-| `.hint.error`                                                         | 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 icons. |
-| `.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.error`                                                         | 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.                                                        |
 
 ## Icons
 
-The package ships no icons. 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 are the consumer's to choose now.
+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.
 
-`.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`.
+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.
+
+`.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">
@@ -59,22 +52,24 @@ set such as `@codenhub/icons`.
 </label>
 ```
 
-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.
+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.
+
+The slot works the same way for a text affix — a URL host, a currency symbol, a unit — not just an icon:
+
+```html
+<div class="input-group">
+  <span>example.com/</span>
+  <input class="ipt" type="text" />
+</div>
+```
 
-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.
+The gap between the control and its adornment is `--input-group-gap`, `0.5rem` by default: the right amount of breathing room for a distinct icon glyph, and too much for text meant to read as glued to the value — `example.com/` followed by a gap reads as a stray space breaking the path apart. Set `--input-group-gap: 0` on the group for a flush affix; icon compositions keep the default unchanged.
 
 ## Toggles
 
-`.checkbox`, `.radio`, and `.switch` accept the same intent classes as
-buttons to set the checked color:
+`.checkbox`, `.radio`, and `.switch` accept the same intent classes as buttons to set the checked color:
 
 | Class                               | Meaning                 |
 | ----------------------------------- | ----------------------- |
@@ -86,39 +81,21 @@ buttons to set the checked color:
 | `.destructive`, `.danger`, `.error` | Destructive color.      |
 | `.info`                             | Info color.             |
 
-All three toggles rest at `.solid`, and **`.ghost` is not supported on any of
-them.** An unchecked ghost toggle is the silhouette every toggle already
-has, and a checked one is a mark on nothing — a tick floating on the page, a
-dot with no ring around it. A container that cascades `.ghost` onto a
-toggle is floored rather than obeyed.
-
-Presentation decides the fill in both states. Being checked lifts the cap
-rather than pinning a fill, so the class still chooses:
+All three toggles rest at `.soft`. Presentation decides the _unchecked_ plate; checked is pinned to one look regardless of which class is on the element, so a checkbox, a radio, and a switch each have a single "on" identity rather than one per presentation:
 
-| Toggle            | unchecked       | checked                         |
-| ----------------- | --------------- | ------------------------------- |
-| `.solid`, default | 20%, switch 40% | 100%, mark in the contrast tone |
-| `.soft`           | 12%             | 12%, mark in the strong tone    |
+| Toggle           | unchecked | checked                                  |
+| ---------------- | --------- | ---------------------------------------- |
+| `.ghost`         | 0%        | 100%, mark in the contrast tone (pinned) |
+| `.soft`, default | 12%       | 100%, mark in the contrast tone (pinned) |
+| `.solid`         | 40%       | 100%, mark in the contrast tone (pinned) |
 
-A checked checkbox and a checked switch cut their mark out of that plate. A
-checked radio thickens its ring to twice the resting line and takes the
-intent whole on it, so `.radio.soft` is the classic ring-and-dot radio and
-`.radio.solid` is a filled circle whose dot stays readable — the mark
-follows the plate rather than being pinned to the intent color.
+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.
 
 ## 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.
+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.
 
-The boundary is the edge axis's, and it splits the same way. A container's
-`.edgeless` is floored, so a toolbar cannot leave a field with no mark of
-where typing goes. `.edgeless` on the control itself is honoured, which is
-how the borderless field is spelled — it does not meet WCAG 1.4.11 at rest,
-so it is opt-in and never a default, and the focus ring still shows.
+The boundary is the edge axis's, and it splits the same way. A container's `.edgeless` is floored, so a toolbar cannot leave a field with no mark of where typing goes. `.edgeless` on the control itself is honoured, which is how the borderless field is spelled — it does not meet WCAG 1.4.11 at rest, so it is opt-in and never a default, and the focus ring still shows.
 
 ```html
 <input class="ipt success" placeholder="Valid" />
@@ -133,11 +110,7 @@ so it is opt-in and never a default, and the focus ring still shows.
 </div>
 ```
 
-`.surface` is a public low-level utility. It is the box every container in
-the package composes: ghost, edged, surface radius, and the two slots only
-a surface resolves — the backdrop filter and the complete surface shadow.
-Use it to paint a container the package does not ship, under whichever
-aesthetic is in scope. Prefer `.card` or `.panel` when they fit.
+`.surface` is a public low-level utility. It is the box every container in the package composes: ghost, edged, surface radius, and the two slots only a surface resolves — the backdrop filter and the complete surface shadow. Use it to paint a container the package does not ship, under whichever aesthetic is in scope. Prefer `.card` or `.panel` when they fit.
 
 ```html
 <div class="surface glass">Blurred, translucent, glass corners</div>
@@ -145,11 +118,7 @@ aesthetic is in scope. Prefer `.card` or `.panel` when they fit.
 <div class="surface primary solid">Any intent, any presentation</div>
 ```
 
-`.text-control` is a public low-level utility from the form entrypoint. It
-provides the shared control dimensions, border, placeholder, focus-visible,
-invalid, and disabled styles composed by `ipt`, `textarea`, and `select`.
-Use it for custom text-like controls; prefer those higher-level utilities
-when they fit.
+`.text-control` is a public low-level utility from the form entrypoint. It provides the shared control dimensions, border, placeholder, focus-visible, invalid, and disabled styles composed by `ipt`, `textarea`, and `select`. Use it for custom text-like controls; prefer those higher-level utilities when they fit.
 
 ## Example
 
@@ -173,5 +142,4 @@ when they fit.
 </label>
 ```
 
-Use labels, `type`, validation logic, `aria-describedby`, and error message
-relationships; see [Accessibility](../accessibility.md).
+Use labels, `type`, validation logic, `aria-describedby`, and error message relationships; see [Accessibility](../accessibility.md).

package/docs/usage/index.md

@@ -1,32 +1,24 @@
 ---
-title: Usage
+title: Overview
 description: Guides for composing axes, theming, customizing, aesthetics, and each component family.
+group: Usage
+order: 3
 ---
 
 # Usage
 
-These guides assume the [Concepts](../concepts.md) mental model: intent,
-presentation, and aesthetic as three independent axes, resolved through
-tokens a component reads.
+These guides assume the [Concepts](../concepts.md) mental model: intent, presentation, and aesthetic as three independent axes, resolved through tokens a component reads.
 
-- [Composing](./composing.md): Combining the three axes on a component, the
-  axis-support matrix, and elevation modifiers.
+- [Composing](./composing.md): Combining the three axes on a component, the axis-support matrix, and elevation modifiers.
 - [Theming](./theming.md): The color, intent, and foundation token reference.
-- [Customizing](./customizing.md): The presentation and material token
-  reference, aesthetic knobs, and defining a custom intent.
-- [Aesthetics](./aesthetics.md): Each shipped aesthetic in depth, including
-  its documented exceptions.
+- [Customizing](./customizing.md): The presentation and material token reference, aesthetic knobs, and defining a custom intent.
+- [Aesthetics](./aesthetics.md): Each shipped aesthetic in depth, including its documented exceptions.
 - [Buttons](./buttons.md)
 - [Forms](./forms.md)
 - [Feedback](./feedback.md)
 - [Tooltips](./tooltips.md)
-- [Content and layout](./content-and-layout.md): Layout helpers, tables,
-  quotes, code, surfaces, and typography utilities.
+- [Content and layout](./content-and-layout.md): Layout helpers, tables, quotes, code, surfaces, and typography utilities.
 
 ## Supported surface
 
-A class, component, and axis combination is supported when this documentation
-describes it and the package playground demonstrates it. Undocumented and
-undemonstrated combinations may still produce CSS, but are not maintained
-behavior. Playground variant matrices are the exhaustive demonstrations; small
-examples elsewhere illustrate usage without widening that contract.
+A class, component, and axis combination is supported when this documentation describes it and the package playground demonstrates it. Undocumented and undemonstrated combinations may still produce CSS, but are not maintained behavior. Playground variant matrices are the exhaustive demonstrations; small examples elsewhere illustrate usage without widening that contract.

package/docs/usage/theming.md

@@ -1,20 +1,18 @@
 ---
 title: Theming
 description: The color, intent, and foundation token reference.
+order: 2
 ---
 
 # Theming
 
-Color tokens are how you restyle the palette; see
-[Concepts → Theme selection](../concepts.md#theme-selection) for how a theme
-is chosen. Intent tokens are how a component reads that palette once an
-intent class is applied. Foundation tokens are the shared layout, shape, and
-motion defaults underneath everything.
+Color tokens are how you restyle the palette; see [Concepts → Theme selection](../concepts.md#theme-selection) for how a theme is chosen. Intent tokens are how a component reads that palette once an intent class is applied. Foundation tokens are the shared layout, shape, and motion defaults underneath everything.
 
 ## Color tokens
 
-Each color token holds both of its theme values at once through
-`light-dark()`, and the element's `color-scheme` picks one.
+Each color token holds both of its theme values at once through `light-dark()`, and the element's `color-scheme` picks one.
+
+Every row is an override point: set it on `:root` to retheme globally, or on any element to retheme that subtree. The `-hover`, `-subtle`, `-strong`, and `-contrast` rows are companion tones wired into the intent slots, so overriding a base color such as `--color-primary` on its own does not shift its companions — retheme the whole family. The `text` family has no `-subtle` row: the neutral intent draws its subtle tone from `--color-surface`.
 
 ```html
 <section data-theme="dark">
@@ -44,7 +42,6 @@ Each color token holds both of its theme values at once through
 | `--color-text-secondary`       | Secondary text color.                                                                                             |
 | `--color-text-contrast`        | Readable color on top of a full fill of `--color-text`. A checked toggle prints it.                               |
 | `--color-text-hover`           | Text hover state.                                                                                                 |
-| `--color-text-subtle`          | Low-emphasis companion tone for text. Use as soft surface or subtle background.                                   |
 | `--color-text-strong`          | High-emphasis companion tone for text. Use as readable text, icon, or border on subtle surfaces.                  |
 | `--color-tooltip`              | Tooltip bubble plate with no intent. Chosen per theme rather than derived: near-white in light, mid grey in dark. |
 | `--color-tooltip-contrast`     | Ink on `--color-tooltip`.                                                                                         |
@@ -69,20 +66,11 @@ Each color token holds both of its theme values at once through
 | `--color-info-subtle`          | Low-emphasis companion tone for info.                                                                             |
 | `--color-info-strong`          | High-emphasis companion tone for info.                                                                            |
 
-> **Intent token contract**: color intent tokens own meaning and tone
-> variants. Intent classes map one family onto the shared intent slots below,
-> and presentation classes decide how much of it a component shows. Theme
-> changes belong in token values, not broad component-level theme checks.
-> Component-level theme handling should exist only when a component has an
-> internal structure that cannot be expressed through the token palette
-> alone.
+> **Intent token contract**: color intent tokens own meaning and tone variants. Intent classes map one family onto the shared intent slots below, and presentation classes decide how much of it a component shows. Theme changes belong in token values, not broad component-level theme checks. Component-level theme handling should exist only when a component has an internal structure that cannot be expressed through the token palette alone.
 
 ## Intent tokens
 
-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.
+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                                                                               |
 | ------------------- | ------------------------------------------------------------------------------------- |
@@ -94,49 +82,19 @@ changes.
 | `--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.  |
 
-`--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.
-
-The strong tone has to stay recognisably its own hue, not just readable. On a
-dark page the `-100` shade of every family is a pale tint that carries almost
-no chroma at small sizes: a soft success badge and a soft destructive one
-printed labels that both read white, and a soft radio's dot stopped matching
-the ring around it. The dark tones are `-300` for that reason, and the tinted
-grounds under them are `-900` so there is room — measured at 5.0:1 or better
-everywhere a partial fill prints text, and past 9:1 on the page.
-
-`--intent-border` exists because a neutral border must stay the quiet border
-gray rather than the text color. Everything that draws a line reads it:
-control borders, table rules, dividers, key caps, and quote bars.
-
-`--intent-fill-max` exists for the neutral intent, whose color is the page's
-own ink. Every other intent is a hue, legible pale at 12% and saturated at
-100%; a grey filled to 100% is a black or white slab, which is the loudest
-thing on the page and the wrong look for the intent that means _nothing in
-particular_. Neutral stops at `20%`, so `.solid` gives it a quiet plate that
-still reads as a step past `.soft`. Hover adds its step on top of the cap, so
-a capped fill still deepens under the pointer.
-
-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.
-
-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%.
+`--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.
+
+The strong tone has to stay recognisably its own hue, not just readable. On a dark page the `-100` shade of every family is a pale tint that carries almost no chroma at small sizes: a soft success badge and a soft destructive one printed labels that both read white, and a soft radio's dot stopped matching the ring around it. The dark tones are `-300` for that reason, and the tinted grounds under them are `-900` so there is room — measured at 5.0:1 or better everywhere a partial fill prints text, and past 9:1 on the page.
+
+`--intent-border` exists because a neutral border must stay the quiet border gray rather than the text color. Everything that draws a line reads it: control borders, table rules, dividers, key caps, and quote bars.
+
+`--intent-fill-max` exists for the neutral intent, whose color is the page's own ink. Every other intent is a hue, legible pale at 12% and saturated at 100%; a grey filled to 100% is a black or white slab, which is the loudest thing on the page and the wrong look for the intent that means _nothing in particular_. Neutral stops at `20%`, so `.solid` gives it a quiet plate that still reads as a step past `.soft`. Hover adds its step on top of the cap, so a capped fill still deepens under the pointer.
+
+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.
+
+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%.
 
 ```css
 .brand {
@@ -151,29 +109,16 @@ intent that omits the cap fills to 20% of its color instead of 100%.
 ```
 
 ```html
-<button class="btn brand">Custom intent</button>
-<span class="badge brand soft">Works everywhere</span>
+<button class="btn brand">Custom intent</button> <span class="badge brand soft">Works everywhere</span>
 ```
 
-> **Intent does not cascade.** Components reset these slots to the text
-> palette at their own root, so a `.success` container never recolors a
-> nested destructive button. Put the intent class on the element that shows
-> the intent.
+> **Intent does not cascade.** Components reset these slots to the text palette at their own root, so a `.success` container never recolors a nested destructive button. Put the intent class on the element that shows the intent.
 
 ## Foundation tokens
 
-Foundation tokens are not aliases for one color. They define layout, shape,
-motion, focus, depth, and layering behavior used by helper classes.
+Foundation tokens are not aliases for one color. They define layout, shape, motion, focus, depth, and layering behavior used by helper classes.
 
-The four `--elevation-*` values below are raw shadows for elements you style
-yourself. They are a separate thing from `.elevation-none`/`.elevation-sm`/
-`.elevation-md` (aliased as `.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.
+The four `--elevation-*` values below are raw shadows for elements you style yourself. They are a separate thing from `.elevation-none`/`.elevation-sm`/ `.elevation-md` (aliased as `.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                                                                 |
 | -------------------------- | ----------------------------------------------------------------------- |
@@ -206,5 +151,4 @@ paint identically.
 | `--breakpoint-xs`          | Extra-small Tailwind responsive breakpoint.                             |
 | `--breakpoint-2xl`         | Extended large 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.
+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

@@ -1,45 +1,65 @@
 ---
 title: Tooltips
-description: Tooltip host classes and positioning attributes.
+description: Tooltip composition classes and positioning attributes.
+order: 8
 ---
 
 # Tooltips
 
-| Class or Attribute                      | Purpose                                                        |
-| --------------------------------------- | -------------------------------------------------------------- |
-| `.tooltip`                              | Tooltip host. Uses `data-tooltip` as pseudo-element content.   |
-| `.tooltip.tooltip-icon`                 | Circular icon-style tooltip host.                              |
-| `[data-tooltip-position="top"]`         | Positions tooltip above host.                                  |
-| `[data-tooltip-position="bottom"]`      | Positions tooltip below host.                                  |
-| `[data-tooltip-position="left"]`        | Positions tooltip left of host.                                |
-| `[data-tooltip-position="right"]`       | Positions tooltip right of host.                               |
-| No `data-tooltip-position`              | Defaults to top placement.                                     |
-| `[data-state="open"]`                   | Shows tooltip without hover.                                   |
-| `.tooltip.raised` / `.tooltip.floating` | Adds one or two units of depth. The bubble is flat by default. |
-
-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, including the
-pseudo-element itself.
-
-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 — `.tooltip.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.
+| 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.
+
+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.
+
+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.
+
+## Example
 
 ```html
-<button
-  class="tooltip tooltip-icon"
-  data-tooltip="More details"
-  data-tooltip-position="right"
-  aria-label="More details"
->
-  ?
-</button>
+<span class="tooltip">
+  <button aria-describedby="status-bubble">Status</button>
+  <span class="tooltip-bubble" role="tooltip" id="status-bubble">Saved 2 minutes ago</span>
+</span>
+
+<span class="tooltip" data-tooltip-position="bottom">
+  <button aria-describedby="docs-bubble">Docs</button>
+  <span class="tooltip-bubble" role="tooltip" id="docs-bubble">Opens in a new tab</span>
+</span>
+
+<span class="tooltip">
+  <button class="btn primary" aria-describedby="deploy-bubble">Deploy</button>
+  <span class="tooltip-bubble raised primary" role="tooltip" id="deploy-bubble">Primary intent, lifted a step</span>
+</span>
+
+<span class="tooltip" data-state="open">
+  <span aria-describedby="pinned-bubble">Pinned</span>
+  <span class="tooltip-bubble" role="tooltip" id="pinned-bubble">Always visible, no hover needed</span>
+</span>
+
+<span class="tooltip" data-tooltip-position="right">
+  <span class="tooltip-icon" tabindex="0" aria-label="More details" aria-describedby="icon-bubble">?</span>
+  <span class="tooltip-bubble" role="tooltip" id="icon-bubble">More details</span>
+</span>
 ```
 
-CSS pseudo-element tooltips are presentational. They are not a complete
-accessible tooltip implementation by themselves — provide accessible
-names/descriptions outside the CSS; see [Accessibility](../accessibility.md).
+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.
+
+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).
+
+Next: [Content and layout](./content-and-layout.md) covers layout helpers, content chips and tables, surfaces, and typography utilities.