🎨 Palette: [UX improvement] - ContextSection 아코디언 접근성 및 키보드 네비게이션 향상

.Jules/palette.md

@@ -0,0 +1,6 @@
+## 2024-06-22 - Overview Stats 토글 버튼 키보드 접근성 개선
+**Learning:** `overview-stats` 컴포넌트의 설명 텍스트를 펼치거나 접는 `<button>` 요소에 키보드 포커스 스타일이 누락되어 있어, 키보드 내비게이션 사용자에게 현재 포커스 위치를 명확히 보여주지 못했습니다. `hover` 스타일은 있었으나 `focus-visible` 처리가 없어 접근성 결함이 있었습니다.
+**Action:** Tailwind CSS의 `focus-visible` 관련 유틸리티 클래스(`focus-visible:outline-none`, `focus-visible:ring-2`, `focus-visible:ring-ring`, `rounded-sm`)를 추가하여 탭(Tab) 키 이동 시 포커스 링이 보이도록 수정했습니다. 앞으로 대화형 컴포넌트를 설계할 때는 항상 키보드 접근성(focus states)을 염두에 두고 작업해야 합니다.
+## 2024-07-05 - ContextSection 아코디언 접근성 및 포커스 개선
+**Learning:** `ContextSection` 같은 사용자 정의 아코디언 컴포넌트를 만들 때, 버튼과 콘텐츠 영역이 스크린 리더에서 올바르게 연결되지 않는 문제가 자주 발생합니다. 또한 단순히 시각적인 hover 상태만 주어지고 키보드 focus 상태가 명확하지 않으면 키보드 탐색 사용자에게 불편함을 줍니다.
+**Action:** React의 `useId` 훅을 사용하여 버튼(`aria-controls`)과 콘텐츠 영역(`id`, `role="region"`, `aria-labelledby`)을 동적으로 안전하게 연결하는 패턴을 적용합니다. 장식용 아이콘은 `aria-hidden="true"`로 숨기고, 버튼에는 `focus-visible:ring` Tailwind 클래스를 일관되게 추가하여 키보드 접근성을 확보해야 합니다.

.gitignore

@@ -17,3 +17,4 @@ __pycache__/
 .jules/
 .state/
 .claude/worktrees/
+coverage/

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Unreleased]
+
+### 🎨 변경 사항 (UX / 접근성)
+
+- 웹 대시보드의 각종 로그아웃 버튼(`org-sidebar.tsx`, `org-header.tsx`, `no-organization-state.tsx`)에 스크린 리더용 `aria-label="Log out of your account"` (또는 `Sign out of your account`) 속성을 추가하여 접근성을 개선했습니다.

package.json

@@ -5,10 +5,13 @@
     "dev": "turbo dev",
     "build": "turbo build",
     "lint": "turbo lint",
-    "typecheck": "turbo typecheck"
+    "typecheck": "turbo typecheck",
+    "test": "turbo test",
+    "coverage": "turbo test -- --coverage"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3",
+    "@vitest/coverage-v8": "3.2.6",
     "eslint": "^9",
     "turbo": "^2.9.16",
     "typescript-eslint": "^8"

packages/web/package.json

@@ -41,12 +41,16 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.2.2",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/bcryptjs": "^2",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "@vitest/coverage-v8": "^3.2.6",
     "dotenv": "^17.4.2",
     "eslint-config-next": "^16.2.3",
+    "jsdom": "^29.1.1",
     "prisma": "^6",
     "shadcn": "^4.10.0",
     "tailwindcss": "^4",

packages/web/src/app/dashboard/[orgSlug]/sessions/[sessionId]/page.tsx

@@ -13,7 +13,7 @@ import {
   SessionFilesTab,
 } from '@/components/dashboard/session-files'
 import { useSessionDetail } from '@/hooks/use-dashboard-sessions'
-import { messagesToTimeline, formatSlashCommandText } from '@/lib/timeline-events'
+import { messagesToTimeline, buildTimelineGroups, formatSlashCommandText } from '@/lib/timeline-events'
 import { extractSessionFiles } from '@/lib/session-files'
 import {
   formatTokens,
@@ -46,6 +46,7 @@ export default function OrgSessionDetailPage({
     () => (data ? messagesToTimeline(data.messages) : []),
     [data],
   )
+  const groups = useMemo(() => buildTimelineGroups(events), [events])
   const files = useMemo(() => extractSessionFiles(events), [events])
   const [selectedIdx, setSelectedIdx] = useState<number | null>(0)
   const safeIdx =
@@ -221,6 +222,7 @@ export default function OrgSessionDetailPage({
             <div className="px-4 pt-3 pb-2">
               <SessionActivityRibbon
                 events={events}
+                groups={groups}
                 selectedIdx={safeIdx}
                 onSelect={setSelectedIdx}
                 sessionStartedAt={data.startedAt}
@@ -232,6 +234,7 @@ export default function OrgSessionDetailPage({
               <div className="border-r border-border min-h-0 overflow-hidden">
                 <EventList
                   events={events}
+                  groups={groups}
                   selectedIdx={safeIdx ?? -1}
                   onSelect={setSelectedIdx}
                   sessionStartedAt={data.startedAt}

packages/web/src/components/dashboard/event-list.tsx

@@ -3,13 +3,14 @@ import { List, type RowComponentProps } from "react-window";
 import { User, Bot, Wrench, ChevronRight } from "lucide-react";
 import {
   formatSlashCommandText,
-  buildTimelineGroups,
   type TimelineEvent,
+  type TimelineGroup,
 } from "@/lib/timeline-events";
 import { cn } from "@/lib/utils";
 
 type EventListProps = {
   events: TimelineEvent[];
+  groups: TimelineGroup[];
   selectedIdx: number;
   onSelect: (idx: number) => void;
   sessionStartedAt: string;
@@ -50,11 +51,10 @@ function formatElapsed(timestamp: string, sessionStartedAt: string): string {
 }
 
 function buildFlatRows(
-  events: TimelineEvent[],
+  groups: TimelineGroup[],
   expandedGroups: Set<number>,
   selectedIdx: number,
 ): FlatRow[] {
-  const groups = buildTimelineGroups(events);
   const rows: FlatRow[] = [];
   for (const group of groups) {
     if (group.kind === "single") {
@@ -261,15 +261,16 @@ function Row({
 
 export function EventList({
   events,
+  groups,
   selectedIdx,
   onSelect,
   sessionStartedAt,
   expandedGroups,
   onToggleGroup,
 }: EventListProps) {
   const rows = useMemo(
-    () => buildFlatRows(events, expandedGroups, selectedIdx),
-    [events, expandedGroups, selectedIdx],
+    () => buildFlatRows(groups, expandedGroups, selectedIdx),
+    [groups, expandedGroups, selectedIdx],
   );
 
   if (events.length === 0) {

packages/web/src/components/dashboard/no-organization-state.tsx

@@ -37,6 +37,7 @@ export function NoOrganizationState({
             <button
               onClick={() => signOut({ callbackUrl: '/login' })}
               className="text-sm text-destructive hover:underline"
+              aria-label="Log out of your account"
             >
               Log out
             </button>

packages/web/src/components/dashboard/overview-stats.tsx

@@ -88,7 +88,7 @@ export function OverviewStats({
         id="overview-stats-explanation-toggle"
         aria-expanded={expanded}
         aria-controls="overview-stats-explanation"
-        className="mt-4 flex items-center gap-2 text-xs text-muted-foreground hover:text-foreground transition-colors"
+        className="mt-4 flex items-center gap-2 text-xs text-muted-foreground hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-colors rounded-sm"
       >
         <span
           aria-hidden="true"

packages/web/src/components/dashboard/reports/context-section.test.tsx

@@ -0,0 +1,80 @@
+import React from 'react'
+import { render, screen, fireEvent, cleanup } from '@testing-library/react'
+import { describe, it, expect, afterEach } from 'vitest'
+import { ContextSection } from './context-section'
+
+/** @vitest-environment jsdom */
+
+describe('ContextSection', () => {
+  afterEach(() => {
+    cleanup()
+  })
+
+  it('renders title correctly', () => {
+    render(
+      <ContextSection title="Test Title">
+        <p>Test Content</p>
+      </ContextSection>
+    )
+    expect(screen.getByText('Test Title')).toBeDefined()
+  })
+
+  it('toggles content visibility on click', () => {
+    render(
+      <ContextSection title="Test Title">
+        <div data-testid="content">Test Content</div>
+      </ContextSection>
+    )
+
+    // Initially closed
+    expect(screen.queryByTestId('content')).toBeNull()
+    const button = screen.getByRole('button')
+    expect(button.getAttribute('aria-expanded')).toBe('false')
+
+    // Click to open
+    fireEvent.click(button)
+    expect(screen.getByTestId('content')).toBeDefined()
+    expect(button.getAttribute('aria-expanded')).toBe('true')
+
+    // Click to close
+    fireEvent.click(button)
+    expect(screen.queryByTestId('content')).toBeNull()
+    expect(button.getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('respects defaultOpen prop', () => {
+    render(
+      <ContextSection title="Test Title" defaultOpen={true}>
+        <div data-testid="content">Test Content</div>
+      </ContextSection>
+    )
+
+    expect(screen.getByTestId('content')).toBeDefined()
+    const button = screen.getByRole('button')
+    expect(button.getAttribute('aria-expanded')).toBe('true')
+  })
+
+  it('has correct ARIA attributes for accessibility', () => {
+    render(
+      <ContextSection title="Test Title" defaultOpen={true}>
+        <div data-testid="content">Test Content</div>
+      </ContextSection>
+    )
+
+    const button = screen.getByRole('button')
+    const region = screen.getByRole('region')
+
+    const buttonControls = button.getAttribute('aria-controls')
+    const regionId = region.getAttribute('id')
+    const regionLabelledBy = region.getAttribute('aria-labelledby')
+    const buttonId = button.getAttribute('id')
+
+    expect(buttonControls).toBeTruthy()
+    expect(regionId).toBeTruthy()
+    expect(buttonControls).toBe(regionId)
+
+    expect(regionLabelledBy).toBeTruthy()
+    expect(buttonId).toBeTruthy()
+    expect(regionLabelledBy).toBe(buttonId)
+  })
+})

packages/web/src/components/dashboard/reports/context-section.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { useState, type ReactNode } from 'react'
+import React, { useState, useId, type ReactNode } from 'react'
 import { ChevronDown, ChevronUp } from 'lucide-react'
 import { cn } from '@/lib/utils'
 
@@ -12,27 +12,38 @@ interface ContextSectionProps {
 
 export function ContextSection({ title, children, defaultOpen = false }: ContextSectionProps) {
   const [open, setOpen] = useState(defaultOpen)
+  const id = useId()
+  const headerId = `${id}-header`
+  const contentId = `${id}-content`
 
   return (
     <div className="rounded-xl bg-card ring-1 ring-foreground/10 overflow-hidden">
       <button
+        id={headerId}
         type="button"
         onClick={() => setOpen((v) => !v)}
         className={cn(
-          'w-full flex items-center justify-between px-4 py-3 text-left',
+          'w-full flex items-center justify-between px-4 py-3 text-left outline-none rounded-sm',
           'hover:bg-card-elevated transition-colors',
+          'focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset'
         )}
         aria-expanded={open}
+        aria-controls={contentId}
       >
         <h2 className="text-base font-medium">{title}</h2>
         {open ? (
-          <ChevronUp className="h-4 w-4 text-muted-foreground" />
+          <ChevronUp aria-hidden="true" className="h-4 w-4 text-muted-foreground" />
         ) : (
-          <ChevronDown className="h-4 w-4 text-muted-foreground" />
+          <ChevronDown aria-hidden="true" className="h-4 w-4 text-muted-foreground" />
         )}
       </button>
       {open && (
-        <div className="px-4 pb-4 pt-1">
+        <div
+          id={contentId}
+          role="region"
+          aria-labelledby={headerId}
+          className="px-4 pb-4 pt-1"
+        >
           {children}
         </div>
       )}

packages/web/src/components/dashboard/reports/weekly-flow-chart.tsx

@@ -12,6 +12,7 @@ import {
   Legend,
   type TooltipProps,
 } from 'recharts'
+import { useMemo } from 'react'
 import { parseISO } from 'date-fns'
 import { formatTokens } from '@/lib/format'
 import type { DailySeriesPoint } from '@/types/reports'
@@ -57,18 +58,22 @@ function sumTokens(p: DailySeriesPoint): number {
 }
 
 export function WeeklyFlowChart({ thisWeek, prevWeek }: WeeklyFlowChartProps) {
-  // 요일 기준으로 병합 (월~일 7개 슬롯)
-  const dayNames = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
-  const data: ChartRow[] = dayNames.map((day) => ({ day, thisWeekTokens: 0, prevWeekTokens: 0 }))
+  const data = useMemo(() => {
+    // 요일 기준으로 병합 (월~일 7개 슬롯)
+    const dayNames = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
+    const result: ChartRow[] = dayNames.map((day) => ({ day, thisWeekTokens: 0, prevWeekTokens: 0 }))
 
-  for (const p of thisWeek) {
-    const idx = dayIndex(p.date)
-    if (idx >= 0) data[idx].thisWeekTokens += sumTokens(p)
-  }
-  for (const p of prevWeek) {
-    const idx = dayIndex(p.date)
-    if (idx >= 0) data[idx].prevWeekTokens += sumTokens(p)
-  }
+    for (const p of thisWeek) {
+      const idx = dayIndex(p.date)
+      if (idx >= 0) result[idx].thisWeekTokens += sumTokens(p)
+    }
+    for (const p of prevWeek) {
+      const idx = dayIndex(p.date)
+      if (idx >= 0) result[idx].prevWeekTokens += sumTokens(p)
+    }
+
+    return result
+  }, [thisWeek, prevWeek])
 
   return (
     <ResponsiveContainer width="100%" height={260}>

packages/web/src/components/dashboard/session-activity-ribbon.tsx

@@ -1,16 +1,17 @@
 'use client'
 
-import { useMemo, useState, useRef } from 'react'
+import { useState, useRef } from 'react'
 import {
   formatSlashCommandText,
-  buildTimelineGroups,
   type TimelineEvent,
+  type TimelineGroup,
 } from '@/lib/timeline-events'
 import { formatTokens, formatCost, formatRelativeTime } from '@/lib/format'
 import { segmentVisuals } from './session-ribbon-visuals'
 
 type Props = {
   events: TimelineEvent[]
+  groups: TimelineGroup[]
   selectedIdx: number | null
   onSelect: (idx: number) => void
   sessionStartedAt: string
@@ -147,6 +148,7 @@ function MergedTooltipBody({
 
 export function SessionActivityRibbon({
   events,
+  groups,
   selectedIdx,
   onSelect,
   sessionStartedAt,
@@ -156,8 +158,6 @@ export function SessionActivityRibbon({
   const [hover, setHover] = useState<HoverState | null>(null)
   const containerRef = useRef<HTMLDivElement>(null)
 
-  const groups = useMemo(() => buildTimelineGroups(events), [events])
-
   if (events.length === 0) return null
 
   const trackMouse = (e: React.MouseEvent) => {

packages/web/src/components/dashboard/token-usage-chart.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import { useMemo } from 'react'
 import { AreaChart, Area, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer, TooltipProps } from 'recharts'
 import { formatTokens, formatCost } from '@/lib/format'
 import type { UsageSeries } from '@argos/shared'
@@ -43,15 +44,17 @@ function CustomTooltip({ active, payload, label }: TooltipProps<number, string>)
 }
 
 export function TokenUsageChart({ data }: TokenUsageChartProps) {
-  const chartData = data.map(d => {
-    const date = new Date(d.date)
-    return {
-      date: format(date, 'MMM d'),
-      fullDate: format(date, 'MMM d, yyyy'),
-      input: d.inputTokens,
-      output: d.outputTokens,
-    }
-  })
+  const chartData = useMemo(() => {
+    return data.map(d => {
+      const date = new Date(d.date)
+      return {
+        date: format(date, 'MMM d'),
+        fullDate: format(date, 'MMM d, yyyy'),
+        input: d.inputTokens,
+        output: d.outputTokens,
+      }
+    })
+  }, [data])
 
   return (
     <ResponsiveContainer width="100%" height={300}>