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 458af5afca)

Original-PR: https://github.com/LibreChat-AI/LibreChat/pull/16587
This commit is contained in:
Marco Beretta 2026-10-01 10:17:24 +02:00 • committed by Lia
parent 443d27ba32
commit f79ddcf2d6
11 changed files with 113 additions and 8 deletions

View file

@ -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 {

View file

@ -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;

View file

@ -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`

View file

@ -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;

View file

@ -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<string, string>) =>
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(
{

View file

@ -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',

View file

@ -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,/);
});

View file

@ -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',

View file

@ -461,6 +461,18 @@ const appearanceDecisions: Partial<Record<keyof IThemeAppearance, AppearanceDeci
reason:
'border: Click UI InputWrapper swaps the stroke to field.color.stroke.active on focus; keyboard focus adds a 1px ring in that color to hold the 2px focus floor',
},
focusRingWidth: {
value: '2px',
status: 'match',
reason:
'2px: Click UI draws keyboard focus as a literal `outline: 2px solid` in outline.default (BaseButton, IconButton, Dropdown and ContextMenu triggers); no token carries the width',
},
focusRingOffset: {
value: '2px',
status: 'match',
reason:
'2px: the same Click UI focus rules set a literal `outline-offset: 2px`; no token carries the offset',
},
};
const appearanceSources: Partial<Record<keyof IThemeAppearance, string>> = {

View file

@ -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;

View file

@ -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,