fix(a11y): make /assets/files accessible (#13987)

viktoravelino · web-flow · commit bf818073edbc · 2026-07-10T17:22:33.000Z
* fix(a11y): make /assets/files accessible (LE-1744) Bring the Files page to WCAG 2.1 A/AA, verified with IBM Equal Access plus keyboard/focus tests. - Name the icon-only actions column header, hidden visually (4.1.2) - Open the row actions menu by keyboard from the grid cell (2.1.1) - Label the upload/bulk-delete buttons so they are named on mobile (4.1.2) - Restore a keyboard-only :focus-visible ring on borderless grid cells (2.4.7) - Merge the bulk-delete dialog trigger via asChild to remove the duplicate tab stop (2.4.3) - Move focus into the cell editor when renaming (2.4.3) - Make the upload "try again" retry a real button (2.1.1) Add a dedicated Playwright a11y suite (files.a11y.spec.ts) covering the full state matrix and keyboard/focus behaviour, move the IBM baseline folder under tests/a11y, and baseline the known Radix menu-portal landmark item. * feat(a11y): add frontend accessibility check skill documentation * fix(a11y): return focus to upload button after file picker cancel (LE-1744) Keyboard-activating Upload Files then dismissing the native picker with Esc dropped focus to <body> (WCAG 2.4.3). Only blur on mouse clicks (to keep the #13178 tooltip fix); restore focus to the trigger on keyboard activation. Adds two behavioural a11y tests.
diff --git a/.agents/skills/frontend-a11y-check/SKILL.md b/.agents/skills/frontend-a11y-check/SKILL.md
diff --git a/.secrets.baseline b/.secrets.baseline
diff --git a/src/frontend/.achecker.yml b/src/frontend/.achecker.yml
@@ -11,5 +11,5 @@ outputFormat:
   - html
   - json
 outputFilenameTimestamp: false
-baselineFolder: tests/baselines
+baselineFolder: tests/a11y/baselines
 outputFolder: coverage/accessibility-reports
diff --git a/src/frontend/src/locales/de.json b/src/frontend/src/locales/de.json
@@ -683,6 +683,7 @@
   "fileManager.uploadOrImport": "Dateien hochladen oder importieren",
   "files.cancel": "Abbrechen",
   "files.columnModified": "Geändert",
+  "files.columnActions": "Aktionen",
   "files.columnName": "Ihren Namen",
   "files.columnSize": "Größe",
   "files.columnType": "Typ",
diff --git a/src/frontend/src/locales/en.json b/src/frontend/src/locales/en.json
@@ -952,6 +952,7 @@
   "files.columnType": "Type",
   "files.columnSize": "Size",
   "files.columnModified": "Modified",
+  "files.columnActions": "Actions",
   "files.rename": "Rename",
   "files.download": "Download",
   "files.duplicate": "Duplicate",
diff --git a/src/frontend/src/locales/es.json b/src/frontend/src/locales/es.json
@@ -683,6 +683,7 @@
   "fileManager.uploadOrImport": "Subir o importar archivos",
   "files.cancel": "Cancelar",
   "files.columnModified": "Modificado",
+  "files.columnActions": "Acciones",
   "files.columnName": "Nombre",
   "files.columnSize": "Tamaño",
   "files.columnType": "Tipo",
diff --git a/src/frontend/src/locales/fr.json b/src/frontend/src/locales/fr.json
@@ -683,6 +683,7 @@
   "fileManager.uploadOrImport": "Télécharger ou importer des fichiers",
   "files.cancel": "Annuler",
   "files.columnModified": "Modifiée",
+  "files.columnActions": "Actions",
   "files.columnName": "Nom",
   "files.columnSize": "Taille",
   "files.columnType": "Type",
diff --git a/src/frontend/src/locales/ja.json b/src/frontend/src/locales/ja.json
@@ -683,6 +683,7 @@
   "fileManager.uploadOrImport": "ファイルのアップロードまたはインポート",
   "files.cancel": "キャンセル",
   "files.columnModified": "変更済み",
+  "files.columnActions": "アクション",
   "files.columnName": "名前",
   "files.columnSize": "サイズ",
   "files.columnType": "タイプ",
diff --git a/src/frontend/src/locales/pt.json b/src/frontend/src/locales/pt.json
@@ -683,6 +683,7 @@
   "fileManager.uploadOrImport": "Carregar ou importar arquivos",
   "files.cancel": "Cancelar",
   "files.columnModified": "Modificado",
+  "files.columnActions": "Ações",
   "files.columnName": "Nome",
   "files.columnSize": "Tamanho",
   "files.columnType": "Tipo",
diff --git a/src/frontend/src/locales/zh-Hans.json b/src/frontend/src/locales/zh-Hans.json
@@ -683,6 +683,7 @@
   "fileManager.uploadOrImport": "上传或导入文件",
   "files.cancel": "取消",
   "files.columnModified": "已修改",
+  "files.columnActions": "操作",
   "files.columnName": "名称",
   "files.columnSize": "大小",
   "files.columnType": "类型",
diff --git a/src/frontend/src/pages/MainPage/pages/filesPage/components/FilesTab.tsx b/src/frontend/src/pages/MainPage/pages/filesPage/components/FilesTab.tsx
@@ -1,4 +1,5 @@
 import type {
+  CellKeyDownEvent,
   ColDef,
   NewValueParams,
   SelectionChangedEvent,
@@ -63,12 +64,27 @@ const FilesTab = ({
   };
 
   const handleOpenRename = (id: string, name: string) => {
-    if (tableRef.current) {
-      tableRef.current.api.startEditingCell({
-        rowIndex: files?.findIndex((file) => file.id === id) ?? 0,
-        colKey: "name",
-      });
-    }
+    const rowIndex = files?.findIndex((file) => file.id === id) ?? 0;
+    tableRef.current?.api.startEditingCell({ rowIndex, colKey: "name" });
+    // Rename is triggered from a Radix dropdown item; when that menu closes it
+    // restores focus to its trigger button once, asynchronously, stealing focus
+    // from the cell editor. Re-assert focus on the editor input across a few
+    // frames so it outlasts that restore and a keyboard user can type
+    // immediately (WCAG 2.4.3 Focus Order).
+    let frame = 0;
+    const focusEditor = () => {
+      const input = document.querySelector<HTMLInputElement>(
+        ".ag-cell-inline-editing .ag-input-field-input",
+      );
+      if (input && document.activeElement !== input) {
+        input.focus();
+        input.select();
+      }
+      if (frame++ < 6) {
+        requestAnimationFrame(focusEditor);
+      }
+    };
+    requestAnimationFrame(focusEditor);
   };
 
   const uploadFile = useUploadFile({ multiple: true });
@@ -119,6 +135,42 @@ const FilesTab = ({
     }
   };
 
+  // AG Grid navigates cell-by-cell and never focuses the action button inside a
+  // cell, so keyboard users can't open the row actions menu. Open it when
+  // Enter/Space is pressed while the actions cell is focused (WCAG 2.1.1).
+  const handleCellKeyDown = (event: CellKeyDownEvent<FileType>) => {
+    const keyboardEvent = event.event as KeyboardEvent | undefined;
+    if (keyboardEvent?.key !== "Enter" && keyboardEvent?.key !== " ") {
+      return;
+    }
+    if (event.column?.getColId() !== "actions") {
+      return;
+    }
+    const target = keyboardEvent.target as HTMLElement | null;
+    // The key was already re-dispatched onto the trigger button: let Radix's own
+    // keyboard handler open the menu and don't recurse.
+    if (target?.tagName === "BUTTON") {
+      return;
+    }
+    const actionsButton = target
+      ?.closest?.('[role="gridcell"]')
+      ?.querySelector<HTMLElement>("button");
+    if (!actionsButton) {
+      return;
+    }
+    // Move focus onto the (otherwise unreachable) trigger and replay the key so
+    // the dropdown opens through its native handler, matching a mouse click.
+    keyboardEvent.preventDefault();
+    actionsButton.focus();
+    actionsButton.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: keyboardEvent.key,
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+  };
+
   const colDefs: ColDef[] = [
     {
       headerName: t("files.columnName"),
@@ -166,8 +218,9 @@ const FilesTab = ({
             params.data.progress === -1 ? (
               <span className="text-xs text-primary">
                 {t("files.uploadFailed")}{" "}
-                <span
-                  className="cursor-pointer text-accent-pink-foreground underline"
+                <button
+                  type="button"
+                  className="cursor-pointer text-accent-pink-foreground underline focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-1"
                   onClick={(e) => {
                     e.stopPropagation();
                     if (params.data.file) {
@@ -176,7 +229,7 @@ const FilesTab = ({
                   }}
                 >
                   {t("files.tryAgain")}
-                </span>
+                </button>
               </span>
             ) : (
               <></>
@@ -223,6 +276,12 @@ const FilesTab = ({
         "text-muted-foreground cursor-text select-text group-[.no-select-cells]:cursor-default group-[.no-select-cells]:select-none",
     },
     {
+      // Icon-only actions column: the header stays visually empty but keeps an
+      // accessible name (hidden via the `ag-sr-only-header` class) so the
+      // columnheader is not nameless (WCAG 4.1.2 / IBM aria_accessiblename_exists).
+      colId: "actions",
+      headerName: t("files.columnActions"),
+      headerClass: "ag-sr-only-header",
       maxWidth: 60,
       editable: false,
       resizable: false,
@@ -289,11 +348,23 @@ const FilesTab = ({
         <Button
           className="!px-3 md:!px-4 md:!pl-3.5"
           onClick={async (e) => {
-            e.currentTarget.blur();
+            const button = e.currentTarget;
+            // Keyboard-activated clicks report detail === 0. For mouse clicks
+            // we blur to dismiss the lingering tooltip (#13178); for keyboard
+            // we must return focus to the trigger after the native file picker
+            // closes so focus isn't dropped to <body> (WCAG 2.4.3).
+            const keyboardActivated = e.detail === 0;
+            if (!keyboardActivated) {
+              button.blur();
+            }
             await handleUpload();
+            if (keyboardActivated) {
+              button.focus();
+            }
           }}
           id="upload-file-btn"
           data-testid="upload-file-btn"
+          aria-label={t("files.uploadFiles")}
         >
           <ForwardedIconComponent
             name="Plus"
@@ -328,6 +399,7 @@ const FilesTab = ({
           <div className="flex items-center gap-2">
             {quantitySelected > 0 ? (
               <DeleteConfirmationModal
+                asChild
                 onConfirm={handleDelete}
                 description={"file" + (quantitySelected > 1 ? "s" : "")}
               >
@@ -336,6 +408,9 @@ const FilesTab = ({
                   className="flex items-center gap-2 !px-3 font-semibold md:!px-4 md:!pl-3.5"
                   loading={isDeleting}
                   data-testid="bulk-delete-btn"
+                  aria-label={t("files.deleteSelected", {
+                    count: quantitySelected,
+                  })}
                 >
                   <ForwardedIconComponent name="Trash2" className="h-4 w-4" />
                   <span className="hidden whitespace-nowrap md:inline">
@@ -377,6 +452,7 @@ const FilesTab = ({
                 ]}
                 rowSelection="multiple"
                 onSelectionChanged={handleSelectionChanged}
+                onCellKeyDown={handleCellKeyDown}
                 columnDefs={colDefs}
                 rowData={files.sort((a, b) => {
                   return sortByDate(
diff --git a/src/frontend/src/style/ag-theme-shadcn.css b/src/frontend/src/style/ag-theme-shadcn.css
@@ -114,6 +114,19 @@
   box-shadow: none !important;
   outline: none !important;
 }
+
+/* WCAG 2.4.7 Focus Visible: the borderless tables hide AG Grid's cell focus
+   outline for a clean look, which also hides KEYBOARD focus. Restore a visible
+   ring for keyboard navigation only via :focus-visible — a mouse click resolves
+   to :focus (not :focus-visible) on the grid cell, so pointer use stays quiet. */
+.ag-no-border .ag-cell:focus-visible,
+.ag-no-border .ag-cell-focus:not(.ag-cell-inline-editing):focus-visible,
+.ag-no-border .ag-header-cell:focus-visible,
+.ag-no-border .ag-row:focus-visible {
+  outline: 2px solid hsl(var(--ring)) !important;
+  outline-offset: -2px !important;
+  border-radius: 0.375rem !important;
+}
 .ag-no-border .ag-selection-checkbox {
   margin-right: 0px !important;
 }
@@ -196,3 +209,18 @@
 .ag-tool-mode .ag-layout-auto-height .ag-center-cols-viewport {
   min-height: 0px !important;
 }
+
+/* Visually hide the header label of icon-only action columns while keeping it
+   in the accessibility tree, so the columnheader has an accessible name
+   (WCAG 4.1.2 / IBM aria_accessiblename_exists) without showing header text. */
+.ag-sr-only-header .ag-header-cell-text {
+  position: absolute !important;
+  width: 1px !important;
+  height: 1px !important;
+  padding: 0 !important;
+  margin: -1px !important;
+  overflow: hidden !important;
+  clip: rect(0, 0, 0, 0) !important;
+  white-space: nowrap !important;
+  border: 0 !important;
+}
diff --git a/src/frontend/tests/a11y/baselines/chromium__assets-files-actions-menu.json b/src/frontend/tests/a11y/baselines/chromium__assets-files-actions-menu.json
@@ -0,0 +1,17 @@
+{
+  "label": "chromium__assets-files-actions-menu",
+  "description": "KNOWN a11y debt (tracked, not accepted as correct). The open Radix DropdownMenu portals its content to <body>, which sits outside any landmark, so IBM reports aria_content_in_landmark. This is an app-wide Radix limitation (menus, unlike aria-modal dialogs, are not landmark-exempt) and <main> is overflow-hidden so the menu cannot simply portal into it. Delete this file to resurface the violation in tests/a11y/files.a11y.spec.ts ('scans open row actions menu').",
+  "results": [
+    {
+      "ruleId": "aria_content_in_landmark",
+      "reasonId": "Fail_1",
+      "level": "violation",
+      "message": "Content is not within a landmark element",
+      "path": {
+        "dom": "/html[1]/body[1]/div[2]/div[1]",
+        "aria": "/document[1]/menu[1]"
+      },
+      "value": ["VIOLATION", "FAIL"]
+    }
+  ]
+}
diff --git a/src/frontend/tests/a11y/data-rich-routes.a11y.spec.ts b/src/frontend/tests/a11y/data-rich-routes.a11y.spec.ts
@@ -86,49 +86,9 @@ test.describe("data-rich route accessibility", () => {
     },
   );
 
-  test(
-    "scans files page with uploaded files",
-    { tag: ["@release", "@workspace"] },
-    async ({ page }) => {
-      await page.route("**/api/v2/files", async (route) => {
-        await route.fulfill({
-          json: [
-            {
-              id: "a11y-file-1",
-              user_id: "a11y-user",
-              provider: "local",
-              name: "quarterly-report",
-              path: "quarterly-report.pdf",
-              type: "pdf",
-              size: 428032,
-              created_at: "2026-06-01T10:00:00",
-              updated_at: "2026-06-15T13:30:00",
-            },
-            {
-              id: "a11y-file-2",
-              user_id: "a11y-user",
-              provider: "local",
-              name: "customer-import",
-              path: "customer-import.csv",
-              type: "csv",
-              size: 8192,
-              created_at: "2026-06-02T10:00:00",
-              updated_at: "2026-06-16T13:30:00",
-            },
-          ],
-        });
-      });
-
-      await openRoute(page, "/assets/files");
-      await expect(page.getByText("quarterly-report")).toBeVisible({
-        timeout: TIMEOUTS.standard,
-      });
-      await expect(page.getByTestId("search-store-input")).toBeVisible();
-      await waitForNetworkToSettle(page);
-
-      await page.runA11yScan("assets-files-data-rich");
-    },
-  );
+  // NOTE: the files page (/assets/files) has dedicated, full-state coverage in
+  // files.a11y.spec.ts (populated / empty / mobile / selected / actions menu /
+  // delete modal / rename editing + keyboard operability).
 
   test(
     "scans global variables page with saved variables",
diff --git a/src/frontend/tests/a11y/files.a11y.spec.ts b/src/frontend/tests/a11y/files.a11y.spec.ts
