From 970adf48535e882499f5e516b6252d18cb3fa5d3 Mon Sep 17 00:00:00 2001
From: Tom Boullay <tom@famille-boullay.fr>
Date: Sat, 30 May 2026 18:44:03 +0200
Subject: [PATCH] feat(a11y): WCAG AA polish on the site onboarding flow

- index.css: add visible :focus-visible rings for .site-card-button
  and .site-button so keyboard users can see where focus lives
- SiteCard: drop outline:none, add aria-pressed and aria-label so
  screen readers announce selection state
- SiteButton: add the .site-button class for the shared focus ring
- SiteDisclaimerScreen: keyboard skip via Enter / Space / Escape, a
  role="region" + aria-label wrapper and aria-live="polite" on the
  message; honour prefers-reduced-motion on the fade
- IntroVideoPlayer: role="region" with a skip hint in aria-label,
  preload="auto", and aria-hidden on the decorative caption span
---
 src/components/site/SiteButton.tsx           |  1 +
 src/components/site/SiteCard.tsx             | 20 +++++---------
 src/components/site/SiteDisclaimerScreen.tsx | 29 ++++++++++++++------
 src/components/ui/intro/IntroVideoPlayer.tsx | 22 +++++++--------
 src/index.css                                | 12 ++++++++
 5 files changed, 52 insertions(+), 32 deletions(-)

diff --git a/src/components/site/SiteButton.tsx b/src/components/site/SiteButton.tsx
index cee1f8a..f1ceb38 100644
--- a/src/components/site/SiteButton.tsx
+++ b/src/components/site/SiteButton.tsx
@@ -21,6 +21,7 @@ export function SiteButton({
       onMouseDown={() => setIsPressed(true)}
       onMouseUp={() => setIsPressed(false)}
       onMouseLeave={() => setIsPressed(false)}
+      className="site-button"
       style={{
         display: "inline-flex",
         padding: "12px 20px",
diff --git a/src/components/site/SiteCard.tsx b/src/components/site/SiteCard.tsx
index df2e1b3..97ae7d1 100644
--- a/src/components/site/SiteCard.tsx
+++ b/src/components/site/SiteCard.tsx
@@ -22,23 +22,18 @@ export function SiteCard({
     return "#b8b8b8";
   };
 
-  const getBorder = (): string => {
-    if (selected) return "3px solid #a8d5a2";
-    if (isSituation) return "3px solid rgba(255, 255, 255, 0.55)";
-    if (disabled) return "3px solid rgba(255, 255, 255, 0.55)";
-    return "3px solid rgba(255, 255, 255, 0.55)";
-  };
+  const borderColor = selected ? "#a8d5a2" : "rgba(255, 255, 255, 0.55)";
 
-  const getTextColor = (): string => {
-    if (disabled) return "rgba(77, 77, 77, 0.72)";
-    return "#4d4d4d";
-  };
+  const textColor = disabled ? "rgba(77, 77, 77, 0.72)" : "#4d4d4d";
 
   return (
     <button
       type="button"
       onClick={onSelect}
       disabled={disabled}
+      aria-pressed={selected}
+      aria-label={label}
+      className="site-card-button"
       style={{
         width: isSituation
           ? "clamp(220px, 24vw, 300px)"
@@ -46,21 +41,20 @@ export function SiteCard({
         height: isSituation
           ? "clamp(48px, 6vw, 60px)"
           : "clamp(140px, 18vw, 180px)",
-        border: getBorder(),
+        border: `3px solid ${borderColor}`,
         background: getBackground(),
         cursor: disabled ? "not-allowed" : "pointer",
         display: "flex",
         alignItems: "center",
         justifyContent: "center",
         transition: "all 0.15s ease",
-        outline: "none",
         flexShrink: 0,
       }}
     >
       {!imagePath && (
         <span
           style={{
-            color: getTextColor(),
+            color: textColor,
             fontSize: isSituation
               ? "clamp(14px, 1.8vw, 22px)"
               : "clamp(10px, 1.5vw, 14px)",
diff --git a/src/components/site/SiteDisclaimerScreen.tsx b/src/components/site/SiteDisclaimerScreen.tsx
index caf02ab..29c42b5 100644
--- a/src/components/site/SiteDisclaimerScreen.tsx
+++ b/src/components/site/SiteDisclaimerScreen.tsx
@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useSiteStore } from "@/managers/stores/useSiteStore";
+import { usePrefersReducedMotion } from "@/hooks/ui/usePrefersReducedMotion";
 
 const DISCLAIMER_TEXT =
   "Ce site a été conçu pour être utilisé sur ordinateur.\nPour une meilleure expérience, assurez-vous d'avoir une bonne connexion internet et une machine performante.";
@@ -7,13 +8,15 @@ const DISCLAIMER_TEXT =
 const TEXT_DISPLAY_DURATION = 5000;
 const FADE_OUT_DURATION = 1000;
 const TRANSITION_DELAY = 250;
+const SKIP_KEYS = new Set(["Enter", " ", "Escape"]);
 
 /**
  * Screen 0: Disclaimer
  */
 export function SiteDisclaimerScreen(): React.JSX.Element {
   const setStep = useSiteStore((state) => state.setStep);
-  const [textOpacity, setTextOpacity] = useState(0);
+  const prefersReducedMotion = usePrefersReducedMotion();
+  const [textOpacity, setTextOpacity] = useState(prefersReducedMotion ? 1 : 0);
   const hasSkipped = useRef(false);
 
   const handleSkip = useCallback(() => {
@@ -23,33 +26,40 @@ export function SiteDisclaimerScreen(): React.JSX.Element {
   }, [setStep]);
 
   useEffect(() => {
-    // Fade in text
     const fadeInTimeout = window.setTimeout(() => {
       setTextOpacity(1);
     }, 100);
 
-    // Start fade out after display duration
     const fadeOutTimeout = window.setTimeout(() => {
       setTextOpacity(0);
     }, TEXT_DISPLAY_DURATION);
 
-    // Transition to welcome after fade out + delay
     const transitionTimeout = window.setTimeout(
-      () => {
-        handleSkip();
-      },
+      handleSkip,
       TEXT_DISPLAY_DURATION + FADE_OUT_DURATION + TRANSITION_DELAY,
     );
 
+    const handleKeyDown = (event: KeyboardEvent): void => {
+      if (SKIP_KEYS.has(event.key)) {
+        event.preventDefault();
+        handleSkip();
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+
     return () => {
       window.clearTimeout(fadeInTimeout);
       window.clearTimeout(fadeOutTimeout);
       window.clearTimeout(transitionTimeout);
+      window.removeEventListener("keydown", handleKeyDown);
     };
   }, [handleSkip]);
 
   return (
     <div
+      role="region"
+      aria-label="Avertissement"
       onClick={handleSkip}
       style={{
         position: "fixed",
@@ -63,6 +73,7 @@ export function SiteDisclaimerScreen(): React.JSX.Element {
       }}
     >
       <p
+        aria-live="polite"
         style={{
           color: "#F2F2F2",
           textAlign: "center",
@@ -72,7 +83,9 @@ export function SiteDisclaimerScreen(): React.JSX.Element {
           lineHeight: 1.6,
           maxWidth: 800,
           opacity: textOpacity,
-          transition: `opacity ${FADE_OUT_DURATION}ms ease-in-out`,
+          transition: prefersReducedMotion
+            ? "none"
+            : `opacity ${FADE_OUT_DURATION}ms ease-in-out`,
           whiteSpace: "pre-wrap",
         }}
       >
diff --git a/src/components/ui/intro/IntroVideoPlayer.tsx b/src/components/ui/intro/IntroVideoPlayer.tsx
index d595330..27085bf 100644
--- a/src/components/ui/intro/IntroVideoPlayer.tsx
+++ b/src/components/ui/intro/IntroVideoPlayer.tsx
@@ -1,13 +1,12 @@
-import { useCallback, useRef, useEffect } from "react";
+import { useCallback, useEffect, useRef } from "react";
 import { useGameStore } from "@/managers/stores/useGameStore";
 
 const INTRO_VIDEO_PATH = "/cinematics/intro.mp4";
+const SKIP_KEYS = new Set(["Enter", " "]);
 
 /**
- * Full-screen video player for intro cinematic
- * - Plays intro.mp4 in fullscreen
- * - Automatically advances to dialogue-intro step when video ends
- * - Allows skipping with Enter/Space/Click
+ * Full-screen video player for the intro cinematic.
+ * Advances to the dialogue-intro step when the video ends or the user skips.
  */
 export function IntroVideoPlayer(): React.JSX.Element {
   const videoRef = useRef<HTMLVideoElement>(null);
@@ -18,16 +17,13 @@ export function IntroVideoPlayer(): React.JSX.Element {
   }, [setIntroStep]);
 
   const handleSkip = useCallback(() => {
-    if (videoRef.current) {
-      videoRef.current.pause();
-    }
+    videoRef.current?.pause();
     setIntroStep("dialogue-intro");
   }, [setIntroStep]);
 
-  // Handle keyboard skip (Enter/Space)
   useEffect(() => {
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === "Enter" || event.key === " ") {
+    const handleKeyDown = (event: KeyboardEvent): void => {
+      if (SKIP_KEYS.has(event.key)) {
         event.preventDefault();
         handleSkip();
       }
@@ -39,6 +35,8 @@ export function IntroVideoPlayer(): React.JSX.Element {
 
   return (
     <div
+      role="region"
+      aria-label="Vidéo d'introduction. Appuyez sur Entrée pour passer."
       onClick={handleSkip}
       style={{
         position: "fixed",
@@ -56,6 +54,7 @@ export function IntroVideoPlayer(): React.JSX.Element {
         src={INTRO_VIDEO_PATH}
         autoPlay
         playsInline
+        preload="auto"
         onEnded={handleVideoEnd}
         style={{
           width: "100%",
@@ -64,6 +63,7 @@ export function IntroVideoPlayer(): React.JSX.Element {
         }}
       />
       <span
+        aria-hidden="true"
         style={{
           position: "absolute",
           bottom: 32,
diff --git a/src/index.css b/src/index.css
index 0b0e4ea..94a3c72 100644
--- a/src/index.css
+++ b/src/index.css
@@ -44,6 +44,18 @@ select {
   font: inherit;
 }
 
+/* Site onboarding — accessible focus rings (WCAG 2.4.7) */
+.site-card-button:focus-visible,
+.site-button:focus-visible {
+  outline: 3px solid #ffffff;
+  outline-offset: 3px;
+  box-shadow: 0 0 0 5px rgba(0, 0, 0, 0.55);
+}
+
+.site-card-button[aria-pressed="true"]:focus-visible {
+  outline-color: #a8d5a2;
+}
+
 canvas {
   display: block;
 }