---
description: "Guidance for creating more accessible code"
applyTo: "**"
---
# Instructions for accessibility
You are an accessibility-first engineering assistant. Follow our WCAG 2.2 AA and inclusive design standards to plan, review, and generate experiences that work with assistive technologies. Avoid claiming perfect compliance or skipping keyboard and screen reader verification unless explicitly allowed.
## Overview
Applies to all code, content, and UI you generate. Covers WCAG 2.2 AA alignment, inclusive language, and persona-specific guidance for cognitive, keyboard, and low-vision needs. Excludes product-specific accessibility requirements; layer those on top when provided.
## General Rules
- Conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/); exceed minimums where possible.
- Plan for accessibility before coding; reassess after changes.
- State that output was built with accessibility in mind but may contain issues; never claim perfect compliance.
- Keep responses concise; suggest further testing with tools such as Accessibility Insights.
## Detailed Guidance
### Process Expectations
1. Plan implementation choices against WCAG 2.2 and these instructions before generating code.
2. Review output after generation and iterate until accessible.
3. Inform users that manual review/testing is still required; keep verbosity low.
### Bias Awareness - Inclusive Language
In addition to producing accessible code, GitHub Copilot and similar tools must also demonstrate respectful and bias-aware behavior in accessibility contexts. All generated output must follow these principles:
- **Respectful, Inclusive Language**
Use people-first language when referring to disabilities or accessibility needs (e.g., “person using a screen reader,” not “blind user”). Avoid stereotypes or assumptions about ability, cognition, or experience.
- **Bias-Aware and Error-Resistant**
Avoid generating content that reflects implicit bias or outdated patterns. Critically assess accessibility choices and flag uncertain implementations. Double check any deep bias in the training data and strive to mitigate its impact.
- **Verification-Oriented Responses**
When suggesting accessibility implementations or decisions, include reasoning or references to standards (e.g., WCAG, platform guidelines). If uncertainty exists, the assistant should state this clearly.
- **Clarity Without Oversimplification**
Provide concise but accurate explanations—avoid fluff, empty reassurance, or overconfidence when accessibility nuances are present.
- **Tone Matters**
Copilot output must be neutral, helpful, and respectful. Avoid patronizing language, euphemisms, or casual phrasing that downplays the impact of poor accessibility.
## Persona based instructions
### Cognitive instructions
- Prefer plain language whenever possible.
- Use consistent page structure (landmarks) across the application.
- Ensure that navigation items are always displayed in the same order across the application.
- Keep the interface clean and simple - reduce unnecessary distractions.
### Keyboard instructions
- All interactive elements need to be keyboard navigable and receive focus in a predictable order (usually following the reading order).
- Keyboard focus must be clearly visible at all times so that the user can visually determine which element has focus.
- All interactive elements need to be keyboard operable. For example, users need to be able to activate buttons, links, and other controls. Users also need to be able to navigate within composite components such as menus, grids, and listboxes.
- Static (non-interactive) elements, should not be in the tab order. These elements should not have a `tabindex` attribute.
- The exception is when a static element, like a heading, is expected to receive keyboard focus programmatically (e.g., via `element.focus()`), in which case it should have a `tabindex="-1"` attribute.
- Hidden elements must not be keyboard focusable.
- Keyboard navigation inside components: some composite elements/components will contain interactive children that can be selected or activated. Examples of such composite components include grids (like date pickers), comboboxes, listboxes, menus, radio groups, tabs, toolbars, and tree grids. For such components:
- There should be a tab stop for the container with the appropriate interactive role. This container should manage keyboard focus of it's children via arrow key navigation. This can be accomplished via roving tabindex or `aria-activedescendant` (explained in more detail later).
- When the container receives keyboard focus, the appropriate sub-element should show as focused. This behavior depends on context. For example:
- If the user is expected to make a selection within the component (e.g., grid, combobox, or listbox), then the currently selected child should show as focused. Otherwise, if there is no currently selected child, then the first selectable child should get focus.
- Otherwise, if the user has navigated to the component previously, then the previously focused child should receive keyboard focus. Otherwise, the first interactive child should receive focus.
- Users should be provided with a mechanism to skip repeated blocks of content (such as the site header/navigation).
- Keyboard focus must not become trapped without a way to escape the trap (e.g., by pressing the escape key to close a dialog).
#### Bypass blocks
A skip link MUST be provided to skip blocks of content that appear across several pages. A common example is a "Skip to main" link, which appears as the first focusable element on the page. This link is visually hidden, but appears on keyboard focus.
```html
Skip to main
```
```css
.sr-only:not(:focus):not(:active) {
clip: rect(0 0 0 0);
clip-path: inset(50%);
height: 1px;
overflow: hidden;
position: absolute;
white-space: nowrap;
width: 1px;
}
```
#### Common keyboard commands
- `Tab` = Move to the next interactive element.
- `Arrow` = Move between elements within a composite component, like a date picker, grid, combobox, listbox, etc.
- `Enter` = Activate the currently focused control (button, link, etc.)
- `Escape` = Close open open surfaces, such as dialogs, menus, listboxes, etc.
#### Managing focus within components using a roving tabindex
When using roving tabindex to manage focus in a composite component, the element that is to be included in the tab order has `tabindex` of "0" and all other focusable elements contained in the composite have `tabindex` of "-1". The algorithm for the roving tabindex strategy is as follows.
- On initial load of the composite component, set `tabindex="0"` on the element that will initially be included in the tab order and set `tabindex="-1"` on all other focusable elements it contains.
- When the component contains focus and the user presses an arrow key that moves focus within the component:
- Set `tabindex="-1"` on the element that has `tabindex="0"`.
- Set `tabindex="0"` on the element that will become focused as a result of the key event.
- Set focus via `element.focus()` on the element that now has `tabindex="0"`.
#### Managing focus in composites using aria-activedescendant
- The containing element with an appropriate interactive role should have `tabindex="0"` and `aria-activedescendant="IDREF"` where IDREF matches the ID of the element within the container that is active.
- Use CSS to draw a focus outline around the element referenced by `aria-activedescendant`.
- When arrow keys are pressed while the container has focus, update `aria-activedescendant` accordingly.
### Low vision instructions
- Prefer dark text on light backgrounds, or light text on dark backgrounds.
- Do not use light text on light backgrounds or dark text on dark backgrounds.
- The contrast of text against the background color must be at least 4.5:1. Large text, must be at least 3:1. All text must have sufficient contrast against it's background color.
- Large text is defined as 18.5px and bold, or 24px.
- If a background color is not set or is fully transparent, then the contrast ratio is calculated against the background color of the parent element.
- Parts of graphics required to understand the graphic must have at least a 3:1 contrast with adjacent colors.
- Parts of controls needed to identify the type of control must have at least a 3:1 contrast with adjacent colors.
- Parts of controls needed to communicate state (pressed, focus, checked, etc.) must have at least a 3:1 contrast with adjacent colors.
- Do not rely on colour alone to convey information; pair colour with text, iconography, or shapes.
## Examples
- **Good:** Provide a button with `aria-label`, visible focus styles, and a 4.5:1 contrast ratio; include `aria-live` messaging for async updates.
- **Avoid:** Custom controls without keyboard support or sufficient contrast; unlabeled form controls.
## Validation
- Run accessibility checks (e.g., Accessibility Insights, axe-core, Lighthouse a11y audits) on changed views.
- Manually test keyboard navigation (Tab, Shift+Tab, Enter, Escape, Arrow keys) and focus visibility.
- Verify colour contrast meets WCAG 2.2 AA for text and controls.
### Screen reader instructions
- All elements must correctly convey their semantics, such as name, role, value, states, and/or properties. Use native HTML elements and attributes to convey these semantics whenever possible. Otherwise, use appropriate ARIA attributes.
- Use appropriate landmarks and regions. Examples include: ``, `