astro-website/openspec/specs/wcag-responsive-ui/spec.md

Purpose

Define a minimum UX baseline for accessibility (WCAG 2.2 AA aligned) and responsive behavior for the site shell (navigation, focus, motion, typography, and background behavior).

Requirements

Requirement: Responsive layout baseline

The site MUST be responsive across common breakpoints (mobile, tablet, desktop, and large desktop) and MUST not exhibit broken layouts (overlapping content, horizontal scrolling, clipped navigation).

Scenario: Mobile viewport does not horizontally scroll

• WHEN the site is viewed on a small mobile viewport
• THEN content reflows to a single-column layout and the page does not require horizontal scrolling to read primary content

Scenario: Large viewport uses available space without visual artifacts

• WHEN the site is viewed on a large desktop viewport (ultrawide / high resolution)
• THEN the background and layout scale without visible abrupt gradient cutoffs or banding artifacts

Requirement: Collapsible primary navigation (hamburger menu)

The primary navigation MUST collapse into a hamburger menu on smaller viewports.

The menu toggle MUST be a <button> with:

• aria-controls referencing the menu container
• aria-expanded reflecting open/closed state
• an accessible label (e.g., aria-label="Open menu"/"Close menu" or equivalent)

When the menu is open, the menu items MUST be visible and keyboard navigable.

Scenario: Menu collapses on small viewport

• WHEN the viewport is below the mobile navigation breakpoint
• THEN the primary navigation renders in a collapsed state and can be opened via a hamburger toggle

Scenario: Menu toggle exposes accessible state

• WHEN the user toggles the menu open and closed
• THEN aria-expanded updates correctly and the toggle remains reachable via keyboard

Requirement: Keyboard and focus behavior baseline (WCAG 2.2 AA aligned)

The site MUST support keyboard navigation for all primary interactive elements.

The site MUST provide visible focus indication for keyboard users using :focus-visible styles.

For the mobile menu:

• pressing Escape MUST close the menu (when open)
• closing the menu MUST return focus to the menu toggle button

Scenario: Focus is visible on links and buttons

• WHEN a keyboard user tabs through the page
• THEN the focused element shows a visible focus indicator

Scenario: Escape closes the menu

• WHEN the menu is open and the user presses Escape
• THEN the menu closes and focus returns to the menu toggle

Requirement: Reduced motion support

The site MUST respect user motion preferences:

• if prefers-reduced-motion: reduce is set, animations/transitions for the menu and other UI elements MUST be reduced or disabled.

Scenario: Reduced motion disables menu animation

• WHEN the user's system preference is prefers-reduced-motion: reduce
• THEN opening/closing the menu does not use noticeable animation

Requirement: Typography baseline (display-friendly font)

The site MUST use a display-friendly font stack consistently across pages, including headings and navigation.

The site MUST ensure text remains readable:

• reasonable line height
• sufficient contrast against the background for primary text and focus indicators

Scenario: Font is applied consistently

• WHEN a user navigates between pages
• THEN typography (font family and basic scale) remains consistent