fix: a11y roles and arias

ShaunSHamilton · ShaunSHamilton · commit ee6d0b886ac9 · 2025-11-29T10:02:39.000+02:00
diff --git a/index.html b/index.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
@@ -7,6 +7,7 @@
     <title>freeCodeCamp: Exam Environment</title>
   </head>
   <body class="light-palette">
+    <a href="#main-content" class="skip-link">Skip to main content</a>
     <div id="root"></div>
     <script type="module" src="/src/main.tsx"></script>
   </body>
diff --git a/src/components/audio-player.tsx b/src/components/audio-player.tsx
@@ -139,19 +139,22 @@ export function AudioPlayer({ fullQuestion }: AudioPlayerProps) {
   }
 
   return (
-    <Box>
+    <Box role="region" aria-label="Audio player">
       <Flex direction="column">
         <Flex alignItems="center">
-          <Button onClick={togglePlay}>
+          <Button
+            onClick={togglePlay}
+            aria-label={isPlaying ? "Pause audio" : "Play audio"}
+          >
             {isPlaying ? "| |" : <TriangleUpIcon style={{ rotate: "90deg" }} />}
           </Button>
-          <Text ml={2}>
+          <Text ml={2} aria-live="polite">
             {formatTime(audioRef.current.currentTime)} / {formatTime(duration)}
           </Text>
         </Flex>
 
         <Slider
-          aria-label="slider-ex-1"
+          aria-label="Audio progress and seek"
           min={0}
           max={duration}
           value={progress}
@@ -160,7 +163,7 @@ export function AudioPlayer({ fullQuestion }: AudioPlayerProps) {
           <SliderTrack>
             <SliderFilledTrack />
           </SliderTrack>
-          <SliderThumb />
+          <SliderThumb aria-label="Seek position" />
         </Slider>
       </Flex>
     </Box>
diff --git a/src/components/button-loading.tsx b/src/components/button-loading.tsx
@@ -20,8 +20,9 @@ export function ButtonLoading({
       alignItems={"center"}
       {...rest}
       type="button"
+      aria-busy={isPending}
     >
-      {isPending && <Spinner marginInlineEnd="0.5rem" />}
+      {isPending && <Spinner marginInlineEnd="0.5rem" aria-hidden="true" />}
       {children}
     </Button>
   );
diff --git a/src/components/exam-card.tsx b/src/components/exam-card.tsx
@@ -53,18 +53,20 @@ export function ExamCard({ exam }: ExamCardProps) {
   return (
     <li style={{ listStyle: "none", marginBottom: "1rem" }}>
       <Card
+        as="article"
         borderWidth={examStatus.status === "InProgress" ? "3px" : "1px"}
         borderColor={
           examStatus.status === "InProgress" ? "orange.400" : "gray.200"
         }
         boxShadow={examStatus.status === "InProgress" ? "lg" : "sm"}
         _hover={{ boxShadow: "md" }}
         transition="all 0.2s"
+        aria-label={`${exam.config.name} exam card`}
       >
         <CardBody>
           <Flex justifyContent="space-between" alignItems="flex-start" mb={2}>
             <Box flex={1}>
-              <Heading size="md" mb={2}>
+              <Heading as="h2" size="md" mb={2}>
                 {exam.config.name}
               </Heading>
               <Flex justifyContent={"space-between"}>
@@ -92,7 +94,13 @@ export function ExamCard({ exam }: ExamCardProps) {
           </Flex>
 
           {attemptsQuery.isPending ? (
-            <Flex alignItems="center" gap={2} mt={3}>
+            <Flex
+              alignItems="center"
+              gap={2}
+              mt={3}
+              aria-live="polite"
+              aria-busy="true"
+            >
               <Spinner size="sm" />
               <Text fontSize="sm" color="gray.500">
                 Getting attempt status...
diff --git a/src/components/exam-submission-modal.tsx b/src/components/exam-submission-modal.tsx
@@ -33,8 +33,10 @@ export function ExamSubmissionModal({
   return (
     <Modal isOpen={hasFinishedExam} onClose={onClose}>
       <ModalOverlay />
-      <ModalContent>
-        <ModalHeader>{maxTimeReached ? "Time's up!" : "Exam End"}</ModalHeader>
+      <ModalContent role="dialog" aria-labelledby="exam-submission-title">
+        <ModalHeader id="exam-submission-title">
+          {maxTimeReached ? "Time's up!" : "Exam End"}
+        </ModalHeader>
         <ModalBody>
           <Text>Thank you for taking the exam.</Text>
           <Text>
@@ -53,6 +55,7 @@ export function ExamSubmissionModal({
                 textDecoration: "underline",
                 textDecorationColor: "blue.300",
               }}
+              aria-label="Open freeCodeCamp page in browser"
             >
               https://freecodecamp.org
             </Button>{" "}
diff --git a/src/components/header.tsx b/src/components/header.tsx
@@ -52,6 +52,7 @@ export function Header() {
             >
               <Img
                 src=" https://cdn.freecodecamp.org/platform/universal/fcc_puck_500.jpg"
+                alt="freeCodeCamp logo"
                 width="32px"
                 height="32px"
                 mr="12px"
@@ -62,7 +63,12 @@ export function Header() {
           </Flex>
         </Box>
         <Flex alignSelf={"center"} width={"auto"} pr={"1em"}>
-          <IconButton ref={btnRef} aria-label="Menu" onClick={onOpen}>
+          <IconButton
+            ref={btnRef}
+            aria-label="Open navigation menu"
+            aria-expanded={isOpen}
+            onClick={onOpen}
+          >
             <HamburgerIcon />
           </IconButton>
         </Flex>
@@ -74,8 +80,8 @@ export function Header() {
         finalFocusRef={btnRef}
       >
         <DrawerOverlay />
-        <DrawerContent>
-          <DrawerCloseButton />
+        <DrawerContent aria-label="Navigation menu">
+          <DrawerCloseButton aria-label="Close navigation menu" />
           <DrawerHeader>Navigate</DrawerHeader>
           <DrawerBody>
             <Button
diff --git a/src/components/question-submission-error-modal.tsx b/src/components/question-submission-error-modal.tsx
@@ -60,11 +60,21 @@ export function QuestionSubmissionErrorModal({
       closeOnOverlayClick={false}
     >
       <ModalOverlay />
-      <ModalContent>
-        <ModalHeader backgroundColor={"#edb1af"} borderRadius={"md"}>
+      <ModalContent
+        role="alertdialog"
+        aria-labelledby="error-modal-title"
+        aria-describedby="error-modal-description"
+      >
+        <ModalHeader
+          id="error-modal-title"
+          backgroundColor={"#edb1af"}
+          borderRadius={"md"}
+        >
           Question Submission Error
         </ModalHeader>
-        <ModalBody>{error}</ModalBody>
+        <ModalBody id="error-modal-description" role="alert">
+          {error}
+        </ModalBody>
         <ModalFooter justifyContent={"center"}>
           <ButtonLoading
             onClick={onClick}
diff --git a/src/index.css b/src/index.css
@@ -156,6 +156,11 @@ body {
   line-height: 2;
 }
 
+.bottom-bubble-nav:focus {
+  outline: 3px solid var(--blue-mid);
+  outline-offset: 2px;
+}
+
 .bubble-active {
   border: 3px solid rgb(48, 48, 204);
   background-color: rgb(48, 48, 204);
@@ -167,6 +172,28 @@ body {
   color: white;
 }
 
+/* Skip to main content link */
+.skip-link {
+  position: absolute;
+  left: -9999px;
+  z-index: 999;
+  padding: 1em;
+  background-color: #000;
+  color: #fff;
+  text-decoration: none;
+}
+
+.skip-link:focus {
+  left: 0;
+  top: 0;
+}
+
+/* Ensure focus is visible across the application */
+*:focus-visible {
+  outline: 3px solid var(--blue-mid);
+  outline-offset: 2px;
+}
+
 audio {
   width: 100%;
 }
diff --git a/src/pages/exam-landing.tsx b/src/pages/exam-landing.tsx
@@ -96,13 +96,13 @@ export function ExamLanding() {
   return (
     <>
       <Header />
-      <Box width={"full"}>
+      <Box width={"full"} as="main" id="main-content">
         <Center height={"100%"}>
           <Flex direction={"column"} maxWidth={"70%"}>
             <Spacer size="m" />
-            <Heading>Instructions</Heading>
+            <Heading as="h1">Instructions</Heading>
             <Spacer size="s" />
-            <Text color={"red"}>
+            <Text color={"red"} role="alert">
               Please note that any attempt to cheat will result in immediate
               disqualification from the exam and you will need to retake the
               exam to qualify for the certification.
@@ -117,11 +117,16 @@ export function ExamLanding() {
             </Text>
             {!!note && (
               <>
-                <Heading size={"md"}>Exam Note</Heading>
+                <Heading as="h2" size={"md"}>
+                  Exam Note
+                </Heading>
                 <Text>{note}</Text>
               </>
             )}
-            <Checkbox onChange={(e) => setHasAgreed(e.target.checked)}>
+            <Checkbox
+              id="terms-agreement"
+              onChange={(e) => setHasAgreed(e.target.checked)}
+            >
               I agree to the terms and conditions
             </Checkbox>
             <Spacer size="s" />
@@ -163,7 +168,7 @@ export function ExamLanding() {
             )}
             <Spacer size="m" />
             {updateMutation.isError && (
-              <Box maxWidth="100%">
+              <Box maxWidth="100%" role="alert">
                 <Text>Error checking for updates:</Text>
                 <Code
                   p={2}
@@ -183,16 +188,20 @@ export function ExamLanding() {
               </Box>
             )}
             {downloadAndInstallMutation.isPending && !!updateMutation.data && (
-              <Box>
+              <Box role="status" aria-live="polite">
                 <Text>
                   Downloading update (version {updateMutation.data.version}).
                   App will restart when finished.
                 </Text>
-                <Progress hasStripe value={progress} />
+                <Progress
+                  hasStripe
+                  value={progress}
+                  aria-label="Download progress"
+                />
               </Box>
             )}
             {downloadAndInstallMutation.isError && (
-              <Box maxWidth="100%">
+              <Box maxWidth="100%" role="alert">
                 <Text>Error downloading and installing update:</Text>
                 <Code
                   p={2}
diff --git a/src/pages/exam.tsx b/src/pages/exam.tsx
@@ -395,7 +395,7 @@ export function Exam() {
         fullQuestion={fullQuestion}
         newSelectedAnswers={newSelectedAnswers}
       />
-      <Box overflowY="hidden">
+      <Box overflowY="hidden" as="main" id="main-content">
         <Box width={"full"} mt="2em">
           <Center height={"100%"} display={"flex"} flexDirection={"column"}>
             <Center width="full" borderBottom={"2px"} borderColor={"gray.300"}>
@@ -576,7 +576,9 @@ function Timer({
   }, [secondsLeft]);
 
   return (
-    <Text fontWeight={"bold"}>Time: {secondsToHHMMSS(availableTime)}</Text>
+    <Text fontWeight={"bold"} aria-live="polite" aria-atomic="true">
+      Time: {secondsToHHMMSS(availableTime)}
+    </Text>
   );
 }
 
@@ -622,9 +624,14 @@ function NavigationBubbles({
   const bubblesArr = getCurrentBubbleIndex(wantedIndex);
 
   return (
-    <Flex width="80%" justifyContent={"center"}>
+    <Flex
+      width="80%"
+      justifyContent={"center"}
+      as="nav"
+      aria-label="Question navigation"
+    >
       <IconButton
-        aria-label="previous question"
+        aria-label="Go to previous question"
         icon={<ChevronLeftIcon />}
         m={"0.3em"}
         isDisabled={currentQuestionNumber === 1}
@@ -633,7 +640,7 @@ function NavigationBubbles({
         }}
       />
       <IconButton
-        aria-label="previous set of questions"
+        aria-label="Go to previous set of questions"
         icon={<ArrowLeftIcon />}
         m={"0.3em"}
         isDisabled={wantedIndex === 0}
@@ -655,12 +662,24 @@ function NavigationBubbles({
           className={`bottom-bubble-nav ${
             currentQuestionNumber === question_num ? "bubble-active" : ""
           } ${isAnswered(question_num) ? "bubble-answered" : ""}`}
+          role="button"
+          tabIndex={0}
+          aria-label={`Go to question ${question_num}${isAnswered(question_num) ? " (answered)" : ""}`}
+          aria-current={
+            currentQuestionNumber === question_num ? "page" : undefined
+          }
+          onKeyDown={(e) => {
+            if (e.key === "Enter" || e.key === " ") {
+              e.preventDefault();
+              specificQuestion(question_num);
+            }
+          }}
         >
           <Text>{question_num.toString()}</Text>
         </Box>
       ))}
       <IconButton
-        aria-label="next"
+        aria-label="Go to next set of questions"
         icon={<ArrowRightIcon />}
         m={"0.3em"}
         isDisabled={maxIndex == wantedIndex}
@@ -669,7 +688,7 @@ function NavigationBubbles({
         }}
       />
       <IconButton
-        aria-label="next question"
+        aria-label="Go to next question"
         icon={<ChevronRightIcon />}
         m={"0.3em"}
         isDisabled={currentQuestionNumber === questions.length}
diff --git a/src/pages/landing.tsx b/src/pages/landing.tsx
diff --git a/src/pages/login.tsx b/src/pages/login.tsx
