검증 (Verify)
스크립트는 기계적 결함을 잡아냅니다. 스크린샷은 디자인 결함을 잡아내는 도구입니다. 매번 둘 다 수행하세요.
실행하기
node ~/.config/opencode/lib/design/verify.mjs "design/Foo.html" --full --out design/.verify/foo.png
자주 사용하는 변형:
| 경우 | 플래그 |
|---|---|
| 덱(Deck), 슬라이드당 한 장씩 | --each "section" --step --each-out design/.verify/deck |
| 문서, 인쇄 너비 | --width 900 --height 1200 --full |
| 포스터 또는 고정 캔버스 | --width 1080 --height 1350 --full |
| 좁은 패널 확인 | --width 900 |
| 느린 애니메이션 안정화 | --settle 2000 |
일회용 localhost 포트에 파일을 서빙하고, 헤드리스로 로드한 후 JSON과 요약 정보를 stderr에 출력합니다. 종료 코드 1은 문제가 있음을 의미합니다.
출력 읽기
errors— 콘솔 오류와 잡히지 않은 예외입니다. 보통 누락된 요소를 참조하는 스크립트 문제입니다. 원인을 수정하고, 무시하지 마세요.failedRequests— 누락된 폰트, 이미지, 형제 파일입니다. 폰트가 누락되면 조용히 폴백(fallback)되어 전체 타이포그래피 결정이 무효화되므로, 겉보기보다 중요한 항목입니다.horizontalScroll— 페이지가 뷰포트보다 넓은 경우입니다. 화면에서는 아무도 원하지 않는 스크롤바가 생기고, 인쇄 시에는 콘텐츠가 오른쪽 가장자리에서 잘립니다.overflowing목록에서 해당 요소를 찾으세요.metrics.fontFamilies— 실제로 렌더링된 폰트입니다. 표시용 서체가 없다면 폰트가 로드되지 않은 것이며, 폴백 폰트를 보고 있는 것입니다.images[].loaded: false— 깨진 에셋 또는 잘못된 상대 경로입니다.metrics.nodeCount— 이상 징후 확인 용도이며, 목표 값이 아닙니다.
토큰 규율 확인하기
디자인을 판단하기 전에 실제로 시스템을 사용하고 있는지 확인하세요. tokens.css가 아티팩트 옆에 있을 때, 검증기가 tokens 항목 아래에서 이를 자동으로 확인합니다: 페이지가 해당 파일을 링크하지 않으면 경고하고, 페이지 자체 CSS와 components.css 같은 다른 로컬 스타일시트에 있는 모든 색상 리터럴 — hex, oklch(), rgb() 등 — 을 나열합니다.
각 항목은 존재해야 하는 토큰이거나, 파일을 우회한 값입니다. 구조적 CSS(덱의 스케일 변환, 포스터의 그리드)에는 정당하게 px 숫자가 포함될 수 있지만, 색상 리터럴은 거의 항상 그래서는 안 됩니다. 중립적인 뷰어 크롬(예: 덱의 레터박스나 문서 페이지 주변 책상 배경)은 black과 white 같은 명명된 색상을 사용합니다.
그런 다음 스크린샷 보기
파일을 엽니다. 다음 순서대로 판단하세요:
- 계층(Hierarchy) — 눈이 가장 먼저 헤드라인에, 그 다음에 보조 설명에 도달하나요? 눈을 가늘게 뜨고 보세요: 모든 것이 같은 무게를 가지면 계층이 없는 것입니다.
- 간격(Spacing) — 일관된 리듬과 충분한 간격이 있는가? 그룹 간 고르지 않은 간격은 정돈되지 않은 레이아웃의 가장 흔한 신호입니다.
- 정렬(Alignment) — 왼쪽 가장자리를 공유해야 할 요소들이 그렇게 되어 있는가?
- 클리핑 및 겹침(Clipping and overlap) — 텍스트가 경계에 닿거나 교차하거나, 요소가 컨테이너를 벗어나는 경우.
- 대비(Contrast) — 밝은 회색 위에 탁한 회색은 기본적인 실패입니다. 실제 값을 확인하고, 스크린샷 렌더링을 신뢰하지 마세요.
- 콘텐츠(Content) — 채우기용 텍스트, 남겨진 플레이스홀더, 여러분이 지어낸 숫자가 없어야 합니다.
수정 후 재실행
전체 파일을 다시 읽어서 줄을 찾지 말고, 오류 텍스트에서 직접 수정하세요. 각 실질적인 변경 후에 재실행하십시오. 세 번의 라운드가 한계입니다 — 그 이후에는 아직 무엇이 잘못되었는지 솔직히 적어서 넘기세요.
내보내기 (Export)
아티팩트가 폴더 없이 다른 곳으로 이동할 때:
node ~/.config/opencode/lib/design/inline.mjs "design/Foo.html"
이 명령은 로컬 스타일시트를 복사한 Foo.standalone.html을 생성합니다. 독립 실행형 복사본에서도 검증기를 실행하세요 — 인라인화는 상대 경로와 url() 참조가 깨지기 쉬운 지점입니다.
스크립트가 0으로 종료되었다고 디자인이 완료되었다고 말하지 마세요. 스크립트는 디자인이 잘 보이는지 알지 못합니다.