Accessibility Standards

This policy defines the accessibility baseline for the astro-agency theme. All pages, components, and content must conform to these standards before shipping. Accessibility is a release-blocking quality gate enforced by both automated tooling and manual review.

WCAG 2.2 AA Conformance Baseline

The theme shall conform to WCAG 2.2 Level AA (REQ-00081). This means every page must satisfy the success criteria across all four WCAG principles:

• Perceivable — content is presentable to all users, including those using assistive technologies.
• Operable — all interface components and navigation are keyboard-accessible.
• Understandable — information and UI behavior are predictable and legible.
• Robust — content is compatible with current and future assistive technologies.

WCAG 2.2 AA is the floor, not the ceiling. Where AAA conformance is achievable without trade-offs, prefer it.

Skip-to-Content Link

A skip-to-content link shall be provided on every page (REQ-00082). The link must be the first focusable element in the DOM, become visible on focus, and move keyboard focus to the <main> element. This gives keyboard and screen reader users a fast path past repetitive navigation.

Alternative Text

Missing alternative text shall generate warnings during the validation pipeline (REQ-00083). The rules:

• Every <img> must have an alt attribute.
• Decorative images use alt="" (empty string) — never omit the attribute entirely.
• Informative images must have concise, descriptive alt text that conveys the image’s purpose.
• Complex images (charts, diagrams) require extended descriptions via aria-describedby or adjacent text.

Alt text violations are surfaced by axe-core during npm run validate. Content authors are responsible for writing meaningful alt text; the build system catches missing attributes.

Color Contrast

Potential color contrast violations shall generate warnings (REQ-00084). Minimum contrast ratios follow WCAG 2.2 AA:

• Normal text (under 18pt / 14pt bold): 4.5:1 contrast ratio against background.
• Large text (18pt+ / 14pt+ bold): 3:1 contrast ratio against background.
• UI components and graphical objects: 3:1 contrast ratio against adjacent colors.

The design token system enforces contrast through curated semantic tokens (--st-*). Components must consume semantic tokens, never raw color values. When using color-mix() or opacity adjustments, verify the computed contrast manually — automated tools may not evaluate dynamic values.

Both light and dark mode must meet these ratios independently. The axe-core audit runs against both modes on showcase pages.

Reduced Motion Preferences

Reduced motion preferences shall be respected (REQ-00085). All CSS animations and transitions must be wrapped in a prefers-reduced-motion media query or use the theme’s motion tokens that automatically resolve to safe values.

When prefers-reduced-motion: reduce is active:

• Animations are eliminated or replaced with instant state changes.
• Scroll-driven effects are disabled.
• Auto-playing media pauses.

Do not assume reduced motion means no motion — instantaneous transitions (opacity, color) are acceptable.

Interactive Target Sizes

Interactive targets shall meet minimum size guidelines (REQ-00088). The target rules:

• Minimum interactive target size: 44x44 CSS pixels (WCAG 2.2 AA Level AAA target, adopted as project policy).
• Inline text links are exempt when surrounded by sufficient spacing.
• Touch targets on mobile layouts should be at least 48x48 CSS pixels where layout permits.

Use the semantic spacing tokens to maintain consistent target sizing across components.

ARIA Semantics and Relationships

Form validation shall implement correct ARIA relationships and semantics (REQ-00087). This requirement extends beyond forms to all interactive components:

• Use native HTML semantics first. Reach for ARIA only when native elements cannot express the required role or state.
• No ARIA is better than wrong ARIA. Incorrect role, aria-*, or tabindex values actively harm assistive technology users.
• Required ARIA patterns:
  • Forms: aria-describedby linking inputs to error messages, aria-invalid on fields with errors, aria-required on mandatory fields (REQ-00086, REQ-00087).
  • Navigation: aria-expanded on menu triggers, aria-current="page" on active links, role="navigation" with accessible labels.
  • Modals: role="dialog", aria-modal="true", aria-labelledby pointing to the dialog title.
  • Live regions: aria-live="polite" for status updates, aria-live="assertive" only for critical alerts.

Testing Expectations

Build processes shall fail for violations that would ship inaccessible interactive UI when deterministically detectable (REQ-00128). Testing is split into two tiers:

Automated testing (axe-core)

The npm run validate pipeline includes an axe-core audit that runs against showcase pages in both light and dark mode. Automated testing catches:

• Missing or empty alt text
• Insufficient color contrast (on static values)
• Missing form labels and ARIA attributes
• Incorrect heading hierarchy
• Missing landmark regions

Automated violations are build-blocking. The pipeline will not pass with unresolved axe errors.

Manual testing

Automated tools catch roughly 30-40% of accessibility issues. Manual testing covers the rest:

• Keyboard navigation — all interactive elements reachable and operable via keyboard. See the Keyboard Testing Checklist (DOC-00034) for the full procedure.
• Screen reader verification — content read in logical order, ARIA states announced correctly, dynamic updates communicated.
• Zoom and reflow — content usable at 200% zoom with no horizontal scrolling at 320px viewport width.
• Cognitive load — error messages are clear, instructions are visible before interaction, timeouts are generous or absent.

Manual verification is expected before any component is marked as complete. Plans include manual verification sections for keyboard and screen reader verification.

Exception Process

When a known accessibility violation cannot be resolved before shipping, the following process applies:

1. Document the violation. Record the axe rule ID (or WCAG success criterion), the affected component, and the reason the fix is blocked.
2. File a tracking issue. The violation must have a concrete remediation plan with a target milestone.
3. Get project owner approval. No exception ships without explicit sign-off from the project owner.
4. Suppress with justification. If the violation triggers an axe-core failure, add a targeted rule suppression with a code comment linking to the tracking issue. Blanket rule disabling is not permitted.
5. Revisit at next milestone. Exceptions are reviewed at each release checkpoint. Stale exceptions without active remediation plans are escalated.

Exceptions are the last resort. The default is to fix the violation before shipping.