Layout Witness
페이지를 더 쉽게 훑어보고 사용할 수 있게 만듭니다. 관련 요소를 명확하게 그룹화하고, 반복되는 컴포넌트의 일관성을 유지하며, 콘텐츠와 뷰포트 크기가 변경되어도 이러한 관계를 유지합니다. 가이드를 사용하여 편집하면서 무엇을 수정할지 결정하세요.
기존 개발 탭에서 Chrome 확장 프로그램을 사용합니다. 로컬 에이전트 연결과 페어링하여 터미널에서 페이지 및 요소 측정값을 JSON으로 읽고 가이드를 제어합니다. 옵션인 Playwright CLI를 사용하여 신규 브라우저 컨텍스트에서 무인 캡처를 수행할 수 있습니다.
기존 탭에 연결
chrome://extensions에서 전체 layout-witness 스킬 디렉터리를 압축 해제된 확장 프로그램으로 로드합니다. Chrome 116 이상을 사용하세요.
WITNESS_DIR을 설치된 스킬 디렉터리로 설정합니다.(cd "$WITNESS_DIR" && npm ci --omit=dev)를 한 번 실행한 후, 지속적인 터미널에서node "$WITNESS_DIR/scripts/agent.mjs" serve를 시작합니다.- 개발 탭의 툴바에서 Layout Witness를 엽니다. Agent access에서 터미널이 출력한 페어링 URL을 붙여넣고 Connect agent를 선택합니다. 이렇게 하면 하나의 탭이 승인됩니다. 액세스가 없으면 사용자에게 해당 탭을 한 번 페어링하도록 요청하세요.
- 같은 머신의 모든 터미널에서 CLI를 사용합니다. 편집 중에는 로컬 서버를 계속 실행 상태로 유지하세요.
node "$WITNESS_DIR/scripts/agent.mjs" start
node "$WITNESS_DIR/scripts/agent.mjs" select 'header [aria-label="Search"]'
node "$WITNESS_DIR/scripts/agent.mjs" measure
# 프로젝트의 CSS를 편집하고 dev 서버가 적용될 때까지 기다립니다.
node "$WITNESS_DIR/scripts/agent.mjs" measure
measure는 페이지 영역, 체크 결과 및 현재 선택된 요소(있는 경우)를 출력합니다. 해당 요소에는 렌더링된 박스, 마진, 테두리, 패딩, 그리드 및 갭 값, 타이포그래피(측정 가능한 경우 뷰포트 기준선 Y 포함), SVG 지오메트리가 포함될 수 있습니다. 하나의 보이는 요소와 일치하는 선택자를 사용하세요. 편집하는 동안 선택을 유지하고 브라우저가 변경 사항을 적용한 후 다시 JSON을 읽으세요.
status를 사용하여 연결을 확인하고, clear를 사용하여 요소 가이드만 제거하고, pick을 사용하여 수동 클릭 선택을 하고, import <rules.json>을 사용하여 프로젝트 규칙을 로드하고, defaults를 사용하여 기본 규칙을 복원합니다. stop을 사용하여 두 가이드를 모두 제거하고 선택을 초기화하여 깨끗하게 검토합니다. start와 select를 사용하여 다시 시작합니다. 탭이 명령 수락을 중단해야 하는 경우 완료 시 disconnect를 사용하세요. 동일 출처 리로드는 동일한 경로에서 가이드와 선택을 복원할 수 있습니다. 다른 출처 또는 탭 종료는 페어링을 종료합니다.
수동 검토의 경우 툴바 팝업에서 Start guides, Inspect element, Stop guides를 사용하세요. 사본을 저장하려면 Download report를 사용할 수 있습니다.
가이드를 켠 상태에서 작업하기
- 예상 레이아웃을 설정합니다. 프로젝트의 레이아웃 및 컴포넌트 규칙을 읽은 다음 기존 토큰과 허용된 형제 컴포넌트를 확인합니다. 작업에 중요한 관계(예: 공유 읽기 가장자리, 탐색 그룹 간의 간격, 버튼의 인라인 패딩)를 기록합니다. 새 페이지의 경우 브리핑에서 이러한 관계를 선택하고 가정을 기록합니다. 확장 프로그램의 기본 그리드는 탐색 가이드로 취급합니다.
- 페이지에서 요소까지 검사합니다. 편집하기 전에 가이드를 시작합니다. 렌더링된 시작점을 캡처하고 문제가 있는 요소를 선택합니다. 레이블이 겹칠 경우 정확한 측정을 위해 보고서를 사용합니다. 새 페이지의 경우 셸이 렌더링되면 시작하고 섹션과 컨트롤을 추가할 때 가이드를 계속 켜 둡니다.
- 선택 항목을 활성화한 상태에서 소스를 편집합니다. 측정된 값을 예상 값과 비교합니다. 관계를 소유하는 CSS 또는 공유 컴포넌트를 수정합니다. dev 서버가 편집 내용을 적용하면 다른 요소를 선택하기 전에 동일한 요소의 가이드와 측정값을 확인합니다. 리로드가 요소를 대체하는 경우 복원된 선택이 여전히 의도한 컨트롤을 참조하는지 확인합니다. 실제 값, 예상 값 및 측정 결과를 기록합니다.
- 깨끗한 렌더링을 검토합니다. 먼저 수정된 가이드를 캡처한 다음 가이드를 끄고 실제 페이지를 검사합니다. 레이아웃이 변경되는 너비에서 그룹화, 계층 구조, 정렬, 줄 바꿈 및 가시적인 포커스를 확인합니다. 긴 레이블이나 번역된 콘텐츠 및 관련 열림, 접힘 또는 밀집 상태를 포함합니다. 남은 문제와 확인한 너비 및 상태를 보고합니다.
| 범위 | 검사할 내용 |
|---|---|
| 페이지 셸 | 페이지 가이드를 사용하여 공유 읽기 가장자리, 외부 거터 및 헤더, 사이드바, 메인 영역, 푸터가 중단점에서 어떻게 적응하는지 확인합니다. 깨끗한 렌더링에서 반복되는 작업을 쉽게 찾을 수 있고 주요 작업이 시각적으로 가장 강조되는지 확인합니다. |
| 그룹 및 반복되는 컴포넌트 | 로컬 그리드 트랙을 사용하여 영역 내에서 정렬 및 범위를 확인합니다. 각 컴포넌트 내의 패딩 및 갭과 별도로 그룹 간의 간격을 비교합니다. 관련 항목을 시각적으로 그룹화하고 그룹이 쌓일 때 읽기 순서를 확인합니다. |
| 개별 요소 | 컨트롤을 선택하여 박스, 패딩 및 아이콘-레이블 간격을 검사합니다. 정렬되어야 하는 레이블 간의 줄 높이와 기준선을 비교합니다. 동일한 패밀리 내의 아이콘 크기와 획을 검토한 다음 렌더링된 크기에서 시각적 균형을 판단합니다. 글리프와 별도로 대화형 대상을 측정합니다. |
비좁은 사이드바의 경우 먼저 관련 링크가 그룹으로 읽히고 인접한 섹션에 명확한 간격이 있는지 확인합니다. 그런 다음 행을 선택하고 해당 행의 삽입 및 아이콘-레이블 간격을 동등한 행과 비교합니다. 공유 컴포넌트가 각 측면에 16px을 요구하는데 가이드가 한쪽에 8px이라고 표시되면 토큰을 복원하고 동일한 선택을 다시 측정합니다. 컨텍스트에서 확장 및 축소된 사이드바를 확인하려면 가이드를 끕니다.
토큰 값, 명명된 가장자리 간의 정렬 및 오버플로와 같은 명시적인 기대에는 엄격한 검사를 사용합니다. 렌더링된 페이지에서 계층 구조와 시각적 균형을 판단합니다. 프로젝트의 타입 스케일을 사용하여 기준선을 정렬해야 하는지 결정합니다.
디자인 참고 자료
- Adobe Spectrum 2는 근접성이 관계를 어떻게 나타내는지, 간격이 범위에 따라 어떻게 달라지는지, 패밀리 내에서 아이콘 간격과 획을 검토하는 방법을 설명합니다. 간격 · 아이콘 기본 사항
- Figma는 페이지, 중첩 영역, 컴포넌트 패딩 및 텍스트 기준선에 대한 가이드를 선택하는 방법을 보여줍니다. 레이아웃 그리드
- Linear의 디자인 리프레시는 복잡한 작업 공간에서 예측 가능한 헤더 작업과 시각적 계층 구조에 관한 사례 연구입니다. 디자인 리프레시
접근성이 범위에 포함된 경우 WCAG를 사용하여 리플로우, 사용자 텍스트 간격 재정의 및 실제 포인터 대상을 확인합니다(해당 예외 포함). 리플로우 · 텍스트 간격 · 대상 크기
선택적 무인 캡처
automation이 뷰포트 너비 또는 테마에 걸쳐 신규 브라우저 컨텍스트를 필요로 할 때 CLI를 사용합니다. Node.js 22+ 및 Playwright Chromium이 필요합니다. WITNESS_DIR을 설치된 스킬 디렉터리로 설정하고 거기에 종속성을 설치하세요:
(cd "$WITNESS_DIR" && npm ci && npx --no-install playwright install chromium)
구성 및 출력 경로가 프로젝트에서 확인되도록 프로젝트에서 CLI를 실행하세요:
node "$WITNESS_DIR/scripts/witness.mjs" capture http://localhost:3000 \
--config ./layout-witness.json --width 1440 --width 390 --strict \
--out .layout-witness/review
생성된 오버레이와 JSON 보고서를 읽습니다. 캡처 모드는 각 너비 및 테마에 대해 신규 페이지를 엽니다. 영역 및 체크 정의는 규칙 참조를 참조하세요. 대화형 CLI 워크플로에는 watch를 사용하세요.