Accessible by Default
Distinctive design is optional; accessible design is not. Apply this baseline to every screen, whatever the visual direction.
This skill covers the checks that most often break when agents restyle UI. It targets WCAG 2.2 Level AA, a widely used target in accessibility policies. It is a baseline, not a full conformance audit: automated and checklist review do not replace testing with assistive technology and with disabled users.
When to Use
- Building any page or component
- After applying a new visual direction, palette, or motion system
- Reviewing a PR that changes CSS, colors, interactive elements, or animation
Workflow
Step 1: Use Semantic HTML First
Native elements bring keyboard support, focus, and roles for free.
<!-- Before -->
<div class="btn"
<!-- After -->
<button type="button" draft</button>
- Links navigate (
<a href>); buttons act (<button>)
- One
<h1> per page and headings in order; use <main>, <nav>, <header>, <footer> landmarks
- Every input has a
<label> (visible, associated with for/id or by wrapping)
- Use ARIA only when no native element fits, and then follow the ARIA pattern fully
Step 2: Meet Contrast Thresholds (Unrounded)
| What |
Ratio |
WCAG 2.2 |
| Normal text |
4.5:1 |
1.4.3 Contrast (Minimum), AA |
| Large text: at least 18pt, or 14pt bold (about 24px / 18.5px) |
3:1 |
1.4.3, AA |
| UI component boundaries and states, meaningful graphics, focus indicators |
3:1 against adjacent colors |
1.4.11 Non-text Contrast, AA |
| Enhanced (optional) |
7:1 / 4.5:1 large |
1.4.6, AAA |
W3C states ratios are not rounded: 4.499:1 fails 4.5:1. Logos and purely decorative text are exempt. Check text over images or gradients at the lowest-contrast point.
Step 3: Keep Focus Visible and Unobscured
/* Never remove focus without replacing it */
:focus-visible {
outline: 3px solid var(--color-focus);
outline-offset: 2px;
}
- 2.4.7 Focus Visible (AA): keyboard focus must be visible.
outline: none without a replacement fails
- 2.4.11 Focus Not Obscured (Minimum) (AA, new in 2.2): a focused element must not be entirely hidden by author content such as sticky headers or cookie banners. Use
scroll-padding-top for sticky headers
- 2.4.13 Focus Appearance (AAA) defines a stronger indicator (area at least a 2 CSS px perimeter, 3:1 contrast); a useful target even if you only claim AA
:focus-visible is Baseline widely available and shows the ring for keyboard users without showing it on every mouse click
html { scroll-padding-top: 5rem; } /* height of the sticky header */
Step 4: Size Targets for Pointers and Fingers
2.5.8 Target Size (Minimum) (AA, new in 2.2): pointer targets at least 24 by 24 CSS pixels, unless an exception applies — enough spacing (a 24px circle centered on each target doesn't overlap another), an equivalent larger control on the page, inline links in text, user-agent default controls, or essential presentation. 2.5.5 (AAA) asks for 44 by 44.
.icon-button {
min-width: 44px; /* exceeds the 24px AA minimum; matches the AAA size */
min-height: 44px;
display: inline-grid;
place-items: center;
}
Step 5: Respect Motion Preferences
prefers-reduced-motion: reduce indicates the user asked to minimize non-essential motion (Baseline widely available)
- 2.2.2 Pause, Stop, Hide (A): auto-moving content that lasts more than 5 seconds alongside other content needs a way to pause, stop, or hide it
- 2.3.3 Animation from Interactions (AAA): interaction-triggered motion can be disabled unless essential
@media (prefers-reduced-motion: reduce) {
*, *::before, *::after {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
scroll-behavior: auto !important;
}
}
The blanket rule is a safety net. Better: design the reduced version deliberately (crossfade instead of slide, no parallax) so meaning conveyed by motion is not lost.
Step 6: Never Use Color Alone
1.4.1 Use of Color (A): color cannot be the only way to convey information, indicate an action, or distinguish an element.
<!-- Before: red border is the only error signal -->
<input class="border-red">
<!-- After -->
<label for="email">Email</label>
<input id="email" type="email" aria-invalid="true" aria-describedby="email-err">
<p id="email-err" class="error">Enter an email address like name@example.com</p>
Links inside body text should be distinguishable by more than color (underline is the simplest choice).
Step 7: Provide Text Alternatives
1.1.1 Non-text Content (A):
- Informative image:
alt describes the information, not the file ("Invoice total 336 EUR, due 30 November")
- Decorative image:
alt="" so screen readers skip it
- Icon-only button: accessible name via visible text,
aria-label, or visually hidden text
- Charts: a text summary or data table nearby
Step 8: Allow Zoom, Reflow, and Text Spacing
- 1.4.10 Reflow (AA): content works without two-direction scrolling at 320 CSS px wide (vertical content) — test at 400% zoom on a 1280px window
- 1.4.12 Text Spacing (AA): no loss of content when users raise line height to 1.5x, paragraph spacing 2x, letter spacing 0.12x, word spacing 0.16x
- Never set
maximum-scale=1 or user-scalable=no in the viewport meta
Step 9: Verify
| Check |
How |
| Keyboard |
Tab through the whole page: every control reachable, order logical, focus always visible, no traps |
| Contrast |
Contrast checker on every text/background and component pair, both themes |
| Zoom/reflow |
400% zoom at 1280px width; 320px viewport |
| Motion |
Turn on the OS reduced-motion setting and reload |
| Screen reader |
Spot-check headings, landmarks, form labels, and buttons with VoiceOver or NVDA |
| Automated |
Run an automated checker; treat it as a floor (it finds only some issues) |
Best Practices
- Native HTML before ARIA
- Contrast ratios are thresholds, checked unrounded, in every theme
- Replace focus styles; never just remove them
- Account for sticky UI hiding focused elements
- Size touch targets generously; 24px is the AA floor, not a goal
- Design the reduced-motion experience, don't only switch motion off
- Pair color with text, shape, or pattern
- Test with a keyboard on every change; it takes minutes
References
1---2name: accessible-by-default3description: |4 Non-negotiable accessibility baseline for any UI an agent builds or restyles: WCAG 2.2 AA contrast, visible focus, 24x24 target size, reduced motion, semantic HTML, text alternatives, and never relying on color alone. Includes a pass/fail checklist and code patterns.5 Use this skill when building or reviewing any user-facing UI, especially after a visual redesign, or when a distinctive style risks readability.6 Activate when: accessibility, a11y, WCAG, contrast, focus ring, keyboard navigation, reduced motion, alt text, screen reader, target size, semantic HTML.7metadata:8 source: https://skillmd.com/skills/latestaiagents/accessible-by-default9---1011# Accessible by Default1213**Distinctive design is optional; accessible design is not. Apply this baseline to every screen, whatever the visual direction.**1415This skill covers the checks that most often break when agents restyle UI. It targets WCAG 2.2 Level AA, a widely used target in accessibility policies. It is a baseline, not a full conformance audit: automated and checklist review do not replace testing with assistive technology and with disabled users.1617## When to Use1819- Building any page or component20- After applying a new visual direction, palette, or motion system21- Reviewing a PR that changes CSS, colors, interactive elements, or animation2223## Workflow2425### Step 1: Use Semantic HTML First2627Native elements bring keyboard support, focus, and roles for free.2829```html30<!-- Before -->31<div class="btn" onclick="save()">Save</div>3233<!-- After -->34<button type="button" onclick="save()">Save draft</button>35```3637- Links navigate (`<a href>`); buttons act (`<button>`)38- One `<h1>` per page and headings in order; use `<main>`, `<nav>`, `<header>`, `<footer>` landmarks39- Every input has a `<label>` (visible, associated with `for`/`id` or by wrapping)40- Use ARIA only when no native element fits, and then follow the ARIA pattern fully4142### Step 2: Meet Contrast Thresholds (Unrounded)4344| What | Ratio | WCAG 2.2 |45|------|-------|----------|46| Normal text | 4.5:1 | 1.4.3 Contrast (Minimum), AA |47| Large text: at least 18pt, or 14pt bold (about 24px / 18.5px) | 3:1 | 1.4.3, AA |48| UI component boundaries and states, meaningful graphics, focus indicators | 3:1 against adjacent colors | 1.4.11 Non-text Contrast, AA |49| Enhanced (optional) | 7:1 / 4.5:1 large | 1.4.6, AAA |5051W3C states ratios are not rounded: 4.499:1 fails 4.5:1. Logos and purely decorative text are exempt. Check text over images or gradients at the lowest-contrast point.5253### Step 3: Keep Focus Visible and Unobscured5455```css56/* Never remove focus without replacing it */57:focus-visible {58 outline: 3px solid var(--color-focus);59 outline-offset: 2px;60}61```6263- 2.4.7 Focus Visible (AA): keyboard focus must be visible. `outline: none` without a replacement fails64- 2.4.11 Focus Not Obscured (Minimum) (AA, new in 2.2): a focused element must not be entirely hidden by author content such as sticky headers or cookie banners. Use `scroll-padding-top` for sticky headers65- 2.4.13 Focus Appearance (AAA) defines a stronger indicator (area at least a 2 CSS px perimeter, 3:1 contrast); a useful target even if you only claim AA66- `:focus-visible` is Baseline widely available and shows the ring for keyboard users without showing it on every mouse click6768```css69html { scroll-padding-top: 5rem; } /* height of the sticky header */70```7172### Step 4: Size Targets for Pointers and Fingers73742.5.8 Target Size (Minimum) (AA, new in 2.2): pointer targets at least 24 by 24 CSS pixels, unless an exception applies — enough spacing (a 24px circle centered on each target doesn't overlap another), an equivalent larger control on the page, inline links in text, user-agent default controls, or essential presentation. 2.5.5 (AAA) asks for 44 by 44.7576```css77.icon-button {78 min-width: 44px; /* exceeds the 24px AA minimum; matches the AAA size */79 min-height: 44px;80 display: inline-grid;81 place-items: center;82}83```8485### Step 5: Respect Motion Preferences8687- `prefers-reduced-motion: reduce` indicates the user asked to minimize non-essential motion (Baseline widely available)88- 2.2.2 Pause, Stop, Hide (A): auto-moving content that lasts more than 5 seconds alongside other content needs a way to pause, stop, or hide it89- 2.3.3 Animation from Interactions (AAA): interaction-triggered motion can be disabled unless essential9091```css92@media (prefers-reduced-motion: reduce) {93 *, *::before, *::after {94 animation-duration: 0.01ms !important;95 animation-iteration-count: 1 !important;96 transition-duration: 0.01ms !important;97 scroll-behavior: auto !important;98 }99}100```101102The blanket rule is a safety net. Better: design the reduced version deliberately (crossfade instead of slide, no parallax) so meaning conveyed by motion is not lost.103104### Step 6: Never Use Color Alone1051061.4.1 Use of Color (A): color cannot be the only way to convey information, indicate an action, or distinguish an element.107108```html109<!-- Before: red border is the only error signal -->110<input class="border-red">111112<!-- After -->113<label for="email">Email</label>114<input id="email" type="email" aria-invalid="true" aria-describedby="email-err">115<p id="email-err" class="error">Enter an email address like name@example.com</p>116```117118Links inside body text should be distinguishable by more than color (underline is the simplest choice).119120### Step 7: Provide Text Alternatives1211221.1.1 Non-text Content (A):123124- Informative image: `alt` describes the information, not the file ("Invoice total 336 EUR, due 30 November")125- Decorative image: `alt=""` so screen readers skip it126- Icon-only button: accessible name via visible text, `aria-label`, or visually hidden text127- Charts: a text summary or data table nearby128129### Step 8: Allow Zoom, Reflow, and Text Spacing130131- 1.4.10 Reflow (AA): content works without two-direction scrolling at 320 CSS px wide (vertical content) — test at 400% zoom on a 1280px window132- 1.4.12 Text Spacing (AA): no loss of content when users raise line height to 1.5x, paragraph spacing 2x, letter spacing 0.12x, word spacing 0.16x133- Never set `maximum-scale=1` or `user-scalable=no` in the viewport meta134135### Step 9: Verify136137| Check | How |138|-------|-----|139| Keyboard | Tab through the whole page: every control reachable, order logical, focus always visible, no traps |140| Contrast | Contrast checker on every text/background and component pair, both themes |141| Zoom/reflow | 400% zoom at 1280px width; 320px viewport |142| Motion | Turn on the OS reduced-motion setting and reload |143| Screen reader | Spot-check headings, landmarks, form labels, and buttons with VoiceOver or NVDA |144| Automated | Run an automated checker; treat it as a floor (it finds only some issues) |145146## Best Practices1471481. Native HTML before ARIA1492. Contrast ratios are thresholds, checked unrounded, in every theme1503. Replace focus styles; never just remove them1514. Account for sticky UI hiding focused elements1525. Size touch targets generously; 24px is the AA floor, not a goal1536. Design the reduced-motion experience, don't only switch motion off1547. Pair color with text, shape, or pattern1558. Test with a keyboard on every change; it takes minutes156157## References158159- WCAG 2.2: https://www.w3.org/TR/WCAG22/160- Understanding 1.4.3 Contrast (Minimum): https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html161- Understanding 2.5.8 Target Size (Minimum): https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html162- Understanding 2.5.5 Target Size (Enhanced): https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html163- Understanding 1.4.10 Reflow: https://www.w3.org/WAI/WCAG22/Understanding/reflow.html164- MDN, `prefers-reduced-motion`: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion165- MDN, `:focus-visible`: https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible