@uncinq/css-components 1.16.2 → 1.16.3

package/docs/overlays/drawer.md

@@ -0,0 +1,58 @@
+---
+isIndex: false
+title: Drawer
+description: The edge-pinned panel configuration and its four position variants.
+weight: 3
+icon: layout-sidebar-reverse
+---
+
+A panel sliding in from an edge. Like [`.modal`](../modal/), the class is **pure configuration**: `drawer.css` declares nothing but `--panel-*` tokens, and [`components/panel.css`](../panel/) owns every rule.
+
+```html
+<div class="drawer drawer-end" id="menu" popover="auto" role="dialog" aria-labelledby="menuLabel">
+  <div class="header">
+    <p class="title" id="menuLabel">Menu</p>
+    <button class="btn-close js-dialog-close" aria-label="Close"></button>
+  </div>
+  <div class="content">
+    <ul class="nav">...</ul>
+  </div>
+</div>
+```
+
+**A position variant is required.** `.drawer` on its own pins nothing: `--drawer-start` and its siblings have no value until one of the four variants sets them.
+
+## Position variants
+
+| Class | Edge | Slides from |
+| --- | --- | --- |
+| `.drawer-start` | Inline start, left in a left-to-right document | `translateX(-100%)` |
+| `.drawer-end` | Inline end | `translateX(100%)` |
+| `.drawer-top` | Top | `translateY(-100%)` |
+| `.drawer-bottom` | Bottom | `translateY(100%)` |
+
+Each sets three things: which two insets are `0`, which two are `auto`, and the translate the panel animates from.
+
+The start and end variants leave `--panel-inline-size: var(--drawer-width)` and let the block axis stretch. The top and bottom variants swap that, taking `--panel-block-size: var(--drawer-height)` and `--panel-inline-size: auto`.
+
+## Why the margin stays at 0
+
+```css
+/* two edges pinned, the opposite ones auto */
+--panel-inset-block:  var(--drawer-top)   var(--drawer-bottom);
+--panel-inset-inline: var(--drawer-start) var(--drawer-end);
+```
+
+A `<dialog>` opened with `showModal()` is centred by user agent rules that only apply when the margins are `auto`. The drawer leaves `--panel-margin` at its `0` default precisely so those rules do not fire, which is what lets the same file work on a `<dialog>` and on a popover.
+
+## It only slides, it does not fade
+
+Unlike a modal, the drawer sets no `--panel-opacity`, so the token keeps its `1` default. The closed state is a pure translate, and the `@starting-style` block in `panel.css` replays it. That is the whole difference in the two animations.
+
+## The case for `popover` over `<dialog>`
+
+A drawer is the usual host for [`.panel-inline-*`](../panel/#inline-variants): a menu, a filters sidebar or a table of contents that is an overlay on mobile and a column on desktop. A `<dialog>` is exposed as `role="dialog"` even while it is styled as a column, so use `popover="auto"` and let your script set the role only while the panel is actually open.
+
+## Sizing
+
+`--drawer-width` and `--drawer-height` are the two dimensions. `--panel-max-inline-size` is pinned to `100%`, so a drawer wider than the viewport is clamped rather than pushed off screen.

package/docs/overlays/dropdown.md

@@ -0,0 +1,87 @@
+---
+isIndex: false
+title: Dropdown
+description: A contextual menu positioned against its trigger, with a three-class transition contract.
+weight: 4
+icon: caret-down-square
+---
+
+A contextual menu. Unlike [`.modal`](../modal/) and [`.drawer`](../drawer/), it is not a panel: it is absolutely positioned against its trigger, stays out of the top layer, and has a tighter JavaScript contract because it animates in both directions.
+
+```html
+<div class="dropdown">
+  <button class="dropdown-toggle js-dropdown-toggle" aria-expanded="false">Label</button>
+  <ul class="dropdown-menu">
+    <li><a href="#">Item</a></li>
+    <li><hr></li>
+    <li><a href="#">Item</a></li>
+  </ul>
+</div>
+```
+
+## Three classes, three jobs
+
+| Class | Role |
+| --- | --- |
+| `.dropdown` | The positioning context, `inline-flex` and `position: relative` |
+| `.dropdown-toggle` | The trigger, styled: transparent, with a chevron on `::after` |
+| `.dropdown-menu` | The menu panel, absolutely positioned under the trigger |
+
+The trigger needs **both** `.dropdown-toggle` for the styling and `.js-dropdown-toggle` for the script. They are separate on purpose, so a trigger can be a `.btn`, a [`.btn-share`](../../buttons/btn-share/) or a plain button and still be found by the same script.
+
+**`.js-dropdown-toggle`'s next element sibling must be the `.dropdown-menu`.** That is how the script pairs the two; there is no `data-target` here.
+
+## Items are styled by element, not by class
+
+`.dropdown-menu` styles `li a` directly. There is no `.dropdown-item` rule in this package, and no `.dropdown-divider` rule either: a separator is a plain `<hr>` taking whatever [css-base](../../../css-base/base/) gives it. Adding those classes to your markup is harmless but changes nothing.
+
+Links get `white-space: nowrap`, so the menu widens to its longest item rather than wrapping. `--dropdown-min-width` sets the floor.
+
+## The chevron
+
+Drawn on `::after` as a mask from `--dropdown-icon`, and rotated by the trigger's own ARIA state:
+
+```css
+&[aria-expanded="true"]::after { rotate: 180deg; }
+```
+
+So the arrow follows `aria-expanded` rather than a state class. If your script forgets to update the attribute, the menu opens with the chevron still pointing down, which makes the omission visible during development rather than only to screen reader users.
+
+The trigger also lays a transparent `::before` over its whole positioning context, widening the click target beyond the text.
+
+## The three-class transition contract
+
+The script toggles three classes on the **menu**, in this sequence:
+
+| Class | Meaning | Effect |
+| --- | --- | --- |
+| `.showing` | Opening transition has started | Visible and clickable, still at its closed opacity and offset |
+| `.show` | Fully open | Opacity 1, translate 0 |
+| `.hiding` | Closing transition has started | Still visible while it animates out |
+
+```css
+&.show, &.showing, &.hiding { pointer-events: auto; visibility: visible; }
+&.show                      { opacity: 1; transform: translateY(0); }
+```
+
+The three exist so the menu can animate **out** before being removed from the flow. A single `.show` class would make the closing transition impossible: removing it would snap `visibility` to `hidden` on the same frame as the opacity change, and nothing would be seen.
+
+The script must also keep `aria-expanded` on the toggle in sync with the state.
+
+Transitions are inside `@media (prefers-reduced-motion: no-preference)`, so the three classes still work with motion disabled; they simply take effect instantly.
+
+## Alignment
+
+`.dropdown-menu-end` aligns the menu to the inline end of its trigger rather than the start. It is the only variant, and it goes on the menu, not on the container.
+
+```html
+<ul class="dropdown-menu dropdown-menu-end">...</ul>
+```
+
+## Inside a navigation
+
+[`.nav`](../../navigation/nav/) restyles `.dropdown-toggle` to take the navigation's own text colour, so a dropdown in a header menu matches the links beside it without a variant class.
+
+## It uses `z-index`, not the top layer
+
+`.dropdown-menu` is positioned with `z-index: var(--dropdown-z-index)` inside its own stacking context. Unlike a panel, it can therefore be clipped by an ancestor with `overflow: hidden` or trapped under a sticky header. If that happens, the fix is the ancestor's overflow, not a higher `z-index`.

package/docs/overlays/modal.md

@@ -0,0 +1,75 @@
+---
+isIndex: false
+title: Modal
+description: The centred panel configuration, and how it centres and shrinks to its content at once.
+weight: 2
+icon: window
+---
+
+A centred panel. The class is **pure configuration**: `modal.css` declares nothing but `--panel-*` tokens, and [`components/panel.css`](../panel/) owns every rule.
+
+```html
+<dialog class="modal" id="contact" aria-labelledby="contactLabel">
+  <div class="header">
+    <p class="title" id="contactLabel">Contact</p>
+    <button class="btn-close js-dialog-close" aria-label="Close"></button>
+  </div>
+  <div class="content">...</div>
+  <div class="footer">
+    <button class="btn btn-secondary js-dialog-close">Cancel</button>
+    <button class="btn" type="submit">Send</button>
+  </div>
+</dialog>
+```
+
+Works on a `<dialog>` opened with `showModal()` and on any element carrying `popover="auto"`, opened with `showPopover()`. Reach for the second form only when the panel is not always modal, typically when [`.panel-inline-*`](../panel/#inline-variants) turns it into a region of the page above a breakpoint.
+
+## Sizing
+
+Override `--modal-max-width` on the element:
+
+```html
+<dialog class="modal" style="--modal-max-width: 40rem">...</dialog>
+```
+
+or globally, for every modal on the site:
+
+```css
+@layer components {
+  .modal { --modal-max-width: 40rem; }
+}
+```
+
+`--modal-max-height`, `--modal-min-height` and `--modal-margin` are the other three sizing tokens. All `--modal-*` names are the public API; `--panel-*` is the internal one.
+
+## Why the height is `fit-content` and not `auto`
+
+The centring is done with insets and auto margins:
+
+```css
+--panel-block-size: fit-content;
+--panel-inset-block: 0;
+--panel-inset-inline: 0;
+--panel-margin: auto;
+```
+
+With both block insets set, an `auto` height resolves to fill the gap between them, and the auto margins then collapse to `0`. The panel would neither centre nor shrink to its content. `fit-content` is what keeps both behaviours, and it is the same reason the user agent dialog stylesheet uses it.
+
+## Why there is no mobile breakpoint
+
+The maximum is a `min()` rather than a media query:
+
+```css
+--panel-max-block-size: min(var(--modal-max-height), 100% - var(--modal-margin) * 2);
+--panel-max-inline-size: min(var(--modal-max-width),  100% - var(--modal-margin) * 2);
+```
+
+So the panel always keeps `--modal-margin` clear of the viewport edges, whatever the maximum is set to. Raising `--modal-max-width` on a narrow screen changes nothing, which is why a modal needs no responsive variant.
+
+## Opening animation
+
+`--panel-opacity: 0` and `--panel-translate: var(--modal-translate)` describe the **closed** state, so a modal both fades and moves on the way in. A drawer leaves the opacity alone and only slides. Both are replayed by the `@starting-style` block in `panel.css`, and both are skipped under `prefers-reduced-motion: reduce`.
+
+## Accessibility
+
+Point `aria-labelledby` at the `id` of the title in the header. A `<dialog>` opened with `showModal()` gets the focus trap, Escape and inertness from the browser; the `popover` path gets light dismiss and Escape but no role, which your script has to supply.

package/docs/overlays/panel.md

@@ -0,0 +1,159 @@
+---
+isIndex: false
+title: Panel
+description: The shared skeleton behind .modal and .drawer, the two opening strategies, the inline variants and the backdrop.
+weight: 1
+icon: layout-sidebar
+---
+
+`components/panel.css` is the largest file in the package and the only one with no class of its own. It owns every rule behind [`.modal`](../modal/) and [`.drawer`](../drawer/), which contribute nothing but `--panel-*` values.
+
+There is **no `.panel` class.** The selectors read `:where(.modal, .drawer)`, so the skeleton arrives with either variant class.
+
+## Structure
+
+```html
+<dialog class="modal" id="contact" aria-labelledby="contactLabel">
+  <div class="header">
+    <p class="title" id="contactLabel">Contact</p>
+    <button class="btn-close js-dialog-close" aria-label="Close"></button>
+  </div>
+  <div class="content">...</div>
+  <div class="footer">...</div>
+</dialog>
+```
+
+All three sections are optional, and all three are matched as **direct children** (`& > .header`).
+
+| Section | Behaviour |
+| --- | --- |
+| `.header` | Fixed height, title and close button pushed apart, bottom border |
+| `.content` | Takes the remaining height and scrolls, with `overscroll-behavior: contain` |
+| `.footer` | Fixed height, top border, stacked on mobile and right-aligned from `--sm` up |
+
+The panel itself carries **no padding**. It lives on the three sections instead, so that a click on the panel element is always a click on the backdrop rather than on a transparent margin.
+
+## Two ways to open a panel
+
+**The tag picks the strategy, not the class.** Either variant works both ways.
+
+### `<dialog>` with `showModal()`
+
+The browser handles Escape, the focus trap and making the rest of the page inert. You get `[open]`, the native `::backdrop` and the top layer for free.
+
+This is the right choice when the panel is **always** a dialog.
+
+### `popover="auto"` with `showPopover()`
+
+Same top layer, same native `::backdrop`, but the element carries no implicit role.
+
+Use this when the panel becomes a static region of the page above a breakpoint, which is what the [inline variants](#inline-variants) do. The reason is an accessibility one: a `<dialog>` is exposed as `role="dialog"` even when it is only styled as a sidebar, whereas a script can set that role solely while the panel is actually open.
+
+## How open and closed are expressed
+
+`display` is only ever declared on a state selector, never on the panel itself:
+
+```css
+:where(.modal, .drawer):not(:where([open], :popover-open)) { display: none; }
+:where(.modal, .drawer):is([open], :popover-open)         { display: flex; opacity: 1; transform: none; }
+```
+
+Declaring `display` on the panel would beat the user agent rule that hides a closed `<dialog>`, and a closed dialog would render.
+
+The two selectors differ deliberately. The closed rule uses `:where()` throughout and carries **zero specificity**. The open rule uses `:is()` on the state, giving it 0,1,0, which is what lets it beat the unstyled base rule that comes later in the file on specificity rather than on source order, while still leaving a host component such as `.toc .drawer` (0,2,0) room to override without escalating.
+
+Everything else about the closed state lives in tokens: `--panel-opacity` and `--panel-translate` are the values the panel animates **from**, which is why a drawer only slides while a modal also fades.
+
+The entry transition needs those values spelled out a second time, because opening is a discrete `display` change:
+
+```css
+@starting-style {
+  :where(.modal, .drawer):is([open], :popover-open) {
+    opacity: var(--panel-opacity, 1);
+    transform: var(--panel-translate, none);
+  }
+}
+```
+
+`transition-behavior: allow-discrete` keeps the panel displayed while it transitions out, and keeps a `<dialog>` in the top layer until the transition ends.
+
+## The backdrop
+
+Both opening paths put the panel in the top layer, so both get the native `::backdrop`, which inherits from the panel and therefore reads the same `--panel-*` tokens. **No backdrop node is ever injected, and no `z-index` is involved.**
+
+This is the reason the class-driven path uses `popover` rather than a plain element. A backdrop placed outside the panel sits in the root stacking context while the panel stays confined to its nearest stacking ancestor, a sticky sidebar wrapper or a sticky header, so the veil paints over the panel and no `z-index` can lift it out. Placing the backdrop next to the panel only moves the problem: it then inherits the same confinement, and anything painted later shows through it. The top layer removes the question entirely, which is exactly what it exists for.
+
+Page scroll is locked from the panel's own state, with no class on `<body>` to manage:
+
+```css
+body:has(:where(.modal, .drawer):where([open], :popover-open)) { overflow: hidden; }
+```
+
+## Inline variants
+
+`.panel-inline-*` turns a panel into an ordinary region of the page from a breakpoint upwards, while it stays an overlay below.
+
+| Class | Becomes inline at |
+| --- | --- |
+| `.panel-inline-sm` | `--sm`, 768px |
+| `.panel-inline-md` | `--md`, 1024px |
+| `.panel-inline-lg` | `--lg`, 1440px |
+| `.panel-inline-xl` | `--xl`, 1600px |
+
+This is the case that calls for `popover="auto"` rather than `<dialog>`. A filters sidebar that is a drawer on mobile and a column on desktop should not announce itself as a dialog while it is a column. **The panel must not be a `<dialog>` when one of these is used.**
+
+Above the breakpoint the variant neutralises the whole panel rule: position, insets, size, shadow, overflow, transition, and it hides `.header` and `.footer` while flattening `.content`.
+
+### Colours go too, not just geometry
+
+A region of the page carries none of the panel's chrome, so the variant hands five custom properties back to the parent:
+
+```css
+--color-link: inherit;
+--color-link-active: inherit;
+--color-link-hover: inherit;
+--nav-color-text: inherit;
+--nav-color-text-active: inherit;
+```
+
+`inherit` on a custom property is what hands it back, and it has to be done token by token. Resetting the `--panel-color-text-*` tokens they derive from would make them invalid at computed-value time rather than page-valued, and every link would fall back to the surrounding text colour instead of the site's link colour.
+
+If you add a property to the panel rule, neutralise it in all four variants. That is the maintenance cost of the pattern, and the reason the block is written once per breakpoint rather than derived.
+
+## Hiding the trigger
+
+`.panel-trigger-*` is the companion, applied to the **trigger button** rather than to the panel. It hides the trigger at the breakpoint where the panel stops being an overlay.
+
+| Class | Trigger hidden from |
+| --- | --- |
+| `.panel-trigger-sm` | `--sm`, 768px |
+| `.panel-trigger-md` | `--md`, 1024px |
+| `.panel-trigger-lg` | `--lg`, 1440px |
+| `.panel-trigger-xl` | `--xl`, 1600px |
+
+Pair the suffixes: a panel carrying `.panel-inline-md` needs its button carrying `.panel-trigger-md`, otherwise a button that opens nothing remains on screen at desktop width.
+
+The reason this is a second class rather than something CSS derives on its own is worth knowing, because it looks like a redundancy. Nothing structurally connects a trigger to its panel: the only link is `data-target` matching an `id`, and no selector can compare two attribute values. A positional rule would work only until somebody moved the markup, and a filter button typically lives in the page heading rather than beside the panel it opens. In practice both classes come from the same configuration value, so the pair cannot disagree.
+
+## The JavaScript contract
+
+This package ships no JavaScript. `.modal` and `.drawer` expect a script that provides:
+
+| Hook | Role |
+| --- | --- |
+| `.js-dialog-toggle[data-target="#id"]` | Opens the panel it points at |
+| `.js-dialog-close` | Any element inside the panel that closes it |
+
+Closing must also work on Escape and on a click outside. With `<dialog>` and `showModal()` the browser already does both. With `popover="auto"` the platform handles light dismiss and Escape too, so in practice the script mainly manages the role and the open call.
+
+One case CSS cannot cover: a panel carrying a `.panel-inline-*` class that is **open** when the viewport crosses the breakpoint. The script has to close it, because nothing in CSS releases the backdrop, the scroll lock and the inert background.
+
+## Source order, not specificity
+
+Most of this file is wrapped in `:where()` and carries no specificity at all, which is what lets `.modal`, `.drawer` and your own overrides win without escalating:
+
+```css
+.modal { border-radius: 0; }   /* enough, no !important needed */
+```
+
+The `.panel-inline-*` variants are the exception. They are plain class selectors that must beat `.modal` and `.drawer`, and they do so on **source order**. Alphabetical import order already places `panel.css` after `drawer.css` and `modal.css`; keep it that way if you import files individually. See [Cascade layers](../../cascade-layers/).

package/docs/utilities/_index.md

@@ -0,0 +1,21 @@
+---
+isIndex: false
+title: Utilities
+description: The one utility this package ships, and why it is a utility rather than a component rule.
+weight: 8
+icon: tools
+---
+
+One utility, in its own layer.
+
+| Page | Class | Purpose |
+| --- | --- | --- |
+| [Scrollsnap](scrollsnap/) | `.scrollsnap` | Turns a grid into a horizontal snap carousel |
+
+## Why it is not a component
+
+`.scrollsnap` changes the `grid-template-columns` that a component such as [`.items`](../content/items/) declares for itself in `@layer components`. A later layer beats an earlier one regardless of specificity, so putting it in `@layer utilities` is what lets a single class opt an existing component into carousel behaviour without rewriting the component.
+
+That is also the test for anything else that might land here: a utility is a **modifier applied to something else**, not a thing of its own. If it has its own markup, it is a component.
+
+`@layer utilities` must come last in your layer declaration for this to hold. See [Cascade layers](../cascade-layers/).

package/docs/{utilities.md → utilities/scrollsnap.md}

@@ -1,13 +1,11 @@
 ---
 isIndex: false
-title: Utilities
-description: The .scrollsnap utility, which turns a grid into a horizontal snap carousel below a breakpoint.
-weight: 8
-icon: tools
+title: Scrollsnap
+description: Turns a grid into a horizontal snap carousel below a breakpoint, bleeding into the gutter so the next item peeks in.
+weight: 1
+icon: arrow-left-right
 ---
 
-## `.scrollsnap`
-
 Turns a grid into a horizontal carousel with snap points. Items keep their own width, the grid stops wrapping, and the row scrolls sideways, bleeding into the gutter so the next item peeks in.
 
 ```html
@@ -34,9 +32,22 @@ This is the one thing to get right, and it reads backwards from most responsive
 
 **The suffix names the rung where the carousel STOPS and the grid comes back.** `.scrollsnap-md` is a carousel on mobile and tablet, and a grid from 1024px up.
 
-## Why it is a utility
+## How a variant hands the grid back
+
+Above its rung, every property is set to `revert-layer` rather than to a second set of values:
+
+```css
+@media (--md) {
+  .scrollsnap-md {
+    grid-auto-flow: revert-layer;
+    grid-template-columns: revert-layer;
+    margin-inline: revert-layer;
+    /* … */
+  }
+}
+```
 
-It has to win over the `grid-template-columns` that a component such as `.items` declares for itself in `@layer components`. `@layer utilities` comes later in the order, so it wins regardless of specificity. See [Cascade layers](../cascade-layers/).
+`revert-layer` hands the property back to the layer below, which is the component's own grid rule in `@layer components`. So there is no duplicated set of grid values to keep in step: whatever `.items` declares is what comes back, including any override you wrote yourself.
 
 ## Item width
 
@@ -51,7 +62,7 @@ Items take `--items-min-width`, the same value that drives the grid, capped by `
 
 ## The bleed, and why margin and padding disagree
 
-The row pulls out to the screen edge using `--container-bleed`, published by `.container` in [css-base](../../css-base/layouts/#the-container-bleed-contract). The property inherits, so it reaches the row from a `.container` however far up it sits.
+The row pulls out to the screen edge using `--container-bleed`, published by `.container` in [css-base](../../../css-base/layouts/#the---container-bleed-contract). The property inherits, so it reaches the row from a `.container` however far up it sits.
 
 Outside a container there is no published value, and the two `var()` fallbacks differ **on purpose**, because margin and padding answer different questions:
 
@@ -65,3 +76,9 @@ Inside a container the two collapse to one value: both read the published bleed,
 `scroll-margin-inline` follows the **padding**, not the margin. It is what makes an item snap flush with the content edge rather than the padding edge, so it has to cancel the padding whatever the margin does.
 
 This is the same reasoning as the `--container-bleed` contract itself, applied to a scroll container. If you write your own full-bleed component, copy the pair rather than picking one fallback for both.
+
+## It needs a build step
+
+The four responsive variants are written with `@media (--sm)` and its siblings, which rely on the `@custom-media` rules declared in css-base. No browser implements `@custom-media`, so without [postcss-custom-media](https://www.npmjs.com/package/postcss-custom-media) every `.scrollsnap-*` variant becomes a permanent carousel: the base block applies and the block that hands the grid back is dropped.
+
+The failure is silent. See [the package index](../../).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncinq/css-components",
-  "version": "1.16.2",
+  "version": "1.16.3",
   "description": "Framework-agnostic CSS component implementations.",
   "license": "MIT",
   "repository": {

package/docs/buttons.md

@@ -1,103 +0,0 @@
----
-isIndex: false
-title: Buttons
-description: The .btn base class with its colour, size and style variants, and the seven specialised buttons built on it.
-weight: 2
-icon: hand-index
----
-
-## `.btn`
-
-The base class. Works on `<button>`, `<a>` and `<input type="submit">`, and reads `--btn-*` from [@uncinq/component-tokens](../../component-tokens/reference/).
-
-```html
-<button class="btn">Send</button>
-<a class="btn btn-secondary" href="/contact">Contact</a>
-```
-
-### Colour variants
-
-| Class | Intent |
-| --- | --- |
-| `.btn-primary` | Primary action |
-| `.btn-secondary` | Secondary action |
-| `.btn-brand` | Brand-coloured |
-| `.btn-neutral` | Neutral emphasis |
-| `.btn-dark` | Dark surface |
-| `.btn-light` | Light surface |
-| `.btn-success` | Confirmation |
-| `.btn-danger` | Destructive action |
-| `.btn-warning` | Warning |
-| `.btn-info` | Informational |
-
-Each variant sets `--btn-color-background`, `--btn-color-border` and `--btn-color-text` together. The text colour always comes from the matching `--color-text-on-*` semantic token, so contrast is preserved when the underlying colour is overridden. That pairing is the reason to change `--color-brand` rather than `--btn-color-background` when rebranding.
-
-### Sizes
-
-| Class | Use |
-| --- | --- |
-| `.btn-xs` | Dense UI, inline controls |
-| `.btn-sm` | Compact |
-| `.btn-md` | Default, can be omitted |
-| `.btn-lg` | Prominent |
-| `.btn-xl` | Hero call to action |
-
-### Style variants
-
-| Class | Effect |
-| --- | --- |
-| `.btn-ghost` | Transparent background, visible border |
-| `.btn-link` | Renders as a link, no background or border |
-| `.btn-control` | Form control styling, transparent border, for buttons sitting next to inputs |
-
-Variants compose: `class="btn btn-danger btn-sm btn-ghost"`.
-
-## Specialised buttons
-
-Seven single-purpose buttons. Read the second column before using one: whether `.btn` is required differs between them.
-
-| Class | Needs `.btn` | Icon | Purpose |
-| --- | --- | --- | --- |
-| `.btn-close` | no | `--icon-close` | Close control, used inside panels and alerts |
-| `.btn-menu` | no | `--icon-menu` | Menu toggle, typically the burger in a header |
-| `.btn-search` | yes | `--icon-search` | Search toggle |
-| `.btn-filter` | yes | `--icon-filter` | Filters toggle |
-| `.btn-share` | yes | `--icon-share` | Share control |
-| `.btn-toc` | yes | `--icon-toc` | Table of contents toggle |
-| `.btn-toggle-video` | yes | child elements | Play and pause control overlaid on a video |
-
-```html
-<!-- self-contained -->
-<button class="btn-close" aria-label="Close"></button>
-
-<!-- modifier on .btn -->
-<button class="btn btn-search" aria-label="Search"></button>
-```
-
-`.btn-close` and `.btn-menu` redeclare everything they need, with `--btn-close-*` and `--btn-menu-*` falling back to the matching `--btn-*` token. They therefore look consistent with `.btn` without depending on it. The other five are modifiers, and omitting the base class leaves them largely unstyled.
-
-Six of the seven **do ship their icon**, drawn as a `mask` on `::before` from the icon tokens in [@uncinq/design-tokens](../../design-tokens/reference/#icon). Because it is a mask rather than a background image, the glyph takes `currentColor` and follows the button's text colour through every state. Size it with `--icon-size`, or per button with `--btn-close-icon-size` and its siblings.
-
-`.btn-toggle-video` is the exception and expects two child elements, for the reason given below.
-
-When a button has no visible text, give it an accessible name with `aria-label`, or a `.visually-hidden` span from [css-base](../../css-base/base/#accessibility-helpers). None of these buttons provides one for you.
-
-## `.btn-toggle-video`
-
-The one worth explaining, because its behaviour is driven by a state class rather than by CSS alone.
-
-It is a play and pause control overlaid on a video that autoplays without native controls, which WCAG requires to be pausable. It stays transparent so the video shows through, and the `.is-playing` class, toggled by whatever script drives the video, decides which of the two icons is shown.
-
-```html
-<div class="video">
-  <video autoplay muted loop playsinline></video>
-  <button class="btn btn-toggle-video is-playing" aria-label="Pause">
-    <span class="icon-pause"></span>
-    <span class="icon-play"></span>
-  </button>
-</div>
-```
-
-The `.video` wrapper is what positions it. See [Embeds](../embeds/).
-
-Your script owns two things: toggling `.is-playing` in step with the video's actual state, and keeping the accessible name in sync, since the control means "pause" while playing and "play" while paused.