From f79ddcf2d6e3187baea6796b4c1f3dfd05b17585 Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Thu, 1 Oct 2026 10:17:24 +0200 Subject: [PATCH] feat: Focus ring width and offset theme roles (#16587) The global keyboard focus outline and the keyboard-modality text input outline read focusRingWidth and focusRingOffset instead of 2px literals. Both default to 2px, the ClickHouse theme sets Click UI's 2px and 2px, and the drift guard pins those values against Click UI's focus rules. (cherry picked from commit 458af5afcac7a449e6e90ba63d4f9af33f1f9774) Original-PR: https://github.com/LibreChat-AI/LibreChat/pull/16587 --- client/src/style.css | 16 ++++++---- .../mock/scenarios/focus-outline.spec.ts | 25 +++++++++++++++ packages/client/src/theme/README.md | 3 ++ packages/client/src/theme/defaults.css | 2 ++ packages/client/src/theme/registry.spec.ts | 32 +++++++++++++++++++ packages/client/src/theme/registry.ts | 4 +++ .../client/src/theme/semanticTokens.spec.ts | 9 +++++- .../client/src/theme/themes/clickhouse.ts | 4 +++ .../client/src/theme/themes/clickui.spec.ts | 12 +++++++ packages/client/src/theme/types/index.ts | 4 +++ packages/data-provider/src/theme.ts | 10 ++++++ 11 files changed, 113 insertions(+), 8 deletions(-) diff --git a/client/src/style.css b/client/src/style.css index 14816127bc..25833cf011 100644 --- a/client/src/style.css +++ b/client/src/style.css @@ -2037,23 +2037,25 @@ html[data-input-modality='keyboard'] ), textarea ):not(.lc-field):focus-visible { - outline: 2px solid rgb(var(--focus-control)) !important; - outline-offset: 2px !important; + outline: var(--theme-focus-ring-width, 2px) solid rgb(var(--focus-control)) !important; + outline-offset: var(--theme-focus-ring-offset, 2px) !important; } /* The focus outline is the theme's `focus-outline` role: black and white in the * default theme, and whatever a theme names, or its `ring-primary` when it names - * only that (see `resolveTheme`). The contrast modes keep their own 3px rule. */ + * only that (see `resolveTheme`). Its width and offset are the `focusRingWidth` + * and `focusRingOffset` roles, 2px each by default. The contrast modes keep their + * own 3px rule. */ @layer base { :focus-visible { - outline: 2px solid rgb(var(--focus-outline)); - outline-offset: 2px; + outline: var(--theme-focus-ring-width, 2px) solid rgb(var(--focus-outline)); + outline-offset: var(--theme-focus-ring-offset, 2px); } } .dark :focus-visible { - outline: 2px solid rgb(var(--focus-outline)); - outline-offset: 2px; + outline: var(--theme-focus-ring-width, 2px) solid rgb(var(--focus-outline)); + outline-offset: var(--theme-focus-ring-offset, 2px); } .popover-ui { diff --git a/e2e/specs/mock/scenarios/focus-outline.spec.ts b/e2e/specs/mock/scenarios/focus-outline.spec.ts index 3bf1b5085f..55fd00f9c9 100644 --- a/e2e/specs/mock/scenarios/focus-outline.spec.ts +++ b/e2e/specs/mock/scenarios/focus-outline.spec.ts @@ -49,6 +49,16 @@ const FOCUS_ROLE_THEME = { }, } as const; +/** Names the outline's width and offset, so an outline still drawn at the 2px literals shows. */ +const FOCUS_RING_SIZE_THEME = { + version: 1, + name: 'e2e-focus-ring-size', + modes: { + light: { appearance: { focusRingWidth: '3px', focusRingOffset: '1px' } }, + dark: { appearance: { focusRingWidth: '4px', focusRingOffset: '0' } }, + }, +} as const; + /** Leaves `rgb-ring-primary` to the default, which resolves to a gray too dim for a dark surface. */ const RINGLESS_THEME = { version: 1, @@ -243,6 +253,21 @@ test.describe('keyboard focus outline', () => { } }); + test('a theme that names the focus outline width and offset draws them in both modes @scenario:focus-outline-width-offset-roles', async ({ + page, + }) => { + const expected: Record<'light' | 'dark', Outline> = { + light: { color: 'rgb(0, 0, 0)', style: 'solid', width: '3px', offset: '1px' }, + dark: { color: 'rgb(255, 255, 255)', style: 'solid', width: '4px', offset: '0px' }, + }; + for (const mode of ['light', 'dark'] as const) { + const modePage = mode === 'light' ? page : await page.context().newPage(); + await openChat(modePage, mode, FOCUS_RING_SIZE_THEME); + + expect(await keyboardFocusOutline(modePage)).toEqual(expected[mode]); + } + }); + /** Each tag is written out whole: the runner finds a scenario by its literal tag. */ const RING_CASES: Array<{ title: string; diff --git a/packages/client/src/theme/README.md b/packages/client/src/theme/README.md index 183ee5f39f..f04c7aacbb 100644 --- a/packages/client/src/theme/README.md +++ b/packages/client/src/theme/README.md @@ -341,6 +341,9 @@ Each status family has a foreground, a `-subtle` background, a `-border`, and a keeps the half-opacity treatment every primitive carries. - `font-display` - Headings (`displayFontFamily`). Follows the theme's `fontFamily` when it names no display family. +- Keyboard focus outline - The global `:focus-visible` outline is drawn in + `focus-outline`, `focusRingWidth` wide and `focusRingOffset` off the edge (2px + each by default). The contrast modes keep their own 3px outline. - `border-border-field-focus` - A form field's edge while it holds focus, under `fieldFocusStyle: border`. Follows `focus-control` when a theme names only that. - Form fields and labels - `h-theme-field` (`fieldHeight`) sizes `Input`, `Dropdown` diff --git a/packages/client/src/theme/defaults.css b/packages/client/src/theme/defaults.css index 3bb5874db3..5a7d806cd3 100644 --- a/packages/client/src/theme/defaults.css +++ b/packages/client/src/theme/defaults.css @@ -213,6 +213,8 @@ html { --theme-field-height: 2.5rem; --theme-field-padding-y: 0.5rem; --theme-field-focus-style: ring; + --theme-focus-ring-width: 2px; + --theme-focus-ring-offset: 2px; --theme-label-size: var(--theme-text-sm, 0.875rem); --theme-label-leading: 1; --theme-label-font-weight: inherit; diff --git a/packages/client/src/theme/registry.spec.ts b/packages/client/src/theme/registry.spec.ts index 4132a22c49..d552d54aa7 100644 --- a/packages/client/src/theme/registry.spec.ts +++ b/packages/client/src/theme/registry.spec.ts @@ -948,6 +948,38 @@ describe('theme registry', () => { ].forEach((appearance) => expect(issues(appearance)).toHaveLength(1)); }); + it('keeps a 2px focus outline 2px off the edge unless a theme names its own', () => { + expect(defaultAppearance).toMatchObject({ focusRingWidth: '2px', focusRingOffset: '2px' }); + const { appearance } = resolveTheme( + { + version: 1, + name: 'focus-ring-reference', + modes: { dark: { appearance: { focusRingWidth: '0.25rem', focusRingOffset: '-1px' } } }, + }, + 'dark', + ); + expect(appearance).toMatchObject({ focusRingWidth: '0.25rem', focusRingOffset: '-1px' }); + }); + + it('rejects a focus outline that would vanish or is not a fixed length', () => { + const issues = (appearance: Record) => + validateThemeDefinition({ + version: 1, + name: 'focus-ring-values', + modes: { light: { appearance } }, + }); + + expect(issues({ focusRingWidth: '3px', focusRingOffset: '0' })).toEqual([]); + [ + { focusRingWidth: '0' }, + { focusRingWidth: '0px' }, + { focusRingWidth: '-2px' }, + { focusRingWidth: '2em' }, + { focusRingOffset: '2' }, + { focusRingOffset: 'calc(2px + 1px)' }, + ].forEach((appearance) => expect(issues(appearance)).toHaveLength(1)); + }); + it('does not count the dialog title ink among the surfaces the verified mark sits on', () => { const { colors } = resolveTheme( { diff --git a/packages/client/src/theme/registry.ts b/packages/client/src/theme/registry.ts index d7875ca8ec..d8282b6f8a 100644 --- a/packages/client/src/theme/registry.ts +++ b/packages/client/src/theme/registry.ts @@ -177,6 +177,8 @@ export const themeAppearanceProperties: Readonly< fieldHeight: '--theme-field-height', fieldPaddingY: '--theme-field-padding-y', fieldFocusStyle: '--theme-field-focus-style', + focusRingWidth: '--theme-focus-ring-width', + focusRingOffset: '--theme-focus-ring-offset', labelSize: '--theme-label-size', labelLeading: '--theme-label-leading', labelFontWeight: '--theme-label-font-weight', @@ -244,6 +246,8 @@ export const defaultAppearance: IThemeAppearance = Object.freeze({ fieldHeight: '2.5rem', fieldPaddingY: '0.5rem', fieldFocusStyle: 'ring', + focusRingWidth: '2px', + focusRingOffset: '2px', labelSize: '0.875rem', labelLeading: '1', labelFontWeight: 'inherit', diff --git a/packages/client/src/theme/semanticTokens.spec.ts b/packages/client/src/theme/semanticTokens.spec.ts index f3eaf4c2c0..14eb1f2c45 100644 --- a/packages/client/src/theme/semanticTokens.spec.ts +++ b/packages/client/src/theme/semanticTokens.spec.ts @@ -150,7 +150,14 @@ describe('shared field and dropdown interaction styles', () => { ); expect(appStyles).toMatch(/html\[data-input-modality='pointer'\]/); expect(appStyles).toMatch(/html\[data-input-modality='keyboard'\]/); - expect(appStyles).toMatch(/outline:\s*2px solid rgb\(var\(--focus-control\)\) !important;/); + expect(appStyles).toMatch( + /outline:\s*var\(--theme-focus-ring-width, 2px\) solid rgb\(var\(--focus-control\)\) !important;\s*outline-offset:\s*var\(--theme-focus-ring-offset, 2px\) !important;/, + ); + /** The global outline, in both its layered and its unlayered dark rule, reads the roles. */ + const roleOutline = + ':focus-visible \\{\\s*outline: var\\(--theme-focus-ring-width, 2px\\) solid rgb\\(var\\(--focus-outline\\)\\);\\s*outline-offset: var\\(--theme-focus-ring-offset, 2px\\);'; + expect(appStyles).toMatch(new RegExp(`@layer base \\{\\s*${roleOutline}`)); + expect(appStyles).toMatch(new RegExp(`\\.dark ${roleOutline}`)); expect(appStyles).not.toMatch(/textarea\s*\n\):hover,/); }); diff --git a/packages/client/src/theme/themes/clickhouse.ts b/packages/client/src/theme/themes/clickhouse.ts index 23b31c7b75..9dedaa143a 100644 --- a/packages/client/src/theme/themes/clickhouse.ts +++ b/packages/client/src/theme/themes/clickhouse.ts @@ -389,6 +389,10 @@ const clickHouseShape = { fieldHeight: '2rem', fieldPaddingY: '0.2813rem', // field.space.y fieldFocusStyle: 'border' as const, + /** Click UI's keyboard focus outline: 2px in `outline.default`, 2px off the edge + * (BaseButton.module.css, IconButton, Dropdown and ContextMenu triggers). */ + focusRingWidth: '2px', + focusRingOffset: '2px', /** `field.typography.label.default`: 500 0.75rem/1.5. */ labelSize: '0.75rem', labelLeading: '1.5', diff --git a/packages/client/src/theme/themes/clickui.spec.ts b/packages/client/src/theme/themes/clickui.spec.ts index e262e2988f..ddca61b362 100644 --- a/packages/client/src/theme/themes/clickui.spec.ts +++ b/packages/client/src/theme/themes/clickui.spec.ts @@ -461,6 +461,18 @@ const appearanceDecisions: Partial> = { diff --git a/packages/client/src/theme/types/index.ts b/packages/client/src/theme/types/index.ts index 7324181a75..865b66d67f 100644 --- a/packages/client/src/theme/types/index.ts +++ b/packages/client/src/theme/types/index.ts @@ -473,6 +473,10 @@ export interface IThemeAppearance { /** The field's vertical padding, which has to leave its line room inside `fieldHeight`. */ fieldPaddingY: string; fieldFocusStyle: 'ring' | 'border'; + /** The keyboard focus outline's width and its offset from the element's edge, apart from the + * heavier outline the contrast modes keep. */ + focusRingWidth: string; + focusRingOffset: string; /** A field label's size, leading and weight. The size follows `textSm` when a theme omits it, * and the default weight is `inherit`. */ labelSize: string; diff --git a/packages/data-provider/src/theme.ts b/packages/data-provider/src/theme.ts index 7ed20c48ab..329dfb0a5d 100644 --- a/packages/data-provider/src/theme.ts +++ b/packages/data-provider/src/theme.ts @@ -208,6 +208,13 @@ const isTableLength = (value: unknown): value is string => typeof value === 'string' && /^(0|\d*\.?\d+(px|rem))$/.test(value); const isSwitchLength = (value: unknown): value is string => typeof value === 'string' && /^\d*\.?\d+(px|rem)$/.test(value) && parseFloat(value) > 0; +/** + * A focus outline's width is a positive px or rem length (`isSwitchLength`), so the indicator + * never vanishes; its offset may also be zero or negative, drawing the outline on or inside the + * element's edge. + */ +const isFocusRingOffset = (value: unknown): value is string => + typeof value === 'string' && /^(0|-?\d*\.?\d+(px|rem))$/.test(value); /** A numeric CSS font weight, 1 to 1000, which is all a label weight needs. */ const isFontWeight = (value: unknown): value is string => typeof value === 'string' && @@ -335,6 +342,9 @@ const appearanceValidators = { fieldHeight: isLength, fieldPaddingY: isLength, fieldFocusStyle: (value: unknown) => value === 'ring' || value === 'border', + /** The keyboard focus outline's width and offset. */ + focusRingWidth: isSwitchLength, + focusRingOffset: isFocusRingOffset, /** A field label's size, leading and weight; `inherit` keeps the weight of the text around it. */ labelSize: isLength, labelLeading: isLineHeight,