From b619b8ae136a27cc1dfa71a7fc09d0a98c1bb3cc Mon Sep 17 00:00:00 2001
From: Arthur Bassi <arthur.bassi@luby.com.br>
Date: Fri, 28 Aug 2026 15:06:59 -0300
Subject: [PATCH 1/3] feat(work-orders): expose accessible names on board row
 flags

Give keyboard and screen-reader users color-independent labels
when setting, changing, or clearing a work-order flag.
---
 .../adv-parity-filter-sections.tsx            |  1 +
 .../list/table/cells/flag-cell.tsx            | 79 ++++++++++++-------
 .../_components/list/table/wo-table-cols.ts   |  2 +-
 .../_components/list/table/wo-table-head.tsx  | 47 ++++++-----
 .../list/table/wo-table-inline-row.tsx        |  7 +-
 src/domain/work-orders/flag-colors.ts         | 20 +++++
 .../(protected)/workorders/flag-cell.test.tsx | 53 +++++++++++++
 .../wo-table-row-completed-lock.test.tsx      |  4 +-
 .../domain/work-orders/flag-colors.test.ts    | 23 ++++++
 9 files changed, 181 insertions(+), 55 deletions(-)
 create mode 100644 src/test/app/(protected)/workorders/flag-cell.test.tsx
 create mode 100644 src/test/domain/work-orders/flag-colors.test.ts

diff --git a/src/app/(protected)/workorders/_components/list/advanced-search/adv-parity-filter-sections.tsx b/src/app/(protected)/workorders/_components/list/advanced-search/adv-parity-filter-sections.tsx
index 3bb9ecbd..c5189fab 100644
--- a/src/app/(protected)/workorders/_components/list/advanced-search/adv-parity-filter-sections.tsx
+++ b/src/app/(protected)/workorders/_components/list/advanced-search/adv-parity-filter-sections.tsx
@@ -41,6 +41,7 @@ function indicatorCount(draft: WorkOrderAdvancedFilters): number {
 function FlagColorDot({ value }: { value: string }) {
   return (
     <span
+      aria-hidden="true"
       className="size-3 shrink-0 rounded-full"
       style={{ background: value, border: "1px solid var(--color-border)" }}
     />
diff --git a/src/app/(protected)/workorders/_components/list/table/cells/flag-cell.tsx b/src/app/(protected)/workorders/_components/list/table/cells/flag-cell.tsx
index 05c9460a..3138b450 100644
--- a/src/app/(protected)/workorders/_components/list/table/cells/flag-cell.tsx
+++ b/src/app/(protected)/workorders/_components/list/table/cells/flag-cell.tsx
@@ -1,7 +1,7 @@
 import { useState } from "react";
 import { Flag, X } from "lucide-react";
 import { Popover } from "@mui/material";
-import { FLAG_COLORS } from "@/domain/work-orders/flag-colors";
+import { FLAG_COLORS, flagTriggerAccessibleName } from "@/domain/work-orders/flag-colors";
 
 type FlagCellProps = {
   color?: string | null;
@@ -11,11 +11,16 @@ type FlagCellProps = {
 
 export function FlagCell({ color, disabled, onChange }: FlagCellProps) {
   const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null);
+  const triggerName = flagTriggerAccessibleName(color);
+  const popoverOpen = Boolean(anchorEl);
 
   if (disabled) {
     return (
-      <span className="flex h-[22px] w-[22px] items-center justify-center opacity-30">
-        <Flag size={14} />
+      <span
+        className="flex h-[22px] w-[22px] items-center justify-center opacity-30"
+        aria-label={triggerName}
+      >
+        <Flag size={14} aria-hidden="true" />
       </span>
     );
   }
@@ -24,15 +29,19 @@ export function FlagCell({ color, disabled, onChange }: FlagCellProps) {
     <>
       <button
         type="button"
+        aria-label={triggerName}
+        aria-haspopup="dialog"
+        aria-expanded={popoverOpen}
+        title={triggerName}
         onClick={(e) => {
           e.stopPropagation();
           setAnchorEl(e.currentTarget);
         }}
-        title={color ? "Flagged — click to change" : "Add color flag"}
-        className="flex h-[22px] w-[22px] items-center justify-center transition-opacity hover:opacity-80"
+        className="flex h-[22px] w-[22px] items-center justify-center transition-opacity hover:opacity-80 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-[var(--color-primary)]"
       >
         <Flag
           size={14}
+          aria-hidden="true"
           strokeWidth={color ? 1.5 : 1.75}
           style={{
             color: color ?? "var(--color-text-muted)",
@@ -41,37 +50,47 @@ export function FlagCell({ color, disabled, onChange }: FlagCellProps) {
         />
       </button>
       <Popover
-        open={Boolean(anchorEl)}
+        open={popoverOpen}
         anchorEl={anchorEl}
         onClose={() => setAnchorEl(null)}
         anchorOrigin={{ vertical: "bottom", horizontal: "left" }}
         onClick={(e) => e.stopPropagation()}
-        slotProps={{ paper: { className: "rounded-lg border border-border p-2" } }}
+        slotProps={{
+          paper: {
+            className: "rounded-lg border border-border p-2",
+            "aria-label": "Choose flag color",
+          },
+        }}
       >
         <div className="grid grid-cols-4 gap-1.5">
-          {FLAG_COLORS.map((c) => (
-            <button
-              key={c.value}
-              type="button"
-              title={c.name}
-              onClick={() => {
-                onChange(c.value);
-                setAnchorEl(null);
-              }}
-              className="flex h-7 w-7 items-center justify-center rounded transition-transform hover:scale-110"
-            >
-              <span
-                className="rounded-full"
-                style={{
-                  width: 18,
-                  height: 18,
-                  background: c.value,
-                  boxShadow:
-                    color === c.value ? `0 0 0 2px var(--card), 0 0 0 4px ${c.value}` : "none",
+          {FLAG_COLORS.map((c) => {
+            const selected = color === c.value;
+            return (
+              <button
+                key={c.value}
+                type="button"
+                aria-label={c.name}
+                aria-pressed={selected}
+                title={c.name}
+                onClick={() => {
+                  onChange(c.value);
+                  setAnchorEl(null);
                 }}
-              />
-            </button>
-          ))}
+                className="flex h-7 w-7 items-center justify-center rounded transition-transform hover:scale-110 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-[var(--color-primary)]"
+              >
+                <span
+                  aria-hidden="true"
+                  className="rounded-full"
+                  style={{
+                    width: 18,
+                    height: 18,
+                    background: c.value,
+                    boxShadow: selected ? `0 0 0 2px var(--card), 0 0 0 4px ${c.value}` : "none",
+                  }}
+                />
+              </button>
+            );
+          })}
         </div>
         <button
           type="button"
@@ -81,7 +100,7 @@ export function FlagCell({ color, disabled, onChange }: FlagCellProps) {
           }}
           className="mt-2 flex w-full items-center gap-1.5 border-t border-border px-1 pt-2 text-xs text-[var(--color-text-secondary)] transition-colors hover:opacity-80"
         >
-          <X size={12} /> Clear flag
+          <X size={12} aria-hidden="true" /> Clear flag
         </button>
       </Popover>
     </>
diff --git a/src/app/(protected)/workorders/_components/list/table/wo-table-cols.ts b/src/app/(protected)/workorders/_components/list/table/wo-table-cols.ts
index 12194252..96b1caa2 100644
--- a/src/app/(protected)/workorders/_components/list/table/wo-table-cols.ts
+++ b/src/app/(protected)/workorders/_components/list/table/wo-table-cols.ts
@@ -1,6 +1,6 @@
 export const WO_TABLE_COLS = [
   { key: "grip", label: "", w: 28 },
-  { key: "flag", label: "", w: 28 },
+  { key: "flag", label: "", srLabel: "Flag", w: 28 },
   { key: "site", label: "SITE", w: 168 },
   { key: "wo", label: "WO", w: 120 },
   { key: "type", label: "TYPE OF WO", w: 108 },
diff --git a/src/app/(protected)/workorders/_components/list/table/wo-table-head.tsx b/src/app/(protected)/workorders/_components/list/table/wo-table-head.tsx
index 36309923..c490f17e 100644
--- a/src/app/(protected)/workorders/_components/list/table/wo-table-head.tsx
+++ b/src/app/(protected)/workorders/_components/list/table/wo-table-head.tsx
@@ -4,27 +4,32 @@ export function WoTableHead() {
   return (
     <thead className="sticky top-0 z-10">
       <tr>
-        {WO_TABLE_COLS.map((col) => (
-          <th
-            key={col.key}
-            style={{
-              width: col.w,
-              minWidth: col.w,
-              padding: "11px 14px",
-              textAlign: "left",
-              fontSize: 10.5,
-              fontWeight: 700,
-              textTransform: "uppercase",
-              letterSpacing: "0.06em",
-              color: "var(--foreground)",
-              whiteSpace: "nowrap",
-              background: "var(--color-bg-muted)",
-              borderBottom: "1px solid var(--border)",
-            }}
-          >
-            {col.label}
-          </th>
-        ))}
+        {WO_TABLE_COLS.map((col) => {
+          const srLabel = "srLabel" in col ? col.srLabel : undefined;
+          return (
+            <th
+              key={col.key}
+              scope="col"
+              style={{
+                width: col.w,
+                minWidth: col.w,
+                padding: "11px 14px",
+                textAlign: "left",
+                fontSize: 10.5,
+                fontWeight: 700,
+                textTransform: "uppercase",
+                letterSpacing: "0.06em",
+                color: "var(--foreground)",
+                whiteSpace: "nowrap",
+                background: "var(--color-bg-muted)",
+                borderBottom: "1px solid var(--border)",
+              }}
+            >
+              {col.label}
+              {Boolean(srLabel) && <span className="sr-only">{srLabel}</span>}
+            </th>
+          );
+        })}
       </tr>
     </thead>
   );
diff --git a/src/app/(protected)/workorders/_components/list/table/wo-table-inline-row.tsx b/src/app/(protected)/workorders/_components/list/table/wo-table-inline-row.tsx
index 79432d66..f6258ee0 100644
--- a/src/app/(protected)/workorders/_components/list/table/wo-table-inline-row.tsx
+++ b/src/app/(protected)/workorders/_components/list/table/wo-table-inline-row.tsx
@@ -118,7 +118,12 @@ export function WoTableInlineRow({
       <td style={{ padding: "0 0 0 6px" }} />
 
       <td style={{ padding: "0 2px 0 8px" }}>
-        <Flag size={14} strokeWidth={1.75} style={{ color: "var(--color-border)" }} />
+        <Flag
+          size={14}
+          strokeWidth={1.75}
+          aria-hidden="true"
+          style={{ color: "var(--color-border)" }}
+        />
       </td>
 
       <WoTableInlineRowCells
diff --git a/src/domain/work-orders/flag-colors.ts b/src/domain/work-orders/flag-colors.ts
index d4cf32a7..fe616bd8 100644
--- a/src/domain/work-orders/flag-colors.ts
+++ b/src/domain/work-orders/flag-colors.ts
@@ -11,3 +11,23 @@ export const FLAG_COLORS: { name: string; value: string }[] = [
 ];
 
 export const FLAG_COLOR_VALUES = FLAG_COLORS.map((c) => c.value);
+
+export function flagColorName(value: string | null | undefined): string | null {
+  if (!value) {
+    return null;
+  }
+  const normalized = value.toLowerCase();
+  return FLAG_COLORS.find((color) => color.value.toLowerCase() === normalized)?.name ?? null;
+}
+
+/** Accessible trigger name — never color-only. */
+export function flagTriggerAccessibleName(color: string | null | undefined): string {
+  const name = flagColorName(color);
+  if (name) {
+    return `${name} flag`;
+  }
+  if (color) {
+    return "Flagged";
+  }
+  return "Add flag";
+}
diff --git a/src/test/app/(protected)/workorders/flag-cell.test.tsx b/src/test/app/(protected)/workorders/flag-cell.test.tsx
new file mode 100644
index 00000000..2b0cb47f
--- /dev/null
+++ b/src/test/app/(protected)/workorders/flag-cell.test.tsx
@@ -0,0 +1,53 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { FlagCell } from "@/app/(protected)/workorders/_components/list/table/cells/flag-cell";
+import { WoTableHead } from "@/app/(protected)/workorders/_components/list/table/wo-table-head";
+
+describe("FlagCell", () => {
+  it("sets, changes, and clears a flag by named controls", () => {
+    const onChange = vi.fn();
+    const { rerender } = render(<FlagCell color={null} onChange={onChange} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Add flag" }));
+    fireEvent.click(screen.getByRole("button", { name: "Red" }));
+    expect(onChange).toHaveBeenCalledWith("#EF4444");
+
+    rerender(<FlagCell color="#EF4444" onChange={onChange} />);
+    expect(screen.getByRole("button", { name: "Red flag" })).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "Red flag" }));
+    fireEvent.click(screen.getByRole("button", { name: "Blue" }));
+    expect(onChange).toHaveBeenCalledWith("#3B82F6");
+
+    rerender(<FlagCell color="#3B82F6" onChange={onChange} />);
+    fireEvent.click(screen.getByRole("button", { name: "Blue flag" }));
+    fireEvent.click(screen.getByRole("button", { name: "Clear flag" }));
+    expect(onChange).toHaveBeenCalledWith(null);
+  });
+
+  it("exposes a non-color name when the hex is not in the palette", () => {
+    render(<FlagCell color="#000000" onChange={vi.fn()} />);
+    expect(screen.getByRole("button", { name: "Flagged" })).toBeInTheDocument();
+  });
+
+  it("names a disabled flag without exposing a button", () => {
+    const onChange = vi.fn();
+    render(<FlagCell color="#EF4444" disabled onChange={onChange} />);
+
+    expect(screen.getByLabelText("Red flag")).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Red flag" })).toBeNull();
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
+
+describe("WoTableHead flag column", () => {
+  it("exposes a screen-reader label for the flag column", () => {
+    render(
+      <table>
+        <WoTableHead />
+      </table>,
+    );
+
+    expect(screen.getByRole("columnheader", { name: "Flag" })).toBeInTheDocument();
+  });
+});
diff --git a/src/test/app/(protected)/workorders/wo-table-row-completed-lock.test.tsx b/src/test/app/(protected)/workorders/wo-table-row-completed-lock.test.tsx
index c49d8001..2c02e58c 100644
--- a/src/test/app/(protected)/workorders/wo-table-row-completed-lock.test.tsx
+++ b/src/test/app/(protected)/workorders/wo-table-row-completed-lock.test.tsx
@@ -98,8 +98,8 @@ describe("WoTableRow completed selective lock", () => {
       { withAuth: false },
     );
 
-    expect(screen.getByTitle("Add color flag")).toBeEnabled();
-    fireEvent.click(screen.getByTitle("Add color flag"));
+    expect(screen.getByRole("button", { name: "Add flag" })).toBeEnabled();
+    fireEvent.click(screen.getByRole("button", { name: "Add flag" }));
     expect(screen.getByText("Clear flag")).toBeInTheDocument();
     expect(screen.queryByTitle("Edit")).not.toBeInTheDocument();
     expect(screen.getByTitle("View details")).toBeInTheDocument();
diff --git a/src/test/domain/work-orders/flag-colors.test.ts b/src/test/domain/work-orders/flag-colors.test.ts
new file mode 100644
index 00000000..15ba9909
--- /dev/null
+++ b/src/test/domain/work-orders/flag-colors.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { flagColorName, flagTriggerAccessibleName } from "@/domain/work-orders/flag-colors";
+
+describe("flag color accessible names", () => {
+  it("resolves palette hex values to names", () => {
+    expect(flagColorName("#EF4444")).toBe("Red");
+    expect(flagColorName("#ef4444")).toBe("Red");
+    expect(flagColorName("#3B82F6")).toBe("Blue");
+  });
+
+  it("returns null for empty or unknown values", () => {
+    expect(flagColorName(null)).toBeNull();
+    expect(flagColorName(undefined)).toBeNull();
+    expect(flagColorName("")).toBeNull();
+    expect(flagColorName("#000000")).toBeNull();
+  });
+
+  it("builds trigger names that are not color-only", () => {
+    expect(flagTriggerAccessibleName(null)).toBe("Add flag");
+    expect(flagTriggerAccessibleName("#EF4444")).toBe("Red flag");
+    expect(flagTriggerAccessibleName("#000000")).toBe("Flagged");
+  });
+});

From 8d44b1868c9c1448dfdefd216d37bc585c134e6d Mon Sep 17 00:00:00 2001
From: Arthur Bassi <arthur.bassi@luby.com.br>
Date: Mon, 31 Aug 2026 09:49:09 -0300
Subject: [PATCH 2/3] fix(work-orders): expose disabled flag name via img role

---
 .../workorders/_components/list/table/cells/flag-cell.tsx       | 1 +
 src/test/app/(protected)/workorders/flag-cell.test.tsx          | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/app/(protected)/workorders/_components/list/table/cells/flag-cell.tsx b/src/app/(protected)/workorders/_components/list/table/cells/flag-cell.tsx
index 3138b450..e3a3972d 100644
--- a/src/app/(protected)/workorders/_components/list/table/cells/flag-cell.tsx
+++ b/src/app/(protected)/workorders/_components/list/table/cells/flag-cell.tsx
@@ -17,6 +17,7 @@ export function FlagCell({ color, disabled, onChange }: FlagCellProps) {
   if (disabled) {
     return (
       <span
+        role="img"
         className="flex h-[22px] w-[22px] items-center justify-center opacity-30"
         aria-label={triggerName}
       >
diff --git a/src/test/app/(protected)/workorders/flag-cell.test.tsx b/src/test/app/(protected)/workorders/flag-cell.test.tsx
index 2b0cb47f..1bc5cb46 100644
--- a/src/test/app/(protected)/workorders/flag-cell.test.tsx
+++ b/src/test/app/(protected)/workorders/flag-cell.test.tsx
@@ -34,7 +34,7 @@ describe("FlagCell", () => {
     const onChange = vi.fn();
     render(<FlagCell color="#EF4444" disabled onChange={onChange} />);
 
-    expect(screen.getByLabelText("Red flag")).toBeInTheDocument();
+    expect(screen.getByRole("img", { name: "Red flag" })).toBeInTheDocument();
     expect(screen.queryByRole("button", { name: "Red flag" })).toBeNull();
     expect(onChange).not.toHaveBeenCalled();
   });

From 065ebbd4035a45c6bfc57f3269e6d1b4d70cc128 Mon Sep 17 00:00:00 2001
From: Arthur Bassi <arthur.bassi@luby.com.br>
Date: Mon, 31 Aug 2026 11:46:04 -0300
Subject: [PATCH 3/3] fix(work-orders): expose flag picker as named dialog

---
 .../_components/list/table/cells/flag-cell.tsx     |  1 +
 .../app/(protected)/workorders/flag-cell.test.tsx  | 14 ++++++++++----
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/src/app/(protected)/workorders/_components/list/table/cells/flag-cell.tsx b/src/app/(protected)/workorders/_components/list/table/cells/flag-cell.tsx
index e3a3972d..ce17fa54 100644
--- a/src/app/(protected)/workorders/_components/list/table/cells/flag-cell.tsx
+++ b/src/app/(protected)/workorders/_components/list/table/cells/flag-cell.tsx
@@ -59,6 +59,7 @@ export function FlagCell({ color, disabled, onChange }: FlagCellProps) {
         slotProps={{
           paper: {
             className: "rounded-lg border border-border p-2",
+            role: "dialog",
             "aria-label": "Choose flag color",
           },
         }}
diff --git a/src/test/app/(protected)/workorders/flag-cell.test.tsx b/src/test/app/(protected)/workorders/flag-cell.test.tsx
index 1bc5cb46..db90e884 100644
--- a/src/test/app/(protected)/workorders/flag-cell.test.tsx
+++ b/src/test/app/(protected)/workorders/flag-cell.test.tsx
@@ -1,28 +1,34 @@
-import { fireEvent, render, screen } from "@testing-library/react";
+import { fireEvent, render, screen, within } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
 import { FlagCell } from "@/app/(protected)/workorders/_components/list/table/cells/flag-cell";
 import { WoTableHead } from "@/app/(protected)/workorders/_components/list/table/wo-table-head";
 
+function flagPickerDialog() {
+  return screen.getByRole("dialog", { name: "Choose flag color" });
+}
+
 describe("FlagCell", () => {
   it("sets, changes, and clears a flag by named controls", () => {
     const onChange = vi.fn();
     const { rerender } = render(<FlagCell color={null} onChange={onChange} />);
 
     fireEvent.click(screen.getByRole("button", { name: "Add flag" }));
-    fireEvent.click(screen.getByRole("button", { name: "Red" }));
+    fireEvent.click(within(flagPickerDialog()).getByRole("button", { name: "Red" }));
     expect(onChange).toHaveBeenCalledWith("#EF4444");
+    expect(screen.queryByRole("dialog", { name: "Choose flag color" })).toBeNull();
 
     rerender(<FlagCell color="#EF4444" onChange={onChange} />);
     expect(screen.getByRole("button", { name: "Red flag" })).toBeInTheDocument();
 
     fireEvent.click(screen.getByRole("button", { name: "Red flag" }));
-    fireEvent.click(screen.getByRole("button", { name: "Blue" }));
+    fireEvent.click(within(flagPickerDialog()).getByRole("button", { name: "Blue" }));
     expect(onChange).toHaveBeenCalledWith("#3B82F6");
 
     rerender(<FlagCell color="#3B82F6" onChange={onChange} />);
     fireEvent.click(screen.getByRole("button", { name: "Blue flag" }));
-    fireEvent.click(screen.getByRole("button", { name: "Clear flag" }));
+    fireEvent.click(within(flagPickerDialog()).getByRole("button", { name: "Clear flag" }));
     expect(onChange).toHaveBeenCalledWith(null);
+    expect(screen.queryByRole("dialog", { name: "Choose flag color" })).toBeNull();
   });
 
   it("exposes a non-color name when the hex is not in the palette", () => {