studio-engine 0.108.0 → 0.109.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 731299717728fa47ee4546968f5e931e3e717043954d5262e6811c255872c1c6
-  data.tar.gz: 7f0a4f9eedccac043b017cbc25291f60559529e6a5fe655e8dc89c70ab9118dd
+  metadata.gz: 19c0cd3c18b09bb009d42eea9911cb5eef64299aa74ba800f7bdd011da66623b
+  data.tar.gz: b22bc36fc79bac82a01ff679bbd9e7d9a49ea92f4d5b71fb52d1efc95e75bd0b
 SHA512:
-  metadata.gz: 0daadeed40010820350c83f4d029d2681eb56850204e35c2125681b041408a91c932dcc890efe4e687e0b343008a96a353ed61eb809f319b5089e7b70029bbea
-  data.tar.gz: 8764a4e2134c2fc02ed07344efb5dfb20fcbce6777923cb84d0dfd4c5302d29c36ed7fdeb59077b573af9a4f50ccd9cf8b7f5d31632faf127eace78a17302d65
+  metadata.gz: dd07af40833cdeb4acdaab8e37bffc7f021b9369c14c3b5f6d83c417e7344ada891143924f662cda4bcf6b389098b21eb9c85a860c99134798417273caf7b715
+  data.tar.gz: e4a4fc94d72ffcb463a1e37117dcd53f2d2897aea9ee070852a732cf1bace6b31ec35f3c0bdaa128528dcebd63c5d008a98142a024eb4415eabda0ccc5a02a69

data/CHANGELOG.md

@@ -4,8 +4,37 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+### Changed
+
+- **A held navbar eases its collapse again.** 0.108.0 held the header's
+  footprint so the page never moves, and with it let the header follow the
+  scroll position exactly. On a hard flick that crossed the whole ramp in a
+  frame or two, the header then snapped full to compact (or back) in one frame,
+  which read as a jerk on the hub's `/deployments`. The `--nav-max-step` cap
+  (5px of header travel per frame) now applies to held headers too, so a flick
+  plays as a short animation of about 8-9 frames. The page still never moves:
+  the hold keeps the document's height whatever `--nav-p` is. After a hard
+  flick to the top, page background shows between the header and the content
+  for those frames while the header grows back. A slow scroll is unchanged.
+
+## 0.109.0 — 2026-10-15
+
 ### Added
 
+- **Tints and shades: the `.scrim` primitive.** A scrim is the wash laid over
+  media so text reads on it. A **shade** lays the dark base over the media and
+  takes light ink; a **tint** lays the light base over it and takes dark ink.
+  `.scrim` picks by theme (a tint in light mode, a shade in dark),
+  `.scrim-tint` / `.scrim-shade` force a tone in either theme, `.scrim-soft` /
+  `.scrim-strong` step the strength from the tone's default (tint 75/58, shade
+  85/70; the default dark shade is the old navy `rgba(26,21,53,.85/.7/.85)`
+  exactly), and `.scrim-ink` / `.scrim-ink-muted` pick the ink for the tone.
+  The tone classes set inherited custom properties, so a tone on the parent
+  reaches both the wash and its sibling text. `Studio::ThemeResolver` now emits
+  the theme-independent `--color-shade`, `--color-tint` and their ink pairs
+  (`--color-{shade,tint}-ink`, `--color-{shade,tint}-ink-muted`) in both theme
+  blocks, following a custom `dark` / `light` colour. Specimen at
+  `/admin/style` → Tricks → Tints & shades; README "Tints and shades".
 - **`GET /_studio/health_report`: the daily health report as JSON, for the
   hub's central pull.** McRitchie Studio runs one 07:00 America/Denver job that
   pulls every app's report and posts it to Discord, so a satellite needs no

data/README.md

@@ -209,6 +209,69 @@ flag — it cannot know where the reader is sitting, so only the reader's machin
 may assert one. A host that omits the script still gets working stamps, just
 frozen in the app's timezone. Specimen: `/admin/style` → Tricks → Time stamps.
 
+### Tints and shades — `.scrim`
+
+Text laid over media on a PAGE (a hero photo, a video, a banner) reads through
+a **scrim**, a wash between the two. (The transactional email banner's scrim,
+below, is a separate inline shade built for mail clients.) A scrim comes in one of two tones, and the tone is the
+design decision:
+
+| Tone | What it lays over the media | Ink that reads on it | Token |
+|------|-----------------------------|----------------------|-------|
+| **Shade** | the dark base; it darkens the media | light | `--color-shade` |
+| **Tint** | the light base; it lightens the media | dark | `--color-tint` |
+
+The shade is the dark theme's natural scrim and the tint the light theme's, so
+`.scrim` on its own picks by theme. Force a tone when the media needs it, not
+the theme: a pale photo that only a shade can carry, or a brand moment that
+wants dark ink in both themes.
+
+```erb
+<section class="relative overflow-hidden">
+  <img src="/hero.avif" alt="" class="absolute inset-0 w-full h-full object-cover">
+  <div class="scrim absolute inset-0"></div>
+  <div class="relative z-10 text-center">
+    <h1 class="scrim-ink text-5xl font-extrabold">Solutions For Business</h1>
+    <p class="scrim-ink-muted">An acquisition entrepreneur ...</p>
+  </div>
+</section>
+
+<%# Forced: a shade in both themes. The tone goes on the shared PARENT. %>
+<section class="scrim-shade relative overflow-hidden"> ... </section>
+```
+
+| Class | Effect |
+|-------|--------|
+| `.scrim` | Paints the wash: a 135deg gradient, heavier at both corners than in the middle. Theme-aware with no tone class: a tint in light mode, a shade in dark. |
+| `.scrim-tint` · `.scrim-shade` | Force the tone, in either theme. |
+| `.scrim-soft` · `.scrim-strong` | Step the strength: 15 points lighter, or 10 heavier, from the tone's default. |
+| `.scrim-ink` | The strong ink for the tone (headlines): the dark text colour on a tint, white on a shade. |
+| `.scrim-ink-muted` | The quieter ink (subtitles): the body ink at weight 600 on a tint, the secondary ink at 400 on a shade. |
+
+- **Put the tone on the shared parent.** The tone classes set custom
+  properties, which inherit. The wash and the text are usually siblings (an
+  `absolute inset-0` scrim, then a `relative z-10` content box), so a tone on the
+  wash alone leaves the text on the theme's ink.
+- **Default strengths.** A tint is 75% at the corners and 58% in the middle (the
+  hub hero's approved light treatment); a shade is 85% and 70%, which on the
+  default theme is the old hero navy, `rgba(26,21,53,.85/.7/.85)`, exactly. For an
+  exact value set `--scrim-edge` and `--scrim-mid` on the scrim element.
+- **Muted ink on a tint is bolder, not greyer.** The secondary grey washes into
+  the media behind a pale tint, so the tint's muted ink is the body colour at
+  semibold. `.scrim-ink-muted` sets that weight; do not add a `font-*` beside it.
+- **Tokens.** `Studio::ThemeResolver` emits `--color-shade` (the dark base) and
+  `--color-tint` (the light base) with the SAME value in both theme blocks, plus
+  their ink pairs `--color-{shade,tint}-ink` and `--color-{shade,tint}-ink-muted`.
+  They follow a custom theme's `dark` and `light` colours. Each ink clears WCAG AA
+  on its own base; contrast over a busy photo depends on the photo, so pick
+  `.scrim-strong` for small or long text.
+- A scrim needs no theme switch of its own: there is no `dark:` variant, because
+  the tone is read from `:root` and the root `.dark` class.
+
+Specimen: `/admin/style` → Tricks → Tints & shades. Definitions and the
+reasoning: `engine.css` (Scrims: tints and shades). Browser proof:
+`e2e/scrim_tones.spec.js`.
+
 ### Smooth-load header pin — `.vt-pinned-header`
 
 When `Studio.smooth_load` is on, put `vt-pinned-header` on the app's sticky
@@ -875,7 +938,9 @@ generated at send time.
 **The scrim** is a wash between artwork and type, on by default at 0.40.
 Background art is chosen to look good, not to guarantee contrast, and white text
 over a pale sky cannot be read. Pass `scrim: 0` for artwork dark enough to carry
-the type itself.
+the type itself. This email scrim is its own fixed shade (`24,16,64`, inline for
+mail clients); it is not the page primitive in [Tints and shades](#tints-and-shades--scrim),
+which mail clients could not render.
 
 **The markup is deliberately old-fashioned.** Outlook on Windows renders through
 Word and ignores `background-image`, so the picture is carried by the `<td

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

@@ -178,6 +178,118 @@ body.modal-open .studio-app-banner {
   @apply bg-inset rounded-xl border border-subtle p-4 overflow-x-auto;
 }
 
+/* -- Scrims: tints and shades ----------------------------------------------
+   A scrim is the wash laid over media (a photo, a video) so text reads on it.
+   It comes in two TONES, and the tone is a design decision, not a colour pick:
+
+     SHADE  the dark base (--color-shade) over the media. It DARKENS it, and
+            LIGHT ink reads on it. The dark theme's natural scrim.
+     TINT   the light base (--color-tint) over the media. It LIGHTENS it, and
+            DARK ink reads on it. The light theme's natural scrim.
+
+   Both tokens are theme-INDEPENDENT (Studio::ThemeResolver#tone_vars emits
+   each with one value in both theme blocks), so a forced tone paints the same
+   in either theme. They follow the theme's own bases, so a custom dark or
+   light colour carries through.
+
+   THE CLASSES
+     .scrim                 paints the wash. With no tone class it is
+                            theme-aware: a tint in light mode, a shade in dark.
+     .scrim-tint            forces a tint, in either theme.
+     .scrim-shade           forces a shade, in either theme.
+     .scrim-soft            a lighter wash (-15 points on both stops).
+     .scrim-strong          a heavier wash (+10 points on both stops).
+     .scrim-ink             the strong ink for text on the tone (headlines).
+     .scrim-ink-muted       the quieter ink (subtitles): on a tint, the body
+                            ink at 600, because the secondary grey washes into
+                            the media; on a shade, the secondary ink at 400.
+
+   THE TONE IS INHERITED CONTEXT, NOT A PROPERTY OF THE WASH. The usual layout
+   puts the scrim and the text as SIBLINGS (an `absolute inset-0` scrim, then
+   a `relative z-10` content box), so the text cannot read anything off the
+   scrim element itself. The tone classes therefore only set custom
+   properties, and those inherit: put `.scrim-shade` on the section and both
+   the wash and every `.scrim-ink` inside it take the shade. With no tone
+   class anywhere, :root and .dark supply the theme-aware default.
+
+   STRENGTH. Each tone carries its own default stops (--scrim-tone-edge /
+   --scrim-tone-mid): a tint 75% / 58% (approved on the hub's landing hero),
+   a shade 85% / 70%. The gradient reads --scrim-edge / --scrim-mid first, so
+   a caller sets either inline for an exact value, and .scrim-soft /
+   .scrim-strong derive them from the tone's own default. Put a strength class
+   on the scrim element itself: --scrim-edge inherits like any custom property.
+
+   THE GRADIENT runs corner to corner (135deg), heavier at both ends than in
+   the middle, so the media shows through where the eye lands least. The
+   default shade is exactly rgba(26,21,53, .85 / .70 / .85) on the default
+   theme: color-mix against `transparent` keeps the colour and scales alpha.
+
+   Every token carries the engine default as a fallback, so an app that sets
+   its own theme vars without studio_theme_css_tag still gets a working wash. */
+:root {
+  --scrim-color:            var(--color-tint, #f8fafc);
+  --scrim-tone-edge:        75%;
+  --scrim-tone-mid:         58%;
+  --scrim-ink:              var(--color-tint-ink, #0f172a);
+  --scrim-ink-muted:        var(--color-tint-ink-muted, #334155);
+  --scrim-ink-muted-weight: 600;
+}
+
+.dark {
+  --scrim-color:            var(--color-shade, #1A1535);
+  --scrim-tone-edge:        85%;
+  --scrim-tone-mid:         70%;
+  --scrim-ink:              var(--color-shade-ink, #ffffff);
+  --scrim-ink-muted:        var(--color-shade-ink-muted, #BAB9C2);
+  --scrim-ink-muted-weight: 400;
+}
+
+@utility scrim {
+  background-image: linear-gradient(
+    135deg,
+    color-mix(in srgb, var(--scrim-color) var(--scrim-edge, var(--scrim-tone-edge)), transparent) 0%,
+    color-mix(in srgb, var(--scrim-color) var(--scrim-mid, var(--scrim-tone-mid)), transparent) 50%,
+    color-mix(in srgb, var(--scrim-color) var(--scrim-edge, var(--scrim-tone-edge)), transparent) 100%
+  );
+}
+
+@utility scrim-tint {
+  --scrim-color:            var(--color-tint, #f8fafc);
+  --scrim-tone-edge:        75%;
+  --scrim-tone-mid:         58%;
+  --scrim-ink:              var(--color-tint-ink, #0f172a);
+  --scrim-ink-muted:        var(--color-tint-ink-muted, #334155);
+  --scrim-ink-muted-weight: 600;
+}
+
+@utility scrim-shade {
+  --scrim-color:            var(--color-shade, #1A1535);
+  --scrim-tone-edge:        85%;
+  --scrim-tone-mid:         70%;
+  --scrim-ink:              var(--color-shade-ink, #ffffff);
+  --scrim-ink-muted:        var(--color-shade-ink-muted, #BAB9C2);
+  --scrim-ink-muted-weight: 400;
+}
+
+@utility scrim-soft {
+  --scrim-edge: calc(var(--scrim-tone-edge) - 15%);
+  --scrim-mid:  calc(var(--scrim-tone-mid) - 15%);
+}
+
+@utility scrim-strong {
+  --scrim-edge: calc(var(--scrim-tone-edge) + 10%);
+  --scrim-mid:  calc(var(--scrim-tone-mid) + 10%);
+}
+
+@utility scrim-ink {
+  color: var(--scrim-ink);
+}
+
+@utility scrim-ink-muted {
+  color: var(--scrim-ink-muted);
+  font-weight: var(--scrim-ink-muted-weight);
+}
+
 /* -- Text + form ----------------------------------------------------------- */
 
 @utility badge {
@@ -518,9 +630,10 @@ body.modal-open .studio-app-banner {
          single frame on a flick — measured 39px in turf-monster, the full
          178 -> 139. navCollapse() converts this to --nav-p units off
          --nav-ramp's 3x relation to the collapse total, so one number covers
-         every band. It binds only a header OUT of the page's flow: a header
-         in flow is held (studio/nav_collapse, the hold), so the page cannot
-         move, and its progress follows the scroll exactly. */
+         every band. It eases every header, held or not: a held header cannot
+         move the page (studio/nav_collapse, the hold), so for it the cap only
+         shapes the header's own motion, and a flick plays as a short animation
+         rather than a one-frame jump. */
       --nav-max-step: 5px;
       --nav-pad: calc(1.5rem - 1rem * var(--nav-p, 0));                 /* py-6 -> py-2 */
       --nav-logo-size: calc(3rem - 1rem * var(--nav-p, 0));             /* 48px -> 32px */

data/app/javascript/studio/nav_collapse.js

@@ -35,12 +35,17 @@
 //   finger moved it, and only the header itself changes size. A header that
 //   is not in flow (fixed or absolute) is left alone: it never moved the page.
 //
-//   (Held, the two guards below exist only for an UNHELD header. The document
-//   no longer shortens, so the short-page flap cannot happen, and the per-frame
-//   cap, which slowed the header so the page it dragged would not jump, now
-//   only makes the header lag the scroll. Worse, a lagging header opens a gap
-//   above the content on a fast scroll back to the top. Held, the progress is
-//   the scroll position, every frame.)
+//   (Held, the short-page guard below is off: the document no longer
+//   shortens, so the flap it prevents cannot happen. The per-frame CAP stays
+//   on. It was written to stop a flick dragging the page, and the hold already
+//   does that; what it buys a held header is the header's own motion. With the
+//   cap off, a flick that crossed the ramp in one frame snapped the header
+//   from full to compact in one frame, which read as a jerk on the hub's
+//   /deployments (2026-10-15). Capped, the header eases over a few frames, and
+//   the page under it still holds, because the hold keeps the document's
+//   height whatever --nav-p is. Easing open after a flick to the top leaves
+//   page background between the header and the content for those frames, the
+//   space the header is growing back into.)
 //
 //   passive + rAF: the listener never blocks the compositor and coalesces a
 //   burst of scroll events (iOS momentum fires far above 60Hz) into one write
@@ -85,7 +90,7 @@ export const DEFAULT_MAX_STEP = 5;
 //   innerHeight   window.innerHeight
 //   reduce        prefers-reduced-motion matches
 //   held          the header holds its footprint (see the hold above): no
-//                 short-page guard, no per-frame cap
+//                 short-page guard; the per-frame cap still eases the header
 //
 // Answers { p, settling }: the progress to publish, and whether the frame
 // clamp left it short of where the scroll position wants it (so the caller
@@ -107,8 +112,6 @@ export function collapseFrame({ y, p, ramp, maxPx, scrollHeight, innerHeight, re
   } else {
     var t = Math.min(1, y / ramp);
     target = t * t * (3 - 2 * t);
-    // Held, the progress IS the scroll position: nothing to cap.
-    if (held) snap = true;
   }
 
   // THE RATE LIMIT: how far the collapse may travel in ONE frame.
@@ -139,7 +142,7 @@ export function collapseFrame({ y, p, ramp, maxPx, scrollHeight, innerHeight, re
   if (snap) {
     // A guard refusal and a reduced-motion state are DECISIONS, not
     // motion; ramping them would animate the very thing each exists to
-    // avoid. A held header follows the scroll exactly.
+    // avoid.
     next = target;
   } else {
     var maxStep = (3 * maxPx) / ramp;

data/app/views/style/_scrims.html.erb

@@ -0,0 +1,67 @@
+<%#  Tints and shades: the scrim primitive's group on the living style guide's
+     Tricks board (admin/style). Rendered by style/_tricks, and by the e2e lab
+     page e2e_lab/scrims, which grades the painted wash and ink in a browser.
+
+     A SHADE lays the dark base over media and light ink reads on it; a TINT
+     lays the light base over media and dark ink reads on it. .scrim alone is
+     theme-aware (a tint in light mode, a shade in dark); .scrim-tint and
+     .scrim-shade force a tone in either theme. The tone classes only set
+     custom properties, which inherit, so each specimen puts its tone on the
+     STAGE and the wash and the text, which are siblings, both take it.
+
+     The striped panel stands in for a photo: vivid and busy, drawn in the role
+     colours, which are the same in both themes, so what changes between
+     specimens is the scrim alone. The
+     definitions and the strength numbers live in engine.css (Scrims: tints
+     and shades) and the README section of the same name. %>
+<%
+  media_style = "background-image: repeating-linear-gradient(135deg, var(--color-primary) 0 18px, var(--color-accent) 18px 36px, var(--color-warning) 36px 54px, var(--color-success) 54px 72px)"
+
+  specimens = [
+    { key: "theme",  tone: nil,           scrim: "scrim",
+      klass: ".scrim",
+      note:  "Theme-aware: a tint in light mode, a shade in dark." },
+    { key: "tint",   tone: "scrim-tint",  scrim: "scrim",
+      klass: ".scrim-tint .scrim",
+      note:  "Forced tint, in either theme. Dark ink." },
+    { key: "shade",  tone: "scrim-shade", scrim: "scrim",
+      klass: ".scrim-shade .scrim",
+      note:  "Forced shade, in either theme. Light ink." },
+    { key: "soft",   tone: nil,           scrim: "scrim scrim-soft",
+      klass: ".scrim .scrim-soft",
+      note:  "A lighter wash: more of the media shows." },
+    { key: "strong", tone: nil,           scrim: "scrim scrim-strong",
+      klass: ".scrim .scrim-strong",
+      note:  "A heavier wash, for long or small text." }
+  ]
+%>
+<section id="scrims" class="space-y-5" data-scrim-group>
+  <div class="space-y-1">
+    <h3 class="text-xl font-bold text-heading">Tints &amp; shades</h3>
+    <p class="text-muted text-sm max-w-2xl">
+      A <strong>shade</strong> lays the dark base over media and light ink reads on it; a
+      <strong>tint</strong> lays the light base over media and dark ink reads on it.
+      <code class="font-mono text-2xs">.scrim</code> picks by theme;
+      <code class="font-mono text-2xs">.scrim-tint</code> / <code class="font-mono text-2xs">.scrim-shade</code>
+      force one. Put the tone on the shared parent so the wash and the
+      <code class="font-mono text-2xs">.scrim-ink</code> text both take it.
+    </p>
+  </div>
+  <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+    <% specimens.each do |s| %>
+      <% tone_attr = s[:tone] ? %( class="#{s[:tone]} relative ...") : %( class="relative ...") %>
+      <%= render layout: "style/specimen",
+            locals: { klass: s[:klass],
+                      usage: %(<section#{tone_attr}>\n  <img class="absolute inset-0 ..." src="...">\n  <div class="#{s[:scrim]} absolute inset-0"></div>\n  <div class="relative z-10">\n    <h2 class="scrim-ink">Headline</h2>\n    <p class="scrim-ink-muted">Subtitle</p>\n  </div>\n</section>) } do %>
+        <div class="relative w-full max-w-xs h-36 rounded-lg overflow-hidden <%= s[:tone] %>" data-scrim-specimen="<%= s[:key] %>">
+          <div class="absolute inset-0" style="<%= media_style %>" aria-hidden="true"></div>
+          <div class="<%= s[:scrim] %> absolute inset-0" data-scrim-wash></div>
+          <div class="relative z-10 h-full flex flex-col items-center justify-center gap-1 px-4 text-center">
+            <p class="scrim-ink text-lg font-extrabold" data-scrim-ink>Solutions For Business</p>
+            <p class="scrim-ink-muted text-sm" data-scrim-ink-muted><%= s[:note] %></p>
+          </div>
+        </div>
+      <% end %>
+    <% end %>
+  </div>
+</section>

data/app/views/style/_tricks.html.erb

@@ -34,8 +34,8 @@
     <p class="text-muted text-sm max-w-2xl">
       A board of style tricks you can see and hand to an agent to use out of the box.
       Each specimen surfaces the rendered primitive, its <strong>class name (one-click
-      copy)</strong>, and a copyable usage snippet - the button, surface, motion, effect,
-      and leveling primitives. The color tokens live in <a href="#theme" class="underline">Theme</a>.
+      copy)</strong>, and a copyable usage snippet - the button, surface, scrim, motion,
+      effect, and leveling primitives. The color tokens live in <a href="#theme" class="underline">Theme</a>.
     </p>
   </div>
 
@@ -113,6 +113,9 @@
     </div>
   </section>
 
+  <!-- Tints and shades: the scrim primitive -->
+  <%= render "style/scrims" %>
+
   <!-- Time stamps: the "at" format -->
   <section class="space-y-5">
     <div class="space-y-1">

data/lib/studio/theme_resolver.rb

@@ -28,23 +28,60 @@ module Studio
     end
 
     def to_css
-      dark_vars  = dark_mode_vars.map { |k, v| "  #{k}: #{v};" }.join("\n")
-      light_vars = light_mode_vars.map { |k, v| "  #{k}: #{v};" }.join("\n")
+      dark  = dark_mode_vars
+      light = light_mode_vars
+      dark_vars  = dark.map { |k, v| "  #{k}: #{v};" }.join("\n")
+      light_vars = light.map { |k, v| "  #{k}: #{v};" }.join("\n")
       palette_vars = primary_palette_vars.map { |k, v| "  #{k}: #{v};" }.join("\n")
+      tone_css     = tone_vars(dark, light).map { |k, v| "  #{k}: #{v};" }.join("\n")
 
       <<~CSS
         :root, .dark {
         #{dark_vars}
         #{palette_vars}
+        #{tone_css}
         }
 
         html:not(.dark) {
         #{light_vars}
         #{palette_vars}
+        #{tone_css}
         }
       CSS
     end
 
+    # THE SHADE AND THE TINT — the two tones the scrim primitive lays over
+    # media (engine.css `.scrim`, README "Tints and shades").
+    #
+    # A SHADE is the dark base over a photo: it darkens it, and light ink reads
+    # on it. A TINT is the light base over a photo: it lightens it, and dark
+    # ink reads on it. They are the same pair as the two themes' page colours,
+    # but these tokens are THEME-INDEPENDENT: emitted with one value in both
+    # blocks, so a forced `.scrim-shade` is the dark base in light mode too.
+    # --color-page cannot serve, because it flips with the theme.
+    #
+    # Each tone carries its ink pair, also theme-independent, because text on a
+    # forced tone in the opposite theme cannot use --color-text (it would be
+    # light ink on a tint). The pairs are the two themes' own inks, chosen so
+    # the theme-aware `.scrim` matches the page's text exactly:
+    #   shade: --color-text (#fff) and the dark --color-text-secondary;
+    #   tint:  --color-text (#0f172a) and the light --color-text-BODY, which
+    #          `.scrim-ink-muted` sets at 600. Not the light secondary grey:
+    #          on the hub hero it washed into the skyline behind the tint, and
+    #          the body ink at semibold is the treatment Alex approved.
+    # Takes the two mode hashes when the caller already built them (to_css),
+    # so the contrast searches behind them run once per render, not twice.
+    def tone_vars(dark = dark_mode_vars, light = light_mode_vars)
+      {
+        "--color-shade"           => dark["--color-page"],
+        "--color-shade-ink"       => dark["--color-text"],
+        "--color-shade-ink-muted" => dark["--color-text-secondary"],
+        "--color-tint"            => light["--color-page"],
+        "--color-tint-ink"        => light["--color-text"],
+        "--color-tint-ink-muted"  => light["--color-text-body"]
+      }
+    end
+
     def dark_mode_vars
       dark_base   = colors[:dark] || "#1A1535"
       primary     = colors[:primary] || DEFAULT_PRIMARY

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.108.0"
+  VERSION = "0.109.0.rc2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.108.0
+  version: 0.109.0.rc2
 platform: ruby
 authors:
 - Alex McRitchie
@@ -674,6 +674,7 @@ files:
 - app/views/style/_host.html.erb
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
+- app/views/style/_scrims.html.erb
 - app/views/style/_site_footer.html.erb
 - app/views/style/_specimen.html.erb
 - app/views/style/_tasks.html.erb