@uncinq/css-components 1.16.1 → 1.16.3

package/docs/navigation/nav.md

@@ -0,0 +1,65 @@
+---
+isIndex: false
+title: Nav
+description: The base navigation list, vertical by default, whose direction is set by context rather than by a modifier class.
+weight: 1
+icon: compass
+---
+
+The base navigation list, vertical by default.
+
+```html
+<ul class="nav">
+  <li><a href="/">Home</a></li>
+  <li><a href="/about">About</a></li>
+</ul>
+```
+
+Works on `ul` or `ol`.
+
+## Direction is set by context, not by a modifier
+
+There is no `.nav-horizontal`. The direction comes from a token:
+
+```css
+flex-direction: var(--nav-direction, column);
+```
+
+so a header lays its own navigation out horizontally by setting `--nav-direction: row` on it, or `flex-direction` directly. That keeps the component free of layout variants that would only ever be used in one place, and it means the same list is a column in a drawer and a row in a header without a class change.
+
+## Nested lists inherit the layout
+
+```css
+&,
+:is(ul, ol) { display: flex; flex-direction: var(--nav-direction, column); ... }
+```
+
+The rule matches the nav **and** every list inside it, so a submenu needs no second `.nav` class. Note that a nested list inherits `--nav-direction` too, so a horizontal header menu gets horizontal submenus unless the submenu resets it.
+
+## Links
+
+`a:where(:not(.btn))` and `li > span` are styled together, so a non-link entry, the current page rendered as text, lines up with the links around it. `.btn` is excluded through `:where()`, which adds no specificity, so a call to action inside a navigation keeps its own styling.
+
+The current entry is marked with a class on the link:
+
+```html
+<li><a href="/about" class="active" aria-current="page">About</a></li>
+```
+
+```css
+&.active { --nav-color-text: var(--nav-color-text-active); }
+```
+
+The class drives the colour; `aria-current` is what a screen reader announces. Write both.
+
+## Highlighted items
+
+`.nav-item-highlighted` tightens the line height and pulls the item out to the nav's own inline padding, for an entry rendered as a block rather than as a line of text.
+
+## Dropdowns inside a nav
+
+`.dropdown-toggle` is restyled to take `--nav-color-text`, so a [dropdown](../../overlays/dropdown/) in a header menu matches the links beside it. Nothing else about the dropdown changes.
+
+## Inside a panel
+
+A `.modal` or `.drawer` publishes `--nav-color-text` from its own text colour, so a navigation inside a panel follows the panel's palette. Going inline with [`.panel-inline-*`](../../overlays/panel/#inline-variants) hands that token back to the page, which is why a drawer menu that becomes a sidebar column changes colour at the breakpoint.

package/docs/navigation/pagination.md

@@ -0,0 +1,77 @@
+---
+isIndex: false
+title: Pagination
+description: Page navigation, with masked control glyphs and a built-in responsive collapse.
+weight: 5
+icon: three-dots
+---
+
+A page navigation list.
+
+```html
+<nav aria-label="Pagination">
+  <ul class="pagination">
+    <li class="disabled"><a class="first">First</a></li>
+    <li><a class="previous" href="?page=1">Previous</a></li>
+    <li class="item active"><a href="?page=2">2</a></li>
+    <li class="item item-adjacent"><a href="?page=3">3</a></li>
+    <li><a class="next" href="?page=3">Next</a></li>
+    <li><a class="last" href="?page=9">Last</a></li>
+  </ul>
+</nav>
+```
+
+| Class | On | Role |
+| --- | --- | --- |
+| `.first`, `.previous`, `.next`, `.last` | the `a` | Navigation controls |
+| `.item` | the `li` | A page number |
+| `.item-adjacent` | the `li` | A page number next to the current one |
+| `.active` | the `li` | The current page |
+| `.disabled` | the `li` | An unavailable control |
+
+`.active` and `.disabled` are both read as ancestors of the link (`.active a`, `.disabled a`), so putting either on the `li` is what the rules expect.
+
+## The glyphs are shipped
+
+Each control draws a mask on `::after` from its own token:
+
+```css
+.next::after { mask: var(--pagination-icon-next) center / var(--pagination-icon-size) no-repeat; }
+```
+
+Four tokens, `--pagination-icon-first`, `-previous`, `-next` and `-last`, sized by `--pagination-icon-size`. The two backwards controls reuse their forwards glyph and rotate it:
+
+```css
+.first::after    { mask: var(--pagination-icon-first) ...;    rotate: 180deg; }
+.previous::after { mask: var(--pagination-icon-previous) ...; rotate: 180deg; }
+```
+
+So a themed arrow only has to exist in one direction. Because the glyph is a mask over `currentColor`, it follows the link colour through hover, active and disabled without a second declaration.
+
+The text inside the control (`First`, `Previous`) sits beside the glyph. Replace it with a `.visually-hidden` span if the design wants icons alone; do not remove it, or the control loses its accessible name.
+
+## The responsive collapse is built in
+
+```css
+@media not (--sm) {
+  .first, .last,
+  li:has(.first), li:has(.last),
+  .item:not(.item-adjacent):not(.active) { display: none; }
+}
+```
+
+Below 768px the paginator drops to *previous, the current page, its neighbours, next*. You do not need to write that rule, and you do not need a second markup path for mobile: render the full paginator and let CSS thin it out.
+
+This is what `.item-adjacent` is for. It is the only signal the CSS has about which page numbers are near the current one, so a paginator that omits it collapses to the current page alone on a narrow screen.
+
+The `li:has(...)` selectors are there so the list item goes with the control it contains, rather than leaving an empty `li` contributing a gap.
+
+## States
+
+`.active a` and `.disabled a` both get `pointer-events: none`, so neither is clickable regardless of whether you render an `href`. The active page takes the `-active` colour pair, and a disabled control takes `--pagination-disabled-opacity`.
+
+Note that the hover rule here is **not** behind `@media (hover: hover) and (pointer: fine)`, unlike the rest of the package. On a touch device a tapped page number can keep its hover background until the next paint.
+
+## Accessibility
+
+The `<nav>` and its `aria-label` are yours to write; the component styles the list only. Mark the current page with `aria-current="page"` on the link as well as `.active` on the item, so the state is announced and not merely coloured.

package/docs/overlays/_index.md

@@ -0,0 +1,34 @@
+---
+isIndex: false
+title: Overlays
+description: The shared panel skeleton behind .modal and .drawer, the two opening strategies, and the .dropdown contract.
+weight: 3
+icon: window-stack
+---
+
+Four files, and a design worth understanding before reading any of them.
+
+| Page | Covers |
+| --- | --- |
+| [Panel](panel/) | The shared skeleton, `.panel-inline-*`, `.panel-trigger-*`, the backdrop and the JavaScript contract |
+| [Modal](modal/) | `.modal`, the centred configuration |
+| [Drawer](drawer/) | `.drawer` and its four edge variants |
+| [Dropdown](dropdown/) | `.dropdown`, a contextual menu with its own contract |
+
+## `.modal` and `.drawer` are the same panel
+
+Same structure, header and content and footer. Same open and closed contract. Same backdrop. They differ only in where they sit: modal centres them, drawer pins them to an edge.
+
+`components/panel.css` owns **every rule**. The two variants are pure configuration, declaring nothing but `--panel-*` tokens.
+
+There is **no `.panel` class to apply.** The file targets `:where(.modal, .drawer)` directly, so the skeleton arrives with either variant class. `panel` names the shared concept and the token namespace, not a class.
+
+Each variant aliases `--panel-*` from its own namespace, so `--modal-*` and `--drawer-*` remain the public API. Override those.
+
+## The tag picks the strategy, not the class
+
+Either variant works both ways, and the choice is an accessibility one rather than a styling one. See [Two ways to open a panel](panel/#two-ways-to-open-a-panel).
+
+## No JavaScript ships here
+
+`.modal`, `.drawer` and `.dropdown` all expect a script. The CSS defines the classes and attributes that script must toggle; each page documents the contract it needs.

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.1",
+  "version": "1.16.3",
   "description": "Framework-agnostic CSS component implementations.",
   "license": "MIT",
   "repository": {