@uncinq/css-components 1.16.2 → 1.16.3

package/docs/content/_index.md

@@ -0,0 +1,39 @@
+---
+isIndex: false
+title: Content
+description: Alerts, badges, banners, cards, the items grid, labelled lists, media objects and surtitles.
+weight: 4
+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

@@ -0,0 +1,97 @@
+---
+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
+icon: exclamation-triangle
+---
+
+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 background, border and text colour from the matching `-muted` and `-strong` semantic tokens, so the pairing stays legible if the underlying colour changes.
+
+```css
+.alert-success {
+  --alert-color-background: var(--color-success-muted);
+  --alert-color-border: var(--color-success-muted);
+  --alert-color-text: var(--color-success-strong);
+}
+```
+
+`.alert-primary` and `.alert-brand` resolve identically, as do `.alert-secondary` and `.alert-neutral`. `.alert-dark` is the one exception to the muted pattern: it takes `--color-text-on-dark` rather than `--color-dark-strong`.
+
+The base `.alert` declares no colours of its own, so an alert with no variant class shows whatever `--alert-color-*` resolves to in your token set.
+
+## Links inside an alert
+
+`--color-link` is reassigned to the alert's own text colour:
+
+```css
+.alert { --color-link: var(--alert-color-text); }
+```
+
+Without that, a link inside a tinted block would fall back to the page link colour, which is chosen for contrast against the page background rather than against a muted tint.
+
+## Leading with an icon
+
+An alert whose first child is an `.icon`, and which has no `.alert-heading`, switches to a horizontal layout on its own:
+
+```css
+&:has(.icon:first-child):not(:has(.alert-heading)) {
+  flex-direction: row;
+  align-items: flex-start;
+}
+```
+
+```html
+<div class="alert alert-warning">
+  <span class="icon icon-triangle-alert"></span>
+  <p>This action cannot be undone.</p>
+</div>
+```
+
+With a heading present the alert stays stacked, because the icon then belongs beside the heading rather than beside the whole block. `.alert-heading` is itself a flex row with `--spacing-xs` between its children, so an icon inside the heading lines up with the text.
+
+## `.container` inside an alert
+
+`.container` inherits the same flex layout as the alert itself:
+
+```css
+&,
+.container {
+  display: flex;
+  flex-direction: var(--alert-direction, column);
+  gap: var(--alert-gap);
+}
+```
+
+That is what lets a full-bleed alert keep its content aligned with the rest of the page: the alert spans the viewport, the container inside it caps the measure, and both lay their children out the same way.
+
+## Hiding an alert
+
+`.alert` declares `display: flex`, which would otherwise beat the user agent rule for `[hidden]`. The file restores it:
+
+```css
+.alert[hidden] { display: none; }
+```
+
+So a dismissible alert can be hidden with the attribute alone, with no state class to manage:
+
+```js
+alert.hidden = true;
+```
+
+## Margins
+
+`.alert *` sets `margin-block: 0` on every descendant, so paragraphs inside an alert are spaced by the flex `gap` rather than by their own margins. Vertical rhythm around the alert itself comes from `--alert-margin`.

package/docs/content/badge.md

@@ -0,0 +1,50 @@
+---
+isIndex: false
+title: Badge
+description: A small inline label, with ten solid colour variants and hover styles reserved for links.
+weight: 2
+icon: tag
+---
+
+A small inline label.
+
+```html
+<span class="badge badge-success">Published</span>
+<a class="badge" href="/tag/css">css</a>
+```
+
+It is `inline-flex`, so it sits in a line of text and can hold an icon beside its label.
+
+## Variants
+
+The names mirror the [alert](../alert/) set: `.badge-primary`, `.badge-secondary`, `.badge-brand`, `.badge-neutral`, `.badge-dark`, `.badge-light`, `.badge-success`, `.badge-danger`, `.badge-warning`, `.badge-info`.
+
+The colours do not. A badge is a **solid** chip, not a tinted block:
+
+```css
+.badge-success {
+  --badge-color-background: var(--color-success);
+  --badge-color-background-hover: var(--color-success-strong);
+  --badge-color-text: var(--color-text-on-success);
+}
+```
+
+Full colour for the background, and the matching `--color-text-on-*` token for the text, which is the pair that guarantees contrast when the underlying colour is overridden. Compare with `.alert-*`, which uses `-muted` and `-strong` because it has to remain readable behind a paragraph.
+
+Note that a variant sets no border colour. `--badge-color-border` keeps whatever the base token resolves to, so a bordered badge needs that token set explicitly.
+
+## Hover is reserved for links
+
+```css
+@media (hover: hover) and (pointer: fine) {
+  a.badge:hover { ... }
+}
+```
+
+Two guards, doing two different jobs. The element selector means a static `<span class="badge">` never looks interactive, which matters because badges are used for both states and actions. The media query means a tap on a touch device does not leave the badge stuck in its hover colour.
+
+Both hover values fall back to the resting one, so a variant that defines no hover colour simply does not change on hover rather than resolving to nothing.
+
+## Text decoration
+
+The base rule sets `text-decoration: none`, so `a.badge` never carries the page's link underline. That is the one thing the class overrides on a link; everything else it leaves to the variant.

package/docs/content/banner.md

@@ -0,0 +1,43 @@
+---
+isIndex: false
+title: Banner
+description: A centred modifier on .alert, for site-wide announcements.
+weight: 3
+icon: megaphone
+---
+
+A thin variation on the [alert](../alert/), centred rather than start-aligned.
+
+```html
+<div class="alert banner">
+  <p>Site-wide announcement.</p>
+</div>
+```
+
+**It is a modifier, so use both classes.** `.banner` on its own has no background, no border and no padding.
+
+## The whole component
+
+```css
+.banner {
+  --alert-align: center;
+
+  p { margin-block: 0; }
+}
+```
+
+That is the entire file. `--alert-align` feeds both `align-items` and `text-align` in the alert rule, so one token centres the block on both axes at once. The paragraph reset flattens the margins that would otherwise show up when the banner holds a single line.
+
+## Variants come from the alert
+
+Every `.alert-*` colour works here, because the variant only sets `--alert-color-*` tokens and the banner only sets alignment:
+
+```html
+<div class="alert alert-warning banner">
+  <p>Scheduled maintenance on Sunday.</p>
+</div>
+```
+
+## Full-bleed announcements
+
+A banner is usually the one alert that spans the viewport. Put a `.container` inside it rather than constraining the banner itself: the alert passes its flex layout down to `.container`, so the announcement stays aligned with the rest of the page while the tint runs edge to edge. See [the alert page](../alert/#container-inside-an-alert).

package/docs/content/card.md

@@ -0,0 +1,93 @@
+---
+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
+icon: card-heading
+---
+
+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>
+```
+
+| Child | Role |
+| --- | --- |
+| `.content` | The text block, grows to fill the card |
+| `.title` | The heading line, styled from `--card-title-*` |
+| `.description` | The body text, at `--card-font-size` |
+| `.media` | The image or video, see [Media](../media/) |
+| `.surtitle` | An optional eyebrow, see [Surtitle](../surtitle/) |
+
+{{< 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 >}}
+
+## Put the media last in the markup
+
+The media block sits first **visually**, through `--card-media-order: -1`, regardless of where it appears in the source. Put it after the content so that screen readers and search engines reach the text first.
+
+Set `--card-media-order` to anything else, or to `initial`, to put the image below the text on a given card.
+
+## What the card hands down
+
+Three reassignments at the top of the rule:
+
+```css
+--media-color-background: var(--card-media-color-background);
+--media-ratio: var(--card-media-ratio);
+--surtitle-margin-block-end: calc(var(--card-gap) * -1);
+```
+
+A [`.media`](../media/) inside a card therefore takes the card's ratio and background without any variant class, and a [`.surtitle`](../surtitle/) is pulled back by exactly one gap so that it reads as part of the title rather than as a separate line.
+
+`.media-icon` gets a longer handover of its own, mapping eight `--card-media-icon-*` tokens onto the media namespace, which is what lets an icon card look nothing like a photo card while using the same two classes.
+
+## The whole-card link
+
+Wrapping the content in `a.content` makes the entire card clickable:
+
+```html
+<article class="card">
+  <a class="content" href="/article">
+    <p class="title">Card title</p>
+    <p class="description">Short description.</p>
+  </a>
+  <div class="media">...</div>
+</article>
+```
+
+The link lays a `::before` overlay across the card, and its own focus ring is suppressed so the focus outline can be drawn on the card instead:
+
+```css
+a.content::before { content: ''; inset: 0; position: absolute; }
+a.content:focus-visible { outline: none; }
+
+.card:has(a.content:focus-visible) {
+  outline: var(--focus-outline-width) var(--focus-outline-style) var(--focus-color-outline);
+}
+```
+
+Without the `:has()` rule the ring would outline an invisible box, which is the usual failure of this pattern.
+
+Two things to know before using it. **Nested interactive elements become unreachable**, since the overlay covers them: a card with both a whole-card link and a button inside needs a different structure. And the overlay resolves against the nearest positioned ancestor, so the card must establish one; give it `position: relative` if your layout does not already.
+
+## Sizing
+
+`--card-max-width` and `--card-width` are unset by default, so a card fills its grid track. Prefer `ch` units when you do set them, so the width tracks the text measure rather than a fixed pixel count.
+
+`overflow: hidden` on the card is what lets `--card-border-radius` clip a full-bleed media block at the corners.
+
+## States
+
+Hover swaps the shadow, `--card-shadow` taking `--card-shadow-hover`, behind `@media (hover: hover) and (pointer: fine)`. The transition is behind `prefers-reduced-motion`. There is no hover colour change, deliberately: a card that changes background on hover competes with the link inside it.

package/docs/content/items.md

@@ -0,0 +1,76 @@
+---
+isIndex: false
+title: Items
+description: A responsive grid whose column count is intrinsic rather than breakpoint-driven.
+weight: 5
+icon: grid-3x2-gap
+---
+
+A responsive grid, and the usual container for [cards](../card/).
+
+```html
+<div class="items">
+  <article class="card">...</article>
+  <article class="card">...</article>
+  <article class="card">...</article>
+</div>
+```
+
+The children are yours to provide. Within this package that means `.card`; `.item` is defined by the Hugolify design system theme, not here.
+
+## The column count is intrinsic
+
+```css
+grid-template-columns: repeat(
+  var(--items-cols, auto-fill),
+  minmax(min(var(--items-min-width, var(--max-width-item)), 100%), 1fr)
+);
+```
+
+Items wrap once they no longer fit at `--items-min-width`, **with no media query involved**. The grid answers to the width of its container rather than to the width of the viewport, so the same markup works in a page, in a sidebar and inside another grid.
+
+The inner `min(..., 100%)` is what keeps a single item from overflowing a container narrower than `--items-min-width`. Without it, a 30ch minimum in a 20ch column would blow out the layout.
+
+Two ways to change the result:
+
+| Token | Effect |
+| --- | --- |
+| `--items-min-width` | The width below which items wrap. Defaults to `--max-width-item` |
+| `--items-cols` | A fixed column count, replacing `auto-fill` |
+
+```css
+.related { --items-cols: 2; }
+```
+
+## Gaps
+
+`--items-gap` sets both axes. `--items-column-gap` and `--items-row-gap` override one at a time, each falling back to `--items-gap`.
+
+## It is a container query context
+
+```css
+container-type: inline-size;
+container-name: items;
+```
+
+So children can query the grid rather than the viewport:
+
+```css
+@container items (min-width: 60ch) {
+  .card { --card-media-order: initial; }
+}
+```
+
+That is the companion to the intrinsic columns: the grid decides how many tracks fit, and the children adapt to the space they actually got.
+
+Be aware that `container-type: inline-size` makes the grid its own containment context, which affects how absolutely positioned descendants resolve.
+
+## Turning it into a carousel
+
+Add a [`.scrollsnap-*`](../../utilities/scrollsnap/) class to the same element. The utility replaces the grid template with a single scrolling row below its breakpoint and hands everything back above it.
+
+```html
+<div class="items scrollsnap-md">...</div>
+```
+
+The carousel reads the same `--items-min-width`, so item width stays consistent between the two modes.

package/docs/content/list.md

@@ -0,0 +1,41 @@
+---
+isIndex: false
+title: List
+description: A compact labelled list, with the label as a sibling of the list rather than inside it.
+weight: 6
+icon: list-ul
+---
+
+A compact labelled list.
+
+```html
+<div class="list">
+  <p>Optional label</p>
+  <ul>
+    <li>First</li>
+    <li>Second</li>
+  </ul>
+</div>
+```
+
+**The wrapper is a `div`, and the label is a sibling of the list, not inside it.** That is the one structural thing to get right. Either `ul` or `ol` works.
+
+## What it changes
+
+Three small things, and nothing else:
+
+| Selector | Token | Effect |
+| --- | --- | --- |
+| `p` | `--list-label-font-weight`, `--list-label-margin-block` | The label's weight and the space under it |
+| `li` | `--list-item-font-size`, `--list-item-gap` | Item size, and the space between items as a block margin |
+| `.list, ul, ol` | — | `margin-block-end: 0`, so the block ends flush |
+
+Item spacing is a **margin**, not a `gap`, because the list is not a flex container. A `gap` here would do nothing.
+
+## Markers come from css-base
+
+The dash marker is not declared in this file. Bullets, numbering and the marker colour all come from the native list styling in [css-base](../../../css-base/base/), which is also why the component works on `ol` without a variant.
+
+## Where it fits
+
+It is the plain-text counterpart to [`.nav`](../../navigation/nav/), which resets the markers and lays its items out with flexbox because they are links. Use `.list` for content, `.nav` for navigation.

package/docs/content/media.md

@@ -0,0 +1,88 @@
+---
+isIndex: false
+title: Media
+description: The structural base for images and video, holding the aspect ratio, plus the logo and icon variants.
+weight: 7
+icon: image
+---
+
+The structural base for media blocks. It holds an aspect ratio and crops whatever is inside it.
+
+```html
+<div class="media">
+  <picture>
+    <img src="..." alt="...">
+  </picture>
+</div>
+```
+
+| Class | Use |
+| --- | --- |
+| `.media` | Base, for a picture or a video |
+| `.media-logo` | Logo, contained rather than cropped |
+| `.media-icon` | Icon, no ratio and no background |
+
+`.media-logo` and `.media-icon` are **modifiers**: use them alongside `.media`.
+
+## What the base does
+
+```css
+.media {
+  aspect-ratio: var(--media-ratio);
+  background-color: var(--media-color-background);
+  overflow: hidden;
+}
+```
+
+and then stretches `img`, `picture` and `video` to fill it with `object-fit: cover`. The background shows through while an image loads, which is what keeps a grid of cards from flashing white.
+
+Note that the base declares **no border and no radius**. A bordered media block is a card's doing, not the component's: see below.
+
+## `.media-logo`
+
+Swaps the crop for a contain:
+
+```css
+.media-logo {
+  picture { display: flex; align-items: center; justify-content: center; }
+  img { object-fit: contain; max-height: var(--media-logo-max-height); max-width: var(--media-logo-max-width); }
+}
+```
+
+A logo must never be cropped, and it must not fill the box either, hence the two maxima and the centring. Everything else, ratio and background, still comes from `.media`.
+
+## `.media-icon`
+
+Removes the two things that make a media block a media block:
+
+```css
+.media-icon {
+  --media-ratio: none;
+  --media-color-background: transparent;
+}
+```
+
+So it takes the size of its content. Inside a [card](../card/) it gets far more than that: the card maps eight `--card-media-icon-*` tokens onto the media namespace, including `--icon-size` and `--icon-color`, which is what gives icon cards their own look without a third class.
+
+## Context over variants
+
+A media block inside a card reads the card's tokens rather than its own:
+
+```css
+.card {
+  --media-color-background: var(--card-media-color-background);
+  --media-ratio: var(--card-media-ratio);
+}
+```
+
+and the card adds the border, radius and margins on `.media` directly. So the same `<div class="media">` is a full-bleed card header in one place and a standalone framed image in another, with no class changing.
+
+That is the pattern to copy when you need a media block to look different in a new context: set the `--media-*` tokens on the context, not a variant on the block.
+
+## Video inside a media block
+
+```css
+.media .video { height: 100%; }
+```
+
+A [`.video`](../../embeds/video/) wrapper is stretched to fill the media box, so a video and an image are interchangeable inside a card.

package/docs/content/surtitle.md

@@ -0,0 +1,43 @@
+---
+isIndex: false
+title: Surtitle
+description: An eyebrow label above a heading, tightened automatically when it sits inside a card.
+weight: 8
+icon: type-h2
+---
+
+An eyebrow label above a heading.
+
+```html
+<p class="surtitle">Category</p>
+<h2>Main title</h2>
+```
+
+It is a leaf component: no children, no variants, no states. Every property reads a `--surtitle-*` token, including the border set, so it can be a plain label in one theme and a chip in another without a second class.
+
+| Token group | Covers |
+| --- | --- |
+| `--surtitle-color-*` | Background and text |
+| `--surtitle-border-*` | Colour, style, width and radius |
+| `--surtitle-font-size`, `-font-weight`, `-letter-spacing`, `-line-height`, `-text-transform` | Typography |
+| `--surtitle-padding-*`, `-margin-block-*` | Spacing |
+
+## It pulls itself closer inside a card
+
+A [card](../card/) reassigns one token:
+
+```css
+.card { --surtitle-margin-block-end: calc(var(--card-gap) * -1); }
+```
+
+The negative margin cancels exactly one grid gap, so the surtitle and the title read as a single unit rather than as two stacked lines. The card also zeroes `margin-block-start` on it, so the pair sits flush against the top of the content block.
+
+That is the whole mechanism, and it is worth copying: a context that stacks its children with a `gap` can tighten any pair by handing back one negative gap, with no change to the component.
+
+## Use a paragraph, not a heading
+
+A surtitle is a label, not a level in the document outline. Marking it up as `<h3>` above an `<h2>` inverts the heading order and breaks navigation by headings. If the category needs to be part of the heading, put it inside one:
+
+```html
+<h2><span class="surtitle">Category</span> Main title</h2>
+```

package/docs/embeds/_index.md

@@ -0,0 +1,25 @@
+---
+isIndex: false
+title: Embeds
+description: Aspect-ratio wrappers for third-party embeds, native video and maps.
+weight: 6
+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

@@ -0,0 +1,53 @@
+---
+isIndex: false
+title: Embed
+description: A responsive container for third-party embeds, holding an aspect ratio so the page does not reflow.
+weight: 1
+icon: aspect-ratio
+---
+
+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, each stretched to fill the box.
+
+## The ratio
+
+`--embed-ratio` 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>
+```
+
+or per context, which is usually better:
+
+```css
+.podcast-player { --embed-ratio: 4 / 1; }
+```
+
+## Frame and shadow
+
+`--embed-border`, `--embed-border-radius` and `--embed-box-shadow` are the three decoration tokens. `overflow: hidden` is what lets the radius clip the iframe at the corners, since an iframe cannot be given one of its own.
+
+Note that `--embed-border` is a **shorthand** token taking width, style and colour together, unlike most components in this package which split the three. Set it as one value:
+
+```css
+.embed { --embed-border: 1px solid var(--color-border); }
+```
+
+## Always give the iframe a title
+
+```html
+<iframe src="..." title="2024 annual report, presented by the CFO"></iframe>
+```
+
+It is the only accessible name an embedded frame has. Without it a screen reader announces "frame" and the reader has to enter it to find out what it holds.
+
+## Embed or video?
+
+Use `.embed` for a **third-party player**, where the content is an iframe you do not control. Use [`.video`](../video/) for a native `<video>` element, which needs a positioning context for its pause control rather than a ratio wrapper.