designpaca/research/references/02-methodology.md
Yun Chan 8808c672dc designpaca 초기 구현 — 스킬 · 설치 CLI · 배포 파이프라인
웹 디자인 파이프라인 스킬과 이를 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)
2026-08-20 10:48:00 +09:00

20 KiB
Raw Permalink Blame History

02 — 레퍼런스 해체·합성 방법론

이 문서는 두 부분이다. §14: 사람 디자이너가 레퍼런스를 다루는 방식 (원리). §58: 이미지를 보지 못하는 AI 에이전트가 그 원리를 실행하는 절차 (실무).

designpaca 스킬은 §6의 6축 해체 시트와 §7의 3-소스 합성 규칙을 강제 산출물로 삼는다.


1. 원칙: 베끼기와 참고의 경계

1.1 무엇을 훔치고 무엇을 훔치지 않는가

Austin Kleon의 Steal Like an Artist가 말하는 "훔치기"는 결과물 복제가 아니라 분해 → 원리 추출 → 재조합이다. 실무에서 이 경계는 다음과 같이 그어진다.

훔쳐도 되는 것 (원리) 훔치면 안 되는 것 (표현)
그리드 비율 (예: 2:1 비대칭 분할) 그 사이트의 레이아웃 전체 배치
타입 스케일 비율 (예: 1.333) 폰트 조합 그대로
색의 역할 배분 (배경 60 / 중립 30 / 강조 10) 색상값 그 자체
여백 리듬 (섹션 간 120px, 요소 간 24px) 섹션 구성 순서 그대로
모션의 의도 (스크롤 = 시선 유도) 특정 애니메이션 시퀀스 복제
정보 위계 결정 (무엇을 1순위로 뒀나) 카피 문장

판별 기준 한 줄: 레퍼런스를 언어로 설명했을 때 그 설명이 여러 다른 결과물로 구현될 수 있으면 원리, 하나의 결과물로만 이어지면 표현이다. 원리만 가져가라.

1.2 레퍼런스를 3개 이상 쓰는 이유

레퍼런스가 1개면 모방이다. 2개면 절충이다. 3개 이상이어야 합성이 된다. 그리고 3개는 서로 다른 층위에서 골라야 한다 (§7 참조).

1.3 레퍼런스를 쓰지 않았을 때 벌어지는 일

레퍼런스 없이 생성한 디자인은 학습 데이터의 최빈값으로 수렴한다. 그 최빈값이 정확히 04번 문서에 나열된 AI 슬롭 시그니처다. 레퍼런스 참고는 취향의 문제가 아니라 최빈값 회피 장치다.


2. 6축 해체 프레임워크

레퍼런스 하나를 볼 때 반드시 이 6축으로 뜯는다. 축마다 숫자 또는 규칙으로 기록한다. "세련됐다", "깔끔하다" 같은 형용사는 기록이 아니다.

축 1 — 레이아웃 그리드

기록할 것:

  • 컬럼 수와 거터 (12컬럼 / 24px 거터 / 최대폭 1280px 같은 식)
  • 콘텐츠 최대폭과 뷰포트 폭의 비 (예: 1440 뷰포트에 1120 컨테이너 = 78%)
  • 대칭인가 비대칭인가. 비대칭이면 분할 비율 (2:1, 3:2, 5:7 등)
  • 그리드를 깨는 요소가 있는가 (풀블리드 이미지, 오버행 타이틀)
  • 본문 텍스트 한 줄의 글자 수 (영문 4575자 / 국문 2540자가 정상 범위)

질문: "이 사이트는 무엇을 정렬시키고 무엇을 일부러 어긋나게 했는가?"

축 2 — 타입 스케일

기록할 것:

  • 실제 사용된 폰트 크기 목록 (예: 14 / 16 / 20 / 32 / 56 / 96)
  • 그 사이의 비율 (1.2 minor third / 1.25 major third / 1.333 perfect fourth / 1.5)
  • 서로 다른 크기가 몇 단계 쓰였나 (좋은 디자인은 보통 35단계. 8단계 이상이면 통제 실패)
  • 폰트 패밀리 수 (2개가 표준. 3개 이상이면 이유가 있어야 함)
  • 굵기 대비 (400 vs 700처럼 극단으로 벌렸나, 500 vs 600처럼 붙였나)
  • line-height: 본문 1.51.7, 헤드라인 1.01.2가 일반 범위
  • letter-spacing: 대형 헤드라인은 보통 음수(-0.02em ~ -0.04em)

질문: "가장 큰 글자와 본문의 비는 몇 배인가?" (4배 미만이면 위계가 약하다)

축 3 — 컬러 역할

색상값이 아니라 역할을 기록한다.

역할 기록 항목
surface (배경) 몇 단계의 배경이 있나. 순백/순흑인가 아니면 오프화이트/오프블랙인가
text 본문 / 보조 / 비활성 3단계가 있나
accent 강조색이 몇 %의 면적을 차지하나 (10% 이하가 정상)
border 테두리가 존재하나, 아니면 배경 차이로만 구분하나
state hover / focus / active / disabled가 별도 색인가

60-30-10 규칙: 지배색 60% / 중립 30% / 강조 10%. 레퍼런스에서 이 비율이 어떻게 깨져 있는지가 그 사이트의 성격이다.

질문: "강조색을 지우면 이 페이지는 여전히 읽히는가?" (읽혀야 정상이다)

축 4 — 여백 리듬

기록할 것:

  • 기본 단위 (4px / 8px 그리드인가)
  • 섹션 간 수직 여백 (데스크톱에서 80160px가 일반 범위)
  • 요소 간 여백과 섹션 간 여백의 비율 (보통 1:4 ~ 1:6)
  • 여백 값이 몇 종류인가 (46종이 건강. 모든 곳이 같은 값이면 리듬이 없다)
  • 좌우 패딩 (모바일 1624px, 데스크톱 2480px)

질문: "이 페이지에서 가장 큰 빈 공간은 어디이고, 왜 거기인가?"

축 5 — 모션 언어

기록할 것:

  • 트리거: 로드 / 스크롤 진입 / 호버 / 클릭 / 커서 위치 중 무엇에 반응하나
  • duration: 마이크로(100200ms) / 트랜지션(200400ms) / 연출(600ms+)
  • easing: ease-out인가 spring인가. bounce가 있으면 대개 잘못된 선택이다
  • 모션이 정보를 전달하나 (상태 변화·연속성) 아니면 장식인가
  • 스크롤 연출이 콘텐츠를 가리는가 (reveal 실패 시 빈 화면이 되는가)
  • prefers-reduced-motion 대응이 있나

질문: "모션을 전부 끄면 이 사이트는 여전히 작동하는가?" (작동해야 정상이다)

축 6 — 시선 흐름

기록할 것:

  • 첫 시선 진입점 (가장 큰 대비를 가진 요소)
  • 2번째, 3번째로 눈이 가는 곳
  • 그 순서가 비즈니스 우선순위와 일치하는가
  • Z 패턴인가 F 패턴인가 단일 축 수직 낙하인가
  • CTA가 시선 경로 위에 있나, 아니면 옆에 비켜 있나

측정 방법 (squint test): 눈을 가늘게 뜨거나 이미지를 강하게 블러 처리한다. 디테일이 사라지고 명암 덩어리만 남았을 때 먼저 보이는 것이 실제 진입점이다. AI 에이전트는 눈을 못 뜨므로 대신 회색조 위계 서술을 만든다 (§6.3).


3. 프로가 실제로 하는 순서

  1. 브리프 한 줄 먼저. 레퍼런스를 모으기 전에 "이 사이트는 누구에게 무엇을 하게 만드나"를 한 문장으로 쓴다. 이 문장이 없으면 수집은 취향 나열이 된다.
  2. 넓게 모은다. 4060개를 빠르게 수집. 이 단계에서는 판단하지 않는다.
  3. 1220개로 잘라낸다. 브리프 문장과 연결되지 않는 것을 전부 버린다.
  4. 각 레퍼런스에 "역할표"를 붙인다. 이 이미지는 색을 위해 / 이건 그리드를 위해 / 이건 질감을 위해. 역할이 안 붙는 레퍼런스는 그냥 예쁜 것이므로 버린다.
  5. 6축으로 해체한다 (§2). 형용사가 아니라 숫자로 기록.
  6. 합성한다 (§7).
  7. 자가 검증한다 (§8).

4. 무드보드 구성법

4.1 좋은 무드보드의 조건

  • 결정을 내리게 하는가. 보기 좋기만 한 보드는 실패다. 각 항목이 "이 결정을 위해 여기 있다"를 말해야 한다.
  • 의도적 그룹핑. 색 / 질감 / 구조 / 타입 / 모션으로 묶는다. 아무데나 붙이지 않는다.
  • 반례를 포함한다. "이렇게는 안 한다"의 예시 23개를 넣으면 방향이 훨씬 선명해진다.
  • 웹 밖의 것을 30% 이상 넣는다. 웹 갤러리만 보면 웹처럼 생긴 것만 나온다. 인쇄물, 포스터, 패키지, 영화 타이틀, 건축 사진을 섞어라.

4.2 AI 에이전트용 무드보드 = 텍스트 무드보드

에이전트는 이미지 보드 대신 MOODBOARD.md 파일을 만든다. 형식:

## 브리프 한 줄
[누가] 이 페이지에 와서 [무엇]을 하게 만든다. 그때 느껴야 할 것은 [형용사 2개].

## 레퍼런스 (역할 명시 필수)
### R1 — 구조 담당: <이름> <URL>
- 그리드: 비대칭 5:7, 최대폭 1200
- 섹션 간 여백: 140px
- 왜 골랐나: 브리프의 "정보량이 많지만 답답하지 않게"에 대응

### R2 — 톤 담당: <이름> <URL>
- 색 역할: 오프화이트 #F7F5F2 배경 / 잉크 #14120F 텍스트 / 강조 단 하나
- 타입: 세리프 디스플레이 + 그로테스크 본문, 비율 1.333
- 왜 골랐나: 브리프의 "신뢰감"

### R3 — 디테일 담당: <이름> <URL>
- 모션: 스크롤 진입 시 8px 상승 + 페이드, 320ms, ease-out
- 호버: 밑줄이 좌→우로 그려짐
- 왜 골랐나: 과하지 않게 살아있는 느낌

## 안 할 것 (반례)
- 보라-파랑 그라디언트 히어로
- 아이콘 상단 배치 3열 균등 카드
- 다크 모드 기본값

## 결정 사항 (위 3개에서 합성한 결과)
- 그리드: R1의 5:7을 채택하되 최대폭은 1120으로 축소
- 팔레트: R2의 역할 구조 채택, 색상값은 브랜드 기준으로 교체
- 모션: R3 채택, duration만 280ms로 단축

5. AI 에이전트의 현실: 이미지를 못 볼 때 무엇을 하는가

5.1 전제

에이전트는 갤러리 사이트의 스크린샷을 볼 수 없는 경우가 많다. Awwwards·Godly의 카드는 이미지이고, WebFetch는 이미지를 텍스트로 바꿔주지 않는다. 그러므로 전략은 **"이미지를 보는 것"이 아니라 "구조를 읽는 것"**이다.

5.2 세 가지 접근 경로 (우선순위 순)

경로 A — 레퍼런스 사이트 본체를 직접 읽는다 (가장 정확)

갤러리에서 링크된 원본 사이트WebFetch한다. 갤러리 카드가 아니라 실물이다. 얻을 수 있는 것: 카피 톤, 섹션 순서, 정보 위계, 내비게이션 구조, 헤딩 계층. 얻을 수 없는 것: 색, 폰트, 여백, 모션 (CSS는 마크다운 변환에서 소실됨).

경로 B — 텍스트 설명이 있는 소스를 우선한다 (가장 효율적)

이미지 대신 말로 설명해주는 소스를 골라라. 01번 카탈로그에서 이 성격의 사이트:

소스 얻는 것
Typewolf 특정 사이트가 쓴 폰트 이름 + 대체 무료 폰트
Fonts In Use 폰트의 역사적·산업적 톤
Eyecandy (eyecannndy.com) 모션 기법에 붙은 이름 (예: "displacement", "kinetic type")
UI Sources 인터랙션을 문장으로 분해한 해설
UX Bites (Built for Mars) 특정 앱 UX가 왜 좋은지 서술
DesignSystems.one 실제 시스템의 토큰 값 (design.md 다운로드)
designmd.app AI 에이전트용으로 정제된 561개 디자인 시스템 정의
Codrops 효과의 소스 코드 그 자체
Happy Hues 색을 "역할"로 서술한 팔레트

경로 C — 브라우저 도구가 있으면 computed style을 뽑는다 (가장 강력)

Chrome DevTools MCP / Playwright를 쓸 수 있으면 실제 렌더된 값을 읽을 수 있다. 이때 뽑을 것: font-family, font-size, line-height, letter-spacing, color, background-color, border-radius, box-shadow, padding, gap, max-width, transition.

같은 일을 하는 기성 도구:

  • Dembrandt (github.com/dembrandt/dembrandt) — Playwright로 렌더 후 토큰 추출. MCP 클라이언트에서 도구로 사용 가능
  • Design Extractor / Design Snap — 크롬 확장. computed style → design.md 생성

5.3 WebFetch에 던질 프롬프트 템플릿

WebFetch는 페이지를 마크다운으로 바꿔 작은 모델에게 질문을 던진다. 그러므로 "예쁜지 물어보면 안 되고, 구조를 물어야 한다."

레퍼런스 사이트 본체에 던질 프롬프트:

이 페이지의 구조를 분석해줘. 다음을 순서대로 답해라.
1. 상단부터 순서대로 섹션 목록 (각 섹션의 역할을 한 단어로)
2. h1의 정확한 문장, h2 목록
3. CTA 문구 전부와 각각의 위치
4. 내비게이션 항목 목록
5. 이 페이지가 독자에게 시키려는 단 하나의 행동
6. 카피의 톤 (문장 길이, 1인칭/2인칭, 전문용어 밀도)
7. 숫자·지표가 사용된 곳과 그 값
추측하지 말고 페이지에 실제로 있는 것만 답해라. 없으면 "없음"이라고 써라.

폰트를 알고 싶을 때 (Typewolf 등):

이 페이지에서 언급된 폰트 이름을 전부 나열하고,
각각이 헤드라인용인지 본문용인지, 유료인지 무료인지,
그리고 제시된 무료 대체 폰트가 있으면 함께 적어라.

모션 기법을 알고 싶을 때 (Eyecandy, Codrops):

이 페이지에서 설명하는 애니메이션 기법의 이름, 그 기법이 무엇을 하는지,
그리고 구현에 쓰인 CSS 속성이나 라이브러리를 나열해라.

5.4 검색으로 레퍼런스를 "말로" 확보하는 법

WebSearch는 이미지를 못 주지만, 디자인을 서술한 글은 준다. 유효한 쿼리 형태:

  • "<사이트명>" web design analysis typography color — 특정 사이트 분해 글
  • awwwards site of the day <YYYY-MM> what makes it work — 최근 수상작 해설
  • <업종> landing page teardown 2026 — 티어다운 글
  • <브랜드> design system tokens color typography — 토큰 공개 여부 확인
  • site:typewolf.com <폰트명> — 폰트 사용례

5.5 하지 말아야 할 것

  • 갤러리 홈페이지만 WebFetch하고 "레퍼런스를 봤다"고 말하기. 홈페이지에는 카드 이미지뿐이라 정보가 없다.
  • 레퍼런스 이름만 나열하고 넘어가기. 6축 수치가 없으면 참고한 게 아니다.
  • 이미지를 못 본다는 이유로 레퍼런스 단계를 건너뛰기. 경로 B만으로도 폰트·색 역할·모션 언어는 확보된다.

6. 실전 절차: 에이전트용 8단계

6.1 절차

단계 행동 산출물
1 브리프를 한 문장으로 압축 [대상]이 [행동]하게. 느낌은 [형용사 2개]
2 01번 §0 라우팅 표로 갤러리 3개 선택 갤러리명 3개 + 선택 이유
3 각 갤러리에서 실제 사이트 URL 1개씩 확보 원본 URL 3개
4 각 URL을 §5.3 템플릿으로 WebFetch 섹션 구조 3벌
5 텍스트 소스로 폰트·색·모션 보강 (§5.2 경로 B) 폰트명, 팔레트 역할, 모션 기법명
6 6축 해체 시트 작성 (§2) 축별 숫자·규칙
7 3-소스 합성 (§7) 최종 결정 사항 목록
8 자가 검증 (§8) 통과 여부 + 재작업 항목

6.2 6축 해체 시트 템플릿

### 레퍼런스: <이름> — <URL>
| 축 | 관측값 | 내 프로젝트에 가져갈 것 |
|---|---|---|
| 그리드 | 최대폭 1200 / 비대칭 7:5 / 거터 32 | 비대칭 비율만 |
| 타입스케일 | 15/17/21/34/68 (≈1.28) / 패밀리 2개 | 비율 1.25로 조정해 채택 |
| 컬러 역할 | 배경 1단계 / 텍스트 3단계 / 강조 1색 · 면적 6% | 구조 채택, 색상값 교체 |
| 여백 리듬 | 8px 단위 / 섹션간 120 / 요소간 24 (1:5) | 그대로 |
| 모션 | 스크롤 진입 fade+8px / 300ms / ease-out | 채택, 280ms |
| 시선 흐름 | 대형 헤드라인 → 제품샷 → CTA (단일 수직축) | 채택 |

6.3 이미지를 못 볼 때의 squint test 대체 — "회색조 위계 서술"

에이전트는 실제 화면을 흐리게 볼 수 없으므로, 자기가 만들 화면에 대해 다음을 문장으로 쓴다.

색을 전부 제거하고 회색조로 봤을 때 이 페이지에서 가장 어두운(=가장 강한) 덩어리는 ___이고,
두 번째는 ___, 세 번째는 ___이다.
이 순서는 비즈니스 우선순위 [1위 ___ / 2위 ___ / 3위 ___]와 일치한다 / 일치하지 않는다.

일치하지 않으면 크기·굵기·대비를 조정한다. 색으로 해결하려 들지 마라 — 색을 빼도 위계가 서야 한다.


7. 3-소스 합성 규칙

7.1 층위를 분리해서 고른다

레퍼런스 3개를 같은 층위에서 고르면 안 된다. 3개 다 "예쁜 랜딩페이지"면 평균이 나온다. 반드시 아래처럼 역할을 나눠 고른다.

슬롯 무엇을 가져오나 어디서 고르나
R1 · 구조(Skeleton) 그리드, 섹션 순서, 정보 위계, 여백 리듬 같은 업종·같은 목적의 사이트 (Land-book, Refero, Lapa Ninja)
R2 · 톤(Skin) 색 역할, 타입 페어링, 질감, 형태 언어 다른 업종의 사이트 또는 웹이 아닌 것 (SiteInspire, The Brand Identity, Typographic Posters)
R3 · 디테일(Spark) 모션 하나, 호버 하나, 전환 하나 Codrops, Eyecandy, Design Spells, Details Matter

핵심은 R2가 R1과 다른 업종이어야 한다는 것. SaaS 구조 + SaaS 톤 = 또 하나의 SaaS 슬롭. SaaS 구조 + 독립 출판사의 톤 = 차별화.

7.2 합성 시 충돌 해결 규칙

레퍼런스 3개가 서로 어긋날 때의 우선순위:

  1. 가독성·접근성이 항상 이긴다. R2의 톤이 대비를 깨면 톤을 조정한다.
  2. R1의 구조가 R3의 모션을 이긴다. 모션 때문에 구조를 바꾸지 않는다.
  3. 브리프 한 줄이 모든 레퍼런스를 이긴다. 레퍼런스가 브리프와 충돌하면 레퍼런스를 버린다.
  4. 하나의 축은 하나의 소스에서만 가져온다. 그리드는 R1에서만, 팔레트는 R2에서만. 축을 섞으면 이유 없는 절충이 된다.

7.3 "그대로 가져오지 않았음"을 증명하는 변형 3가지

각 레퍼런스마다 최소 하나씩 의도적으로 바꾼다. 그리고 왜 바꿨는지 한 줄로 적는다.

  • 비율 변형: 타입 스케일 1.333 → 1.25 (정보량이 많아 단계 간 점프를 줄임)
  • 역전 변형: 레퍼런스는 좌측 텍스트/우측 이미지 → 우측 텍스트/좌측 이미지 (읽기 흐름상 CTA를 우하단에 두기 위해)
  • 제거 변형: 레퍼런스의 3개 요소 중 1개 삭제 (해당 정보가 우리 브리프엔 없음)

8. 자가 검증 체크리스트

8.1 Awwwards 채점 축으로 자가 채점

Awwwards의 실제 배점은 **Design 40% / Usability 30% / Creativity 20% / Content 10%**이다. Creativity가 20%뿐이라는 점이 중요하다 — 화려함은 4순위다.

항목 자문 통과 기준
Design 40 타입 스케일·그리드·리듬이 전 브레이크포인트에서 일관한가 6축 시트의 값이 실제 코드에 반영됐는가
Usability 30 모션 끄고, 색 빼고, 키보드만으로 쓸 수 있는가 3개 다 예
Creativity 20 이 페이지에 이 프로젝트만의 결정이 최소 1개 있는가 그 결정을 한 문장으로 말할 수 있어야 함
Content 10 카피가 경쟁사 이름으로 바꿔도 말이 되는가 말이 되면 실패 (§8.2)

8.2 경쟁사 치환 테스트

카피에서 제품/회사 이름을 경쟁사 이름으로 바꿔 읽는다. 여전히 자연스러우면 그 카피는 아무것도 말하지 않는 것이다. 다시 써라.

8.3 최종 게이트 (하나라도 걸리면 재작업)

  • 레퍼런스 3개의 URL과 각각의 **역할(R1/R2/R3)**을 말할 수 있다
  • 6축 해체 시트에 형용사가 아닌 숫자가 들어 있다
  • R2가 R1과 다른 업종이다
  • 각 레퍼런스마다 의도적 변형 1개와 그 이유가 있다
  • 회색조 위계 순서가 비즈니스 우선순위와 일치한다
  • 04번 문서의 금지 목록을 훑고, 걸린 항목이 없다
  • 모션을 전부 끄고도 페이지가 작동한다
  • 강조색을 지워도 페이지가 읽힌다
  • 카피가 경쟁사 치환 테스트를 통과한다

9. 요약 카드 (스킬에 그대로 넣을 수 있는 형태)

[레퍼런스 프로토콜]
1. 브리프 1줄 → 2. 갤러리 3개 선택(01번 §0 라우팅) → 3. 원본 URL 3개 확보
4. WebFetch 구조 분석(02번 §5.3 템플릿) → 5. 텍스트 소스로 폰트·색·모션 보강
6. 6축 해체 시트(그리드/타입스케일/컬러역할/여백리듬/모션언어/시선흐름)
7. 3-소스 합성(R1 구조 · R2 톤 · R3 디테일, R2는 반드시 다른 업종)
8. 자가 검증(§8.3 9개 항목) → 하나라도 실패 시 6번으로 복귀

[금지]
- 갤러리 홈만 열어보고 "참고했다"고 말하기
- 형용사만 적힌 해체 시트
- 3개 레퍼런스를 같은 층위에서 고르기
- 이미지를 못 본다는 이유로 이 절차를 건너뛰기