# Focus and Keyboard
Focus rings, skip links, tabindex, focus trapping, and the APG keyboard patterns.
## Focus rings
Style `:focus-visible`, not bare `:focus`. The browser shows `:focus-visible` for keyboard and assistive-tech focus but suppresses it for mouse clicks, where focus is already obvious. Never write `outline: none` or `focus:outline-none` without a visible replacement; that removes keyboard navigation for sighted keyboard users.
Prefer the browser's unmodified focus indicator: it adapts to platform and forced-color settings without the author predicting every background. Adding only `outline-offset` generally preserves that indicator. A custom `outline: 2px solid` with no color renders `currentColor`; that is not automatically accessible because the outline may cross colors different from the text's own background. So the preference order is:
```css
/* Best: keep the browser ring, just give it breathing room */
:focus-visible {
outline-offset: 2px;
}
/* Custom ring when the design requires one: use the project's verified token */
:focus-visible {
outline: 2px solid var(--focus-ring);
outline-offset: 2px;
}
```
```tsx
// Tailwind: use the project's focus token or established focus-ring utility
```
A custom focus indicator must meet the applicable project/WCAG target for visible area and change of contrast. Inspect the whole perimeter against every adjacent color it crosses, including component fills, page surfaces, images, gradients, and hover/selected states. A token, brand color, or `currentColor` is acceptable only when that rendered check passes.
In `forced-colors: active` (Windows High Contrast), keep the default color adjustment or explicitly use a system color such as `Highlight`; never freeze the authored color with `forced-color-adjust: none` unless the control remains perceivable.
Group focus styles with `:focus-within` when a wrapper should light up while an inner input has focus (e.g. a search box with an icon inside the border).
## Skip link
When repeated navigation or other repeated chrome precedes the primary content, the first focusable element is a "Skip to content" link targeting ``. Visually hide it until focused:
```css
.skip-link {
position: absolute;
inset-inline-start: -999px;
}
.skip-link:focus {
inset-inline-start: 16px;
top: 16px;
}
```
```html
Skip to content……
```
Give in-page anchor targets `scroll-margin-top` (e.g. `scroll-margin-top: 80px` under a sticky header) so the target isn't hidden when jumped to.
## tabindex rules
- `tabindex="0"`: adds an element to the natural tab order. Only for custom interactive elements that aren't natively focusable.
- `tabindex="-1"`: focusable via JavaScript only (`el.focus()`). Use for headings you move focus to, modal containers, and roving-tabindex members.
- Positive `tabindex`: never. It hijacks the tab order for the whole page; fix the DOM order instead.
### Roving tabindex
Composite widgets (tabs, menus, toolbars, radio groups) occupy a single Tab stop. The active item has `tabindex="0"`, all others `tabindex="-1"`, and arrow keys move both focus and the `0`:
```tsx
{tabs.map((tab, i) => (
))}
```
## Focus trapping and restoration
Modals must trap focus. The modern technique is the `inert` attribute on everything behind the dialog; it removes background content from the tab order and from assistive tech in one move:
```tsx
// On open
document.getElementById("app-content").inert = true;
const dialog = dialogRef.current;
(dialog.querySelector("[autofocus]") ??
dialog.querySelector("button, [href], input, select, textarea"))?.focus();
// On close
document.getElementById("app-content").inert = false;
triggerRef.current?.focus(); // always return focus to the element that opened it
```
Native `