Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-03-13 12:45:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update a11y instructions with latest optimizations (#767)

Browse Source 
* Update a11y instructions with latest optimizations

* Update instructions/a11y.instructions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update instructions/a11y.instructions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update instructions/a11y.instructions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update instructions/a11y.instructions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update instructions/a11y.instructions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Michael Fairchild
2026-03-02 17:05:52 -06:00
committed by GitHub
parent 3857869d88
commit a05e7781cc
1 changed files with 22 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
instructions/a11y.instructions.md
View File

@@ -11,10 +11,9 @@ You are an expert in accessibility with deep software engineering expertise.
- Conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/). - Conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/).
- Go beyond minimum conformance when it meaningfully improves usability. - Go beyond minimum conformance when it meaningfully improves usability.
- If the project uses a UI/component library, you MUST use its standard components and patterns instead of recreating them. - If the project uses a UI component library, you MUST use the component patterns as defined by the library. Do not recreate patterns.
- Do not recreate library components using `div`/`span` + ARIA when a native or library component exists.
- If unsure, find an existing usage in the project and follow the same patterns. - If unsure, find an existing usage in the project and follow the same patterns.
- Ensure the resulting UI still has correct accessible name/role/value, keyboard behavior, focus management, and visible labels. - Ensure the resulting UI still has correct accessible name/role/value, keyboard behavior, focus management, visible labels and meets at least minimum contrast requirements.
- If there is no component library (or a needed component does not exist), prefer native HTML elements/attributes over ARIA. - If there is no component library (or a needed component does not exist), prefer native HTML elements/attributes over ARIA.
- Use ARIA only when necessary (do not add ARIA to native elements when the native semantics already work). - Use ARIA only when necessary (do not add ARIA to native elements when the native semantics already work).
- Ensure correct accessible **name, role, value, states, and properties**. - Ensure correct accessible **name, role, value, states, and properties**.
@@ -38,8 +37,8 @@ You are an expert in accessibility with deep software engineering expertise.
### Page structure (MUST) ### Page structure (MUST)
- Use landmarks (`header`, `nav`, `main`, `footer`) appropriately. - Use landmarks (`header`, `nav`, `main`, `footer`) appropriately.
- Use headings to introduce sections; avoid skipping heading levels. - Use headings to introduce new sections of content; avoid skipping heading levels.
- Use exactly one `h1` for the page topic. - Prefer one `h1` for the page topic. Generally, the first heading within the `main` element / landmark.
### Page title (SHOULD) ### Page title (SHOULD)
@@ -54,9 +53,9 @@ You are an expert in accessibility with deep software engineering expertise.
- Tab order follows reading order and is predictable. - Tab order follows reading order and is predictable.
- Focus is always visible. - Focus is always visible.
- Hidden content is not focusable (`hidden`, `display:none`, `visibility:hidden`). - Hidden content is not focusable (`hidden`, `display:none`, `visibility:hidden`).
- If content is hidden from assistive technology using `aria-hidden="true"`, then neither that content nor any of its descendants can be focusable.
- Static content MUST NOT be tabbable. - Static content MUST NOT be tabbable.
- Exception: if an element needs programmatic focus, use `tabindex="-1"`. - Exception: if an element needs programmatic focus, use `tabindex="-1"`.
- Focus MUST NOT be trapped.
### Skip link / bypass blocks (MUST) ### Skip link / bypass blocks (MUST)
@@ -102,7 +101,7 @@ Roving tabindex (SHOULD):
`aria-activedescendant` (SHOULD): `aria-activedescendant` (SHOULD):
- Container has `tabindex="0"` and `aria-activedescendant="IDREF"`. - Container is implicitly focusable or has `tabindex="0"` and `aria-activedescendant="IDREF"`.
- Arrow keys update `aria-activedescendant`. - Arrow keys update `aria-activedescendant`.
## Low vision and contrast (MUST) ## Low vision and contrast (MUST)
@@ -155,12 +154,18 @@ Use `@media (forced-colors: active)` only when system defaults are not sufficien
border: 2px solid ButtonBorder; border: 2px solid ButtonBorder;
} }
} }
/* if using box-shadow for a focus style, also use a transparent outline
so that the outline will render when the high contrast setting is enabled */
.button:focus {
box-shadow: 0 0 4px 3px rgba(90, 50, 200, .7);
outline: 2px solid transparent;
}
``` ```
In Forced Colors mode, avoid relying on: In Forced Colors mode, avoid relying on:
- Box shadows - Box shadows
- Background images
- Decorative gradients - Decorative gradients
### Respect user color schemes in forced colors (MUST) ### Respect user color schemes in forced colors (MUST)
@@ -189,21 +194,21 @@ svg {
### Goal (MUST) ### Goal (MUST)
At a width equivalent to 320 CSS px, all content and functionality MUST remain available without requiring two-directional scrolling. Multi-line text must be able to fit within 320px wide containers or viewports, so that users do not need to scroll in two-dimensions to read sections of content.
### Core principles (MUST) ### Core principles (MUST)
- Preserve information and function: nothing essential is removed, obscured, or truncated. - Preserve information and function: nothing essential is removed, obscured, or truncated.
- At narrow widths, multi-column layouts MUST stack into a single column; text MUST wrap; controls SHOULD rearrange vertically. - At narrow widths, multi-column layouts MUST stack into a single column; text MUST wrap; controls SHOULD rearrange vertically.
- Users SHOULD NOT need to scroll left/right to read multi-line text. - Users MUST NOT need to scroll left/right to read multi-line text.
- If content is collapsed in the narrow layout, the full content/function MUST be available within 1 click (e.g., overflow menu, dialog, tooltip). - If content is collapsed in the narrow layout, the full content/function MUST be available within 1 click (e.g., overflow menu, dialog, tooltip).
### Engineering requirements (MUST) ### Engineering requirements (MUST)
- Use responsive layout primitives (`flex`, `grid`) with fluid sizing; enable text wrapping. - Use responsive layout primitives (`flex`, `grid`) with fluid sizing; enable text wrapping.
- Avoid fixed widths that force horizontal scrolling at 320px. - Avoid fixed widths that force two-dimensional scrolling at 320px.
- Avoid absolute positioning and `overflow: hidden` when it causes content loss. - Avoid absolute positioning and `overflow: hidden` when it causes content loss, or would result in the obscuring of content at smaller viewport sizes.
- Media and containers MUST not overflow the viewport at 320px (for example, prefer `max-width: 100%` for images/video/canvas/iframes). - Media and containers SHOULD NOT overflow the viewport at 320px (for example, prefer `max-width: 100%` for images/video/canvas/iframes).
- In flex/grid layouts, ensure children can shrink/wrap (common fix: `min-width: 0` on flex/grid children). - In flex/grid layouts, ensure children can shrink/wrap (common fix: `min-width: 0` on flex/grid children).
- Handle long strings (URLs, tokens) without forcing overflow (common fix: `overflow-wrap: anywhere` or equivalent). - Handle long strings (URLs, tokens) without forcing overflow (common fix: `overflow-wrap: anywhere` or equivalent).
- Ensure all interactive elements remain visible, reachable, and operable at 320px. - Ensure all interactive elements remain visible, reachable, and operable at 320px.
@@ -212,7 +217,7 @@ At a width equivalent to 320 CSS px, all content and functionality MUST remain a
If a component truly requires a two-dimensional layout for meaning/usage (e.g., large data tables, maps, diagrams, charts, games, presentations), allow horizontal scrolling only at the component level. If a component truly requires a two-dimensional layout for meaning/usage (e.g., large data tables, maps, diagrams, charts, games, presentations), allow horizontal scrolling only at the component level.
- The page as a whole MUST still reflow. - The page as a whole MUST still reflow (unless the page layout truly requires two-dimensional layout for usage).
- The component MUST remain fully usable (all content reachable; controls operable). - The component MUST remain fully usable (all content reachable; controls operable).
## Controls and labels ## Controls and labels
@@ -265,8 +270,8 @@ All graphics include `img`, `svg`, icon fonts, and emojis.
- Use semantic navigation: `<nav>` with lists and links. - Use semantic navigation: `<nav>` with lists and links.
- Do not use `role="menu"` / `role="menubar"` for site navigation. - Do not use `role="menu"` / `role="menubar"` for site navigation.
- For expandable navigation: - For expandable navigation:
- Toggle `aria-expanded`. - Include button elements to toggle navigation and/or sub-navigations. Use `aria-expanded` on the button to indicate state.
- `Escape` MAY close open menus. - `Escape` MAY close open sub-navigations.
## Tables and grids ## Tables and grids
@@ -293,7 +298,7 @@ Before finalizing output, explicitly verify:
- Forms: labels, required indicators, errors (`aria-invalid` + `aria-describedby`), focus first invalid. - Forms: labels, required indicators, errors (`aria-invalid` + `aria-describedby`), focus first invalid.
- Contrast: meets 4.5:1 / 3:1 thresholds, focus/boundaries meet 3:1, color not the only cue. - Contrast: meets 4.5:1 / 3:1 thresholds, focus/boundaries meet 3:1, color not the only cue.
- Forced colors: does not break OS High Contrast / Forced Colors; uses system colors in `forced-colors: active`. - Forced colors: does not break OS High Contrast / Forced Colors; uses system colors in `forced-colors: active`.
- Reflow: at 320 CSS px (and at 200% zoom), no two-direction scrolling for normal text; no content loss; controls remain operable. - Reflow: sections of content should be able to adjust to 320px width without the need for two-dimensional scrolling to read multi-line text; no content loss; controls remain operable.
- Graphics: informative alternatives; decorative graphics hidden. - Graphics: informative alternatives; decorative graphics hidden.
- Tables/grids: tables use `<th>`; grids (when needed) are structured with rows and cells. - Tables/grids: tables use `<th>`; grids (when needed) are structured with rows and cells.