8808c672dc
웹 디자인 파이프라인 스킬과 이를 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)
137 lines
6.7 KiB
Markdown
137 lines
6.7 KiB
Markdown
# preflight — 출시 전 감사
|
||
|
||
5단계에서 읽는다. **자기 결과물을 남의 것처럼 본다.** 통과 못 한 항목은 4단계로 돌아가 고친다.
|
||
|
||
슬롭 지문 검출과 자가 채점표는 `references/antipatterns.md` 에 있다. 이 문서는 **그 외 전부**를 다룬다.
|
||
|
||
---
|
||
|
||
## 0. 먼저 기계로 검사한다
|
||
|
||
**무엇에 돌리는가부터 정해라.**
|
||
- 정적 HTML/CSS 프로젝트 → 소스 그대로
|
||
- **React·Vue·Astro 등 프레임워크 프로젝트 → 프로덕션 빌드 결과에 돌린다.** 소스만 보면 렌더된 DOM 이 없어 대비·가로 스크롤·LCP 를 잴 수 없다. `pnpm build && pnpm preview` 로 띄우고 그 URL 을 검사해라
|
||
- **소스만 보고 "측정 불가"로 남기지 마라.** 미측정은 통과가 아니다
|
||
|
||
grep 검사는 **주석과 문자열을 제외**해라. "100vh 금지"라고 쓴 주석이 게이트 #9 에 걸리는 오탐이 실제로 나왔다.
|
||
|
||
사람 눈보다 정확하고 빠르다. 셋 다 돌려라.
|
||
|
||
### A. 이펙트 전부 끄기
|
||
```css
|
||
/* 임시로 주입해서 확인한다 */
|
||
*, *::before, *::after {
|
||
filter: none !important;
|
||
backdrop-filter: none !important;
|
||
animation: none !important;
|
||
transition: none !important;
|
||
transform: none !important;
|
||
}
|
||
canvas { display: none !important; }
|
||
```
|
||
이 상태에서 **페이지가 여전히 읽히고 구조가 살아 있어야 한다.** 무너지면 이펙트가 구조를 대신하고 있는 것이다. 4-1로 돌아가라.
|
||
|
||
### B. 슬롭 지문 grep
|
||
`references/antipatterns.md` 의 grep 목록을 소스에 돌린다. 검출률 상위 항목(보라 CTA, 전체 대문자 헤드라인, 번호 매긴 1·2·3 단계)부터.
|
||
|
||
### C. 카피 경쟁사 치환
|
||
제품명을 경쟁사 이름으로 바꿔 읽는다. **문장이 그대로 성립하면 그 카피는 아무것도 말하지 않았다.** 히어로 문구부터 검사한다.
|
||
|
||
---
|
||
|
||
## 1. 접근성 — 타협 없음
|
||
|
||
| 항목 | 확인 방법 | 기준 |
|
||
|---|---|---|
|
||
| 키보드 도달 | Tab 만으로 순회 | 모든 인터랙티브 요소에 도달, 순서가 시각 순서와 일치 |
|
||
| 포커스 표시 | Tab 하며 눈으로 | 항상 보인다. `outline: none` 만 있고 대체가 없으면 실패 |
|
||
| 대비 | 측정 도구 | 본문 4.5:1, 큰 글자·UI 3:1 |
|
||
| 이미지 대체텍스트 | 소스 확인 | 의미 있는 이미지에 alt, 장식은 `alt=""` |
|
||
| 폼 레이블 | 소스 확인 | 모든 입력에 연결된 `<label>`. placeholder 는 레이블이 아니다 |
|
||
| 제목 구조 | 개요 확인 | h1 하나, 건너뛰지 않음 |
|
||
| 모션 감소 | `prefers-reduced-motion` 켜고 확인 | **전부 끄는 게 정답이 아니다** — 위치 이동·시차·자동재생을 죽이고, 페이드·상태 변화는 남긴다 |
|
||
| 자동재생 | 확인 | 5초 이상 반복되는 애니메이션에는 정지 수단이 있다 |
|
||
| 캔버스/WebGL 실패 | JS 끄고 확인 | 콘텐츠가 여전히 보인다 |
|
||
|
||
**스크린리더를 실제로 켜볼 수 없다면** 최소한 소스의 읽기 순서를 확인해라. `order`·`position: absolute` 로 시각 순서를 바꿨다면 읽기 순서가 어긋난다.
|
||
|
||
---
|
||
|
||
## 2. 성능 — 3단계에서 정한 예산과 대조
|
||
|
||
**예산 값은 `tokens.md` §5 를 보라. 여기서 다시 적지 않는다** — 두 곳에 적으면 갈라진다.
|
||
이 문서가 하는 일은 **실측을 채우는 것**이다.
|
||
|
||
| 항목 | 실측 | 판정 |
|
||
|---|---|---|
|
||
| 히어로까지 JS (gzip) | | |
|
||
| WebGL/3D 추가분 | | |
|
||
| 총 전송량 (첫 화면) | | |
|
||
| 첫 인터랙션 (모바일 4G) | | |
|
||
| LCP | | |
|
||
| CLS | | |
|
||
| 폰트 파일 수 | | |
|
||
|
||
**측정하지 않았으면 통과가 아니다.** 예산을 넘겼다면 둘 중 하나다: 이펙트를 빼거나, 예산을 올린 이유를 명시하거나.
|
||
|
||
### 자주 걸리는 것
|
||
- 폰트 서브셋 안 함 (한글 전체 폰트는 수 MB)
|
||
- 첫 화면 밖 이미지에 `loading="lazy"` 누락
|
||
- 3D/WebGL을 초기 번들에 포함 (뷰포트 진입 시 동적 import 해야 한다)
|
||
- 애니메이션이 `top`/`left`/`width` 를 건드림 → `transform` 으로 바꿔라
|
||
- `will-change` 남발 → 레이어가 늘어 오히려 느려진다
|
||
|
||
---
|
||
|
||
## 3. 반응형
|
||
|
||
- [ ] **320px** 폭에서 가로 스크롤 없음 (하드 게이트 #5 는 320~1920px 전 구간을 요구한다. 375px 만 보면 그 아래가 뚫린다)
|
||
- [ ] 1920px 이상에서 콘텐츠가 늘어지지 않음(최대 폭 제한)
|
||
- [ ] 중간 뷰포트(768~1024px)에서 레이아웃이 깨지지 않음 — **가장 자주 빠뜨리는 구간**
|
||
- [ ] 터치 타깃: **버튼·아이콘·카드 등 독립 컨트롤은 44×44px 이상**(Apple/Google 권고)
|
||
- [ ] 터치 타깃: **본문 안 인라인 텍스트 링크는 24×24px 이상**(WCAG 2.5.8 AA). 여기에 44 를 요구하면 정상적인 내비 링크가 오탐된다
|
||
- [ ] 호버로만 접근되는 기능 없음
|
||
- [ ] 긴 단어/URL이 넘치지 않음 (`overflow-wrap: anywhere`)
|
||
- [ ] 가로 모드에서 첫 화면이 잠기지 않음
|
||
|
||
---
|
||
|
||
## 4. 콘텐츠
|
||
|
||
- [ ] 히어로가 **무엇인지** 말한다. 형용사만 있고 명사가 없으면 실패
|
||
- [ ] 로렘입숨이 남아 있지 않다
|
||
- [ ] 실제 콘텐츠 길이로 테스트했다 (짧은 제목만으로 맞춘 레이아웃은 긴 제목에서 깨진다)
|
||
- [ ] 빈 상태·오류 상태·로딩 상태가 있다
|
||
- [ ] 링크가 어디로 가는지 텍스트만 보고 알 수 있다 ("여기를 클릭" 금지)
|
||
- [ ] 이미지가 없거나 실패했을 때 레이아웃이 무너지지 않는다(`aspect-ratio` 지정)
|
||
|
||
---
|
||
|
||
## 5. 디자인 자체
|
||
|
||
기계로 못 잡는 부분이다. **정직하게 답해라.**
|
||
|
||
1. **이 사이트를 다른 회사의 것으로 바꿔도 그대로 쓸 수 있는가?** → 그렇다면 브리프에 맞춘 것이 없다
|
||
2. **2단계에서 정한 한 문장 컨셉이 화면에서 보이는가?** → 안 보이면 컨셉이 문서에만 있는 것이다
|
||
3. **감수하기로 한 리스크가 실제로 들어갔는가?** → 구현 중에 안전한 쪽으로 후퇴하지 않았는지
|
||
4. **1단계 레퍼런스 R2(다른 업종의 톤)의 흔적이 있는가?** → 없으면 결국 R1을 베낀 것이다
|
||
5. **강조색이 하나인가?**
|
||
6. **여백이 의도적인가, 남은 것인가?**
|
||
|
||
---
|
||
|
||
## 6. 최종 게이트
|
||
|
||
전부 통과해야 끝난다.
|
||
|
||
- [ ] 0장 기계 검사 3종 통과
|
||
- [ ] 접근성 표 전 항목 통과
|
||
- [ ] 성능 예산 내 (또는 초과 이유 명시)
|
||
- [ ] 반응형 체크리스트 통과
|
||
- [ ] 콘텐츠 체크리스트 통과
|
||
- [ ] 5장 여섯 질문에 정직하게 답했고, 실패 항목을 고쳤다
|
||
- [ ] `antipatterns.md` 자가 채점표 통과
|
||
|
||
**하나라도 실패하면 출시가 아니라 4단계 복귀다.**
|
||
|
||
> 근거: research/references/04-ai-slop-signatures.md, research/motion/01-principles.md, research/three/04-performance.md (조사일 2026-08-20)
|