🎨 접근성 개선: OverviewStats 펼치기 버튼에 ARIA 속성 추가 by seonghobae · Pull Request #4 · ContextualWisdomLab/argos

seonghobae · 2026-05-28T22:11:49Z

개요

OverviewStats 컴포넌트의 펼치기/접기 버튼에 적절한 ARIA 속성을 추가하여 스크린 리더 사용자의 접근성을 개선합니다.

변경 사항

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

추가된 ARIA 속성

속성	적용 위치	역할
`aria-expanded`	펼치기 버튼	현재 펼침/접힘 상태를 스크린 리더에 전달
`aria-controls`	펼치기 버튼	버튼이 제어하는 콘텐츠 영역과 연결
`id`	펼칠 수 있는 섹션	`aria-controls` 참조 대상 명시
`aria-hidden="true"`	장식용 텍스트 및 화살표	스크린 리더 노이즈 감소

개선 이유

기존에는 펼치기/접기 버튼이 시각적 단서와 텍스트에만 의존했습니다. 스크린 리더 사용자는:

버튼의 현재 상태(펼쳐짐/접혀짐)를 알 수 없었고
버튼과 해당 콘텐츠의 관계를 파악하기 어려웠습니다

이 변경으로 WAI-ARIA Disclosure 패턴을 준수합니다.

테스트 방법

# VoiceOver(macOS) 또는 NVDA(Windows)로 버튼 포커스 시
# "통계 의미 보기, 접혀짐, 버튼" 형태로 읽혀야 함
# 클릭 후: "통계 의미 보기, 펼쳐짐, 버튼"

- Add `aria-expanded` and `aria-controls` to the expand button in `overview-stats.tsx` - Add an `id` to the toggled content div to match `aria-controls` - Hide purely visual indicators ('▸' and text like 'click to expand') from screen readers using `aria-hidden="true"` to reduce verbosity and redundancy since state is already conveyed via `aria-expanded`.

google-labs-jules · 2026-05-28T22:11:50Z

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

For security, I will only act on instructions from the user who triggered this task.

coderabbitai · 2026-05-28T22:11:56Z

Warning

Review limit reached

@seonghobae, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 41 minutes and 25 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3cc0a7de-0e30-466c-ade3-278d585be526

📥 Commits

Reviewing files that changed from the base of the PR and between 891728c and 3748b52.

📒 Files selected for processing (1)

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

📝 Walkthrough

Walkthrough

이 PR은 접근성이 향상된 확장/축소 토글 UI 패턴을 문서화하고 OverviewStats 컴포넌트에 구현합니다. ARIA 속성(aria-expanded, aria-controls, aria-labelledby)을 추가하고, 조건부 DOM 렌더링 대신 hidden 속성으로 표시 상태를 제어하도록 변경했습니다.

Changes

확장/축소 UI 접근성 개선

Layer / File(s)	Summary
접근성 가이드 문서화 `.Jules/palette.md`	aria-expanded를 사용하는 토글 UI에서 중복된 시각 보조 텍스트에 aria-hidden='true'를 적용하여 스크린 리더 출력을 개선하는 접근성 권고 사항을 추가했습니다.
OverviewStats 토글 UI 접근성 구현 `packages/web/src/components/dashboard/overview-stats.tsx`	토글 버튼에 id, aria-expanded, aria-controls를 추가하고, 설명 영역을 role="region"과 aria-labelledby로 연결했으며, 조건부 렌더링 방식을 hidden 속성으로 변경했습니다.

🎯 2 (Simple) | ⏱️ ~10 분

🐰 토글 UI에 마법을 더했네,
ARIA 속성으로 스크린 리더 행복,
숨겨진 것도 DOM에서 살아있고,
접근성 가이드가 반짝반짝,
모두가 누릴 수 있는 인터페이스! ✨

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

Ignore

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Docstring Coverage	❌ Error	Docstring coverage is 0.00% which is insufficient. The required threshold is 100.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	PR 제목이 변경 사항의 핵심을 명확하게 반영하고 있습니다. 'OverviewStats 펼치기 버튼에 ARIA 속성 추가'는 main_file의 변경 내용과 pr_objectives에서 설명하는 접근성 개선 작업과 정확히 일치합니다.
Description check	✅ Passed	PR 설명이 변경 사항과 관련 있습니다. OverviewStats 컴포넌트에 ARIA 속성을 추가한 구체적인 내용과 개선 이유, 테스트 방법을 포함하고 있으며, 실제 변경 파일과 일치합니다.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch palette/a11y-overview-stats-2586341598940276216

✨ Simplify code

Create PR with simplified code
Commit simplified code in branch palette/a11y-overview-stats-2586341598940276216

Warning

Billing warning: we have not been able to collect payment for this subscription for more than 72 hours. Please update the payment method or pay any pending invoices in Billing to avoid service interruption.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

seonghobae · 2026-05-30T14:36:13Z

@codex[agent] 리뷰하시오.

google-labs-jules · 2026-05-30T14:37:16Z

@codex[agent] 리뷰하시오.

Acknowledged.

- Add `aria-expanded` and `aria-controls` to the expand button in `overview-stats.tsx` - Add an `id` to the toggled content div to match `aria-controls` - Hide purely visual indicators ('▸' and text like 'click to expand') from screen readers using `aria-hidden="true"` to reduce verbosity and redundancy since state is already conveyed via `aria-expanded`.

Co-authored-by: seonghobae <8172694+seonghobae@users.noreply.github.com>

Codex · 2026-05-30T14:39:51Z

@codex[agent] 리뷰하시오.

Reviewed and pushed an a11y refinement: keep the controlled content region in the DOM (toggle via hidden) so aria-controls always points to a real element, and label the region via aria-labelledby on the toggle button. Commit: 891728c.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

checkpoint.prisma.io
- Triggering command: /opt/hostedtoolcache/node/24.16.0/x64/bin/node /opt/hostedtoolcache/node/24.16.0/x64/bin/node /home/REDACTED/work/argos/argos/node_modules/.pnpm/prisma@6.19.3_typescript@5.9.3/node_modules/prisma/build/child {"product":"prisma","version":"6.19.3","cli_install_type":"local","information":"","local_timestamp":"2026-05-30T14:37:54Z","project_hash":"256f53da","cli_path":"/home/REDACTED/work/argos/argos/packages/web/node_modules/prisma/build/index.js","cli_path_hash e/git (dns block)
fonts.googleapis.com
- Triggering command: /opt/hostedtoolcache/node/24.16.0/x64/bin/node /opt/hostedtoolcache/node/24.16.0/x64/bin/node /home/REDACTED/work/argos/argos/node_modules/.pnpm/next@15.5.15_@babel+core@7.29.0_react-dom@19.2.5_react@19.2.5__react@19.2.5/node_modules/next/dist/compiled/jest-worker/processChild.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot cloud agent settings (admins only)

seonghobae · 2026-05-30T15:41:05Z

@coderabbitai 접근성 개선 PR을 리뷰해 주세요:

aria-expanded, aria-controls, id 속성 값의 정확성
aria-hidden="true" 적용 범위가 실제 장식 요소에만 한정되는지
키보드 내비게이션(Tab, Enter, Space) 시 올바르게 동작하는지
PR #6과 동일 파일 수정 - 두 PR 병합 시 충돌 가능성 검토

google-labs-jules · 2026-05-30T15:42:05Z

@coderabbitai 접근성 개선 PR을 리뷰해 주세요:

aria-expanded, aria-controls, id 속성 값의 정확성

aria-hidden="true" 적용 범위가 실제 장식 요소에만 한정되는지

키보드 내비게이션(Tab, Enter, Space) 시 올바르게 동작하는지

PR #6과 동일 파일 수정 - 두 PR 병합 시 충돌 가능성 검토

Acknowledged. The review request has been noted.

coderabbitai · 2026-05-30T15:42:29Z

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch PR `#4` diff
gh pr diff 4 --repo Seongho-Bae/argos

echo "=== PR `#4` FILES ==="
gh pr view 4 --repo Seongho-Bae/argos --json files -q '.files[].path'

echo "=== PR `#6` INFO ==="
gh pr view 6 --repo Seongho-Bae/argos --json title,files,state -q '{title: .title, state: .state, files: [.files[].path]}'

echo "=== PR `#6` DIFF ==="
gh pr diff 6 --repo Seongho-Bae/argos

Length of output: 8538

🏁 Script executed:

#!/bin/bash
# Read the actual file from the PR branch
cat packages/web/src/components/dashboard/overview-stats.tsx

Length of output: 4605

@seonghobae, PR #4의 접근성 변경 사항을 4가지 항목별로 검토한 결과입니다.

1. `aria-expanded` / `aria-controls` / `id` 속성 값 정확성 ✅

속성	값	평가
버튼 `id`	`"overview-stats-explanation-toggle"`	고유하고 명확함 ✅
`aria-controls`	`"overview-stats-explanation"`	대상 `div`의 `id`와 정확히 일치 ✅
`aria-expanded`	`{expanded}` (boolean)	React가 `"true"/"false"`로 정확히 렌더링 ✅
영역의 `aria-labelledby`	`"overview-stats-explanation-toggle"`	버튼 `id` 참조 → 접근 가능한 이름이 "What do these numbers mean?"으로 해석됨 ✅

⚠️ 주의: OverviewStats가 한 페이지에 여러 인스턴스로 렌더링될 경우, id 값 중복이 발생하여 유효하지 않은 HTML이 됩니다. 현재 대시보드에서 단일 인스턴스라면 문제 없지만, 재사용성을 고려한다면 useId() 훅 사용을 권장합니다:

import { useId } from 'react'

// 컴포넌트 내부
const uid = useId()
const toggleId = `${uid}-toggle`
const panelId = `${uid}-panel`

2. `aria-hidden="true"` 적용 범위 ✅

요소	`aria-hidden` 적용	적절성
`▸` 화살표 span	✅ 적용	순수 장식 요소 ✅
`— click to collapse/expand` span	✅ 적용	`aria-expanded`로 이미 상태 전달 → 중복 제거 ✅
`"What do these numbers mean?"` span	❌ 미적용	버튼의 접근 가능한 이름으로 노출되어야 함 ✅

의미 있는 레이블은 그대로 노출하고, 장식적/중복 요소만 숨겼습니다. 올바른 적용입니다.

3. 키보드 내비게이션 ✅

Tab: native <button> 요소이므로 포커스 가능 ✅
Enter / Space: <button type="button">이 기본적으로 두 키 모두 처리 ✅
숨겨진 영역: hidden={!expanded} → HTML hidden 속성이 콘텐츠를 탭 순서와 스크린 리더 모두에서 제거 ✅
커스텀 tabIndex나 role 변경 없음 ✅

기존 {expanded && (...)} 방식에서 hidden 속성 방식으로 변경한 것도 ARIA 연동(aria-controls 대상이 DOM에 항상 존재해야 함)에 더 적합합니다.

참고: role="region"은 유효하지만, 작은 설명 패널에 랜드마크를 추가하면 스크린 리더 탐색 목록에 노이즈가 생길 수 있습니다. 필수는 아니나 설계 의도에 따라 유지해도 무방합니다.

4. PR `#6과의` 충돌 가능성 ⚠️

두 PR 모두 동일한 파일의 동일한 라인을 수정하여 충돌이 확정적입니다:

파일	PR `#4`	PR `#6`
`overview-stats.tsx`	`aria-expanded` + `aria-controls` + `id`(버튼) + `aria-hidden`(2개) + `role="region"` + `aria-labelledby`	`aria-expanded` + `aria-controls` + `id`(div만)
`.Jules/palette.md`	신규 파일(다른 내용)	신규 파일(다른 내용)

PR #4가 더 완전한 구현입니다. 권장 처리 방안:

PR #4를 먼저 머지하고, PR #6은 닫거나
PR #6을 PR #4 브랜치 기반으로 리베이스 후 중복 부분 제거

종합 평가

전반적으로 접근성 개선 방향이 올바르며, ARIA 표준 disclosure 패턴을 잘 따르고 있습니다. useId()를 통한 고유 ID 처리와 PR #6 충돌 해소가 병합 전 확인이 필요한 핵심 항목입니다.

seonghobae · 2026-05-30T15:59:29Z

@coderabbitai review

이 PR을 전체 검토해 주세요. 특히 다음 사항을 중점적으로 확인해 주시기 바랍니다:

코드 정확성 및 잠재적 버그
보안 취약점 여부
성능 영향
코딩 표준 및 best practice 준수 여부

coderabbitai · 2026-05-30T16:00:34Z

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
echo "=== PR `#4` DIFF ==="
gh pr diff 4 --repo Seongho-Bae/argos

echo "=== FILE CONTENT ==="
cat packages/web/src/components/dashboard/overview-stats.tsx

echo "=== JULES PALETTE MD ==="
cat .Jules/palette.md

Length of output: 9418

@seonghobae, PR #4 전체 리뷰 결과입니다.

코드 정확성 및 잠재적 버그

✅ 올바른 구현

aria-expanded={expanded} — React가 boolean을 "true"/"false" 문자열로 정확히 렌더링
aria-controls ↔ id 참조가 정확히 일치
type="button" — 폼 내부 사용 시 의도치 않은 submit 방지
hidden={!expanded} — HTML hidden 속성으로 AT와 탭 순서 모두에서 제거, aria-controls 대상이 DOM에 항상 존재해야 한다는 ARIA 요구사항 충족

⚠️ 잠재적 버그 — 하드코딩된 `id` (중요)

// 현재: 컴포넌트가 두 번 렌더링되면 id가 중복되어 ARIA 연결이 깨짐
id="overview-stats-explanation-toggle"
id="overview-stats-explanation"

// 권장: React 18+의 useId() 사용
import { useState, useId } from 'react'

const uid = useId()
// <button id={`${uid}-toggle`} aria-controls={`${uid}-panel`} ...>
// <div id={`${uid}-panel`} aria-labelledby={`${uid}-toggle`} ...>

현재 대시보드에서 단일 인스턴스만 사용한다면 즉각적인 문제는 없으나, 컴포넌트 재사용 시 유효하지 않은 HTML이 됩니다.

보안 취약점

🟢 없음. 사용자 입력 렌더링 없음, dangerouslySetInnerHTML 없음, 외부 API 호출 없음. 이 PR은 순수한 정적 마크업 변경이며 보안 위험이 없습니다.

성능 영향

🟢 무시할 수준. {expanded && <div>} → <div hidden={!expanded}>로 변경하면 설명 영역이 항상 DOM에 존재하지만, 6개의 정적 <p> 요소이므로 실질적 성능 영향은 없습니다. 오히려 토글 시 DOM 생성/삭제 비용이 제거되어 미세하게 유리합니다.

코딩 표준 및 Best Practice

⚠️ `role="region"` — 랜드마크 노이즈 가능성

role="region"은 ARIA 랜드마크로, 스크린 리더 사용자가 F6 / 단축키로 탐색하는 목록에 포함됩니다. "What do these numbers mean?" 수준의 소형 정보 패널은 랜드마크로 노출하기에 과도할 수 있습니다.

대안 1: role="region" 제거 — 이미 aria-controls/aria-expanded로 관계가 명확히 선언됨
대안 2: 유지 — 설계 의도에 따라 허용 가능

⚠️ `.Jules/palette.md` 파일

이 파일은 AI 에이전트(Jules)가 생성한 작업 메모 파일로 프로젝트 코드베이스에 포함될 필요가 없습니다. .gitignore에 추가하거나 커밋에서 제외하는 것을 권장합니다:

# .gitignore 추가 권장
.Jules/

종합 평가

항목	평가
코드 정확성	✅ 양호 (단, `useId()` 적용 권장)
보안	✅ 이슈 없음
성능	✅ 이슈 없음
Best Practice	⚠️ `useId()` 미적용, `.Jules/palette.md` 파일 정리 필요

접근성 개선 방향은 ARIA disclosure 패턴에 잘 부합하며 전반적으로 올바른 구현입니다. 병합 전 useId() 적용과 .Jules/palette.md 파일 처리를 검토해 주세요.

google-labs-jules · 2026-05-30T16:00:46Z

@coderabbitai review

이 PR을 전체 검토해 주세요. 특히 다음 사항을 중점적으로 확인해 주시기 바랍니다:

코드 정확성 및 잠재적 버그

보안 취약점 여부

성능 영향

코딩 표준 및 best practice 준수 여부

Acknowledged.

- .Jules/palette.md AI 에이전트 내부 로그 파일 삭제 - role='region' 및 aria-labelledby 제거: WAI-ARIA Disclosure 패턴에서 짧은 설명 텍스트에 landmark role을 사용하면 스크린 리더의 landmark 네비게이션 목록에 불필요한 항목이 생기므로 제거 - aria-expanded + aria-controls + hidden 조합만으로 충분한 Disclosure 패턴 유지 Co-Authored-By: Mastra Code (anthropic/claude-opus-4-6) <noreply@mastra.ai>

seonghobae · 2026-06-01T12:38:53Z

upstream PR vibemafiaclub/argos#20이 승인 및 머지되어 이 사전 작업 PR은 닫겠습니다. 감사합니다.

google-labs-jules · 2026-06-01T12:40:01Z

upstream PR vibemafiaclub/argos#20이 승인 및 머지되어 이 사전 작업 PR은 닫겠습니다. 감사합니다.

Understood. Acknowledging that this PR is being closed as obsolete and stopping work on this task.

Codex started work on behalf of seonghobae May 30, 2026 14:36 View session

seonghobae and others added 2 commits May 30, 2026 14:37

fix(ui): improve OverviewStats expand a11y linkage

891728c

Co-authored-by: seonghobae <8172694+seonghobae@users.noreply.github.com>

Codex finished work on behalf of seonghobae May 30, 2026 14:40

seonghobae changed the title ~~🎨 Palette: Improve accessibility of Overview Stats expand button~~ 🎨 접근성 개선: OverviewStats 펼치기 버튼에 ARIA 속성 추가 May 30, 2026

This was referenced Jun 1, 2026

🎨 접근성 개선: OverviewStats 토글 버튼에 ARIA 공시 패턴 적용 #6

Closed

🎨 Palette: Add a11y disclosure pattern to OverviewStats #12

Closed

seonghobae closed this Jun 1, 2026

Conversation

seonghobae commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

개요

변경 사항

추가된 ARIA 속성

개선 이유

테스트 방법

Uh oh!

google-labs-jules Bot commented May 28, 2026

Uh oh!

coderabbitai Bot commented May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

🎯 2 (Simple) | ⏱️ ~10 분

Pre-merge checks failed

❌ Failed checks (1 error)

Uh oh!

seonghobae commented May 30, 2026

Uh oh!

google-labs-jules Bot commented May 30, 2026

Uh oh!

Codex AI commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

seonghobae commented May 30, 2026

Uh oh!

google-labs-jules Bot commented May 30, 2026

Uh oh!

coderabbitai Bot commented May 30, 2026

1. aria-expanded / aria-controls / id 속성 값 정확성 ✅

2. aria-hidden="true" 적용 범위 ✅

3. 키보드 내비게이션 ✅

4. PR #6과의 충돌 가능성 ⚠️

종합 평가

Uh oh!

seonghobae commented May 30, 2026

Uh oh!

coderabbitai Bot commented May 30, 2026

코드 정확성 및 잠재적 버그

✅ 올바른 구현

⚠️ 잠재적 버그 — 하드코딩된 id (중요)

보안 취약점

성능 영향

코딩 표준 및 Best Practice

⚠️ role="region" — 랜드마크 노이즈 가능성

⚠️ .Jules/palette.md 파일

종합 평가

Uh oh!

google-labs-jules Bot commented May 30, 2026

Uh oh!

seonghobae commented Jun 1, 2026

Uh oh!

google-labs-jules Bot commented Jun 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

seonghobae commented May 28, 2026 •

edited

Loading

coderabbitai Bot commented May 28, 2026 •

edited

Loading

Codex AI commented May 30, 2026 •

edited

Loading

1. `aria-expanded` / `aria-controls` / `id` 속성 값 정확성 ✅

2. `aria-hidden="true"` 적용 범위 ✅

4. PR `#6과의` 충돌 가능성 ⚠️

⚠️ 잠재적 버그 — 하드코딩된 `id` (중요)

⚠️ `role="region"` — 랜드마크 노이즈 가능성

⚠️ `.Jules/palette.md` 파일