contrast-ratio — 가독성 자동 검사

연한 회색 글자를 흰 배경에 썼더니 안 보이네, 이런 상황 본 적 있죠? 이런 가독성 문제를 기계가 자동으로 잡아주는 규칙이에요.

WCAG가 뭐고, 4.5:1이 뭐예요

WCAG는 W3C가 만든 웹 접근성 지침이에요. 시력이 약한 분도 글을 읽을 수 있도록 글자색과 배경색의 밝기 차이가 일정 비율 이상이어야 한다고 정해뒀어요.

• 4.5:1 이상 — 본문 텍스트 최소 기준 (AA 등급)
• 3:1 이상 — 큰 글자(18pt 볼드 / 24pt 이상) 최소 기준
• 7:1 이상 — 더 엄격한 기준 (AAA 등급, 시각 보조 필요한 사용자까지)

이 규칙은 기본값으로 AA normal(4.5:1)을 검사해요.

components:
  button-muted:
    backgroundColor: "#f0f0f0"   # 밝은 회색 배경
    textColor: "#c0c0c0"         # 연한 회색 글자

검사 대상은 "컴포넌트 안의 쌍"만

이 규칙은 components 안에서 backgroundColor와 textColor가 둘 다 있을 때만 검사해요. 왜? 어느 배경 위에 어느 글자가 올지 쌍으로 명시돼야 대비를 계산할 수 있어서요.

반대로 말하면, 색 토큰에 primary: "#888"만 달랑 있으면 이 규칙은 적용 안 돼요. 어디에 쓸지 모르거든요. 컴포넌트에 색 쌍을 명시한 DESIGN.md일수록 접근성 자동 검증이 잘 작동해요.

출력 예시

{
  "severity": "warning",
  "path": "components.button-primary",
  "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
}

흥미롭게도 통과해도 메시지를 찍어요. 디자이너에게 "이 조합은 대비 15.42라서 잘 보여요"를 알려주는 정보성 출력. 실패할 때는 같은 형식으로 "fails WCAG AA"가 찍혀요.

반투명 색은 계산이 까다로워요

rgba(255, 255, 255, 0.1)처럼 반투명 배경은 정확한 대비 계산이 어려워요. 실제 화면에서 어떤 배경과 합성되느냐에 따라 최종 색이 달라지니까요. 검사 도구는 반투명 값을 보통 건너뛰거나 대략 계산해요. 이런 경우는 사람이 따로 확인해야 해요.