@uncinq/css-components 1.16.2 → 1.16.4

package/README.md

@@ -63,7 +63,7 @@ The failure is silent. No error is raised, the page simply stays at its mobile v
 
 ## Two import-order rules
 
-`components/panel.css` is imported **last** among the components: its `.panel-inline-*` variants beat `.modal` and `.drawer` on source order, because most of the file is `:where()`-wrapped and carries no specificity.
+`components/panel.css` must come **after** `modal.css` and `drawer.css`: its `.panel-inline-*` variants beat them on source order, because most of the file is `:where()`-wrapped and carries no specificity. Alphabetical order already gives that in `css/index.css`.
 
 `utilities/scrollsnap.css` comes after everything, in `@layer utilities`, because it has to win over the grid a component declares for itself.
 
@@ -73,22 +73,23 @@ If you import file by file rather than using the barrel, preserve both positions
 
 - **No JavaScript.** `modal`, `drawer` and `dropdown` expect a script; each documents the classes and attributes it must toggle.
 - **No `.item`.** This package ships `.card`, a complete implementation. `.item` lives in the Hugolify design system theme.
-- **No pagination glyphs.** The theme supplies them through `::before` or `::after` content.
+- **No `.icon` glyphs.** Buttons and `pagination` mask their own from icon tokens, but an `.icon` element you place inside an `alert` or a video toggle is the theme's to render.
 
 ## Documentation
 
 Full documentation: **[socle.uncinq.dev/docs/css-components/](https://socle.uncinq.dev/docs/css-components/)**
 
-It is also versioned with the code in [`docs/`](docs/), and ships inside the npm package, so it is readable offline and from `node_modules`:
+It is also versioned with the code in [`docs/`](docs/), one page per component, and ships inside the npm package, so it is readable offline and from `node_modules`:
 
+- [Overview](docs/overview.md) — installation, import order, what the package leaves out
 - [Cascade layers](docs/cascade-layers.md) — the two layers, and the `:where()` convention
-- [Buttons](docs/buttons.md)
-- [Overlays](docs/overlays.md) — the panel skeleton and the JS contracts
-- [Content](docs/content.md)
-- [Navigation](docs/navigation.md)
-- [Embeds](docs/embeds.md)
-- [Forms](docs/forms.md)
-- [Utilities](docs/utilities.md) — `.scrollsnap` and the bleed contract
+- [Buttons](docs/buttons/) — [`.btn`](docs/buttons/btn.md) and the seven specialised buttons
+- [Overlays](docs/overlays/) — [the panel skeleton](docs/overlays/panel.md), [`.modal`](docs/overlays/modal.md), [`.drawer`](docs/overlays/drawer.md), [`.dropdown`](docs/overlays/dropdown.md)
+- [Content](docs/content/) — [`.alert`](docs/content/alert.md), [`.badge`](docs/content/badge.md), [`.banner`](docs/content/banner.md), [`.card`](docs/content/card.md), [`.items`](docs/content/items.md), [`.list`](docs/content/list.md), [`.media`](docs/content/media.md), [`.surtitle`](docs/content/surtitle.md)
+- [Navigation](docs/navigation/) — [`.nav`](docs/navigation/nav.md), [`.nav-title`](docs/navigation/nav-title.md), [skip links](docs/navigation/nav-accessibility.md), [breadcrumb](docs/navigation/breadcrumb.md), [pagination](docs/navigation/pagination.md)
+- [Embeds](docs/embeds/) — [`.embed`](docs/embeds/embed.md), [`.video`](docs/embeds/video.md), [`.map`](docs/embeds/map.md)
+- [Forms](docs/forms/) — [`.form`](docs/forms/form.md), [`.form-check`](docs/forms/form-check.md)
+- [Utilities](docs/utilities/) — [`.scrollsnap`](docs/utilities/scrollsnap.md) and the bleed contract
 
 ## References
 

package/css/components/alert.css

@@ -38,6 +38,11 @@
     }
   }
 
+  /* Restore the hidden attribute, which display: flex would otherwise override */
+  .alert[hidden] {
+    display: none;
+  }
+
   /* Variants */
   .alert-brand {
     --alert-color-background: var(--color-brand-muted);

package/css/components/panel.css

@@ -9,17 +9,19 @@
  * The tag picks the strategy, not the class. Either variant can be:
  * - <dialog> opened with showModal() — [open], native ::backdrop, top layer,
  *   and the browser handles Escape, the focus trap and inertness;
- * - any element carrying popover="auto", opened by components/dialog.js
- *   with showPopover() — same top layer, same ::backdrop, but no role of its
+ * - any element carrying popover="auto", opened with showPopover() by the
+ *   script you provide — same top layer, same ::backdrop, but no role of its
  *   own. Use this when the panel becomes a static region of the page above a
  *   breakpoint (see .panel-inline-*): a <dialog> is exposed as role="dialog"
- *   even when it is only styled as a sidebar, whereas dialog.js sets that
+ *   even when it is only styled as a sidebar, whereas a script can set that
  *   role solely while the panel is open.
  *
  * Most selectors here are :where()-wrapped so they carry no specificity: the
  * variants and the host components always win without escalating. The
  * .panel-inline-* variants are the exception — they must beat .modal and
- * .drawer, which they do on source order, so this file is imported last.
+ * .drawer, which they do on source order, so this file must be imported
+ * AFTER modal.css and drawer.css. Alphabetical order already gives that in
+ * css/index.css; keep it if you import file by file.
  *
  * Structure reads --panel-* tokens; each variant aliases them from its own
  * namespace, so --modal-* and --drawer-* stay the public API.
@@ -158,8 +160,8 @@
    * than patching every host component.
    *
    * The panel must NOT be a <dialog> when one of these is used — see the
-   * strategy note at the top of this file. components/dialog.js also closes
-   * an open panel carrying one of these classes when the viewport width
+   * strategy note at the top of this file. Your script must also close an
+   * open panel carrying one of these classes when the viewport width
    * changes, since CSS alone cannot release the backdrop, the scroll lock
    * and the inert background. */
 

package/docs/_index.md

@@ -5,87 +5,3 @@ description: Framework-agnostic CSS component implementations, driven entirely b
 weight: 5
 icon: grid
 ---
-
-`@uncinq/css-components` is the top of the stack: 29 components and 1 utility, written as plain CSS, reading their values from [@uncinq/component-tokens](../component-tokens/) and adding no values of their own.
-
-```
-@uncinq/design-tokens      primitive + semantic values
-@uncinq/component-tokens   component-scoped values
-@uncinq/css-base           reset, native elements, layouts
-@uncinq/css-components     ← this package
-```
-
-Every rule lives in `@layer components`, except the scroll-snap utility which lives in `@layer utilities`. There is no build step, no preprocessor, and no JavaScript shipped in the package. Three components do expect a script you provide, and each one documents the contract it needs.
-
-## The components
-
-| Page | Covers |
-| --- | --- |
-| [Buttons](buttons/) | `.btn` with its colour, size and style variants, plus 7 specialised buttons |
-| [Overlays](overlays/) | `.panel`, `.modal`, `.drawer`, `.dropdown` |
-| [Content](content/) | `.alert`, `.badge`, `.banner`, `.card`, `.items`, `.list`, `.media`, `.surtitle` |
-| [Navigation](navigation/) | `.nav`, `.nav-title`, `.nav-accessibility`, `.breadcrumb-wrapper`, `.pagination` |
-| [Embeds](embeds/) | `.embed`, `.video`, `.map` |
-| [Forms](forms/) | `.form`, `.form-check` and the form layout helpers |
-| [Utilities](utilities/) | `.scrollsnap`, turning a grid into a snap carousel |
-
-Read [Cascade layers](cascade-layers/) first if you are wiring this into a project for the first time.
-
-## Installation
-
-All three packages below are required. The tokens resolve the custom properties, and css-base provides the reset and the element styles the components build on.
-
-```bash
-npm install @uncinq/design-tokens @uncinq/component-tokens @uncinq/css-base @uncinq/css-components
-```
-
-```css
-@layer reset, tokens, libs, base, vendors, layouts, components, pages, utilities;
-
-@import '@uncinq/design-tokens';    /* @layer tokens */
-@import '@uncinq/css-base';         /* @layer reset, base, layouts */
-@import '@uncinq/component-tokens'; /* @layer tokens */
-@import '@uncinq/css-components';   /* @layer components, utilities */
-```
-
-Per component, when you only need a few:
-
-```css
-@import '@uncinq/css-components/css/components/button.css';
-@import '@uncinq/css-components/css/components/alert.css';
-@import '@uncinq/css-components/css/utilities/scrollsnap.css';
-```
-
-### A CDN link is not enough
-
-`@uncinq/design-tokens` and `@uncinq/component-tokens` can be linked straight from a CDN, because they emit nothing but custom properties. **This package cannot**, and neither can `@uncinq/css-base`.
-
-Both ship `@media (--sm)` queries that rely on the `@custom-media` rules declared in `css-base/css/mediaqueries.css`, and no browser implements `@custom-media`. Loaded without [postcss-custom-media](https://www.npmjs.com/package/postcss-custom-media), 13 responsive blocks in this package are dropped: `.panel-inline-*`, `.panel-trigger-*` and every `.scrollsnap-*` variant.
-
-The failure is silent. No error is raised, the page simply stays at its mobile values on every screen. A build step is required.
-
-Note that `@uncinq/css-base` is a genuine prerequisite but is **not** declared in `peerDependencies`. Install it explicitly.
-
-## Import order inside the package
-
-`css/index.css` imports the components alphabetically, with two deliberate exceptions.
-
-`components/panel.css` is imported **last** among the components. Its `.panel-inline-*` variants have to beat `.modal` and `.drawer`, and they do so on source order rather than on specificity, because most of the file is wrapped in `:where()` and carries no specificity at all.
-
-`utilities/scrollsnap.css` comes after everything, in `@layer utilities`, because it has to win over the grid a component declares for itself in `@layer components`.
-
-If you import file by file rather than using the barrel, preserve those two positions.
-
-## What this package does not include
-
-**No JavaScript.** `.modal`, `.drawer` and `.dropdown` expect a script. The CSS defines the classes and attributes that script must toggle, and each page documents the contract.
-
-**No `.item`.** Despite what a couple of source comments still suggest, `.item` is not defined here. It lives in the Hugolify design system theme. This package ships `.card`, a complete implementation in its own right, and `.items`, a grid whose children you provide. See [Content](content/).
-
-**No icons.** Components that show a glyph, such as `.pagination` controls, expect the theme to supply it through `::before` or `::after` content.
-
-## References
-
-- [@uncinq/component-tokens](https://github.com/uncinq/component-tokens), the values these components read
-- [@uncinq/css-base](https://github.com/uncinq/css-base), the foundation underneath
-- [MDN: CSS cascade layers](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers)

package/docs/buttons/_index.md

@@ -0,0 +1,7 @@
+---
+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: 3
+icon: hand-index
+---

package/docs/buttons/btn-close.md

@@ -0,0 +1,58 @@
+---
+isIndex: false
+title: Close button
+description: The self-contained close control used inside panels, alerts and dismissible blocks.
+weight: 3
+icon: x-lg
+---
+
+A close control. It is **self-contained**: `.btn` is not required.
+
+```html
+<button class="btn-close" aria-label="Close"></button>
+```
+
+Its main use is the header of a [panel](../../overlays/panel/), where it usually carries the `.js-dialog-close` hook as well:
+
+```html
+<div class="header">
+  <p class="title" id="contactLabel">Contact</p>
+  <button class="btn-close js-dialog-close" aria-label="Close"></button>
+</div>
+```
+
+## Why it stands alone
+
+Every property is declared twice over, with `--btn-close-*` falling back to the matching `--btn-*` token:
+
+```css
+background-color: var(--btn-close-color-background, var(--btn-control-color-background));
+border-radius: var(--btn-close-border-radius, var(--btn-border-radius));
+font-size: var(--btn-close-font-size, var(--btn-font-size));
+```
+
+So it looks like the rest of the button family without inheriting from it, and a single `--btn-close-*` override retargets it alone. Its default palette is `--btn-control-*`, the same quiet colours as [`.btn-control`](../btn/#style-variants), which is what keeps it from competing with the panel's real actions.
+
+## The icon
+
+Drawn on `::before` as a mask from `--icon-close`, sized by `--btn-close-icon-size` falling back to `--icon-size`. Since nothing above a bare `.btn-close` publishes `--icon-size`, set one explicitly if the ambient value is not what you want:
+
+```css
+.btn-close {
+  --btn-close-icon-size: var(--font-size-lg);
+}
+```
+
+## What it does not declare
+
+No `:focus-visible` rule and no disabled styling. The focus ring is therefore the browser's own rather than the one from the `--focus-*` tokens, and `disabled` changes nothing visually.
+
+Add `.btn` alongside it when either matters:
+
+```html
+<button class="btn btn-close" aria-label="Close"></button>
+```
+
+## Accessibility
+
+The button has no text content, so `aria-label` is not optional. A close button with no accessible name is announced as "button" and nothing more.

package/docs/buttons/btn-filter.md

@@ -0,0 +1,36 @@
+---
+isIndex: false
+title: Filter button
+description: The filters toggle, a modifier on .btn carrying the filter icon.
+weight: 6
+icon: funnel
+---
+
+The control that opens a filters panel. **It requires `.btn`.**
+
+```html
+<button class="btn btn-filter panel-trigger-md js-dialog-toggle"
+        data-target="#filters"
+        aria-label="Filters"></button>
+```
+
+Like [`.btn-search`](../btn-search/), it declares only a `--btn-color-*` set pointed at the control palette, with `--btn-filter-color-*` in front of it as the override hook, and an icon masked from `--icon-filter`. Everything else comes from `.btn`.
+
+## It usually needs a `.panel-trigger-*`
+
+A filters panel is the textbook case for [`.panel-inline-*`](../../overlays/panel/#inline-variants): a drawer on mobile, a sidebar column on desktop. Once the panel is a column there is nothing left to open, so the button has to go with it.
+
+The two classes are separate and must be paired by hand:
+
+| Panel carries | Button carries |
+| --- | --- |
+| `.panel-inline-sm` | `.panel-trigger-sm` |
+| `.panel-inline-md` | `.panel-trigger-md` |
+| `.panel-inline-lg` | `.panel-trigger-lg` |
+| `.panel-inline-xl` | `.panel-trigger-xl` |
+
+A mismatch leaves a button on screen that opens nothing. The reasoning behind the two-class design is on the [panel page](../../overlays/panel/#hiding-the-trigger).
+
+## Placement
+
+The filter button usually lives in the page heading rather than beside the panel it opens, which is worth remembering when writing layout rules around it. It is an ordinary inline-flex button and takes whatever the surrounding layout gives it.

package/docs/buttons/btn-menu.md

@@ -0,0 +1,39 @@
+---
+isIndex: false
+title: Menu button
+description: The self-contained menu toggle, typically the burger in a site header.
+weight: 4
+icon: list
+---
+
+A menu toggle, typically the burger control in a header. Like [`.btn-close`](../btn-close/), it is **self-contained**: `.btn` is not required.
+
+```html
+<button class="btn-menu js-dialog-toggle" data-target="#menu" aria-label="Menu"></button>
+```
+
+It is almost always the trigger for a [drawer](../../overlays/drawer/), which is why it usually carries `.js-dialog-toggle` and a `data-target` pointing at the panel's `id`.
+
+## Same construction as the close button
+
+Every property falls back from `--btn-menu-*` to the matching `--btn-*` token, and the default palette is `--btn-control-*`. See [`.btn-close`](../btn-close/#why-it-stands-alone) for the full explanation, which applies here unchanged.
+
+The icon comes from `--icon-menu`, masked on `::before` and sized by `--btn-menu-icon-size` falling back to `--icon-size`.
+
+## What it does not declare
+
+No `:focus-visible` rule and no disabled styling, exactly as with `.btn-close`. Add `.btn` alongside it when you need either.
+
+## Hiding it once the menu is inline
+
+A burger that opens a panel which has become a static region of the page is a button that does nothing. Pair the panel's `.panel-inline-*` class with the matching `.panel-trigger-*` on this button:
+
+```html
+<button class="btn-menu panel-trigger-md js-dialog-toggle" data-target="#menu" aria-label="Menu"></button>
+```
+
+See [Hiding the trigger](../../overlays/panel/#hiding-the-trigger).
+
+## Accessibility
+
+`aria-label` is required, since the button has no text. Keep `aria-expanded` in sync if your script toggles a menu in place rather than opening a panel in the top layer.

package/docs/buttons/btn-search.md

@@ -0,0 +1,40 @@
+---
+isIndex: false
+title: Search button
+description: The search toggle, a modifier on .btn carrying the search icon.
+weight: 5
+icon: search
+---
+
+A search control. **It requires `.btn`**: on its own it is nothing but a colour set and an icon.
+
+```html
+<button class="btn btn-search js-dialog-toggle" data-target="#search" aria-label="Search"></button>
+```
+
+## What it declares
+
+Two things, and nothing else.
+
+The `--btn-color-*` set is retargeted at the control palette, with a per-button escape hatch in front of it:
+
+```css
+--btn-color-background: var(--btn-search-color-background, var(--btn-control-color-background));
+--btn-color-text: var(--btn-search-color-text, var(--btn-control-color-text));
+```
+
+Override `--btn-search-color-*` to restyle every search button, or `--btn-color-*` directly on one instance.
+
+And the glyph, masked from `--icon-search` on `::before`, sized by `--btn-search-icon-size` falling back to `--icon-size`, which `.btn` sets to its own font size.
+
+That is the whole file. Geometry, focus, hover, disabled and the transition all come from the base class, which is why omitting it leaves an unstyled button with an icon.
+
+## Adding a label
+
+The icon sits on `::before`, so any text content lands beside it with `--btn-gap` between the two. No extra class is needed:
+
+```html
+<button class="btn btn-search">Search</button>
+```
+
+Without visible text, `aria-label` is required.

package/docs/buttons/btn-share.md

@@ -0,0 +1,33 @@
+---
+isIndex: false
+title: Share button
+description: The share control, a modifier on .btn carrying the share icon.
+weight: 7
+icon: share
+---
+
+A share control. **It requires `.btn`.**
+
+```html
+<button class="btn btn-share" aria-label="Share">Share</button>
+```
+
+Construction is identical to [`.btn-search`](../btn-search/): a `--btn-color-*` set pointed at the control palette, with `--btn-share-color-*` as the per-variant override, and the glyph masked from `--icon-share`.
+
+## It ships no behaviour
+
+The class is presentation only. Whether the button calls `navigator.share()`, copies a URL to the clipboard or opens a [dropdown](../../overlays/dropdown/) of destinations is entirely up to your script.
+
+If it opens a menu, the dropdown contract applies: the trigger needs `.dropdown-toggle` and `.js-dropdown-toggle`, and its next element sibling must be the `.dropdown-menu`.
+
+```html
+<div class="dropdown">
+  <button class="btn btn-share dropdown-toggle js-dropdown-toggle" aria-expanded="false">Share</button>
+  <ul class="dropdown-menu">
+    <li><a href="...">Bluesky</a></li>
+    <li><a href="...">LinkedIn</a></li>
+  </ul>
+</div>
+```
+
+Note that `.dropdown-toggle` draws its own chevron on `::after` while `.btn-share` draws the share glyph on `::before`, so the combination gives you both, one on each side of the label.

package/docs/buttons/btn-toc.md

@@ -0,0 +1,23 @@
+---
+isIndex: false
+title: Table of contents button
+description: The table of contents toggle, a modifier on .btn carrying the toc icon.
+weight: 8
+icon: list-nested
+---
+
+The control that opens a table of contents. **It requires `.btn`.**
+
+```html
+<button class="btn btn-toc panel-trigger-lg js-dialog-toggle"
+        data-target="#toc"
+        aria-label="Table of contents"></button>
+```
+
+Construction is identical to [`.btn-search`](../btn-search/): a `--btn-color-*` set pointed at the control palette, with `--btn-toc-color-*` as the per-variant override, and the glyph masked from `--icon-toc`.
+
+## It behaves like the filter button
+
+A table of contents follows the same responsive pattern as a filters panel: a drawer on small screens, a sticky column on large ones. Pair the panel's [`.panel-inline-*`](../../overlays/panel/#inline-variants) with the matching `.panel-trigger-*` on this button, or you keep a button that opens nothing at desktop width.
+
+Because a table of contents is typically a [`.nav`](../../navigation/nav/) inside the panel's `.content`, the panel's colour handover matters here: going inline hands `--nav-color-text` back to the page, so the links stop using the panel's text colour and take the site's link colour instead.

package/docs/buttons/btn-toggle-video.md

@@ -0,0 +1,58 @@
+---
+isIndex: false
+title: Video toggle
+description: The play and pause control overlaid on an autoplaying video, driven by the .is-playing state class.
+weight: 9
+icon: play-circle
+---
+
+A play and pause control overlaid on a video. **It requires `.btn`**, and it is the one specialised button that ships no icon of its own.
+
+```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>
+```
+
+## Why it exists
+
+A video that autoplays without native controls must be pausable to meet WCAG. This button is that pause control. If your video carries `controls`, you do not need it.
+
+It stays fully transparent, background and border alike, so the video shows through:
+
+```css
+--btn-color-background: transparent;
+--btn-color-border: transparent;
+```
+
+The [`.video`](../../embeds/video/) wrapper is what positions it, pinned to the bottom inline-end corner. Used outside that wrapper it is an ordinary transparent button in the flow.
+
+## Two children, one visible
+
+The whole file beyond the colours is this:
+
+```css
+&:not(.is-playing) .icon-pause { display: none; }
+&.is-playing .icon-play { display: none; }
+```
+
+So the button expects **two** child elements and shows exactly one. The glyphs themselves are not provided here: `.icon-pause` and `.icon-play` are whatever your theme's icon system renders.
+
+## What your script owns
+
+Two things, and getting either wrong breaks the control.
+
+**Toggling `.is-playing`** in step with the video's actual state, including when playback stops for a reason the script did not initiate.
+
+**Keeping the accessible name in sync.** The control means *pause* while playing and *play* while paused, so a fixed `aria-label` is wrong half the time.
+
+```js
+button.classList.toggle('is-playing', !video.paused);
+button.setAttribute('aria-label', video.paused ? 'Play' : 'Pause');
+```
+
+Note that `.is-playing` describes the **video**, not the button, which is why the class stays on while the video runs rather than flipping on click.

package/docs/buttons/btn.md

@@ -0,0 +1,95 @@
+---
+isIndex: false
+title: Button
+description: The .btn base class, its ten colour variants, five sizes and three style variants.
+weight: 2
+icon: hand-index-thumb
+---
+
+`.btn` is the base class. It 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>
+```
+
+Variants compose freely: `class="btn btn-danger btn-sm btn-ghost"`.
+
+## 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 sets four properties together: background, border, their hover values, and the text colour.
+
+```css
+.btn-danger {
+  --btn-color-background: var(--color-danger);
+  --btn-color-background-hover: var(--color-danger-strong);
+  --btn-color-border: var(--color-danger);
+  --btn-color-border-hover: var(--color-danger-strong);
+  --btn-color-text: var(--color-text-on-danger);
+}
+```
+
+The text colour always comes from the matching `--color-text-on-*` semantic token, so contrast survives a change to the underlying colour. That pairing is the reason to rebrand by redefining `--color-brand` rather than `--btn-color-background`.
+
+`.btn-primary` and `.btn-brand` resolve to exactly the same values, as do `.btn-secondary` and `.btn-neutral`. The intent names exist so a page can say *primary action* without deciding which colour that is.
+
+## 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 |
+
+A size class sets `--btn-font-size` along with the block and inline padding, all three from the same rung of the scale. Since `.btn` publishes `--icon-size: var(--btn-font-size)`, any icon inside scales with it.
+
+## Style variants
+
+| Class | Effect |
+| --- | --- |
+| `.btn-ghost` | Fully transparent, background and border alike, text in `--color-text` |
+| `.btn-link` | Renders as an underlined link |
+| `.btn-control` | Form control styling, for buttons sitting next to inputs |
+
+`.btn-control` maps the `--btn-color-*` set onto the `--btn-control-*` tokens, which is the same palette the [close](../btn-close/) and [menu](../btn-menu/) buttons use by default. It is what makes a button read as part of a form rather than as a call to action.
+
+### How `.btn-link` gets its underline
+
+Every button already carries one. The base class declares `text-decoration-line: var(--btn-text-decoration-line)`, which the tokens set to `underline`, and paints it with `--btn-color-text-decoration`, which defaults to `transparent`.
+
+`.btn-link` only changes the colour:
+
+```css
+.btn-link {
+  --btn-color-text-decoration: initial;   /* revealed, takes currentColor */
+
+  @media (hover: hover) and (pointer: fine) {
+    &:hover {
+      --btn-color-text-decoration: transparent;  /* hidden again */
+    }
+  }
+}
+```
+
+The underline is therefore always in the layout and never shifts the text, which is why hovering one does not nudge the label. If you write your own link-like variant, change the decoration colour rather than the decoration line, for the same reason.
+
+## States
+
+`:focus-visible` draws the outline from the `--focus-*` tokens. `:disabled` and `[aria-disabled='true']` are treated alike, both getting `cursor: not-allowed` and `--opacity-disabled`.
+
+Hover is guarded by `@media (hover: hover) and (pointer: fine)`, so a touch device never leaves a button stuck in its hover colours after a tap. The transition is guarded by `prefers-reduced-motion`.

package/docs/buttons/overview.md

@@ -0,0 +1,75 @@
+---
+isIndex: false
+title: Overview
+description: The eight button files, the two kinds of specialised button, and the masked icons they share.
+weight: 1
+icon: book
+---
+
+Eight files: one base class, and seven single-purpose buttons.
+
+| Page | Class | Needs `.btn` |
+| --- | --- | --- |
+| [Button](../btn/) | `.btn` | — |
+| [Close button](../btn-close/) | `.btn-close` | no |
+| [Menu button](../btn-menu/) | `.btn-menu` | no |
+| [Search button](../btn-search/) | `.btn-search` | yes |
+| [Filter button](../btn-filter/) | `.btn-filter` | yes |
+| [Share button](../btn-share/) | `.btn-share` | yes |
+| [Table of contents button](../btn-toc/) | `.btn-toc` | yes |
+| [Video toggle](../btn-toggle-video/) | `.btn-toggle-video` | yes |
+
+## Two kinds of specialised button
+
+Read the third column before using one, because the two kinds behave differently when the base class is missing.
+
+`.btn-close` and `.btn-menu` **redeclare everything they need**. Each `--btn-close-*` and `--btn-menu-*` token falls back to the matching `--btn-*` one, so they look consistent with `.btn` without depending on it. Use them on their own.
+
+The other five are **modifiers**. They declare nothing but `--btn-color-*` reassignments and an icon, so omitting `.btn` leaves them almost entirely unstyled.
+
+```html
+<!-- self-contained -->
+<button class="btn-close" aria-label="Close"></button>
+
+<!-- modifier on .btn -->
+<button class="btn btn-search" aria-label="Search"></button>
+```
+
+## The icons are masks, not images
+
+Six of the seven ship their glyph, drawn on `::before` from the icon tokens in [@uncinq/design-tokens](../../../design-tokens/reference/#icon):
+
+```css
+&::before {
+  background-color: currentColor;
+  mask: var(--icon-search) center / var(--btn-search-icon-size, var(--icon-size)) no-repeat;
+}
+```
+
+Because it is a mask over a background colour rather than a background image, the glyph takes `currentColor` and follows the button's text colour through every state, including hover and disabled. Size it globally with `--icon-size`, or per button with `--btn-close-icon-size` and its siblings.
+
+`.btn` publishes `--icon-size: var(--btn-font-size)`, so a modifier button scales with its size class for free. A bare `.btn-close` or `.btn-menu` has no such declaration above it and takes whatever `--icon-size` is in scope.
+
+[`.btn-toggle-video`](../btn-toggle-video/) is the exception: it ships no icon and expects two child elements instead.
+
+## None of them names itself
+
+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/). No button in this package provides one.
+
+## Focus and disabled states
+
+`.btn` declares both:
+
+```css
+&:focus-visible {
+  outline: var(--focus-outline-width) var(--focus-outline-style) var(--focus-color-outline);
+}
+
+&:disabled,
+&[aria-disabled='true'] {
+  cursor: not-allowed;
+  opacity: var(--opacity-disabled);
+}
+```
+
+The five modifiers inherit that through the base class. **`.btn-close` and `.btn-menu` declare neither**, so they fall back to the browser's own focus ring rather than the design system's, and a disabled one looks no different from an enabled one. Add `.btn` alongside them when either matters.