studio-engine 0.127.0 → 0.128.0

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

@@ -163,16 +163,22 @@ body.modal-open .studio-app-banner {
 
 /* -- Surfaces -------------------------------------------------------------- */
 
+/* --surface-card-fill is unset unless an app opts in to the glass surfaces (THE GLASS SURFACES,
+   below). A token and not a higher-specificity rule, so a card's own tone still wins: a bg-warning/5,
+   a border-danger or a hover:bg-surface-alt on the element beats this as it always did. */
 @utility card {
-  @apply bg-surface rounded-xl border border-subtle;
+  @apply rounded-xl border border-subtle;
+  background-color: var(--surface-card-fill, var(--color-surface));
 }
 
 @utility card-hover {
-  @apply bg-surface rounded-xl border border-subtle hover:border-primary-700/50 hover:shadow-lg hover:shadow-primary-900/10 transition;
+  background-color: var(--surface-card-fill, var(--color-surface));
+  @apply rounded-xl border border-subtle hover:border-primary-700/50 hover:shadow-lg hover:shadow-primary-900/10 transition;
 }
 
 @utility empty-state {
-  @apply bg-surface rounded-xl border border-subtle p-8 text-center;
+  @apply rounded-xl border border-subtle p-8 text-center;
+  background-color: var(--surface-card-fill, var(--color-surface));
 }
 
 @utility json-debug {
@@ -223,6 +229,36 @@ body.modal-open .studio-app-banner {
   line-height: 1.4;
 }
 
+/* THE TYPE LADDER, on trial on /admin/style (Alex McRitchie, 2026-11-04: "standardize font
+   sizes across pages"). A role sets size, weight and line height; the tag stays whatever the
+   document outline needs, so a page's one <h1> may wear type-h2. These sizes are fixed px, so
+   type-dense does not move them. On Studio::TypeScale: h1 (3x of 16) and h4 (1x of 16). Off it,
+   on purpose: h2 and h3, the two steps the scale lacks between 3x and 1.5x and below 1.5x.
+   Body and fine print are the scale's own type-body and type-fine. */
+@utility type-h1 {
+  font-size: 48px;
+  font-weight: var(--type-display-weight, 800);
+  line-height: 1.1;
+}
+
+@utility type-h2 {
+  font-size: 30px;
+  font-weight: var(--type-display-weight, 800);
+  line-height: 1.2;
+}
+
+@utility type-h3 {
+  font-size: 20px;
+  font-weight: 700;
+  line-height: 1.3;
+}
+
+@utility type-h4 {
+  font-size: 16px;
+  font-weight: 600;
+  line-height: 1.4;
+}
+
 /* -- The page header (studio/_page_header, docs/PAGE_HEADER.md) ---------
    A normal page header at rest and a bar once stuck. The border is there in
    both states, in transparent at rest, so the row's height never changes and
@@ -282,6 +318,13 @@ body.modal-open .studio-app-banner {
   overflow-y: clip;
 }
 
+/* The trial's one reach into the page header: the shared title keeps its own size everywhere
+   but under this attribute. Same numbers as type-h2. */
+[data-type-ladder] .page-header-title {
+  font-size: 30px;
+  line-height: 1.2;
+}
+
 @utility page-header-meta {
   white-space: nowrap;
 
@@ -668,16 +711,18 @@ body.modal-open .studio-app-banner {
 }
 
 /* -- App-to-app page transitions --------------------------------------------
-   Studio.page_transition_direction (studio/page_transitions, docs/PAGE_TRANSITIONS.md).
-   Every rule is gated on an attribute only that script sets, so an app without
-   the setting keeps the fade above. Attribute selectors outrank the bare
-   ::view-transition-*(root) rules, here and in a host. The effects are from the
-   Codrops Page Transitions demo, at its values; the keyframes were written fresh.
-
-   Black behind the pages gives the shading: a page at opacity 0.3 darkens as it
-   moves. */
+   Studio.page_transition_direction and Studio.page_transition_style
+   (studio/page_transitions, docs/PAGE_TRANSITIONS.md). Every rule is gated on an
+   attribute only that script sets, so an app without the setting keeps the fade
+   above. Attribute selectors outrank the bare ::view-transition-*(root) rules, here
+   and in a host. The effects are from the Codrops Page Transitions demo; the
+   keyframes were written fresh.
+
+   The app's own page color sits behind the pages, so no gap reads as a dark band.
+   Each page stays opaque as it moves: a page color seen through a fading page
+   would still shade it. The fallback covers a layout with no runtime theme block. */
 html[data-page-transition]:not([data-page-transition="still"])::view-transition {
-  background: #000;
+  background: var(--color-page, Canvas);
 }
 
 html[data-page-transition]::view-transition-old(root),
@@ -723,14 +768,14 @@ html[data-page-transition-direction]:not([data-page-transition-morph]) [data-vt-
   view-transition-name: none !important;
 }
 
-html[data-page-transition="fade-left"]::view-transition-old(root) { animation-name: pt-out-left; }
-html[data-page-transition="fade-left"]::view-transition-new(root) { animation-name: pt-in-from-right; }
-html[data-page-transition="fade-right"]::view-transition-old(root) { animation-name: pt-out-right; }
-html[data-page-transition="fade-right"]::view-transition-new(root) { animation-name: pt-in-from-left; }
-html[data-page-transition="fade-top"]::view-transition-old(root) { animation-name: pt-out-top; }
-html[data-page-transition="fade-top"]::view-transition-new(root) { animation-name: pt-in-from-bottom; }
-html[data-page-transition="fade-bottom"]::view-transition-old(root) { animation-name: pt-out-bottom; }
-html[data-page-transition="fade-bottom"]::view-transition-new(root) { animation-name: pt-in-from-top; }
+html[data-page-transition="slide-left"]::view-transition-old(root) { animation-name: pt-out-left; }
+html[data-page-transition="slide-left"]::view-transition-new(root) { animation-name: pt-in-from-right; }
+html[data-page-transition="slide-right"]::view-transition-old(root) { animation-name: pt-out-right; }
+html[data-page-transition="slide-right"]::view-transition-new(root) { animation-name: pt-in-from-left; }
+html[data-page-transition="slide-top"]::view-transition-old(root) { animation-name: pt-out-top; }
+html[data-page-transition="slide-top"]::view-transition-new(root) { animation-name: pt-in-from-bottom; }
+html[data-page-transition="slide-bottom"]::view-transition-old(root) { animation-name: pt-out-bottom; }
+html[data-page-transition="slide-bottom"]::view-transition-new(root) { animation-name: pt-in-from-top; }
 
 html[data-page-transition="unfold-right"]::view-transition-old(root) { animation-name: pt-out-left; }
 html[data-page-transition="unfold-right"]::view-transition-new(root) { animation-name: pt-unfold-right; transform-origin: 0% 50%; }
@@ -741,14 +786,14 @@ html[data-page-transition="unfold-bottom"]::view-transition-new(root) { animatio
 html[data-page-transition="unfold-top"]::view-transition-old(root) { animation-name: pt-out-bottom; }
 html[data-page-transition="unfold-top"]::view-transition-new(root) { animation-name: pt-unfold-top; transform-origin: 50% 100%; }
 
-@keyframes pt-out-left { to { opacity: 0.3; transform: translateX(-100%); } }
-@keyframes pt-out-right { to { opacity: 0.3; transform: translateX(100%); } }
-@keyframes pt-out-top { to { opacity: 0.3; transform: translateY(-100%); } }
-@keyframes pt-out-bottom { to { opacity: 0.3; transform: translateY(100%); } }
-@keyframes pt-in-from-right { from { opacity: 0.3; transform: translateX(100%); } }
-@keyframes pt-in-from-left { from { opacity: 0.3; transform: translateX(-100%); } }
-@keyframes pt-in-from-bottom { from { opacity: 0.3; transform: translateY(100%); } }
-@keyframes pt-in-from-top { from { opacity: 0.3; transform: translateY(-100%); } }
+@keyframes pt-out-left { to { transform: translateX(-100%); } }
+@keyframes pt-out-right { to { transform: translateX(100%); } }
+@keyframes pt-out-top { to { transform: translateY(-100%); } }
+@keyframes pt-out-bottom { to { transform: translateY(100%); } }
+@keyframes pt-in-from-right { from { transform: translateX(100%); } }
+@keyframes pt-in-from-left { from { transform: translateX(-100%); } }
+@keyframes pt-in-from-bottom { from { transform: translateY(100%); } }
+@keyframes pt-in-from-top { from { transform: translateY(-100%); } }
 @keyframes pt-unfold-right { from { opacity: 0; transform: perspective(1200px) translateX(100%) rotateY(90deg); } }
 @keyframes pt-unfold-left { from { opacity: 0; transform: perspective(1200px) translateX(-100%) rotateY(-90deg); } }
 @keyframes pt-unfold-bottom { from { opacity: 0; transform: perspective(1200px) translateY(100%) rotateX(-90deg); } }
@@ -1107,7 +1152,10 @@ html[data-page-transition="unfold-top"]::view-transition-new(root) { animation-n
        It is a pseudo-element of the panel: it moves with the slide, it leaves with the
        panel, and it takes no clicks, so an outside click still reaches the page. A
        transform on the panel does not start a new backdrop root, so it blurs the page.
-       40px wide, a 6px blur, held for the 10px nearest the panel, then fading to sharp.
+       100px wide, a 6px blur, on an eased mask: whole at the panel, half at 60px, nothing
+       at the far end, and flat at both ends, so no stop shows as a line where the blur
+       ends. A hold and a straight fade showed that line over a photo. A blur reads only
+       above about half strength, so the 50% stop sits past the middle to carry it out.
        right: 100% measures from the padding box, so the band runs over the panel's 1px
        border. Stopping short of it left the border as a lit line beside the blur.
 
@@ -1120,14 +1168,448 @@ html[data-page-transition="unfold-top"]::view-transition-new(root) { animation-n
         position: absolute;
         inset-block: 0;
         right: 100%;
-        width: 2.5rem;
+        width: 6.25rem;
         pointer-events: none;
         -webkit-backdrop-filter: blur(6px);
         backdrop-filter: blur(6px);
-        -webkit-mask-image: linear-gradient(to left, #000 25%, transparent);
-        mask-image: linear-gradient(to left, #000 25%, transparent);
+        -webkit-mask-image: linear-gradient(to left, #000, rgb(0 0 0 / 0.99) 10%, rgb(0 0 0 / 0.96) 20%, rgb(0 0 0 / 0.9) 30%, rgb(0 0 0 / 0.8) 40%, rgb(0 0 0 / 0.66) 50%, rgb(0 0 0 / 0.5) 60%, rgb(0 0 0 / 0.33) 70%, rgb(0 0 0 / 0.17) 80%, rgb(0 0 0 / 0.05) 90%, transparent);
+        mask-image: linear-gradient(to left, #000, rgb(0 0 0 / 0.99) 10%, rgb(0 0 0 / 0.96) 20%, rgb(0 0 0 / 0.9) 30%, rgb(0 0 0 / 0.8) 40%, rgb(0 0 0 / 0.66) 50%, rgb(0 0 0 / 0.5) 60%, rgb(0 0 0 / 0.33) 70%, rgb(0 0 0 / 0.17) 80%, rgb(0 0 0 / 0.05) 90%, transparent);
+      }
+    }
+
+    /* THE GLASS SIDEBAR (Studio.sidebar_style = :glass, components/_sidebar_panel glass: true).
+       A rounded panel floats off the page's edge with the page blurred through it.
+
+       TWO BOXES. The aside keeps the drawer's geometry: its top and height from --nav-bottom,
+       data-pin-edge's scroll animation, and Alpine's translate-x-full slide, which now carries
+       the inset off screen with it. It is a clear frame that takes no clicks, so a click in
+       the inset reaches the page and closes the panel like any outside click. The shell inside
+       holds the fill and the blur. That keeps the containing block a backdrop-filter makes off
+       the element Alpine, Turbo's snapshot and a view transition move.
+
+       THE FILL IS THE FALLBACK. Here it is nearly solid, so a browser with no backdrop-filter,
+       or a reader who asks for less transparency, still gets readable text. The @supports rule
+       thins it where the browser says it has the blur.
+
+       CONTRAST. The worst page behind the panel is the opposite of its theme: a white image
+       under dark glass, a black one under light. A browser can claim the blur and not paint it, so
+       the thin fill alone holds resting soft ink at 4.5:1 over both, and brightness() only adds
+       to that. A thinner fill looks more like glass and fails over a white page.
+
+       IT HANGS FROM THE NAVBAR. The frame has no top padding, so no page shows between the
+       navbar and the panel, and the shell's top is square with no top border: the navbar is
+       its top edge. The sides and the bottom keep the inset and the round corners. The frame
+       still takes its top from --nav-bottom and data-pin-edge, so it follows every navbar state.
+
+       SPACING IS FIVE TOKENS, on the shell: --glass-row-height, --glass-row-gap between rows,
+       --glass-icon-size, --glass-icon-gap between icon and label, and --glass-section-gap,
+       which sets the space under a section and above its header and from which the title and
+       Log out padding derive. A row's no-jump description needs no rule of its own: the 18px
+       label and 14px description take 32px, and with the lift at 7px a 44px row leaves 6px above
+       and below them.
+
+       THE PHONE gets a narrower inset, the full width and a lighter blur, which costs less
+       through the slide. */
+    [data-sidebar-glass] {
+      --sidebar-glass-inset: 0.75rem;
+      width: 19.5rem;
+      padding: 0 var(--sidebar-glass-inset) var(--sidebar-glass-inset);
+      pointer-events: none;
+    }
+    [data-sidebar-glass-shell] {
+      --glass-row-height: 2.75rem;
+      --glass-row-gap: 0.125rem;
+      --glass-icon-size: 1.375rem;
+      --glass-icon-gap: 0.625rem;
+      --glass-section-gap: 1rem;
+      --sidebar-row-lift: 0.4375rem;
+      --glass-fill: rgb(250 249 253 / 0.97);
+      --glass-thin-fill: rgb(255 255 255 / 0.72);
+      --glass-filter: blur(24px) saturate(150%) brightness(1.15);
+      --glass-ink: #1d1832;
+      --glass-soft-ink: #474260;
+      --glass-hover: rgb(29 24 50 / 0.08);
+      --glass-line: rgb(29 24 50 / 0.14);
+      --glass-shadow: 0 24px 60px rgb(29 24 50 / 0.24);
+      pointer-events: auto;
+      overflow: hidden;
+      min-height: 0;
+      border: 1px solid var(--glass-line);
+      border-top: 0;
+      border-radius: 0 0 1.125rem 1.125rem;
+      background-color: var(--glass-fill);
+      box-shadow: var(--glass-shadow);
+      color: var(--glass-ink);
+      font-size: 0.84375rem;
+    }
+    .dark [data-sidebar-glass-shell] {
+      --glass-fill: rgb(36 30 62 / 0.97);
+      --glass-thin-fill: rgb(36 30 62 / 0.72);
+      --glass-filter: blur(24px) saturate(150%) brightness(0.8);
+      --glass-ink: #f1effa;
+      --glass-soft-ink: #dedaed; /* 4.5:1 on the thin fill alone over white, if a blur never paints */
+      --glass-hover: rgb(255 255 255 / 0.1);
+      --glass-line: rgb(255 255 255 / 0.14);
+      --glass-shadow: 0 24px 60px rgb(0 0 0 / 0.5);
+    }
+    /* The less-transparency rule turns the blur off, rather than this rule asking for that
+       setting's absence: a browser that does not know the media feature answers false to a
+       not query as well, which left Safari and Firefox on the solid fill. */
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      [data-sidebar-glass-shell] {
+        background-color: var(--glass-thin-fill);
+        -webkit-backdrop-filter: var(--glass-filter);
+        backdrop-filter: var(--glass-filter);
+      }
+      @media (prefers-reduced-transparency: reduce) {
+        [data-sidebar-glass-shell] {
+          background-color: var(--glass-fill);
+          -webkit-backdrop-filter: none;
+          backdrop-filter: none;
+        }
+      }
+    }
+    @media (max-width: 47.99rem) {
+      [data-sidebar-glass] {
+        --sidebar-glass-inset: 0.5rem;
+        width: 100%;
+      }
+      [data-sidebar-glass-shell] { --glass-filter: blur(16px) saturate(150%); }
+      .dark [data-sidebar-glass-shell] { --glass-filter: blur(16px) saturate(150%) brightness(0.8); }
+    }
+    [data-sidebar-glass-head] {
+      padding: calc(var(--glass-section-gap) + 0.25rem) 0.875rem calc(var(--glass-section-gap) * 0.75) 1.125rem;
+      border-bottom: 0;
+    }
+    [data-sidebar-glass-head] [data-link-sidebar-title],
+    [data-sidebar-glass-head] [data-sidebar-panel-lead] > * {
+      color: var(--glass-ink);
+      font-size: 0.9375rem;
+      font-weight: 600;
+    }
+    [data-sidebar-glass-head] [data-link-sidebar-close] { color: var(--glass-soft-ink); }
+    [data-sidebar-glass-head] [data-link-sidebar-close]:hover {
+      color: var(--glass-ink);
+      background-color: var(--glass-hover);
+    }
+    [data-sidebar-glass-shell] nav { padding-block: 0; scrollbar-width: thin; scrollbar-color: var(--glass-line) transparent; }
+    [data-sidebar-glass-shell] nav > [role="group"] { padding: 0 0.625rem var(--glass-section-gap); }
+    [data-sidebar-glass-shell] [data-sidebar-group-header] {
+      padding: calc(var(--glass-section-gap) * 0.5) 0.5rem 0.375rem;
+      color: var(--glass-soft-ink);
+      font-size: 0.6875rem;
+      font-weight: 600;
+      letter-spacing: normal;
+      text-transform: none;
+    }
+    [data-sidebar-glass-shell] nav > [role="group"] > :is(a, [aria-disabled]),
+    [data-sidebar-glass-foot] > a {
+      height: var(--glass-row-height);
+      gap: var(--glass-icon-gap);
+      padding: 0 0.5rem 0 0.375rem;
+      border-radius: 0.625rem;
+      color: var(--glass-ink);
+      font-size: inherit;
+      font-weight: 500;
+      line-height: 1.125rem;
+    }
+    [data-sidebar-glass-shell] nav > [role="group"] > :is(a, [aria-disabled]):hover,
+    [data-sidebar-glass-foot] > a:hover {
+      color: var(--glass-ink);
+      background-color: var(--glass-hover);
+    }
+    [data-sidebar-glass-shell] [data-sidebar-row-desc] {
+      color: var(--glass-soft-ink);
+      font-size: 0.6875rem;
+      line-height: 0.875rem;
+    }
+    [data-sidebar-glass-shell] nav > [role="group"] > a[aria-current="page"],
+    [data-sidebar-glass-shell] nav > [role="group"] > a[aria-current="page"]:hover {
+      /* A step down the primary's own scale: white on the hub's primary is 3.1:1, and this
+         mix holds 4.5:1 and still reads as the brand's violet. */
+      background-color: color-mix(in srgb, var(--color-primary-600) 65%, var(--color-primary-700));
+      box-shadow: 0 4px 14px rgb(var(--color-primary-rgb) / 0.4);
+      color: #fff;
+    }
+    /* The glow above outranks the row's focus ring, which is a box-shadow. This ring is an
+       outline set inside the edge, so the row's own fill shows on both sides of it: at the
+       edge, white would melt into the light theme's panel. */
+    [data-sidebar-glass-shell] nav > [role="group"] > a[aria-current="page"]:focus-visible {
+      outline: 2px solid #fff;
+      outline-offset: -4px;
+    }
+    [data-sidebar-glass-shell] a[aria-current="page"] [data-sidebar-row-desc] { color: rgb(255 255 255 / 0.9); }
+    [data-sidebar-glass-shell] nav > [role="group"] > a + a { margin-top: var(--glass-row-gap); }
+    /* The fixed column: a line icon sits in the 24px box the engine's emoji and portrait rows
+       already take (EMOJI_SWAP_CSS), so every label starts at one x. A line icon, a portrait
+       and an emoji all draw at --glass-icon-size. The swap's box is 1.25em tall and clips, so
+       the font size is what keeps an emoji or a portrait whole. A host's portrait class asks
+       for 20px, and the helper's svg for 18. */
+    [data-sidebar-glass-shell] [data-sidebar-row-icon] {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: 1.5rem;
+      height: var(--glass-icon-size);
+    }
+    [data-sidebar-glass-shell] [data-sidebar-row-icon] svg,
+    [data-sidebar-glass-shell] nav > [role="group"] > a > :is(.studio-emoji-box, .studio-emoji-swap) img {
+      width: var(--glass-icon-size);
+      height: var(--glass-icon-size);
+    }
+    [data-sidebar-glass-shell] nav > [role="group"] > a > :is(.studio-emoji-box, .studio-emoji-swap) {
+      font-size: calc(var(--glass-icon-size) / 1.25);
+    }
+    [data-sidebar-glass-foot] {
+      padding: calc(var(--glass-section-gap) * 0.625) 0.625rem;
+      border-top: 1px solid var(--glass-line);
+    }
+
+    /* THE GLASS SURFACES (Studio.surface_style = :glass, on the host's root as
+       html[data-surface-style="glass"]). A card turns translucent over a soft ambient page.
+
+       THE AMBIENT PAGE IS WHAT MAKES IT READ. On a flat page a translucent card looks like a
+       flat tinted one, so body::before lays low glows behind everything. It is one fixed layer
+       behind the content, so a scroll does not repaint it.
+
+       TWO TIERS. A dense card (--surface-glass-card) gets fill, hairline, top highlight and
+       soft shadow, with no backdrop-filter: a board holds a hundred of them. A card a host
+       marks with .surface-glass-blur, or a page's few big panels, adds the real blur. The
+       fill is the same in both, so a browser with no backdrop-filter draws the first tier.
+
+       WHAT IT REACHES: .card, .card-hover, .empty-state, and a hand-rolled panel spelled
+       .bg-surface.rounded-xl.border. NOT a menu, popover or modal: anything .absolute, .fixed,
+       .sticky or .shadow-2xl, or inside a .fixed scrim or a dialog, stays solid, because it
+       floats over text and has no blur to protect it. Under prefers-reduced-transparency
+       every surface goes solid. */
+    html[data-surface-style="glass"] {
+      --surface-glass-fill: color-mix(in srgb, var(--color-surface) 62%, transparent);
+      --surface-glass-fill-hover: color-mix(in srgb, var(--color-surface) 80%, transparent);
+      --surface-glass-line: rgb(29 24 50 / 0.1);
+      --surface-glass-highlight: inset 0 1px 0 rgb(255 255 255 / 0.7);
+      --surface-glass-shadow: 0 6px 20px rgb(60 50 120 / 0.08);
+      --surface-glass-filter: blur(16px) saturate(140%);
+      --surface-glass-ambient:
+        radial-gradient(60vw 55vh at 10% 5%, rgb(var(--color-primary-rgb) / 0.17), transparent 70%),
+        radial-gradient(50vw 60vh at 92% 30%, rgb(56 130 246 / 0.1), transparent 70%),
+        radial-gradient(70vw 55vh at 45% 100%, rgb(var(--color-primary-rgb) / 0.14), transparent 70%);
+    }
+    html.dark[data-surface-style="glass"] {
+      --surface-glass-fill: color-mix(in srgb, var(--color-surface) 52%, transparent);
+      --surface-glass-fill-hover: color-mix(in srgb, var(--color-surface) 72%, transparent);
+      --surface-glass-line: rgb(255 255 255 / 0.1);
+      --surface-glass-highlight: inset 0 1px 0 rgb(255 255 255 / 0.08);
+      --surface-glass-shadow: 0 8px 24px rgb(0 0 0 / 0.22);
+      --surface-glass-ambient:
+        radial-gradient(60vw 55vh at 10% 5%, rgb(var(--color-primary-rgb) / 0.2), transparent 70%),
+        radial-gradient(50vw 60vh at 92% 30%, rgb(56 130 246 / 0.1), transparent 70%),
+        radial-gradient(70vw 55vh at 45% 100%, rgb(var(--color-primary-rgb) / 0.14), transparent 70%);
+    }
+    html[data-surface-style="glass"] body::before {
+      content: "";
+      position: fixed;
+      inset: 0;
+      z-index: -1;
+      pointer-events: none;
+      background-image: var(--surface-glass-ambient);
+    }
+    /* A CARD KEEPS WHAT IT SAYS. Glass sets no border and no tone. The fill of .card, .card-hover and
+       .empty-state is a token its own utility reads, so an authored bg-*, border-* or focus-within:*
+       on the element wins as it always did. A hand-rolled panel has .bg-surface, so it has no tone to
+       lose, and only its fill changes. The shadow list carries the element's own ring and shadow. */
+    html[data-surface-style="glass"] { --surface-card-fill: var(--surface-glass-fill); }
+    html[data-surface-style="glass"] :is(.card, .card-hover, .empty-state):is(.absolute, .fixed, .sticky, .shadow-2xl, .fixed *, [role="dialog"] *) { --surface-card-fill: var(--color-surface); }
+    html[data-surface-style="glass"] :is(.card-hover, a.card):not(.absolute, .fixed, .sticky, .shadow-2xl, .fixed *, [role="dialog"] *):hover { --surface-card-fill: var(--surface-glass-fill-hover); }
+    html[data-surface-style="glass"] .bg-surface.rounded-xl.border:not(.absolute, .fixed, .sticky, .shadow-2xl, .fixed *, [role="dialog"] *) { background-color: var(--surface-glass-fill); }
+    html[data-surface-style="glass"] :is(.card, .card-hover, .empty-state, .bg-surface.rounded-xl.border):not(.absolute, .fixed, .sticky, .shadow-2xl, .fixed *, [role="dialog"] *) {
+      box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000),
+        var(--surface-glass-highlight), var(--surface-glass-shadow), var(--tw-shadow, 0 0 #0000);
+    }
+    /* A backdrop-filter starts a stacking context and a containing block, so a tooltip inside
+       a blurred card must lift the card above its neighbours. */
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      html[data-surface-style="glass"] .surface-glass-blur {
+        -webkit-backdrop-filter: var(--surface-glass-filter);
+        backdrop-filter: var(--surface-glass-filter);
+      }
+      html[data-surface-style="glass"] .surface-glass-blur:is(:hover, :focus-within) { position: relative; z-index: 2; }
+      /* The navbar is a blurred bar already. Thinner, the ambient page runs under it and no
+         hard edge marks where the page begins. */
+      html[data-surface-style="glass"] .nav-shell {
+        background-color: color-mix(in srgb, var(--color-page) 62%, transparent);
+        -webkit-backdrop-filter: blur(18px) saturate(140%);
+        backdrop-filter: blur(18px) saturate(140%);
+      }
+    }
+
+    /* THE STICKY PAGE HEADER UNDER GLASS. Stuck, the shared rule fills it with surface grey.
+       Here it is a bar like the sidebar: square against the navbar, round at the bottom, a
+       hairline edge and the same top light. Opaque page color without a blur; thin with one.
+       A failed page-header controller takes the same bar, as it takes the grey one today. */
+    html[data-surface-style="glass"] .page-header:is([data-stuck], [data-studio-controller-failed~="page-header"] + .page-header) {
+      background-color: var(--color-page);
+      border-top-color: transparent;
+      border-bottom-color: var(--surface-glass-line);
+      border-radius: 0 0 0.875rem 0.875rem;
+      box-shadow: var(--surface-glass-highlight), var(--surface-glass-shadow);
+    }
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      html[data-surface-style="glass"] .page-header:is([data-stuck], [data-studio-controller-failed~="page-header"] + .page-header) {
+        background-color: color-mix(in srgb, var(--color-page) 62%, transparent);
+        -webkit-backdrop-filter: blur(18px) saturate(140%);
+        backdrop-filter: blur(18px) saturate(140%);
+      }
+    }
+
+    /* LIT FROM ABOVE, under the same opt-in: one light for buttons, badges and inputs, from the
+       direction of the cards' top highlight. Four shadows: top light, bottom shade, contact, and
+       a glow in the button's own color.
+
+       THE GRADIENT KEEPS ITS CHROMA. Both stops are built in oklch from the token, a brighter
+       and an equally saturated top over a deep saturated bottom; mixing toward black or grey is
+       what mutes a button. White text is held to 4.5:1 against the midpoint behind it, so the
+       top stop reads lower, as it does in the rule this follows.
+
+       WHO GETS WHAT. Every full-size filled button: gradient, top, bottom, contact and a glow in
+       its own color, on the same 0.15 lightness range. A .btn-sm has no glow, since a toolbar or
+       a board of them would be noise. Neutral,
+       outline and google, which includes a resting tab: top, bottom, contact, softer. Badges: a
+       small top light and contact, no press. Inputs read pressed in. Disabled is flat.
+
+       THE PRESS flips the shadow to inset. Only a full-size button also moves 1px: translate
+       takes no layout, but a toolbar row of small buttons should not jitter, and reduced motion
+       never moves.
+
+       FOCUS IS AN OUTLINE on .btn, which no box-shadow here touches. Each list names the ring
+       variables on the element itself: declared once on the root they would resolve there, to no
+       ring. A button that spells its own bg-* or border-* keeps it.
+
+       EDGE TO EDGE. An inset box-shadow paints inside the padding box, so a 1px border leaves a
+       strip where the light and the shade stop short. The inset shadows live on ::after, over
+       the whole border box and on the same radius. The clear 1px border stays as a spacer, so
+       every size, including a hand-sized .btn px-3 py-1, keeps its box and a selected tab is as
+       tall as the neutral tabs beside it. Neutral paints its hairline there too. An outline
+       button keeps its real border.
+
+       data-lit-state forces a state, for the specimens on the style guide. */
+    html[data-surface-style="glass"] {
+      --lit-top: inset 0 1px 0 rgb(255 255 255 / 0.35);
+      --lit-bottom: inset 0 -2px 0 rgb(0 0 0 / 0.2);
+      --lit-contact: 0 1px 2px rgb(0 0 0 / 0.4);
+      --lit-glow: 0 8px 24px -6px;
+      --lit-glow-alpha: 0.6;
+      --lit-soft-top: inset 0 1px 0 rgb(255 255 255 / 0.8);
+      --lit-soft-bottom: inset 0 -1px 0 rgb(29 24 50 / 0.08);
+      --lit-pressed: inset 0 2px 4px rgb(0 0 0 / 0.27);
+      --lit-soft-pressed: inset 0 2px 3px rgb(29 24 50 / 0.16);
+      --lit-badge: inset 0 1px 0 rgb(255 255 255 / 0.5), 0 1px 1px rgb(29 24 50 / 0.12);
+      --lit-input: inset 0 1px 2px rgb(29 24 50 / 0.14), inset 0 -1px 0 rgb(255 255 255 / 0.6);
+    }
+    html.dark[data-surface-style="glass"] {
+      --lit-bottom: inset 0 -2px 0 rgb(0 0 0 / 0.3);
+      --lit-contact: 0 1px 2px rgb(0 0 0 / 0.65);
+      --lit-glow: 0 12px 28px -10px;
+      --lit-glow-alpha: 0.8;
+      --lit-soft-top: inset 0 1px 0 rgb(255 255 255 / 0.12);
+      --lit-soft-bottom: inset 0 -1px 0 rgb(0 0 0 / 0.25);
+      --lit-soft-pressed: inset 0 2px 3px rgb(0 0 0 / 0.4);
+      --lit-badge: inset 0 1px 0 rgb(255 255 255 / 0.14), 0 1px 1px rgb(0 0 0 / 0.35);
+      --lit-input: inset 0 1px 2px rgb(0 0 0 / 0.4), inset 0 -1px 0 rgb(255 255 255 / 0.06);
+    }
+    /* Stops: the app's primary is often too light for white, so it steps down its own lightness;
+       the semantic fills already hold 4.5:1, so the midpoint stays on the fill. */
+    html[data-surface-style="glass"] .btn-primary {
+      --lit-top-stop: oklch(from var(--color-cta) calc(l - 0.03) calc(c + 0.03) h / var(--lit-fill-alpha, 1));
+      --lit-low-stop: oklch(from var(--color-cta) calc(l - 0.18) calc(c + 0.05) h / var(--lit-fill-alpha, 1));
+    }
+    html[data-surface-style="glass"] :is(.btn-secondary, .btn-danger, .btn-warning, .btn-success) {
+      --lit-top-stop: oklch(from var(--lit-fill) calc(l + 0.075) calc(c + 0.03) h / var(--lit-fill-alpha, 1));
+      --lit-low-stop: oklch(from var(--lit-fill) calc(l - 0.075) calc(c + 0.03) h / var(--lit-fill-alpha, 1));
+    }
+    html[data-surface-style="glass"] .btn-secondary { --lit-fill: var(--btn-secondary-bg, var(--color-success)); }
+    html[data-surface-style="glass"] .btn-danger { --lit-fill: var(--color-danger-fill, var(--color-danger)); }
+    html[data-surface-style="glass"] .btn-warning { --lit-fill: var(--color-warning-fill, var(--color-warning)); }
+    html[data-surface-style="glass"] .btn-success { --lit-fill: var(--color-success); }
+    /* The spacer holds in every state, so a submit that disables its button moves nothing. */
+    html[data-surface-style="glass"] :is(.btn-primary, .btn-secondary, .btn-danger, .btn-warning, .btn-success):not([class*=" bg-"], [class^="bg-"]) { border: 1px solid transparent; }
+    html[data-surface-style="glass"] :is(.btn-primary, .btn-secondary, .btn-danger, .btn-warning, .btn-success):not(:disabled, [aria-disabled="true"], [class*=" bg-"], [class^="bg-"]) {
+      background-origin: border-box;
+      background-repeat: no-repeat;
+      background-image: linear-gradient(var(--lit-top-stop), var(--lit-low-stop));
+      --lit-inset: var(--lit-top), var(--lit-bottom);
+      --lit-inset-pressed: var(--lit-pressed);
+      box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--lit-contact);
+    }
+    html[data-surface-style="glass"] :is(.btn-primary, .btn-secondary, .btn-danger, .btn-warning, .btn-success):not(.btn-sm, :disabled, [aria-disabled="true"]) {
+      box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--lit-contact),
+        var(--lit-glow) oklch(from var(--lit-glow-stop, var(--lit-low-stop)) l c h / var(--lit-glow-alpha));
+    }
+    /* On a dark page a deep green, red or orange glow disappears, so these glow from the top
+       stop. The violet is already bright enough at its low stop. */
+    html.dark[data-surface-style="glass"] :is(.btn-secondary, .btn-danger, .btn-warning, .btn-success) { --lit-glow-stop: var(--lit-top-stop); }
+    /* A TOUCH OF TRANSPARENCY on a full-size filled button, dark theme only: a photo behind it
+       shows subtly, and white text holds 4.5:1 at the midpoint. An outer shadow is not painted
+       under its own box, so the glow never brightens the fill. On a light page the backdrop would
+       lift the fill and cost contrast, so it stays solid there. Without a blur, or without relative
+       oklch (the gradient would drop out and leave white text on nothing), it stays solid. */
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) and (color: oklch(from red l c h)) {
+      html.dark[data-surface-style="glass"] :is(.btn-primary, .btn-secondary, .btn-danger, .btn-warning, .btn-success):not(.btn-sm, :disabled, [aria-disabled="true"], [class*=" bg-"], [class^="bg-"]) {
+        --lit-fill-alpha: 0.94;
+        background-color: transparent;
+        -webkit-backdrop-filter: blur(6px);
+        backdrop-filter: blur(6px);
       }
     }
+    html[data-surface-style="glass"] .btn-primary:not(:disabled, [aria-disabled="true"]):is(:hover, [data-lit-state="hover"]) {
+      filter: brightness(0.94);
+    }
+    html[data-surface-style="glass"] :is(.btn-neutral, .btn-google):not(:disabled, [aria-disabled="true"], [class*=" border-"]) {
+      border-color: transparent;
+    }
+    html[data-surface-style="glass"] :is(.btn-neutral, .btn-google):not(:disabled, [aria-disabled="true"]) {
+      --lit-inset: inset 0 0 0 1px var(--surface-glass-line), var(--lit-soft-top), var(--lit-soft-bottom);
+      --lit-inset-pressed: inset 0 0 0 1px var(--surface-glass-line), var(--lit-soft-pressed);
+      box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--lit-contact);
+    }
+    html[data-surface-style="glass"] .btn-outline:not(:disabled, [aria-disabled="true"]) {
+      box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--lit-soft-top), var(--lit-soft-bottom), var(--lit-contact);
+    }
+    html[data-surface-style="glass"] .btn-outline:not(:disabled, [aria-disabled="true"]):is(:active, [data-lit-state="pressed"]) {
+      box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--lit-soft-pressed);
+    }
+    html[data-surface-style="glass"] :is(.btn-primary, .btn-secondary, .btn-danger, .btn-warning, .btn-success, .btn-neutral, .btn-google):not(:disabled, [aria-disabled="true"], .absolute, .fixed, .sticky) { position: relative; }
+    html[data-surface-style="glass"] :is(.btn-primary, .btn-secondary, .btn-danger, .btn-warning, .btn-success, .btn-neutral, .btn-google):not(:disabled, [aria-disabled="true"])::after {
+      content: "";
+      position: absolute;
+      inset: -1px;
+      border-radius: inherit;
+      pointer-events: none;
+      box-shadow: var(--lit-inset);
+    }
+    html[data-surface-style="glass"] :is(.btn-primary, .btn-secondary, .btn-danger, .btn-warning, .btn-success, .btn-neutral, .btn-google):not(:disabled, [aria-disabled="true"]):is(:active, [data-lit-state="pressed"]) {
+      box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000);
+    }
+    html[data-surface-style="glass"] :is(.btn-primary, .btn-secondary, .btn-danger, .btn-warning, .btn-success, .btn-neutral, .btn-google):not(:disabled, [aria-disabled="true"]):is(:active, [data-lit-state="pressed"])::after {
+      box-shadow: var(--lit-inset-pressed);
+    }
+    @media (prefers-reduced-motion: no-preference) {
+      html[data-surface-style="glass"] .btn:not(.btn-sm, :disabled, [aria-disabled="true"]):is(:active, [data-lit-state="pressed"]) { translate: 0 1px; }
+    }
+    html[data-surface-style="glass"] .btn[data-lit-state="focus"] {
+      outline: 2px solid color-mix(in srgb, var(--color-cta) 70%, transparent);
+      outline-offset: 2px;
+    }
+    html[data-surface-style="glass"] .badge { box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--lit-badge); }
+    html[data-surface-style="glass"] .input-field { box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--lit-input); }
+
+    /* LESS TRANSPARENCY: every surface above goes solid and drops its blur. Last, to win on order;
+       both spellings of the root, since html.dark outranks a bare html[...] on specificity. */
+    @media (prefers-reduced-transparency: reduce) {
+      html[data-surface-style="glass"], html.dark[data-surface-style="glass"] { --surface-glass-fill: var(--color-surface); --surface-glass-fill-hover: var(--color-surface-alt); }
+      html[data-surface-style="glass"] :is(.surface-glass-blur, .nav-shell, .page-header:is([data-stuck], [data-studio-controller-failed~="page-header"] + .page-header)),
+      html.dark[data-surface-style="glass"] :is(.btn-primary, .btn-secondary, .btn-danger, .btn-warning, .btn-success):not(.btn-sm, :disabled, [aria-disabled="true"]) { --lit-fill-alpha: 1; -webkit-backdrop-filter: none; backdrop-filter: none; }
+      html[data-surface-style="glass"] :is(.nav-shell, .page-header:is([data-stuck], [data-studio-controller-failed~="page-header"] + .page-header)) { background-color: var(--color-page); }
+    }
 
     /* THE SIDEBAR ROW'S DESCRIPTION (components/_link_sidebar, _geo_signpost). At rest
        a row with a description is one line, the height of any other row. On hover or
@@ -1157,23 +1639,23 @@ html[data-page-transition="unfold-top"]::view-transition-new(root) { animation-n
     [data-sidebar-row-label] { transition: transform 140ms ease-in; }
     [data-sidebar-row-described]:focus-visible [data-sidebar-row-label],
     [data-sidebar-row-described][aria-disabled="true"]:focus [data-sidebar-row-label] {
-      transform: translateY(-0.5rem);
+      transform: translateY(calc(-1 * var(--sidebar-row-lift, 0.5rem)));
       transition: transform 200ms ease-out 150ms;
     }
     [data-sidebar-row-described]:focus-visible [data-sidebar-row-desc],
     [data-sidebar-row-described][aria-disabled="true"]:focus [data-sidebar-row-desc] {
       opacity: 1;
-      transform: translateY(-0.5rem);
+      transform: translateY(calc(-1 * var(--sidebar-row-lift, 0.5rem)));
       transition: opacity 200ms ease-out 150ms, transform 200ms ease-out 150ms;
     }
     @media (hover: hover) {
       [data-sidebar-row-described]:hover [data-sidebar-row-label] {
-        transform: translateY(-0.5rem);
+        transform: translateY(calc(-1 * var(--sidebar-row-lift, 0.5rem)));
         transition: transform 200ms ease-out 150ms;
       }
       [data-sidebar-row-described]:hover [data-sidebar-row-desc] {
         opacity: 1;
-        transform: translateY(-0.5rem);
+        transform: translateY(calc(-1 * var(--sidebar-row-lift, 0.5rem)));
         transition: opacity 200ms ease-out 150ms, transform 200ms ease-out 150ms;
       }
     }
@@ -1186,7 +1668,7 @@ html[data-page-transition="unfold-top"]::view-transition-new(root) { animation-n
       [data-sidebar-row-described]:hover [data-sidebar-row-desc],
       [data-sidebar-row-described]:focus-visible [data-sidebar-row-desc],
       [data-sidebar-row-described][aria-disabled="true"]:focus [data-sidebar-row-desc] {
-        transform: translateY(-0.5rem);
+        transform: translateY(calc(-1 * var(--sidebar-row-lift, 0.5rem)));
         transition: opacity 200ms ease-out 150ms;
       }
     }