Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🔲 a11y: Form-Control Outlines Clear 3:1 in Every Palette (#16377)

Marco Berettabedfa785cba3
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<DropdownProps> = ({
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<DropdownProps> = ({
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"
/>
</div>
</div>
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<
<div
ref={ref}
className={cn(
- 'border-border-medium relative flex h-11 w-11 items-center justify-center border-y border-r text-base shadow-xs transition-all first:rounded-l-xl first:border-l last:rounded-r-xl',
+ 'border-border-control relative flex h-11 w-11 items-center justify-center border-y border-r text-base shadow-xs transition-all first:rounded-l-xl first:border-l last:rounded-r-xl',
isActive && 'ring-text-primary z-10 ring-1',
className,
)}
diff --git a/packages/client/src/components/SecretInput.tsx b/packages/client/src/components/SecretInput.tsx
index 0703eb19e2..dabc37fdff 100644
--- a/packages/client/src/components/SecretInput.tsx
+++ b/packages/client/src/components/SecretInput.tsx
@@ -83,7 +83,7 @@ const SecretInput: React.ForwardRefExoticComponent<
id={id}
type={isVisible ? 'text' : 'password'}
className={cn(
- 'border-border-light placeholder:text-text-secondary flex h-10 w-full rounded-lg border bg-transparent py-2 pl-3 text-sm focus-visible:outline-hidden disabled:cursor-not-allowed disabled:opacity-50',
+ 'border-border-control placeholder:text-text-secondary flex h-10 w-full rounded-lg border bg-transparent py-2 pl-3 text-sm focus-visible:outline-hidden disabled:cursor-not-allowed disabled:opacity-50',
colorTransition && 'transition-colors',
className ?? '',
copyButton != null || showCopy ? 'pr-20' : 'pr-11',
diff --git a/packages/client/src/components/Select.tsx b/packages/client/src/components/Select.tsx
index 7bbd9cfee0..1c14b63bc1 100644
--- a/packages/client/src/components/Select.tsx
+++ b/packages/client/src/components/Select.tsx
@@ -27,7 +27,7 @@ const SelectTrigger: React.ForwardRefExoticComponent<
<SelectPrimitive.Trigger
ref={ref}
className={cn(
- 'border-border-medium 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',
+ '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<keyof IThemeAppearance, `--theme-${string}`>
> = 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<IThemeRGB>,
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<keyof IThemeRGB> = [...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);
+}