@uncinq/css-components 1.16.2 → 1.16.4

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: 2
+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/container/#the---container-bleed-contract). The property inherits, so it reaches the row from a `.container` however far up it sits.
 
 Outside a container there is no published value, and the two `var()` fallbacks differ **on purpose**, because margin and padding answer different questions:
 
@@ -65,3 +76,9 @@ Inside a container the two collapse to one value: both read the published bleed,
 `scroll-margin-inline` follows the **padding**, not the margin. It is what makes an item snap flush with the content edge rather than the padding edge, so it has to cancel the padding whatever the margin does.
 
 This is the same reasoning as the `--container-bleed` contract itself, applied to a scroll container. If you write your own full-bleed component, copy the pair rather than picking one fallback for both.
+
+## It needs a build step
+
+The four responsive variants are written with `@media (--sm)` and its siblings, which rely on the `@custom-media` rules declared in css-base. No browser implements `@custom-media`, so without [postcss-custom-media](https://www.npmjs.com/package/postcss-custom-media) every `.scrollsnap-*` variant becomes a permanent carousel: the base block applies and the block that hands the grid back is dropped.
+
+The failure is silent. See [the package index](../../).

package/package.json

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

package/docs/buttons.md

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

package/docs/content.md

@@ -1,145 +0,0 @@
----
-isIndex: false
-title: Content
-description: Alerts, badges, banners, cards, the items grid, labelled lists, media objects and surtitles.
-weight: 4
-icon: card-text
----
-
-## `.alert`
-
-An inline notification block.
-
-```html
-<div class="alert alert-info">
-  <p class="alert-heading">Heads up</p>
-  <p>Your changes were saved.</p>
-</div>
-```
-
-Variants: `.alert-primary`, `.alert-secondary`, `.alert-brand`, `.alert-neutral`, `.alert-dark`, `.alert-light`, `.alert-success`, `.alert-danger`, `.alert-warning`, `.alert-info`.
-
-Each sets the background, border and text colour from the matching `-muted` and `-strong` semantic tokens, so the pairing stays legible if the underlying colour changes.
-
-Two behaviours are worth knowing. `--color-link` is reassigned to the alert's own text colour, so links inside an alert do not fall back to the page link colour against a tinted background. And an alert whose first child is an `.icon`, with no `.alert-heading`, switches to a horizontal layout automatically.
-
-`.container` inside an alert inherits the same flex layout, which is what lets a full-bleed alert keep its content aligned with the rest of the page.
-
-## `.banner`
-
-A thin variation on the alert, centred rather than start-aligned. It sets `--alert-align: center` and flattens paragraph margins, and nothing else.
-
-```html
-<div class="alert banner">
-  <p>Site-wide announcement.</p>
-</div>
-```
-
-It is a modifier on `.alert`, so use both classes.
-
-## `.badge`
-
-A small inline label.
-
-```html
-<span class="badge badge-success">Published</span>
-<a class="badge" href="/tag/css">css</a>
-```
-
-Variants mirror the alert set: `.badge-primary`, `.badge-secondary`, `.badge-brand`, `.badge-neutral`, `.badge-dark`, `.badge-light`, `.badge-success`, `.badge-danger`, `.badge-warning`, `.badge-info`.
-
-Hover styles apply only to `a.badge`, guarded by `@media (hover: hover) and (pointer: fine)`, so a static badge never looks interactive.
-
-## `.card`
-
-A self-contained content card.
-
-```html
-<article class="card">
-  <div class="content">
-    <p class="surtitle">Category</p>
-    <p class="title">Card title</p>
-    <p class="description">Short description.</p>
-  </div>
-  <div class="media">
-    <picture>...</picture>
-  </div>
-</article>
-```
-
-The media block sits first visually, through `--card-media-order: -1`, regardless of its position in the markup. Put it after the content so that screen readers and search engines reach the text first.
-
-Wrapping the content in `a.content` makes the whole card clickable, using a `::before` overlay that covers the card. Focus is then handled on the card itself with `:has(a.content:focus-visible)`, so the focus ring outlines the card rather than an invisible box. Nested interactive elements inside such a card will be unreachable, which is the known trade-off of this pattern.
-
-Sizing with `--card-max-width` and `--card-width` is unset by default. Prefer `ch` units, so the width tracks the text measure.
-
-{{< alert-block state="info" >}}
-The source comment in `card.css` describes `.card` as a backwards-compatible alias for `.item` and recommends using `.item` directly. That is misleading for anyone consuming this package on its own: **`.item` is not defined here**. It lives in the Hugolify design system theme. Within `@uncinq/css-components`, `.card` is a complete implementation and the class to use.
-{{< /alert-block >}}
-
-## `.items`
-
-A responsive grid, and the usual container for cards.
-
-```html
-<div class="items">
-  <article class="card">...</article>
-  <article class="card">...</article>
-</div>
-```
-
-The column count is intrinsic rather than breakpoint-driven:
-
-```css
-grid-template-columns: repeat(
-  var(--items-cols, auto-fill),
-  minmax(min(var(--items-min-width, var(--max-width-item)), 100%), 1fr)
-);
-```
-
-Items wrap when they no longer fit at `--items-min-width`, with no media query involved. Set `--items-cols` to a number to force a fixed count instead.
-
-It also declares `container-type: inline-size` and `container-name: items`, so children can use container queries against the grid rather than the viewport.
-
-Pair it with [`.scrollsnap`](../utilities/) to turn the grid into a horizontal carousel below a given breakpoint.
-
-## `.list`
-
-A compact labelled list with dash markers.
-
-```html
-<div class="list">
-  <p>Optional label</p>
-  <ul>
-    <li>First</li>
-    <li>Second</li>
-  </ul>
-</div>
-```
-
-The wrapper is a `div`, with the label as a sibling of the list rather than inside it. Either `ul` or `ol` works.
-
-## `.media`
-
-The structural base for media blocks, controlling aspect ratio, background and border.
-
-| Class | Use |
-| --- | --- |
-| `.media` | Base, for a picture or video |
-| `.media-logo` | Logo, typically contained rather than cropped |
-| `.media-icon` | Icon, sized from `--icon-size` |
-
-`.media-logo` and `.media-icon` build on `.media`. Inside a `.card`, the card reassigns `--media-color-background` and `--media-ratio` from its own `--card-media-*` tokens, so a media block adapts to its context without a variant class.
-
-A `.video` inside a `.media` is stretched to fill it. See [Embeds](../embeds/).
-
-## `.surtitle`
-
-An eyebrow label above a heading.
-
-```html
-<p class="surtitle">Category</p>
-<h2>Main title</h2>
-```
-
-Inside a `.card` it gets a negative `--surtitle-margin-block-end`, pulling it closer to the title so the pair reads as one unit.

package/docs/embeds.md

@@ -1,66 +0,0 @@
----
-isIndex: false
-title: Embeds
-description: Aspect-ratio wrappers for third-party embeds, native video and maps.
-weight: 6
-icon: play-btn
----
-
-## `.embed`
-
-A responsive container for third-party embeds, holding an aspect ratio so the page does not reflow once the iframe loads.
-
-```html
-<div class="embed">
-  <iframe src="https://..." title="Video title" allowfullscreen></iframe>
-</div>
-```
-
-Accepts `iframe`, `video`, `embed` or `object` as its child. The ratio comes from `--embed-ratio`, which defaults to the video ratio token. Override it per instance for a square or portrait embed:
-
-```html
-<div class="embed" style="--embed-ratio: 1">...</div>
-```
-
-Always give the `iframe` a `title`. It is the only accessible name an embedded frame has.
-
-## `.video`
-
-A wrapper for a **native** `<video>`, as opposed to an embedded player.
-
-```html
-<div class="video">
-  <video autoplay muted loop playsinline></video>
-  <button class="btn btn-toggle-video is-playing" aria-label="Pause">
-    <span class="icon-pause"></span>
-    <span class="icon-play"></span>
-  </button>
-</div>
-```
-
-The wrapper positions the optional toggle control over the video. Inside a `.media`, the wrapper is stretched to fill it, so a video and an image are interchangeable within a card.
-
-The control is there for a reason rather than for decoration. A video that autoplays without native controls must be pausable to meet WCAG, which is exactly what `.btn-toggle-video` provides. If your video carries `controls`, you do not need it. See [Buttons](../buttons/#btn-toggle-video) for the `.is-playing` contract.
-
-## `.map`
-
-A map container, driven by Leaflet through a `js-map` hook.
-
-```html
-<div class="map js-map"
-     data-markers="[...]"
-     data-zoom="12"
-     data-tile="3"
-     data-marker-hidden="false"></div>
-```
-
-| Attribute | Role |
-| --- | --- |
-| `data-markers` | The markers to plot |
-| `data-zoom` | Initial zoom level |
-| `data-tile` | Tile layer selection |
-| `data-marker-hidden` | Whether markers start hidden |
-
-This package provides the container only: sizing, background and border. Leaflet itself, its stylesheet and the script reading those attributes are yours to supply.
-
-Leaflet's own CSS is a good example of why the layer order matters. Import it into `@layer libs` and any adjustments you write into `@layer vendors`, so that a lazily loaded Leaflet cannot outrank your own rules on source order. See [Cascade layers](../cascade-layers/).

package/docs/forms.md

@@ -1,80 +0,0 @@
----
-isIndex: false
-title: Forms
-description: The .form grid, its layout helpers, and where the actual control styling lives.
-weight: 7
-icon: ui-checks
----
-
-Form **controls** are styled by [@uncinq/css-base](../../css-base/base/#forms), on the native elements themselves. There is no `.input` or `.select` class to apply.
-
-This package adds only what css-base cannot: the layout around those controls.
-
-## `.form`
-
-A responsive two-column grid that collapses to one column when there is not enough room.
-
-```html
-<form class="form">
-  <div>
-    <label for="first">First name</label>
-    <input id="first" type="text">
-  </div>
-  <div>
-    <label for="last">Last name</label>
-    <input id="last" type="text">
-  </div>
-  <div class="full">
-    <label for="message">Message</label>
-    <textarea id="message"></textarea>
-    <p class="help">Markdown is supported.</p>
-  </div>
-  <div class="actions">
-    <button class="btn" type="submit">Send</button>
-  </div>
-</form>
-```
-
-The column rule is worth reading once:
-
-```css
-grid-template-columns: repeat(
-  auto-fill,
-  minmax(max(var(--form-col-min-width, 25ch), calc(50% - var(--gap) / 2)), 1fr)
-);
-```
-
-The `max()` sets a floor of `25ch` **and** caps the result at half the width. The effect is a form that is one column or two, never three, however wide the container gets. A three-column form is almost never what you want, because it breaks the vertical reading order of a sequence of fields.
-
-Change the floor with `--form-col-min-width`.
-
-## Layout helpers
-
-| Class | Effect |
-| --- | --- |
-| `.full` | Spans both columns, `grid-column: 1 / -1` |
-| `.actions` | Spans both columns and stacks its children vertically |
-| `.help` | Help text under a field |
-| `.form-check` | A checkbox or radio laid out inline with its label |
-
-```html
-<div class="form-check">
-  <input id="terms" type="checkbox">
-  <label for="terms">I accept the terms</label>
-</div>
-```
-
-`.form-check` is deliberately minimal, just `display: flex`. The checkbox and radio appearance, including the gap with the adjacent label, comes from css-base, which styles `[type='checkbox'] + label` directly.
-
-## Accessibility
-
-Nothing here supplies an accessible name. Every control needs a `<label for>` pointing at its `id`, or a `.visually-hidden` label when the design has no room for a visible one.
-
-Tie `.help` text to its field with `aria-describedby`, otherwise it is visible but never announced:
-
-```html
-<input id="message" aria-describedby="message-help">
-<p class="help" id="message-help">Markdown is supported.</p>
-```
-
-For error states, use `aria-invalid="true"` on the control and point `aria-describedby` at the error message.

package/docs/navigation.md

@@ -1,93 +0,0 @@
----
-isIndex: false
-title: Navigation
-description: Navigation lists, skip links, breadcrumbs and pagination.
-weight: 5
-icon: signpost
----
-
-## `.nav`
-
-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 class**: a header lays its nav out horizontally by setting `flex-direction: row` on it. That keeps the component free of layout variants that would only ever be used in one place.
-
-## `.nav-title`
-
-A title within a navigation block, for labelling a group of links.
-
-## `.nav-accessibility`
-
-Skip links, for keyboard and assistive technology users.
-
-```html
-<ul class="nav nav-accessibility">
-  <li><a href="#main">Skip to content</a></li>
-  <li><a href="#navigation">Skip to navigation</a></li>
-  <li><a href="#footer">Skip to footer</a></li>
-</ul>
-```
-
-Three things matter here, and getting any of them wrong defeats the purpose:
-
-**It must be the first focusable element in `<body>`.** A skip link that comes after the navigation it skips is useless.
-
-**It is hidden off-screen, not hidden.** It slides into view when a child receives focus. Using `display: none` would remove it from the tab order entirely.
-
-**It requires the `.nav` base class** alongside it.
-
-The targets must exist and be focusable. An `id` on a non-interactive element needs `tabindex="-1"` for the jump to move focus rather than just scroll.
-
-## `.breadcrumb-wrapper`
-
-The breadcrumb trail. Note that the class goes on the **wrapper**, not on the list itself.
-
-```html
-<nav class="breadcrumb-wrapper" aria-label="Breadcrumb">
-  <ol>
-    <li><a href="/">Home</a></li>
-    <li><a href="/docs">Docs</a></li>
-    <li aria-current="page">Navigation</li>
-  </ol>
-</nav>
-```
-
-The separator is drawn from `--breadcrumb-separator`, which defaults to `"/"`. Mark the current page with `aria-current="page"` rather than relying on it being last.
-
-## `.pagination`
-
-A page navigation list.
-
-```html
-<nav role="navigation" aria-label="Pagination">
-  <ul class="pagination">
-    <li class="disabled"><a class="first">First</a></li>
-    <li><a class="previous">Previous</a></li>
-    <li class="item active"><a href="?page=1">1</a></li>
-    <li class="item item-adjacent"><a href="?page=2">2</a></li>
-    <li><a class="next">Next</a></li>
-    <li><a class="last">Last</a></li>
-  </ul>
-</nav>
-```
-
-| Class | Role |
-| --- | --- |
-| `.first`, `.previous`, `.next`, `.last` | Navigation controls, on the `a` |
-| `.item` | A page number, on the `li` |
-| `.item-adjacent` | A page number next to the current one |
-| `.active` | The current page |
-| `.disabled` | An unavailable control, on the `li` |
-
-`.item-adjacent` exists so that a responsive paginator can hide distant page numbers while keeping the immediate neighbours visible, which is the usual mobile treatment.
-
-**The glyphs for `.first`, `.last`, `.previous` and `.next` are not provided.** This package positions and spaces them; the theme supplies the arrow through `a::before` or `a::after` content. A paginator with no theme styling will show the text labels only, which is a reasonable fallback but rarely what you want visually.
-
-Note that `.item` here means a pagination entry, and is unrelated to the `.item` card unit mentioned in [Content](../content/).