@codenhub/styles 0.1.0 → 0.1.1

package/docs/usage/feedback.md

@@ -1,6 +1,7 @@
 ---
 title: Feedback
 description: Alert, badge, loader, skeleton, and progress class reference.
+order: 7
 ---
 
 # Feedback
@@ -32,11 +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 is part of focused loader, button, and components imports; it does not depend on the global reset. See [Accessibility](../accessibility.md).
 
 Loader size modifiers:
 
@@ -46,27 +43,17 @@ Loader size modifiers:
 | `.sm`    | Small (`1.5rem`). |
 | `.lg`    | Large (`2.5rem`). |
 
-Alerts, badges, progress bars, skeletons, and loaders accept `.primary`,
-`.secondary`, `.success`, `.warning`, `.destructive`, `.danger`, `.error`,
-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`, `.danger`, `.error`, and `.info`. Without an intent, they use the text palette, except `.loader`, which keeps `currentColor` so it matches whatever content surrounds it.
 
-Skeletons, loaders, progress bars, and dividers are indicators. They read
-intent but ignore fill and edge [presentation](./composing.md#presentation).
+Skeletons, loaders, progress bars, and dividers are indicators. They read intent but ignore fill and edge [presentation](./composing.md#presentation).
 
 ```html
-<span class="loader success" aria-hidden="true"></span>
-<span class="skeleton info"></span>
+<span class="loader success" aria-hidden="true"></span> <span class="skeleton info"></span>
 ```
 
-`.icon` is a subclass of `.alert`. When applied as `.alert.icon`, it
-increases the left padding and adds an embedded SVG. Success, warning, and
-destructive intents use corresponding symbols; other intents use the
-information symbol.
+`.icon` is a subclass of `.alert`. When applied as `.alert.icon`, it increases the left padding and adds an embedded SVG. Success, warning, and destructive intents use corresponding symbols; other intents use the information symbol.
 
-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.
+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.
 
 ## Example
 
@@ -84,34 +71,9 @@ mixed intent border.
 <span class="loader bars-wave" aria-hidden="true"></span>
 <span class="loader pulse-ring sm" aria-hidden="true"></span>
 <span class="loader dots-grow lg" aria-hidden="true"></span>
-<div
-  class="progress"
-  role="progressbar"
-  aria-label="Upload progress"
-  aria-valuemin="0"
-  aria-valuemax="100"
-  aria-valuenow="64"
-  style="--progress-value: 64%"
-></div>
-<div
-  class="progress secondary active"
-  role="progressbar"
-  aria-label="Upload progress"
-  aria-valuemin="0"
-  aria-valuemax="100"
-  aria-valuenow="64"
-  style="--progress-value: 64%"
-></div>
-<div
-  class="progress info indeterminate"
-  role="progressbar"
-  aria-label="Loading"
-  aria-valuemin="0"
-  aria-valuemax="100"
-></div>
+<div class="progress" role="progressbar" aria-label="Upload progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="64" style="--progress-value: 64%"></div>
+<div class="progress secondary active" role="progressbar" aria-label="Upload progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="64" style="--progress-value: 64%"></div>
+<div class="progress info indeterminate" role="progressbar" aria-label="Loading" aria-valuemin="0" aria-valuemax="100"></div>
 ```
 
-Add `role="status"` or `role="alert"` to alerts based on announcement
-urgency, mark decorative loading visuals with `aria-hidden="true"`, and use
-semantic progress elements or ARIA values when numeric progress must be
-announced; see [Accessibility](../accessibility.md).
+Add `role="status"` or `role="alert"` to alerts based on announcement urgency, mark decorative loading visuals with `aria-hidden="true"`, and use semantic progress elements or ARIA values when numeric progress must be announced; see [Accessibility](../accessibility.md).

package/docs/usage/forms.md

@@ -1,6 +1,7 @@
 ---
 title: Forms
 description: Field, text control, and toggle class reference.
+order: 6
 ---
 
 # Forms
@@ -25,19 +26,11 @@ description: Field, text control, and toggle class reference.
 
 ## 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 and the alert icons in [Feedback](./feedback.md#example): those are small, fixed, built-in glyphs — not a per-input icon system — and aren't affected by this change.
+
+`.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,13 @@ 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.
+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.
 
 ## 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 +70,22 @@ 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.
+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:
+Presentation decides the fill in both states. Being checked lifts the cap rather than pinning a fill, so the class still chooses:
 
 | Toggle            | unchecked       | checked                         |
 | ----------------- | --------------- | ------------------------------- |
 | `.solid`, default | 20%, switch 40% | 100%, mark in the contrast tone |
 | `.soft`           | 12%             | 12%, mark in the strong tone    |
 
-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 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.
 
 ## 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 +100,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 +108,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 +132,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,6 +1,7 @@
 ---
 title: Tooltips
 description: Tooltip host classes and positioning attributes.
+order: 8
 ---
 
 # Tooltips
@@ -17,29 +18,22 @@ description: Tooltip host classes and positioning attributes.
 | `[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.
+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.
+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.
+
+Intent works on a tooltip the same way it works on a filled component: `.tooltip.primary` fills the bubble with the primary color, black text on a light page and white on a dark one; `.tooltip.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 — near-white in light, mid-grey in dark; 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>
+<button class="tooltip" data-tooltip="Saved 2 minutes ago">Status</button>
+<button class="tooltip" data-tooltip="Opens in a new tab" data-tooltip-position="bottom">Docs</button>
+<button class="tooltip primary raised" data-tooltip="Primary intent, lifted a step">Deploy</button>
+<button class="tooltip" data-tooltip="Always visible, no hover needed" data-state="open">Pinned</button>
+<button class="tooltip tooltip-icon" data-tooltip="More details" data-tooltip-position="right" aria-label="More details">?</button>
 ```
 
-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 hosts with default (top) and explicit bottom placement. The third combines an intent with `.raised` to show they compose freely — the intent decides the bubble's fill, `.raised` decides whether it casts depth. The fourth uses `data-state="open"` 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 is the circular icon variant.
+
+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).