antislop-human
안티슬롭: AI 코딩 에이전트를 위한 규칙. Human 스킬
antislop 시스템의 일부입니다.
antislop.md(핵심)와 함께 읽으세요. 이 스킬은 인간의 관심사, 즉 UI가 다양한 시력, 손 움직임, 환경을 가진 사람들이 사용할 수 있도록 만드는 것에 대해 깊이 다룹니다: 대비, 키보드, 초점, 상태, 그리고 사람을 배제하는 모바일 세부 사항.
이 스킬을 사용하는 방법
- UI를 구축하거나 편집할 때마다
antislop.md와 함께 로드하세요. 핵심은 메커니즘(목적 테스트, 세 가지 계층, 전달 게이트)을 담고 있습니다. 이 스킬은 인간 측면의 깊이, 즉 다른 시력, 손, 설정을 가진 사람들을 배제하는 UI 부분을 담고 있습니다. - 모든 항목은 동일한 형태를 가집니다: Tell (패턴), Why (누구를 배제하는지, 왜 미완성으로 읽히는지), Fix (대신 할 일)로 구성되며, 적용되는 핵심 규칙은 R-XX로 인용됩니다.
- 접근성은 마지막에 덧붙이는 체크리스트가 아닙니다. "UI가 견딘다"는 핵심 약속(C-4)의 일부입니다. 핵심의 전달 게이트는 여전히 게이트 역할을 하며, 이 파일 끝에 있는 "Human Skill 체크리스트"는 그와 함께 실행할 보충 자료입니다.
- 대비 검사기(공식 + 참조 테이블 + 스크립트)는 이 스킬에 있습니다. 눈으로 확인할 수 없는 모든 색상 조합에 사용하세요.
- 이 스킬은 사람을 배제하는 모바일 세부 사항만 유지합니다: 확대/축소 및 화면 키보드.
색상 및 대비
저대비 텍스트
- Tell: 흰색 또는 거의 흰색 배경에 밝은 회색 텍스트, 얇은 본문 텍스트, "우아해 보인다"는 이유로 선택되었지만 읽기 어려운 흐린 레이블.
- Why: 저시력 사용자와 밝은 빛 아래의 모든 사람을 배제합니다. 표준을 확인하지 않고 시각적 선택을 한 것이며, 필터가 걸러내야 하는 기본 유형입니다.
- Fix: WCAG AA 최소 기준(R-25)을 충족하세요: 일반 텍스트 4.5:1, 큰 텍스트(18px+) 3:1. 비율을 계산하고 눈대중으로 판단하지 마세요.
사진 또는 그라데이션 위의 텍스트
- Tell: 이미지나 그라데이션 위에 직접 배치된 흰색 텍스트가 일부 영역에서 밝으며, 한 곳만 확인함.
- Why: 대비는 국소적입니다. 이미지가 밝은 곳에서 텍스트가 4.5:1 미만으로 떨어질 수 있으며, 히어로 영역이 "괜찮아" 보여도 그렇습니다. R-25는 텍스트가 지나가는 전체 영역을 테스트하도록 요구하며, 한 지점만 테스트하지 않습니다.
- Fix: 텍스트 뒤에 스크림 또는 단색 블록을 추가한 다음, 가장 나쁜 지점(가장 좋은 지점이 아닌)을 확인하세요. 텍스트 영역의 어떤 부분이라도 실패하면 처리 방식이 실패한 것입니다.
회색 위 회색 환각
- Tell: "검정 위에 진회색" 또는 "흰색 위에 밝은 회색"이 계산 없이 AA를 통과한다고 주장.
- Why: 이것은 가장 흔한 접근성 환각입니다. 눈은 회색 쌍의 대비를 과대평가하며, 에이전트는 그럴듯하게 들리기 때문에 주장을 반복합니다. 검정 위의 #555555는 2.8:1입니다. 실패합니다.
- Fix: 쌍이 통과한다고 단정하지 마세요. 대비 검사기(아래)를 실행하거나 공식을 적용하세요. 둘 다 불가능할 때는 참조 테이블을 사용하세요.
비텍스트 대비
- Tell: 대화형 컴포넌트(버튼, 아이콘, 입력 테두리, 초점 표시기, 차트 세그먼트)가 배경과 3:1 미만으로 구분됨.
- Why: 비텍스트 UI는 모양과 가장자리로 정보를 전달합니다. 가장자리가 아주 약간의 색조일 때 저시력 사용자는 컨트롤을 찾을 수 없습니다. 호버, 선택됨 같은 상태에도 동일한 기준이 적용됩니다.
- Fix: 모든 컴포넌트 경계와 상태 표시기에 인접한 색상과 3:1 비율을 제공하세요(WCAG 1.4.11). 아이콘은 4.5:1을 충족하는 텍스트 레이블과 쌍을 이루세요.
대비 검사기
대비 검사기의 본체입니다. 가장 편리한 순서부터 덜 편리한 순서까지 세 가지 계층.
스크립트. 스크립트 런타임을 사용할 수 있고 파일이 있는 경우, 수동 계산 대신 스크립트를 실행하세요. 스크립트는 이 스킬의 폴더(contrast-check.py, 이 SKILL.md 옆)에 있습니다. macOS와 Linux에서는 python3, Windows에서는 python으로 실행하세요:
python3 "${CLAUDE_SKILL_DIR}/contrast-check.py" "#FFFFFF" "#777777"
# 일반 텍스트: 실패 (4.48 < 4.5)
# 큰 텍스트: 통과 (4.48 >= 3.0)
이 에이전트에서 ${CLAUDE_SKILL_DIR} 변수를 사용할 수 없는 경우, 스크립트 경로를 이 스킬의 폴더로 직접 지정하세요. 스크립트는 에이전트가 AA를 환각하는 것을 막기 위해 존재합니다. 두 개의 16진수 색상을 받아 대비율과 두 텍스트 크기에 대한 판정을 출력합니다. 파일이 없는 경우 아래 공식과 테이블만으로도 충분합니다. 스크립트가 없어도 멈추지 마세요.
공식 (WCAG 2.x).
- 대비율 = (L1 + 0.05) / (L2 + 0.05), 여기서 L1은 더 밝은 상대 휘도, L2는 더 어두운 휘도입니다.
- 한 색상의 상대 휘도 L: 각 채널을 0-1로 변환(
c = hex / 255)한 다음 선형화:c <= 0.03928이면c_lin = c / 12.92; 그렇지 않으면c_lin = ((c + 0.055) / 1.055)^2.4. L = 0.2126*R + 0.7152*G + 0.0722*B.- 반올림되지 않은 비율을 비교하세요: 일반 텍스트 4.5:1, 큰 텍스트 3:1(18px+, R-25 기준). 표시를 위해서만 반올림하므로, 4.498:1인 쌍은 4.50으로 출력되면서 여전히 4.5:1에 실패합니다. 최대 비율은 21.0(흰색 위 검정)입니다.
참조 테이블 (공통 쌍, 공식으로 계산됨):
| 쌍 (텍스트 위 배경) | 비율 | 일반 텍스트 (4.5) | 큰 텍스트 (3.0) |
|---|---|---|---|
| 흰색 위 검정 | 21.00 | 통과 | 통과 |
| 검정 위 흰색 | 21.00 | 통과 | 통과 |
| #333333 위 흰색 | 12.63 | 통과 | 통과 |
| #666666 위 흰색 | 5.74 | 통과 | 통과 |
| 흰색 위 #777777 | 4.48 | 실패 | 통과 |
| #070707 위 #777777 | 4.50 | 실패 | 통과 |
| #888888 위 흰색 | 3.54 | 실패 | 통과 |
| #999999 위 흰색 | 2.85 | 실패 | 실패 |
| 검정 위 #555555 | 2.82 | 실패 | 실패 |
#070707 위 #777777 행은 임계값에 가까운 경우입니다: 4.4983:1은 표시를 위해 4.50으로 반올림되지만 여전히 4.5:1에 실패합니다.
테이블은 대체재가 아닌 sanity check(개념 검증)로 읽으세요. 나열되지 않은 쌍이나 임계값 근처의 모든 것은 공식 또는 스크립트를 거쳐야 합니다.
키보드
제거된 초점 윤곽선
- Tell:
outline: none또는outline: 0으로 대체 초점 스타일 없음. - Why: 키보드 사용자는 자신의 위치를 볼 수 없습니다. 마우스 없이 UI를 사용할 수 없게 만드는 가장 빠른 방법이며, R-32는 이를 완전히 금지합니다.
- Fix: 윤곽선을 유지하거나 이웃과의 대비 기준(3:1)을 충족하는 보이는
:focus-visible스타일로 대체하세요. 대체 스타일 없이outline: none을 설정하지 마세요.
마우스 전용 패턴
- Tell: 호버할 때만 열리는 메뉴, 클릭 시 열리지만 키보드로 열리지 않는 드롭다운, 키보드 대체 기능이 없는 드래그 앤 드롭.
- Why: 각각은 키보드 및 보조 기술 사용자를 배제합니다(R-32). 컨트롤이 Tab, Enter, Space로 도달하고 작동할 수 없다면, 한 집단의 사람들에게 존재하지 않는 것입니다.
- Fix: 모든 대화형 요소는 키보드로 도달 및 작동 가능해야 합니다(R-32): 시각적 순서를 따르는 논리적 탭 순서, Enter 또는 Space로 활성화, Escape로 닫을 수 있는 대화상자(R-26).
깨진 탭 순서
- Tell: DOM 순서가 시각적 순서와 일치하지 않아 초점이 페이지를 건너뛰거나, 콘텐츠를 건너뛰거나, 숨겨진 요소에 도달함.
- Why: 코드 순서를 읽는 탭 순서는 탐색을 예측 불가능하게 만듭니다(R-32). 사용자는 위치를 잃고 페이지가 망가진 느낌을 받습니다.
- Fix: 소스 순서가 시각적 순서와 일치하도록 유지하고, 긴 페이지에는 건너뛰기 링크를 추가하며, 대화상자와 같은 통제된 포커스 트랩의 일부가 아닌 실제 콘텐츠에
tabindex="-1"을 설정하지 마세요.
초점 및 상태
약하거나 보이지 않는 초점 표시기
- Tell: 배경과 같은 색상의 초점 링, 호버할 때만 나타나는 링, 1px 테두리보다 얇은 표시기.
- Why: 초점 표시기는 키보드 사용자가 자신의 위치를 아는 방법입니다. 대비 기준을 통과하지 못하거나 호버에서만 나타나면 키보드 전용 사용이 깨집니다(R-32, R-34).
- Fix: 모든 대화형 요소에 보이는 초점 표시기를 제공하고, 인접한 색상과 3:1 비율을 유지하며, 제공하는 모든 테마에서 확인하세요. 어두운 모드와 밝은 모드에서 확인하세요.
색상 전용 피드백
- Tell: 성공, 오류, 상태가 색상으로만 전달됨: 빨간색 오류 텍스트, 녹색 성공 테두리, 색조가 입혀진 칩, 아이콘, 레이블 또는 텍스트 없음.
- Why: 색맹 및 저시력 사용자를 배제하며, 강제 색상 모드에서는 완전히 사라집니다. 색상에 의존하는 상태는 상태가 아닙니다(C-4).
- Fix: 모든 색상 신호를 텍스트, 아이콘 또는 패턴과 쌍을 이루세요. 오류 상태는 텍스트가 먼저입니다: "비밀번호는 최소 8자 이상이어야 합니다", 단순한 빨간 테두리가 아닌.
누락된 UI 상태
- Tell: 빈 상태, 로딩 상태, 오류 상태가 없는 데이터 뷰, 또는 존재하지만 보이지 않는 상태: 텍스트 없는 스피너, 설명 없는 빈 화면.
- Why: R-27은 세 가지 상태를 요구합니다. 접근성 관점은 각 상태가 장식적이지 않고 인지 가능하며 정보를 제공해야 한다는 것입니다. 컨텍스트 없는 로딩 스피너는 스크린 리더 사용자에게 페이지가 멈춘 것으로 읽힙니다.
- Fix: 모든 데이터 뷰는 세 가지 상태(R-27)를 가지며, 각 상태는 선언되거나 표시됩니다: 명시적인 빈 메시지, 텍스트가 있는 로딩 상태, 무엇이 발생했고 어떻게 진행해야 하는지 알려주는 오류 상태.
확대/축소 및 모바일 사용
모바일의 레이아웃 메커니즘(중단점, 규모, 그리드, 오버플로, 터치 대상)은 antislop-layoutmobile의 관심사입니다. 이 섹션은 사람을 배제하는 모바일 세부 사항, 즉 확대/축소와 화면 키보드만 유지합니다.
확대할 수 없는 텍스트
- Tell: 고정된 픽셀 글꼴 크기, 또는 200% 확대 시 텍스트를 자르는
overflow: hidden컨테이너. - Why: 사용자는 텍스트 크기를 조정할 수 있어야 합니다(WCAG 1.4.4). 200%로 확대할 때 콘텐츠가 잘리거나 가로 스크롤이 강제되면 텍스트는 실제로 크기 조정이 불가능합니다.
- Fix: 확대/축소에 따라 리플로우되는 유동적인 글꼴 크기, 텍스트를 자르지 않는 컨테이너, 좁은 뷰포트에서 200% 확대 시 레이아웃이 유지되는지 확인하세요(R-35).
모바일 키보드가 양식을 가림
- Tell: 화면 키보드 뒤에 숨겨진 뷰포트 하단의 입력 필드, 보기로 스크롤되지 않고 입력 공간도 없음.
- Why: 사용자가 보거나 도달할 수 없는 양식은 완료할 수 없는 양식입니다. 모바일 전용 배제입니다(R-03).
- Fix: 입력 필드가 포커스될 때 키보드 위로 스크롤되어 보이도록 하고, 포커스된 필드가 가려지지 않도록 충분한 하단 패딩을 추가하세요. 실제 기기 또는 에뮬레이트된 키보드로 테스트하세요.
Human Skill 체크리스트
UI와 관련된 작업 시 핵심 전달 게이트와 함께 실행하세요. 모든 답변이 예여야 합니다:
- 모든 텍스트와 배경 쌍(이미지 및 그라데이션 위의 텍스트 포함)이 대비 검사기(공식, 테이블 또는 스크립트)로 검증되었습니까? (R-25)
- 모든 대화형 컴포넌트 경계와 상태 표시기가 배경과 3:1 비율을 충족합니까? (비텍스트 대비)
- 초점 표시기가 모든 테마의 모든 대화형 요소에 보이고, 대비가 높으며, 존재합니까? (R-32, R-34)
- 모든 대화형 요소가 키보드로 도달 및 작동 가능하며, 대화상자는 Escape로 닫을 수 있고, 대체 스타일 없이
outline: none이 설정되지 않았습니까? (R-32, R-26) - 모든 데이터 뷰의 빈 상태, 로딩 상태, 오류 상태가 존재하고 인지 가능하며, 색상 전용이 아닙니까? (R-27, C-4)
- 텍스트를 200%로 크기 조정할 때 잘리지 않으며, 모바일 키보드가 포커스된 입력 필드를 가리지 않습니까? (R-35)