AI 도우미에게 건네는
꼼꼼한 화면 작업 설명서

어떤 화면인지 확인하기

2단계

저장소부터 살펴요. 공개 웹 페이지예요. 브라우저가 HTML로 그려요. 이 프로젝트의 디자인 기준은 DESIGN.md예요. 버튼 하나를 고치는 좁은 수정이라 UX_CONTRACT.md는 만들지 않아요.

## 확인 메모
- 사용자: 휴대폰으로 상품을 찾는 손님 (증거: 신고 스크린샷)
- 대상: 공개 웹 페이지, 휴대폰 Chrome 360px
- 디자인 기준: DESIGN.md (색 5개, 간격 기본 4px)
- 옆 화면: 데스크톱 1280px 검색 폼
- 크기: 좁은 수정, 기존 영수증에 짧게

맞는 안내서 고르기

3단계4단계

웹 페이지라 공통 UX와 웹 안내서를 펼쳐요. 버튼 폭과 줄바꿈이 바뀌니 배치 안내서를 더해요. 움직임은 그대로이고 홍보 페이지가 아닌 제품 화면이라 다른 안내서는 펼치지 않아요.

펼침     ux.md, web.md, layout.md
안 펼침  motion-core.md   움직임은 그대로
안 펼침  anti-slop.md     홍보 페이지가 아닌 제품 화면

진짜 화면으로 재현하기

규칙 27단계

처음에는 Chrome headless로 360px을 찍었는데 버튼이 오른쪽 끝에서 잘려 보였어요. 화면 폭을 직접 물어보니 500이었어요. 500px로 그린 뒤 360px만 잘라 낸 사진이었던 거예요. 진짜로 360px로 그리는 브라우저로 다시 찍었어요.

$ "Google Chrome" --headless=new --window-size=360,740 --dump-dom file:///tmp/fe-w.html
<html><head><script>document.write("w="+innerWidth)</script></head><body>w=500</body></html>

$ chrome-headless-shell --hide-scrollbars --window-size=360,740 --screenshot=shots/before-360.png file://<project-root>/index.html
9885 bytes written to file shots/before-360.png

디자인 기준 검사

5단계

버튼 색도 살펴봐요. 스킬에 든 토큰 검사가 DESIGN.md에 없는 색 #3b82f6을 찾아냈어요. 기준에 있는 --color-primary를 써야 해요.

$ node "$FRONTEND_SKILL_DIR/scripts/ds-compliance.mjs" DESIGN.md src/tokens.css src/app.css
{
  "ok": false,
  "design": "DESIGN.md",
  "base": 4,
  "declaredColors": 5,
  "counts": {
    "undeclared-color": 1
  },
  "violations": [
    {
      "file": "src/app.css",
      "line": 4,
      "kind": "undeclared-color",
      "value": "#3b82f6",
      ...
    }
  ]
}
# 종료 코드 1

원인 고치기

6단계

원인은 줄바꿈을 막은 버튼이에요. 버튼이 줄어들 수 있게 하고 폭은 40%까지로 막아요. 한국어 단어는 쪼개지 않고 줄을 바꾸게 해요. 색은 기준의 토큰으로 바꿔요. 쓰던 CSS 한 줄만 고쳐요.

 /* src/app.css 4번째 줄 */
-.search button { flex: 0 0 auto; white-space: nowrap; padding: 12px 16px; font-size: 16px; color: var(--color-on-primary); background: #3b82f6; border: 0; }
+.search button { flex: 0 1 auto; max-width: 40%; white-space: normal; word-break: keep-all; padding: 12px 16px; font-size: 16px; color: var(--color-on-primary); background: var(--color-primary); border: 0; }

같은 조건으로 다시 찍기

7단계

같은 브라우저, 같은 360px로 다시 찍어요. 버튼 글자가 두 줄로 바뀌고 입력창 안내 문구가 다 보여요. 그다음 두 사진을 비교해요.

$ node "$FRONTEND_SKILL_DIR/scripts/visual-diff.mjs" shots/before-360.png shots/after-360.png --json
{
  "dimensionsMatch": true,
  "width": 360,
  "height": 740,
  "diffPixels": 16864,
  "diffRatio": 0.0633033033033033,
  "similarityScore": 94,
  "alphaChannelIntact": true,
  "hotspots": [
    { "gridX": 5, "gridY": 1, "x": 225, "y": 92, "width": 45, "height": 93, "diffRatio": 0.6734299516908212 },
    ...
  ]
}
# 바뀐 칸 8개가 모두 gridY 1, 검색 폼 줄이에요

점수는 판정이 아니에요

규칙 8

94점은 “얼마나, 어디가 달라졌는지”만 알려 줘요. 이 스크립트는 점수가 몇 점이든 종료 코드 0으로 끝나요. 판정은 사람이 두 화면을 보고 내려요. 같은 화면을 두 번 찍으면 100점이 나오는 것도 확인했어요.

$ node "$FRONTEND_SKILL_DIR/scripts/visual-diff.mjs" shots/before-360.png shots/before-360-again.png --json
{
  "dimensionsMatch": true,
  "width": 360,
  "height": 740,
  "diffPixels": 0,
  "diffRatio": 0,
  "similarityScore": 100,
  "alphaChannelIntact": true,
  "hotspots": []
}

스크립트 머리말에도 적혀 있어요: “이 JSON은 리뷰할 곳을 겨누는 증거일 뿐 판정이 아니다. 99점도 가짜나 깨진 화면을 숨길 수 있다.”

디자인 기준 다시 검사

5단계

색을 토큰으로 바꾼 뒤 같은 검사를 다시 돌려요. 이번에는 통과예요.

$ node "$FRONTEND_SKILL_DIR/scripts/ds-compliance.mjs" DESIGN.md src/tokens.css src/app.css
{
  "ok": true,
  "design": "DESIGN.md",
  "base": 4,
  "declaredColors": 5,
  "counts": {},
  "violations": []
}
# 종료 코드 0

실행 폴더에 모으기

8단계

실행마다 폴더를 하나 만들고 전후 사진, 비교 결과, VISUAL_QA.md를 거기 모아요. 끝으로 파일이 모두 폴더 안에 제대로 있는지 확인해요.

$ node "$FRONTEND_SKILL_DIR/scripts/evidence-root.mjs" create search-button-overflow
.superloopy/evidence/frontend/20261013T070825Z-search-button-overflow

$ node "$FRONTEND_SKILL_DIR/scripts/evidence-root.mjs" verify .superloopy/evidence/frontend/20261013T070825Z-search-button-overflow VISUAL_QA.md before-360.png after-360.png visual-diff.json
.superloopy/evidence/frontend/20261013T070825Z-search-button-overflow

# VISUAL_QA — 검색 버튼 라벨 (360px)

- Viewport: 360x740, chrome-headless-shell (innerWidth=360 확인)
- Before: before-360.png — 라벨이 한 줄을 차지해 입력창이 ~104px로 눌리고 placeholder가 "상품명을 입"에서 잘림
- After: after-360.png — 라벨이 두 줄로 줄바꿈, 버튼 폭 40% 상한, placeholder 전체 노출
- visual-diff.json: similarityScore 94, hotspot 전부 검색 폼 행
- 토큰: ds-compliance ok=true (#3b82f6 → var(--color-primary))
- 판정: PASS (사람 눈으로 두 스크린샷 비교 후 기록)

루프에 연결하고 영수증 남기기

8단계

이번엔 Superloopy 루프 안에서 했어요. 기준 C001은 CSS 규칙을 확인하는 명령으로, C002는 VISUAL_QA.md 파일로 증명해요. 파일 증거에는 “명령으로 다시 돌릴 수 있으면 그게 더 좋다”는 경고가 붙어요.

$ superloopy loop prove -- node scripts/check-button-fit.mjs
superloopy prove: G001/C001 -> pass (.superloopy/evidence/G001-C001-capture.txt)

$ superloopy loop evidence --goal-id G001 --criterion-id C002 --status pass \
    --artifact .superloopy/evidence/frontend/20261013T070825Z-search-button-overflow/VISUAL_QA.md
superloopy evidence: G001/C002 -> pass

$ superloopy loop check
superloopy check: ok
Evidence summary: 2 artifact-backed criteria, 0 unresolved, 0 invalid

Warnings:
- manual-proof: G001/C002 is passed with artifact-only proof; prefer command-backed proof when feasible.

$ superloopy loop finish --evidence "C001 check-button-fit pass; C002 VISUAL_QA.md at 360px" \
    --artifact .superloopy/evidence/gate.json --notes "criteria reviewed"
superloopy finish: complete

버튼 글자가 360px에서 두 줄로 바뀌었어요. 전후 스크린샷을 남겼어요.
SUPERLOOPY_EVIDENCE: .superloopy/evidence/frontend/20261013T070825Z-search-button-overflow/VISUAL_QA.md

증거가 만들어지는 과정과 생김새 자세히 보기