@uncinq/css-components 1.16.1 → 1.16.3

package/docs/buttons/btn.md

@@ -0,0 +1,95 @@
+---
+isIndex: false
+title: Button
+description: The .btn base class, its ten colour variants, five sizes and three style variants.
+weight: 1
+icon: hand-index-thumb
+---
+
+`.btn` is the base class. It works on `<button>`, `<a>` and `<input type="submit">`, and reads `--btn-*` from [@uncinq/component-tokens](../../../component-tokens/reference/).
+
+```html
+<button class="btn">Send</button>
+<a class="btn btn-secondary" href="/contact">Contact</a>
+```
+
+Variants compose freely: `class="btn btn-danger btn-sm btn-ghost"`.
+
+## Colour variants
+
+| Class | Intent |
+| --- | --- |
+| `.btn-primary` | Primary action |
+| `.btn-secondary` | Secondary action |
+| `.btn-brand` | Brand-coloured |
+| `.btn-neutral` | Neutral emphasis |
+| `.btn-dark` | Dark surface |
+| `.btn-light` | Light surface |
+| `.btn-success` | Confirmation |
+| `.btn-danger` | Destructive action |
+| `.btn-warning` | Warning |
+| `.btn-info` | Informational |
+
+Each sets four properties together: background, border, their hover values, and the text colour.
+
+```css
+.btn-danger {
+  --btn-color-background: var(--color-danger);
+  --btn-color-background-hover: var(--color-danger-strong);
+  --btn-color-border: var(--color-danger);
+  --btn-color-border-hover: var(--color-danger-strong);
+  --btn-color-text: var(--color-text-on-danger);
+}
+```
+
+The text colour always comes from the matching `--color-text-on-*` semantic token, so contrast survives a change to the underlying colour. That pairing is the reason to rebrand by redefining `--color-brand` rather than `--btn-color-background`.
+
+`.btn-primary` and `.btn-brand` resolve to exactly the same values, as do `.btn-secondary` and `.btn-neutral`. The intent names exist so a page can say *primary action* without deciding which colour that is.
+
+## Sizes
+
+| Class | Use |
+| --- | --- |
+| `.btn-xs` | Dense UI, inline controls |
+| `.btn-sm` | Compact |
+| `.btn-md` | Default, can be omitted |
+| `.btn-lg` | Prominent |
+| `.btn-xl` | Hero call to action |
+
+A size class sets `--btn-font-size` along with the block and inline padding, all three from the same rung of the scale. Since `.btn` publishes `--icon-size: var(--btn-font-size)`, any icon inside scales with it.
+
+## Style variants
+
+| Class | Effect |
+| --- | --- |
+| `.btn-ghost` | Fully transparent, background and border alike, text in `--color-text` |
+| `.btn-link` | Renders as an underlined link |
+| `.btn-control` | Form control styling, for buttons sitting next to inputs |
+
+`.btn-control` maps the `--btn-color-*` set onto the `--btn-control-*` tokens, which is the same palette the [close](../btn-close/) and [menu](../btn-menu/) buttons use by default. It is what makes a button read as part of a form rather than as a call to action.
+
+### How `.btn-link` gets its underline
+
+Every button already carries one. The base class declares `text-decoration-line: var(--btn-text-decoration-line)`, which the tokens set to `underline`, and paints it with `--btn-color-text-decoration`, which defaults to `transparent`.
+
+`.btn-link` only changes the colour:
+
+```css
+.btn-link {
+  --btn-color-text-decoration: initial;   /* revealed, takes currentColor */
+
+  @media (hover: hover) and (pointer: fine) {
+    &:hover {
+      --btn-color-text-decoration: transparent;  /* hidden again */
+    }
+  }
+}
+```
+
+The underline is therefore always in the layout and never shifts the text, which is why hovering one does not nudge the label. If you write your own link-like variant, change the decoration colour rather than the decoration line, for the same reason.
+
+## States
+
+`:focus-visible` draws the outline from the `--focus-*` tokens. `:disabled` and `[aria-disabled='true']` are treated alike, both getting `cursor: not-allowed` and `--opacity-disabled`.
+
+Hover is guarded by `@media (hover: hover) and (pointer: fine)`, so a touch device never leaves a button stuck in its hover colours after a tap. The transition is guarded by `prefers-reduced-motion`.

package/docs/cascade-layers.md

@@ -1,7 +1,7 @@
 ---
 isIndex: false
 title: Cascade layers
-description: The two layers this package owns, why panel.css is imported last, and how to override a component cleanly.
+description: The two layers this package owns, why panel.css follows modal and drawer, and how to override a component cleanly.
 weight: 1
 icon: stack
 ---
@@ -16,25 +16,27 @@ This package writes to two layers.
 The full order, including layers owned by the sibling packages and by the project itself, is the **consuming project's** responsibility. Declare it once, at the very top of your entry stylesheet, before any `@import`:
 
 ```css
-@layer reset, tokens, libs, vendors, base, layouts, components, pages, utilities;
+@layer reset, tokens, libs, base, vendors, layouts, components, pages, utilities;
 ```
 
 CSS fixes a layer's position the first time its name is seen, and later re-declarations do not reorder it. If that line comes after an import, it is already too late. See [the css-base page](../../css-base/cascade-layers/) for the full explanation, including why `libs` and `vendors` are a pair.
 
 ## Why `utilities` is last
 
-`.scrollsnap` changes the `grid-template-columns` that a component such as `.items` declares for itself in `@layer components`. A later layer beats an earlier one regardless of specificity, so putting it in `utilities` is what lets a single class opt an existing component into carousel behaviour without rewriting the component.
+[`.scrollsnap`](../utilities/scrollsnap/) changes the `grid-template-columns` that a component such as [`.items`](../content/items/) declares for itself in `@layer components`. A later layer beats an earlier one regardless of specificity, so putting it in `utilities` is what lets a single class opt an existing component into carousel behaviour without rewriting the component.
 
-This is also why it is a utility rather than a component rule: it is a modifier applied to something else, not a thing of its own.
+It is also what makes `revert-layer` work in the responsive variants: handing a property back to the layer below only means anything when there is a layer below holding the component's own value.
 
-## Why `panel.css` is imported last
+This is the reason it is a utility rather than a component rule: it is a modifier applied to something else, not a thing of its own.
+
+## Why `panel.css` follows `modal.css` and `drawer.css`
 
 Inside `@layer components`, source order breaks ties between rules of equal specificity. Two facts combine here:
 
-1. Most of `panel.css` is wrapped in `:where()`, so it carries **zero specificity**. That is deliberate: it lets `.modal`, `.drawer` and your own overrides win without escalating.
+1. Most of [`panel.css`](../overlays/panel/) is wrapped in `:where()`, so it carries **zero specificity**. That is deliberate: it lets `.modal`, `.drawer` and your own overrides win without escalating.
 2. The `.panel-inline-*` variants must beat `.modal` and `.drawer`, and they are plain class selectors.
 
-Because those variants have no specificity advantage over the host components, they rely on arriving later in the file. Hence `@import 'components/panel.css';` sits last among the component imports in `css/index.css`.
+Because those variants have no specificity advantage over the host components, they rely on arriving later in the file. The alphabetical import order in `css/index.css` already puts `panel.css` after both, so nothing there looks out of the ordinary, but the constraint is real.
 
 If you import files individually, keep `panel.css` after `modal.css` and `drawer.css`.
 

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.