fix(a11y): WCAG 2.1 AA fixes (#2219)

apps/client/src/components/common/avatar-uploader.tsx

@@ -80,12 +80,20 @@ export default function AvatarUploader({
     }
   };
 
-  const ariaLabel = {
+  const actionLabel = {
     [AvatarIconType.AVATAR]: t("Change avatar"),
     [AvatarIconType.SPACE_ICON]: t("Change space icon"),
     [AvatarIconType.WORKSPACE_ICON]: t("Change workspace icon"),
   }[type];
 
+  // Per WCAG 2.5.3 (Label in Name), the accessible name must include the
+  // visible text. When no image is set, the avatar renders the name's
+  // initials, so prepend the name to the action label.
+  const ariaLabel =
+    !currentImageUrl && fallbackName
+      ? `${fallbackName} – ${actionLabel}`
+      : actionLabel;
+
   const handleRemove = async () => {
     if (disabled) return;
 

apps/client/src/components/common/copy.tsx

@@ -8,15 +8,19 @@ interface CopyProps {
   text: string;
   size?: MantineSize;
   color?: MantineColor;
+  /** Override the accessible name (and tooltip) when not yet copied. Lets callers disambiguate adjacent copy buttons for screen readers. */
+  label?: string;
 }
-export default function CopyTextButton({ text, size }: CopyProps) {
+export default function CopyTextButton({ text, size, label }: CopyProps) {
   const { t } = useTranslation();
 
+  const copyLabel = label ?? t("Copy");
+
   return (
     <CopyButton value={text} timeout={2000}>
       {({ copied, copy }) => (
         <Tooltip
-          label={copied ? t("Copied") : t("Copy")}
+          label={copied ? t("Copied") : copyLabel}
           withArrow
           position="right"
         >
@@ -25,7 +29,7 @@ export default function CopyTextButton({ text, size }: CopyProps) {
             variant="subtle"
             onClick={copy}
             size={size}
-            aria-label={copied ? t("Copied") : t("Copy")}
+            aria-label={copied ? t("Copied") : copyLabel}
           >
             {copied ? <IconCheck size={16} /> : <IconCopy size={16} />}
           </ActionIcon>

apps/client/src/components/common/export-modal.tsx

@@ -81,7 +81,7 @@ export default function ExportModal({
       <Modal.Content style={{ overflow: "hidden" }}>
         <Modal.Header py={0}>
           <Modal.Title fw={500}>{t(`Export ${type}`)}</Modal.Title>
-          <Modal.CloseButton />
+          <Modal.CloseButton aria-label={t("Close")} />
         </Modal.Header>
         <Modal.Body>
           <Group justify="space-between" wrap="nowrap">

apps/client/src/components/common/recent-changes.tsx

@@ -17,6 +17,7 @@ import { EmptyState } from "@/components/ui/empty-state.tsx";
 import { getSpaceUrl } from "@/lib/config.ts";
 import { useTranslation } from "react-i18next";
 import { getInitialsColor } from "@/lib/get-initials-color.ts";
+import rowClasses from "@/components/ui/clickable-table-row.module.css";
 
 interface Props {
   spaceId?: string;
@@ -41,9 +42,10 @@ export default function RecentChanges({ spaceId }: Props) {
         <Table highlightOnHover verticalSpacing="sm">
           <Table.Tbody>
             {pages.map((page) => (
-              <Table.Tr key={page.id}>
+              <Table.Tr key={page.id} className={rowClasses.row}>
                 <Table.Td>
                   <UnstyledButton
+                    className={rowClasses.link}
                     component={Link}
                     to={buildPageUrl(page?.space.slug, page.slugId, page.title)}
                   >

apps/client/src/components/layouts/global/aside.tsx

@@ -1,22 +1,28 @@
-import { ActionIcon, Box, Group, ScrollArea, Text, Tooltip } from "@mantine/core";
+import { ActionIcon, Box, Group, ScrollArea, Title, Tooltip } from "@mantine/core";
 import { IconX } from "@tabler/icons-react";
 import CommentListWithTabs from "@/features/comment/components/comment-list-with-tabs.tsx";
 import { useAtom } from "jotai";
 import { asideStateAtom } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
-import React, { ReactNode } from "react";
+import React, { ReactNode, useEffect } from "react";
 import { useTranslation } from "react-i18next";
 import { TableOfContents } from "@/features/editor/components/table-of-contents/table-of-contents.tsx";
 import { useAtomValue } from "jotai";
 import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
 import AsideChatPanel from "@/ee/ai-chat/components/aside-chat-panel";
 import { PageDetailsAside } from "@/features/page-details/components/page-details-aside.tsx";
+import { ASIDE_PANEL_ID } from "@/hooks/use-toggle-aside.tsx";
 
 export default function Aside() {
-  const [{ tab }, setAsideState] = useAtom(asideStateAtom);
+  const [{ tab, isAsideOpen }, setAsideState] = useAtom(asideStateAtom);
   const { t } = useTranslation();
   const pageEditor = useAtomValue(pageEditorAtom);
   const closeAside = () => setAsideState((s) => ({ ...s, isAsideOpen: false }));
 
+  useEffect(() => {
+    if (!isAsideOpen) return;
+    document.getElementById(ASIDE_PANEL_ID)?.focus();
+  }, [isAsideOpen, tab]);
+
   let title: string;
   let component: ReactNode;
 
@@ -48,7 +54,7 @@ export default function Aside() {
         <>
           {tab !== "chat" && (
             <Group justify="space-between" wrap="nowrap" mb="md">
-              <Text fw={500}>{t(title)}</Text>
+              <Title order={2} size="h6" fw={500}>{t(title)}</Title>
               <Tooltip label={t("Close")} withArrow>
                 <ActionIcon
                   variant="subtle"

apps/client/src/components/layouts/global/global-app-shell.tsx

@@ -18,6 +18,8 @@ import classes from "./app-shell.module.css";
 import { useTrialEndAction } from "@/ee/hooks/use-trial-end-action.tsx";
 import { useToggleSidebar } from "@/components/layouts/global/hooks/hooks/use-toggle-sidebar.ts";
 import GlobalSidebar from "@/components/layouts/global/global-sidebar.tsx";
+import { ASIDE_PANEL_ID } from "@/hooks/use-toggle-aside.tsx";
+import { MAIN_CONTENT_ID, SkipToMain } from "@/components/ui/skip-to-main.tsx";
 
 export default function GlobalAppShell({
   children,
@@ -81,7 +83,9 @@ export default function GlobalAppShell({
   const showGlobalSidebar = !isSpaceRoute && !isSettingsRoute && !isAiRoute;
 
   return (
-    <AppShell
+    <>
+      <SkipToMain />
+      <AppShell
       header={{ height: 45 }}
       navbar={{
         width: isSpaceRoute ? sidebarWidth : 300,
@@ -125,7 +129,7 @@ export default function GlobalAppShell({
         {isAiRoute && <AiChatSidebar />}
         {showGlobalSidebar && <GlobalSidebar />}
       </AppShell.Navbar>
-      <AppShell.Main id="main-content">
+      <AppShell.Main id={MAIN_CONTENT_ID} tabIndex={-1}>
         {isSettingsRoute ? (
           <Container size={900} pb={80}>
             {children}
@@ -137,6 +141,8 @@ export default function GlobalAppShell({
 
       {isPageRoute && (
         <AppShell.Aside
+          id={ASIDE_PANEL_ID}
+          tabIndex={-1}
           className={classes.aside}
           p="md"
           withBorder={false}
@@ -156,5 +162,6 @@ export default function GlobalAppShell({
         </AppShell.Aside>
       )}
     </AppShell>
+    </>
   );
 }

apps/client/src/components/layouts/global/global-sidebar.module.css

@@ -31,6 +31,11 @@
         color: light-dark(var(--mantine-color-black), var(--mantine-color-white));
     }
 
+    &:focus-visible {
+        outline: 2px solid var(--mantine-primary-color-filled);
+        outline-offset: 2px;
+    }
+
     &[data-active] {
         &,
         & :hover {
@@ -96,4 +101,9 @@
         );
         color: light-dark(var(--mantine-color-black), var(--mantine-color-white));
     }
+
+    &:focus-visible {
+        outline: 2px solid var(--mantine-primary-color-filled);
+        outline-offset: 2px;
+    }
 }

apps/client/src/components/layouts/global/global-sidebar.tsx

@@ -92,6 +92,7 @@ export default function GlobalSidebar() {
                 key={item.label}
                 className={classes.link}
                 data-active={active === item.path || undefined}
+                aria-current={active === item.path ? "page" : undefined}
                 to={item.path}
                 onClick={handleNavClick}
               >
@@ -159,6 +160,7 @@ export default function GlobalSidebar() {
         <Link
           className={classes.link}
           data-active={active.startsWith("/settings") || undefined}
+          aria-current={active.startsWith("/settings") ? "page" : undefined}
           to="/settings/account/profile"
           onClick={handleNavClick}
         >

apps/client/src/components/settings/settings-title.tsx

@@ -4,7 +4,7 @@ import { Divider, Title } from '@mantine/core';
 export default function SettingsTitle({ title }: { title: string }) {
   return (
     <>
-      <Title order={3}>
+      <Title order={1} size="h3">
         {title}
       </Title>
       <Divider my="md" />

apps/client/src/components/ui/clickable-table-row.module.css

@@ -0,0 +1,29 @@
+/*
+ * Focus styling for list-style tables (recent changes, favorites, all
+ * spaces, groups, verified pages, shares).
+ *
+ * Per WAI-ARIA Authoring Practices and Adrian Roselli's guidance on table
+ * accessibility (https://adrianroselli.com/2020/02/block-links-cards-clickable-regions-etc.html),
+ * data tables should not be made fully clickable. Only the title cell is the
+ * link, and that link is what receives Tab focus.
+ *
+ * - `.row` adds a subtle background tint when the row contains the focused
+ *   element, so keyboard users can see which row they're inspecting.
+ * - `.link` adds a visible :focus-visible outline on the title link itself.
+ *
+ * No stretched-link pseudo here on purpose: absolutely-positioned pseudos
+ * inside table cells cause column reflow on focus in Chromium.
+ */
+
+.row:focus-within {
+  background-color: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-6)
+  );
+}
+
+.link:focus-visible {
+  outline: 2px solid var(--mantine-primary-color-filled);
+  outline-offset: 2px;
+  border-radius: var(--mantine-radius-sm);
+}

apps/client/src/components/ui/custom-avatar.tsx

@@ -16,14 +16,18 @@ interface CustomAvatarProps {
   mt?: string | number;
 }
 
-// `color.shade` pairs whose filled background meets WCAG AA (4.5:1) against
-// white text. Avoids lime/yellow/green/orange — even their dark shades have
-// weak white-text contrast.
+// `color.shade` pairs whose contrast meets WCAG AA (4.5:1) in BOTH variants:
+//   - filled: white text on the shade as bg
+//   - light:  shade as text on the color's light-bg (10% color.6 over white)
+// Avoids lime/yellow/green/orange — even their dark shades have weak
+// contrast. grape and indigo were bumped from .7 to darker shades because
+// the original picks failed: grape.7 was 4.02/3.61 (both fail) and
+// indigo.7 was 4.98/4.39 (light fails by a hair).
 const SAFE_INITIALS_COLORS: MantineColor[] = [
   "blue.8",
   "cyan.9",
-  "grape.7",
-  "indigo.7",
+  "grape.9",
+  "indigo.8",
   "pink.8",
   "red.8",
   "violet.7",

apps/client/src/components/ui/destination-picker/destination-picker-modal.tsx

@@ -41,7 +41,7 @@ export function DestinationPickerModal({
       <Modal.Content>
         <Modal.Header py={0}>
           <Modal.Title fw={500}>{title}</Modal.Title>
-          <Modal.CloseButton />
+          <Modal.CloseButton aria-label={t("Close")} />
         </Modal.Header>
         <Modal.Body>
           <DestinationPicker

apps/client/src/components/ui/sidebar-toggle-button.tsx

@@ -14,7 +14,14 @@ export interface SidebarToggleProps extends BoxProps, ElementProps<"button"> {
 const SidebarToggle = React.forwardRef<HTMLButtonElement, SidebarToggleProps>(
   ({ opened, size = "sm", ...others }, ref) => {
     return (
-      <ActionIcon size={size} {...others} variant="subtle" color="gray" ref={ref}>
+      <ActionIcon
+        size={size}
+        aria-expanded={opened}
+        {...others}
+        variant="subtle"
+        color="gray"
+        ref={ref}
+      >
         {opened ? (
           <IconLayoutSidebarRightExpand />
         ) : (

apps/client/src/components/ui/skip-to-main.module.css

@@ -0,0 +1,27 @@
+.skipLink {
+  position: absolute;
+  top: 8px;
+  left: 8px;
+  z-index: 9999;
+  padding: 8px 16px;
+  background: var(--mantine-color-body);
+  color: var(--mantine-color-text);
+  border: 2px solid var(--mantine-color-blue-6);
+  border-radius: 4px;
+  text-decoration: none;
+  font-weight: 500;
+  font-size: var(--mantine-font-size-sm);
+  transform: translateY(-200%);
+  transition: transform 0.15s ease-out;
+}
+
+.skipLink:focus {
+  transform: translateY(0);
+  outline: none;
+}
+
+@media print {
+  .skipLink {
+    display: none !important;
+  }
+}

apps/client/src/components/ui/skip-to-main.tsx

@@ -0,0 +1,13 @@
+import { useTranslation } from "react-i18next";
+import classes from "./skip-to-main.module.css";
+
+export const MAIN_CONTENT_ID = "main-content";
+
+export function SkipToMain() {
+  const { t } = useTranslation();
+  return (
+    <a href={`#${MAIN_CONTENT_ID}`} className={classes.skipLink}>
+      {t("Skip to main content")}
+    </a>
+  );
+}