diff --git a/instructions/a11y.instructions.md b/instructions/a11y.instructions.md index 91a5bc02e..d6d3d2c1e 100644 --- a/instructions/a11y.instructions.md +++ b/instructions/a11y.instructions.md @@ -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/). - 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. - - Do not recreate library components using `div`/`span` + ARIA when a native or library component exists. +- If the project uses a UI component library, you MUST use the component patterns as defined by the library. Do not recreate 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. - 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**. @@ -38,8 +37,8 @@ You are an expert in accessibility with deep software engineering expertise. ### Page structure (MUST) - Use landmarks (`header`, `nav`, `main`, `footer`) appropriately. -- Use headings to introduce sections; avoid skipping heading levels. -- Use exactly one `h1` for the page topic. +- Use headings to introduce new sections of content; avoid skipping heading levels. +- Prefer one `h1` for the page topic. Generally, the first heading within the `main` element / landmark. ### 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. - Focus is always visible. - 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. - Exception: if an element needs programmatic focus, use `tabindex="-1"`. -- Focus MUST NOT be trapped. ### Skip link / bypass blocks (MUST) @@ -102,7 +101,7 @@ Roving tabindex (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`. ## 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; } } + +/* 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: - Box shadows -- Background images - Decorative gradients ### Respect user color schemes in forced colors (MUST) @@ -189,21 +194,21 @@ svg { ### 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) - 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. -- 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). ### Engineering requirements (MUST) - Use responsive layout primitives (`flex`, `grid`) with fluid sizing; enable text wrapping. -- Avoid fixed widths that force horizontal scrolling at 320px. -- Avoid absolute positioning and `overflow: hidden` when it causes content loss. -- Media and containers MUST not overflow the viewport at 320px (for example, prefer `max-width: 100%` for images/video/canvas/iframes). +- Avoid fixed widths that force two-dimensional scrolling at 320px. +- 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 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). - 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. @@ -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. -- 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). ## Controls and labels @@ -265,8 +270,8 @@ All graphics include `img`, `svg`, icon fonts, and emojis. - Use semantic navigation: `