From bedfa785cba399efdf6ed9e5605a7531aaa57673 Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Fri, 25 Sep 2026 21:53:34 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=B2=20a11y:=20Form-Control=20Outlines?= =?UTF-8?q?=20Clear=203:1=20in=20Every=20Palette=20(#16377)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(client): Give form-control outlines their own 3:1 border role border-medium and border-light were the only visible edge on the shared form controls, and neither clears the WCAG 1.4.11 3:1 non-text floor in any palette. Raising them would also darken every separator and card edge, which the quieter dark borders deliberately keep one step off the page. border-control is a new theme role for the outline of a field, select trigger, dropdown, combobox trigger and OTP slot. Every bundled palette gives it a value that clears 3:1 on each canvas a form can sit on, the package ships the stock light and dark defaults so the outline holds before and without a theme definition, and a custom theme that paints its own medium border but not the new role keeps the outline it drew. semanticTokens.spec.ts holds the 3:1 floor for the role in all six modes. * fix(client): Keep a legacy control outline only when it clears 3:1 A theme that paints its own borders but predates border-control took its medium border as the control outline, and a quiet one left every field without a visible edge. The fallback now keeps that border only where it clears 3:1 on the theme's own canvases and otherwise uses the theme's secondary text, in both resolveTheme and the legacy applyTheme adapter. The palette scenarios spell out their tags so the runner can find them. * fix(client): Map legacy light and medium borders onto the control outline Controls drew border-light (fields, dropdowns, comboboxes) or border-medium (select, OTP) before border-control existed, so a stored theme that painted either, or the canvases they sit on, takes the first of its light border, its medium border, the bundled role or its secondary text that clears 3:1 on its own canvases. A theme that names none of them keeps the bundled role. * fix(client): Never settle for a control outline that fails when a better one exists Secondary and primary text join the candidates for a legacy theme's control outline, and when none clears 3:1 on the theme's canvases the one that comes closest is used rather than the secondary text by default. (cherry picked from commit 85910e97b4cdf3164e3812acba76c8aa5b29d3aa) Original-PR: https://github.com/LibreChat-AI/LibreChat/pull/16377 --- .../mock/scenarios/control-border.spec.ts | 166 ++++++++++++++++++ .../client/src/components/ControlCombobox.tsx | 2 +- packages/client/src/components/Dropdown.tsx | 4 +- packages/client/src/components/Field.ts | 8 +- packages/client/src/components/InputOTP.tsx | 2 +- .../client/src/components/SecretInput.tsx | 2 +- packages/client/src/components/Select.tsx | 2 +- .../client/src/components/SelectDropDown.tsx | 2 +- .../src/theme/context/ThemeProvider.tsx | 1 + packages/client/src/theme/controls.css | 18 ++ packages/client/src/theme/registry.spec.ts | 116 ++++++++++++ packages/client/src/theme/registry.ts | 70 ++++++++ .../client/src/theme/semanticTokens.spec.ts | 42 ++++- .../client/src/theme/themes/clickhouse.ts | 2 + packages/client/src/theme/themes/dark.ts | 1 + packages/client/src/theme/themes/default.ts | 1 + .../client/src/theme/themes/highContrast.ts | 2 + packages/client/src/theme/tokens.css | 1 + packages/client/src/theme/types/index.ts | 6 + .../client/src/theme/utils/applyTheme.spec.ts | 35 ++++ packages/client/src/theme/utils/applyTheme.ts | 6 + packages/client/src/theme/utils/contrast.ts | 23 +++ 22 files changed, 501 insertions(+), 11 deletions(-) create mode 100644 e2e/specs/mock/scenarios/control-border.spec.ts create mode 100644 packages/client/src/theme/controls.css create mode 100644 packages/client/src/theme/utils/contrast.ts diff --git a/e2e/specs/mock/scenarios/control-border.spec.ts b/e2e/specs/mock/scenarios/control-border.spec.ts new file mode 100644 index 0000000000..c9546a9837 --- /dev/null +++ b/e2e/specs/mock/scenarios/control-border.spec.ts @@ -0,0 +1,166 @@ +import { expect, test } from '@playwright/test'; +import type { Page } from '@playwright/test'; +import { clickHouseTheme } from '../../../../packages/client/src/theme/themes/clickhouse'; +import { darkTheme } from '../../../../packages/client/src/theme/themes/dark'; +import { themeValue } from './style.helpers'; + +/** + * A form control's outline is the only edge it has, so it owes the WCAG 1.4.11 + * 3:1 non-text floor against whatever the control is painted on. The separators + * are a different role and stay quiet. The probe is a real control, the week + * start `Dropdown` in the settings dialog, measured against the first opaque + * surface behind it, in every palette the app ships. + */ + +type Rgb = [number, number, number]; +type Appearance = 'light' | 'dark' | 'high-contrast-light' | 'high-contrast-dark'; + +const WCAG_NON_TEXT = 3; +const TRIGGER = '[data-testid="week-start-selector"]'; + +test.use({ viewport: { width: 1280, height: 800 } }); + +async function installAppearance(page: Page, appearance: Appearance, definition?: unknown) { + await page.addInitScript( + ([mode, stored]) => { + localStorage.setItem('color-theme', mode as string); + localStorage.setItem('navVisible', 'true'); + 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'); + } + }, + [appearance, definition ?? null] as [string, unknown], + ); +} + +function parseRgb(value: string): Rgb { + const channels = value.match(/\d+(\.\d+)?/g)?.map(Number) ?? []; + return [channels[0], channels[1], channels[2]]; +} + +function channel(value: number): number { + const c = value / 255; + return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4); +} + +function contrast(a: Rgb, b: Rgb): number { + const luminance = ([r, g, b]: Rgb) => + 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b); + const [lighter, darker] = [luminance(a), luminance(b)].sort((x, y) => y - x); + return (lighter + 0.05) / (darker + 0.05); +} + +async function openSettings(page: Page) { + await page.goto('/c/new'); + await page.getByTestId('nav-user').click(); + await page.getByRole('menuitem', { name: 'Settings' }).click(); + await expect(page.locator(TRIGGER)).toBeVisible({ timeout: 10000 }); +} + +/** The trigger's border colour and the first opaque background behind it. */ +function outlineAgainstSurface(page: Page): Promise<{ border: string; surface: string }> { + return page.locator(TRIGGER).evaluate((node) => { + const border = getComputedStyle(node).borderTopColor; + for (let el: Element | null = node.parentElement; el; el = el.parentElement) { + const background = getComputedStyle(el).backgroundColor; + if (background !== 'rgba(0, 0, 0, 0)' && background !== 'transparent') { + return { border, surface: background }; + } + } + return { border, surface: getComputedStyle(document.body).backgroundColor }; + }); +} + +/** Each tag is written out whole: the runner finds a scenario by its literal tag. */ +const PALETTES: Array<{ + name: string; + tag: string; + appearance: Appearance; + definition?: unknown; +}> = [ + { + name: 'default light', + tag: '@scenario:control-outline-clears-3-to-1-default-light', + appearance: 'light', + }, + { + name: 'default dark', + tag: '@scenario:control-outline-clears-3-to-1-default-dark', + appearance: 'dark', + }, + { + name: 'high contrast light', + tag: '@scenario:control-outline-clears-3-to-1-high-contrast-light', + appearance: 'high-contrast-light', + }, + { + name: 'high contrast dark', + tag: '@scenario:control-outline-clears-3-to-1-high-contrast-dark', + appearance: 'high-contrast-dark', + }, + { + name: 'clickhouse light', + tag: '@scenario:control-outline-clears-3-to-1-clickhouse-light', + appearance: 'light', + definition: clickHouseTheme, + }, + { + name: 'clickhouse dark', + tag: '@scenario:control-outline-clears-3-to-1-clickhouse-dark', + appearance: 'dark', + definition: clickHouseTheme, + }, +]; + +test.describe('form control outline', () => { + for (const palette of PALETTES) { + test(`a dropdown outline clears 3:1 in the ${palette.name} palette ${palette.tag}`, async ({ + page, + }) => { + await installAppearance(page, palette.appearance, palette.definition); + await openSettings(page); + + const { border, surface } = await outlineAgainstSurface(page); + const ratio = contrast(parseRgb(border), parseRgb(surface)); + + expect({ border, surface, clears: ratio >= WCAG_NON_TEXT }).toEqual({ + border, + surface, + clears: true, + }); + }); + } + + test('dark separators keep their quiet step while controls take their own role @scenario:dark-separators-stay-quiet', async ({ + page, + }) => { + await installAppearance(page, 'dark'); + await openSettings(page); + + expect(await themeValue(page, '--border-light')).toBe(darkTheme['rgb-border-light']); + expect(await themeValue(page, '--border-medium')).toBe(darkTheme['rgb-border-medium']); + expect(await themeValue(page, '--border-control')).toBe(darkTheme['rgb-border-control']); + }); + + test('a custom theme without the control role keeps the outline it drew @scenario:custom-theme-keeps-its-control-outline', async ({ + page, + }) => { + const definition = { + version: 1, + name: 'legacy-outline', + modes: { light: { colors: { 'rgb-border-medium': '70 90 110' } } }, + }; + await installAppearance(page, 'light', definition); + await openSettings(page); + + await expect(page.locator('html')).toHaveAttribute('data-theme', 'legacy-outline'); + expect(await themeValue(page, '--border-control')).toBe('70 90 110'); + expect((await outlineAgainstSurface(page)).border).toBe('rgb(70, 90, 110)'); + }); +}); diff --git a/packages/client/src/components/ControlCombobox.tsx b/packages/client/src/components/ControlCombobox.tsx index 48fdf54430..b26e74f3e3 100644 --- a/packages/client/src/components/ControlCombobox.tsx +++ b/packages/client/src/components/ControlCombobox.tsx @@ -197,7 +197,7 @@ function ControlCombobox({ className={cn( 'bg-surface-secondary flex items-center justify-center gap-2 rounded-full', 'text-text-primary hover:bg-surface-tertiary', - 'border-border-light border', + 'border-border-control border', isCollapsed ? 'h-9 w-9' : 'h-9 w-full rounded-xl px-3 py-2 text-sm', variant === 'field' && cn(fieldControl, 'hover:bg-surface-hover justify-start'), className, diff --git a/packages/client/src/components/Dropdown.tsx b/packages/client/src/components/Dropdown.tsx index b1269ed759..79e4495efe 100644 --- a/packages/client/src/components/Dropdown.tsx +++ b/packages/client/src/components/Dropdown.tsx @@ -150,7 +150,7 @@ const Dropdown: React.FC = ({ store={selectProps} disabled={disabled} className={cn( - 'border-border-light text-text-primary hover:bg-surface-hover hover:text-text-primary relative inline-flex items-center justify-between rounded-xl border bg-transparent py-2 text-sm transition-all duration-200 ease-in-out', + 'border-border-control text-text-primary hover:bg-surface-hover hover:text-text-primary relative inline-flex items-center justify-between rounded-xl border bg-transparent py-2 text-sm transition-all duration-200 ease-in-out', 'disabled:hover:text-text-primary disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-transparent', /** Horizontal padding would squeeze the icon, which flex-shrinks to fit */ iconOnly ? 'size-10 justify-center px-0' : 'w-fit gap-2 px-3', @@ -214,7 +214,7 @@ const Dropdown: React.FC = ({ autoSelect placeholder={searchPlaceholder} aria-label={searchPlaceholder} - className="border-border-light text-text-primary placeholder:text-text-secondary w-full rounded-lg border bg-inherit py-1.5 pr-2 pl-8 text-sm focus:outline-hidden" + className="border-border-control text-text-primary placeholder:text-text-secondary w-full rounded-lg border bg-inherit py-1.5 pr-2 pl-8 text-sm focus:outline-hidden" /> diff --git a/packages/client/src/components/Field.ts b/packages/client/src/components/Field.ts index c49dbd85e0..687d7faf33 100644 --- a/packages/client/src/components/Field.ts +++ b/packages/client/src/components/Field.ts @@ -1,11 +1,13 @@ /** - * The shared appearance of a form control — border, radius, type scale and focus + * The shared appearance of a form control: border, radius, type scale and focus * treatment. Owned here so `Input`, `Textarea`, and the select/combobox triggers * that have to sit beside them in a form cannot drift apart as the theme evolves. - * Callers compose a variant rather than restating these classes locally. + * Callers compose a variant rather than restating these classes locally. The + * border is `border-control` because it is the only edge the control has, so it + * owes the 3:1 non-text floor that the separator roles deliberately do not. */ export const fieldBase: string = - 'lc-field flex w-full rounded-lg border border-border-light px-3 py-2 text-sm text-text-primary placeholder:text-text-secondary focus-visible:border-border-medium focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-text-primary disabled:cursor-not-allowed disabled:opacity-50'; + 'lc-field flex w-full rounded-lg border border-border-control px-3 py-2 text-sm text-text-primary placeholder:text-text-secondary focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-text-primary disabled:cursor-not-allowed disabled:opacity-50'; /** A single-line control sized to sit in a form row, matching `Input`. */ export const fieldControl: string = `${fieldBase} h-10 bg-transparent`; diff --git a/packages/client/src/components/InputOTP.tsx b/packages/client/src/components/InputOTP.tsx index 61cc187230..5c894b3648 100644 --- a/packages/client/src/components/InputOTP.tsx +++ b/packages/client/src/components/InputOTP.tsx @@ -109,7 +109,7 @@ const InputOTPSlot: React.ForwardRefExoticComponent<
span]:line-clamp-1', + 'border-border-control ring-offset-surface-primary placeholder:text-text-secondary flex h-9 w-full items-center justify-between rounded-md border bg-transparent px-3 py-2 text-sm whitespace-nowrap shadow-xs focus:outline-hidden disabled:cursor-not-allowed disabled:opacity-50 [&>span]:line-clamp-1', 'hover:bg-surface-hover rounded-lg', className, )} diff --git a/packages/client/src/components/SelectDropDown.tsx b/packages/client/src/components/SelectDropDown.tsx index 1bbee715aa..5a7b7597b3 100644 --- a/packages/client/src/components/SelectDropDown.tsx +++ b/packages/client/src/components/SelectDropDown.tsx @@ -119,7 +119,7 @@ function SelectDropDown({ } }} className={cn( - 'border-border-light bg-surface-secondary focus-visible:ring-text-primary disabled:bg-surface-secondary relative flex w-full cursor-default flex-col rounded-md border py-2 pr-10 pl-3 text-left focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-hidden sm:text-sm', + 'border-border-control bg-surface-secondary focus-visible:ring-text-primary disabled:bg-surface-secondary relative flex w-full cursor-default flex-col rounded-md border py-2 pr-10 pl-3 text-left focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-hidden sm:text-sm', className ?? '', )} > diff --git a/packages/client/src/theme/context/ThemeProvider.tsx b/packages/client/src/theme/context/ThemeProvider.tsx index c2181adeec..82467fbe21 100644 --- a/packages/client/src/theme/context/ThemeProvider.tsx +++ b/packages/client/src/theme/context/ThemeProvider.tsx @@ -21,6 +21,7 @@ import { defaultTheme } from '../themes/default'; import { darkTheme } from '../themes/dark'; import '../highContrast.css'; import '../preflight.css'; +import '../controls.css'; const THEME_KEY = 'color-theme'; const THEME_COLORS_KEY = 'theme-colors'; diff --git a/packages/client/src/theme/controls.css b/packages/client/src/theme/controls.css new file mode 100644 index 0000000000..f409aeac63 --- /dev/null +++ b/packages/client/src/theme/controls.css @@ -0,0 +1,18 @@ +/** + * Stylesheet defaults for `--border-control`, the form-control boundary role. + * + * Every other color role is declared by the app stylesheet, but this one ships + * with the package so a consumer rendering `Input`, `Select` or `InputOTP` gets + * an outline that clears the WCAG 1.4.11 3:1 floor without restating it. + * `ThemeProvider` paints the registry value inline whenever a theme is active, + * which outranks these; they only cover the stock palette before and without a + * theme definition, and `semanticTokens.spec.ts` keeps them in step with + * `themes/default.ts` and `themes/dark.ts`. + */ +html { + --border-control: 133 133 133; +} + +.dark { + --border-control: 125 125 125; +} diff --git a/packages/client/src/theme/registry.spec.ts b/packages/client/src/theme/registry.spec.ts index c0aef7ea40..9bfbe8a063 100644 --- a/packages/client/src/theme/registry.spec.ts +++ b/packages/client/src/theme/registry.spec.ts @@ -250,6 +250,122 @@ describe('theme registry', () => { expect(resolved.colors['rgb-chart-widget-stroke']).toBe('50 51 52'); }); + it('keeps the control outline a theme drew with its own medium border', () => { + const resolved = resolveTheme( + { + version: 1, + name: 'legacy-control-border-reference', + modes: { dark: { colors: { 'rgb-border-medium': '150 151 152' } } }, + }, + 'dark', + ); + + expect(resolved.colors['rgb-border-control']).toBe('150 151 152'); + }); + + it('keeps a legacy light border that clears 3:1, the role most controls drew', () => { + const resolved = resolveTheme( + { + version: 1, + name: 'light-border-reference', + modes: { + light: { colors: { 'rgb-border-light': '110 111 112', 'rgb-border-medium': '90 91 92' } }, + }, + }, + 'light', + ); + + expect(resolved.colors['rgb-border-control']).toBe('110 111 112'); + }); + + it('passes over quiet legacy borders to the bundled outline where it clears 3:1', () => { + const resolved = resolveTheme( + { + version: 1, + name: 'quiet-border-reference', + modes: { + light: { + colors: { 'rgb-border-light': '245 245 245', 'rgb-border-medium': '240 240 240' }, + }, + }, + }, + 'light', + ); + + expect(resolved.colors['rgb-border-control']).toBe(defaultTheme['rgb-border-control']); + }); + + it('falls to the candidate that comes closest when nothing clears 3:1', () => { + const resolved = resolveTheme( + { + version: 1, + name: 'illegible-reference', + modes: { + light: { + colors: { + 'rgb-surface-primary': '140 140 140', + 'rgb-border-medium': '150 150 150', + 'rgb-text-secondary': '120 120 120', + 'rgb-text-primary': '90 90 90', + }, + }, + }, + }, + 'light', + ); + + expect(resolved.colors['rgb-border-control']).toBe('90 90 90'); + }); + + it('outlines controls with secondary text when no border clears its canvases', () => { + const resolved = resolveTheme( + { + version: 1, + name: 'mid-gray-canvas-reference', + modes: { + light: { + colors: { + 'rgb-surface-primary': '140 140 140', + 'rgb-border-medium': '150 150 150', + 'rgb-text-secondary': '20 21 22', + }, + }, + }, + }, + 'light', + ); + + expect(resolved.colors['rgb-border-control']).toBe('20 21 22'); + }); + + it('gives a theme that leaves every border alone the bundled control outline', () => { + const resolved = resolveTheme( + { + version: 1, + name: 'surface-only-reference', + modes: { light: { colors: { 'rgb-surface-primary': '250 250 250' } } }, + }, + 'light', + ); + + expect(resolved.colors['rgb-border-control']).toBe(defaultTheme['rgb-border-control']); + }); + + it('preserves an explicit control outline', () => { + const resolved = resolveTheme( + { + version: 1, + name: 'explicit-control-border-reference', + modes: { + dark: { colors: { 'rgb-border-medium': '60 61 62', 'rgb-border-control': '70 71 72' } }, + }, + }, + 'dark', + ); + + expect(resolved.colors['rgb-border-control']).toBe('70 71 72'); + }); + /** A deliberately different reference theme: it paints the whole seven-slot * scale and its own surfaces, so it predates slot 8 and cannot name it. * Falling back to the bundled indigo would paint a stop whose 3:1 mark diff --git a/packages/client/src/theme/registry.ts b/packages/client/src/theme/registry.ts index 1e3ddf82b4..6824ea4fb7 100644 --- a/packages/client/src/theme/registry.ts +++ b/packages/client/src/theme/registry.ts @@ -9,6 +9,7 @@ import type { ThemeMode, } from './types'; import { highContrastDarkTheme, highContrastLightTheme } from './themes/highContrast'; +import { contrastRatio } from './utils/contrast'; import { defaultTheme } from './themes/default'; import { darkTheme } from './themes/dark'; export const THEME_VERSION = 1 as const; @@ -46,6 +47,70 @@ export const MARK_NEIGHBOURHOOD: readonly (keyof IThemeRGB)[] = Object.freeze([ 'rgb-surface-tertiary', ]); +const NON_TEXT_CONTRAST = 3; + +/** The canvases a form control is painted on, which its outline is measured against. */ +const CONTROL_CANVASES: readonly (keyof IThemeRGB)[] = Object.freeze([ + 'rgb-surface-primary', + 'rgb-surface-secondary', + 'rgb-surface-tertiary', + 'rgb-surface-dialog', + 'rgb-surface-chat', +]); + +/** What a theme has to paint to have coordinated the outline its controls wore. */ +const CONTROL_SURROUNDINGS: readonly (keyof IThemeRGB)[] = Object.freeze([ + 'rgb-border-light', + 'rgb-border-medium', + ...CONTROL_CANVASES, +]); + +/** The outline's lowest contrast across the canvases a theme paints. */ +const weakestContrast = (outline: string, palette: IThemeRGB): number => + CONTROL_CANVASES.reduce((weakest, canvas) => { + const surface = palette[canvas]; + const ratio = surface === undefined ? undefined : contrastRatio(outline, surface); + return ratio === undefined ? weakest : Math.min(weakest, ratio); + }, Number.POSITIVE_INFINITY); + +/** + * The control outline for a stored or environment theme that predates + * `rgb-border-control`. Controls drew `border-light` (fields, dropdowns, + * comboboxes) or `border-medium` (select, OTP) before the role existed, so a + * theme that painted either, or the canvases they sit on, coordinated an + * outline this role now replaces. The first candidate that clears the 3:1 + * non-text floor on the theme's own canvases wins: its light border, its + * medium border, the bundled role, then its secondary and primary text. When + * none clears, the one that comes closest does. A theme that names none of + * these keeps the bundled role, and one that names the role keeps it as written. + * `base` is the bundled palette for the mode, which the theme is painted over. + */ +export function controlBorderFallback(colors: IThemeRGB, base: IThemeRGB = {}): string | undefined { + if (colors['rgb-border-control'] !== undefined) { + return undefined; + } + const ownsControlSurroundings = CONTROL_SURROUNDINGS.some((token) => colors[token] !== undefined); + if (!ownsControlSurroundings) { + return undefined; + } + const palette: IThemeRGB = { ...base, ...colors }; + const ranked = [ + colors['rgb-border-light'], + colors['rgb-border-medium'], + base['rgb-border-control'], + palette['rgb-text-secondary'], + palette['rgb-text-primary'], + ] + .filter((value): value is string => value !== undefined) + .map((outline) => ({ outline, contrast: weakestContrast(outline, palette) })); + const clearing = ranked.find(({ contrast }) => contrast >= NON_TEXT_CONTRAST); + const closest = ranked.reduce<(typeof ranked)[number] | undefined>( + (best, entry) => (best === undefined || entry.contrast > best.contrast ? entry : best), + undefined, + ); + return (clearing ?? closest)?.outline; +} + export const themeAppearanceProperties: Readonly< Record > = Object.freeze({ @@ -580,6 +645,10 @@ export function resolveTheme(theme: ThemeDefinition, mode: ThemeMode): ResolvedT customColors?.['rgb-border-light'] !== undefined ? { 'rgb-chart-widget-stroke': customColors['rgb-border-light'] } : {}; + const borderControlSource = + customColors != null ? controlBorderFallback(customColors, baseColors) : undefined; + const borderControlFallback = + borderControlSource !== undefined ? { 'rgb-border-control': borderControlSource } : {}; /** * Slot 8 arrived after the seven-slot scale shipped, so a stored or * environment theme that paints its own scale cannot name it. Filling the @@ -639,6 +708,7 @@ export function resolveTheme(theme: ThemeDefinition, mode: ThemeMode): ResolvedT ...textMutedFallback, ...chartWidgetSurfaceFallback, ...chartWidgetStrokeFallback, + ...borderControlFallback, ...seriesEightFallback, ...verifiedFallback, } as Required, diff --git a/packages/client/src/theme/semanticTokens.spec.ts b/packages/client/src/theme/semanticTokens.spec.ts index 5d41f54992..d1dc867930 100644 --- a/packages/client/src/theme/semanticTokens.spec.ts +++ b/packages/client/src/theme/semanticTokens.spec.ts @@ -129,7 +129,8 @@ describe('shared field and dropdown interaction styles', () => { * assert the primitives still compose it rather than restating the classes. */ const field = readFileSync(join(__dirname, '..', 'components', 'Field.ts'), 'utf8'); - expect(field).toMatch(/focus-visible:border-border-medium/); + expect(field).toMatch(/\bborder-border-control\b/); + expect(field).not.toMatch(/\bborder-border-(?:light|medium)\b/); expect(field).toMatch(/focus-visible:ring-2/); expect(field).toMatch(/focus-visible:ring-text-primary/); @@ -610,3 +611,42 @@ describe('syntax highlighting palette', () => { expect(hljsRules.filter((body) => /#[0-9a-f]{3,8}|hsla?\(/i.test(body))).toEqual([]); }); }); + +/** `border-control` is the only edge a form control has (`Field`, `Select`, + * `InputOTP`, the dropdown and combobox triggers), so it is a UI component + * boundary under WCAG 1.4.11 and owes 3:1 on every canvas a form can sit on. + * The separator roles are deliberately quieter and are not held to this. */ +const controlCanvases: Array = [...canvasSurfaces, 'rgb-surface-tertiary']; + +describe.each([ + ['default', defaultTheme], + ['dark', darkTheme], + ['high contrast light', highContrastLightTheme], + ['high contrast dark', highContrastDarkTheme], + ['clickhouse light', clickHouseLightTheme], + ['clickhouse dark', clickHouseDarkTheme], +])('%s control border', (_name, theme: IThemeRGB) => { + it('keeps the form-control outline at the 3:1 floor on every canvas', () => { + const outline = toRgb(theme, 'rgb-border-control'); + const failures = controlCanvases.flatMap((surface) => { + const ratio = contrast(outline, toRgb(theme, surface)); + return ratio < WCAG_MARK_MIN ? [`${surface}: ${ratio.toFixed(2)}:1`] : []; + }); + + expect(failures).toEqual([]); + }); +}); + +describe('control border defaults', () => { + /** The app stylesheet does not declare this role; the package does, so the + * stock palette has an outline before and without a theme definition. */ + it('keeps the package CSS in step with the runtime themes', () => { + const controls = readFileSync(join(__dirname, 'controls.css'), 'utf8'); + const declared = [...controls.matchAll(/--border-control:\s*([^;]+);/g)].map((match) => + match[1].trim(), + ); + + /** One declaration for `html`, one for `.dark`, and both must match. */ + expect(declared).toEqual([defaultTheme['rgb-border-control'], darkTheme['rgb-border-control']]); + }); +}); diff --git a/packages/client/src/theme/themes/clickhouse.ts b/packages/client/src/theme/themes/clickhouse.ts index bd4197a383..945e2cadfb 100644 --- a/packages/client/src/theme/themes/clickhouse.ts +++ b/packages/client/src/theme/themes/clickhouse.ts @@ -92,6 +92,7 @@ export const clickHouseLightTheme: IThemeRGB = { 'rgb-border-heavy': '179 182 189', // #b3b6bd (stroke.intense) 'rgb-border-xheavy': '128 134 145', // #808691 (palette.slate.500, two steps past stroke.intense #b3b6bd (2.03:1 on white)) 'rgb-border-destructive': '193 0 0', // #c10000 (palette.danger.600) + 'rgb-border-control': '128 134 145', // #808691 (palette.slate.500, 3.42:1 on background.muted) // Status colors 'rgb-status-success': '0 97 8', // #006108 (palette.success.800, one step past feedback.success.foreground #008a0b (4.27:1 on its fill)) @@ -211,6 +212,7 @@ export const clickHouseDarkTheme: IThemeRGB = { 'rgb-border-heavy': '65 65 65', // #414141 (stroke.intense) 'rgb-border-xheavy': '128 128 128', // #808080 (palette.neutral.500, three steps past stroke.intense #414141 (1.62:1 on the canvas)) 'rgb-border-destructive': '255 117 117', // #ff7575 (palette.danger.300) + 'rgb-border-control': '128 128 128', // #808080 (palette.neutral.500, 3.73:1 on background.muted) // Status colors 'rgb-status-success': '204 255 208', // #ccffd0 (feedback.success.foreground) diff --git a/packages/client/src/theme/themes/dark.ts b/packages/client/src/theme/themes/dark.ts index 95f5e2cc83..0278ebfccd 100644 --- a/packages/client/src/theme/themes/dark.ts +++ b/packages/client/src/theme/themes/dark.ts @@ -69,6 +69,7 @@ export const darkTheme: IThemeRGB = { 'rgb-border-heavy': '89 89 89', // #595959 (gray-500) 'rgb-border-xheavy': '153 150 150', // #999696 (gray-400) 'rgb-border-destructive': '239 68 68', // #ef4444 (red-500) + 'rgb-border-control': '125 125 125', // #7d7d7d, 3.25:1 on gray-700, the lightest canvas // Status colors 'rgb-status-success': '110 231 183', // #6ee7b7 (green-300) diff --git a/packages/client/src/theme/themes/default.ts b/packages/client/src/theme/themes/default.ts index 4f31f7b986..ca70e41553 100644 --- a/packages/client/src/theme/themes/default.ts +++ b/packages/client/src/theme/themes/default.ts @@ -69,6 +69,7 @@ export const defaultTheme: IThemeRGB = { 'rgb-border-heavy': '153 150 150', // #999696 (gray-400) 'rgb-border-xheavy': '89 89 89', // #595959 (gray-500) 'rgb-border-destructive': '220 38 38', // #dc2626 (red-600) + 'rgb-border-control': '133 133 133', // #858585, 3.12:1 on gray-100, the lightest canvas // Status colors 'rgb-status-success': '4 120 87', // #047857 (green-700) diff --git a/packages/client/src/theme/themes/highContrast.ts b/packages/client/src/theme/themes/highContrast.ts index 8a55b2cb92..93d220caab 100644 --- a/packages/client/src/theme/themes/highContrast.ts +++ b/packages/client/src/theme/themes/highContrast.ts @@ -105,6 +105,7 @@ export const highContrastLightTheme: IThemeRGB = { 'rgb-border-heavy': '0 0 0', // #000000 'rgb-border-xheavy': '0 0 0', // #000000 'rgb-border-destructive': '161 0 0', // #a10000 + 'rgb-border-control': '0 0 0', // #000000 // Status colors 'rgb-status-success': '0 92 46', // #005c2e @@ -246,6 +247,7 @@ export const highContrastDarkTheme: IThemeRGB = { 'rgb-border-heavy': '255 255 255', // #ffffff 'rgb-border-xheavy': '255 255 255', // #ffffff 'rgb-border-destructive': '255 143 143', // #ff8f8f + 'rgb-border-control': '255 255 255', // #ffffff // Status colors 'rgb-status-success': '127 240 179', // #7ff0b3 diff --git a/packages/client/src/theme/tokens.css b/packages/client/src/theme/tokens.css index c3ee6f0b36..5df3b7129a 100644 --- a/packages/client/src/theme/tokens.css +++ b/packages/client/src/theme/tokens.css @@ -75,6 +75,7 @@ --color-border-heavy: rgb(var(--border-heavy) / var(--border-heavy-alpha, 1)); --color-border-xheavy: rgb(var(--border-xheavy) / var(--border-xheavy-alpha, 1)); --color-border-destructive: rgb(var(--border-destructive)); + --color-border-control: rgb(var(--border-control)); /* status */ --color-status-success: rgb(var(--status-success)); diff --git a/packages/client/src/theme/types/index.ts b/packages/client/src/theme/types/index.ts index 5e297eadb0..7ba250a8fa 100644 --- a/packages/client/src/theme/types/index.ts +++ b/packages/client/src/theme/types/index.ts @@ -70,6 +70,10 @@ export interface IThemeRGB { 'rgb-border-heavy'?: string; 'rgb-border-xheavy'?: string; 'rgb-border-destructive'?: string; + /** The boundary of a form control (field, select trigger, OTP slot). Owes the + * 3:1 non-text floor on every canvas, so it is kept apart from the separator + * roles above, which stay quiet. */ + 'rgb-border-control'?: string; // Status colors 'rgb-status-success'?: string; @@ -210,6 +214,7 @@ export interface IThemeVariables { '--border-xheavy': string; '--border-xheavy-alpha': string; '--border-destructive': string; + '--border-control': string; '--status-success': string; '--status-success-subtle': string; '--status-success-border': string; @@ -311,6 +316,7 @@ export interface IThemeColors { 'border-heavy'?: string; 'border-xheavy'?: string; 'border-destructive'?: string; + 'border-control'?: string; 'status-success'?: string; 'status-success-subtle'?: string; 'status-success-border'?: string; diff --git a/packages/client/src/theme/utils/applyTheme.spec.ts b/packages/client/src/theme/utils/applyTheme.spec.ts index 3c05b0ee0f..e688872c97 100644 --- a/packages/client/src/theme/utils/applyTheme.spec.ts +++ b/packages/client/src/theme/utils/applyTheme.spec.ts @@ -18,6 +18,7 @@ const semanticProperties = [ '--chart-widget-surface', '--chart-widget-stroke', '--border-destructive', + '--border-control', '--status-success', '--status-success-subtle', '--status-success-border', @@ -331,6 +332,40 @@ describe('applyTheme', () => { expect(root.style.getPropertyValue('--chart-widget-stroke')).toBe('50 51 52'); }); + it('carries a legacy medium border onto the control outline', () => { + const root = document.documentElement; + + applyTheme({ 'rgb-border-medium': '60 61 62' }, root); + + expect(root.style.getPropertyValue('--border-control')).toBe('60 61 62'); + }); + + it('carries a legacy light border onto the control outline', () => { + const root = document.documentElement; + + applyTheme({ 'rgb-border-light': '110 111 112' }, root, defaultTheme); + + expect(root.style.getPropertyValue('--border-control')).toBe('110 111 112'); + }); + + it('keeps the bundled outline when the legacy borders are too quiet', () => { + const root = document.documentElement; + + applyTheme({ 'rgb-border-medium': '240 240 240' }, root, defaultTheme); + + expect(root.style.getPropertyValue('--border-control')).toBe( + defaultTheme['rgb-border-control'], + ); + }); + + it('leaves an explicit control outline alone', () => { + const root = document.documentElement; + + applyTheme({ 'rgb-border-medium': '60 61 62', 'rgb-border-control': '70 71 72' }, root); + + expect(root.style.getPropertyValue('--border-control')).toBe('70 71 72'); + }); + it('carries a legacy theme without a verified fill onto its success fill', () => { const root = document.documentElement; diff --git a/packages/client/src/theme/utils/applyTheme.ts b/packages/client/src/theme/utils/applyTheme.ts index eed64f5731..71aa8b72cf 100644 --- a/packages/client/src/theme/utils/applyTheme.ts +++ b/packages/client/src/theme/utils/applyTheme.ts @@ -1,5 +1,6 @@ import type { IThemeAppearance, IThemeBrands, IThemeRGB, ResolvedThemeDefinition } from '../types'; import { + controlBorderFallback, MARK_NEIGHBOURHOOD, themeAppearanceProperties, themeBrandTokens, @@ -70,6 +71,11 @@ function mapColors(colors: IThemeRGB, base?: IThemeRGB): Array<[string, string]> variables.push(['--chart-widget-stroke', colors['rgb-border-light']]); } + const legacyControlBorder = controlBorderFallback(colors, base); + if (legacyControlBorder !== undefined) { + variables.push(['--border-control', legacyControlBorder]); + } + /** * Same rule as `resolveTheme`: a theme that paints what the mark is measured * against coordinated the `status-success-strong` the mark wore before it had diff --git a/packages/client/src/theme/utils/contrast.ts b/packages/client/src/theme/utils/contrast.ts new file mode 100644 index 0000000000..f3a485b34e --- /dev/null +++ b/packages/client/src/theme/utils/contrast.ts @@ -0,0 +1,23 @@ +const channel = (value: number): number => { + const c = value / 255; + return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4); +}; + +function luminance(triplet: string): number | undefined { + const parts = triplet.trim().split(/\s+/).map(Number); + if (parts.length !== 3 || parts.some(Number.isNaN)) { + return undefined; + } + const [r, g, b] = parts; + return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b); +} + +/** WCAG contrast ratio between two `R G B` triplets; `undefined` when either is malformed. */ +export function contrastRatio(a: string, b: string): number | undefined { + const [first, second] = [luminance(a), luminance(b)]; + if (first === undefined || second === undefined) { + return undefined; + } + const [lighter, darker] = first > second ? [first, second] : [second, first]; + return (lighter + 0.05) / (darker + 0.05); +}