.callout{padding:12px 16px;border-radius:6px;margin:16px 0;font-size:14px;line-height:1.6}
.callout strong{display:block;margin-bottom:6px}
.callout p{margin:4px 0 0}
.callout-placeholder{background:#F9FAFB;border:1px dashed #D1D5DB;border-left:4px solid #9CA3AF}
.do-dont{display:grid;grid-template-columns:1fr 1fr;gap:16px;margin:16px 0}
@media(max-width:640px){.do-dont{grid-template-columns:1fr}}
.do{border-left:4px solid #1A7F5A;padding:12px 16px;background:#F0FDF4;border-radius:0 4px 4px 0}
.dont{border-left:4px solid #B91C1C;padding:12px 16px;background:#FFF5F5;border-radius:0 4px 4px 0}
.do-dont-label{font-size:11px;font-weight:700;text-transform:uppercase;letter-spacing:.08em;margin-bottom:8px}
.do-label{color:#1A7F5A}
.dont-label{color:#B91C1C}
.do-dont-content p{margin:0;font-size:13px;line-height:1.6}
.spec-table{width:100%;border-collapse:collapse;font-size:13px;margin:12px 0}
.spec-table th{text-align:left;padding:8px 12px;background:#F3F4F6;font-weight:700;font-size:11px;text-transform:uppercase;letter-spacing:.04em;color:#6B7280;border-bottom:2px solid #E5E7EB}
.spec-table td{padding:8px 12px;border-bottom:1px solid #F3F4F6;vertical-align:top;line-height:1.5}
.prototype-note{font-size:12px;font-style:italic;color:#6B7280;border-left:2px solid #D1D5DB;padding-left:10px;margin:6px 0 12px}
.related-pages{margin-top:32px;padding-top:20px;border-top:1px solid #E5E7EB}
.related-pages h3{font-size:13px;font-weight:700;text-transform:uppercase;letter-spacing:.06em;color:#6B7280;margin-bottom:10px}

# Keyboard and focus

All functionality in Petrel must be operable using a keyboard alone. Every interactive control must have a visible focus indicator and a logical position in the tab sequence.
## Purpose

Keyboard accessibility enables users who cannot use a pointing device — due to motor disabilities, temporary injury, or workflow preference — to operate all Petrel functions. WPF provides built-in keyboard support for standard controls, but custom controls and complex layouts require explicit implementation.

## Who uses this guidance

UX designers defining interaction models, developers implementing WPF tab navigation and focus management, and reviewers validating keyboard-only workflows.

## Core requirements

- All interactive controls must be reachable by Tab and Shift+Tab.
- Focus must never be trapped inside a component (except modal dialogs, which have intentional focus trapping).
- Every focusable control must have a visible focus indicator that meets the 3:1 contrast ratio against adjacent colours.
- Focus must move to the first interactive element in a dialog when it opens.
- Focus must return to the trigger control when a dialog closes.
- Keyboard shortcuts must not conflict with Windows system shortcuts or Petrel application shortcuts.


## Tab order requirements

Tab order must follow the visual reading order of the interface: left to right, top to bottom. In dialogs with multiple columns, tab order should traverse each row fully before moving to the next, unless the dialog layout is clearly divided into independent zones.

Use WPF's `KeyboardNavigation.TabNavigation` attached property to control tab behaviour within containers. Set `TabIndex` explicitly when the default WPF order does not match the visual order.

## Focus indicator specifications

WPF default focus indicators are often invisible at smaller sizes. Petrel controls must use a custom focus visual that meets these requirements:

Property
Requirement
Minimum contrast ratio
3:1 against adjacent background
Indicator style
Outline (not fill-only)
Minimum area
Perimeter of the component
Prototype value. Confirm exact focus ring styling tokens with the Petrel design and development team.
## Do and Don't

DO
Test every dialog and pane in Petrel using keyboard only. Verify that Tab reaches every interactive control, that the tab order matches the visual layout, and that the focus ring is clearly visible on every control.
DON'T
Don't suppress the default WPF FocusVisualStyle without providing an equally visible replacement. Many Petrel dialogs currently have invisible focus indicators because the style was removed without a substitute.
## Modal dialog focus trapping

Modal dialogs must trap focus so that Tab and Shift+Tab cycle only through the controls within the dialog while it is open. This is required behaviour — it is not a keyboard trap in the WCAG sense because the user can always dismiss the dialog with Escape or the Cancel button.

## Petrel example

Petrel example placeholder
Screenshots showing correct and incorrect tab order in a Petrel property dialog will be added here.
## Testing guidance

To test keyboard accessibility: close all pointing devices, open the feature under test, and attempt to complete the workflow using only Tab, Shift+Tab, Arrow keys, Enter, Space, and Escape. Document any control that cannot be reached or activated.

### Related pages

Colour and contrast
— Focus indicator contrast requirements
Custom controls
— Keyboard patterns for non-standard controls
Dialogs
— Focus management in modal dialogs
Accessibility testing
— Keyboard testing checklists