Focus
The focus indicator shows where the keyboard is. Every Luxen element draws it from the same three tokens, on :focus-visible, as an outline. Press Tab:
Anatomy
Ring
Field
| Part | Token | Default |
|---|---|---|
| Offset | --l-focus-ring-offset | 2px |
| Ring | --l-focus-ring-width, --l-focus-ring-color | 2px, #d9461f |
| Halo | --l-form-control-focus-halo-width | 3px, the ring color at 22% |
| Border | --l-form-control-border-width | 1px, in the ring color |
| Stroke | --l-form-control-focus-border-width | 2px, drawn inward over the border |
An invalid field takes --l-form-control-border-color-invalid for its halo, border and stroke.
Placements
Outside
Standalone controls. The gap keeps the ring legible.
Inside
Items set edge to edge. The ring never overlaps a neighbor or the panel edge.
Field
Text fields. Already a box: the border changes, no second box.
| Placement | Drawn | Used by |
|---|---|---|
| Outside | outline-offset: var(--l-focus-ring-offset) | Button, link, checkbox, radio, switch, tag, avatar, breadcrumb, slider thumb, rating star, carousel buttons |
| Inside | outline-offset: calc(var(--l-focus-ring-width) * -1) | Menu item, tabs, segmented control, disclosure summary, input stepper, carousel dots — items set edge to edge, where an outside ring would overlap the neighbor |
| Field | Border recolored, stroke inward, halo outside (box-shadow) | Input, textarea, select, l-input-group, l-select and its search box, l-combobox, l-prose-editor, the active l-input-otp cell |
| Active option | Inside ring, once the arrow keys moved it | l-select and l-combobox options |
In a listbox, DOM focus stays on the field and aria-activedescendant points at the option. The browser draws no focus there, so the option draws the ring itself when the keyboard moved it. A mouse-driven highlight stays a tint, like a hover.
Shown when it helps
:focus-visible lets the browser decide whether focus needs an indicator. Luxen never styles :focus alone.
| Focus arrives by | On | Indicator |
|---|---|---|
| Tab, arrow keys | Any control | Shown |
| Click or tap | Button, checkbox, tab, row | Hidden |
| Click or tap | Text field | Shown — typing follows |
Script (element.focus()) | Any control | Same as the element focus left |
When a script moves focus after a click and the user must see where it landed, force it: element.focus({ focusVisible: true }).
Contrast
The ring needs 3:1 against the surface it sits on. The default passes on Luxen surfaces in both schemes, not on every background you may put under it.
Tokens cascade: set the color on the container that changes the background.
.hero {
--l-focus-ring-color: white;
}Over a photo or a video no single color is safe. Use two — a light ring edged with dark (WCAG technique C40), as l-stories-viewer does for the buttons over its media:
.on-media :focus-visible {
outline: var(--l-focus-ring-width) solid white;
outline-offset: var(--l-focus-ring-offset);
box-shadow: 0 0 0 calc(var(--l-focus-ring-offset) + var(--l-focus-ring-width) * 2) black;
}Never hidden
A sticky header or bar can cover the element that just received focus. Reserve their height on the scroll container:
✗ Without
- Focused link
- Link
- Link
- Link
✓ With scroll-padding
- Focused link
- Link
- Link
- Link
scroll-padding keeps it clear. html {
scroll-padding-block: 4rem 5rem; /* sticky header, sticky bar */
}A container with overflow: hidden clips an outside ring. Give it padding of at least offset + width (4px by default).
Forced colors
In forced colors mode (Windows High Contrast), the browser drops every box-shadow and repaints outline in a system color. Luxen rings are outlines. A field's halo is a shadow, so fields add a transparent outline there for the system to repaint.
box-shadow
outline
Variants
Deliberate departures from the three tokens, each for a reason:
| Where | Variant | Why |
|---|---|---|
| Invalid field | Border, stroke and halo in --l-form-control-border-color-invalid | The error stays readable while the field is focused |
| Destructive menu item | Ring in --l-color-text-danger | Matches the item's own danger color |
| Tree row, prose editor toolbar button | Half the offset | Rows and buttons sit edge to edge; a full gap reaches the neighbor |
| Carousel buttons | Gap filled with --l-color-surface | They float over slides: the ring always sits next to a known color |
| Stories viewer buttons | Light ring edged with a dark band | They float over video, whose brightness is unknown |
l-input-otp, l-prose-editor | --cell-focus-color, --border-color-focus | Per-element color override, defaulting to --l-focus-ring-color |
Your own controls
Plain links, <button> and <summary> already take the ring from Luxen's base CSS (zero specificity: any rule of yours wins). For anything else, reuse the tokens so custom controls match:
.card-link:focus-visible {
outline: var(--l-focus-ring-width) solid var(--l-focus-ring-color);
outline-offset: var(--l-focus-ring-offset);
}
/* Inside a clipping container: flush with the inner edge */
.menu-row:focus-visible {
outline: var(--l-focus-ring-width) solid var(--l-focus-ring-color);
outline-offset: calc(var(--l-focus-ring-width) * -1);
}
/* Ring on a wrapper whose focusable child is visually hidden */
.swatch:has(input:focus-visible) {
outline: var(--l-focus-ring-width) solid var(--l-focus-ring-color);
outline-offset: var(--l-focus-ring-offset);
}Theming
Brand color
One value per scheme with light-dark() — 6.9:1 on white, 8.8:1 on the dark surface. For a neutral ring that follows the scheme and forced colors on its own, use the system color CanvasText.
:root {
--l-focus-ring-color: light-dark(oklch(48% 0.2 265), oklch(78% 0.14 265));
}One thickness everywhere
Point the field stroke at the ring width and drop the halo:
:root {
--l-focus-ring-width: 3px;
--l-form-control-focus-border-width: var(--l-focus-ring-width);
--l-form-control-focus-halo-width: 0;
}Crisp field
The stroke alone, no halo. The stroke is drawn inward: the field keeps its size and its text does not move.
:root {
--l-form-control-focus-halo-width: 0;
}Code
<div class="grid max-w-sm gap-4 [--l-form-control-focus-halo-width:0px]">
<l-form-field>
<label>Start date</label>
<input type="date" />
</l-form-field>
<l-form-field>
<label>Plan</label>
<select class="l-select">
<option>Starter</option>
<option>Pro</option>
</select>
</l-form-field>
<l-select
label="Team"
placeholder="Pick a team…"
>
<datalist>
<option value="design">Design</option>
<option value="dev">Development</option>
</datalist>
</l-select>
<l-combobox
label="Country"
placeholder="Search a country…"
>
<datalist>
<option value="fr">France</option>
<option value="de">Germany</option>
</datalist>
</l-combobox>
</div>Accessibility
Your part 8
Check these in your markupDon’t remove the outline without a substitute
Write
outline: noneonly with an equally visible replacementStyle
:focus-visible, not:focusDraw indicators with
outlineA
box-shadowalone disappears in forced colorsDon’t use a positive
tabindexCheck the ring color on every background
Test
--l-focus-ring-colorat 3:1 against every background it lands on, in light and darkScope it where a background differs
Clear sticky bars with
scroll-paddingSet it on the scroll container when the page has sticky headers or bars
It keeps focus clear of sticky content
Keep
--l-focus-ring-widthat2pxor moreWiden rings to
3pxfor AAA everywhereSet
--l-focus-ring-widthand--l-form-control-focus-border-widthto3pxInside rings and the field stroke otherwise cover less than Focus Appearance asks
WCAG2.4.13
Built in 6
Handled by the elementFocus ring on keyboard focus
Every focusable element shows an indicator
Focus ring contrast passes
The indicator has 3:1 against adjacent colors: 4.3:1 on white, 4.1:1 on the dark surface
Outside rings meet Focus Appearance
They are a solid 2px perimeter, the minimum area of Focus Appearance (AAA)
Inside rings and the field stroke are drawn inward, which covers less
WCAG2.4.13Adjacent rings never covered
Rings between items set edge to edge are drawn inside, so none is covered by a neighbor
Rings survive forced colors
Indicators are outlines, repainted by the system; never a
box-shadowaloneFocus follows DOM order
Composite widgets (tabs, tree, menu, radio group) are one Tab stop with arrow keys inside
Modals hold focus until
Escapecloses them; nothing else traps it
References
- Sara Soueidan — A guide to designing accessible, WCAG-conformant focus indicators — the reference walkthrough of area, contrast and outline vs box-shadow
- Patrick H. Lauke, TetraLogical — What’s new in WCAG 2.2 — Focus Not Obscured (2.4.11, 2.4.12) and Focus Appearance (2.4.13), and why the latter moved to AAA
- Adrian Roselli — Avoid default browser focus styles — why browser defaults fail contrast on many backgrounds
- Adrian Roselli — 2.4.11: adversarial conformance — why a sliver of visible control is not enough in practice
- GOV.UK Design System — Understanding focus state styles — a two-color indicator that contrasts on any background
- Eric Bailey, Piccalilli — Taking a shot at the double focus ring problem using modern CSS — two-color rings without extra markup
- Melanie Richards and Alison Maher, Microsoft Edge — Styling for Windows high contrast with forced colors — what forced colors overrides:
box-shadowreverted,outline-colorreplaced - WCAG techniques — C45
:focus-visible, C40 two-color indicator, C43scroll-padding, G195 author-supplied indicator, F78 failure: indicator removed - ARIA APG — Developing a keyboard interface — roving
tabindexandaria-activedescendantfor composite widgets - Selectors Level 4 — the :focus-visible pseudo-class — the heuristics browsers apply
Tokens
Color of the focus indicator, shown on :focus-visible: the ring around buttons, checkbox, radio, switch, tabs, tags, menu and tree items, links, and the border and halo of a focused text field. Keep at least 3:1 against every surface it lands on (WCAG 1.4.11) — the default gives 4.3:1 on white and 4.1:1 on the dark surface. Re-theme it on an ancestor to scope it, e.g. a lighter color over a photo.
Thickness of the :focus-visible ring drawn around interactive elements — buttons, checkbox, radio, switch, slider thumb, rating, tabs, tags, menu and tree items, toolbar and adornment buttons, close buttons, avatars, breadcrumb links. Keep it at 2px or more (WCAG 2.4.13). Rings set inside their element (items laid edge to edge — menu items, tabs, segmented control — where an outer ring would overlap a neighbor or the panel edge) grow inward with it. Text fields show focus on their border instead: see --l-form-control-focus-border-width, which a consumer can point at this token for one focus thickness everywhere.
Gap between an element and its :focus-visible ring, so the ring reads apart from the element's own border or fill. Rings set inside their element (menu items, tabs, segmented control, disclosure summary — items laid edge to edge, where an outer ring would overlap a neighbor or the panel edge) ignore it and sit flush inside the edge instead.
Width of the stroke drawn on a focused text field (input, textarea, native select, input group, l-select and its search box, l-combobox, l-prose-editor, the active l-input-otp cell), in the focus-ring color (the invalid color on an invalid field). Drawn inward from the outer edge, over the border: the control keeps its size and its text does not move. The default `2px` covers the 1px border and 1px more inside, so a focused field reads as clearly as a ring around a button. A value at or below --l-form-control-border-width adds nothing visible: the resting border alone takes the focus color.
Width of the soft halo around a focused text field — a ring of the focus-ring color (the invalid color on an invalid field) at 22% opacity, outside the border. Set to `0` for a crisp stroke with no halo, typically together with --l-form-control-focus-border-width. The color is mixed at the control, so a --l-focus-ring-color re-themed on an ancestor recolors the halo too.