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,