레이아웃 감사(Audit)
layout-audit.mjs가 이 파일과 같은 디렉터리에 위치하며, 여러 너비에서 페이지를 구동하고 DOM을 측정합니다.
레이아웃 결함이라고 불릴 만한 것만 보고하며, 접근성은 별도의 문제이므로 다루지 않습니다.
node ~/.claude/skills/layout-audit/layout-audit.mjs --base=http://localhost:3000 --routes=/,/pricing
플래그: --routes (쉼표로 구분, 기본값 /), --widths (기본값 1440x900,390x844), --auth=user:pass
(Basic Auth), --shots=<dir> (라우트 및 너비별 스크린샷 저장), --json (실행 간 차이 비교).
Playwright는 전역에 설치된 @playwright/cli를 사용하므로 프로젝트에 추가 의존성이 생기지 않습니다.
검사 항목
| 검사 항목 | 의미 |
|---|---|
viewport-overflow | 요소가 뷰포트 가장자리를 넘어감 - 페이지가 가로로 스크롤됨 |
clipped-text | 상자가 자신의 텍스트를 생략 부호나 title 속성 없이 잘라내어 텍스트에 접근할 수 없음 |
collapsed-text | 요소가 텍스트를 포함하지만 높이가 없어 빈 공간처럼 보임 |
overlapping-text | 두 개의 텍스트 상자가 동일한 픽셀에 겹쳐 그려짐 |
tiny-text | 휴대폰에서 읽을 수 없는 작은 글꼴 크기 |
결과 활용
- 개발 중인 dev 서버가 아닌 빌드된 결과물에 대해 실행하세요. 핫 리로드는 절반만 적용된 스타일을 남깁니다.
- 수정 전에 요소별로 결과를 그룹화하세요. 여러 라우트에서 반복되는 공유 헤더는 하나의 결함이지 열 개가 아니며, 보고서의 개수가 작업량을 의미하지는 않습니다.
- 생략 부호와 title 속성을 가진 텍스트 자름은 패턴이지 결함이 아닙니다. 도구는 이미 이를 제외합니다. 검사 결과에서 상자가 텍스트를 자른다고 표시된다면, 텍스트에 실제로 접근할 수 없는 것입니다.
- 동일한 클래스의 요소에서 반복되는 발견은 디자인 결정입니다. 전체 표면의 글꼴 크기나 색상은 디자인을 소유한 사람의 몫입니다. 숫자를 보고하고 그들이 선택하도록 하되, 임의로 색상을 변경하지 마세요.
- 스크린샷은 어떤 규칙도 명시하지 않은 문제를 여전히 포착합니다.
--shots를 사용하고 규칙이 깨끗하다고 판단한 페이지, 특히 휴대폰 너비를 살펴보세요. - 깨끗한 실행 결과는 실제 휴대폰에서도 동일하다는 것을 의미하지 않습니다. iPhone 프로필을 사용한 Playwright의 WebKit은 iPhone의 Safari와 다릅니다. 보고된 휴대폰 결함이 재현되지 않으면, 작동한다고 보고하지 말고 그렇게 말한 후 장치를 요청하거나 의심되는 메커니즘을 완전히 제거하세요.
- 규칙이 실제로 동작하는지 확인한 후에 결과를 신뢰하세요. 임시 페이지에 결함을 심고 검사를 실행하여 규칙이 이를 보고하는지 확인하세요. 특히 페이지 수준의 클리핑은 단순한 너비 비교가 모든 페이지에서 통과하게 만들 수 있습니다.