이번 라운드(스크롤 잔류·빈약한 헤더·인셋 불일치 — 사용자 보고 3건)의 교훈을 스킬로 승격:
- design-gate leftInset 검사 내장(텍스트 노드 Range 기준 ≥12px, 모바일 390px 전 뷰) — 오버플로 검사는 오른쪽만 보는 계측 공백을 메움. 도그푸드: 양앱 통과(가온 16·두레 24 각자 일관 축)
- 브랜드 검사 오탐 수정(동일 셀렉터 다중 요소 시 보이는 것 기준 — 도그푸드가 잡음)
- preflight §0-E 왼쪽 인셋 리듬, 하니스 규칙 15~17(기준 갱신 의도 리뷰·스크린샷 픽셀 판정·RED 재현), 사고표 4행
- SKILL.md 규칙 6 보강: 계측의 공백 — 보고가 오면 픽셀 판정으로 수치화하고 게이트에 추가
사용자 스크린샷을 픽셀 판정으로 해부: 앱바·검색·칩·카드는 24px에서 시작하는데 h2만 16px — 8px 어긋난 큰 명조 제목이 '가장자리에 붙었다'로 읽혔다. .layout 모바일 인셋을 24px로 통일.
- 게이트 공백: 기존 매트릭스는 오른쪽 오버플로만 검사 — e2e 에 M6 왼쪽 인셋 스위트 신설(60단언, 텍스트 시작점 ≥12px + 헤더-제목 같은 축 ±10px), RED 38 실패로 결함 재현 후 GREEN
- 측정 하자 2건 교정: display:none rect=0 필터, 전폭 컨테이너 보더박스가 아닌 텍스트 시작점 기준
- 스킬 mobile-app-ux.md: '왼쪽 인셋은 하나의 축' 규칙 추가. 시각 기준 갱신, verify L0~L6 전 통과(E2E 1,805단언)
v23 은 구조(단일 sticky 바)만 맞고 시각적 무게가 틀렸다 — 작은 회색 크럼 텍스트가 52px 바에 혼자 떠 있는 빈약한 헤더였다. 계측이 전부 통과해도 보기에 빈약하면 실패다.
- 탑바에 브랜드(가 모노그램 타일+이름)를 이어받게 하고 크럼은 모바일에서 숨김 — 두레 앱바와 같은 문법(브랜드+액션). 화면 이름은 각 뷰 헤드와 활성 탭이 말한다
- 검증: 360/390/412px 오버플로 0·브랜드 노출, 스크롤 800에서 top=0, 탭 전환 scrollY=0, 비전 검수 통과, 시각 기준 갱신 후 verify L0~L6 전 통과
- 스킬 mobile-app-ux.md 규칙 갱신: 크럼 내보내기 금지 + 계측 통과에도 눈으로 봐야 한다
사용자 보고 '상단 바가 페이지마다 왔다갔다하며 패딩이 없고 포지션도 이상하다'를 계측으로 원인 규명:
- 탭 전환 시 이전 뷰의 window.scrollY 잔류 — 짧은 뷰에선 클램프(600→49)되어 헤더가 반쯤 잘림. setCurrentView 에 scrollTo(0,0) 리셋(양앱)
- ≤900 헤더 이중 스택(브랜드 줄 43px+크럼 52px)·비sticky·safe-top 무 — .side 숨기고 .topbar 를 sticky+safe-top 단일 헤더로(두레 앱바 문법). 데스크톱 무변경
- 재발 방지: e2e M5 헤더·스크롤 스위트 10단언(스크롤 300px+에서 탭 전환 → scrollY=0·헤더 top=0), 시각 기준 갱신(390px 9화면 의도 변경), verify L0~L6 재통과
- 스킬 mobile-app-ux.md 에 '뷰 전환은 스크롤을 리셋·헤더는 하나' 규칙 반영. 가온 CSS v23
- ZCode(~/.zcode/skills) 타깃 추가
- 중립 경로 agents(~/.agents/skills · .agents/skills) 타깃 추가
- gemini-cli(.gemini/skills)·copilot(~/.copilot/skills · .github/skills) 타깃 추가
- Cursor·Windsurf 를 네이티브 스킬 경로로 전환 — 규칙 파일 12,000자 상한 때문에
Windsurf 는 실제 스킬이 아예 설치되지 못했었다. 전역 설치도 가능해진다
- Antigravity 전역 경로를 공식 문서대로 ~/.gemini/antigravity-cli/skills 로 수정
실제로 한 페이지를 만들어 보고 드러난 것들이다.
0단계 인터뷰에 두 축을 더한다.
- 브랜드 색: 꽃집 작업에서 색을 묻지 않고 레퍼런스 실측 평균으로 정했다.
결과는 좋았지만 브랜드 색이 있었다면 그걸 무시한 작업이 된다.
"없다"는 답도 답이고, 그때는 피해야 할 색을 묻는다.
- 좁은 화면 내비: 항목 수는 0단계에 이미 정해져 있는데 구현에서 발견했다.
2~4개는 쌓고, 5~6개는 가로 스크롤, 7개 이상만 여는 메뉴다.
넷인데 햄버거를 쓰면 탭 한 번을 공짜로 뺏는 것이다.
4-0 이미지 조달 단계를 새로 만든다(references/images.md).
자리를 만들기 전에 무엇을 실을지 정한다. codex 설치와 auth_mode 를 확인해
생성 경로를 쓰고, 생성물이라는 사실을 design.md 에 남긴다.
래퍼 실패 대응을 기록했다 — codex-cli 0.147.0 은 base64 를 돌려주지 않고
~/.codex/generated_images/<session>/exec-<id>.png 로 저장한다. 공식 래퍼는
"image_gen 이 호출되지 않았다"며 실패하지만 파일은 멀쩡히 있다.
실측에서 이 메시지를 보고 두 번 다시 만들었고 두 번 다 이미 있었다.
싣기 전 최적화도 넣었다(실측 10.1MB → 603KB).
구현에서 넘어진 것 셋.
- images.md: <img width height> 를 적으면 그 height 가 계산된 높이가 되어
aspect-ratio 가 조용히 무시된다. computed 는 "3 / 4" 로 멀쩡히 보이고
실제 높이는 원본 1448px 이었다. height:auto 한 줄로 10.9 화면이 7 화면이 됐다.
- antipatterns.md: "컨트롤이 2줄로 접히나" 를 개별 높이로 재서 거짓 통과했다.
링크는 한 줄짜리였고 줄바꿈된 것은 컨테이너였다(top 46/77).
행 수는 높이가 아니라 top 값의 종류로 센다.
- typography.md: 세로쓰기에 가로쓰기 자간(0.14em)을 물리면 글자 사이 세로
간격이 되어 낱글자가 흩어진다. 한글은 자소가 모여 한 글자라 특히 심하다.
- layout.md: 그리드 구조를 바꾸면 미디어쿼리도 같이 다시 써야 한다.
넓은 화면은 멀쩡했고 390px 에서 헤드라인이 6줄이 됐다.
Antigravity 에서 스킬로 인식되지 않는다는 제보를 받고 확인했다.
설치 경로가 없었던 것이 원인이다.
공식 문서 기준 경로:
워크스페이스 <root>/.agents/skills/<이름>/
전역 ~/.gemini/config/skills/<이름>/
.agents/skills 는 특정 제품 경로가 아니라 중립 경로라, 같은 규약을 쓰는
다른 하네스도 함께 읽는다. SKILL.md 구조(프론트매터 + references/)가
Claude Code 와 같아서 변환 없이 그대로 복사하면 된다.
프론트매터 요구사항도 맞는 것을 확인했다 — description 필수, name 선택.
우리 SKILL.md 는 둘 다 갖고 있다.
- targets/antigravity.ts 추가, 설치 대상 5 → 6종
- 하위호환 경로(.agent/skills, 단수)는 감지에만 쓰고 설치는 복수형에만 한다.
두 곳에 깔면 스킬이 두 번 잡힌다
- 테스트 2개 추가: 범위별 경로, 변환 없이 싣는지 (테스트 25 → 27개)
- 소개 페이지 설치 대상 목록에 반영
세 가지를 고친다. 전부 실제 사용에서 드러난 것이다.
1) 0단계에서 가정으로 채우던 것을 인터뷰로 바꾼다
"꽃집 사이트 만들어보자"를 받고 업종 성격·목표 행동·톤·이름을 혼자 정했다.
물어보니 넷 중 넷이 달랐다(일상 구독 → 하이엔드 스튜디오, 문의 하나 → 넷 다,
톤 미정 → 에디토리얼, 이름 지어냄 → 목요일의 화원).
그대로 갔으면 레퍼런스 세 개를 전부 틀린 방향에서 골랐다.
SKILL.md 0단계에 질문 도구로 한 번에 묻는 절차를 넣었다. 무엇을 묻고
무엇을 묻지 않는지, 답이 모순될 때 어떻게 정리하는지까지 적었다.
2) 레퍼런스가 막히면 브라우저를 띄운다
Aesop(403) → Kinto(404) → Hasami(DNS) → MUJI(타임아웃)로 네 번 왕복하고
톤 레퍼런스를 하나도 못 얻었다. 좋은 레퍼런스일수록 봇을 막는다.
galleries.md 에 headed 브라우저로 직접 열어 스크린샷과 실측값을 받는
방법을 넣고, 접근 실패 2회면 바로 전환하도록 규칙을 세웠다.
Playwright 를 선택 의존성으로 잡았다(core/tools.ts).
- 온보딩 마지막에 설치 여부를 묻는다. 건너뛰어도 스킬은 동작한다
- `designpaca tools` 로 상태 확인, `--yes` 로 설치
- 수백 MB 라 --yes 없이는 상태만 보여준다
- MCP 서버는 설치만 하고 등록 명령은 안내만 한다(에이전트 설정을
대신 건드리지 않는다)
3) 온보딩 말투
"이제 브리프를 던져라", "설치해라", "건너뛴다" — 사용자를 향한 문구가
명령조였다. 스킬 문서의 단정한 반말은 의도지만 CLI UI 는 다르다.
전부 존댓말로 바꾸고, 각 단계가 왜 필요한지 설명을 붙였다.
명령조가 다시 섞이지 않도록 검사하는 테스트를 넣었다(테스트 22 → 25개).
웹 디자인 파이프라인 스킬과 이를 5개 에이전트에 설치하는 CLI 를 담은 모노레포.
스킬 (packages/skill)
- SKILL.md 261줄 + 참조 문서 16개 3,349줄. progressive disclosure 로
본문은 절차와 인덱스만, 지식은 references/ 로 분리
- 0~6단계 파이프라인. 규모에 따라 전체·연장·국소 세 경로로 분기
- 하드 게이트 12개는 grep·카운트로 검증 가능한 것만. 취향 판단은 제외
- 미학 프리셋 5종, AI 슬롭 지문 목록, 한글 조판 규칙,
SVG 필터·three.js·인터랙티브 모션·HTML-in-Canvas 실전 지침
설치 CLI (packages/cli, packages/core)
- npx designpaca 온보딩 TUI. Claude Code · Codex · Cursor · Windsurf · AGENTS.md
- 매니페스트에 설치 시점 해시를 기록해 사용자가 고친 파일은 update 가 건너뛴다
- 타깃별로 본문의 references/ 경로를 실제 설치 위치로 재작성
- AGENTS.md 는 항상 로드되므로 본문 대신 303자 포인터만 주입
- Windsurf 는 12,000자 상한 초과 시 설치를 차단
배포 (build/ci, .forgejo/workflows)
- 태그 v* → 검사·테스트·빌드 → npmjs 배포 + Forgejo 레지스트리 미러
→ draft 릴리스 → Cloudflare Pages. 재실행 멱등
근거 (research/)
- 약 250개 웹 소스 조사 결과와 도그푸딩 검증 2건. 스킬의 모든 수치는 여기서 나온다
테스트 22개 통과 (core 16 · cli 6)
