WCAG AA 명암비 미달을 전면 수정한 하루

왜 이 작업을 오늘 했냐면

어드민 대시보드를 쓰다가 사이드바 텍스트가 유독 흐릿하게 느껴졌다. 눈이 피로한 건지 싶었는데, 막상 명암비 체커를 돌려보니 WCAG AA 기준(4.5:1)에 한참 못 미치는 수치가 줄줄이 나왔다. 한두 군데가 아니었다. muted 계열 색상, accent, 차트 범례, 사이드바 활성 항목, success/green 계열 뱃지, 심지어 "사이트 열기" 버튼까지. 이쯤 되면 개별 수정이 아니라 색상 시스템 레벨에서 일괄 교정이 필요했다.

두 커밋으로 나뉜 건 작업 순서 때문이다. 먼저 대시보드 내부 컴포넌트(BotUsageGauge, GscPropertyChart, page.tsx)와 글로벌 CSS·Tailwind 설정을 정비하고, 이어서 레이아웃 쪽(Sidebar, SidebarContent, HeaderClient)과 나머지 잔여 미달 항목을 처리했다.

뭘 어떻게 고쳤나

크게 두 레이어에서 수정이 발생했다.

1. 디자인 토큰 레이어 (globals.css + tailwind.config.ts)

muted, accent, success, green 계열 CSS 변수의 명도값을 조정했다. 밝은 배경 위에서 텍스트로 쓸 때 4.5:1을 충족하도록 L* 값을 낮추는 방향이 대부분이었다. Tailwind config에서도 그 변수를 참조하는 컬러 매핑을 같이 업데이트했다.

2. 컴포넌트 레이어

컴포넌트 쪽은 하드코딩된 Tailwind 유틸리티 클래스(text-muted-foreground, text-green-400 류)가 문제였다. 일부는 토큰 수정으로 자동 해결됐고, 일부는 클래스를 직접 교체했다.

작업하면서 신경 쓴 것들

수정 전: contrast ratio ≈ 2.8:1 ~ 3.9:1 (AA 미달)
수정 후: contrast ratio ≥ 4.5:1 (AA 통과)

접근성 수정에서 흔히 하는 실수가 텍스트 색만 어둡게 해서 통과시키는 거다. 근데 그러면 다크모드나 다른 배경색 위에서 깨진다. 이번엔 CSS 변수 레벨부터 손댔기 때문에 globals.css에서 라이트/다크 두 케이스 모두 체크했다.

또 하나 — success/green 계열은 브랜드 컬러와 맞물려 있어서 너무 어둡게 내리면 디자인 톤이 죽는다. 그 경계에서 최솟값을 찾는 게 생각보다 손이 많이 갔다. 결국 배경에 약간 틴트를 얹고 텍스트는 더 진하게 쓰는 방식으로 절충했다.

마치며

사실 이런 작업은 "기능"이 아니라서 백로그에서 계속 밀리기 쉽다. 근데 어드민은 내부 팀이 매일 들여다보는 툴이고, 명암비 미달이 쌓이면 실제로 눈이 피로해진다. 오늘 한 번 시스템 레벨에서 정리해뒀으니 앞으로 새 컴포넌트 추가할 때도 토큰만 제대로 쓰면 AA는 기본으로 따라오는 구조가 됐다. 잡일처럼 보여도 쌓이면 이런 게 기반이다.

🛒 이 글과 어울리는 추천 상품

• IPS모니터 쿠팡에서 보기 →
• 책상조명 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.