@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/dist/styles/foundation.css

@@ -5,25 +5,24 @@
   --kui-font-sans: var(
     --wa-font-family-body,
     ui-sans-serif,
-    -apple-system,
-    BlinkMacSystemFont,
-    "Segoe UI",
+    system-ui,
     sans-serif
   );
-  --kui-font-mono: var(
-    --wa-font-family-code,
-    ui-monospace,
-    SFMono-Regular,
-    Menlo,
-    monospace
-  );
+  /* Kerf owns the code stack rather than deferring to Web Awesome's
+     `ui-monospace, monospace`: Chromium does not recognize `ui-monospace`, and
+     the generic `monospace` ends any stack, so named fallbacks after it would
+     never apply. Kerf's Web Awesome theme points `--wa-font-family-code` here. */
+  --kui-font-mono:
+    ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono",
+    monospace;
   --kui-font-2xs: var(--wa-font-size-2xs, 11px);
   --kui-font-xs: var(--wa-font-size-xs, 12px);
   --kui-font-s: var(--wa-font-size-s, 14px);
   --kui-font-m: var(--wa-font-size-m, 16px);
   --kui-font-l: var(--wa-font-size-l, 20px);
+  --kui-font-xl: var(--wa-font-size-xl, 25px);
   --kui-font-2xl: var(--wa-font-size-2xl, 32px);
-  --kui-font-weight-semibold: var(--wa-font-weight-semibold, 650);
+  --kui-font-weight-semibold: var(--wa-font-weight-semibold, 500);
   /* Official spacing scale (see docs/layout.md "Spacing scale"). Five canonical
      steps, each expressing one relationship — pick by how connected the elements
      are, not by eye:
@@ -58,30 +57,169 @@
   --kui-layout-content-gap: var(--kui-space-l);
   --kui-layout-control-gap: var(--kui-space-xs);
   --kui-layout-metadata-gap: var(--kui-space-2xs);
+  --kui-layout-highlight-inset: 2px;
   --kui-layout-rounded-radius: calc(1px + 0.6875rem);
   --kui-layout-pill-radius: calc(1px + 1.3125rem);
   --kui-toolbar-group-inner-size: 2.625rem;
   --kui-toolbar-group-size: calc(2px + var(--kui-toolbar-group-inner-size));
   --kui-toolbar-gap: var(--kui-layout-item-gap);
+  /* Device safe-area insets, in logical terms. Panes and layouts read these
+     through the inherited `--kui-edge-inset-*` edge context: surfaces paint
+     through the unsafe area while their content gains compensating padding on
+     the edges it still touches (docs/app-layouts.md "Safe areas"). Override
+     them to simulate a device or to reserve space for app-owned chrome. */
+  --kui-safe-area-block-start: env(safe-area-inset-top, 0px);
+  --kui-safe-area-block-end: env(safe-area-inset-bottom, 0px);
+  --kui-safe-area-inline-start: env(safe-area-inset-left, 0px);
+  --kui-safe-area-inline-end: env(safe-area-inset-right, 0px);
   --kui-radius-s: var(--wa-border-radius-s, 0.1875rem);
   --kui-radius-m: var(--wa-border-radius-m, 0.375rem);
   --kui-radius-l: var(--wa-border-radius-l, 0.75rem);
   --kui-radius-circle: var(--wa-border-radius-circle, 50%);
   --kui-radius-pill: var(--wa-border-radius-pill, 999px);
   --kui-disclosure-icon-scale: 0.5;
+  /* Private popup-choice contract. A Select's listbox and a PopupMenu's menu
+     both read these, so a value list and a command menu draw one surface
+     inset, one row geometry (Web Awesome's option metrics plus Kerf's label
+     rhythm), one reserved check column, one current-row fill, one group-title
+     style, and one disclosure-caret motion. The em values resolve against the
+     row that reads them. */
+  --_kui-popup-inset: 0.25rem;
+  --_kui-popup-row-gap: 0.125rem;
+  --_kui-popup-row-padding-block: 0.5em;
+  --_kui-popup-row-padding-inline-start: 0.25em;
+  --_kui-popup-row-padding-inline-end: 1em;
+  --_kui-popup-row-check-width: calc(
+    2 * var(--wa-font-size-smaller, round(calc(1em / 1.125), 1px))
+  );
+  --_kui-popup-row-icon-size: 1rem;
+  --_kui-popup-row-icon-gap: 0.5rem;
+  --_kui-popup-row-label-padding-block: 0.35rem;
+  --_kui-popup-row-label-line-height: 1.25;
+  --_kui-popup-group-title-padding: 0.2rem 0.75rem 0.3rem;
+  --_kui-popup-group-title-font-weight: 750;
+  --_kui-popup-caret-open-rotation: -180deg;
+  /* The theme's brand text color as the root resolves it. A scoped tint
+     clamps its lightness for links and brand text (below); it lives outside
+     the palette block, so a tint inherits the root's brand rather than
+     re-deriving from itself. */
+  --_kui-tint-brand-source: var(--kui-color-brand-on-quiet);
+  --_kui-popup-caret-transition: rotate var(--wa-transition-slow, 0.3s)
+    var(--wa-transition-easing, ease);
+}
+
+/* The palette. A scoped tint ([data-kui-tint], below) re-declares this whole
+   block on its element: an unregistered custom property substitutes its var()
+   references where it is declared, so a derived token (the chrome material, a
+   quiet fill mixed into the surface, a popup's current row) resolved at the
+   root would keep the root's colors inside the tint. Only color tokens live
+   here, so a tint never resets an app's spacing or geometry override. */
+:root,
+[data-kui-tint] {
+  --_kui-popup-row-current-background: var(--kui-color-brand-fill-normal);
+  /* Current row text sits on the brand fill; the darker on-fill accent clears
+     WCAG AA there (brand-on-quiet is 4.26:1 over that fill). */
+  --_kui-popup-row-current-color: var(--kui-color-brand-on-fill);
+  /* A capped, scrolling popup shows that it scrolls: a soft shadow along an
+     edge while more choices lie beyond it. Covers painted in the surface
+     color scroll with the content (`local`) and hide each shadow (`scroll`,
+     fixed to the box) only while the list rests at that edge, so a popup
+     whose choices all fit, or one scrolled to its end, draws no cue there.
+     CSS alone, so it works in every engine with no listeners, and it leaves
+     the popup's own border, radius, and drop shadow untouched. */
+  --_kui-popup-scroll-cue-color: light-dark(rgb(0 0 0 / 0.2), rgb(0 0 0 / 0.9));
+  --_kui-popup-scroll-cue:
+    linear-gradient(var(--kui-color-surface-raised) 30%, transparent) center
+      top / 100% 1.5rem no-repeat local,
+    linear-gradient(transparent, var(--kui-color-surface-raised) 70%) center
+      bottom / 100% 1.5rem no-repeat local,
+    radial-gradient(
+        farthest-side at 50% 0,
+        var(--_kui-popup-scroll-cue-color),
+        transparent
+      )
+      center top / 100% 0.75rem no-repeat scroll,
+    radial-gradient(
+        farthest-side at 50% 100%,
+        var(--_kui-popup-scroll-cue-color),
+        transparent
+      )
+      center bottom / 100% 0.75rem no-repeat scroll,
+    var(--kui-color-surface-raised);
   /* macOS Tahoe light semantics used by Hot Sheet 2, with a compatible dark extension. */
+  /* Every --kui-color-* token (and the focus-ring color) that reads a --wa-*
+     token falls back to the value src/webawesome.css assigns to that token,
+     including its light-dark() pair, so a page without the Web Awesome theme
+     resolves the same palette in both color schemes. A single light color
+     here would render, e.g., dark red danger text on a dark surface, and a
+     fallback that points at a different token (surface-raised at the surface,
+     text-link at the brand fill) silently diverges from the theme.
+     tests/browser/tone-contrast.spec.ts pins the parity for every token. */
   --kui-color-surface: var(
     --wa-color-surface-default,
     light-dark(#fff, #1c1c1e)
   );
   --kui-color-surface-raised: var(
     --wa-color-surface-raised,
-    var(--kui-color-surface)
+    light-dark(#fff, #2c2c2e)
   );
   --kui-color-surface-lowered: var(
     --wa-color-surface-lowered,
-    light-dark(#f2f2f7, #111113)
+    light-dark(
+      rgb(0 0 98.076923 / 0.05098),
+      rgb(228.157895 228.157895 255 / 0.07451)
+    )
   );
+  /* The sunken surface: a fine monochrome grain over the lowered color. The
+     tile is generated once per page by the first sunken surface that renders
+     (ensureSunkenTexture); set --kui-sunken-texture to none at :root for a
+     flat lowered surface, or to another image. */
+  --kui-sunken-texture: var(--_kui-sunken-texture-generated, none);
+  --kui-sunken-surface:
+    var(--kui-sunken-texture) 0 0 / 100px 100px repeat,
+    var(--kui-color-surface-lowered);
+  /* The surface context: what a region paints behind its children, for a
+     control that must match it (an inset focus ring's inner line). Left
+     undeclared here, so a reader falls back to the base surface:
+       --kui-color-surface-current: the opaque surface beneath (default
+         --kui-color-surface); an opaque surface (a raised dialog or popup, a
+         base or raised List) sets it and clears the tint.
+       --kui-color-surface-current-region: a layout region's fill over it
+         (a sunken Pane, Workbench area, or TabNavigator scene; a Pane's or
+         TabNavigator's app `background`; default transparent).
+       --kui-color-surface-current-tint: a content surface's fill over that
+         (a SunkenPanel, a sunken Disclosure, a lowered FramedList or its
+         highlighted row, a quiet ContentItem, a TabBar strip, and glass
+         chrome at rest: a Pane overlay header, NavStack overlay chrome, a
+         TabNavigator overlay bar, a dialog's floating header; default
+         transparent).
+     A reader layers the tint over the region over the color, so a content
+     surface inside a sunken region (the common nesting) composes exactly;
+     custom properties cannot fold an inherited value into a new one, so a
+     third translucent level keeps only the innermost content tint. A surface sets both on its own
+     painted element, never on a child; a scoped tint resets them below. */
+  /* Translucent chrome material: a bar laid over scrolling content (a Pane's
+     overlay header) lets the content show through, blurred, beneath it.
+     80% of the surface keeps --kui-color-text at AA over any content
+     (about 10:1 light and 8:1 dark against a black or white backdrop). It
+     resolves to the opaque surface under prefers-reduced-transparency or
+     prefers-contrast: more, and where backdrop-filter is unsupported
+     (below). */
+  --kui-chrome-material: color-mix(
+    in srgb,
+    var(--kui-color-surface) 80%,
+    transparent
+  );
+  /* The same material over a raised surface (a dialog panel's floating
+     header): 80% of surface-raised keeps --kui-color-text at AA over any
+     content (about 10:1 light and 6.7:1 dark against a black or white
+     backdrop), with the same opaque fallbacks. */
+  --kui-chrome-material-raised: color-mix(
+    in srgb,
+    var(--kui-color-surface-raised) 80%,
+    transparent
+  );
+  --kui-chrome-material-filter: blur(20px) saturate(180%);
   --kui-color-text: var(--wa-color-text-normal, light-dark(#1d1d1f, #f5f5f7));
   --kui-color-text-quiet: var(
     --wa-color-text-quiet,
@@ -89,7 +227,7 @@
   );
   --kui-color-text-link: var(
     --wa-color-text-link,
-    var(--kui-color-brand-fill-loud)
+    var(--kui-color-brand-on-quiet)
   );
 
   --kui-color-neutral-fill-quiet: var(
@@ -98,7 +236,7 @@
   );
   --kui-color-neutral-fill-normal: var(
     --wa-color-neutral-fill-normal,
-    light-dark(#e5e5ea, #3a3a3c)
+    light-dark(rgb(0 0 49.038462 / 0.101961), rgb(253 253 255 / 0.133333))
   );
   --kui-color-neutral-fill-loud: var(
     --wa-color-neutral-fill-loud,
@@ -106,19 +244,19 @@
   );
   --kui-color-neutral-border-quiet: var(
     --wa-color-neutral-border-quiet,
-    var(--kui-color-neutral-fill-normal)
+    light-dark(rgb(0 0 49.038462 / 0.101961), rgb(253 253 255 / 0.124444))
   );
   --kui-color-neutral-border-normal: var(
     --wa-color-neutral-border-normal,
-    light-dark(#d1d1d6, #48484a)
+    light-dark(rgb(0 0 27.717391 / 0.180392), rgb(253 253 255 / 0.195556))
   );
   --kui-color-neutral-border-loud: var(
     --wa-color-neutral-border-loud,
-    light-dark(#aeaeb2, #636366)
+    light-dark(rgb(0 0 12.592593 / 0.317647), rgb(249.875 249.875 255 / 0.32))
   );
   --kui-color-neutral-on-quiet: var(
     --wa-color-neutral-on-quiet,
-    var(--kui-color-text-quiet)
+    light-dark(#626267, #c2c2c6)
   );
   --kui-color-neutral-on-normal: var(
     --wa-color-neutral-on-normal,
@@ -129,9 +267,11 @@
     var(--kui-color-surface)
   );
 
+  /* Each brand token below falls back to its tuned literal unless the app
+     sets the opt-in --kui-color-brand (see the brand ramp after this block). */
   --kui-color-brand-fill-loud: var(
     --wa-color-brand-fill-loud,
-    light-dark(#0088ff, #64d2ff)
+    var(--_kui-brand-fill-loud, light-dark(#0075db, #64d2ff))
   );
   --kui-color-brand-fill-quiet: var(
     --wa-color-brand-fill-quiet,
@@ -169,15 +309,63 @@
     --wa-color-brand-border-loud,
     var(--kui-color-brand-fill-loud)
   );
+  /* The light brand/success/warning on-quiet values are Kerf-owned (mirrored
+     in src/webawesome.css): each is the Hot Sheet 2 hue darkened just enough to
+     clear WCAG AA (>=4.5:1) on the lowered page background (#f2f2f7), not only
+     on the white surface. The prior #1e6ef4 / #008932 / #a16a00 reached ~4.1:1
+     there. Brand #0c62f3 is 4.64:1, success #007f2e 4.62:1, warning #966200
+     4.65:1 on the page (5.2:1 on white). */
   --kui-color-brand-on-quiet: var(
     --wa-color-brand-on-quiet,
-    light-dark(#1e6ef4, #8acbff)
+    var(--_kui-brand-on-quiet, light-dark(#0c62f3, #8acbff))
   );
   --kui-color-brand-on-normal: var(
     --wa-color-brand-on-normal,
     var(--kui-color-brand-on-quiet)
   );
-  --kui-color-brand-on-loud: var(--wa-color-brand-on-loud, #fff);
+  --kui-color-brand-on-loud: var(
+    --wa-color-brand-on-loud,
+    light-dark(#fff, #111113)
+  );
+  /* Brand accent text placed directly ON a brand fill (quiet or normal), such as
+     the info StateBanner and Select's current option. Darker than brand-on-quiet
+     so it clears WCAG AA (>=4.5:1): brand-on-quiet (#0c62f3) resolves to only
+     4.26:1 over brand-fill-normal (#d6ecff), while #1a5dcf (same hue) clears
+     ~4.9:1 there and ~5.5:1 over brand-fill-quiet (#ebf6ff). The dark value
+     matches brand-on-quiet, which already passes over the dark fills. */
+  --kui-color-brand-on-fill: var(
+    --_kui-brand-on-fill,
+    light-dark(#1a5dcf, #8acbff)
+  );
+
+  /* Pop is attractive emphasis without status meaning: use it for featured,
+     novel, or celebratory content, never as a success/danger substitute. */
+  --kui-color-pop-fill-loud: light-dark(#af34d4, #da8fff);
+  --kui-color-pop-fill-quiet: color-mix(
+    in srgb,
+    var(--kui-color-pop-fill-loud) 10%,
+    var(--kui-color-surface)
+  );
+  --kui-color-pop-fill-normal: color-mix(
+    in srgb,
+    var(--kui-color-pop-fill-loud) 18%,
+    var(--kui-color-surface)
+  );
+  --kui-color-pop-border-quiet: color-mix(
+    in srgb,
+    var(--kui-color-pop-fill-loud) 36%,
+    var(--kui-color-surface)
+  );
+  --kui-color-pop-border-normal: color-mix(
+    in srgb,
+    var(--kui-color-pop-fill-loud) 58%,
+    var(--kui-color-surface)
+  );
+  --kui-color-pop-border-loud: var(--kui-color-pop-fill-loud);
+  --kui-color-pop-on-quiet: light-dark(#792498, #e8a5ff);
+  --kui-color-pop-on-normal: var(--kui-color-pop-on-quiet);
+  --kui-color-pop-on-loud: light-dark(#fff, #241126);
+  --kui-color-pop-on-fill: var(--kui-color-pop-on-quiet);
 
   --kui-color-success-fill-loud: var(--wa-color-success-fill-loud, #34c759);
   --kui-color-success-fill-quiet: var(
@@ -220,9 +408,20 @@
       var(--kui-color-neutral-on-normal)
     )
   );
-  --kui-color-success-on-quiet: var(--wa-color-success-on-quiet, #008932);
-  --kui-color-success-on-normal: var(--wa-color-success-on-normal, #006d28);
-  --kui-color-success-on-loud: var(--wa-color-success-on-loud, #fff);
+  --kui-color-success-on-quiet: var(
+    --wa-color-success-on-quiet,
+    light-dark(#007f2e, #63e685)
+  );
+  --kui-color-success-on-normal: var(
+    --wa-color-success-on-normal,
+    light-dark(#006d28, #8cea9f)
+  );
+  --kui-color-success-on-loud: var(--wa-color-success-on-loud, #1d1d1f);
+  /* Success text placed ON a success fill (e.g. the success StateBanner). Darker
+     than success-on-quiet for margin over success-fill-quiet (#e3f7e8): the
+     original on-quiet #008932 reached only 4.05:1 there and today's #007f2e sits
+     at 4.60:1, while #00792c clears ~5:1. Dark matches success-on-quiet. */
+  --kui-color-success-on-fill: light-dark(#00792c, #63e685);
 
   --kui-color-warning-fill-loud: var(--wa-color-warning-fill-loud, #ffcc00);
   --kui-color-warning-fill-quiet: var(
@@ -265,11 +464,25 @@
       var(--kui-color-neutral-on-normal)
     )
   );
-  --kui-color-warning-on-quiet: var(--wa-color-warning-on-quiet, #a16a00);
-  --kui-color-warning-on-normal: var(--wa-color-warning-on-normal, #5f3f00);
+  --kui-color-warning-on-quiet: var(
+    --wa-color-warning-on-quiet,
+    light-dark(#966200, #ffd84a)
+  );
+  --kui-color-warning-on-normal: var(
+    --wa-color-warning-on-normal,
+    light-dark(#5f3f00, #ffe27a)
+  );
   --kui-color-warning-on-loud: var(--wa-color-warning-on-loud, #1d1d1f);
+  /* Warning text placed ON a warning fill (e.g. the warning StateBanner). Darker
+     than warning-on-quiet for margin over warning-fill-quiet (#fffae8): the
+     original on-quiet #a16a00 reached only 4.39:1 there (today's #966200 is
+     4.97:1), while #8f5e00 clears ~5.3:1. Dark matches warning-on-quiet. */
+  --kui-color-warning-on-fill: light-dark(#8f5e00, #ffd84a);
 
-  --kui-color-danger-fill-loud: var(--wa-color-danger-fill-loud, #ff383c);
+  --kui-color-danger-fill-loud: var(
+    --wa-color-danger-fill-loud,
+    light-dark(#eb0005, #ff383c)
+  );
   --kui-color-danger-fill-quiet: var(
     --wa-color-danger-fill-quiet,
     color-mix(
@@ -310,38 +523,265 @@
       var(--kui-color-neutral-on-normal)
     )
   );
-  --kui-color-danger-on-quiet: var(--wa-color-danger-on-quiet, #c20b20);
-  --kui-color-danger-on-normal: var(--wa-color-danger-on-normal, #8e0717);
-  --kui-color-danger-on-loud: var(--wa-color-danger-on-loud, #fff);
+  --kui-color-danger-on-quiet: var(
+    --wa-color-danger-on-quiet,
+    light-dark(#c20b20, #ff696c)
+  );
+  --kui-color-danger-on-normal: var(
+    --wa-color-danger-on-normal,
+    light-dark(#8e0717, #ff8a8c)
+  );
+  --kui-color-danger-on-loud: var(
+    --wa-color-danger-on-loud,
+    light-dark(#fff, #111113)
+  );
+  /* Danger text placed ON a danger fill (e.g. the danger StateBanner) and the
+     danger Badge's solid fill. The light value matches danger-on-quiet, which
+     already clears WCAG AA (5.7:1) over danger-fill-quiet. The dark value is
+     lighter than danger-on-quiet (#ff696c), which reached only 5.7:1 over the
+     dark fill-quiet (4.0:1 as dimmed banner detail) and left the solid badge's
+     dark text and placeholder skeleton the weakest of any tone on a mid-red
+     fill; #ffa0a2 matches the other tones' pale dark on-fill values. */
+  --kui-color-danger-on-fill: light-dark(#c20b20, #ffa0a2);
 
-  /* Compatibility aliases retained for existing @kerfjs/ui consumers. */
-  --kui-color-border: var(
-    --wa-color-surface-border,
-    var(--kui-color-neutral-border-normal)
-  );
-  --kui-color-border-quiet: var(--kui-color-neutral-border-quiet);
-  --kui-color-accent: var(--kui-color-brand-fill-normal);
-  --kui-color-accent-text: var(--kui-color-brand-on-quiet);
-  --kui-color-success: var(--kui-color-success-fill-quiet);
-  --kui-color-success-text: var(--kui-color-success-on-quiet);
-  --kui-color-warning: var(--kui-color-warning-fill-quiet);
-  --kui-color-warning-text: var(--kui-color-warning-on-quiet);
-  --kui-color-danger: var(--kui-color-danger-fill-quiet);
-  --kui-color-danger-text: var(--kui-color-danger-on-quiet);
   --kui-focus-ring: var(
     --wa-focus-ring,
-    3px solid var(--wa-color-focus, var(--kui-color-brand-fill-loud))
+    3px solid
+      var(
+        --wa-color-focus,
+        var(--_kui-brand-focus, light-dark(#007aff, #64d2ff))
+      )
+  );
+  /* Elevation mirrors webawesome.css's scheme-aware shadows: dark raises the
+     alpha so a raised surface still separates from a near-black page. */
+  --kui-shadow-s: var(
+    --wa-shadow-s,
+    0 1px 3px light-dark(rgb(0 0 0 / 0.14), rgb(0 0 0 / 0.5))
+  );
+  --kui-shadow-m: var(
+    --wa-shadow-m,
+    0 0.35rem 1rem light-dark(rgb(0 0 0 / 0.11), rgb(0 0 0 / 0.4))
   );
-  --kui-shadow-s: var(--wa-shadow-s, 0 1px 3px rgb(0 0 0 / 0.14));
   --kui-shadow-l: var(
     --wa-shadow-l,
-    0 0.75rem 2rem rgb(0 0 0 / 0.09)
+    0 0.75rem 2rem light-dark(rgb(0 0 0 / 0.09), rgb(0 0 0 / 0.32))
   );
 }
 
-@media (prefers-contrast: more) {
+:root:dir(rtl) {
+  --kui-safe-area-inline-start: env(safe-area-inset-right, 0px);
+  --kui-safe-area-inline-end: env(safe-area-inset-left, 0px);
+}
+
+/* Scoped tint. A Pane, NavStack, or TabNavigator `tint` ({ color, scheme })
+   marks its root `data-kui-tint="<scheme>"` with the color in
+   `--_kui-tint-color`. The app declares the scheme (there is no automatic
+   color detection), and the scope re-derives the base surface and text
+   tokens from the color; the palette block above then re-derives everything
+   built on them (raised and lowered surfaces, quiet fills, the chrome
+   material). Relative color syntax clamps each token's lightness to a band
+   that holds WCAG AA whatever the color: a light tint's surface stays at or
+   above 90% OKLCH lightness under 24% text, 44% quiet text, and brand text
+   at most 45%, and a dark tint's surface at or below 30% under 97% text, 80%
+   quiet text, and brand text at least 80%. Chroma is capped so
+   text stays near-neutral and a surface stays a tint, not a fill.
+   Without relative color syntax, and under `prefers-contrast: more`, the
+   scope keeps the plain palette in its declared scheme. */
+[data-kui-tint="light"] {
+  color-scheme: light;
+}
+
+[data-kui-tint="dark"] {
+  color-scheme: dark;
+}
+
+/* Inside a tint the chrome material keeps its blur but drops the saturation
+   boost: over the scope's own colored surface, saturating it would paint a
+   visibly brighter band (and a lighter edge) under an overlay header at
+   rest, where the header should read as the same surface. */
+[data-kui-tint] {
+  color: var(--kui-color-text);
+  --kui-chrome-material-filter: blur(20px);
+  /* The scope re-derives its surface, so an outer surface context ends here. */
+  --kui-color-surface-current: initial;
+  --kui-color-surface-current-region: initial;
+  --kui-color-surface-current-tint: initial;
+}
+
+/* The opt-in brand, left undeclared so the tuned literals apply:
+     --kui-color-brand: any color an app sets on :root;
+   the whole brand ramp follows it, the way a scoped tint's accent re-derives
+   its ramp: the loud fill (and the quiet/normal fills and borders mixed from
+   it), brand text and links, brand text on brand fills, and the focus ring.
+   Lightness is clamped per scheme so every pair keeps WCAG AA for any hue
+   and chroma (the brand-ramp browser test sweeps them): a light fill stays
+   dark enough for white text and a dark one light enough for near-black
+   text; brand text stays dark enough for the page, the surface, and the
+   brand fills in light, and light enough in dark. Unset, each private
+   derivation references an undefined variable, is invalid, and the tokens
+   above keep their tuned literals exactly. Web Awesome's theme reads the
+   same derivations (webawesome.css). */
+@supports (color: oklch(from red l c h)) {
   :root {
-    --kui-color-border: currentColor;
+    --_kui-brand-fill-loud: light-dark(
+      oklch(from var(--kui-color-brand) min(l, 0.46) c h),
+      oklch(from var(--kui-color-brand) clamp(0.74, l, 0.86) c h)
+    );
+    --_kui-brand-on-quiet: light-dark(
+      oklch(from var(--kui-color-brand) min(l, 0.43) c h),
+      oklch(from var(--kui-color-brand) max(l, 0.86) c h)
+    );
+    --_kui-brand-on-fill: light-dark(
+      oklch(from var(--kui-color-brand) min(l, 0.38) c h),
+      oklch(from var(--kui-color-brand) max(l, 0.9) c h)
+    );
+    --_kui-brand-focus: var(--_kui-brand-fill-loud);
+  }
+}
+
+@supports (color: oklch(from red l c h)) {
+  @media not (prefers-contrast: more) {
+    [data-kui-tint="light"] {
+      --wa-color-surface-default: oklch(
+        from var(--_kui-tint-color) clamp(0.9, l, 0.985) min(c, 0.08) h
+      );
+      --wa-color-surface-raised: oklch(
+        from var(--_kui-tint-color) min(1, calc(clamp(0.9, l, 0.985) + 0.03))
+          min(c, 0.05) h
+      );
+      --wa-color-text-normal: oklch(
+        from var(--_kui-tint-color) 0.24 min(c, 0.03) h
+      );
+      --wa-color-text-quiet: oklch(
+        from var(--_kui-tint-color) 0.44 min(c, 0.04) h
+      );
+      --wa-color-neutral-on-quiet: oklch(
+        from var(--_kui-tint-color) 0.42 min(c, 0.04) h
+      );
+      --wa-color-brand-on-quiet: oklch(
+        from var(--_kui-tint-brand-source) min(l, 0.45) c h
+      );
+    }
+
+    [data-kui-tint="dark"] {
+      --wa-color-surface-default: oklch(
+        from var(--_kui-tint-color) clamp(0.16, l, 0.3) min(c, 0.1) h
+      );
+      --wa-color-surface-raised: oklch(
+        from var(--_kui-tint-color) calc(clamp(0.16, l, 0.3) + 0.06)
+          min(c, 0.08) h
+      );
+      --wa-color-text-normal: oklch(
+        from var(--_kui-tint-color) 0.97 min(c, 0.02) h
+      );
+      --wa-color-text-quiet: oklch(
+        from var(--_kui-tint-color) 0.8 min(c, 0.04) h
+      );
+      --wa-color-neutral-on-quiet: oklch(
+        from var(--_kui-tint-color) 0.82 min(c, 0.04) h
+      );
+      --wa-color-brand-on-quiet: oklch(
+        from var(--_kui-tint-brand-source) max(l, 0.8) c h
+      );
+    }
+
+    /* An optional accent (`tint.accent`) re-derives the brand ramp in the
+       scope: the loud fill (buttons, the current row, checked controls), its
+       on-loud text, brand text and links, text on brand fills, and the focus
+       ring. Lightness is clamped so each pair keeps WCAG AA for any accent:
+       a light scope's fill stays at or below 46% under white text, a dark
+       scope's between 72% and 85% under near-black text, and brand text at
+       most 36% (light) or at least 94% (dark). Dark on-fill text also caps
+       chroma so a vivid red stays light after gamut clipping. */
+    [data-kui-tint="light"][data-kui-tint-accent] {
+      --wa-color-brand-fill-loud: oklch(
+        from var(--_kui-tint-accent) min(l, 0.46) c h
+      );
+      --wa-color-brand-on-loud: #fff;
+      --wa-color-brand-on-quiet: oklch(
+        from var(--_kui-tint-accent) min(l, 0.36) c h
+      );
+      --kui-color-brand-on-fill: oklch(
+        from var(--_kui-tint-accent) min(l, 0.3) c h
+      );
+      --wa-color-focus: oklch(from var(--_kui-tint-accent) min(l, 0.46) c h);
+    }
+
+    [data-kui-tint="dark"][data-kui-tint-accent] {
+      --wa-color-brand-fill-loud: oklch(
+        from var(--_kui-tint-accent) clamp(0.72, l, 0.85) c h
+      );
+      --wa-color-brand-on-loud: #111113;
+      --wa-color-brand-on-quiet: oklch(
+        from var(--_kui-tint-accent) max(l, 0.94) c h
+      );
+      --kui-color-brand-on-fill: oklch(
+        from var(--_kui-tint-accent) max(l, 0.95) min(c, 0.12) h
+      );
+      --wa-color-focus: oklch(
+        from var(--_kui-tint-accent) clamp(0.78, l, 0.85) c h
+      );
+    }
+  }
+}
+
+@supports not (
+  (backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))
+) {
+  :root,
+  [data-kui-tint] {
+    --kui-chrome-material: var(--kui-color-surface);
+    --kui-chrome-material-raised: var(--kui-color-surface-raised);
+    --kui-chrome-material-filter: none;
+  }
+}
+
+@media (prefers-reduced-transparency: reduce), (prefers-contrast: more) {
+  :root,
+  [data-kui-tint] {
+    --kui-chrome-material: var(--kui-color-surface);
+    --kui-chrome-material-raised: var(--kui-color-surface-raised);
+    --kui-chrome-material-filter: none;
+  }
+}
+
+/* The static-effects switch. There is no reliable CSS signal for a low-power
+   or slow device, so an app that detects one itself sets
+   `data-kui-effects="static"` on the root element; a display that cannot
+   animate smoothly (`update: slow`, e-ink and similar) gets the same result
+   on its own. Either way every backdrop effect turns opaque here, and every
+   scroll-driven animation a component owns stops in that component's CSS
+   (tests/unit/static-effects.test.ts holds each one to it). */
+:root[data-kui-effects="static"],
+:root[data-kui-effects="static"] [data-kui-tint] {
+  --kui-chrome-material: var(--kui-color-surface);
+  --kui-chrome-material-raised: var(--kui-color-surface-raised);
+  --kui-chrome-material-filter: none;
+}
+
+@media (update: slow) {
+  :root,
+  [data-kui-tint] {
+    --kui-chrome-material: var(--kui-color-surface);
+    --kui-chrome-material-raised: var(--kui-color-surface-raised);
+    --kui-chrome-material-filter: none;
+  }
+}
+
+@media (prefers-contrast: more) {
+  :root,
+  [data-kui-tint] {
+    --kui-color-pop-fill-quiet: Canvas;
+    --kui-color-pop-fill-normal: Canvas;
+    --kui-color-pop-fill-loud: Highlight;
+    --kui-color-pop-border-quiet: currentColor;
+    --kui-color-pop-border-normal: currentColor;
+    --kui-color-pop-border-loud: currentColor;
+    --kui-color-pop-on-quiet: currentColor;
+    --kui-color-pop-on-normal: currentColor;
+    --kui-color-pop-on-loud: HighlightText;
+    --kui-color-pop-on-fill: currentColor;
+    --kui-color-neutral-border-normal: currentColor;
     --kui-focus-ring: 3px solid currentColor;
   }
 }