@uncinq/css-components 1.16.3 → 1.16.5

package/README.md

@@ -81,6 +81,7 @@ Full documentation: **[socle.uncinq.dev/docs/css-components/](https://socle.unci
 
 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/) — [`.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)

package/css/utilities/scrollsnap.css

@@ -61,6 +61,7 @@
     justify-content: start;
     margin-inline: calc(var(--container-bleed, 0px) * -1);
     overflow-x: auto;
+    overflow-y: hidden;
     padding-inline: var(--container-bleed, var(--gutter));
     scroll-snap-type: x mandatory;
 

package/docs/_index.md

@@ -5,89 +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
-
-One page per component, grouped into six sections.
-
-| Section | Components |
-| --- | --- |
-| [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.
-
-## 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/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`.
-
-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
-
-**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 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
-
-- [@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

@@ -2,74 +2,6 @@
 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
+weight: 3
 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

@@ -2,7 +2,7 @@
 isIndex: false
 title: Close button
 description: The self-contained close control used inside panels, alerts and dismissible blocks.
-weight: 2
+weight: 3
 icon: x-lg
 ---
 

package/docs/buttons/btn-filter.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Filter button
 description: The filters toggle, a modifier on .btn carrying the filter icon.
-weight: 5
+weight: 6
 icon: funnel
 ---
 

package/docs/buttons/btn-menu.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Menu button
 description: The self-contained menu toggle, typically the burger in a site header.
-weight: 3
+weight: 4
 icon: list
 ---
 

package/docs/buttons/btn-search.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Search button
 description: The search toggle, a modifier on .btn carrying the search icon.
-weight: 4
+weight: 5
 icon: search
 ---
 

package/docs/buttons/btn-share.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Share button
 description: The share control, a modifier on .btn carrying the share icon.
-weight: 6
+weight: 7
 icon: share
 ---
 

package/docs/buttons/btn-toc.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Table of contents button
 description: The table of contents toggle, a modifier on .btn carrying the toc icon.
-weight: 7
+weight: 8
 icon: list-nested
 ---
 

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

@@ -2,7 +2,7 @@
 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
+weight: 9
 icon: play-circle
 ---
 

package/docs/buttons/btn.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Button
 description: The .btn base class, its ten colour variants, five sizes and three style variants.
-weight: 1
+weight: 2
 icon: hand-index-thumb
 ---
 

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.

package/docs/cascade-layers.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Cascade layers
 description: The two layers this package owns, why panel.css follows modal and drawer, and how to override a component cleanly.
-weight: 1
+weight: 2
 icon: stack
 ---
 

package/docs/content/_index.md

@@ -2,38 +2,6 @@
 isIndex: false
 title: Content
 description: Alerts, badges, banners, cards, the items grid, labelled lists, media objects and surtitles.
-weight: 4
+weight: 5
 icon: card-text
 ---
-
-Eight components for laying out page content.
-
-| Page | Class | Purpose |
-| --- | --- | --- |
-| [Alert](alert/) | `.alert` | An inline notification block |
-| [Badge](badge/) | `.badge` | A small inline label |
-| [Banner](banner/) | `.banner` | A centred modifier on `.alert` |
-| [Card](card/) | `.card` | A self-contained content card |
-| [Items](items/) | `.items` | The responsive grid that holds cards |
-| [List](list/) | `.list` | A compact labelled list |
-| [Media](media/) | `.media` | The structural base for images and video |
-| [Surtitle](surtitle/) | `.surtitle` | An eyebrow label above a heading |
-
-## Three of them are meant to nest
-
-`.items` holds `.card`, a card holds a `.media`, and a `.surtitle` sits above the card's title. Each one reassigns the next one's tokens from its own namespace, so a media block or a surtitle adapts to its context without a variant class. The [card page](card/) covers what it hands down.
-
-{{< alert-block state="info" >}}
-Several source comments describe `.card` as a backwards-compatible alias for `.item` and recommend 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 >}}
-
-## Colour variants follow one of two patterns
-
-`.alert` and `.badge` both ship the same ten intent names, and they resolve them differently.
-
-| | Background | Text |
-| --- | --- | --- |
-| `.alert-*` | `--color-*-muted` | `--color-*-strong` |
-| `.badge-*` | `--color-*` | `--color-text-on-*` |
-
-An alert is a tinted block meant to hold a paragraph, so it uses the muted pair. A badge is a solid chip meant to be read at a glance, so it uses the full colour with its guaranteed-contrast text token. Neither ever hardcodes a colour, which is what makes a rebrand a token change rather than a search and replace.

package/docs/content/alert.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Alert
 description: An inline notification block, with ten colour variants and an automatic horizontal layout when it leads with an icon.
-weight: 1
+weight: 2
 icon: exclamation-triangle
 ---
 

package/docs/content/badge.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Badge
 description: A small inline label, with ten solid colour variants and hover styles reserved for links.
-weight: 2
+weight: 3
 icon: tag
 ---
 

package/docs/content/banner.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Banner
 description: A centred modifier on .alert, for site-wide announcements.
-weight: 3
+weight: 4
 icon: megaphone
 ---
 

package/docs/content/card.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Card
 description: A self-contained content card, the tokens it hands down to its media, and the whole-card link pattern.
-weight: 4
+weight: 5
 icon: card-heading
 ---
 

package/docs/content/items.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Items
 description: A responsive grid whose column count is intrinsic rather than breakpoint-driven.
-weight: 5
+weight: 6
 icon: grid-3x2-gap
 ---
 

package/docs/content/list.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: List
 description: A compact labelled list, with the label as a sibling of the list rather than inside it.
-weight: 6
+weight: 7
 icon: list-ul
 ---
 

package/docs/content/media.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Media
 description: The structural base for images and video, holding the aspect ratio, plus the logo and icon variants.
-weight: 7
+weight: 8
 icon: image
 ---
 

package/docs/content/overview.md

@@ -0,0 +1,39 @@
+---
+isIndex: false
+title: Overview
+description: The eight content components, the three that are meant to nest, and the two colour patterns they follow.
+weight: 1
+icon: book
+---
+
+Eight components for laying out page content.
+
+| Page | Class | Purpose |
+| --- | --- | --- |
+| [Alert](../alert/) | `.alert` | An inline notification block |
+| [Badge](../badge/) | `.badge` | A small inline label |
+| [Banner](../banner/) | `.banner` | A centred modifier on `.alert` |
+| [Card](../card/) | `.card` | A self-contained content card |
+| [Items](../items/) | `.items` | The responsive grid that holds cards |
+| [List](../list/) | `.list` | A compact labelled list |
+| [Media](../media/) | `.media` | The structural base for images and video |
+| [Surtitle](../surtitle/) | `.surtitle` | An eyebrow label above a heading |
+
+## Three of them are meant to nest
+
+`.items` holds `.card`, a card holds a `.media`, and a `.surtitle` sits above the card's title. Each one reassigns the next one's tokens from its own namespace, so a media block or a surtitle adapts to its context without a variant class. The [card page](../card/) covers what it hands down.
+
+{{< alert-block state="info" >}}
+Several source comments describe `.card` as a backwards-compatible alias for `.item` and recommend 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 >}}
+
+## Colour variants follow one of two patterns
+
+`.alert` and `.badge` both ship the same ten intent names, and they resolve them differently.
+
+| | Background | Text |
+| --- | --- | --- |
+| `.alert-*` | `--color-*-muted` | `--color-*-strong` |
+| `.badge-*` | `--color-*` | `--color-text-on-*` |
+
+An alert is a tinted block meant to hold a paragraph, so it uses the muted pair. A badge is a solid chip meant to be read at a glance, so it uses the full colour with its guaranteed-contrast text token. Neither ever hardcodes a colour, which is what makes a rebrand a token change rather than a search and replace.

package/docs/content/surtitle.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Surtitle
 description: An eyebrow label above a heading, tightened automatically when it sits inside a card.
-weight: 8
+weight: 9
 icon: type-h2
 ---
 

package/docs/embeds/_index.md

@@ -2,24 +2,6 @@
 isIndex: false
 title: Embeds
 description: Aspect-ratio wrappers for third-party embeds, native video and maps.
-weight: 6
+weight: 7
 icon: play-btn
 ---
-
-Three containers, all built on the same idea: hold the space before the content arrives.
-
-| Page | Class | For |
-| --- | --- | --- |
-| [Embed](embed/) | `.embed` | Third-party iframes, players, social cards |
-| [Video](video/) | `.video` | A native `<video>`, with an optional pause control |
-| [Map](map/) | `.map` | A Leaflet map container |
-
-## They all reserve an aspect ratio
-
-An iframe, a video or a map that sizes itself once its content loads pushes the rest of the page down at an unpredictable moment. Each of these components declares `aspect-ratio` from a token, so the box exists at its final size from the first paint.
-
-That is also why all three set `overflow: hidden`: the content is stretched to fill a box whose proportions it did not choose.
-
-## They stop at the container
-
-None of the three ships the thing it wraps. `.embed` gives you no player, `.video` gives you no controls beyond the [toggle button](../buttons/btn-toggle-video/), and `.map` gives you neither Leaflet nor its stylesheet. Loading those, and keeping them out of your own layers, is the consuming project's job. See [Cascade layers](../cascade-layers/) for where third-party CSS belongs.

package/docs/embeds/embed.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Embed
 description: A responsive container for third-party embeds, holding an aspect ratio so the page does not reflow.
-weight: 1
+weight: 2
 icon: aspect-ratio
 ---
 

package/docs/embeds/map.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Map
 description: A Leaflet map container, and where Leaflet's own stylesheet belongs in the layer order.
-weight: 3
+weight: 4
 icon: map
 ---
 

package/docs/embeds/overview.md

@@ -0,0 +1,25 @@
+---
+isIndex: false
+title: Overview
+description: Three containers that reserve their aspect ratio before the content arrives, and stop at the container.
+weight: 1
+icon: book
+---
+
+Three containers, all built on the same idea: hold the space before the content arrives.
+
+| Page | Class | For |
+| --- | --- | --- |
+| [Embed](../embed/) | `.embed` | Third-party iframes, players, social cards |
+| [Video](../video/) | `.video` | A native `<video>`, with an optional pause control |
+| [Map](../map/) | `.map` | A Leaflet map container |
+
+## They all reserve an aspect ratio
+
+An iframe, a video or a map that sizes itself once its content loads pushes the rest of the page down at an unpredictable moment. Each of these components declares `aspect-ratio` from a token, so the box exists at its final size from the first paint.
+
+That is also why all three set `overflow: hidden`: the content is stretched to fill a box whose proportions it did not choose.
+
+## They stop at the container
+
+None of the three ships the thing it wraps. `.embed` gives you no player, `.video` gives you no controls beyond the [toggle button](../../buttons/btn-toggle-video/), and `.map` gives you neither Leaflet nor its stylesheet. Loading those, and keeping them out of your own layers, is the consuming project's job. See [Cascade layers](../../cascade-layers/) for where third-party CSS belongs.

package/docs/embeds/video.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Video
 description: A wrapper for a native video, positioning the optional pause control an autoplaying video needs.
-weight: 2
+weight: 3
 icon: camera-video
 ---
 

package/docs/forms/_index.md

@@ -2,30 +2,6 @@
 isIndex: false
 title: Forms
 description: The .form grid, the .form-check row, and where the actual control styling lives.
-weight: 7
+weight: 8
 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.
-
-| Page | Class | Covers |
-| --- | --- | --- |
-| [Form](form/) | `.form` | The two-column grid and its layout helpers |
-| [Check row](form-check/) | `.form-check` | A checkbox or radio laid out beside its label |
-
-Both live in `components/form.css`.
-
-## 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/forms/form-check.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Check row
 description: A checkbox or radio laid out beside its label, and why the class is only one declaration.
-weight: 2
+weight: 3
 icon: check-square
 ---
 
@@ -21,7 +21,7 @@ A checkbox or radio laid out inline with its label.
 .form-check { display: flex; }
 ```
 
-That is the entire rule, and it is deliberate. The control's appearance, its size, and the gap between it and the adjacent label all come from [css-base](../../../css-base/base/#forms), which styles `[type='checkbox'] + label` directly on the native elements.
+That is the entire rule, and it is deliberate. The control's appearance, its size, and the gap between it and the adjacent label all come from [css-base](../../../css-base/base/form-checkbox/), which styles `[type='checkbox'] + label` directly on the native elements.
 
 So the only thing missing from a bare input and label is that they sit on separate lines by default. This class fixes that, and stays out of everything else.
 

package/docs/forms/form.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Form
 description: A responsive grid that is one column or two, never three, plus its layout helpers.
-weight: 1
+weight: 2
 icon: columns-gap
 ---
 
@@ -64,4 +64,4 @@ Both axes use `--gap`, the same token the grid uses for its column calculation.
 
 ## Controls are not styled here
 
-Inputs, selects, textareas and their focus and invalid states come from [css-base](../../../css-base/base/#forms), applied to the native elements. This file adds layout and nothing else, which is why a form built without `.form` still looks right, it is simply stacked.
+Inputs, selects, textareas and their focus and invalid states come from [css-base](../../../css-base/base/form/), applied to the native elements. This file adds layout and nothing else, which is why a form built without `.form` still looks right, it is simply stacked.

package/docs/forms/overview.md

@@ -0,0 +1,31 @@
+---
+isIndex: false
+title: Overview
+description: The two form layout components, why the controls themselves are styled elsewhere, and the accessible names none of it supplies.
+weight: 1
+icon: book
+---
+
+Form **controls** are styled by [@uncinq/css-base](../../../css-base/base/form/), 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.
+
+| Page | Class | Covers |
+| --- | --- | --- |
+| [Form](../form/) | `.form` | The two-column grid and its layout helpers |
+| [Check row](../form-check/) | `.form-check` | A checkbox or radio laid out beside its label |
+
+Both live in `components/form.css`.
+
+## 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/_index.md

@@ -2,28 +2,6 @@
 isIndex: false
 title: Navigation
 description: Navigation lists, navigation titles, skip links, breadcrumbs and pagination.
-weight: 5
+weight: 6
 icon: signpost
 ---
-
-Five components for moving around a site.
-
-| Page | Class | Purpose |
-| --- | --- | --- |
-| [Nav](nav/) | `.nav` | The base navigation list |
-| [Nav title](nav-title/) | `.nav-title` | A label above a group of links |
-| [Skip links](nav-accessibility/) | `.nav-accessibility` | Skip navigation for keyboard and assistive technology |
-| [Breadcrumb](breadcrumb/) | `.breadcrumb-wrapper` | The breadcrumb trail |
-| [Pagination](pagination/) | `.pagination` | Page navigation |
-
-## Two of them take the class on the wrapper
-
-`.breadcrumb-wrapper` goes on the `<nav>`, not on the `<ol>` inside it. `.nav-accessibility` goes on the list itself, but only alongside `.nav`. Neither is guessable from the name, so check the page before writing the markup.
-
-## None of them supplies the landmark
-
-`<nav>`, `aria-label` and `aria-current` are yours to write. A page with three navigation regions and no labels on them is harder to use with a screen reader than a page with one, which is the usual reason to add them.
-
-## `.item` means two different things
-
-In [pagination](pagination/), `.item` is a page number. It is unrelated to the `.item` card unit mentioned throughout the [Content](../content/) section, which is not defined in this package at all.

package/docs/navigation/breadcrumb.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Breadcrumb
 description: The breadcrumb trail, with the class on the wrapper and the separator drawn from a token.
-weight: 4
+weight: 5
 icon: chevron-double-right
 ---
 

package/docs/navigation/nav-accessibility.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Skip links
 description: Skip navigation for keyboard and assistive technology users, hidden off-screen rather than hidden.
-weight: 3
+weight: 4
 icon: universal-access
 ---
 

package/docs/navigation/nav-title.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Nav title
 description: A label above a group of navigation links.
-weight: 2
+weight: 3
 icon: type
 ---
 

package/docs/navigation/nav.md

@@ -2,7 +2,7 @@
 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
+weight: 2
 icon: compass
 ---
 

package/docs/navigation/overview.md

@@ -0,0 +1,29 @@
+---
+isIndex: false
+title: Overview
+description: The five navigation components, the two that take their class on the wrapper, and the landmarks none of them supplies.
+weight: 1
+icon: book
+---
+
+Five components for moving around a site.
+
+| Page | Class | Purpose |
+| --- | --- | --- |
+| [Nav](../nav/) | `.nav` | The base navigation list |
+| [Nav title](../nav-title/) | `.nav-title` | A label above a group of links |
+| [Skip links](../nav-accessibility/) | `.nav-accessibility` | Skip navigation for keyboard and assistive technology |
+| [Breadcrumb](../breadcrumb/) | `.breadcrumb-wrapper` | The breadcrumb trail |
+| [Pagination](../pagination/) | `.pagination` | Page navigation |
+
+## Two of them take the class on the wrapper
+
+`.breadcrumb-wrapper` goes on the `<nav>`, not on the `<ol>` inside it. `.nav-accessibility` goes on the list itself, but only alongside `.nav`. Neither is guessable from the name, so check the page before writing the markup.
+
+## None of them supplies the landmark
+
+`<nav>`, `aria-label` and `aria-current` are yours to write. A page with three navigation regions and no labels on them is harder to use with a screen reader than a page with one, which is the usual reason to add them.
+
+## `.item` means two different things
+
+In [pagination](../pagination/), `.item` is a page number. It is unrelated to the `.item` card unit mentioned throughout the [Content](../../content/) section, which is not defined in this package at all.

package/docs/navigation/pagination.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Pagination
 description: Page navigation, with masked control glyphs and a built-in responsive collapse.
-weight: 5
+weight: 6
 icon: three-dots
 ---
 

package/docs/overlays/_index.md

@@ -2,33 +2,6 @@
 isIndex: false
 title: Overlays
 description: The shared panel skeleton behind .modal and .drawer, the two opening strategies, and the .dropdown contract.
-weight: 3
+weight: 4
 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

@@ -2,7 +2,7 @@
 isIndex: false
 title: Drawer
 description: The edge-pinned panel configuration and its four position variants.
-weight: 3
+weight: 4
 icon: layout-sidebar-reverse
 ---
 

package/docs/overlays/dropdown.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Dropdown
 description: A contextual menu positioned against its trigger, with a three-class transition contract.
-weight: 4
+weight: 5
 icon: caret-down-square
 ---
 

package/docs/overlays/modal.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Modal
 description: The centred panel configuration, and how it centres and shrinks to its content at once.
-weight: 2
+weight: 3
 icon: window
 ---
 

package/docs/overlays/overview.md

@@ -0,0 +1,34 @@
+---
+isIndex: false
+title: Overview
+description: Why .modal and .drawer are the same panel, where the class you apply actually lives, and what the four files expect from your JavaScript.
+weight: 1
+icon: book
+---
+
+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/panel.md

@@ -2,7 +2,7 @@
 isIndex: false
 title: Panel
 description: The shared skeleton behind .modal and .drawer, the two opening strategies, the inline variants and the backdrop.
-weight: 1
+weight: 2
 icon: layout-sidebar
 ---
 

package/docs/overview.md

@@ -0,0 +1,93 @@
+---
+isIndex: false
+title: Overview
+description: The 29 components and 1 utility, how to install them, the import order inside the package, and what it deliberately leaves out.
+weight: 1
+icon: book
+---
+
+`@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
+
+One page per component, grouped into six sections.
+
+| Section | Components |
+| --- | --- |
+| [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.
+
+## 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/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`.
+
+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
+
+**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 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
+
+- [@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/utilities/_index.md

@@ -2,20 +2,6 @@
 isIndex: false
 title: Utilities
 description: The one utility this package ships, and why it is a utility rather than a component rule.
-weight: 8
+weight: 9
 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/overview.md

@@ -0,0 +1,21 @@
+---
+isIndex: false
+title: Overview
+description: The one utility in the package, and the test for whether anything else belongs here.
+weight: 1
+icon: book
+---
+
+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/scrollsnap.md

@@ -2,7 +2,7 @@
 isIndex: false
 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
+weight: 2
 icon: arrow-left-right
 ---
 
@@ -62,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:
 

package/package.json

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