Namespace the subtree theme scopes as .theme-light/.theme-dark: dark: follows the nearest scope, portalled dashboard menus and tooltips restate it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WgBfkm4rCmtd1T4vHWjEPx
This commit is contained in:
2026-10-15 17:42:59 +02:00
co-authored by Claude Opus 5.5
parent 58b92da8b0
commit 868a10d94b
14 changed files with 78 additions and 47 deletions
+1 -1
View File
@@ -8,7 +8,7 @@ any UI work.
## Sync rule (read before touching tokens) ## Sync rule (read before touching tokens)
The `@theme inline`, `:root`, and `.dark` blocks in `app/frontend/src/index.css` The `@theme inline`, `:root`, and `.theme-dark` blocks in `app/frontend/src/index.css`
and `index/src/index.css` **must be kept byte-identical**, and and `index/src/index.css` **must be kept byte-identical**, and
`frontend/src/lib/motion.ts` is duplicated verbatim. Any palette / radius / `frontend/src/lib/motion.ts` is duplicated verbatim. Any palette / radius /
elevation / motion-token change is made in *both* repos in the same change. elevation / motion-token change is made in *both* repos in the same change.
@@ -139,8 +139,9 @@ export function useDashboardBackground(
* The class that themes a dashboard's own surface, or `""` to follow the app. * The class that themes a dashboard's own surface, or `""` to follow the app.
* *
* A class rather than the root, because inside the app shell this must not * A class rather than the root, because inside the app shell this must not
* flip the chrome around it. `.light` and `.dark` both redefine the tokens on * flip the chrome around it. `.theme-light` and `.theme-dark` both redefine the
* whatever carries them (`index.css`), so either direction works on a subtree. * tokens on whatever carries them (`index.css`), and `dark:` follows the
* nearest of them, so either direction works on a subtree.
* *
* A palette decides this for itself: its first colour *is* the ground, so * A palette decides this for itself: its first colour *is* the ground, so
* whether the surface is light or dark is a fact about the palette rather than * whether the surface is light or dark is a fact about the palette rather than
@@ -6,9 +6,10 @@
* below reads them from there: the tokens by inheritance, the look and the * below reads them from there: the tokens by inheritance, the look and the
* touch flag through this context. * touch flag through this context.
* *
* The style is carried in the context as well as on the element, because a * The style and the theme class are carried in the context as well as on the
* menu is portalled to `body` and lands outside the canvas. A surface that * element, because a menu is portalled to `body` and lands outside the canvas.
* floats out of the tree re-states the tokens rather than borrowing the app's. * A surface that floats out of the tree re-states them rather than borrowing
* the app's.
*/ */
import { createContext, useContext, useMemo } from "react" import { createContext, useContext, useMemo } from "react"
@@ -28,6 +29,8 @@ type Canvas = {
touch: boolean touch: boolean
/** The palette's tokens, or `{}` when the dashboard names none. */ /** The palette's tokens, or `{}` when the dashboard names none. */
style: React.CSSProperties style: React.CSSProperties
/** The theme scope class, `theme-light` or `theme-dark`. */
theme: string
} }
/** A dashboard that names no palette, as one object rather than one per render. */ /** A dashboard that names no palette, as one object rather than one per render. */
@@ -37,6 +40,7 @@ const LookContext = createContext<Canvas>({
look: "material", look: "material",
touch: false, touch: false,
style: {}, style: {},
theme: "",
}) })
/** The look everything under here is drawn in. */ /** The look everything under here is drawn in. */
@@ -46,10 +50,10 @@ export const useLook = () => useContext(LookContext)
* What the canvas root carries: the theme class, the palette, and the two * What the canvas root carries: the theme class, the palette, and the two
* attributes the looks' stylesheets key off. * attributes the looks' stylesheets key off.
* *
* The class is always resolved to `light` or `dark`, rather than left empty * The class is always resolved to `theme-light` or `theme-dark`, rather than
* for a dashboard that follows the device: the sets state their own colours * left empty for a dashboard that follows the device: the sets state their own
* per theme, and a chart canvas has to be told which one it is drawing in. * colours per theme, and a chart canvas has to be told which one it is drawing
* Restating the app's own resolved theme changes nothing when they agree. * in. Restating the app's own resolved theme changes nothing when they agree.
* *
* `touch` is passed in rather than read off the document, because it belongs to * `touch` is passed in rather than read off the document, because it belongs to
* the screen rather than to the dashboard: the same document may hang on a * the screen rather than to the dashboard: the same document may hang on a
@@ -73,7 +77,7 @@ export function useCanvasRoot(
[roles], [roles],
) )
return { return {
className: stated || (resolvedTheme === "dark" ? "dark" : "light"), className: `theme-${stated || resolvedTheme}`,
style, style,
"data-look": look, "data-look": look,
"data-touch": touch ? "" : undefined, "data-touch": touch ? "" : undefined,
@@ -101,13 +105,13 @@ export function LookProvider({
const root = useCanvasRoot(dashboard, touch) const root = useCanvasRoot(dashboard, touch)
const look = root["data-look"] const look = root["data-look"]
const touched = root["data-touch"] !== undefined const touched = root["data-touch"] !== undefined
const { style } = root const { style, className: theme } = root
// A bound setting wakes this component on every message its flow sends, and // A bound setting wakes this component on every message its flow sends, and
// what the widgets below actually react to is the value — so it changes only // what the widgets below actually react to is the value — so it changes only
// when one of the three things it carries does. // when one of the four things it carries does.
const value = useMemo( const value = useMemo(
() => ({ look, touch: touched, style }), () => ({ look, touch: touched, style, theme }),
[look, touched, style], [look, touched, style, theme],
) )
return <LookContext.Provider value={value}>{children}</LookContext.Provider> return <LookContext.Provider value={value}>{children}</LookContext.Provider>
} }
@@ -121,7 +121,7 @@ assert.deepEqual(
) )
assert.deepEqual( assert.deepEqual(
rolesOf(["#0a0a0a"])?.series.slice(1), rolesOf(["#0a0a0a"])?.series.slice(1),
slots(block(".dark {")), slots(block(".theme-dark {")),
"a dark dashboard continues with the dark --chart-2…8", "a dark dashboard continues with the dark --chart-2…8",
) )
@@ -10,7 +10,7 @@
* *
* The result is written onto the canvas as the plain token variables the app * The result is written onto the canvas as the plain token variables the app
* already themes with (`--background`, `--card`, `--primary`, …), which is the * already themes with (`--background`, `--card`, `--primary`, …), which is the
* same mechanism `.light` and `.dark` use on a subtree. Nothing here touches * same mechanism `.theme-light` and `.theme-dark` use on a subtree. Nothing here touches
* `index.css`: that file's token blocks are byte-identical with the website's * `index.css`: that file's token blocks are byte-identical with the website's
* and `make design-check` holds them there. * and `make design-check` holds them there.
* *
@@ -154,8 +154,9 @@ export function Select({
onChange, onChange,
}: SelectProps) { }: SelectProps) {
// The menu is portalled to `body`, which is outside the canvas — so it // The menu is portalled to `body`, which is outside the canvas — so it
// re-states the dashboard's own colours rather than borrowing the app's. // re-states the dashboard's own theme and colours rather than borrowing the
const { style } = useLook() // app's.
const { style, theme } = useLook()
return ( return (
<SelectPrimitive.Root <SelectPrimitive.Root
value={value} value={value}
@@ -178,7 +179,10 @@ export function Select({
position="popper" position="popper"
sideOffset={4} sideOffset={4}
style={style} style={style}
className="fx-menu z-50 max-h-64 min-w-[var(--radix-select-trigger-width)] overflow-y-auto p-1 data-[state=open]:animate-in data-[state=open]:zoom-in-95 data-[state=open]:fade-in-0" className={cn(
theme,
"fx-menu z-50 max-h-64 min-w-[var(--radix-select-trigger-width)] overflow-y-auto p-1 data-[state=open]:animate-in data-[state=open]:zoom-in-95 data-[state=open]:fade-in-0",
)}
> >
<SelectPrimitive.Viewport> <SelectPrimitive.Viewport>
{options.map((option) => ( {options.map((option) => (
@@ -172,8 +172,9 @@ export function Select({
onChange, onChange,
}: SelectProps) { }: SelectProps) {
// The menu is portalled to `body`, which is outside the canvas — so it // The menu is portalled to `body`, which is outside the canvas — so it
// re-states the dashboard's own colours rather than borrowing the app's. // re-states the dashboard's own theme and colours rather than borrowing the
const { style } = useLook() // app's.
const { style, theme } = useLook()
return ( return (
<SelectPrimitive.Root <SelectPrimitive.Root
value={value} value={value}
@@ -200,7 +201,10 @@ export function Select({
position="popper" position="popper"
sideOffset={4} sideOffset={4}
style={style} style={style}
className="gl-menu z-50 max-h-64 min-w-[var(--radix-select-trigger-width)] overflow-y-auto p-1 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95" className={cn(
theme,
"gl-menu z-50 max-h-64 min-w-[var(--radix-select-trigger-width)] overflow-y-auto p-1 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95",
)}
> >
<SelectPrimitive.Viewport> <SelectPrimitive.Viewport>
{options.map((option) => ( {options.map((option) => (
@@ -42,7 +42,7 @@
--dui-on-handle: rgb(0 0 0 / 0.75); --dui-on-handle: rgb(0 0 0 / 0.75);
} }
[data-look="glass"].light { [data-look="glass"].theme-light {
--gl-bg: rgb(255 255 255 / 0.5); --gl-bg: rgb(255 255 255 / 0.5);
--gl-bg-strong: rgb(255 255 255 / 0.7); --gl-bg-strong: rgb(255 255 255 / 0.7);
--gl-border: rgb(255 255 255 / 0.75); --gl-border: rgb(255 255 255 / 0.75);
@@ -199,8 +199,9 @@ export function Select({
onChange, onChange,
}: SelectProps) { }: SelectProps) {
// The menu is portalled to `body`, which is outside the canvas — so it // The menu is portalled to `body`, which is outside the canvas — so it
// re-states the dashboard's own colours rather than borrowing the app's. // re-states the dashboard's own theme and colours rather than borrowing the
const { style } = useLook() // app's.
const { style, theme } = useLook()
return ( return (
<SelectPrimitive.Root <SelectPrimitive.Root
value={value} value={value}
@@ -226,7 +227,10 @@ export function Select({
position="popper" position="popper"
sideOffset={4} sideOffset={4}
style={style} style={style}
className="m3-menu z-50 max-h-64 min-w-[var(--radix-select-trigger-width)] overflow-y-auto p-1 data-[state=open]:animate-in data-[state=open]:zoom-in-95 data-[state=open]:fade-in-0" className={cn(
theme,
"m3-menu z-50 max-h-64 min-w-[var(--radix-select-trigger-width)] overflow-y-auto p-1 data-[state=open]:animate-in data-[state=open]:zoom-in-95 data-[state=open]:fade-in-0",
)}
> >
<SelectPrimitive.Viewport> <SelectPrimitive.Viewport>
{options.map((option) => ( {options.map((option) => (
@@ -23,6 +23,7 @@ import type {
RailProps, RailProps,
} from "../core/contract" } from "../core/contract"
import { railGeometry, TESTID } from "../core/contract" import { railGeometry, TESTID } from "../core/contract"
import { useLook } from "../core/look"
import { LOOK } from "../core/motion" import { LOOK } from "../core/motion"
/** Material's ground is the surface colour itself; only an image is drawn. */ /** Material's ground is the surface colour itself; only an image is drawn. */
@@ -39,6 +40,8 @@ export function Backdrop({ image }: BackdropProps) {
} }
function Issue({ issue }: { issue: string }) { function Issue({ issue }: { issue: string }) {
// Portalled to `body`, so it re-states the dashboard's theme and colours.
const { style, theme } = useLook()
return ( return (
<Tooltip> <Tooltip>
<TooltipTrigger asChild> <TooltipTrigger asChild>
@@ -49,7 +52,12 @@ function Issue({ issue }: { issue: string }) {
data-testid={TESTID.issue} data-testid={TESTID.issue}
/> />
</TooltipTrigger> </TooltipTrigger>
<TooltipContent className="max-w-xs break-words">{issue}</TooltipContent> <TooltipContent
className={cn(theme, "max-w-xs break-words")}
style={style}
>
{issue}
</TooltipContent>
</Tooltip> </Tooltip>
) )
} }
+2 -3
View File
@@ -219,9 +219,8 @@ function BrainCanvas() {
nodesConnectable={false} nodesConnectable={false}
elementsSelectable={false} elementsSelectable={false}
proOptions={{ hideAttribution: true }} proOptions={{ hideAttribution: true }}
// React Flow stamps this on the wrapper as a class, and the app's own // React Flow's own defaults, for whatever flow.css does not route
// token scopes are named `.light` / `.dark` (index.css) — so leaving it // through the tokens, follow the theme too.
// unset re-themes the whole canvas to light inside a dark shell.
colorMode={resolvedTheme} colorMode={resolvedTheme}
fitView fitView
fitViewOptions={FIT} fitViewOptions={FIT}
+2 -3
View File
@@ -1284,9 +1284,8 @@ function FlowEditorInner({
nodeTypes={nodeTypes} nodeTypes={nodeTypes}
edgeTypes={edgeTypes} edgeTypes={edgeTypes}
proOptions={{ hideAttribution: true }} proOptions={{ hideAttribution: true }}
// React Flow stamps this on the wrapper as a class, and the app's own // React Flow's own defaults, for whatever flow.css does not route
// token scopes are named `.light` / `.dark` (index.css) — so leaving it // through the tokens, follow the theme too.
// unset re-themes the whole canvas to light inside a dark shell.
colorMode={resolvedTheme} colorMode={resolvedTheme}
fitView fitView
fitViewOptions={FIT_VIEW} fitViewOptions={FIT_VIEW}
+4 -4
View File
@@ -2,10 +2,10 @@
* React Flow, routed through the design tokens. * React Flow, routed through the design tokens.
* *
* Scoped to `.react-flow` rather than added to index.css, so the canvas needs no * Scoped to `.react-flow` rather than added to index.css, so the canvas needs no
* tokens of its own. The `colorMode` prop is passed all the same: React Flow * tokens of its own. The `colorMode` prop is passed all the same, so React
* stamps it on the wrapper as a class, and `.light` / `.dark` are the app's own * Flow's own defaults for anything not routed here follow the theme. The class
* token scopes — an unset one defaults to `light` and re-themes the whole canvas * it stamps on the wrapper cannot re-theme the canvas: the app's token scopes
* inside a dark shell. See the root DESIGN-GUIDELINES.md → Shells. * are `:root.dark` and `.theme-light` / `.theme-dark` (index.css).
*/ */
.react-flow { .react-flow {
+17 -9
View File
@@ -2,14 +2,19 @@
@import "tw-animate-css"; @import "tw-animate-css";
@import "./vendor.css"; @import "./vendor.css";
@custom-variant dark (&:is(.dark *)); /* `dark:` follows the nearest theme scope: inside the dark document or a
`.theme-dark` subtree, unless a `.theme-light` subtree sits in between. */
@custom-variant dark (&:is(:where(:root.dark, .theme-dark) *):not(
:where(:root.dark, .theme-dark) .theme-light *
));
/* /*
* Self-hosted font, duplicated verbatim across the fluksio and website repos (a * Self-hosted font, duplicated verbatim across the fluksio and website repos (a
* sync point like `lib/motion.ts`; see the root DESIGN-GUIDELINES.md, * sync point like `lib/motion.ts`; see the root DESIGN-GUIDELINES.md,
* Typography). Kept OUT of the byte-identical `@theme inline` / `:root` / * Typography). Kept OUT of the byte-identical `@theme inline` / `:root` /
* `.dark` blocks. Inter is used for both body (set on `body` in `@layer base`) * `.theme-dark` blocks. Inter is used for both body (set on `body` in
* and the display face applied via the `.font-display` class below. * `@layer base`) and the display face applied via the `.font-display` class
* below.
*/ */
@font-face { @font-face {
font-family: "Inter"; font-family: "Inter";
@@ -106,11 +111,13 @@
* `--primary`, the rest are hues that clear 3:1 against `--card` and stay * `--primary`, the rest are hues that clear 3:1 against `--card` and stay
* apart under colour blindness. See DESIGN-GUIDELINES.md → Colour tokens. * apart under colour blindness. See DESIGN-GUIDELINES.md → Colour tokens.
*/ */
/* `.light` is the symmetric half of `.dark` below: both are plain classes, so /* `.theme-light` and `.theme-dark` theme a subtree, which is what lets a
either themes a subtree as well as the whole document — which is what lets a dashboard forced to one theme sit inside a shell on the other. The document
dashboard forced to one theme sit inside a shell on the other. `:root` is is themed by the bare `.dark` the theme provider puts on `<html>`, matched
listed second so the parity grep keeps its anchor line. */ only there as `:root.dark`, so a library that stamps `light` or `dark` on its
.light, own wrapper cannot re-theme what is inside it. `:root` is listed second so
the parity grep keeps its anchor line. */
.theme-light,
:root { :root {
--background: #ffffff; --background: #ffffff;
--foreground: #333232; --foreground: #333232;
@@ -152,7 +159,8 @@
--chart-8: #b32474; --chart-8: #b32474;
} }
.dark { :root.dark,
.theme-dark {
--background: #0a0a0a; --background: #0a0a0a;
--foreground: #f5f5f5; --foreground: #f5f5f5;
--card: #1a1a1a; --card: #1a1a1a;