🌫️ feat: Give the Dialog Scrims Theme-Owned Opacity Roles (#16492)

* feat: Give the Dialog Scrims Theme-Owned Opacity Roles

The three dialog families carried their scrim alpha in each utility
(bg-surface-overlay/80, /90, /65), so a theme could recolor a scrim but
not set how much it dims. Add scrimOpacity, alertScrimOpacity and
modalScrimOpacity, exposed as bg-scrim, bg-scrim-alert and
bg-scrim-modal in the published tokens, defaulting to the 80%, 90% and
65% each family drew.

ClickHouse takes Click UI's 0.75 from dialog.color.opaqueBackground,
cited in the drift guard. A bundled scrim never lifts the page and, on
a light canvas, separates the dialog by 3:1, which is why ClickHouse
dark keeps a black overlay rather than Click UI's lighter gray.

* test: Read the Dialog Scrim Through Its Role Class in the Morph and Settings Scenarios

Both scenarios pinned the old bg-surface-overlay/80 literal: the morph
counted elements carrying it and Settings compared its scrim with a
probe of it, whose color-mix value serializes differently from the
role's rgb(). They now use bg-scrim, the class DIALOG_SCRIM_CLASS
exports.
This commit is contained in:
Marco Beretta 2026-09-29 16:13:14 +02:00 • committed by GitHub
parent 400e4549ca
commit 2d7133fcb1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
17 changed files with 269 additions and 11 deletions

View file

@ -334,6 +334,9 @@ html {
--theme-space-compact: 0.375rem;
--theme-space-normal: 0.75rem;
--theme-disabled-style: dim;
--theme-scrim-opacity: 0.8;
--theme-alert-scrim-opacity: 0.9;
--theme-modal-scrim-opacity: 0.65;
--theme-font-family: Inter, sans-serif;
--theme-display-font-family: Inter, sans-serif;
--theme-text-xs: 0.75rem;

View file

@ -8,7 +8,7 @@ import { getAccessToken, MOCK_ENDPOINTS, NEW_CHAT_PATH, requestJson } from '../h
* one class OGDialog's overlay and the morph's own backdrop both carry, which is
* what lets the count below tell a shared scrim from a second one.
*/
const SCRIM_CLASS = 'bg-surface-overlay/80';
const SCRIM_CLASS = 'bg-scrim';
type CreatedAgent = {
id: string;

View file

@ -0,0 +1,145 @@
import { expect, test } from '@playwright/test';
import type { Page } from '@playwright/test';
import { clickHouseTheme } from '../../../../packages/client/src/theme/themes/clickhouse';
import { NEW_CHAT_PATH } from '../helpers';
/**
* The dialog scrims' opacity roles. OGDialog, AlertDialog and Dialog lay `surface-overlay` over the
* page at `scrimOpacity`, `alertScrimOpacity` and `modalScrimOpacity`, which default to the 80%,
* 90% and 65% the families always drew. ClickHouse takes Click UI's 0.75 for all three, and a
* reference theme proves each family follows its own role. The probes carry the scrim classes
* the three overlays compose, so only the roles style them.
*/
type Mode = 'light' | 'dark';
type Scrims = { dialog: string; alert: string; modal: string };
const REFERENCE_THEME = {
version: 1,
name: 'e2e-scrim-opacity',
modes: {
light: {
colors: { 'rgb-surface-overlay': '10 20 30' },
appearance: { scrimOpacity: '0.5', alertScrimOpacity: '0.6', modalScrimOpacity: '0.7' },
},
dark: {
colors: { 'rgb-surface-overlay': '10 20 30' },
appearance: { scrimOpacity: '0.5', alertScrimOpacity: '0.6', modalScrimOpacity: '0.7' },
},
},
} as const;
async function openChat(page: Page, mode: Mode, definition?: { name: string }) {
await page.addInitScript(
([appearance, stored]) => {
localStorage.setItem('color-theme', appearance as string);
localStorage.removeItem('theme-colors');
localStorage.removeItem('theme-name');
if (stored) {
localStorage.setItem('theme-definition', JSON.stringify(stored));
localStorage.setItem('theme-source', 'definition');
} else {
localStorage.removeItem('theme-definition');
localStorage.removeItem('theme-source');
}
},
[mode, definition ?? null] as [string, unknown],
);
await page.goto(NEW_CHAT_PATH, { timeout: 15000 });
await expect(page.getByRole('textbox', { name: 'Message input' })).toBeVisible({
timeout: 30000,
});
const root = page.locator('html');
if (definition) {
await expect(root).toHaveAttribute('data-theme', definition.name);
} else {
await expect(root).not.toHaveAttribute('data-theme');
}
await expect(root).toHaveClass(mode === 'dark' ? /\bdark\b/ : /\blight\b/);
}
function scrims(page: Page): Promise<Scrims> {
return page.evaluate(() => {
const fill = (className: string) => {
const node = document.createElement('div');
node.className = className;
document.body.append(node);
const color = getComputedStyle(node).backgroundColor;
node.remove();
return color;
};
return {
dialog: fill('bg-scrim'),
alert: fill('bg-scrim-alert'),
modal: fill('bg-scrim-modal'),
};
});
}
/** Each tag is written out whole: the runner finds a scenario by its literal tag. */
const CASES: Array<{ title: string; mode: Mode; definition?: { name: string }; expected: Scrims }> =
[
{
title:
'the default light theme keeps each dialog family scrim @scenario:scrim-opacity-default-light-unchanged',
mode: 'light',
expected: {
dialog: 'rgba(89, 89, 89, 0.8)',
alert: 'rgba(89, 89, 89, 0.9)',
modal: 'rgba(89, 89, 89, 0.65)',
},
},
{
title:
'the default dark theme keeps each dialog family scrim @scenario:scrim-opacity-default-dark-unchanged',
mode: 'dark',
expected: {
dialog: 'rgba(0, 0, 0, 0.8)',
alert: 'rgba(0, 0, 0, 0.9)',
modal: 'rgba(0, 0, 0, 0.65)',
},
},
{
title:
'the ClickHouse light theme dims at Click UI scrim opacity @scenario:scrim-opacity-clickhouse-light',
mode: 'light',
definition: clickHouseTheme,
expected: {
dialog: 'rgba(21, 21, 21, 0.75)',
alert: 'rgba(21, 21, 21, 0.75)',
modal: 'rgba(21, 21, 21, 0.75)',
},
},
{
title:
'the ClickHouse dark theme dims at Click UI scrim opacity without lifting the page @scenario:scrim-opacity-clickhouse-dark',
mode: 'dark',
definition: clickHouseTheme,
expected: {
dialog: 'rgba(0, 0, 0, 0.75)',
alert: 'rgba(0, 0, 0, 0.75)',
modal: 'rgba(0, 0, 0, 0.75)',
},
},
{
title:
'a theme that names the scrim roles dims each dialog family by its own @scenario:scrim-opacity-follow-reference-theme',
mode: 'light',
definition: REFERENCE_THEME,
expected: {
dialog: 'rgba(10, 20, 30, 0.5)',
alert: 'rgba(10, 20, 30, 0.6)',
modal: 'rgba(10, 20, 30, 0.7)',
},
},
];
test.describe('dialog scrim opacity roles', () => {
for (const { title, mode, definition, expected } of CASES) {
test(title, async ({ page }) => {
await openChat(page, mode, definition);
expect(await scrims(page)).toEqual(expected);
});
}
});

View file

@ -265,7 +265,7 @@ test.describe('theme roles on prose, Settings, composer and model selector', ()
for (const definition of [null, clickHouseTheme]) {
for (const mode of MODES) {
await openChat(page, conversationId, mode, definition !== null);
const expectedScrim = await probeStyle(page, 'bg-surface-overlay/80', 'background-color');
const expectedScrim = await probeStyle(page, 'bg-scrim', 'background-color');
const settings = await openSettings(page);
expect(settings.scrim, 'the Settings scrim was not found').not.toBeNull();

View file

@ -39,7 +39,7 @@ const AlertDialogOverlay = React.forwardRef<
return (
<AlertDialogPrimitive.Overlay
className={cn(
'bg-surface-overlay/90 animate-in fade-in fixed inset-0 z-50 transition-opacity',
'bg-scrim-alert animate-in fade-in fixed inset-0 z-50 transition-opacity',
className,
)}
style={{ ...style, zIndex }}

View file

@ -29,7 +29,7 @@ const DialogOverlay = React.forwardRef<
>(({ className, ...props }, ref) => (
<DialogPrimitive.Overlay
className={cn(
'bg-surface-overlay/65 data-[state=closed]:animate-out data-[state=closed]:fade-out data-[state=open]:fade-in fixed inset-0 z-[999] transition-all duration-100',
'bg-scrim-modal data-[state=closed]:animate-out data-[state=closed]:fade-out data-[state=open]:fade-in fixed inset-0 z-[999] transition-all duration-100',
className ?? '',
)}
{...props}

View file

@ -139,8 +139,9 @@ DialogClose.displayName = DialogPrimitive.Close.displayName;
/**
* The scrim. `surface-overlay` is the theme's own scrim color, so a theme that
* redefines it moves every OGDialog with it; the opacity stays at 80% because
* that leaves the themes whose overlay is black (dark, and both high-contrast
* redefines it moves every OGDialog with it. The opacity is the theme's
* `scrimOpacity` role, which defaults to 80% because that leaves the themes
* whose overlay is black (dark, and both high-contrast
* modes) rendering exactly as before, and puts the light theme's gray scrim at
* 4.3:1 against the dialog it frames, past the 3:1 floor for a non-text
* boundary, and between the two other dialog families' scrims. Exported so a
@ -148,7 +149,7 @@ DialogClose.displayName = DialogPrimitive.Close.displayName;
* outlives the dialog's mount, consumes this appearance instead of restating it
* in feature code.
*/
export const DIALOG_SCRIM_CLASS = 'bg-surface-overlay/80';
export const DIALOG_SCRIM_CLASS = 'bg-scrim';
export const DialogOverlay: React.ForwardRefExoticComponent<
Omit<DialogPrimitive.DialogOverlayProps & React.RefAttributes<HTMLDivElement>, 'ref'> &

View file

@ -322,6 +322,10 @@ Each status family has a foreground, a `-subtle` background, a `-border`, and a
- `text-xs` to `text-2xl` - Sizes and line heights read `textXs`..`text2xl` and
`leadingXs`..`leading2xl` (app only, like the radius scale); the defaults are
Tailwind's own values.
- `bg-scrim` / `bg-scrim-alert` / `bg-scrim-modal` - The OGDialog, AlertDialog
and Dialog scrims: `surface-overlay` at the `scrimOpacity`,
`alertScrimOpacity` and `modalScrimOpacity` appearance roles (80%, 90% and
65% by default). A bundled scrim dims the page and never lifts it.
- `ring-focus-control` - The keyboard focus ring of the shared primitives
(`Checkbox`, `Switch`, `Field`, `IconButton` and their siblings). Defaults to
the primary text ink; a theme that names only `rgb-text-primary` rings its

View file

@ -452,6 +452,23 @@ describe('theme registry', () => {
]);
});
it('accepts a scrim opacity from 0 to 1 and rejects anything else', () => {
const withScrim = (scrimOpacity: string): ThemeDefinition => ({
version: 1,
name: 'scrim-reference',
modes: { dark: { appearance: { scrimOpacity } } },
});
expect(validateThemeDefinition(withScrim('0.75'))).toEqual([]);
expect(validateThemeDefinition(withScrim('1'))).toEqual([]);
expect(validateThemeDefinition(withScrim('1.5'))).toEqual([
'Invalid appearance value for scrimOpacity: 1.5',
]);
expect(validateThemeDefinition(withScrim('75%'))).toEqual([
'Invalid appearance value for scrimOpacity: 75%',
]);
});
it('draws the focus outline in the ring of a theme that predates the role', () => {
const resolved = resolveTheme(
{

View file

@ -152,6 +152,9 @@ export const themeAppearanceProperties: Readonly<
leadingLg: '--theme-text-lg-leading',
leadingXl: '--theme-text-xl-leading',
leading2xl: '--theme-text-2xl-leading',
scrimOpacity: '--theme-scrim-opacity',
alertScrimOpacity: '--theme-alert-scrim-opacity',
modalScrimOpacity: '--theme-modal-scrim-opacity',
elevationSurface: '--theme-elevation-surface',
shadow2xs: '--theme-shadow-2xs',
shadowXs: '--theme-shadow-xs',
@ -195,6 +198,9 @@ export const defaultAppearance: IThemeAppearance = Object.freeze({
leadingLg: 'calc(1.75 / 1.125)',
leadingXl: 'calc(1.75 / 1.25)',
leading2xl: 'calc(2 / 1.5)',
scrimOpacity: '0.8',
alertScrimOpacity: '0.9',
modalScrimOpacity: '0.65',
elevationSurface: '0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)',
shadow2xs: '0 1px rgb(0 0 0 / 0.05)',
shadowXs: '0 1px 2px 0 rgb(0 0 0 / 0.05)',

View file

@ -1,9 +1,10 @@
import { join } from 'node:path';
import { readFileSync } from 'node:fs';
import type { IThemeRGB } from './types';
import type { IThemeAppearance, IThemeRGB } from './types';
import { clickHouseDarkTheme, clickHouseLightTheme, clickHouseTheme } from './themes/clickhouse';
import { highContrastDarkTheme, highContrastLightTheme } from './themes/highContrast';
import { clickHouseDarkTheme, clickHouseLightTheme } from './themes/clickhouse';
import { defaultTheme } from './themes/default';
import { defaultAppearance } from './registry';
import { darkTheme } from './themes/dark';
const sharedComponents = [
@ -734,3 +735,47 @@ describe('state role defaults', () => {
});
});
});
/**
* The dialog scrims are `surface-overlay` at each family's opacity role. A scrim
* dims the page it covers and never lifts it (Click UI's dark scrim is a lighter
* gray, which the ClickHouse theme declines for that reason), and on a light
* canvas the dimmed page separates the dialog by the 3:1 a non-text boundary
* needs. Dark canvases draw that boundary with the dialog's own border instead.
*/
const scrimRoles = ['scrimOpacity', 'alertScrimOpacity', 'modalScrimOpacity'] as const;
const clickHouseAppearance = (mode: 'light' | 'dark'): IThemeAppearance => ({
...defaultAppearance,
...clickHouseTheme.modes[mode]?.appearance,
});
describe.each([
['default light', defaultTheme, defaultAppearance, true],
['default dark', darkTheme, defaultAppearance, false],
['high contrast light', highContrastLightTheme, defaultAppearance, true],
['high contrast dark', highContrastDarkTheme, defaultAppearance, false],
['clickhouse light', clickHouseLightTheme, clickHouseAppearance('light'), true],
['clickhouse dark', clickHouseDarkTheme, clickHouseAppearance('dark'), false],
])('%s scrims', (_name, theme: IThemeRGB, appearance: IThemeAppearance, lightCanvas: boolean) => {
it.each(scrimRoles)('%s dims the page without lifting it', (role) => {
const alpha = Number(appearance[role]);
const overlay = toRgb(theme, 'rgb-surface-overlay');
const page = toRgb(theme, 'rgb-surface-primary');
const dimmed = page.map(
(channel, index) => overlay[index] * alpha + channel * (1 - alpha),
) as Rgb;
expect(luminance(dimmed)).toBeLessThanOrEqual(luminance(page));
if (lightCanvas) {
expect(contrast(toRgb(theme, 'rgb-surface-dialog'), dimmed)).toBeGreaterThanOrEqual(
WCAG_MARK_MIN,
);
}
});
});
describe('scrim defaults', () => {
it('reproduce the opacities each dialog family drew before the roles', () => {
expect(scrimRoles.map((role) => defaultAppearance[role])).toEqual(['0.8', '0.9', '0.65']);
});
});

View file

@ -203,8 +203,8 @@ export const clickHouseDarkTheme: IThemeRGB = {
'rgb-surface-tertiary-alt': '50 50 50', // #323232 (palette.neutral.712)
'rgb-surface-dialog': '31 31 28', // #1f1f1c (background.default)
/** Not a Click UI value. Its dark scrim, dialog.color.opaqueBackground lch(40.731 0 none), is a
* #606060 gray that lifts the page instead of dimming it, and leaves the dialog surface under the
* 3:1 boundary the scrim gives it; black keeps the dark theme's scrim. */
* #606060 gray that lifts the page instead of dimming it. A bundled scrim never lifts the page
* (`semanticTokens.spec.ts`), so black keeps the dark scrim; the 0.75 alpha is Click UI's. */
'rgb-surface-overlay': '0 0 0', // #000000
'rgb-surface-submit': '250 255 105', // #faff69 (accent.default)
'rgb-surface-submit-hover': '253 255 163', // #fdffa3 (palette.brand.200)
@ -344,6 +344,9 @@ const clickHouseShape = {
shadowXs: '0 2px 2px 0 rgb(0 0 0 / 0.03)', // shadow.5
shadowSm: '0 2px 2px 0 rgb(0 0 0 / 0.03)', // shadow.5
controlHeight: '2rem', // genericMenu.panel.size.height
scrimOpacity: '0.75', // dialog.color.opaqueBackground alpha
alertScrimOpacity: '0.75', // dialog.color.opaqueBackground alpha
modalScrimOpacity: '0.75', // dialog.color.opaqueBackground alpha
/** Click UI paints disabled controls in fixed fills (`#dfdfdf` / `#414141`) rather than fading them. */
disabledStyle: 'fill' as const,
motionFast: '100ms', // transition.duration.medium, the step transition.default runs at

View file

@ -98,6 +98,7 @@
"click.button.iconButton.color.primary.background.active": "rgb(14.118% 14.118% 14.118%)",
"click.codeblock.darkMode.color.background.default": "#282828",
"click.codeblock.darkMode.color.text.default": "#ffffff",
"click.dialog.color.opaqueBackground.default": "lch(40.731 0 none / 0.75)",
"click.field.color.stroke.disabled": "#414141",
"click.genericMenu.panel.size.height": "2rem",
"click.global.color.text.danger": "#ffbaba",

View file

@ -282,6 +282,9 @@ const appearanceSources: Partial<Record<keyof IThemeAppearance, string>> = {
shadow2xl: 'shadow.1',
elevationSurface: 'shadow.1',
controlHeight: 'click.genericMenu.panel.size.height',
scrimOpacity: 'click.dialog.color.opaqueBackground.default',
alertScrimOpacity: 'click.dialog.color.opaqueBackground.default',
modalScrimOpacity: 'click.dialog.color.opaqueBackground.default',
motionFast: 'transition.duration.medium',
motionNormal: 'transition.duration.smooth',
};
@ -344,8 +347,18 @@ const normalizeShadow = (value: string) =>
const firstFamily = (value: string) => value.split(',')[0].trim();
/** How a Click UI appearance token compares with the theme value that cites it. */
const scrimKeys: ReadonlySet<keyof IThemeAppearance> = new Set([
'scrimOpacity',
'alertScrimOpacity',
'modalScrimOpacity',
]);
function comparable(key: keyof IThemeAppearance, raw: string | number): string {
const value = String(raw);
/** A scrim role is the alpha of Click UI's scrim color; the color itself is `surface-overlay`. */
if (scrimKeys.has(key)) {
return /^[\d.]+$/.test(value) ? String(Number(value)) : String(parseColor(value)[3]);
}
if (key.startsWith('shadow') || key === 'elevationSurface') {
return normalizeShadow(value);
}

View file

@ -41,6 +41,12 @@
--color-surface-tertiary-alt: rgb(var(--surface-tertiary-alt));
--color-surface-dialog: rgb(var(--surface-dialog));
--color-surface-overlay: rgb(var(--surface-overlay));
/* The dialog scrims: the overlay at the opacity each dialog family's appearance
* role sets (OGDialog, AlertDialog, Dialog), defaulting to the 80%, 90% and 65%
* the families have always drawn. */
--color-scrim: rgb(var(--surface-overlay) / var(--theme-scrim-opacity, 0.8));
--color-scrim-alert: rgb(var(--surface-overlay) / var(--theme-alert-scrim-opacity, 0.9));
--color-scrim-modal: rgb(var(--surface-overlay) / var(--theme-modal-scrim-opacity, 0.65));
--color-surface-submit: rgb(var(--surface-submit));
--color-surface-submit-hover: rgb(var(--surface-submit-hover));
--color-surface-destructive: rgb(var(--surface-destructive));

View file

@ -422,6 +422,10 @@ export interface IThemeAppearance {
leadingLg: string;
leadingXl: string;
leading2xl: string;
/** Opacity of `surface-overlay` under OGDialog, AlertDialog and Dialog, in that order. */
scrimOpacity: string;
alertScrimOpacity: string;
modalScrimOpacity: string;
elevationSurface: string;
shadow2xs: string;
shadowXs: string;

View file

@ -258,6 +258,12 @@ const isLineHeight = (value: unknown): value is string => {
const divisor = /\/\s*(\d*\.?\d+)\s*\)$/.exec(match[0]);
return divisor === null || Number(divisor[1]) > 0;
};
/** An alpha from 0 to 1, written the way CSS takes it in a color's alpha slot. */
const isOpacity = (value: unknown): value is string =>
typeof value === 'string' &&
/^(0|1|0?\.\d+|1\.0+)$/.test(value.trim()) &&
Number(value) >= 0 &&
Number(value) <= 1;
const isDuration = (value: unknown): value is string =>
typeof value === 'string' && cssDurationPattern.test(value);
@ -304,6 +310,10 @@ const appearanceValidators = {
leadingLg: isLineHeight,
leadingXl: isLineHeight,
leading2xl: isLineHeight,
/** How much of `surface-overlay` each dialog family's scrim lays over the page. */
scrimOpacity: isOpacity,
alertScrimOpacity: isOpacity,
modalScrimOpacity: isOpacity,
/** Released themes may hold `var()` here, so this role keeps its original, looser check. */
elevationSurface: (value: unknown) =>
typeof value === 'string' && value.trim().length > 0 && !/[;{}]|url\s*\(/i.test(value),