amare/openspec/specs/web-accessibility/spec.md

web-accessibility Specification

Purpose

Define automated accessibility checks, semantic structure, keyboard operability, reduced motion, and console hygiene for public routes.

Requirements

Requirement: Public routes have no critical or serious accessibility issues

The system SHALL run automated accessibility checks on the public routes covered by the browser suite (SPEC §6.5, §13.8) after the Heritage Editorial motion enhancement. A critical or serious issue MUST fail the suite.

Scenario: Critical issue blocks the suite

• WHEN the automated accessibility check reports a critical or serious issue on a covered route
• THEN the browser suite MUST fail and report the offending rule and selector

Scenario: Covered routes are checked

• WHEN the accessibility suite runs
• THEN home, services listing, portfolio listing, case detail, about, contact, privacy and branded 404 MUST each be checked

Requirement: Public pages use accessible semantic structure

Public pages SHALL provide semantic landmarks, exactly one h1 per page, a coherent heading order, alt text on every content image and brand mark, and visible focus on interactive elements (SPEC §6.5).

Scenario: Single h1 per page

• WHEN any public page is rendered
• THEN exactly one h1 element MUST be present

Scenario: Landmarks are present

• WHEN any public page is rendered
• THEN header, main, nav and footer landmarks MUST be present

Scenario: Content images expose alt text

• WHEN a page renders a cover or gallery image
• THEN the alt attribute MUST contain the stored alt text

Scenario: Brand mark exposes accessible name

• WHEN the public header brand mark is rendered
• THEN it MUST expose an accessible name identifying Amare Assessoria

Requirement: Public pages are fully keyboard operable

Visitors SHALL be able to reach and activate every interactive element with the keyboard, including the mobile navigation disclosure when visible, with a visible focus indicator and a skip link to the main content.

Scenario: Keyboard reaches the primary CTA

• WHEN a visitor navigates the home with the Tab key
• THEN the primary CTA MUST receive focus with a visible indicator
• AND activating it with the keyboard MUST navigate to the contact route

Scenario: Skip link bypasses navigation

• WHEN a visitor focuses the first element of a public page
• THEN a skip link to the main content MUST be available

Scenario: Mobile menu is keyboard operable

• WHEN the mobile menu button is focused and activated with the keyboard
• THEN the navigation links MUST become reachable by subsequent Tab stops
• AND the button MUST expose the correct aria-expanded state

Requirement: Reduced motion preference is honored

The system SHALL suppress non-essential animation and transition when the user agent reports prefers-reduced-motion: reduce, including page openings, editorial reveals, image hover scales, interaction feedback and menu transitions. All affected content MUST render in its final visible and interactive state.

Scenario: Reduced motion disables transitions

• GIVEN the browser reports prefers-reduced-motion: reduce
• WHEN a public page is loaded
• THEN decorative transitions and animations MUST NOT run
• AND every motion target MUST be in its final visible and interactive state

Requirement: Public pages emit no console errors

Covered public routes SHALL load without JavaScript console errors in a real browser (SPEC §13.8, §19), including home, services listing, portfolio listing, case detail, about, contact, privacy, branded 404, and pages that load the mobile navigation or motion runtime.

Scenario: Console stays clean on covered routes

• WHEN a covered public route is loaded in the browser suite
• THEN the console MUST contain no error-level messages

Requirement: Motion enhancement failure does not hide or disable content

The public site SHALL remain readable, keyboard-operable, and interactive when JavaScript is disabled or IntersectionObserver is unavailable. Motion targets MUST default to their final state without relying on timeout recovery.

Scenario: JavaScript disabled keeps public page usable

• WHEN a visitor loads a public page with JavaScript disabled
• THEN headings, copy, navigation, CTAs, and form controls MUST be visible and operable

Scenario: Observer unavailable keeps reveals final

• WHEN the motion runtime executes without IntersectionObserver
• THEN reveal targets MUST remain in the final state