layered-ui-rails 0.18.4 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62247f3f61f465b4c4c576b807cf69c1f39b2bba73f758b2f2756210515ecbfc
-  data.tar.gz: 5c935329c2269e3f160f2a835958db103f40cb2cfe168ae57199a4aa81447f3e
+  metadata.gz: 3300c4fe2f7e3d1fc8175af4985078888212de7a797482ffc12b5d60074b4b09
+  data.tar.gz: a56fed6fd7b9013d7c0a2ca988194d5071713e137f1c4022b58e86e205992bf1
 SHA512:
-  metadata.gz: 17ea18aaf95c45154f42f6e565ed7e4685e26ac668542195041f55bfd6a1059521c878148bb100e26e03dc97023a08ae4e055f4c0318b8d70acb6b3d2d55ab00
-  data.tar.gz: 8dce1dac58aaee5f41ac5df38494122102f05c92ad71286940e49d47daedf47f84e952101feb805e8ea063b3c734d8d1b69d515460ae079682ec08109c09485e
+  metadata.gz: 717f5fef1822f58376c54673e9c536be2d1509ee185d152f82e0bcce75e91930b2312d21d106b076ae58a0aff5c7c0f239fe7cff5147987b725dcaa433d773d2
+  data.tar.gz: e99903b76852ebf675b7583a71572b0bcd0cad27eb12a9231fc4a9b7ad2b9a4e9d5a3e48970e71713fe780307f6e63fee398a9c25c1c37d94c7d1439abf42f5a

data/.claude/skills/layered-ui-rails/SKILL.md

@@ -192,7 +192,10 @@ Key components:
 |---|---|
 | Page layout | `.l-ui-page`, `--with-navigation`, `__vertically-centered`, `__narrow` (narrow ~384px column, md:max-w-sm), `__contained` (wide column capped at `--l-ui-contained-width`) |
 | Buttons | `.l-ui-button`, `--primary`, `--outline`, `--outline-danger`, `--full`, `--icon` |
+| Hero | `.l-ui-hero` (pair with `.l-ui-bleed`), `__inner`, `__title`, `__title-accent`, `__subtitle`, `__actions`, `__media`, `__media-img` |
 | Surfaces | `.l-ui-surface`, `--highlighted`, `--sm`, `--collapsible`, `--collapsible-highlighted` |
+| Cards | `.l-ui-card`, `--gradient`, `__eyebrow`, `__title`, `__icon`, `__body` |
+| Tints | `.l-ui-tint-1` … `.l-ui-tint-5` (shared decorative palette; sets the `--l-ui-tint-*` role variables) |
 | Forms | `.l-ui-form`, `.l-ui-form__group`, `.l-ui-form__field`, `.l-ui-label`, `.l-ui-select` |
 | Tables | `.l-ui-table`, `.l-ui-table__header`, `.l-ui-table__cell`, `--primary`, `--action`, `.l-ui-table__action`, `--danger` |
 | Badges | `.l-ui-badge`, `--rounded`, `--default`, `--success`, `--warning`, `--danger` |

data/.claude/skills/layered-ui-rails/references/CSS.md

@@ -47,6 +47,16 @@ The page gutter (horizontal and bottom padding) is the `--l-ui-gutter` custom pr
 
 `.l-ui-page` is a flex column (`flex flex-1 flex-col`) and uses `overflow-x-clip` to hold its content to the available width: intrinsically wide content (tables, code blocks, long unbroken strings) is clipped rather than expanding the page or adding a horizontal page scrollbar. So make such content scroll internally (e.g. wrap a table in an `overflow-x-auto` element) instead of expecting the page to grow.
 
+## Typography
+
+Base elements (`h1`-`h4`, `p`, `ul`/`ol`, `code`, etc.) are styled via `@layer base` so the host app can override them. Headings set type scale and weight only - they carry **no** divider by default, so the heading level can be chosen for document structure alone (e.g. an `h2` inside a panel header or hero, without an unwanted rule).
+
+```
+.l-ui-heading--section            Opt-in bottom divider; add to any heading to separate a section from the content above it
+```
+
+Add `l-ui-heading--section` wherever a visual section rule is wanted (the section headings on the documentation pages use it). It applies to whichever heading element you already have, so it does not change the heading level.
+
 ## Buttons
 
 Always combine the `l-ui-button` base class with a colour modifier (e.g. `l-ui-button l-ui-button--primary`):
@@ -73,6 +83,73 @@ Any button variant is automatically styled as disabled when the `disabled` HTML
 
 For destructive actions use `l-ui-button--danger` (solid) or `l-ui-button--outline-danger` (bordered).
 
+## Hero
+
+Full-bleed marketing hero for the top of a landing page. Add `l-ui-bleed` to the section to break out of the page gutter, and pair the body with `l-ui-body--glass-header` + `l-ui-body--flush-top` so it sits flush to the viewport top with optional media showing through the glass header (see Page layout above):
+
+```
+.l-ui-hero                       Full-bleed hero section (pair with l-ui-bleed); ships with a default background
+.l-ui-hero__inner                Content column, capped at the contained width with the page gutter
+.l-ui-hero__title                Large, tight-tracked hero heading
+.l-ui-hero__title-accent         Gradient-clipped accent span for part of the title
+.l-ui-hero__subtitle             Supporting subtitle paragraph below the title
+.l-ui-hero__actions              Row of call-to-action buttons or links
+.l-ui-hero__media                Optional decorative background media layer
+.l-ui-hero__media--light/--dark  Theme-specific media; only the active theme's variant shows
+.l-ui-hero__media-img            Image inside a media layer (covers, right-aligned)
+```
+
+The `__inner` picks up the fixed-header offset automatically under `l-ui-body--flush-top`. A token-driven overlay over the media keeps text legible and fades the hero into the page background below.
+
+A good-looking default background ships with the gem and is on by default, driven by the `--l-ui-hero-image` token (light/dark). Re-skin it by overriding `--l-ui-hero-image` in the overrides file (global) or inline on one section (per-hero); set it to `none` to remove it. For per-page art with proper light/dark `<img>` loading, add a `l-ui-hero__media` picture instead - it paints above the token background.
+
+## Tint palette
+
+A decorative, **control-agnostic** colour palette, separate from the Tier 1 brand `--accent`. `--accent` is the single interactive/emphasis colour (primary buttons, active tab/nav); the tints are a set of categorical decorative colours (cards, tags, sections). Both use `-foreground` for "the readable text/icon colour on this colour", so they read as siblings: `--accent` / `--accent-foreground` vs `--l-ui-tint-1-…` / `--l-ui-tint-1-foreground`.
+
+```
+.l-ui-tint-1 … .l-ui-tint-5   Select a palette slot (defaults: teal, green, amber, rose, purple)
+```
+
+Each `l-ui-tint-N` class only sets four "current tint" role variables, which any control reads:
+
+```
+--l-ui-tint-border       Border / outline tone
+--l-ui-tint-foreground   Strong text / icon tone
+--l-ui-tint-from         Gradient fill start
+--l-ui-tint-to           Gradient fill end
+```
+
+The defaults live in `@layer base` as `--l-ui-tint-N-border` / `-foreground` / `-from` / `-to` (light and dark). **Slot numbers are palette positions, not fixed hues**, so re-skinning a slot (override the `--l-ui-tint-N-*` tokens in the overrides file) never makes a class name misleading. The tints are independent of `--accent`; to colour a control with the brand accent instead, point the role variables at `var(--accent)` inline - no special class needed. Apply `l-ui-tint-N` to any control that reads the role variables (the card below is one consumer).
+
+## Card
+
+A content card in two composable styles. The base `l-ui-card` is bordered; add `l-ui-card--gradient` for a soft tint fill behind the same border. Colour comes from a separate `l-ui-tint-N` slot (see Tint palette above), so style and colour compose independently (`l-ui-card l-ui-card--gradient l-ui-tint-1`):
+
+```
+.l-ui-card                 Base card (bordered, on the surface background)
+.l-ui-card--gradient       Adds the 135° tint fill behind the border
+.l-ui-card__eyebrow        Small uppercase label above the title
+.l-ui-card__title          Card heading, coloured by the active tint
+.l-ui-card__icon           Optional title icon, painted in the tint colour (set --l-ui-icon-src inline)
+.l-ui-card__body           Body copy in the muted foreground colour
+```
+
+The card reads the shared `--l-ui-tint-*` role variables, falling back to the neutral `--border`/`--foreground` when no tint slot is present (so a plain `l-ui-card` is a neutral bordered card). The gradient modifier reads `--l-ui-tint-from`/`-to`. Set the role variables inline (or point them at `var(--accent)`, which is already theme-aware) for a one-off colour - but note that fixed inline values are theme-fixed: for a custom colour that should adapt to dark mode, supply light and dark values via a `.dark` rule (or `prefers-color-scheme`) rather than inline. `__icon` uses the same mask technique as the primary-button icon, so set `--l-ui-icon-src` at the call site.
+
+## Logo block
+
+A responsive strip of brand or partner logos (a "trusted by" / "works with" row). Logos are normalised to a common height and flattened to one tone (black in light, white in dark) so a mismatched set reads as a tidy row. Wraps three-up on small screens and spreads to a single row from `md` up:
+
+```
+.l-ui-logo-block                  Strip container; wraps three-up on small screens, single row from md
+.l-ui-logo-block__item            Wrapper for one logo (give it role="listitem")
+.l-ui-logo-block__logo            The logo image; normalised height, flattened to the foreground tone
+.l-ui-logo-block__logo--wordmark  Taller variant for wide name lockups
+```
+
+Mark the container `role="list"` with an `aria-label`, each item `role="listitem"`, and keep meaningful `alt` text on every logo. Supply normal full-colour logos - the tone is applied with a CSS filter, so source colours are ignored.
+
 ## Surfaces
 
 Always combine the `l-ui-surface` base class with any modifiers (e.g. `l-ui-surface l-ui-surface--highlighted`):

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.19.0] - 2026-06-15
+
+### Added
+
+- `l-ui-hero`: a full-bleed marketing hero for the top of a landing page, with `__inner`, `__title`, `__title-accent` (gradient-clipped emphasis span), `__subtitle`, and `__actions`. Pair the section with `l-ui-bleed` and the body with `l-ui-body--glass-header` + `l-ui-body--flush-top` to sit flush to the viewport top behind the glass header. Ships with a default light/dark background driven by the `--l-ui-hero-image` token (override globally, per-hero inline, or set to `none`); supply per-page art with the optional `l-ui-hero__media`/`__media-img` layer (`--light`/`--dark` variants for theme-aware `<img>` loading).
+- `l-ui-card`: a content card in two composable styles - the base bordered card plus `l-ui-card--gradient` for a soft tint fill behind the same border - with `__eyebrow`, `__title`, `__icon` (masked, set `--l-ui-icon-src` inline), and `__body`. Colour comes from a separate tint slot, so style and colour compose independently; a plain `l-ui-card` falls back to neutral `--border`/`--foreground`.
+- Decorative tint palette: `l-ui-tint-1` … `l-ui-tint-5` set the shared `--l-ui-tint-border`/`-foreground`/`-from`/`-to` role variables that tint-aware controls (such as the card) read. The palette is categorical and independent of the brand `--accent`; slot numbers are palette positions, not fixed hues, and each slot's `--l-ui-tint-N-*` tokens can be re-skinned in the overrides file (light and dark).
+- `l-ui-logo-block`: a responsive "trusted by" / "works with" strip with `__item`, `__logo`, and `__logo--wordmark`. Logos are normalised to a common height and flattened to a single tone (black in light, white in dark); wraps three-up on small screens and spreads to one row from `md` up.
+- `l-ui-heading--section`: an opt-in bottom divider that can be added to any heading to separate a section from the content above it, without changing the heading level.
+- The overrides generator now scaffolds commented-out `--l-ui-hero-image` and `--l-ui-tint-*` token blocks (light and dark) so hosts can re-skin the hero background and tint palette. Pass `--force` to `layered:ui:create_overrides` to regenerate an existing overrides file and pick up the new scaffolding (this overwrites the file, so back up your customisations first).
+
+### Breaking
+
+- Headings (`h1`-`h4`) now set type scale and weight only and carry no divider by default. Previously `h2` rendered a bottom border; the divider is now opt-in via `l-ui-heading--section`. This lets the heading level be chosen for document structure alone (e.g. an `h2` inside a panel header or hero) without an unwanted rule. Add `l-ui-heading--section` to any `h2` that should keep its previous divider. See `UPGRADING.md`.
+
 ## [0.18.4] - 2026-06-14
 
 ### Added
@@ -56,10 +71,13 @@ All notable changes to this project will be documented in this file. This projec
 - `--l-ui-gutter` custom property (default `1rem`) now drives the page's horizontal and bottom padding, shared with `.l-ui-header` so the two always align. Override it on a container to retune the gutter in one place.
 - `.l-ui-bleed` utility to take a child element edge-to-edge by cancelling the current page gutter (e.g. a full-bleed hero), with no negative-margin guesswork.
 
+### Breaking
+
+- `l-ui-page__width-constrained` renamed to `l-ui-page__narrow`. The old name read as a general page-width container, but it is a narrow ~384px column for any compact, centred content (the auth pages are one use). See `UPGRADING.md`.
+- Install flow: the engine's CSS is now served directly from the gem using [tailwindcss-rails' engine support](https://github.com/rails/tailwindcss-rails#rails-engines-support-experimental) instead of being copied into the host app. The install generator no longer creates `app/assets/tailwind/layered_ui.css`; instead it adds `@import "../builds/tailwind/layered_ui";` to your `application.css`. The CSS now stays in sync with the installed gem version automatically - no need to re-run the generator after upgrading.
+
 ### Changed
 
-- **Breaking:** `l-ui-page__width-constrained` renamed to `l-ui-page__narrow`. The old name read as a general page-width container, but it is a narrow ~384px column for any compact, centred content (the auth pages are one use). See `UPGRADING.md`.
-- **Breaking (install flow):** the engine's CSS is now served directly from the gem using [tailwindcss-rails' engine support](https://github.com/rails/tailwindcss-rails#rails-engines-support-experimental) instead of being copied into the host app. The install generator no longer creates `app/assets/tailwind/layered_ui.css`; instead it adds `@import "../builds/tailwind/layered_ui";` to your `application.css`. The CSS now stays in sync with the installed gem version automatically - no need to re-run the generator after upgrading.
 - The engine layout now links the compiled Tailwind build explicitly (`stylesheet_link_tag "tailwind"`) rather than the `:app` bundle, matching tailwindcss-rails' own convention and avoiding a stray link to the engine's intermediate build file.
 - Moved the engine's source stylesheet from `app/assets/tailwind/layered/ui/styles.css` to `app/assets/tailwind/layered_ui/engine.css` (the path tailwindcss-rails' engine support expects).
 

data/app/assets/tailwind/layered_ui/engine.css

@@ -79,6 +79,30 @@
     --warning-text: oklch(0.3625 0.0732 93.12);
     --error-bg: oklch(0.748 0.1306 20.64);
     --error-text: oklch(0.2248 0.0874 28.11);
+    /* Decorative tint palette (categorical colours, independent of --accent; consumed via the
+       .l-ui-tint-* role variables). Slot numbers are palette positions, not fixed hues. */
+    --l-ui-tint-1-border: oklch(0.6 0.1 195);
+    --l-ui-tint-1-foreground: oklch(0.45 0.1 195);
+    --l-ui-tint-1-from: oklch(0.95 0.04 195);
+    --l-ui-tint-1-to: oklch(0.88 0.07 195);
+    --l-ui-tint-2-border: oklch(0.55 0.14 145);
+    --l-ui-tint-2-foreground: oklch(0.45 0.14 145);
+    --l-ui-tint-2-from: oklch(0.95 0.05 145);
+    --l-ui-tint-2-to: oklch(0.88 0.09 145);
+    --l-ui-tint-3-border: oklch(0.65 0.14 65);
+    --l-ui-tint-3-foreground: oklch(0.5 0.14 60);
+    --l-ui-tint-3-from: oklch(0.95 0.05 65);
+    --l-ui-tint-3-to: oklch(0.88 0.09 65);
+    --l-ui-tint-4-border: oklch(0.6 0.16 25);
+    --l-ui-tint-4-foreground: oklch(0.5 0.18 25);
+    --l-ui-tint-4-from: oklch(0.95 0.05 25);
+    --l-ui-tint-4-to: oklch(0.88 0.09 25);
+    --l-ui-tint-5-border: oklch(0.6 0.15 290);
+    --l-ui-tint-5-foreground: oklch(0.45 0.17 290);
+    --l-ui-tint-5-from: oklch(0.95 0.05 290);
+    --l-ui-tint-5-to: oklch(0.88 0.09 290);
+    /* Default hero background; override here, per-hero inline, or set to `none`. */
+    --l-ui-hero-image: url('layered_ui/hero_background_light.webp');
     --header-height: 63px;
     --l-ui-gutter: 1rem;
     --l-ui-contained-width: 80rem;
@@ -111,6 +135,28 @@
     --warning-text: oklch(0.9336 0.1 95.79);
     --error-bg: oklch(0.2248 0.0874 28.11);
     --error-text: oklch(0.748 0.1306 20.64);
+    /* Decorative tint palette (dark) */
+    --l-ui-tint-1-border: oklch(0.5 0.1 195);
+    --l-ui-tint-1-foreground: oklch(0.78 0.11 195);
+    --l-ui-tint-1-from: oklch(0.28 0.05 195);
+    --l-ui-tint-1-to: oklch(0.22 0.06 195);
+    --l-ui-tint-2-border: oklch(0.5 0.13 145);
+    --l-ui-tint-2-foreground: oklch(0.78 0.13 145);
+    --l-ui-tint-2-from: oklch(0.28 0.06 145);
+    --l-ui-tint-2-to: oklch(0.22 0.07 145);
+    --l-ui-tint-3-border: oklch(0.55 0.13 60);
+    --l-ui-tint-3-foreground: oklch(0.78 0.14 60);
+    --l-ui-tint-3-from: oklch(0.28 0.06 60);
+    --l-ui-tint-3-to: oklch(0.22 0.07 60);
+    --l-ui-tint-4-border: oklch(0.5 0.16 25);
+    --l-ui-tint-4-foreground: oklch(0.74 0.17 25);
+    --l-ui-tint-4-from: oklch(0.28 0.07 25);
+    --l-ui-tint-4-to: oklch(0.22 0.08 25);
+    --l-ui-tint-5-border: oklch(0.55 0.15 290);
+    --l-ui-tint-5-foreground: oklch(0.78 0.15 290);
+    --l-ui-tint-5-from: oklch(0.28 0.06 290);
+    --l-ui-tint-5-to: oklch(0.22 0.07 290);
+    --l-ui-hero-image: url('layered_ui/hero_background_dark.webp');
   }
 
   /* Typography */
@@ -120,8 +166,7 @@
   }
 
   h2 {
-    @apply heading text-lg
-           border-b border-border pb-2;
+    @apply heading text-lg;
   }
 
   h3 {
@@ -163,6 +208,15 @@
   }
 }
 
+/* Headings */
+
+/* Opt-in section divider for any heading. Headings carry no border by default so the level can be
+   chosen for document structure alone (e.g. an h2 inside a panel header or hero); add this where a
+   visual section rule is wanted. */
+.l-ui-heading--section {
+  @apply border-b border-border pb-2;
+}
+
 /* Theme */
 
 @theme {
@@ -505,6 +559,272 @@
   padding-inline: max(0px, calc((100% - var(--l-ui-contained-width)) / 2 + var(--l-ui-gutter)));
 }
 
+/* Hero */
+
+/* Full-bleed marketing hero. Pair the section with .l-ui-bleed, and (for a top-of-page hero)
+   the body with .l-ui-body--glass-header + .l-ui-body--flush-top so it sits flush to the
+   viewport top and the background shows through the glass header.
+
+   Ships with a default background via the --l-ui-hero-image token (light/dark, set in @layer
+   base). Painted on the element itself so it sits below the overlays and needs no markup. Override
+   it globally in the overrides file, per-hero with an inline `--l-ui-hero-image`, or set it to
+   `none` to drop the background. For per-page art with proper light/dark <img> loading, add a
+   .l-ui-hero__media element instead (it paints above this background). */
+.l-ui-hero {
+  @apply relative isolate overflow-hidden
+         bg-background bg-cover bg-right bg-no-repeat;
+  background-image: var(--l-ui-hero-image);
+}
+
+/* Optional per-hero media layer; overrides the default background. Provide a --light and --dark
+   variant and the active theme's is shown. */
+.l-ui-hero__media {
+  @apply absolute inset-0 z-[-3]
+         block w-full h-full
+         pointer-events-none;
+}
+
+.l-ui-hero__media-img {
+  @apply w-full h-full
+         object-cover object-right;
+}
+
+.l-ui-hero__media--dark {
+  @apply hidden;
+}
+
+.dark .l-ui-hero__media--light {
+  @apply hidden;
+}
+
+.dark .l-ui-hero__media--dark {
+  @apply block;
+}
+
+/* Left-to-right overlay keeps text legible over media; fades out so the media stays visible
+   on the right. Token-driven, so it adapts to the active theme. */
+.l-ui-hero::before {
+  content: "";
+  @apply absolute inset-0 z-[-2]
+         pointer-events-none;
+  background: linear-gradient(
+    100deg,
+    oklch(from var(--background) l c h / 0.85) 0%,
+    oklch(from var(--background) l c h / 0.6) 45%,
+    oklch(from var(--background) l c h / 0.15) 80%,
+    oklch(from var(--background) l c h / 0) 100%
+  );
+}
+
+/* Bottom fade blends the hero into the page background below it. */
+.l-ui-hero::after {
+  content: "";
+  @apply absolute inset-0 z-[-1]
+         pointer-events-none;
+  background: linear-gradient(
+    to bottom,
+    transparent 0%,
+    oklch(from var(--background) l c h / 0.15) 40%,
+    oklch(from var(--background) l c h / 0.5) 75%,
+    var(--background) 100%
+  );
+}
+
+/* Content column, mirroring the contained page width and gutter. */
+.l-ui-hero__inner {
+  @apply w-full max-w-[var(--l-ui-contained-width)]
+         mx-auto
+         px-[var(--l-ui-gutter)] py-[clamp(2rem,4vw,3.5rem)]
+         text-foreground;
+}
+
+/* When the hero sits flush at the viewport top, push the content clear of the fixed header. */
+.l-ui-body--flush-top .l-ui-hero__inner {
+  @apply pt-[calc(var(--header-height)+clamp(2rem,4vw,3.5rem))];
+}
+
+.l-ui-hero__title {
+  @apply max-w-2xl
+         my-5
+         font-bold;
+  font-size: clamp(1.9rem, 6vw, 3.5rem);
+  line-height: 1.15;
+  letter-spacing: -0.02em;
+}
+
+/* Gradient-clipped accent for emphasising part of the title. */
+.l-ui-hero__title-accent {
+  @apply inline-block
+         pb-[0.15em];
+  background: linear-gradient(
+    95deg,
+    oklch(0.55 0.14 195) 0%,
+    oklch(0.6 0.16 60) 50%,
+    oklch(0.55 0.2 25) 100%
+  );
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+}
+
+.dark .l-ui-hero__title-accent {
+  background: linear-gradient(
+    95deg,
+    oklch(0.82 0.11 195) 0%,
+    oklch(0.78 0.14 60) 50%,
+    oklch(0.68 0.18 25) 100%
+  );
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+}
+
+.l-ui-hero__subtitle {
+  @apply max-w-2xl
+         text-foreground-muted;
+  font-size: clamp(1rem, 1.6vw, 1.2rem);
+  line-height: 1.55;
+}
+
+.l-ui-hero__actions {
+  @apply flex flex-wrap
+         max-w-2xl
+         gap-4
+         mt-7;
+}
+
+/* Tint palette */
+
+/* Decorative, control-agnostic colour slots. Each .l-ui-tint-N class selects one palette entry
+   (defined in @layer base, light + dark) and exposes it through four "current tint" role variables
+   that any control reads: --l-ui-tint-border, --l-ui-tint-foreground, --l-ui-tint-from,
+   --l-ui-tint-to. These are decorative and independent of the Tier-1 brand --accent; to tint a
+   control with the brand accent instead, point these variables at var(--accent) inline. Slot numbers
+   are palette positions, not fixed hues, so re-skinning a slot (via the --l-ui-tint-N-* tokens in
+   the overrides file) never makes a class name misleading. */
+.l-ui-tint-1 {
+  --l-ui-tint-border: var(--l-ui-tint-1-border);
+  --l-ui-tint-foreground: var(--l-ui-tint-1-foreground);
+  --l-ui-tint-from: var(--l-ui-tint-1-from);
+  --l-ui-tint-to: var(--l-ui-tint-1-to);
+}
+
+.l-ui-tint-2 {
+  --l-ui-tint-border: var(--l-ui-tint-2-border);
+  --l-ui-tint-foreground: var(--l-ui-tint-2-foreground);
+  --l-ui-tint-from: var(--l-ui-tint-2-from);
+  --l-ui-tint-to: var(--l-ui-tint-2-to);
+}
+
+.l-ui-tint-3 {
+  --l-ui-tint-border: var(--l-ui-tint-3-border);
+  --l-ui-tint-foreground: var(--l-ui-tint-3-foreground);
+  --l-ui-tint-from: var(--l-ui-tint-3-from);
+  --l-ui-tint-to: var(--l-ui-tint-3-to);
+}
+
+.l-ui-tint-4 {
+  --l-ui-tint-border: var(--l-ui-tint-4-border);
+  --l-ui-tint-foreground: var(--l-ui-tint-4-foreground);
+  --l-ui-tint-from: var(--l-ui-tint-4-from);
+  --l-ui-tint-to: var(--l-ui-tint-4-to);
+}
+
+.l-ui-tint-5 {
+  --l-ui-tint-border: var(--l-ui-tint-5-border);
+  --l-ui-tint-foreground: var(--l-ui-tint-5-foreground);
+  --l-ui-tint-from: var(--l-ui-tint-5-from);
+  --l-ui-tint-to: var(--l-ui-tint-5-to);
+}
+
+/* Card */
+
+/* A bordered or gradient-filled content card. The base card is bordered; add --gradient for the
+   tint fill. Colour comes from a separate, control-agnostic tint slot (l-ui-tint-1..5), so style and
+   colour compose independently:
+
+     <div class="l-ui-card l-ui-tint-1">                      bordered, tint 1
+     <div class="l-ui-card l-ui-card--gradient l-ui-tint-1">  gradient, tint 1
+
+   The card reads the shared --l-ui-tint-* role variables, falling back to the neutral --border and
+   --foreground tokens when no tint slot is present. Set the role variables (or point them at
+   var(--accent)) inline for a one-off colour. */
+.l-ui-card {
+  @apply p-4
+         rounded-sm;
+  background-color: var(--surface);
+  border: 1px solid var(--l-ui-tint-border, var(--border));
+}
+
+/* Tint fill; from/to come from the active tint slot (fall back to the plain surface with no slot). */
+.l-ui-card--gradient {
+  background: linear-gradient(
+    135deg,
+    var(--l-ui-tint-from, var(--surface)) 0%,
+    var(--l-ui-tint-to, var(--surface)) 100%
+  );
+}
+
+.l-ui-card__eyebrow {
+  @apply mt-0 mb-1.5
+         text-xs font-semibold uppercase tracking-[0.12em] text-foreground-muted;
+}
+
+.l-ui-card__title {
+  @apply inline-flex items-center gap-2
+         mt-0 mb-1.5
+         text-lg font-semibold tracking-[-0.01em];
+  color: var(--l-ui-tint-foreground, var(--foreground));
+}
+
+/* Painted from the tint foreground colour via a mask (matching the primary-button icon), so it
+   adapts per theme without an invert. The icon shape comes from --l-ui-icon-src, set at the call
+   site. */
+.l-ui-card__icon {
+  @apply inline-block shrink-0
+         w-5 h-5;
+  background-color: var(--l-ui-tint-foreground, var(--foreground));
+  -webkit-mask: var(--l-ui-icon-src) no-repeat center / contain;
+          mask: var(--l-ui-icon-src) no-repeat center / contain;
+}
+
+.l-ui-card__body {
+  @apply mt-0
+         text-sm leading-relaxed text-foreground-muted;
+}
+
+/* Logo block */
+
+/* A responsive strip of brand or partner logos, normalised to a common height and flattened to a
+   single tone (black in light, white in dark) so a mismatched set of source logos reads as one
+   tidy row. Wraps three-up on small screens and spreads to a single row from md up. Use the
+   --wordmark modifier on wide name lockups that need more height than icon-style marks. */
+.l-ui-logo-block {
+  @apply flex flex-wrap items-center justify-center
+         gap-x-5 gap-y-6
+         md:flex-nowrap md:justify-between md:gap-4;
+}
+
+.l-ui-logo-block__item {
+  @apply flex shrink-0 grow-0 justify-center
+         min-w-0 basis-[calc(33.333%-1rem)]
+         md:block md:shrink md:basis-auto;
+}
+
+.l-ui-logo-block__logo {
+  @apply w-auto max-w-full;
+  height: clamp(1.1rem, 2vw, 2rem);
+  filter: brightness(0);
+}
+
+.l-ui-logo-block__logo--wordmark {
+  height: clamp(1.85rem, 3.3vw, 3.3rem);
+}
+
+.dark .l-ui-logo-block__logo {
+  filter: brightness(0) invert(1);
+}
+
 /* Header */
 
 /* The container owns the gutter (mirroring .l-ui-page), so .l-ui-header fills the gutter-inset

data/app/views/devise/shared/_links.html.erb

@@ -11,7 +11,7 @@
 <% end %>
 
 <%- if devise_mapping.recoverable? || devise_mapping.confirmable? || (devise_mapping.lockable? && resource_class.unlock_strategy_enabled?(:email)) %>
-  <h2 class="l-ui-mt-6">
+  <h2 class="l-ui-mt-6 l-ui-heading--section">
     Need assistance?
   </h2>
 <% end %>

data/app/views/layered_ui/shared/_form_errors.html.erb

@@ -1,6 +1,6 @@
 <% if item.errors.any? %>
   <div id="error_explanation" class="l-ui-form__errors" role="alert">
-    <h2>
+    <h2 class="l-ui-heading--section">
       <%= pluralize(item.errors.count, "error") %> found:
     </h2>
 

data/lib/generators/layered/ui/create_overrides_generator.rb

@@ -6,13 +6,16 @@ module Layered
 
         OVERRIDES_PATH = "app/assets/tailwind/layered_ui_overrides.css"
 
+        class_option :force, type: :boolean, default: false,
+          desc: "Regenerate the overrides file even if it exists (overwrites your customisations - back it up first)"
+
         def create_overrides_file
-          if File.exist?(OVERRIDES_PATH)
-            say "Overrides file already exists at #{OVERRIDES_PATH}, skipping", :yellow
+          if File.exist?(OVERRIDES_PATH) && !options[:force]
+            say "Overrides file already exists at #{OVERRIDES_PATH}, skipping (pass --force to regenerate)", :yellow
             return
           end
 
-          create_file OVERRIDES_PATH, overrides_content
+          create_file OVERRIDES_PATH, overrides_content, force: options[:force]
         end
 
         private
@@ -126,6 +129,50 @@ module Layered
               @apply h-7.5 w-auto;
             }
             */
+
+            /*
+             * Hero background. A default ships with the gem; re-skin it here
+             * (or set it to `none` to remove it). Set --l-ui-hero-image inline
+             * on a single hero to give different heroes different art.
+             */
+
+            /*
+            :root {
+              --l-ui-hero-image: url('my_hero_light.webp');
+            }
+
+            .dark {
+              --l-ui-hero-image: url('my_hero_dark.webp');
+            }
+            */
+
+            /*
+             * Decorative tint palette. The tint slots (l-ui-tint-1..5) are a
+             * shared, control-agnostic palette - used by cards and any other
+             * control that reads the --l-ui-tint-* role variables. They are
+             * independent of the Tier 1 brand --accent above. Slot numbers are
+             * palette positions, not fixed hues, so re-skinning a slot never
+             * makes a class name misleading. Each slot has four tokens (border,
+             * foreground, gradient from/to) for light and dark; override only
+             * the ones you need. (You can also set the role variables inline on
+             * a single element, or point them at var(--accent), for a one-off.)
+             */
+
+            /*
+            :root {
+              --l-ui-tint-1-border:     oklch(0.6 0.1 195);
+              --l-ui-tint-1-foreground: oklch(0.45 0.1 195);
+              --l-ui-tint-1-from:       oklch(0.95 0.04 195);
+              --l-ui-tint-1-to:         oklch(0.88 0.07 195);
+            }
+
+            .dark {
+              --l-ui-tint-1-border:     oklch(0.5 0.1 195);
+              --l-ui-tint-1-foreground: oklch(0.78 0.11 195);
+              --l-ui-tint-1-from:       oklch(0.28 0.05 195);
+              --l-ui-tint-1-to:         oklch(0.22 0.06 195);
+            }
+            */
           CSS
         end
       end

data/lib/layered/ui/version.rb

@@ -1,5 +1,5 @@
 module Layered
   module Ui
-    VERSION = "0.18.4"
+    VERSION = "0.19.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: layered-ui-rails
 version: !ruby/object:Gem::Version
-  version: 0.18.4
+  version: 0.19.0
 platform: ruby
 authors:
 - layered.ai
@@ -188,6 +188,8 @@ files:
 - app/assets/fonts/layered_ui/inter.woff2
 - app/assets/fonts/layered_ui/manrope.woff2
 - app/assets/images/layered_ui/apple_touch_icon.png
+- app/assets/images/layered_ui/hero_background_dark.webp
+- app/assets/images/layered_ui/hero_background_light.webp
 - app/assets/images/layered_ui/icon_chevron_down.svg
 - app/assets/images/layered_ui/icon_chevron_right.svg
 - app/assets/images/layered_ui/icon_close.svg