🎨 Palette: [UX improvement] Enhance accessibility of collapsible table groups

.jules/palette.md

@@ -0,0 +1,4 @@
+## 2024-05-24 - Accessibility for Collapsible Table Groupings
+
+**Learning:** Collapsible table groupings (`tbody` rows expanding/collapsing on toggle) were missing `aria-controls` bindings to screen readers, preventing them from understanding the relationship between the toggle and the controlled content.
+**Action:** When implementing expand/collapse functionalities, always add an `id` to the controlled region (like `tbody`) and link it back to the toggle button via `aria-controls`, in addition to `aria-expanded`.

apps/app/app/components/ActorTable.tsx

@@ -148,14 +148,16 @@ export function ActorTable({
         ) : (
           groups.map(([type, items]) => {
             const isOpen = !collapsed.has(type);
+            const groupId = `actor-group-${type}`;
             return (
-              <tbody key={type}>
+              <tbody key={type} id={groupId}>
                 <tr className="border-t border-border bg-muted/30">
                   <td colSpan={COLUMN_COUNT} className="py-1.5 pr-3 pl-4">
                     <button
                       type="button"
                       onClick={() => toggle(type)}
                       aria-expanded={isOpen}
+                      aria-controls={groupId}
                       className="inline-flex items-center gap-2 rounded-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
                     >
                       <ChevronRight

apps/app/app/components/UsecaseTable.tsx

@@ -193,14 +193,16 @@ export function UsecaseTable({
         ) : (
           groups.map(([level, items]) => {
             const isOpen = !collapsed.has(level);
+            const groupId = `usecase-group-${level}`;
             return (
-              <tbody key={level}>
+              <tbody key={level} id={groupId}>
                 <tr className="border-t border-border bg-muted/30">
                   <td colSpan={COLUMN_COUNT} className="py-1.5 pr-3 pl-4">
                     <button
                       type="button"
                       onClick={() => toggle(level)}
                       aria-expanded={isOpen}
+                      aria-controls={groupId}
                       className="inline-flex items-center gap-2 rounded-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
                     >
                       <ChevronRight

apps/cli/tests/e2e-cli/UC-033.test.ts

@@ -27,7 +27,9 @@ describe("UC-033 CLI - Learn how to use vspec", () => {
       );
       expect(result.stdout).toContain("vspec usecase add-stakeholder");
       expect(result.stdout).toContain("Existing use case edits");
-      expect(result.stdout).toContain("`vspec step add` appends");
+      expect(result.stdout).toContain(
+        "Use `vspec step add --at <n>` to insert a new step"
+      );
       expect(result.stdout).toContain(
         "vspec scenario add POCKET-001 --type EXTENSION --at 2a"
       );