14 — Accessibility and Compliance

PRD Document · Savoy Signature Hotels — Multi-Site Headless Platform
Version: 1.0 · Date: 2026-03-04
Related docs: 05_Design_System_and_Theming.md, 07_Modules_and_Templates.md

1. Purpose

Savoy Signature’s platform must be inclusive and compliant with international usability standards. This document outlines the methodology to achieve, maintain, and test WCAG 2.1 Level AA compliance across the entire headless frontend.

2. WCAG 2.1 Level AA Requirements

Every module, template, and design system token must conform to the following core pillars.

2.1 Perceivable

Information and user interface components must be presentable to users in ways they can perceive.

Text Alternatives: All non-decorative images (e.g., in ResponsiveImage component), icons, and media have descriptive alt text. Background images containing crucial information possess visually hidden text (.sr-only).
Color Contrast: Foreground text and background colors meet the contrast ratio of 4.5:1 for normal text and 3:1 for large text (> 18pt or bold > 14pt). Verified directly in Figma and enforced via packages/themes.
Sensory Characteristics: Instructions do not rely solely on shape, color, size, or visual location (e.g., avoiding “Click the red button on the right”).

2.2 Operable

User interface components and navigation must be operable.

Keyboard Navigation: All interactive elements (links, buttons, form fields, sliders, carousels, accordions) are navigable using the Tab and Shift + Tab keys.
Focus States: A highly visible focus ring is applied globally. Forms must not hide the focus indicator.
_base.scss
```
*:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}
```
Skip to Content: A hidden link is present at the very top of the DOM (e.g., before the header) that becomes visible on focus. This allows keyboard users to bypass repetitive navigation.
```
<a href="#main-content" className="skip-link">Skip to main content</a>
```
Carousels & Sliders: Must include accessible controls. HeroSlider (M05) and OffersCarousel (M19) include a dedicated play/pause button if auto-playing. Users can swipe or arrow through them.

2.3 Understandable

Information and the operation of the user interface must be understandable.

Language Attribute: <html lang="pt"> (or en) changes dynamically based on the Next.js locale segment (see 10_MultiLanguage_and_i18n.md).
Form Labels: Forms (M17) explicitly associate <label> elements with their respective <input>, <select>, or <textarea> tags, primarily via htmlFor and id.
Error Identification: Invalid form submissions programmatically set aria-invalid="true" and aria-describedby="error-id" to alert screen readers of the specific error text. Validation messages are clear and instructional.
Predictable Behavior: Navigation menus (M01) behave consistently across pages. Opening a modal or dropdown shifts focus appropriately and traps it inside the dialog until dismissed.

2.4 Robust

Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies.

Semantic HTML: Use native HTML5 landmarks (<header>, <nav>, <main>, <section>, <article>, <footer>).
ARIA Attributes: aria-* tags are used only when native HTML semantics fall short (e.g., custom dropdowns, tabs, accordions).
Headings Structure: Ensure correct document outline per page. One <h1> per view, followed logically by <h2>, <h3>, etc. Umbraco Rich Text editors (M06) restrict heading levels to maintain structural integrity.

3. Assistive Technologies & Best Practices

3.1 Radix UI Primitives

To accelerate development and guarantee robust accessibility, complex interactive modules (Accordions, Dialogs/Modals, Tabs, Dropdown Menus, Navigation Menus) will utilize Radix UI primitives.

Benefit: Radix provides unstyled, accessible, and highly customizable React components. Focus management, keyboard orchestration, and ARIA roles are handled out-of-the-box.
Implementation: The ui package encapsulates these primitives and applies the Savoy Design System tokens via SCSS.

For dynamic state changes (e.g., adding an item to a booking cart or successful form submission), aria-live regions or Radix UI’s Announcer are utilized to alert assistive technologies without requiring a page reload or stealing focus.

4. Accessibility Testing Pipeline

Accessibility is verified at multiple stages of the SDLC (Software Development Life Cycle).

4.1 Development Stage

Linting: @axe-core/react runs in the local development server, outputting accessibility violations to the browser console.
ESLint Plugin: eslint-plugin-jsx-a11y ensures static React code adheres to accessibility rules (e.g., enforcing alt tags on images).

4.2 CI/CD Stage

openClaw AI QA Agent: The agentic AI runs an accessibility audit (using Playwright + axe-core) during the PR stage. Pull requests failing the WCAG 2.1 AA baseline are blocked from merging.
Lighthouse CI: Accessibility scoring is tracked over time. A score drop below 95/100 prevents deployment.

4.3 Editorial Stage (CMS)

Mandatory Alt Text: Umbraco’s Media Library requires editors to fill the altText field (or the alt field on the responsiveImageComposition) whenever uploading visual content. If the image is purely decorative, a dedicated “Is Decorative” toggle outputs alt="".
Heading Constraints: The TinyMCE Rich Text Editor limits users to H2, H3, and H4 to prevent them from misusing H1 (which is reserved for the page template/hero).

5. Third-Party Integrations

The accessibility of the complete user journey heavily relies on third-party widgets.

Navarino Booking Engine: The Bookpoint calendar widget (M03 - Booking Bar) must be audited. If it fails WCAG standards, custom CSS/JS wrappers will be created, or the vendor will be contacted for remediation.
Synxis Redirects: Once the user redirects to Synxis, accessibility falls under Sabre’s purview.

6. Acceptance Criteria

All interactive modules (Carousels, Accordions, Forms, Maps) pass axe-core audits with zero WCAG 2.1 AA critical violations.
Keyboard navigation is uninterrupted; focus is clearly visible and never trapped unexpectedly.
Screen readers properly announce active states, errors, and modal interactions.
The ui layer effectively leverages Radix UI for complex, accessible DOM patterns.
All 8 themes enforce the 4.5:1 text-to-background contrast ratio.
openClaw QA automated tests block PRs that introduce accessibility regressions.
Umbraco content editors cannot bypass mandatory alt text constraints.

Next document: 15_Security_and_Data_Protection.md