studio-engine 0.108.0.rc2 → 0.109.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2990527dd511a02eea248d9a8ceb2e5f2df97b2b19423f3022b864ea162e38b0
-  data.tar.gz: 24d9da854c8773924858c46fe3bcf31e81ecf4b2e5a1c40b629e16067ad661ac
+  metadata.gz: 1a916913ae747d410986fa4bc0f8abef5379e749678542100a0c396a954ff05e
+  data.tar.gz: 8816f7f0bc15437c3f509ce93c38e9d4d52b2425c81ed1f63a48f8022e21d0e9
 SHA512:
-  metadata.gz: 847d51a58aafc2e75e1d7621cdb674b4dda4c6d54b30676a95803fe5980ad5630392ead197848afe25255b8176cc7754b34c6971a1a27c5fc0f9a162c898c6f6
-  data.tar.gz: fc2bfa04fe01978a9b60ad854553cf89c6d1cb250ebe9ff0c5b75c9b09b49b02ba3a0203e069b32e774763d6505400f4a8a5c5c5574479a39f353e3606451557
+  metadata.gz: 105b1f39b9c67041a6bae67a769f65ecb54f75abad1cea11088df3d69e98c83c75fd5c705eb17c8384a513f6d58488ffb36633a6af6955ca242bc504c4881670
+  data.tar.gz: 2dd6e01fc32d25b69558452f39351c5e3bc5e98b35da3064ea12eb10f8a4f1aba9fcee8f39cbe57cb325109ab64e5624c65ed50d035156e050dcf152ff8ef2e6

data/CHANGELOG.md

@@ -4,8 +4,24 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 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 {

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.rc2"
+  VERSION = "0.109.0.rc1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.108.0.rc2
+  version: 0.109.0.rc1
 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