통과·실패·판정 불가로 결과를 돌려주는 접근성 검사 규칙 만들기

## 린트와 테스트를 뒷정리가 아닌 변경의 일부로 다루세요 서식 지정, 린트, 테스트, 문서화, 커밋 규칙을 구현 후 정리 작업이 아니라 변경의 일부로 다루세요. ### 필수 검사 - 커밋하기 전에 저장소의 포매터와 린터를 실행하세요. - 완료하기 전에 전체 테스트 스위트를 실행하고, 동작 변경에는 단위 및 통합 테스트 범위를 포함하세요. - 런타임 동작에 영향을 줄 수 없는 변경에만 문서화된 예외를 따르세요. - 해결되지 않은 작업을 관련 없는 변경에 숨기지 말고 프로젝트의 이슈 추적기에 남기세요. - 임시 로깅이나 로컬 디버깅 설정을 커밋하지 마세요. ### 코드 규칙 - 오류와 경계 사례를 일찍 처리하여 성공 경로를 쉽게 따라갈 수 있게 하세요. - 정해진 export 위치, 명명 규칙, import 스타일을 따르세요. - 파일과 규칙 식별자의 이름을 일관되게 짓고, 프로젝트 규칙에 따라 함수, 불리언, 상수를 구분하세요. - 변수는 처음 사용하는 위치 가까이에 선언하세요. - export된 API, 매개변수, 반환값, 복잡한 로직을 문서화하세요. - 리팩터링은 초점이 분명한 기능 추가나 수정과 분리하세요. ## 가상 노드와 실제 DOM을 구분해 쓰고 의존 방향을 한쪽으로 유지하세요 가상 트리 추상화와 실제 DOM 노드 중 무엇을 사용할지 신중하게 선택하세요. 추상화는 캐시된 속성과 프로퍼티를 다루는 데 효율적이지만, 브라우저 API와 레이아웃 동작에는 실제 DOM이 필요합니다. ### 노드 선택 - 속성 접근, 캐시된 프로퍼티, 트리 순회, selector 작업에는 가상 노드를 우선하세요. - 레이아웃, 기하 정보, root 조회, 브라우저가 계산한 동작, 기타 네이티브 API에는 실제 DOM 노드를 사용하세요. - 모호한 입력은 문서화된 하나의 변환 경계를 통해 처리하세요. - 가상 노드 의존성이 명확한 API 또는 성능상 이점을 제공하지 않는 한, 범용 유틸리티의 입력과 출력은 실제 DOM을 기반으로 유지하세요. - 변환 로직을 개별 규칙 곳곳에 분산시키지 마세요. ### 의존성 방향 - 표준 정의는 런타임 import가 없는 순수 데이터로 유지하세요. - 저수준 유틸리티는 명시적인 경로를 통해 더 낮은 수준의 기반 코드와 표준 데이터에만 의존하게 하세요. - 서드파티 모듈 import를 지정된 어댑터 계층에 중앙화하세요. - 공유 도메인 헬퍼가 저수준 유틸리티를 사용하게 하되, 그 반대 방향의 의존성은 절대 허용하지 마세요. - 고수준 검사와 규칙이 순환 의존성을 만들지 않고 하위 계층을 조합할 수 있게 하세요. - 린트 또는 빌드 규칙으로 이러한 경계를 기계적으로 강제하세요. ## 통과·실패·판정 불가로 돌려주고 메시지는 메타데이터에 두세요 소비자가 준수, 위반, 증거 불충분을 구분할 수 있도록 결과 계약을 명시하세요. ### 검사 결과 - 테스트한 조건이 충족되면 `pass`를 반환하세요. - 테스트한 조건이 위반되면 `fail`을 반환하세요. - 엔진이 결과를 신뢰성 있게 판단할 수 없으면 `incomplete`를 반환하세요. - 메시지 템플릿과 `incomplete` 결과 설명에 사용할 구조화된 데이터를 첨부하세요. - 단지 이진 답변을 만들기 위해 불확실성을 `pass`나 `fail`에 억지로 포함하지 마세요. ### 규칙 정의 - 명시적인 `all`, `any`, `none` 그룹으로 검사를 조합하세요. - selector와 선택적인 추가 matcher로 후보 요소의 범위를 지정하세요. - 영향도는 프로젝트가 선언한 심각도 값으로 제한하세요. - 검사 내부에 목록을 하드코딩하지 말고 중앙화된 표준 데이터에서 HTML과 ARIA 정의를 읽으세요. ### 사용자 대상 메시지 - 메시지를 구현 코드가 아니라 규칙 또는 검사 메타데이터에 두세요. - 검사 결과가 값을 제공하는 이름 있는 데이터 placeholder를 사용하세요. - 문법상 필요한 경우 단수형과 복수형을 제공하세요. - 원본 메시지가 변경될 때마다 현지화 템플릿을 업데이트하세요. ## 색 대비와 role 판정은 특히 꼼꼼히 검토하세요 일부 접근성 결과는 불완전한 브라우저 정보나 빠르게 변화하는 표준에 의존합니다. 이러한 영역에는 보수적인 결과와 집중 검토가 필요합니다. ### 색상과 가시성 - 지원되는 색상 형식, 불투명도, 블렌딩, 쌓임 맥락, 텍스트 효과를 고려하세요. - 유효 배경이나 대비를 판단할 수 없으면 `incomplete`를 반환하세요. - CSS 가시성에만 의존하지 말고 스크린 리더에서의 가시성을 의미론적으로 평가하세요. - 숨김 상태 속성, 합성 트리, Shadow DOM 경계를 포함하세요. ### 의미론적 표준 - role과 속성 검증을 최신 접근성 명세와 동기화하세요. - 암묵적 role과 명시적 role을 별도로 해석하세요. - 모든 규칙이 동일한 단일 진실 공급원을 사용하도록 중앙화된 role 및 속성 정의를 조회하세요. - 명세 업데이트와 이전에 잘못 분류된 마크업에 대한 회귀 사례를 추가하세요. - 변경이 여러 규칙의 결과를 바꿀 수 있으면 집중 검토를 요구하세요. ## Shadow DOM을 포함한 실제에 가까운 페이지로 규칙을 테스트하세요 구현과 테스트의 소유 관계가 분명하게 유지되도록 단위 테스트 트리에서 소스 구조를 그대로 반영하세요. ### 단위 테스트와 검사 테스트 - 프로젝트에서 제공하는 표준 검사 context 또는 harness를 사용하세요. - 공유 fixture와 가상 트리가 harness에서 이미 초기화된다면 테스트가 소유한 상태만 초기화하세요. - 첨부된 메시지 데이터를 포함하여 `pass`, `fail`, `incomplete` 결과를 테스트하세요. - 광범위한 통합 테스트 범위를 추가하기 전에 경계 조건에 대한 집중 사례를 추가하세요. ### 통합 테스트 - 각 규칙 fixture에 구조화된 예상 결과를 짝지으세요. - frame용 중첩 selector를 포함하여 엔진의 표준 selector 표현을 사용하세요. - 문서 수준 동작을 fragment로 나타낼 수 없으면 완전한 HTML 페이지를 사용하세요. - 관련된 모든 규칙이나 검사에 open Shadow DOM 사례를 추가하세요. - 변경이 가상 트리 평가에 영향을 주면 가상 규칙 테스트 범위를 업데이트하세요. - 반복 작업 중에는 집중 테스트를 실행하고, 인계 전에는 권위 있는 전체 스위트를 실행하세요. ## 번역 템플릿은 메시지와 같은 커밋에서 다시 생성하세요 생성된 릴리스 번들과 저장소가 의도적으로 추적하는 생성 소스 산출물을 구분하세요. ### 산출물 정책 - 번들되거나 minify된 릴리스 출력을 직접 편집하지 마세요. - 추적되는 템플릿이나 소스 산출물은 승인된 빌드를 통해 다시 생성하세요. - 생성된 현지화 템플릿은 이를 만들어 낸 메시지 소스와 동일한 변경에 커밋하세요. - 동기화된 소스와 생성 업데이트를 별도 커밋으로 나누지 마세요. - 무시 대상으로 지정된 배포 번들을 일반 기능 커밋에 포함하지 마세요. ### 검증 - 생성된 diff에서 예상치 못한 메시지, locale, 규칙 변경이 있는지 점검하세요. - 새로운 placeholder가 모두 이를 생성하는 검사 데이터에 존재하는지 확인하세요. - 메시지 변경 후 현지화 및 빌드 검증을 실행하세요. - 어떤 산출물이 생성되며, 어떤 것이 추적되고, 어떤 것이 릴리스 전용인지 문서화하세요. ## 변경 로그와 API 문서를 갱신하고 호환성을 깨지 마세요 각 변경의 초점을 유지하고 공개적 영향을 검토자와 소비자가 볼 수 있게 하세요. ### 변경 문서화 - 규칙을 추가하거나 실질적으로 변경할 때 changelog를 업데이트하세요. - 공개 interface가 변경되면 API 문서와 type 정의를 함께 업데이트하세요. - 간결한 제목과 본문의 변경 동기를 포함하여 저장소에서 요구하는 conventional commit 형식을 사용하세요. - 지원되는 footer 또는 pull request 메타데이터를 통해 해결된 이슈를 연결하세요. - 인계 전에 프로젝트 검토 checklist를 완료하세요. ### 호환성 - 이전 형식과 새 형식을 함께 지원할 수 있다면 breaking change를 피하세요. - deprecated API를 명확히 표시하고 migration 경로를 제공하세요. - breaking change를 피할 수 없다면 릴리스 메타데이터와 changelog에 이를 명시적으로 밝히세요. - migration 지침, 업데이트된 테스트, 동기화된 생성 파일, 검토자가 확인할 수 있는 증거를 포함하세요. - 서식 지정, 린트, 집중 테스트, 통합 테스트, 전체 스위트, 문서 검사의 실제 결과가 나오기 전에는 준비가 완료되었다고 주장하지 마세요.