fix(a11y): announce dynamic status and errors via live regions (A11Y-…

docs/accessibility/ACCESSIBILITY_FINDINGS.md

@@ -1550,14 +1550,18 @@ These patterns recur across the codebase and should be fixed once (component/sou
 
 ### Recommended Fix Order
 
-1. **Critical blockers:** A11Y-001, A11Y-002 (build the `Clickable` and `IconButton` primitives first).
-2. **Keyboard navigation:** A11Y-006, A11Y-007, A11Y-009, A11Y-015, A11Y-020, A11Y-021, A11Y-033.
-3. **Screen reader support:** A11Y-004, A11Y-008, A11Y-010, A11Y-012, A11Y-013, A11Y-014, A11Y-024, A11Y-026, A11Y-030, A11Y-034.
-4. **Forms:** A11Y-005, A11Y-016, A11Y-019, A11Y-029.
+1. **Critical blockers:** A11Y-001 (completed), A11Y-002 (completed) — build the `Clickable` and `IconButton` primitives first.
+2. **Keyboard navigation:** A11Y-006 (completed), A11Y-007, A11Y-009, A11Y-015, A11Y-020 (completed), A11Y-021 (completed), A11Y-033.
+3. **Screen reader support:** A11Y-004 (completed), A11Y-008 (completed), A11Y-010 (completed), A11Y-012, A11Y-013, A11Y-014, A11Y-024, A11Y-026, A11Y-030, A11Y-034.
+4. **Forms:** A11Y-005 (completed), A11Y-016 (completed), A11Y-019 (completed), A11Y-029.
 5. **Dialogs & focus management:** A11Y-011, A11Y-017, A11Y-023 (build `AppModal`).
-6. **Semantic HTML improvements:** A11Y-003, A11Y-018, A11Y-028, A11Y-031, A11Y-035.
+6. **Semantic HTML improvements:** A11Y-003 (completed), A11Y-018 (completed), A11Y-028 (completed), A11Y-031, A11Y-035 (completed).
 7. **Remaining low-priority items:** A11Y-022, A11Y-025, A11Y-027, A11Y-032.
 
+> "(completed)" means the fix is merged into `develop`. 15 of 35 findings are done: A11Y-001, 002, 003, 004, 005, 006, 008, 010, 016, 018, 019, 020, 021, 028, 035.
+>
+> Partially covered: A11Y-005 — one control is still unlabeled, tracked as FU-004 in `FOLLOW_UPS.md`. A11Y-032 was in scope of the semantic-HTML branch but was not fixed; `RedeemPopup` still uses `<a onClick>` with no `href`.
+
 ---
 
 *Generated from a repository-wide accessibility audit. Line numbers reflect the state of the code at audit time and may shift as the codebase changes; re-verify before fixing. Automated color-contrast testing (axe/Lighthouse) and manual screen-reader passes (NVDA, VoiceOver) are recommended to complement this static review.*

docs/accessibility/FOLLOW_UPS.md

@@ -282,3 +282,58 @@ Hoist `handleMouseEnter` (and any other Hooks) above the conditional so they run
 
 - File: `src/features/common/WebappButton/index.tsx` (link branch).
 - Related: shared `isExternalUrl` helper in `src/utils/url.ts`.
+
+## FU-006 — Give empty-state illustrations a text alternative
+
+**Status:** Open.
+**Origin:** Surfaced during A11Y-010 (live regions) while checking whether the PlanetCash empty transactions state is announced. It is not announced, but the cause is a missing text alternative (WCAG 1.1.1), not a missing live region (4.1.3), so it is out of scope for A11Y-010.
+**Priority:** Medium — `NoTransactionsFound` is a real content gap for screen reader users; the rest is consistency work.
+
+### Background
+
+`NoTransactionsFound` renders an illustration and nothing else:
+
+```tsx
+const NoTransactionsFound = (): ReactElement => {
+  return (
+    <CenteredContainer className="CenteredContainer--small">
+      <TransactionsNotFound />
+    </CenteredContainer>
+  );
+};
+```
+
+`TransactionsNotFound` is a bare inline `<svg>` with no `role`, no `<title>`, and no `aria-label`. So a sighted user sees "you have no transactions" and a screen reader user gets nothing at all: the container is empty as far as assistive tech is concerned.
+
+The neighbouring `NoDataFound` illustration in the projects list has the inverse problem. It is also unlabeled, but it sits next to a visible "No project found" paragraph that already carries the meaning, so the SVG is decorative and should be hidden rather than named.
+
+### Proposal
+
+Prefer real text over an SVG label, so the empty state is visible to everyone and translatable:
+
+1. Add a visible message to `NoTransactionsFound` (new `Me` namespace key, for example `noTransactionsFound`; no such key exists today), mirroring how `ProjectList` pairs `NoDataFound` with `noProjectFound` text.
+2. Mark both illustrations `aria-hidden="true"` once the text carries the meaning. Following the A11Y-002 convention, wrap the icon component in `<span aria-hidden="true" style={{ display: 'contents' }}>` rather than editing the SVG, unless the SVG is edited directly.
+3. Sweep for other empty-state and error illustrations that are the sole content of their container, and apply the same treatment.
+
+If a visible message is not wanted for a given state, the fallback is `role="img"` plus a localized `aria-label` on the SVG.
+
+### Why deferred (not fixed in the A11Y-010 PR)
+
+- **Different finding** — A11Y-010 covers status messages under 4.1.3. A missing text alternative is 1.1.1 and belongs with the A11Y-002 / A11Y-004 image and naming work.
+- **Adds visible UI** — a new visible string and a new i18n key is a design and copy decision, not a silent a11y fix.
+- **Scope discipline** — the sweep across other empty-state illustrations should be reviewed as its own change.
+
+### Suggested acceptance criteria
+
+- [ ] `NoTransactionsFound` exposes a localized text alternative; the empty state is conveyed to screen reader users.
+- [ ] New i18n key added to the `en` locale only (Lingohub manages the rest).
+- [ ] Decorative empty-state illustrations (`NoDataFound`, and any others found in the sweep) are `aria-hidden`, so the message is not announced twice.
+- [ ] No visual regression in either empty state.
+- [ ] Verified with a screen reader and axe (`svg-img-alt`).
+
+### References
+
+- Component: `src/features/user/PlanetCash/components/NoTransactionsFound.tsx`.
+- Illustrations: `public/assets/images/icons/TransactionsNotFound.tsx`, `public/assets/images/icons/projectV2/NoDataFound.tsx`.
+- Reference pattern: `src/features/projectsV2/ProjectList/index.tsx` (illustration + visible text).
+- Surfaced by: `ACCESSIBILITY_FINDINGS.md` → A11Y-010; related findings A11Y-002, A11Y-004.

public/static/locales/en/common.json

@@ -8,6 +8,7 @@
     "nextSlide": "Next slide",
     "previousSlide": "Previous slide",
     "loadingProfile": "Loading your profile",
+    "loading": "Loading",
     "and": "and",
     "tree": "{count, plural, =1 {Tree} other {Trees}}",
     "m2": "m²",

public/static/locales/en/donationReceipt.json

@@ -54,6 +54,7 @@
     "donorContactManagement": "Donor Contact Management",
     "contactManagementHeader": "Update profile and address",
     "saveDataAndReturn": "Save data and return",
+    "savingDonorInfo": "Saving your details",
     "donationReceipt": "Donation Receipt",
     "verifyAndDownload": "Verify & Download",
     "itemsReferenceDateMultiDonation": "<u>{count, plural, one {# Item} other {# Items}}</u>",

public/static/locales/en/me.json

@@ -192,6 +192,7 @@
     "downloads": "Downloads",
     "account": "Account",
     "loadMore": "Load More",
+    "loadingTransactions": "Loading transactions",
     "setTarget": "Set Target",
     "targetSave": "Save",
     "targetErrorMessage": "Number must be greater than zero",

src/features/common/ContentLoaders/Projects/GlobeLoader.tsx

@@ -1,31 +1,49 @@
 import type { ReactElement } from 'react';
 
 import { motion } from 'framer-motion';
+import { useTranslations } from 'next-intl';
 
 import GlobeLoader from '../../../../../public/assets/images/icons/Globe';
+import LiveRegion from '../../LiveRegion';
 
 function GlobeContentLoader(): ReactElement {
+  const t = useTranslations('Common');
+
   return (
-    <motion.div
-      animate={{
-        translateY: [0, 20, 0],
-      }}
-      transition={{
-        duration: 1,
-        ease: 'easeInOut',
-        times: [0, 0.5, 1],
-        loop: Infinity,
-        repeatDelay: 0,
-      }}
-      style={{
-        height: '100vh',
-        display: 'flex',
-        justifyContent: 'center',
-        alignItems: 'center',
-      }}
-    >
-      <GlobeLoader />
-    </motion.div>
+    <>
+      {/* The animated globe has no text, so the loading message is announced
+    instead. The live region is placed next to the globe, not inside it,
+    because the globe uses `aria-busy`. Screen readers may ignore live region
+    updates inside a busy element until loading finishes.
+
+    The live region cannot stay on the page because this component is only
+    rendered while loading. That's okay here because the loading message never
+    changes. */}
+      <LiveRegion politeness="polite" isVisuallyHidden>
+        {t('loading')}
+      </LiveRegion>
+      <motion.div
+        aria-busy="true"
+        animate={{
+          translateY: [0, 20, 0],
+        }}
+        transition={{
+          duration: 1,
+          ease: 'easeInOut',
+          times: [0, 0.5, 1],
+          loop: Infinity,
+          repeatDelay: 0,
+        }}
+        style={{
+          height: '100vh',
+          display: 'flex',
+          justifyContent: 'center',
+          alignItems: 'center',
+        }}
+      >
+        <GlobeLoader />
+      </motion.div>
+    </>
   );
 }
 

src/features/common/Layout/ErrorPopup/index.tsx

@@ -3,6 +3,7 @@ import type { ReactElement } from 'react';
 import { useEffect } from 'react';
 import CloseIcon from '../../../../../public/assets/images/icons/CloseIcon';
 import IconButton from '../../IconButton';
+import LiveRegion from '../../LiveRegion';
 import styles from './ErrorPopup.module.scss';
 import { useTranslations } from 'next-intl';
 import { useErrorHandlingStore } from '../../../../stores/errorHandlingStore';
@@ -62,9 +63,15 @@ export default function ErrorPopup(): ReactElement {
               >
                 <CloseIcon color={'#f44336'} width={'10'} height={'10'} />
               </IconButton>
-              <div className={styles.errorContent}>
+              {/* Assertive: an API failure the user must hear immediately.
+                  Scoped to the message so the close button is not announced
+                  as part of the alert. */}
+              <LiveRegion
+                politeness="assertive"
+                className={styles.errorContent}
+              >
                 {processErrorMessage(err.message)}
-              </div>
+              </LiveRegion>
             </div>
           );
         })}

src/features/common/LiveRegion/LiveRegion.module.scss

@@ -0,0 +1,15 @@
+// Screen-reader-only content: removed from the visual flow so it reserves no
+// space, while remaining announced by assistive tech.
+// `display: none` / `visibility: hidden` would remove it from the a11y tree,
+// so the clip technique is used instead.
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

src/features/common/LiveRegion/index.tsx

@@ -0,0 +1,97 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import { clsx } from 'clsx';
+import styles from './LiveRegion.module.scss';
+
+/**
+ * How urgently an update should reach a screen reader.
+ *
+ * - `assertive` → `role="alert"`. Interrupts whatever is being read. Use for
+ *   errors and failed actions the user must hear right away.
+ * - `polite` → `role="status"`. Queued until the reader is idle. Use for
+ *   result counts, empty states, upload/save progress and success messages.
+ */
+export type LiveRegionPoliteness = 'assertive' | 'polite';
+
+/** Elements a live region may render as. Kept to text-level containers. */
+export type LiveRegionElement = 'div' | 'p' | 'span';
+
+export interface LiveRegionProps {
+  /** Announcement urgency. Maps to `role="alert"` / `role="status"`. */
+  politeness: LiveRegionPoliteness;
+
+  /** The message. May be empty while there is nothing to announce. */
+  children?: ReactNode;
+
+  /** Element to render. Defaults to `div`. */
+  as?: LiveRegionElement;
+
+  /** Additional CSS classes. Existing message styling is preserved. */
+  className?: string;
+
+  /**
+   * Announce the message without showing it. Use when the visual cue is a
+   * spinner or skeleton that carries no text.
+   */
+  isVisuallyHidden?: boolean;
+
+  /** Forwarded so the region can still be referenced by `aria-describedby`. */
+  id?: string;
+}
+
+/**
+ * Announces messages that appear or change after the page loads.
+ *
+ * Screen readers don't automatically read updates in a normal element.
+ * Wrapping the content in a live region makes those updates get announced
+ * without moving the user's focus.
+ *
+ * Keep the live region on the page and only update its content instead of
+ * adding a new one. This is more reliable for screen readers.
+ *
+ * This is especially important for `polite` messages. Some screen readers only
+ * announce changes inside a live region that is already on the page, so adding
+ * the region together with its message may not be announced. `assertive`
+ * (`role="alert"`) messages are usually announced even when the region is
+ * added with the message.
+ *
+ * If keeping a visible live region on the page would affect the layout, keep a
+ * hidden live region (`isVisuallyHidden`) on the page and render the visible
+ * message separately:
+ *
+ * ```tsx
+ * <LiveRegion politeness="polite" isVisuallyHidden>
+ *   {isSaving ? t('saving') : ''}
+ * </LiveRegion>
+ * {isSaving && <div className={styles.spinner} />}
+ * ```
+ *
+ * Don't place a live region inside an element with `aria-busy={true}`.
+ * Screen readers wait until the busy element has finished updating, so
+ * messages inside it may not be announced. Render the live region next to the
+ * busy element instead.
+ */
+function LiveRegion({
+  politeness,
+  children,
+  as: Element = 'div',
+  className,
+  isVisuallyHidden = false,
+  id,
+}: LiveRegionProps): ReactElement {
+  return (
+    <Element
+      id={id}
+      role={politeness === 'assertive' ? 'alert' : 'status'}
+      // Both roles already imply these values, but some older
+      // screen-reader/browser pairs only act on the explicit attributes.
+      aria-live={politeness}
+      aria-atomic="true"
+      className={clsx(isVisuallyHidden && styles.visuallyHidden, className)}
+    >
+      {children}
+    </Element>
+  );
+}
+
+export default LiveRegion;

src/features/common/RedeemCode/RedeemFailed.tsx

@@ -3,6 +3,7 @@ import type { SerializedError } from '@planet-sdk/common';
 
 import CancelIcon from '../../../../public/assets/images/icons/CancelIcon';
 import IconButton from '../IconButton';
+import LiveRegion from '../LiveRegion';
 import styles from '../../../../src/features/common/RedeemCode/style/RedeemModal.module.scss';
 import { useTranslations } from 'next-intl';
 import Button from '@mui/material/Button';
@@ -36,9 +37,10 @@ export const RedeemFailed = ({
       </div>
 
       <div className={styles.redeemTitle}>{inputCode}</div>
-      <div className={styles.formErrors}>
+      {/* Assertive: the redeem attempt failed, so the reason must interrupt. */}
+      <LiveRegion politeness="assertive" className={styles.formErrors}>
         {errorMessages && errorMessages[0]?.message}
-      </div>
+      </LiveRegion>
       <div className={styles.redeemCodeButtonContainer}>
         <Button variant="contained" onClick={redeemAnotherCode}>
           {t('redeemAnotherCode')}