aboutsummaryrefslogtreecommitdiff
path: root/frontend-design/references
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-05-22 14:38:16 -0500
committerCraig Jennings <c@cjennings.net>2026-05-22 14:38:16 -0500
commit5f9b72d8311ff1b197ebdc5cff88255863bba15c (patch)
tree55957ee77367eef6571f8db19a50a246c85ec7cb /frontend-design/references
parentd93937c87d46f45f7c108712fc1b738eda77ae23 (diff)
downloadrulesets-5f9b72d8311ff1b197ebdc5cff88255863bba15c.tar.gz
rulesets-5f9b72d8311ff1b197ebdc5cff88255863bba15c.zip
docs(skills): gate accessibility and bound aesthetics in frontend-design
Two audit fixes. Accessibility moves from an optional reference for interactive components to a required WCAG 2.2 gate before handoff, covering keyboard, focus visibility and not-obscured, target size, contrast, reduced motion, labels, and semantics, for all frontend work. references/accessibility.md gained the backing detail and moved from 2.1 to 2.2. A new "creative but bounded" section keeps the maximalist directions as tools within guardrails: domain fit, readability, responsive stability, and no decoration that degrades the workflow.
Diffstat (limited to 'frontend-design/references')
-rw-r--r--frontend-design/references/accessibility.md13
1 files changed, 12 insertions, 1 deletions
diff --git a/frontend-design/references/accessibility.md b/frontend-design/references/accessibility.md
index 2b0ca66..96d45ff 100644
--- a/frontend-design/references/accessibility.md
+++ b/frontend-design/references/accessibility.md
@@ -1,6 +1,6 @@
# Accessibility
-Default target: WCAG 2.1 AA. For government, healthcare, finance, or other regulated contexts: AAA on specific criteria (verify with the user). Don't wait for a retrofit — apply during build.
+Default target: WCAG 2.2 AA. For government, healthcare, finance, or other regulated contexts: AAA on specific criteria (verify with the user). Don't wait for a retrofit — apply during build. This is a baseline for all frontend work, not just interactive components.
## Color Contrast
@@ -30,6 +30,15 @@ Default target: WCAG 2.1 AA. For government, healthcare, finance, or other regul
- Custom focus styles need ≥ 3:1 contrast against the adjacent background
- `:focus-visible` (not `:focus`) for keyboard-only focus rings — lets mouse clicks stay clean without losing keyboard clarity
+**Focus not obscured (WCAG 2.2):**
+- A focused element must not be fully hidden behind sticky headers, footers, or other overlays. Sticky top bars are the usual culprit — they cover the control the user just tabbed to.
+- `scroll-margin-top` on focusable elements, or `scroll-padding-top` on the scroll container, keeps the focused item clear of a fixed header.
+
+**Target size (WCAG 2.2):**
+- Interactive targets are at least 24x24 CSS pixels, or have enough surrounding spacing that a 24px circle centered on the target doesn't overlap a neighbor's.
+- Exceptions: inline links in a sentence, targets sized by the user agent, or an equivalent control of adequate size elsewhere on the page.
+- Dense or maximalist layouts don't get a pass — cramped tap targets fail on touch and for users with motor impairments.
+
## Semantic HTML
Prefer native elements over `<div role="button" tabIndex="0" onClick={...}>`. Native buttons, links, form controls, and landmarks come with keyboard behavior, focus management, and screen reader semantics for free.
@@ -88,6 +97,8 @@ Override per-element for critical motion (a loading spinner should still spin, j
- [ ] All text meets contrast (spot-check worst-case regions)
- [ ] Tab order matches visual order; all interactive elements reachable
- [ ] Visible focus ring on every focusable element
+- [ ] Focused element isn't hidden behind a sticky header/footer/overlay
+- [ ] Interactive targets meet the 24x24px minimum (or have clearing spacing)
- [ ] Semantic HTML used where a native element exists
- [ ] Icon-only buttons have `aria-label` or visible text
- [ ] Form fields have labels; errors are associated