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

apps/client/src/ee/ai-chat/components/ai-chat-sidebar.tsx

@@ -120,7 +120,7 @@ export default function AiChatSidebar() {
   return (
     <div className={classes.sidebar}>
       <div className={classes.header}>
-        <span className={classes.title}>{t("AI Chat")}</span>
+        <h2 className={classes.title}>{t("AI Chat")}</h2>
         <Tooltip label={t("New chat")} openDelay={250} withArrow>
           <ActionIcon
             component={Link}
@@ -176,7 +176,7 @@ export default function AiChatSidebar() {
             ))
           : groupedChats.map((group) => (
               <div key={group.key} className={classes.chatGroup}>
-                <div className={classes.chatGroupLabel}>{group.label}</div>
+                <h3 className={classes.chatGroupLabel}>{group.label}</h3>
                 {group.chats.map((chat) => (
                   <AiChatSidebarItem
                     key={chat.id}

apps/client/src/ee/ai-chat/components/chat-empty-state.tsx

@@ -56,9 +56,9 @@ export default function ChatEmptyState({ isStreaming, onSend, onStop }: Props) {
     <div className={classes.emptyState}>
       <IconSparkles size={48} stroke={1.5} className={classes.emptyStateIcon} />
       <div className={classes.emptyStateBrand}>{t("Docmost AI")}</div>
-      <div className={classes.emptyStateTitle}>
+      <h1 className={classes.emptyStateTitle}>
         {t("What can I help you with?")}
-      </div>
+      </h1>
 
       <div className={classes.emptyStateInput}>
         <ChatInput
@@ -71,7 +71,7 @@ export default function ChatEmptyState({ isStreaming, onSend, onStop }: Props) {
       </div>
 
       <div className={classes.suggestionsSection}>
-        <div className={classes.suggestionsLabel}>Get started</div>
+        <h2 className={classes.suggestionsLabel}>{t("Get started")}</h2>
         <div className={classes.suggestionsGrid}>
           {SUGGESTIONS.map((s) => (
             <button

apps/client/src/ee/ai-chat/components/chat-input.tsx

@@ -226,6 +226,7 @@ export default function ChatInput({
     ],
     editorProps: {
       attributes: {
+        role: "textbox",
         "aria-label": placeholder || t("Ask anything... Use @ to mention pages"),
         "aria-multiline": "true",
       },
@@ -335,7 +336,15 @@ export default function ChatInput({
 
       <EditorContent editor={editor} className={classes.editorContent} />
       <div className={classes.actions}>
-        <Popover opened={plusMenuOpen} onChange={setPlusMenuOpen} position="top-start" width={220} shadow="md">
+        <Popover
+          opened={plusMenuOpen}
+          onChange={setPlusMenuOpen}
+          position="top-start"
+          width={220}
+          shadow="md"
+          trapFocus
+          returnFocus
+        >
           <Popover.Target>
             <button
               type="button"

apps/client/src/ee/ai-chat/components/chat-message-list.tsx

@@ -2,6 +2,7 @@ import { useEffect, useRef, useCallback, useState } from "react";
 import { ErrorBoundary } from "react-error-boundary";
 import { IconArrowDown, IconAlertTriangle } from "@tabler/icons-react";
 import { useTranslation } from "react-i18next";
+import { VisuallyHidden } from "@mantine/core";
 import type { AiChatMessage, AiChatToolCall } from "../types/ai-chat.types";
 import ChatMessage from "./chat-message";
 import classes from "../styles/ai-chat.module.css";
@@ -33,6 +34,7 @@ export default function ChatMessageList({
   streamingContent,
   streamingToolCalls,
 }: Props) {
+  const { t } = useTranslation();
   const containerRef = useRef<HTMLDivElement>(null);
   const bottomRef = useRef<HTMLDivElement>(null);
   const isAtBottomRef = useRef(true);
@@ -40,6 +42,38 @@ export default function ChatMessageList({
   const prevScrollTopRef = useRef(0);
   const [showScrollButton, setShowScrollButton] = useState(false);
 
+  // Dedicated status-region announcement for screen readers. Rather than
+  // putting aria-live on the whole transcript (which re-fires for every
+  // streamed token), announce "AI is thinking…" when streaming starts and
+  // the full assistant reply once streaming completes — a single, clean read.
+  const [statusAnnouncement, setStatusAnnouncement] = useState("");
+  const wasStreamingRef = useRef(false);
+
+  useEffect(() => {
+    const justStartedStreaming = isStreaming && !wasStreamingRef.current;
+    const justFinishedStreaming = !isStreaming && wasStreamingRef.current;
+
+    if (justStartedStreaming) {
+      setStatusAnnouncement(t("AI is thinking..."));
+    } else if (justFinishedStreaming) {
+      const lastMessage = messages[messages.length - 1];
+      if (lastMessage?.role === "assistant" && lastMessage.content) {
+        // Strip markdown punctuation so screen readers don't read symbols
+        // like # * _ ` ~ aloud. A plain-text version is fine — the styled
+        // version stays in the DOM for visual users.
+        const plainText = lastMessage.content
+          .replace(/[#*_`~]/g, "")
+          .replace(/\s+/g, " ")
+          .trim();
+        setStatusAnnouncement(plainText);
+      } else {
+        setStatusAnnouncement("");
+      }
+    }
+
+    wasStreamingRef.current = isStreaming;
+  }, [isStreaming, messages, t]);
+
   const scrollToBottom = useCallback((behavior: ScrollBehavior = "smooth") => {
     const container = containerRef.current;
     if (!container) return;
@@ -127,7 +161,18 @@ export default function ChatMessageList({
 
   return (
     <div className={classes.messageListWrapper}>
-      <div ref={containerRef} className={classes.messageList}>
+      {/* Single status region for chat announcements. Kept outside the
+          scrolling transcript so changes here trigger one polite read per
+          state change instead of re-announcing every streamed token. */}
+      <VisuallyHidden role="status" aria-live="polite">
+        {statusAnnouncement}
+      </VisuallyHidden>
+
+      <div
+        ref={containerRef}
+        className={classes.messageList}
+        aria-label={t("Chat transcript")}
+      >
         {messages.map((msg) => (
           <ErrorBoundary
             key={msg.id}
@@ -162,7 +207,7 @@ export default function ChatMessageList({
       {showScrollButton && (
         <button
           type="button"
-          aria-label="Scroll to bottom"
+          aria-label={t("Scroll to bottom")}
           className={classes.scrollToBottomButton}
           onClick={() => scrollToBottom("smooth")}
         >

apps/client/src/ee/ai-chat/components/chat-message.tsx

@@ -1,5 +1,6 @@
 import { useCallback } from "react";
 import { useNavigate } from "react-router";
+import { useTranslation } from "react-i18next";
 import DOMPurify from "dompurify";
 import { ActionIcon, Tooltip } from "@mantine/core";
 import {
@@ -43,6 +44,7 @@ export default function ChatMessage({
   streamingToolCalls,
 }: Props) {
   const navigate = useNavigate();
+  const { t } = useTranslation();
 
   const handleContentClick = useCallback(
     (e: React.MouseEvent<HTMLDivElement>) => {
@@ -78,7 +80,11 @@ export default function ChatMessage({
       }[]) || [];
 
     return (
-      <div className={classes.userMessage}>
+      <div
+        className={classes.userMessage}
+        role="article"
+        aria-label={t("You said:")}
+      >
         <div className={classes.userBubble}>
           {attachments.length > 0 && (
             <div className={classes.messageAttachments}>
@@ -100,8 +106,16 @@ export default function ChatMessage({
     );
   }
 
+  // Only label the article when there's something meaningful to announce.
+  // Tool-only assistant turns (no text) shouldn't announce "Assistant said:" with empty content.
+  const hasAnnouncableContent = Boolean(content);
+
   return (
-    <div className={classes.assistantMessage}>
+    <div
+      className={classes.assistantMessage}
+      role="article"
+      aria-label={hasAnnouncableContent ? t("Assistant said:") : undefined}
+    >
       <div className={classes.messageContent}>
         {toolCalls && toolCalls.length > 0 && (
           <ChatToolGroup toolCalls={toolCalls} isStreaming={isStreaming} />
@@ -131,7 +145,10 @@ export default function ChatMessage({
       </div>
       {!isStreaming && message.content && (
         <div className={classes.messageActions}>
-          <CopyTextButton text={message?.content} />
+          <CopyTextButton
+            text={message?.content}
+            label={t("Copy assistant response")}
+          />
         </div>
       )}
     </div>