@godxjp/ui 28.13.0 → 29.0.0

package/docs/CUSTOMER-THEMING.md

@@ -312,7 +312,9 @@ A `data-*` attribute the package never writes is a selector you can hold a style
 }
 ```
 
-Use `--text-error`, not `--destructive`: the fill tier is tuned for a white label on top of it and measures 2.95:1 as ink on the dark card (gh#610). The whole family is `--prose-link-color` (default `hsl(var(--primary))`, resolved at the anchor so a scoped re-tint reaches it) and `--prose-link-decoration-line` (default `underline`). Set the first on `[data-tenant]` to re-tint every wiki link at once.
+Use `--text-error`, not `--destructive`: the fill tier is tuned for a white label on top of it and measures 2.95:1 as ink on the dark card (gh#610). The whole family is `--prose-link-color` and `--prose-link-decoration-line` (default `underline`). Set the first on `[data-tenant]` to re-tint every wiki link at once.
+
+`--prose-link-color`'s default is now `hsl(var(--text-link, var(--primary)))`, not `hsl(var(--primary))` (gh#887). The brand FILL was being used as INK here, and a fill has no contrast guarantee as ink — measured across five seeds, prose links ran 1.25:1 to 3.64:1 on the surfaces they land on. `--text-link` is the INK role, which `tenantTheme` clamps to 4.5:1, and `--primary` remains the last fallback so a consumer who set neither sees no change. Set `--text-link` once and every brand-as-ink surface follows; set `--prose-link-color` only to make prose links differ from the rest.
 
 There is **no prop** naming the attribute, deliberately: the attribute IS the API, the same way `data-expanded-row` and `data-axe-open` are. A prop would make the package own a name only your renderer knows, and would let exactly one state be marked.
 
@@ -350,6 +352,7 @@ The interaction states are **derived from the `--primary` in scope, at the eleme
 | `--sidebar-item-active-foreground` | **yes** — defaults to the live `--primary-active` | — |
 | `--focus-outline-color` | **yes, through `--ring`** — every keyboard-focus outline (gh#687) | `var(--focus-ring-color, var(--ring))`, read at the focused element — so it follows the `--ring` you set in the scope |
 | Radio button bar selected (`--choice-button-*`), Slider active dot, BackTop progress, `.ui-brand-glow` | **yes** (gh#687) | `var(--primary)` / `var(--primary-foreground)` at the call site |
+| `--text-link`, `--text-brand`, `--text-primary` | **yes, and they are the BRAND AS INK** — Button `variant="link"`, prose and Anchor links, the active sidebar/NavList label, MegaMenu's current trigger, Timeline's current title, tinted Avatar, the checked radio dot, `Text tone="primary"` and 20 more (gh#887) | `tenantTheme` returns all three as literals, each walked away from the surface until it clears 4.5:1. They are NOT a step on the `--primary` ramp: a fill is tuned for a label ON it, and the same colour used as ink on a page surface has no guarantee at all — measured at 1.24:1 on the lightest seed before this. |
 | Topbar item / AppLauncher tile / Segmented / filled-control hover | **follow `--accent`** (gh#687) | `var(--accent)` / `var(--accent-foreground)` at the call site |
 | `--primary-foreground` | **no — set it** | the label on a filled primary; you choose it for your seed |
 | `--ring` | **only on the element that declares `--primary`** — set it in a nested scope | `var(--primary)` on `:root` / `.dark`. `--ring` is a public role read as `hsl(var(--ring))` in consumer CSS, so it cannot become a live default; a scope below `<html>` inherits the root's |
@@ -379,3 +382,636 @@ Two more CSS-inheritance caveats for the **scoped** case (a single `:root` brand
 
 - **Radius & shadow-tint don't cascade from a scoped anchor.** `--radius-{xs…2xl}`, `--card-radius`, `--control-radius` and the `--shadow-{xs…2xl}` ramp are computed at their declaring element, so a scoped `--radius` / `--shadow-color` override won't reach them. For a scoped re-theme, re-declare the derived tokens you need (e.g. `--card-radius: var(--radius)`, or set `--card-shadow` to a literal value).
 ````
+
+---
+
+## A CUSTOMER's colour, at runtime — `tenantTheme()` (gh#861, gh#868)
+
+Everything above is a colour **you** author, in a stylesheet. This section is the other case: a hex
+your customer picked in a settings screen, which reaches the page as data and must paint one region
+of it — an app launcher, a partner portal, a tenant switcher showing two tenants at once.
+
+There is no `<TenantTheme>` component, and `docs/COMPOSITION-VS-COMPONENT.md` §3.2 records why (it
+fails C3, C4 and C6: a `<div>` with a `style`, a screen-shaped API, and no text or role for the
+international contract to apply to). What ships instead is the part two consumer repos each
+hand-rolled — the arithmetic:
+
+```tsx
+import { tenantTheme } from "@godxjp/ui/app";
+
+const brand = tenantTheme(tenant.primary_color); // "#0071bd", 3- or 6-digit
+
+<div data-tenant={tenant.slug} style={brand.vars}>
+  <Topbar … />
+</div>;
+```
+
+`brand.vars` is exactly five declarations, and each one is there for a stated reason:
+
+| declaration            | why                                                                                                                                                                                 |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--primary`            | the seed, as an `H S% L%` triplet — `hexToHsl()` is the same conversion, exported separately                                                                                        |
+| `--primary-foreground` | **does not follow the seed** (see the table above): the label is chosen by contrast, here                                                                                           |
+| `--ring`               | `derived.css` binds `--ring: var(--primary)` at `:root`, where a `var()` substitutes ONCE — a scope below `<html>` inherits the root's ring unless it restates it (the freeze rule) |
+| `--primary-hover`      | a LITERAL, not `initial` — see "no silent half-application" below                                                                                                                   |
+| `--primary-active`     | the same                                                                                                                                                                            |
+
+It never throws and never returns null. An unusable hex yields **empty `vars`**, so the region
+falls back to the app's own theme instead of breaking the page — the same contract `ColorPicker`
+already has.
+
+### The contrast rule, stated
+
+**WCAG 2.2 SC 1.4.3 Contrast (Minimum), normal text, 4.5:1.** Relative luminance is WCAG's own
+definition (`c′ = c ≤ 0.03928 ? c/12.92 : ((c+0.055)/1.055)^2.4`, then
+`L = 0.2126·R′ + 0.7152·G′ + 0.0722·B′`), and the ratio is `(L_lighter + 0.05) / (L_darker + 0.05)`.
+
+The label is whichever of `#ffffff` / `#000000` scores higher, i.e. the pivot at **L = 0.179**. That
+is not "usually fine": at the pivot BOTH candidates measure 4.58:1, and away from it the winner only
+rises — so the chosen label clears AA for **every** sRGB seed, by construction. The claim is swept
+over the whole cube in `src/app/__tests__/tenant-theme.test.ts`; the worst seed in it measures
+4.58:1.
+
+Measured, for the two shapes where a naive rule fails:
+
+| customer hex | label chosen | ratio   | what "always white" would have given |
+| ------------ | ------------ | ------- | ------------------------------------ |
+| `#0071bd`    | `#ffffff`    | 5.13:1  | 5.13:1                               |
+| `#7a00ff`    | `#ffffff`    | 6.42:1  | 6.42:1                               |
+| `#FFD400`    | `#000000`    | 14.67:1 | **1.29:1**                           |
+| `#0A1F44`    | `#ffffff`    | 16.25:1 | 16.25:1                              |
+| `#E30613`    | `#ffffff`    | 4.88:1  | 4.88:1                               |
+| `#00A86B`    | `#000000`    | 6.81:1  | **2.34:1**                           |
+| `#767676`    | `#000000`    | 4.62:1  | 4.54:1                               |
+
+**If you already computed the pair server-side, pass it and it is used as given** — it is not
+silently second-guessed — but the result reports what it actually achieves, and a dev build warns
+under 4.5:1:
+
+```ts
+const brand = tenantTheme(hex, { foreground: tenant.theme_tokens.foreground });
+if (!brand.meetsAA) {
+  // brand.contrast is the number. The API SAYS no rather than quietly returning white.
+}
+```
+
+`contrastRatio(a, b)` and `relativeLuminance(hex)` are exported for the same reason: so the
+arithmetic can be checked rather than trusted.
+
+### No silent half-application
+
+The derived family (`--primary-hover` & co.) resolves at the painting element with CSS relative
+colour. An engine without it (Chrome/Edge 111–118) gets the `:root` literals of the PACKAGE seed
+instead — so a tenant colour set as a bare `--primary` applies at REST and not on HOVER, with no
+error and no warning. That is the shape a consumer repo was guarding by hand with
+`CSS.supports("color", "hsl(from red h s l)")`, and it is worse than not applying at all.
+
+`tenantTheme` therefore computes the two steps in JS, from the same channel formulas, and emits
+them as literal triplets on the same element that carries the seed. **No feature detection, every
+engine, both states.** It is not a return to the gh#648 defect, because that was a literal on
+`:root` — ABOVE every scope that re-seeds. These are written by the same call that writes
+`--primary`, so a nested region that re-seeds re-emits its own pair and nothing freezes.
+`src/app/__tests__/tenant-theme.test.ts` holds the literals EQUAL to the CSS formula, evaluated the
+way the browser would, over a sweep of seeds and both label polarities.
+
+`--primary-border` and `--control-outline` are left to derive: their channels are per-THEME rather
+than per-label, so JS cannot compute them without being told the theme, and they are a hairline and
+an 11%-alpha halo rather than a state a reader tracks.
+
+### The brand as INK, and the surface it has to clear (gh#887)
+
+The pair above is a FILL and the label on it. It says nothing about the brand used as INK on a page
+surface — which a sidebar active item, a NavList item, a MegaMenu trigger, an Anchor link, a
+`Text link` and `Button variant="link"` all are. So a brand could pass the library's own contrast
+computation and still ship a navigation nobody can read: measured on `/showcase/theme-lab?theme=base`,
+`#FFD400` gave **1.18–2.06:1** and `#E2564A` **2.16–3.64:1**, at rest and hovered.
+
+The three ink roles already existed. What they lacked was a FLOOR: each was a plain lightness step
+off the seed (`l - 8.4` for the link, `l - 15.5` for the pressed ink), and a step is not a contrast
+guarantee — `#FFD400` minus 8.4 lightness is `#d4b000`, 2.06:1 on the page. `tenantTheme` now emits
+all three as literals, each walked AWAY from the surface until the painted pixel clears 4.5:1 and no
+further:
+
+```tsx
+tenantTheme("#FFD400").vars["--text-brand"]; // "49.88 100% 24.4%" — 4.56:1, not 1.73:1
+tenantTheme("#7C3AED").vars["--text-brand"]; // "262.12 83.26% 49.44%" — the ramp step, untouched
+```
+
+**A seed whose ramp step already clears is emitted unchanged**, so the package's own violet is
+byte-identical to what it shipped before, and so are the middle seeds. `tenant-theme.test.ts` sweeps
+the whole sRGB cube: the worst case is 4.5:1 on either surface, for all three roles.
+
+**`surface` is the darkest surface the ink lands on, not the page canvas.** It defaults to the
+package light `--accent` `#ebe9e5` — the hover fill under a nav row — because an ink clamped to
+4.5:1 on `--background` `#fdfdfc` measures 3.78:1 the moment the row is hovered, and the hovered
+state is where the lab measured 1.18:1. A region inside the DARK theme must say so, or its ink is
+walked the wrong way:
+
+```tsx
+tenantTheme(tenant.primary_color, { surface: "#3c3a34" }); // --accent in the dark theme
+tenantTheme(tenant.primary_color, { surface: myThemedSidebarFill });
+```
+
+**The guarantee travels with `tenantTheme()`, not with the token.** A consumer who sets `--primary`
+by hand in a stylesheet gets the CSS ramp step and no floor, because WCAG relative luminance cannot
+be computed in CSS — a lightness clamp is hue-blind, and a yellow and a blue at the same lightness
+are four stops apart in luminance. If you re-seed in raw CSS, set the three ink roles yourself and
+check them with `contrastRatio()`.
+
+Worked screen: `docs/showcase/tenant-brand-color.tsx` (`/showcase/tenant-brand-color`) — scope
+proof inside vs outside, the contrast table above, and three run cases (an invalid hex, a
+server-supplied pair below AA, and the brand-ink boundary).
+
+### A scoped theme needs `ThemeScope` to reach the overlays (gh#877)
+
+Every overlay in this library portals to `document.body`, so custom-property inheritance stops at
+the portal boundary: a themed region themes its own subtree and **nothing it opens**. Measured with
+the trigger inside the scope, the region read `--primary 204 100% 37%` and the Dialog it opened read
+`268.7 100% 50%`, the package default — the button right, the panel it opens wrong.
+
+Wrap the region in `ThemeScope` (`@godxjp/ui/app`) and the Dialog, Select listbox, Popover,
+DropdownMenu, Tooltip, Sheet and Toast all follow it:
+
+```tsx
+<ThemeScope data-tenant={tenant.slug} style={tenantTheme(tenant.primary_color).vars}>
+  {region}
+</ThemeScope>
+```
+
+It reads the COMPUTED tokens at its own element, so it does not care whether the theme came from
+`tenantTheme(...).vars`, from `className="dark"`, or from a `[data-tenant]` rule in your own
+stylesheet — the path this page recommends. `docs/providers/theme-scope.tsx`
+(`/isolate/providers-theme-scope`) is the worked screen.
+
+### `applyPrimaryColor` vs `tenantTheme`
+
+Both land on the same arithmetic. Use `tenantTheme` when you are painting a region declaratively —
+no effect, no unmount restore, no SSR flash. Use `applyPrimaryColor(el, hex)` when you are
+RE-SEEDING a tree that is already themed (a project switcher, a service theme): it additionally
+resets `--primary-border` / `--control-outline` / the brand ink roles to `initial`, so a literal an
+ancestor pinned for the previous brand cannot outrank the new seed, and it returns a cleanup.
+
+One consequence of that reset, stated rather than discovered: because `applyPrimaryColor` writes
+`--text-link` / `--text-brand` / `--text-primary` back to `initial` AFTER spreading
+`tenantTheme(...).vars`, a re-seeded tree gets the CSS ramp step and **not** the 4.5:1 ink floor the
+section above describes. On a pale brand that is the gh#887 defect again. Until that reset is
+reconciled with the floor, prefer `tenantTheme` + `ThemeScope` for a pale seed, or re-apply the
+three ink declarations yourself after the call.
+
+---
+
+## Building a COMPLEX theme — the eight things that cost the most
+
+Everything above changes a **colour**. This section is for a theme that changes the **material** of
+every surface — glass, a dark console, a high-contrast skin, anything where the page is no longer
+"the default with a different hue".
+
+It was written by building one (`docs/themes/glassmorphism.css`, `/showcase/glassmorphism`) from the
+public token API and nothing else, as a deliberate stress test. It worked. But every failure along
+the way was one a consumer would hit with no way to know, and the expensive ones **fail silently**:
+nothing errors, nothing warns, and the surface simply keeps the colour it had. Where the cause is a
+gap on our side rather than a rule you should have guessed, the section says so.
+
+Do them in this order. Each one makes the next one decidable:
+
+| #   | decide                                                                 | why it is first                                               |
+| --- | ---------------------------------------------------------------------- | ------------------------------------------------------------- |
+| 1   | which **value form** each knob takes                                   | a knob set in the wrong form paints nothing, and says nothing |
+| 2   | the **polarity** of every surface — light panes or dark                | it determines the ink ramp, and one ramp cannot serve both    |
+| 3   | `--background`, the canvas under the whole shell                       | four visible defects at once if you skip it                   |
+| 4   | the **ink ramp**, measured against the worst ground                    |                                                               |
+| 5   | the **resting** fill of every surface                                  |                                                               |
+| 6   | the **interaction states** — 95 tokens, and resting is not one of them | what you ship broken                                          |
+| 7   | the **overlay opacity tiers** — a dialog is not a card                 |                                                               |
+| 8   | your own `@supports` / `prefers-reduced-transparency` fallbacks        | the library cannot write them for you                         |
+
+Then measure. On composited pixels, never declared colours.
+
+### 1 · There are TWO token value forms, and the name does not tell you which
+
+```css
+HSL COMPONENTS    --card: 60 33% 99%          read at the call site as  hsl(var(--card))
+COMPLETE COLOUR   --card-tint: hsl(var(--primary) / 4%)   read as  var(--card-tint)
+```
+
+A components token holds three (or four) bare numbers with no function around them. A complete
+token holds a finished CSS colour — `hsl(…)`, `rgb(…)`, `oklch(…)`, `#hex`, `color-mix(…)`.
+
+**The name is not a signal, and neither is the tier.** Five knobs that all paint the hover or
+active fill of a navigable row, all defaulting to the same `--accent` role, in three components:
+
+| knob                                | the declaration that reads it                                                                                   | form                |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------- |
+| `--menu-item-hover-background`      | `src/styles/navigation-layout.css:828` — `background: var(--menu-item-hover-background, hsl(var(--accent)))`    | **complete colour** |
+| `--tree-node-hover-background`      | `src/styles/data-display-layout.css:2525` — `background: var(--tree-node-hover-background, hsl(var(--accent)))` | **complete colour** |
+| `--table-row-hover-background`      | `src/styles/table-layout.css:591` — `var(--table-row-hover-background, hsl(var(--accent) / 0.7))`               | **complete colour** |
+| `--segmented-item-hover-background` | `src/styles/control.css:1559` — `background: hsl(var(--segmented-item-hover-background, var(--accent)))`        | **HSL components**  |
+| `--topbar-item-hover-background`    | `src/styles/shell-layout.css:2852` — `background: hsl(var(--topbar-item-hover-background, var(--accent)))`      | **HSL components**  |
+
+And the two halves of the same `.ui-card` rule disagree with each other:
+`--card-background` is components (`src/styles/card-layout.css:62`, `hsl(var(--card-background,
+var(--card)))`) while `--card-tint` three lines above it is a complete colour.
+
+**How to tell, today: read the call site.** The knob's own declaration in
+`dist/tokens/**` is `initial` and tells you nothing; the read site tells you everything.
+
+```sh
+# in your app, after installing the package
+grep -rho 'hsl(var(--tabs-list-background\|var(--tabs-list-background' node_modules/@godxjp/ui/dist
+#   var(--tabs-list-background              → COMPLETE COLOUR
+#   hsl(var(--tabs-list-background          → HSL COMPONENTS
+```
+
+Grep `dist` whole, not `dist/styles` — a few knobs are read from a component's JS
+(`--toast-background` is read in `sonner.tsx` as `var(--toast-background, hsl(var(--popover)))`,
+because sonner renders the toast body itself).
+
+Measured on this repo's sources: **346 published tokens hold a colour. 96 take HSL components, 249
+take a complete colour, 1 (`--brand-foreground`) is published for your CSS and read by none of
+ours.** There is no rule that predicts the split. The older semantic roles — `--primary`,
+`--background`, `--foreground`, `--card`, `--muted`, `--accent`, `--border`, `--input`, `--ring`,
+the `--text-*` ramp, the four status pairs — are components. Most component-tier knobs added since
+are complete colours. "Most" is not a rule you can theme against.
+
+#### The failure is silent, and it does NOT fall back
+
+Set a knob in the wrong form and the substituted declaration is **invalid at computed-value time**.
+The property takes **its own initial value** — and _not_ the call-site fallback, which is the part
+that makes this read like a knob that does not work. Measured in Chromium, both forms, both
+mistakes:
+
+| the call site                | what you set     | computed `background-color`       |
+| ---------------------------- | ---------------- | --------------------------------- |
+| `var(--k, hsl(120 50% 50%))` | nothing          | `rgb(64, 191, 64)` — the fallback |
+| `var(--k, hsl(120 50% 50%))` | `rgb(255 0 0)` ✓ | `rgb(255, 0, 0)`                  |
+| `var(--k, hsl(120 50% 50%))` | `0 100% 50%` ✗   | **`rgba(0, 0, 0, 0)`**            |
+| `hsl(var(--k, 120 50% 50%))` | nothing          | `rgb(64, 191, 64)` — the fallback |
+| `hsl(var(--k, 120 50% 50%))` | `0 100% 50%` ✓   | `rgb(255, 0, 0)`                  |
+| `hsl(var(--k, 120 50% 50%))` | `rgb(255 0 0)` ✗ | **`rgba(0, 0, 0, 0)`**            |
+
+A transparent background shows whatever is painted behind it, so the surface looks like it kept its
+old colour. A table header set in the wrong form measured **1.03:1** against light ink — because it
+was showing the card beneath it, not the fill that was written for it.
+
+**The tell, when you are debugging:** in DevTools the custom property is set to exactly what you
+wrote, and the painted property is `rgba(0, 0, 0, 0)`. If both of those are true, it is the form.
+
+#### The sub-trap: an alpha baked into a components role
+
+A components role may legally carry an alpha — `--card: 0 0% 100% / 42%` is how a glass theme makes
+every card translucent in one line, and it works. But **83 declarations across 15 roles read a role
+and apply their own alpha** (`hsl(var(--accent) / 0.7)`, `hsl(var(--primary) / 0.12)`, …). A role
+that already carries one produces a second `/` in those, which is a parse error. Measured:
+
+| `--role`          | read as `hsl(var(--role))`  | read as `hsl(var(--role) / 0.9)` |
+| ----------------- | --------------------------- | -------------------------------- |
+| `0 0% 100%`       | `rgb(255, 255, 255)`        | `rgba(255, 255, 255, 0.9)`       |
+| `0 0% 100% / 42%` | `rgba(255, 255, 255, 0.42)` | **`rgba(0, 0, 0, 0)`**           |
+
+The 15 roles with at least one such reader, worst first: `--primary` (18 sites), `--muted` (15),
+`--destructive` (8), `--warning` (6), `--success` (5), `--info` (5), `--accent` (5), `--foreground`
+(5), `--muted-foreground` (4), `--table-row-tone-color` (4), `--background` (3),
+`--destructive-foreground` (2), `--secondary` (1), `--accent-foreground` (1), `--ring` (1).
+`--card` and `--popover` have none, which is exactly why baking an alpha into those two is the
+glass theme's main move.
+
+#### This is our defect, not your oversight
+
+`get_tokens`, `agent/tokens.json` and `mcp/src/data/component-tokens.generated.ts` all report a
+knob as `value: "initial"` plus prose. **3 of the 346 colour tokens say which value form they
+take** (`--background`, `--focus-ring-color`, `--rating-star-filled-color`, each by accident of
+someone writing it into a source comment). `scripts/explain-token.mjs` prints every read site of a
+token but not the text of the read, and it is not in the package's `files` list, so a consumer does
+not have it. Until the catalog carries the form as a field, the grep above is the answer, and it
+should not have to be. Cardinal rule **48** states the rule; the gap is what the rule is for.
+
+### 2 · Ninety-five interaction-state tokens exist, and resting state is not one of them
+
+```sh
+node -e "const t=require('./node_modules/@godxjp/ui/agent/tokens.json'); \
+  console.log(t.filter(x => /-(hover|active|selected|checked|pressed|focus)(-|\$)/.test(x.name)).length)"
+# 95
+```
+
+**95** published tokens paint only in a non-resting state; **62** of them paint a colour, an edge or
+an elevation. The glass theme, after three rounds of fixes, sets **5**. Every defect reported off a
+screenshot during that build was one of the missing 90:
+
+- a sidebar row at `[data-active="true"]` reading dark violet on a violet tint —
+  `--sidebar-item-active-foreground` defaults to the live `--primary-active`
+  (`src/styles/shell-layout.css:2289-2291`), which is legible against the page only for a seed that is
+  itself legible as text on the page. A dark seed on a dark theme is not. The same caveat is in
+  "What follows `--primary`" above; it bites hardest in a re-materialised theme.
+- a Segmented item with a dark hover fill under dark hover text — `--segmented-item-hover-background`
+  and `--segmented-item-hover-color` are separate knobs and the first was set alone.
+- a Topbar hover block — `--topbar-item-hover-background`, same shape.
+
+**`--focus-ring-color` is on that list, and it is the worst one to get wrong.** Every ring in the
+package is painted by one rule in `src/styles/focus-ring.css`:
+
+```css
+outline-width: var(--focus-ring-width);
+outline-style: solid;
+outline-color: hsl(
+  var(--focus-outline-color, var(--focus-ring-color, var(--ring))) / var(--focus-ring-opacity, 1)
+);
+```
+
+So it is **HSL components** — and it is read with an alpha applied, so both mistakes from §1 (write
+`hsl(...)` into it, or bake an alpha into it) make the colour invalid at computed-value time. The
+three longhands are what contains the damage (gh#885): only `outline-color` is discarded, falling
+back to `currentcolor`, so you get a ring in the wrong colour. **As a single `outline` shorthand it
+used to take `outline-width` and `outline-style` down with it and delete the indicator outright** —
+Chromium reported `outline-width: 3px; outline-style: none`, which reads in a measurement tool that
+ignores `outline-style` as "a 3px ring in the brand colour". Fix the FORM of the token; a
+`currentcolor` ring is not the ring you asked for. Unset it follows `--ring`, which is the
+package's, not your theme's. A ring tuned for a light page is a WCAG
+2.2 SC 1.4.11 defect on a dark one (3:1 against **every** surface a control sits on) and an SC 2.4.7
+failure if it vanishes. See the focus-ring section above for the switch, the weight and the
+per-component knobs.
+
+**The method:** for each component your theme re-materialises, list its tokens
+(`get_component`, or `grep -r -- '--<component>-' node_modules/@godxjp/ui/dist/tokens/components/`)
+and
+set the hover / active / selected / checked row **at the same time as the resting one**. A state
+knob left at its default resolves against the _live role_ at the painting element — which is the
+right default and exactly why it can be wrong for you: your `--accent` is now a dark violet, and the
+item's ink still assumes the package's pale one.
+
+### 3 · One ink ramp only works if every surface shares a POLARITY
+
+`docs/GLASSMORPHISM-STANDARD.md` §3 says "one ink ramp for the whole theme". That is right and
+incomplete, and measuring found where: **a single ramp only serves surfaces of the same polarity.**
+
+Light panes take dark ink. A toned tint over a **dark** page is a dark pane and takes light ink. The
+glass theme had one dark ramp serving both; the Cards were fine and the Alert measured **1.27:1 and
+1.35:1** — not a contrast bug in the ink but a polarity bug, two surfaces of opposite value asking
+one ramp to serve both.
+
+**So decide polarity first, then derive one ramp per polarity.** If you want a single ramp — and you
+should, because it is the only way "muted" stays consistent — then every surface has to be the same
+polarity, which for a tinted status pane means making it a **light pane tinted by hue** rather than a
+dark pane darkened by it. The four knobs for that are
+`--surface-success` / `--surface-warning` / `--surface-info` / `--surface-destructive`
+(`src/tokens/foundation.css:235-238`): independently chosen grounds for the four status tones, so
+the ground stops being derived from the ink through an alpha. They are **finished colours**, and
+`foundation.css:217` says so in as many words — "FINISHED COLOURS, NOT HSL COMPONENTS — the one
+place this tier differs from the three above". See §1.
+
+And on any re-materialised surface, `muted` cannot mean lower contrast. Hierarchy is carried by
+size and weight at the **same** ratio — body at 7:1 so it keeps a margin when the ground shifts
+under it, secondary just inside 4.5:1.
+
+### 4 · `--background` is the canvas under the whole shell
+
+`--gradient-glow` paints on the shell's **main region only** — `.app-main`
+(`src/styles/shell-layout.css:412`), and the two other shells' equivalents,
+`.ui-centered-shell-main` (`:897`) and `.ui-mobile-shell-main` (`:3384`). Sidebar and Topbar are
+`.app-main`'s **siblings** in the same CSS grid (`grid-area: sidebar` at `:217`, `grid-area:
+topbar` at `:384`), so none of the gradient is behind them. What is behind them is
+`.app-root { background: hsl(var(--background)) }` (`:28`) — and `body`
+(`src/styles/base.css:260`) under that.
+
+A theme that sets `--foreground` to near-white and never sets its pair therefore gets **light chrome
+carrying near-white labels**. In the glass build, one missing line was four reported defects: a pink
+Sidebar, a Topbar running pink on the left and blue on the right, an unreadable near-white table
+header strip, and a washed-out dropdown. The fix was `--background` plus the family that derives
+from the same canvas decision — `--muted`, `--accent`, `--secondary`, `--input` and their
+`-foreground` pairs.
+
+**`--foreground` and `--background` are one decision — never set only one of them.** The canvas
+family, in full:
+
+```css
+--background   --foreground
+--card         --card-foreground
+--popover      --popover-foreground
+--muted        --muted-foreground
+--accent       --accent-foreground
+--secondary    --secondary-foreground
+--border       --input       --ring
+```
+
+### 5 · A scoped theme cannot re-ink its own text
+
+`src/styles/base.css:261` sets `color: hsl(var(--foreground))` on `body`. `body` is above every
+scope you can make, so that `var()` substitutes against the **root's** `--foreground` exactly once
+and every element below inherits the already-resolved colour. A plain `<div>` that sets your theme's
+tokens therefore retints every **surface** and no **text**. Measured on the showcase before it was
+fixed: the title's own computed `--foreground` was the theme's near-white while its `color` stayed
+`rgb(36, 35, 30)` — real-pixel contrast **1.34:1**, every element in the subtree reporting that it
+was inside the scope. It is the `:root` freeze rule (`docs/TOKEN-RESOLUTION.md` §3) applied to a
+_property_ instead of a token, and worse there: a token can be given a knob, and `color` on `body`
+has none to give.
+
+Two remedies, and they are not interchangeable:
+
+- **React** — wrap the region in `ThemeScope` (`@godxjp/ui/app`). It re-states
+  `color: "hsl(var(--foreground))"` on its own element (`src/lib/overlay-portal.tsx:270`, with
+  `display: contents` so it removes the box and not the inheritance) **and** on the `body`-level
+  host it creates for portalled overlays (`:203`) — which is the other half of the problem, because
+  a Dialog portals to `document.body` and would otherwise wear the root's theme. `...style` is
+  spread after, so your own `color` still wins.
+- **A stylesheet-only scope** — state it yourself, on your own element:
+
+  ```css
+  [data-theme="glass"] {
+    --foreground: 48 20% 96%;
+    --background: 230 40% 9%;
+    /* … */
+    color: hsl(var(--foreground)); /* NOT optional */
+  }
+  ```
+
+  That is a declaration on _your_ element, not a selector into this package, so it does not breach
+  "a consumer sets tokens, never selectors" (`docs/TOKEN-RESOLUTION.md` §5 rule 5). It does **not**
+  reach portalled overlays; for those you still need `ThemeScope` or a scope on the portal
+  container. `docs/TOKEN-RESOLUTION.md` §5 rule 7 is the short form; gh#881 is the incident.
+
+### 6 · A theme owns its own transparency fallbacks
+
+If your theme makes a surface translucent, **your theme** writes its
+`@media (prefers-reduced-transparency: reduce)` and
+`@supports not (backdrop-filter: blur(1px))` branches. The library does not, and cannot: it does
+not know what opaque colour you want, and guessing at the role's own value is not safe — a theme
+whose `--card` is `0 0% 100% / 42%` would get a "fallback" that is still 42% translucent.
+
+We shipped a generic fallback for a while and it was **actively wrong**: under `reduce` it left a
+Card translucent and painted the Topbar fully transparent — invisible. It is removed.
+`docs/TOKEN-RESOLUTION.md` §5 rule 6 is the standing rule. Keep both branches to
+custom-property declarations on your theme's own selector, and repaint exactly the surfaces you
+made translucent; leave borders alone.
+
+`prefers-reduced-transparency` is an OS accessibility setting. Honouring it is not optional.
+
+### 7 · Overlays are not cards
+
+A dialog or a drawer at a card's alpha is read straight through, and both were, at 20%. A card sits
+on a ground you chose; an overlay sits over **arbitrary** content, and the smaller it is the less
+the reader can use context to recover a word. So every overlay belongs at the opaque end of the
+range and the card belongs at the translucent end — the gap is much bigger than it looks when you
+are picking numbers in a token file.
+
+Where the glass theme landed, after the first pass at 20% was reported unreadable:
+
+| surface                           | fill                                                                               |
+| --------------------------------- | ---------------------------------------------------------------------------------- |
+| drawer (`Sheet`)                  | **92%** — covers content that must stay unreadable-but-present                     |
+| `Toast`                           | **90%**                                                                            |
+| dialog panel                      | **88%**, over `--dialog-overlay-alpha: 62%` — a scrim that both darkens and blurs  |
+| `DropdownMenu` / `Select` listbox | **88%**                                                                            |
+| `Card`                            | **12%** — the recipe's own number, and the one that makes the backdrop the palette |
+
+Two mechanics worth knowing before you tune those numbers:
+
+- **A modal's blur belongs on the SCRIM, not the panel.** `backdrop-filter` filters what is behind
+  the element, and the scrim is the layer that covers the page. It also makes the element the
+  containing block for its `position: fixed` descendants, which is why every blur knob in this
+  package is `initial` rather than `blur(0px)` — unset, the whole declaration is invalid at
+  computed-value time, `backdrop-filter` keeps its own `none`, and no backdrop root is created.
+  `--dialog-overlay-backdrop-blur-size` and `--sheet-overlay-backdrop-blur-size` are the scrim
+  knobs; there is deliberately no knob for a blur on the panel itself.
+- **Do not double-blur.** A dropdown inside an already-blurred panel blurs a blurred copy and reads
+  as dirty glass. Blur the few surfaces that define depth — chrome and overlays — not every card,
+  row and chip. It is also GPU-expensive.
+
+`docs/GLASSMORPHISM-STANDARD.md` §4 has the reasoning per surface, and §4b covers form fields, which
+are the hardest case in the system: a field has to read as _a place you can type_ before it reads as
+anything else, and translucency destroys exactly the two signals that say so.
+
+### 8 · Measure the COMPOSITED pixel, against the worst region
+
+A translucent fill over a gradient is not the colour you declared, and `getComputedStyle` cannot
+tell you what it became — it reports the element's own `background-color` with its own alpha, not
+the stack. **Screenshot the rendered page, sample the pixel under the text, compute the ratio.**
+
+Two more rules that come from getting this wrong four times in one session:
+
+- **Sample the worst region the backdrop can produce**, not a convenient one. A radial gradient has
+  a light lobe and a dark one and the pane must be legible over both. The glass build's worst ground
+  sampled `rgb(172, 159, 172)`; against it the stock `--muted-foreground` `rgb(104, 102, 94)`
+  measures **2.28:1**, and solving from that number rather than guessing gave the ramp: `L ≤ 22.5%`
+  for 4.5:1, `L ≤ 9.5%` for 7:1.
+- **Sanity-check the instrument before you believe it.** Two signatures of a broken measurement,
+  both seen: a ratio that is _identical_ for several visibly different colours (the script failed to
+  resolve a custom property and scored the same fallback every time), and a ratio that contradicts
+  what you can see (`1.03:1` on a surface that looks fine — or the reverse). **When a fix does not
+  hold, suspect the diagnosis before re-applying the cure.** A custom property read with
+  `getPropertyValue()` comes back as `initial`, as an unresolved `var()` chain, or as three bare
+  numbers that are not a colour at all; a parser that accepts all three without complaint will
+  report a number for every one of them.
+
+### What to read next
+
+- `docs/TOKEN-RESOLUTION.md` — §3 the freeze rule (why a knob is `initial` and its default lives at
+  the call site), §5 the seven rules for anyone setting or adding a token.
+- `docs/GLASSMORPHISM-STANDARD.md` — the worked case: the four signals of the style, the contrast
+  rules, overlays, and why form fields are the hardest surface.
+- `docs/THEME-API-COVERAGE.md` — how far the token API reaches today, per component, with the
+  hard-coded declarations listed. Read it before you conclude a knob is missing.
+
+---
+
+## Artwork & third-party marks — where the token rule ends (gh#867)
+
+Every section above assumes the colour arrives as CSS on an element this library renders. Artwork
+is the case the rule does not state: **an SVG loaded through `<img src>` runs inside its own
+document boundary and cannot see the page's custom properties.** No token reaches it, scoped or
+otherwise — that is a browser fact, not a library omission, and no component API can change it. So
+"brand colour enters only through scoped tokens" has one silent exception: artwork that arrives as
+a file. Four techniques, and the boundary between them:
+
+| the asset                                                   | the technique                                                    |
+| ----------------------------------------------------------- | ---------------------------------------------------------------- |
+| a multi-colour brand mark                                   | **1 · two masters** — ship both variants, switch by scheme       |
+| a single-colour glyph that should follow the text beside it | **2 · inline + `currentColor`**                                  |
+| a single-colour glyph that should sit at a token colour     | **3 · `mask-image`** — shape from the asset, colour from a token |
+| everything else — screenshots, illustrations, uploads       | **4 · do not recolour**                                          |
+
+### 1 · Two masters, switched by colour scheme
+
+What this library does for its own mark, and the right answer for any multi-colour brand: both
+masters ship, and CSS shows one per scheme. `src/components/general/logo.tsx` renders the light
+and dark artworks as siblings, and `src/styles/logo-layout.css` picks between them — an explicit
+light choice, an explicit dark choice, and the un-stamped default where only the OS preference
+separates them. The brand guidelines quoted in the component's comment (brand identity v2.3)
+forbid all three shortcuts: no re-tinting the master to a module's colour, no inverting it with a
+filter, and the correct sáng/tối variant rendered as-is.
+
+Two properties of that implementation matter if you copy it:
+
+- **The masters are different files and stay different files.** They arrive as separate assets in
+  the brand kit and land verbatim in `src/brand/godx-artwork.generated.ts` — not one artwork whose
+  token values get swapped per theme. `grep -c currentColor src/brand/` → `0`: the package's own
+  brand artwork carries no token hooks at all. This technique involves no tokens on purpose.
+- **Inlining is for fidelity and document validity, not tokenisation.** The markup is inlined
+  (`dangerouslySetInnerHTML`) because 8 gradients, a clipPath and 10 paths must stay byte-exact,
+  and because SVG ids are unique per document — two `<Logo>`s on one page would otherwise emit
+  duplicate ids. Both comments in `logo.tsx` state this explicitly and claim no theming benefit.
+
+The colours of a multi-colour mark ARE the brand; they do not follow `--primary` — which is exactly
+why the generator keeps `--brand` / `--brand-foreground` independent of the action colour (gh#250).
+
+### 2 · Inline the SVG and use `currentColor` — the single-colour glyph
+
+For a single-colour glyph that should follow the text it sits beside. Inline the file and paint
+the path with `currentColor`:
+
+```css
+/* your app's stylesheet — a role, not a literal, so scopes and dark mode reach it */
+.ui-mark {
+  color: hsl(var(--primary)); /* or --text-link, or whatever text role it accompanies */
+}
+```
+
+```tsx
+<svg className="ui-mark" viewBox="…" aria-hidden="true">
+  <path fill="currentColor" d="…" />
+</svg>
+```
+
+The glyph now follows `color` like any text: a `[data-tenant]` scope, a link's `--text-link`, dark
+mode — anything that sets `color` above it re-tints the glyph with it. It is one colour by
+construction; if the glyph needs two, this is the wrong technique — go back to 1.
+
+### 3 · `mask-image` — shape from the asset, colour from a token
+
+When the asset should sit at a token colour regardless of the text around it, take the shape from
+the file and the colour from CSS:
+
+```css
+.ui-partner-mark {
+  width: 1.25em;
+  height: 1.25em;
+  background: hsl(var(--primary)); /* the token does the colouring */
+  mask-image: url("./partner-mark.svg"); /* the asset's transparency supplies the shape */
+  mask-size: contain;
+  mask-repeat: no-repeat;
+}
+```
+
+The mask reads the asset's alpha as the shape; `background` supplies the only colour, so a token
+change, a `[data-tenant]` scope and dark mode all reach it — the colour is ordinary CSS. It is
+single-colour by construction: a mask has no way to carry a second colour.
+
+Stated honestly, this library uses CSS masking in exactly **two** places — the Marquee's edge fade
+(`src/styles/motion.css`) and the FloatButton (`src/styles/float-button-layout.css`). This is a
+technique documented here, not a house pattern; reach for it for one-colour glyphs, not as the
+default answer to "how do I theme an image".
+
+### 4 · Do not recolour
+
+`Thumbnail` (`src/components/data-display/thumbnail.tsx`) is a framed `<img>`, and `src` artwork
+keeps its authored colours in every theme — it always has. Screenshots, illustrations, photos,
+uploaded logos: they render exactly as authored, and that is the answer, not a gap and not a
+roadmap item. If the artwork must read on both schemes, choose or commission artwork that does;
+the frame and the surface around it are yours to theme — the pixels inside them are not.
+
+### The caveat that is not a footnote
+
+Techniques 1–3 inline SVG, and inlined SVG is markup in your document. An upload that lands as
+markup is an XSS surface — `<script>`, event attributes, `javascript:` hrefs all execute. The
+boundary `logo.tsx` states in its own comment — _"package-owned generated content, never user
+input"_ — is the whole rule: **inlining is for artwork you generate**, at build time, from your
+own kit. Anything a customer uploads either passes a real sanitiser before it is inlined, or goes
+through `<img>` and stays unthemed — which is technique 4, and a legitimate outcome.