@uncinq/css-components 1.17.0 → 1.19.0

package/README.md

@@ -4,7 +4,7 @@
 
 <img width="1280" height="640" alt="share-css-components" src="https://github.com/user-attachments/assets/3d74df8a-e7bf-4ba5-8529-99cfef0bc176" />
 
-29 components and 1 utility, written as plain CSS, reading their values from [@uncinq/component-tokens](https://github.com/uncinq/component-tokens) and adding none of their own.
+30 components and 1 utility, written as plain CSS, reading their values from [@uncinq/component-tokens](https://github.com/uncinq/component-tokens) and adding none of their own.
 
 ## Where this sits
 
@@ -55,7 +55,7 @@ The failure is silent. No error is raised, the page simply stays at its mobile v
 | --- | --- |
 | Buttons | `.btn` with colour, size and style variants, plus `btn-close`, `btn-menu`, `btn-search`, `btn-filter`, `btn-share`, `btn-toc`, `btn-toggle-video` |
 | Overlays | `modal`, `drawer`, `dropdown`, and the shared panel skeleton |
-| Content | `alert`, `badge`, `banner`, `card`, `items`, `list`, `media`, `surtitle` |
+| Content | `alert`, `badge`, `banner`, `card`, `items`, `list`, `media`, `push`, `surtitle` |
 | Navigation | `nav`, `nav-title`, `nav-accessibility`, `breadcrumb`, `pagination` |
 | Embeds | `embed`, `video`, `map` |
 | Forms | `form`, `form-check` and the layout helpers |

package/css/components/button.css

@@ -42,7 +42,7 @@
         background-color: var(--btn-color-background-hover);
         border-color: var(--btn-color-border-hover);
         box-shadow: var(--btn-shadow-hover);
-        color: var(--btn-color-text-hover);
+        color: var(--btn-color-text-hover, var(--btn-color-text));
         text-decoration-color: var(--btn-color-text-decoration-hover);
       }
     }

package/css/components/push.css

@@ -0,0 +1,272 @@
+/* components/push.css */
+/*
+ * .push — a video or an image with a surtitle, title, text and CTA laid over it.
+ * Reads --push-* from @uncinq/component-tokens.
+ *
+ * Structure, the same for every modifier:
+ * <div class="push">
+ *   <div class="content">
+ *     <p class="surtitle">...</p>
+ *     <h2 class="title">...</h2>
+ *     <div class="text">...</div>
+ *     <a class="btn">...</a>
+ *   </div>
+ *   <div class="media">
+ *     picture | .video > video
+ *   </div>
+ * </div>
+ *
+ * The push carries the ratio and places .content inside it; .content is only
+ * the text box, which .push-card turns into a card. The ratio is drawn by
+ * .push::after, so that pseudo-element is taken.
+ *
+ * Modifiers:
+ *   .push-center | .push-end                         horizontal position of the content
+ *   .push-align-start | -center | -end               text alignment
+ *   .push-vertical-start | .push-vertical-end        vertical position of the content
+ *   .push-card                                       background behind the text
+ *   .push-darken                                     gradient under the text
+ */
+@layer components {
+  .push {
+    --media-color-background: var(--push-color-background);
+    --ratio-video: auto;
+
+    border-radius: var(--push-border-radius);
+    display: grid;
+    /* A fixed track: sized by its content, it would widen to the ratio box's
+       transferred size whenever the push is stretched by a min-height. */
+    grid-template-columns: minmax(0, 1fr);
+    overflow: hidden;
+    padding-block: var(--push-content-padding-block);
+    padding-inline: var(--push-content-padding-inline);
+    position: relative;
+
+    @media (--sm) {
+      --push-content-max-inline-size: var(--push-content-max-inline-size-tablet);
+    }
+    @media (--lg) {
+      --push-content-max-inline-size: var(--push-content-max-inline-size-laptop);
+    }
+
+    /* The ratio: an empty box sharing the single grid cell with .content, and
+       stretched over the padding by negative margins so that the ratio is the
+       push's own. The push takes the taller of the two, so a text that needs
+       more room grows it rather than being cut, even under a min-height. */
+    &::after {
+      aspect-ratio: var(--push-ratio-mobile);
+      content: '';
+      grid-area: 1 / 1;
+      justify-self: stretch;
+      margin-block: calc(var(--push-content-padding-block) * -1);
+      margin-inline: calc(var(--push-content-padding-inline) * -1);
+
+      @media (--sm) {
+        aspect-ratio: var(--push-ratio);
+      }
+    }
+
+    &:not(.push-card) {
+      --btn-color-background: var(--color-light);
+      --btn-color-background-hover: var(--color-light-hover);
+      --btn-color-border: var(--color-light);
+      --btn-color-border-hover: var(--color-light-hover);
+      --btn-color-text: var(--color-text-on-light);
+      --color-heading: var(--push-color);
+      --color-link: var(--push-color);
+      --color-link-hover: var(--push-color);
+      --surtitle-color-text: var(--push-surtitle-color, oklch(from var(--push-color) l c h / var(--opacity-muted)));
+
+      color: var(--push-color);
+    }
+
+    /* A grid item stacks above the media and the darken overlay through its
+       z-index alone. Left unpositioned, it is no containing block, so the
+       .btn::after overlay below covers the whole push, not just the text. */
+    > .content {
+      align-self: var(--push-content-justify, center);
+      display: flex;
+      flex-direction: column;
+      gap: var(--push-content-gap);
+      grid-area: 1 / 1;
+      justify-self: var(--push-content-items, flex-start);
+      max-inline-size: var(--push-content-max-inline-size);
+      width: 100%;
+      z-index: 1;
+
+      @media (--sm) {
+        text-align: var(--push-content-align);
+      }
+
+      > * {
+        margin-block: 0;
+      }
+
+      /* The button keeps its own width rather than stretching across the
+         box, and follows the text alignment, which applies from --sm up. */
+      > .btn {
+        align-self: start;
+
+        @media (--sm) {
+          align-self: var(--push-content-align, start);
+        }
+      }
+    }
+
+    /* A background: clicks go through it, to the push's own link. */
+    .media {
+      height: 100%;
+      inset: 0;
+      pointer-events: none;
+      position: absolute;
+      width: 100%;
+
+      /* …except the pause control a .video lays over an autoplaying video,
+         which has to stay usable (WCAG 2.2.2). */
+      .btn-toggle-video {
+        pointer-events: auto;
+      }
+
+      /* Safari draws a play button over a video it refuses to autoplay, in
+         Low Power Mode for one. The button sits in the browser's shadow DOM,
+         which only gives way to !important. */
+      video::-webkit-media-controls-start-playback-button {
+        -webkit-appearance: none;
+        display: none !important;
+      }
+    }
+
+    .surtitle {
+      margin-block-end: calc(var(--push-content-gap) * -1);
+    }
+
+    .btn::after {
+      content: '';
+      inset: 0;
+      position: absolute;
+    }
+  }
+
+  /* Card: the text box takes the look of a .card. Each value reads an optional
+     --push-card-* first, unset by default, so push cards can be restyled
+     without touching the cards themselves. */
+  .push-card > .content {
+    background-color: var(--push-card-color-background, var(--card-color-background));
+    border-color: var(--push-card-color-border, var(--card-color-border));
+    border-radius: var(--push-card-border-radius, var(--card-border-radius));
+    border-style: var(--push-card-border-style, var(--card-border-style));
+    border-width: var(--push-card-border-width, var(--card-border-width));
+    box-shadow: var(--push-card-shadow, var(--card-shadow));
+    color: var(--push-card-color-text, var(--card-color-text));
+    padding-block: var(--push-card-padding-block, var(--card-padding-block));
+    padding-inline: var(--push-card-padding-inline, var(--card-padding-inline));
+
+    > .title {
+      color: var(--push-card-title-color, var(--card-title-color));
+      font-family: var(--push-card-title-font-family, var(--card-title-font-family));
+      font-size: var(--push-card-title-font-size, var(--card-title-font-size));
+      font-weight: var(--push-card-title-font-weight, var(--card-title-font-weight));
+      line-height: var(--push-card-title-line-height, var(--card-title-line-height));
+    }
+
+    @media (prefers-reduced-motion: no-preference) {
+      transition: var(--push-card-transition, var(--card-transition));
+    }
+  }
+
+  @media (hover: hover) and (pointer: fine) {
+    .push-card:hover > .content {
+      --push-card-shadow: var(--push-card-shadow-hover, var(--card-shadow-hover));
+    }
+  }
+
+  /* Darken */
+  .push-darken {
+    /* Logical gradient directions (flipped under RTL) */
+    --push-gradient-to-end: to right;   /* toward inline-end */
+    --push-gradient-to-start: to left;  /* toward inline-start */
+
+    /* The shadow comes from the edge the content sits against. Only this
+       variable changes from one variant to the next; the ::before below is
+       the single place that paints it. */
+    --push-darken: linear-gradient(var(--push-gradient-to-end), var(--push-gradient-color-from) 0%, var(--push-gradient-color-to) var(--push-gradient-stop));
+
+    &:dir(rtl) {
+      --push-gradient-to-end: to left;
+      --push-gradient-to-start: to right;
+    }
+
+    @media (--sm) {
+      &.push-end {
+        --push-darken: linear-gradient(var(--push-gradient-to-start), var(--push-gradient-color-from) 0%, var(--push-gradient-color-to) var(--push-gradient-stop));
+      }
+    }
+
+    /* A vertical offset tilts the gradient the same way, as in .hero.
+       Declared after the horizontal ones, so it wins when both are set. */
+    &.push-vertical-start {
+      --push-darken: linear-gradient(to bottom, var(--push-gradient-color-from) 0%, var(--push-gradient-color-to) var(--push-gradient-stop));
+    }
+    &.push-vertical-end {
+      --push-darken: linear-gradient(to top, var(--push-gradient-color-from) 0%, var(--push-gradient-color-to) var(--push-gradient-stop));
+    }
+
+    /* …except when the text carries its own background, or is centered: the
+       media is dimmed as a whole instead. */
+    &.push-card,
+    &.push-center {
+      --push-darken: transparent;
+
+      .media {
+        filter: brightness(var(--push-media-brightness));
+      }
+    }
+
+    /* Painted on the push itself, edge to edge: .content is only the text box.
+       Same layering as .hero: the overlay sits above the media, the content
+       above the overlay. */
+    &::before {
+      background: var(--push-darken);
+      content: '';
+      inset: 0;
+      pointer-events: none;
+      position: absolute;
+      z-index: 1;
+    }
+  }
+
+  /* Offset: horizontal position of the content */
+  .push-center {
+    @media (--sm) {
+      --push-content-items: center;
+    }
+  }
+
+  .push-end {
+    @media (--sm) {
+      --push-content-items: flex-end;
+    }
+  }
+
+  /* Text alignment */
+  .push-align-start {
+    --push-content-align: start;
+  }
+
+  .push-align-center {
+    --push-content-align: center;
+  }
+
+  .push-align-end {
+    --push-content-align: end;
+  }
+
+  /* Vertical position of the content (centered by default) */
+  .push-vertical-start {
+    --push-content-justify: flex-start;
+  }
+
+  .push-vertical-end {
+    --push-content-justify: flex-end;
+  }
+}

package/css/index.css

@@ -26,6 +26,7 @@
 @import 'components/nav-title.css';
 @import 'components/pagination.css';
 @import 'components/panel.css';
+@import 'components/push.css';
 @import 'components/surtitle.css';
 @import 'components/video.css';
 

package/docs/buttons/btn.md

@@ -44,6 +44,8 @@ Each sets four properties together: background, border, their hover values, and
 
 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`.
 
+The text keeps its colour on hover: `.btn` reads `var(--btn-color-text-hover, var(--btn-color-text))`, and `--btn-color-text-hover` is no token, so it is unset unless a variant or a context sets it. A context that recolours its buttons, as a push over a dark media does, only needs `--btn-color-text`.
+
 `.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

package/docs/cascade-layers.md

@@ -10,7 +10,7 @@ This package writes to two layers.
 
 | Layer | Contents |
 | --- | --- |
-| `@layer components` | All 29 components |
+| `@layer components` | All 30 components |
 | `@layer utilities` | `.scrollsnap`, the only utility |
 
 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`:

package/docs/content/_index.md

@@ -1,7 +1,7 @@
 ---
 isIndex: false
 title: Content
-description: Alerts, badges, banners, cards, the items grid, labelled lists, media objects and surtitles.
+description: Alerts, badges, banners, cards, the items grid, labelled lists, media objects, pushes and surtitles.
 weight: 5
 icon: card-text
 ---

package/docs/content/overview.md

@@ -1,12 +1,12 @@
 ---
 isIndex: false
 title: Overview
-description: The eight content components, the three that are meant to nest, and the two colour patterns they follow.
+description: The nine 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.
+Nine components for laying out page content.
 
 | Page | Class | Purpose |
 | --- | --- | --- |
@@ -17,6 +17,7 @@ Eight components for laying out page content.
 | [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 |
+| [Push](../push/) | `.push` | A video or image with text and a call to action laid over it |
 | [Surtitle](../surtitle/) | `.surtitle` | An eyebrow label above a heading |
 
 ## Three of them are meant to nest

package/docs/content/push.md

@@ -0,0 +1,106 @@
+---
+isIndex: false
+title: Push
+description: A video or image with text laid over it, how the push places its text box, the position and darken modifiers, and the card variant.
+weight: 9
+icon: image
+---
+
+A video or an image with a surtitle, a title, some text and a call to action laid over it.
+
+```html
+<div class="push push-darken">
+  <div class="content">
+    <p class="surtitle">Collection</p>
+    <h2 class="title">Push title</h2>
+    <div class="text"><p>Short text.</p></div>
+    <a class="btn" href="/collection">Discover</a>
+  </div>
+  <div class="media">
+    <picture>...</picture>
+  </div>
+</div>
+```
+
+| Child | Role |
+| --- | --- |
+| `.content` | The text box, placed inside the push |
+| `.media` | The image or video, stretched behind the content, see [Media](../media/) |
+| `.surtitle` | An optional eyebrow, pulled back by one gap, see [Surtitle](../surtitle/) |
+| `.btn` | The call to action, whose `::after` makes the whole push clickable |
+
+The markup is the same for every modifier: switching a push to a card, or moving its text, is a class change, never a change of structure.
+
+## The push carries the ratio
+
+The push is a one-cell grid with the content padding. Two boxes share that cell: `.content`, placed by the position modifiers below, and an empty `::after` that carries the ratio, `--push-ratio-mobile` below `--sm` and `--push-ratio` from `--sm` up. Negative margins stretch that box over the padding, so the ratio is the push's own. `.media` is absolutely positioned and fills the push.
+
+The push takes the taller of the two boxes: a text that needs more room than the ratio leaves grows the push instead of being cut, even when a layout gives the push a `min-height` to fill its row. The single track is fixed to `minmax(0, 1fr)`, so the ratio box never widens it. To change the shape of one push, override the two ratio tokens on it rather than setting a height.
+
+`.push::after` is therefore taken; `::before` is the darken overlay.
+
+`--push-ratio-double` is not read here. It is a second ratio for layouts that set two pushes side by side and want a taller shape than a full-width one.
+
+## The media is a background
+
+`.media` takes `pointer-events: none`: a click on the image or the video goes through to the push and its link, and a tap never starts or pauses a video. The pause control that a [`.video`](../../embeds/video/) lays over an autoplaying video is the exception, set back to `pointer-events: auto`, since WCAG requires a way to stop it. A video that needs its native `controls` does not belong in a push.
+
+Safari draws a play button over a video it refuses to autoplay, in Low Power Mode for instance. The push hides it through `::-webkit-media-controls-start-playback-button`, with the one `!important` of the component: the button lives in the browser's shadow DOM, and nothing weaker overrides it there. The video then shows its first frame, or its poster.
+
+## What the push hands down
+
+Unless it has `.push-card`, a push sets the text, heading, link and surtitle colours from `--push-color`, and turns `.btn` into a light button that reads on a dark media. `--push-surtitle-color` overrides the surtitle colour alone; it is unset by default, and the surtitle falls back to `--push-color` at `--opacity-muted`.
+
+It also reassigns two other namespaces:
+
+```css
+--media-color-background: var(--push-color-background);
+--ratio-video: auto;
+```
+
+The background colour shows while the media loads, or behind an image with transparent areas. `--ratio-video: auto` lets a `.video` inside the push fill it instead of imposing its own ratio.
+
+## Position and alignment
+
+The content is centred vertically and sits at the start horizontally by default. Three groups of modifiers move it.
+
+| Modifier | Effect |
+| --- | --- |
+| `.push-center`, `.push-end` | Horizontal position of the content, from `--sm` up |
+| `.push-align-start`, `-center`, `-end` | Text alignment, from `--sm` up |
+| `.push-vertical-start`, `.push-vertical-end` | Vertical position of the content |
+
+Each one only sets a private variable (`--push-content-items`, `--push-content-align`, `--push-content-justify`), so they combine freely. The content is capped at `--push-content-max-inline-size`, which narrows at `--sm` and `--lg` so that a line of text never spans a full-width push. Those steps follow the viewport, not the push: a layout that sets pushes side by side should reset the token to `100%` on them.
+
+The `.btn` keeps its own width rather than stretching across the content, and follows the text alignment from `--sm` up, like the rest of the text.
+
+A push stretched taller than its ratio, by a grid row or a carousel track, keeps its content where the modifiers put it within the whole height.
+
+## Darken
+
+`.push-darken` paints a gradient between the media and the content, from the edge the content sits against: the start edge by default, the end edge with `.push-end`, the top or bottom with a vertical modifier. Directions flip under `:dir(rtl)`.
+
+The gradient is painted by a `::before` on the push itself, edge to edge, since `.content` is only the text box.
+
+With `.push-center` or `.push-card` there is no edge to darken from, so the whole media is dimmed instead, with `filter: brightness(var(--push-media-brightness))`. That token references `--hero-media-brightness` by default, so a push and a hero dim their media alike.
+
+## Card
+
+`.push-card` puts the text on a background of its own, for media too busy to read text over. Nothing changes in the markup: `.content` itself takes the look of a [card](../card/).
+
+It reads the card tokens for its background, border, radius, shadow, text colour, padding, title typography and transition. Each one goes through an optional `--push-card-*` of the same name first, unset by default:
+
+```css
+border-radius: var(--push-card-border-radius, var(--card-border-radius));
+padding-block: var(--push-card-padding-block, var(--card-padding-block));
+```
+
+Override `--push-card-*` to restyle every push card without touching the cards themselves, or `--card-*` to change both. Its shadow swaps to `--push-card-shadow-hover`, falling back to `--card-shadow-hover`, when the push is hovered. A push card does not inherit `--push-color`, so its text keeps the card colours.
+
+## The whole-push link
+
+`.btn::after` lays an overlay across the push, so a click anywhere on it follows the call to action.
+
+`.content` stacks above the media and the darken overlay through its `z-index` as a grid item, without being positioned, so it is no containing block: the overlay resolves against the push and covers it entirely. Anything that does make `.content` a containing block, such as a `transform` or `translate` from an entrance animation, narrows the clickable area to the text box.
+
+As with the [whole-card link](../card/#the-whole-card-link), a push with more than one interactive element needs a different structure, since the overlay covers the others.

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: 9
+weight: 10
 icon: type-h2
 ---
 

package/docs/overview.md

@@ -1,12 +1,12 @@
 ---
 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.
+description: The 30 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/css-components` is the top of the stack: 30 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
@@ -25,7 +25,7 @@ One page per component, grouped into six sections.
 | --- | --- |
 | [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/) |
+| [Content](../content/) | [`.alert`](../content/alert/), [`.badge`](../content/badge/), [`.banner`](../content/banner/), [`.card`](../content/card/), [`.items`](../content/items/), [`.list`](../content/list/), [`.media`](../content/media/), [`.push`](../content/push/), [`.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/) |

package/package.json

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