@uncinq/css-components 1.16.2 → 1.16.3

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,22 @@ 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`:
 
 - [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

@@ -19,15 +19,17 @@ Every rule lives in `@layer components`, except the scroll-snap utility which li
 
 ## The components
 
-| Page | Covers |
+One page per component, grouped into six sections.
+
+| Section | Components |
 | --- | --- |
-| [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 |
+| [Buttons](buttons/) | [`.btn`](buttons/btn/), [`.btn-close`](buttons/btn-close/), [`.btn-menu`](buttons/btn-menu/), [`.btn-search`](buttons/btn-search/), [`.btn-filter`](buttons/btn-filter/), [`.btn-share`](buttons/btn-share/), [`.btn-toc`](buttons/btn-toc/), [`.btn-toggle-video`](buttons/btn-toggle-video/) |
+| [Overlays](overlays/) | [panel](overlays/panel/), [`.modal`](overlays/modal/), [`.drawer`](overlays/drawer/), [`.dropdown`](overlays/dropdown/) |
+| [Content](content/) | [`.alert`](content/alert/), [`.badge`](content/badge/), [`.banner`](content/banner/), [`.card`](content/card/), [`.items`](content/items/), [`.list`](content/list/), [`.media`](content/media/), [`.surtitle`](content/surtitle/) |
+| [Navigation](navigation/) | [`.nav`](navigation/nav/), [`.nav-title`](navigation/nav-title/), [`.nav-accessibility`](navigation/nav-accessibility/), [`.breadcrumb-wrapper`](navigation/breadcrumb/), [`.pagination`](navigation/pagination/) |
+| [Embeds](embeds/) | [`.embed`](embeds/embed/), [`.video`](embeds/video/), [`.map`](embeds/map/) |
+| [Forms](forms/) | [`.form`](forms/form/), [`.form-check`](forms/form-check/) |
+| [Utilities](utilities/) | [`.scrollsnap`](utilities/scrollsnap/) |
 
 Read [Cascade layers](cascade-layers/) first if you are wiring this into a project for the first time.
 
@@ -70,11 +72,11 @@ Note that `@uncinq/css-base` is a genuine prerequisite but is **not** declared i
 
 `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.
+`components/button.css` comes **before** the seven `btn-*` files rather than after them, because five of those are modifiers on `.btn` and read better in that order.
 
 `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.
+One constraint is easy to break when importing file by file: `panel.css` must come **after** `modal.css` and `drawer.css`. Alphabetical order already gives that, which is why nothing in the barrel looks unusual, but the `.panel-inline-*` variants beat the two host components on source order rather than on specificity. See [Cascade layers](cascade-layers/).
 
 ## What this package does not include
 
@@ -82,7 +84,7 @@ If you import file by file rather than using the barrel, preserve those two posi
 
 **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.
+**No icons for `.icon`.** Components that draw a glyph, the [buttons](buttons/) and [`.pagination`](navigation/pagination/), mask it from an icon token. An `.icon` element you place inside an [alert](content/alert/) or a [video toggle](buttons/btn-toggle-video/) is the theme's to render.
 
 ## References
 

package/docs/buttons/_index.md

@@ -0,0 +1,75 @@
+---
+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
+---
+
+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-helpers). 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.

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: 2
+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: 5
+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: 3
+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: 4
+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: 6
+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: 7
+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: 8
+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: 1
+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/cascade-layers.md

@@ -1,7 +1,7 @@
 ---
 isIndex: false
 title: Cascade layers
-description: The two layers this package owns, why panel.css is imported last, and how to override a component cleanly.
+description: The two layers this package owns, why panel.css follows modal and drawer, and how to override a component cleanly.
 weight: 1
 icon: stack
 ---
@@ -23,18 +23,20 @@ CSS fixes a layer's position the first time its name is seen, and later re-decla
 
 ## Why `utilities` is last
 
-`.scrollsnap` changes the `grid-template-columns` that a component such as `.items` declares for itself in `@layer components`. A later layer beats an earlier one regardless of specificity, so putting it in `utilities` is what lets a single class opt an existing component into carousel behaviour without rewriting the component.
+[`.scrollsnap`](../utilities/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 `utilities` is what lets a single class opt an existing component into carousel behaviour without rewriting the component.
 
-This is also why it is a utility rather than a component rule: it is a modifier applied to something else, not a thing of its own.
+It is also what makes `revert-layer` work in the responsive variants: handing a property back to the layer below only means anything when there is a layer below holding the component's own value.
 
-## Why `panel.css` is imported last
+This is the reason it is a utility rather than a component rule: it is a modifier applied to something else, not a thing of its own.
+
+## Why `panel.css` follows `modal.css` and `drawer.css`
 
 Inside `@layer components`, source order breaks ties between rules of equal specificity. Two facts combine here:
 
-1. Most of `panel.css` is wrapped in `:where()`, so it carries **zero specificity**. That is deliberate: it lets `.modal`, `.drawer` and your own overrides win without escalating.
+1. Most of [`panel.css`](../overlays/panel/) is wrapped in `:where()`, so it carries **zero specificity**. That is deliberate: it lets `.modal`, `.drawer` and your own overrides win without escalating.
 2. The `.panel-inline-*` variants must beat `.modal` and `.drawer`, and they are plain class selectors.
 
-Because those variants have no specificity advantage over the host components, they rely on arriving later in the file. Hence `@import 'components/panel.css';` sits last among the component imports in `css/index.css`.
+Because those variants have no specificity advantage over the host components, they rely on arriving later in the file. The alphabetical import order in `css/index.css` already puts `panel.css` after both, so nothing there looks out of the ordinary, but the constraint is real.
 
 If you import files individually, keep `panel.css` after `modal.css` and `drawer.css`.