designpaca/research/skills/05-recommendations.md

# 05. designpaca 설계 원칙 10가지

작성일: 2026-08-20
근거: 01(로컬 스킬 해부), 02(기법 카탈로그), 03(포맷 스펙)에서 도출.
각 원칙은 **주장 / 근거 / designpaca에서의 구체 형태 / 반대 의견과 그에 대한 답** 4부로 쓴다.

---

## 원칙 1. SKILL.md 본문은 절차와 인덱스만 담는다. 지식은 references/로 뺀다.

### 주장
SKILL.md 본문은 **400~480줄, 5,000토큰 이내**로 유지한다. 미학 지식(anti-pattern 카탈로그, 타이포그래피, 컬러, 레이아웃, 모션, 반응형, 디자인 시스템 매핑)은 전부 `references/*.md`로 분리한다. 본문에는 (a) 절차, (b) 참조 파일 인덱스 표, (c) 필수 게이트만 남긴다.

### 근거
세 가지가 겹친다.

**첫째, 공식 권고 수치가 명확하다.**
> "Keep SKILL.md body under 500 lines for optimal performance"
> "**Instructions** (< 5000 tokens recommended)"
> — Anthropic best practices / Agent Skills spec

**둘째, 컨텍스트 수명이 하드 제약이다.**
> "the rendered `SKILL.md` content enters the conversation as a single message and **stays there for the rest of the session**"
> "Claude Code re-attaches the most recent invocation of each skill after the summary, **keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens.**"
> — Claude Code skills docs

design-taste-frontend는 1,206줄(약 22K 토큰)이다. 컴팩션 한 번이면 앞 5K만 남는다. **§9 AI Tells도 §14 Pre-Flight도 사라진다.** 그리고 25K 공유 예산을 혼자 다 먹어서 다른 스킬을 밀어낸다.

**셋째, 참조 파일은 읽기 전까지 0토큰이다.**
> "**No context penalty for large files:** Reference files, data, or documentation don't consume context tokens until actually read"
> — Anthropic best practices

**대조군이 있다.** dataviz는 SKILL.md 약 80줄 + `references/` 7개 + `scripts/` 2개다. 같은 밀도의 지식을 1/10 토큰으로 상주시킨다. Hallmark도 SKILL.md는 절차만 담고 지식은 전부 참조 파일이다.

### designpaca에서의 구체 형태

```
designpaca/
├── SKILL.md                      # 400~480줄
├── references/
│   ├── anti-patterns.md          # AI 텔 카탈로그 (무엇/왜/대신)
│   ├── slop-gates.md             # 출력 후 예/아니오 게이트
│   ├── typography.md
│   ├── color.md
│   ├── layout.md                 # 매크로구조 인덱스
│   ├── motion.md
│   ├── copy.md
│   ├── responsive.md             # 실무 렌더링 버그 포함
│   ├── design-systems.md         # 공식 DS 매핑 + 설치 명령
│   ├── redesign.md
│   └── design-md-template.md
├── assets/themes/                # 테마별 개별 파일
└── scripts/                      # 선택
```

본문의 인덱스는 dataviz 형식을 따른다:
```markdown
| File | What it answers | When to load |
|------|-----------------|--------------|
| `references/anti-patterns.md` | 무엇이 AI처럼 보이는가 | 항상, 출력 직전 |
| `references/typography.md` | 폰트 페어링·스케일 | 타입 결정 시 |
| `references/design-systems.md` | 공식 DS를 써야 하나 | 브리프가 대시보드/엔터프라이즈일 때만 |
```

**규칙**: 참조 파일은 SKILL.md에서 1단계로만 링크. 참조 파일끼리 링크 금지. 100줄 넘는 참조 파일에는 목차.

### 반론과 답
**반론**: "참조 파일을 안 읽고 넘어가면 어쩌나."
**답**: 그래서 "언제 로드하는가"를 인덱스에 명시하고, 절차 단계에 "지금 X를 읽어라"를 박아넣는다. Hallmark가 그렇게 한다. 그리고 안 읽고 넘어가는 실패보다 **컴팩션으로 통째로 사라지는 실패가 훨씬 크다.**

---

## 원칙 2. 가장 중요한 규칙 3~5개를 파일 최상단에 별도 블록으로 둔다.

### 주장
프론트매터 바로 다음, 제목·역할 부여·개요보다 **먼저** 핵심 규칙 블록을 놓는다. 그 블록은 "이 규칙은 모델의 기본 동작을 이긴다"고 명시한다.

### 근거
**컴팩션 생존선이 앞 5,000토큰이다.** 물리적으로 앞에 있어야 살아남는다.

그리고 긴 문서에서 후반부 지시 준수율이 떨어진다는 것은 실무 관찰로 확인된다. design-taste-frontend가 §4.7에서 스스로 인정한다:
> **EYEBROW RESTRAINT (mandatory, the #1 violated rule in production tests).**

가장 많이 위반되는 규칙이 문서 중반에 있다.

imagegen-frontend-web은 반대로 했다. 파일 6번째 줄:
> # HARD OUTPUT RULE — READ FIRST
> **Generate one separate horizontal image PER section. Always. No exceptions.**
> ...
> **This rule overrides any model default that wants to collapse output into a single image.**

마지막 문장이 중요하다. **규칙이 모델 기본값과 싸운다는 사실을 명시**한다.

### designpaca에서의 구체 형태

프론트매터 직후:

```markdown
# READ FIRST — 이 5가지는 다른 모든 판단보다 먼저다

1. **프로젝트에 `design.md`가 있으면 그것이 최상위다.** 이 스킬의 모든 기본값을 덮어쓴다.
   없으면 기존 코드에서 토큰(폰트/팔레트/스페이싱/반경)을 먼저 읽는다.
2. **코드를 쓰기 전에 Design Read 한 줄과 선택(구조·테마·다이얼)을 평문으로 출력한다.**
   선언 없이 시작한 출력은 실패로 간주한다.
3. **트리트먼트를 먼저 정한다.** 메모·플랜·데모는 유틸리티, 랜딩·포트폴리오는 에디토리얼.
   확신이 안 서면 유틸리티 쪽. 과잉 디자인이 과소 디자인보다 나쁘다.
4. **색·폰트는 반드시 명명 토큰을 경유한다.** 인라인 hex, 인라인 font-family, `text-white`
   같은 직접 색 클래스는 금지. 토큰에 없으면 토큰을 먼저 추가한다.
5. **없는 것을 만들어내지 않는다.** 지표, 후기, 로고, 스크린샷. 없으면 라벨 붙은
   플레이스홀더를 두고 사용자에게 요구한다. 숫자 모양의 구멍은 정직하고, 지어낸 숫자는 슬롭이다.

이 5가지는 모델의 기본 동작과 충돌한다. 충돌할 때 이 규칙이 이긴다.
```

### 반론과 답
**반론**: "역할 부여가 먼저 와야 톤이 잡히지 않나."
**답**: 역할 부여는 그 다음 20줄에 놓아도 효과가 유지된다. 규칙은 위치에 민감하지만 페르소나는 덜하다. 그리고 5개 규칙 자체가 이미 톤을 전달한다.

---

## 원칙 3. description은 3부 구성으로 200~350자. 확장 프론트매터는 쓰지 않는다.

### 주장
프론트매터는 `name`과 `description` **둘뿐**. description은 (1) 무엇을 하는가, (2) 어떤 요청에서 발동하는가(한국어·영어 리터럴 문구 포함), (3) 어떤 요청에서는 발동하지 않는가로 구성하고 **200~350자**를 지킨다.

### 근거

**확장 필드는 크로스툴 배포를 깬다.**
> "**If you include any field the spec doesn't allow, packaging or upload fails with a hard error** instead of ignoring the field: `Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name`"
> — Claude Code skills docs

로컬 커뮤니티 디자인 스킬 13개 전부가 이미 `name`+`description`만 쓴다. 이건 우연이 아니라 수렴이다.

**길이 상한은 두 겹이다.**
- 스펙 상한: 1,024자
- Claude Code 목록 상한: description + when_to_use 합쳐 1,536자
- **실효 상한: 스킬 목록 예산.** "The budget scales at 1% of the model's context window" — 이 사용자 환경에는 스킬이 40개 이상이라 긴 description은 잘린다.

imagegen-frontend-web의 620자 description은 이 환경에서 위험하다.

**배제 조건이 과잉 발동을 막는 유일한 방법이다.** Codex 문서가 스펙 수준에서 이걸 요구한다:
> `description: Explain exactly when this skill **should and should not** trigger.`

**한국어 리터럴이 필요하다.** 이 사용자는 한국어로 대화한다. `codex-image`가 한국어 발화를 나열한 이유가 그것이다.

### designpaca에서의 구체 형태

```yaml
---
name: designpaca
description: >-
  웹 UI를 새로 만들거나 다시 디자인할 때 쓴다. 랜딩페이지, 포트폴리오,
  마케팅·제품 페이지, 기존 사이트 리디자인이 대상이다. "랜딩 만들어줘",
  "디자인 예쁘게", "이 페이지 다시 디자인", "UI 만들어줘", "design a landing page",
  "make this look better", "redesign this page" 같은 요청에 발동한다.
  브리프를 먼저 읽고 방향을 선언한 뒤, 템플릿처럼 보이지 않는 UI를 만든다.
  대시보드·데이터테이블·차트·네이티브 모바일 앱, 그리고 버그 수정이나
  기능 추가처럼 시각 결과가 목적이 아닌 작업에는 쓰지 않는다.
---
```

(약 300자. 3부 구성 충족. 3인칭. 한/영 리터럴 포함. 배제 조건 명시.)

### 반론과 답
**반론**: "`paths`로 `**/*.tsx`를 걸면 자동 발동이 정확해지지 않나."
**답**: 두 가지 문제가 있다. (1) `paths`는 Claude Code와 Cursor에만 있고 Codex에는 없다. (2) **새 페이지를 만들 때는 파일이 아직 없다.** 디자인 스킬의 가장 흔한 진입점("랜딩 만들어줘")에서 작동하지 않는다.

---

## 원칙 4. 모든 규칙은 조건부다. 하드 밴에는 반드시 오버라이드 경로를 붙인다.

### 주장
"절대 금지"를 기본 문법으로 쓰지 않는다. **"기본값으로는 지양 + 오버라이드 조건 + 설명 의무"** 3단이 표준 형태다. 예외는 원칙 5에서 정의하는 소수의 하드 게이트뿐이다.

### 근거

**design-taste-frontend v1 → v2가 이 방향으로 갔다.**

v1:
> **THE LILA BAN:** The "AI Purple/Blue" aesthetic is **strictly BANNED**.

v2:
> **THE LILA RULE:** ... is **discouraged as a default**. ...
> **Override:** if the brand or brief explicitly asks for purple / violet / lila, **embrace it.** But execute with intent.

v2 문서 최상단이 철학을 선언한다:
> Every rule below is **contextual**. None of it fires automatically. First read the brief, then pull only what fits.

**Anthropic 공식이 우선순위를 못 박는다.**
> **Where the brief pins down a visual direction, follow it exactly — the brief's own words always win**, including when it asks for one of these looks.
> — frontend-design

> **Precedence is always: the user's own words, then the project's existing system, then your choices.**
> — artifact-design

**탈출구 없는 금지는 두 방향으로 실패한다.** (1) 사용자가 명시적으로 보라색을 요청해도 모델이 거부한다. (2) 모델이 하나를 어기기 시작하면 규칙 체계 전체의 권위가 무너진다.

**"설명 의무"가 오버라이드 남용을 막는다.**
> Serif is only acceptable when ... the aesthetic family is genuinely editorial / luxury / publication **AND you can articulate why this specific serif fits this specific brand**
> **Default-reaching for it because "this is a cookware brief" is banned.**
> — design-taste-frontend §4.1, §4.2

설명할 수 없으면 그건 기본값 회귀라는 뜻이므로 자동으로 걸러진다.

### designpaca에서의 구체 형태

표준 규칙 템플릿:

```markdown
### <규칙 이름>
<무엇이 기본 지양 대상인가. 구체적으로.>

**왜.** <한 문장. 미학이 아니라 결과로 설명.>

**대신.** <실행 가능한 대안 2~3개.>

**해도 되는 경우.** <구체 조건> 이 경우 **왜 이 브리프에 이것이 맞는지 한 문장으로
설명하고 진행한다.** 설명할 수 없으면 기본값으로 회귀한 것이다.
```

우선순위 체인을 본문 상단에 명시:
```
사용자의 명시적 지시 > 프로젝트의 design.md > 프로젝트의 기존 코드 토큰 > 이 스킬의 기본값
```

### 반론과 답
**반론**: "오버라이드를 열어두면 모델이 다 빠져나간다."
**답**: 그래서 원칙 5(하드 게이트)와 짝을 이룬다. 그리고 "설명 의무"가 실질적 장벽이다. 실제로 design-taste-frontend v2가 v1보다 결과가 좋다는 것이 이 스킬이 v1을 "backward compatibility용"으로만 남긴 이유다.

---

## 원칙 5. 하드 게이트는 검증 가능한 것에만 건다. 세거나 grep 할 수 있어야 한다.

### 주장
오버라이드 없는 절대 규칙은 **기계적으로 검증 가능한 항목에만** 적용한다. 취향 판단에는 절대 규칙을 걸지 않는다. 게이트는 20~30개로 제한하고, 각각 예/아니오 질문 형태로 쓴다.

### 근거

**주관적 규칙에 하드 밴을 걸면 지켜지지 않는다.** design-taste-frontend가 그 증거를 문서에 남겼다:
> **The agent has historically ignored em-dash limits when phrased as "use sparingly." The phrasing here is binary: zero em-dashes.**

em-dash는 grep 가능하다. 그래서 이진 규칙이 작동한다.

**반면 카운트 규칙은 즉시 검증된다.**
> **Pre-Flight Check is mechanical:** count instances of `uppercase tracking` across all section components. **If count > ceil(sectionCount / 3), the output fails.**

**체크박스보다 질문형이 낫다.** Hallmark의 58 게이트는 전부 질문이고 정답이 전부 "아니오"다:
> 4. Is any card nested inside another card?
> 10. Is `transition-all` (or `transition: all`) used anywhere?
> 14. Are you animating `width`, `height`, `top`, `left`, `margin`, or `padding` anywhere?
> **If any answer is yes, fix it. Do not ship slop.**

체크박스("- [ ] X를 했는가")는 모델이 무비판적으로 전부 체크한다. 질문형은 실제 검사 행위를 요구한다.

**하지만 58개는 과하다.** design-taste-frontend의 60개 체크박스도 마찬가지다. 매번 정직하게 60개를 검사하는 것은 비현실적이고, 모델은 결국 전부 통과 표시를 한다. **20~30개가 실효 상한**이다.

### designpaca에서의 구체 형태

**본문에 하드 게이트 12개** (가장 자주 깨지고 가장 치명적인 것):

```markdown
## 출력 전 하드 게이트 — 전부 "아니오"여야 한다

1. 인라인 hex/rgb/oklch 색상값이나 인라인 font-family가 토큰 밖에 있는가?
2. 한 페이지에서 액센트 색이 2개 이상인가?
3. 코너 반경 체계가 문서화된 규칙 없이 섞여 있는가?
4. 페이지 중간에 테마(라이트/다크)가 뒤집히는가?
5. 320~1920px 사이 어느 폭에서든 가로 스크롤이 생기는가?
6. 버튼 라벨·내비 링크·CTA가 2줄로 접히는 폭이 있는가?
7. 버튼 텍스트가 버튼 배경과 대비 4.5:1 미만인가?
8. `transform`/`opacity` 외의 속성을 애니메이션하는가?
9. `h-screen`/`100vh`를 풀하이트 섹션에 썼는가? (`100dvh`여야 한다)
10. `window.addEventListener('scroll')`을 썼는가?
11. 사용자가 주지 않은 수치(지표·통계·후기·고객 수)가 페이지에 있는가?
12. `<div>`로 만든 가짜 스크린샷·가짜 브라우저바·가짜 폰 프레임이 있는가?
```

**나머지 게이트는 `references/slop-gates.md`로.** 출력 직전에 그 파일을 읽고 실행한다.

**카운트 규칙 5개**를 본문에:
```
- eyebrow(작은 대문자 라벨) 개수 ≤ ceil(섹션수 / 3), 히어로 포함
- 같은 image+text 스플릿 레이아웃 연속 ≤ 2회
- 마퀴 ≤ 1개
- 8섹션 페이지에 최소 4개의 서로 다른 레이아웃 패밀리
- 히어로: 헤드라인 ≤ 2줄, 서브텍스트 ≤ 20단어, 텍스트 요소 ≤ 4개
```

### 반론과 답
**반론**: "취향 문제야말로 강제해야 하는 것 아닌가."
**답**: 취향은 원칙 4의 조건부 규칙과 원칙 8의 자기 채점으로 다룬다. 하드 게이트에 취향을 넣으면 게이트 전체의 신뢰도가 떨어진다. 모델이 "12번은 지킬 수 없으니 대충 넘어가자"를 배우면 1~11번도 같이 무너진다.

---

## 원칙 6. 프로젝트 루트에 design.md를 쓰고, 다음 실행은 그것을 읽는다.

### 주장
designpaca는 UI만 만들고 끝나지 않는다. **프로젝트 루트에 `design.md`를 쓴다.** 그리고 실행할 때마다 **먼저 그 파일을 찾고, 있으면 스킬 기본값보다 우선한다.** 함께 `.designpaca/log.json`에 이번 실행의 선택(구조·테마·액센트 대역)을 append 한다.

### 근거

**세션 간 일관성 문제는 상태 없이 풀 수 없다.** design-taste-frontend는 이 지시를 세 군데에 넣었다:
> **Palette-rotation rule:** if the previous premium-consumer project you generated used the beige+brass family, this one MUST use a different family.
> - [ ] **Serif discipline**: ... Different serif from your previous project?

**전부 작동하지 않는다.** 모델은 이전 세션을 기억하지 못한다.

**세 개의 독립 프로젝트가 파일 기반 해법에 도달했다.**
- Superdesign: `.superdesign/design-system.md` (필수, 없으면 먼저 생성)
- Hallmark: `design.md` (locked system, "overrides everything") + `.hallmark/log.json` (최근 20개)
- stitch-design-taste: `DESIGN.md` 생성이 스킬의 전부

Superdesign의 DESIGN.md 문서가 이유를 가장 정확히 쓴다:
> Coding agents write great code and mediocre interfaces. One reason: **they have no persistent sense of *how this product is supposed to look*.** `AGENTS.md` and `CLAUDE.md` tell an agent how your code works. **A design system file does the same for how your product looks** ... so every UI the agent ships is consistent with the last one instead of reinventing a generic look each time.
>
> **Capture it once; every design after that is consistent, on-brand, and faster to ship.**

**그리고 이것이 "AI 슬롭"의 정의를 바꾼다.** Hallmark의 관점:
> **Repeating a macrostructure across outputs is the structural fingerprint of templating, which is the AI tell Hallmark exists to defeat.**

개별 페이지가 아무리 예뻐도, 프로젝트 안의 페이지 5개가 같은 구조면 그게 슬롭이다.

### designpaca에서의 구체 형태

**읽기 (Step 0):**
```markdown
## Step 0 — 무엇이 이미 있는지 먼저 읽는다 (질문하기 전에)

1. `design.md` (또는 `.designpaca/design.md`) — 있으면 이것이 최상위다. 스킬 기본값을 전부 덮는다.
2. 없으면 코드에서 추출: 폰트 스택(next/font, @font-face, tailwind config),
   팔레트(`:root`의 hex/hsl/oklch, tokens.json), 스페이싱 스케일, 모션 라이브러리, 프레임워크
3. `.designpaca/log.json` — 최근 3~5개 항목을 읽는다
4. **발견한 것을 파일:줄 인용과 함께 한 번 출력한다.** 사용자가 검증할 수 있어야 한다.
```

**쓰기 (마지막 단계):**
```json
// .designpaca/log.json — 앞에 append, 최근 20개만 유지
{ "date": "2026-08-20", "structure": "<이름>", "theme": "<이름>",
  "accent_band": "warm|cool|neutral|chromatic", "brief": "<한 줄>" }
```

```markdown
<!-- design.md — 사용자가 "시스템 고정"이라고 하면 생성 -->
# Design System: <프로젝트명>
## 1. 제품 맥락 (무엇을, 누구를 위해, 핵심 가치)
## 2. 컬러 (이름 + hex + 역할)
## 3. 타이포그래피 (역할별 폰트 + 스케일)
## 4. 스페이싱·반경·그림자
## 5. 모션 (이징 이름, 지속시간, reduced-motion)
## 6. 컴포넌트 패턴
## 7. 이 프로젝트에서 금지된 것
```

템플릿은 `references/design-md-template.md`에. 작성 규칙은 stitch-design-taste에서:
> - **Be Descriptive:** "Deep Charcoal Ink (#18181B)" — not just "dark text"
> - **Be Precise:** Include exact hex codes, rem values, pixel values
> - Pitfall: 기술 용어를 번역 없이 쓰기 ("rounded-xl" 대신 "generously rounded corners")

### 반론과 답
**반론**: "파일 쓰기 권한이 없는 환경에서는?"
**답**: 로그 쓰기 실패는 조용히 넘어가고, 그 세션 안에서는 명시적 선언(원칙 7)으로 다양성을 유지한다. `design.md`는 사용자가 요청할 때만 쓴다. 읽기는 어디서나 된다.

**반론**: "매번 파일을 읽으면 느리지 않나."
**답**: Hallmark가 답을 준다. `.hallmark/preflight.json`에 캐시하고 "re-scan only on user request or when package.json mtimes are newer".

---

## 원칙 7. 코드를 쓰기 전에 선택을 평문으로 선언한다.

### 주장
Design Read 한 줄 + 선택 프리뷰 블록을 **코드 이전에** 출력한다. 무엇을 골랐는지, 이전 실행과 어느 축에서 다른지, 다이얼 값이 얼마인지를 사용자가 읽을 수 있는 형태로 낸다.

### 근거

**LLM이 나쁜 디자인을 내는 1번 원인은 미학 지식 부족이 아니라 브리프를 안 읽는 것이다.**
> Most LLM design output is bad because **the model jumps to a default aesthetic instead of reading the room.**
> — design-taste-frontend §0

**선언은 세 가지를 동시에 한다.** (1) 선택 행위를 강제한다. (2) 이후 출력이 선언과 일관되게 나온다. (3) 코드 생성 전에 교정 지점을 만든다.

**gpt-taste의 "Python RNG"도 결국 이 효과를 노린 것이다.** 난수는 가짜지만 선언은 진짜다. 그렇다면 가짜 난수를 걷어내고 선언만 남기는 게 정직하다.

**Hallmark의 프리뷰 블록이 형태의 모범이다:**
```markdown
**Hallmark · v1.1.0**
- **Macrostructure** · <name>
- **Theme** · <name>
- **Sections** · <section names>
- **Motion** · <primitives, or "none">
- **Slop test** · <N / 58 pass/fail>
- **Diversification** · <axes that differ from prior run>
```

**단, 전부 보여주면 안 된다.** Anthropic 공식:
> Try to do a lot of this planning and iteration **in your thinking**, and only show ideas to the user when you have higher confidence it'll delight them.

브레인스토밍은 사고 안에서, **결론만** 프리뷰로.

### designpaca에서의 구체 형태

```markdown
## Step 2 — 방향을 선언한다 (코드 전)

먼저 사고 안에서: 후보 방향 2~3개를 만들고, 각각을 브리프에 대조해 가장 특정한 것을 고른다.
비슷한 프롬프트를 머릿속으로 돌려서 같은 곳에 도착하면 그건 기본값이다. 다시 고른다.

그 다음 사용자에게 **결론만** 이 형태로 출력한다:

**designpaca**
- **읽기** · <페이지 종류> for <청중>, <분위기> 언어
- **트리트먼트** · 유틸리티 | 에디토리얼
- **구조** · <매크로구조 이름>
- **타입** · <디스플레이> + <본문> (+ <유틸리티>)
- **컬러** · <액센트 이름 (hex)> / <중성 계열>
- **시그니처** · <이 페이지를 기억하게 만들 단 하나의 요소>
- **모션** · <목록 또는 "없음">
- **다이얼** · variance <n> / motion <n> / density <n>
- **직전과 다른 축** · <축 이름> (로그가 있을 때)
```

**"시그니처" 항목이 원칙 9(대담함은 한 곳에)와 연결된다.** 여기에 하나만 적을 수 있으므로 자동으로 절제가 강제된다.

### 반론과 답
**반론**: "사용자가 빨리 결과를 보고 싶어할 텐데 프리뷰가 방해되지 않나."
**답**: 프리뷰는 9줄이다. 잘못된 방향으로 400줄 HTML을 만드는 것보다 훨씬 빠르다. 그리고 사용자가 "그냥 해"라고 하면 다음 턴부터 생략할 수 있다.

---

## 원칙 8. 트리트먼트를 먼저 정한다. 기본기는 항상, 대담함은 조건부.

### 주장
"디자인할지 말지"가 아니라 **"어느 정도의 트리트먼트가 맞는지"**를 먼저 판단한다. 스킬을 2계층으로 나눈다: **모든 산출물에 적용되는 기본기**와 **에디토리얼 브리프에만 적용되는 대담함**.

### 근거

**디자인 스킬의 두 번째로 큰 실패는 과잉 디자인이다.** 메모에 거대한 히어로를 붙이고, B2B 대시보드에 Awwwards 미학을 씌우는 것. high-end-visual-design과 gpt-taste는 이 실패를 구조적으로 피할 수 없다. 트리트먼트 축이 없기 때문이다.

**artifact-design이 이 문제의 가장 정확한 처방을 담고 있다:**
> **Calibrate treatment, not whether to design.** A doc deserves the same craft as a landing page — **what changes is the treatment that craft is delivered in.**
>
> Many requests call for a more utilitarian treatment: a plan, a memo, a demo. Make it polished ... **but avoid over-designing. Most pages do not need a flashy, gigantic hero.**
>
> **When unsure: a well-composed page is never the wrong answer; an over-designed visual identity sometimes is.**
>
> Fundamentals below apply to everything. **The editorial process after that runs only when the read above says so.**

그리고 UI일 때 무엇이 달라지는지도 명시한다:
> A dashboard or tool is scanned and operated, not read top-to-bottom, so **the craft shifts from typography to information design.** Surface the summary before the detail; encode state in form as well as number.

**design-taste-frontend는 이걸 "범위 밖 선언"으로 처리한다:**
> This skill is NOT for: Dashboards / Data tables / Multi-step forms / Code editors / Native mobile / Realtime collab UIs.
> If the brief is one of the above, **say so explicitly**, point to the right tool.

두 접근을 합치는 게 낫다. **범위 밖은 거절하고, 범위 안에서는 트리트먼트를 보정한다.**

### designpaca에서의 구체 형태

**본문 구조:**
```markdown
## 트리트먼트 보정 (첫 판단)

**에디토리얼** — 랜딩페이지, 포트폴리오, 캠페인 페이지, 제품 소개, 사용자가 자랑할 물건.
  → 대담함 예산 1개. 시그니처 요소 하나. 나머지는 조용히.

**유틸리티** — 내부 도구, 문서 페이지, 관리 화면, 데모, 플랜/메모 페이지.
  → 진짜 타이포그래피 위계, 계산된 여백, 제대로 된 팔레트. 그것으로 충분하다.
     거대한 히어로 없음. 스크롤 연출 없음. 장식 없음.

**정보 밀도형** — 대시보드, 데이터 테이블, 차트 화면.
  → 이 스킬의 미학 규칙 대부분이 적용되지 않는다. 위계는 타이포가 아니라 정보설계가 만든다.
     요약을 먼저, 상세를 나중에. 상태는 숫자만이 아니라 형태로도 인코딩한다
     (필, 칩, 심각도 스트라이프). 의미색(good/warning/critical)은 액센트와 별개다.
     차트가 있으면 dataviz 스킬을 쓴다.

**범위 밖** — 네이티브 모바일(Apple HIG/Material), 코드 에디터(Monaco/CodeMirror),
  실시간 협업 UI. → 그렇다고 말하고 올바른 도구를 알려준다.

확신이 안 서면 유틸리티 쪽으로 기운다.
**잘 구성된 페이지는 틀린 답이 된 적이 없다. 과잉 디자인된 비주얼 아이덴티티는 가끔 틀린 답이다.**

---

## 모든 트리트먼트에 적용되는 기본기
<타이포 위계 / 여백 / 토큰 / 대비 / 반응형 / 포커스 / reduced-motion / 카피>

## 에디토리얼일 때만
<시그니처 요소 / 히어로 논지 / 모션 연출 / 미학적 위험 1개>
```

### 반론과 답
**반론**: "사용자가 designpaca를 부른 건 화려한 걸 원해서 아닌가."
**답**: 아니다. 사용자가 원하는 건 **잘 만들어진 것**이다. artifact-design의 문장이 이 차이를 정확히 잡는다. 그리고 유틸리티 트리트먼트를 명시적으로 인정하지 않으면, 모델은 메모에도 히어로를 붙인다.

---

## 원칙 9. 대담함은 한 곳에만. 나머지는 조용히.

### 주장
"창의적으로 하라"를 지시로 쓰지 않는다. 대신 **시그니처 요소 정확히 하나**를 정하게 하고, 나머지 전부에 절제를 요구한다. 그리고 그 절제를 검증 가능한 수치로 만든다.

### 근거

**"창의적으로"는 모든 섹션에 장식을 붙이는 결과를 낳는다. 그게 슬롭이다.**

**Anthropic 공식이 이 문제의 가장 좋은 프레이밍을 갖고 있다:**
> **Spend your boldness in one place.** Let the signature element be the one memorable thing, keep everything around it quiet and disciplined, and **cut any decoration that does not serve the brief. Not taking a risk can be a risk itself!**
>
> **Consider Chanel's advice: before leaving the house, take a look in the mirror and remove one accessory.**

계획 단계에도 이 항목이 들어간다:
> **Signature:** the single unique element this page will be remembered by that embodies the brief.

**그런데 이것만으로는 검증이 안 된다.** 두 스킬이 이걸 수치로 만들었다:

Hallmark:
> 23. Does the accent colour cover more than ~5 % of any single viewport?

imagegen-frontend-web:
> ### Second-Read Moment
> **Pick exactly 1** unobvious but legible motif and place it deliberately, **once across the page**.
> **Avoid gimmick-for-gimmick: the moment must aid scan order or brand recall.**

**그리고 복잡도를 방향에 맞추는 규칙이 짝을 이룬다:**
> **Match complexity to the vision.** Maximalist directions need elaborate execution; **minimal directions need precision in spacing, type, and detail. Elegance is executing the chosen vision well.**
> — frontend-design

> **Simplicity is not the goal by itself. Cleanliness is the goal.** ... The rule is: **not always simple, always clean**
> — imagegen-frontend-mobile §25

### designpaca에서의 구체 형태

**프리뷰 블록에 "시그니처" 슬롯 1개** (원칙 7). 하나만 적을 수 있다.

**본문 규칙:**
```markdown
## 대담함 예산

이 페이지에서 기억될 요소는 **하나**다. 프리뷰의 "시그니처"에 적은 것.
그 하나에 모든 대담함을 쓰고, 나머지 전부는 조용하고 규율 있게 만든다.

검증:
- 액센트 색은 어느 뷰포트에서도 화면 면적의 5%를 넘지 않는다
- 시그니처 요소 외에 "이건 좀 특이하네" 소리를 들을 만한 것이 2개 이상이면 하나를 뺀다
- 브리프에 봉사하지 않는 장식은 전부 제거한다

위험을 안 지는 것도 위험이다. 시그니처가 "그냥 큰 헤드라인"이면 그건 시그니처가 아니다.

**복잡도는 방향에 맞춘다.** 맥시멀리즘은 정교한 실행을 요구하고, 미니멀리즘은
여백·타입·디테일의 정밀함을 요구한다. **미니멀은 요소를 지우는 게 아니라 남은 것을
정확하게 만드는 것이다.** 단순함이 목표가 아니라 깔끔함이 목표다.
```

### 반론과 답
**반론**: "그럼 결과가 밋밋해지지 않나."
**답**: 반대다. 대담함이 분산되면 아무것도 기억에 안 남는다. 한 곳에 집중되면 그 하나가 기억된다. 그리고 "Not taking a risk can be a risk itself"가 밋밋함에 대한 방어다.

---

## 원칙 10. 미학 규칙과 실무 버그 규칙을 분리한다. 버그 규칙은 협상 불가다.

### 주장
스킬의 규칙을 두 종류로 명확히 나눈다.
- **미학 규칙** — 조건부, 오버라이드 있음, 브리프가 이긴다
- **실무 규칙** — 접근성·성능·반응형·정직성. **오버라이드 없음.** 브리프가 요청해도 안 된다.

그리고 실무 규칙에는 "AI가 반복적으로 만드는 실제 렌더링 버그" 목록을 포함한다.

### 근거

**두 종류가 섞여 있으면 둘 다 약해진다.** "Inter를 쓰지 마라"와 "버튼 텍스트가 배경과 대비 4.5:1을 넘겨라"가 같은 목록에 있으면, 모델은 둘 다 취향 문제로 읽는다.

**여러 소스에서 같은 버그가 반복 등장한다.** 이건 실측 데이터에 가깝다:

`h-screen` → `100dvh`: design-taste-frontend, high-end-visual-design, stitch-design-taste, redesign-existing-projects **4개 스킬 공통**

`transform`/`opacity`만 애니메이션: **거의 모든 소스 공통**

토큰 경유 강제: design-taste-frontend, Hallmark, **v0, Lovable 4개 시스템이 독립적으로 도달**
> "DO NOT use direct colors like text-white, bg-white, bg-black, etc. Everything must be themed via design tokens" — v0
> "DO NOT use direct colors like text-white, text-black, bg-white, bg-black" — Lovable
> "Inline OKLCH/hex/rgb or font declarations are forbidden." — Hallmark

**그리고 미학과 무관한 순수 버그들이 있다:**
> 50. **Image-bearing grid track without `minmax(0, 1fr)`.** — Hallmark
> 51. **Display headers without long-word wrap** (`overflow-wrap: anywhere; min-width: 0`) — Hallmark
> 56. **Sticky element at `top: 0` below a sticky page-level nav.** Auto-fail. — Hallmark
> **NO 100vw widths.** Breaks on scrollbar-visible desktops. — Hallmark
> It's easy to generate CSS classes that cancel each other out (`.section` vs `.cta`) — frontend-design
> Lay out sibling groups with flex or grid and `gap`, **not per-element margins that silently collapse or double** — artifact-design
> **a color whose only definition sits behind `[data-theme]` never applies in the un-stamped state** — artifact-design
> `useState`로 연속값 추적 금지 — "collapses on mobile" — design-taste-frontend
> `loading="lazy"` on LCP — "p75 of 720 ms vs. 364 ms for preloaded" — Hallmark

**정직성도 실무 규칙이다.** 지어낸 지표는 취향 문제가 아니라 신뢰 문제다:
> A page that lies on its proof bar can't be trusted on its claims either ... **The number-shaped hole is honest; the fabricated number is slop.**
> — Hallmark

### designpaca에서의 구체 형태

**본문에 별도 섹션:**

```markdown
## 협상 불가 규칙

아래는 취향이 아니다. 브리프가 요청해도 예외를 두지 않는다.
미학 규칙(조건부)과 달리 이 목록에는 오버라이드 경로가 없다.

### 접근성
- 모든 텍스트와 UI 요소가 배경에 대해 WCAG AA (본문 4.5:1, 18px+ 대형 텍스트 3:1)
- 버튼 텍스트가 버튼 배경에 대해 대비 통과. 고스트 버튼이 사진 위에 있으면 스크림이나 스트로크
- 폼 입력·플레이스홀더·헬퍼·에러 텍스트 전부 대비 통과
- 모든 인터랙티브 요소에 보이는 `:focus-visible`. **포커스 링은 즉시 나타난다.
  절대 페이드인시키지 않는다** (전환 중에는 키보드 사용자가 아무것도 못 본다)
- 터치 타깃 최소 44px
- 색만으로 정보를 전달하지 않는다

### 반응형
- 320~1920px 전 구간에서 가로 스크롤 없음
- 버튼 라벨·내비 링크·CTA는 어느 폭에서도 1줄. 안 되면 라벨을 줄인다 (기본 CTA는 3단어 이하)
- 풀하이트 섹션은 `min-h-[100dvh]`. `h-screen`/`100vh` 금지 (iOS Safari 주소창)
- `width: 100vw` 금지 (스크롤바 있는 데스크톱에서 깨진다). `width: 100%` + 컨테이너 패딩
- 이미지가 들어가는 그리드 트랙은 `minmax(0, 1fr)`. 맨 `1fr` 금지
- 디스플레이 사이즈 텍스트에 `overflow-wrap: anywhere; min-width: 0`
- 다단 레이아웃마다 768px 미만 붕괴 규칙을 같은 컴포넌트 안에 명시
- 페이지 레벨 sticky 아래에 또 다른 `top: 0` sticky 금지

### 성능
- `transform`과 `opacity`만 애니메이션. `top`/`left`/`width`/`height`/`margin`/`padding` 금지
- `window.addEventListener('scroll')` 금지. IntersectionObserver, 스크롤 구동 CSS
  (`animation-timeline: view()`), 또는 라이브러리 훅을 쓴다
- 연속값(마우스 위치, 스크롤 진행률)을 React state로 추적 금지
- `backdrop-blur`는 fixed/sticky 요소에만. 스크롤 컨테이너나 큰 콘텐츠 영역에 금지
- 노이즈/그레인은 `position: fixed; pointer-events: none` 의사요소에만
- LCP 요소에 `loading="lazy"` 금지. `fetchpriority="high"`
- `prefers-reduced-motion: reduce`에서 모든 공간 이동이 150ms 이하 opacity 크로스페이드로 붕괴
- `useEffect` 애니메이션에 정리 함수

### 토큰 규율
- 모든 색과 폰트는 명명된 CSS 커스텀 프로퍼티를 경유한다
- 인라인 hex/rgb/oklch, 인라인 `font-family`, `text-white`/`bg-black` 같은 직접 색 클래스 금지
- 필요한 값이 토큰에 없으면 **토큰을 먼저 추가**하고 참조한다
- 한 페이지 = 하나의 액센트, 하나의 반경 체계, 하나의 테마

### 정직성
- 사용자가 주지 않은 지표·통계·후기·로고·고객 수를 만들지 않는다.
  없으면 라벨 붙은 플레이스홀더(`— / 확인 필요`)를 두거나, 사용자에게 묻거나, 그 섹션을 뺀다
- `<div>`로 가짜 스크린샷·가짜 브라우저바·가짜 폰 프레임·가짜 IDE 크롬을 만들지 않는다
- 이미지 생성 도구가 없고 실제 이미지도 없으면, 라벨 붙은 플레이스홀더 슬롯을 두고
  **응답 끝에 무엇이 필요한지 목록으로 말한다**
- 존재하지 않는 라이브러리를 import 하지 않는다. 쓰기 전에 의존성을 확인한다

### CSS 위생
- 셀렉터 특이성 충돌 주의. 타입 기반(`.section`)과 요소 기반(`.cta`) 셀렉터가
  섹션 간 padding/margin을 두고 서로를 상쇄하는 일이 잦다
- 형제 그룹 간격은 flex/grid의 `gap`으로. 요소별 margin은 조용히 붕괴하거나 두 배가 된다
- 넓은 콘텐츠(테이블·코드·다이어그램)는 자기 컨테이너에 `overflow-x: auto`
- 다크모드는 3상태다. 색을 미디어 쿼리나 `[data-theme]` 블록 안에서만 정의하면
  스탬프 없는 기본 상태에서 적용되지 않는다. `body`에 명시적 배경 토큰을 준다
```

### 반론과 답
**반론**: "이 목록이 길다. 원칙 1(500줄)과 충돌하지 않나."
**답**: 이 섹션은 약 50줄이다. 그리고 **이게 스킬이 실제로 값을 만드는 부분**이다. 미학 지식은 references로 뺄 수 있지만, 이 목록은 매번 적용되어야 하므로 본문에 있어야 한다.

**반론**: "브리프가 `100vh`를 원하면?"
**답**: `100dvh`가 같은 결과를 더 정확하게 낸다. 이건 취향 대립이 아니라 구식 API 대 신식 API다. 다른 항목들도 마찬가지다. 브리프가 "포커스 링 없애줘"라고 하면 그건 접근성 후퇴이므로 거절하고 대안(더 절제된 포커스 스타일)을 제시한다.

---

## 부록 A. 원칙 간 상호작용

| 원칙 | 지원하는 원칙 | 긴장 관계 |
|---|---|---|
| 1. references 분리 | 2(앞부분 배치), 5(게이트 분리) | 10(협상불가 목록은 본문에) |
| 2. 최상단 핵심 규칙 | 1, 4, 10 | - |
| 3. description 3부 | - | - |
| 4. 조건부 규칙 | 8(트리트먼트), 9(대담함) | 5(하드 게이트), 10(협상불가) |
| 5. 검증 가능 게이트 | 10 | 4 |
| 6. design.md + 로그 | 7(선언), 9(시그니처) | - |
| 7. 명시적 선언 | 6, 8, 9 | - |
| 8. 트리트먼트 보정 | 4, 9 | - |
| 9. 대담함 한 곳 | 7, 8 | - |
| 10. 실무 규칙 분리 | 2, 5 | 4 |

**4 vs 5·10의 긴장이 핵심이다.** 해소 방식: **규칙을 세 등급으로 명시적으로 나눈다.**
- **협상 불가** (원칙 10) — 접근성·성능·반응형·정직성·토큰. 오버라이드 없음
- **하드 게이트** (원칙 5) — 검증 가능한 슬롭 탐지. 오버라이드 없음, 단 검증 가능한 항목에만
- **조건부 미학** (원칙 4) — 나머지 전부. 브리프가 이긴다, 설명 의무 있음

스킬 본문에서 이 세 등급을 **시각적으로 구분**해야 한다. 같은 목록에 섞으면 등급이 무너진다.

---

## 부록 B. 명시적으로 채택하지 않는 것

| 항목 | 어디서 왔나 | 채택 안 하는 이유 |
|---|---|---|
| 가짜 Python RNG 시뮬레이션 | gpt-taste §1 | 난수가 생성되지 않는다. 같은 프롬프트 → 같은 결과. 원칙 7(명시적 선언)이 같은 효과를 정직하게 낸다 |
| "이전 프로젝트와 다른 세리프/팔레트" (파일 없이) | design-taste-frontend §4.1, §4.2, §14 | 상태 없이 실행 불가. 원칙 6(로그 파일)로 대체 |
| 다이얼 9축 | image-to-code §1 | 인지 부하 대비 효과 없음. 3축 유지 |
| Pre-Flight 체크박스 60개 | design-taste-frontend §14 | 정직한 검사가 불가능한 분량. 본문 12개 + references로 분리 |
| 슬롭 게이트 58개를 본문에 | Hallmark | 같은 이유. 본문 12개, 나머지는 `references/slop-gates.md` |
| 단일 미학 강제 | minimalist-ui, industrial-brutalist-ui, high-end-visual-design | designpaca는 여러 방향을 다뤄야 한다. 이들은 `assets/themes/` 아래 개별 테마 파일로 흡수 |
| `trigger:` 프론트매터 필드 | graphify | 스펙에 없다. claude.ai 업로드/패키징 하드 에러. Windsurf의 `trigger`와 의미도 다르다 |
| 존재하지 않는 파일 경로 지시 | design-taste-frontend §12 (blocks/) | 모델을 혼란시킨다. 만들 거면 만들고, 아니면 언급하지 않는다 |
| 특정 프레임워크 고정 (React/Next 전제) | design-taste-frontend §3.A, gpt-taste §5 | Vue, Svelte, Astro, 바닐라 HTML에서도 돌아야 한다. 스택은 사전 스캔(원칙 6 Step 0)에서 감지한다 |
| GSAP 강제 | gpt-taste §5, design-taste-frontend §5.A/5.B | 스택 의존. 모션 규칙은 라이브러리 불가지론으로 쓴다 |
| 형용사 나열형 페르소나 ("elite", "$150k agency") | high-end-visual-design, gpt-taste | 정보를 주지 않고, "화려하게 하라"로 오독된다. 원칙 8·9와 충돌 |
| 이미지 생성 도구 전제 워크플로 | image-to-code, imagegen-* | 환경 의존. 도구가 있으면 쓰고 없으면 정직한 플레이스홀더(원칙 10)로 분기한다 |

---

## 부록 C. 다음 단계 (설계 → 구현)

1. **description 초안 3~5개를 쓰고 트리거 평가를 돌린다.** skill-creator의 절차대로: should-trigger 8~10개, should-not-trigger 8~10개. 네거티브는 "genuinely tricky"해야 한다 (같은 키워드를 공유하지만 다른 걸 필요로 하는 near-miss).
2. **SKILL.md 본문 400~480줄 초안.** 순서: READ FIRST 5규칙 → 페르소나 3줄 → 트리트먼트 보정 → Step 0 사전 스캔 → Step 1 브리프 읽기 → Step 2 선언 → Step 3 참조 로드 인덱스 → Step 4 빌드 → Step 5 게이트 → Step 6 로그/design.md → 협상 불가 규칙.
3. **references 11개 작성.** 각각 100줄 넘으면 목차 포함. anti-patterns.md는 `무엇/왜 실패/대신` 3단 구조를 지킨다.
4. **테마 파일 작성.** minimalist-ui, industrial-brutalist-ui, high-end-visual-design의 내용을 `assets/themes/*.md`로 이식. 인덱스-후-선택 로딩.
5. **평가.** 최소 3개 시나리오 (새 랜딩 / 기존 페이지 리디자인 / 유틸리티 페이지). 스킬 없는 베이스라인과 비교.
6. **크로스툴 검증.** `skills-ref validate`, Claude Code `/doctor`, Cursor에서 발동 확인, Codex에서 발동 확인.
7. **레거시 어댑터 생성 스크립트.** SKILL.md → `.mdc` / Windsurf 규칙 / AGENTS.md 포인터. 03-format-specs.md §8.4의 주의점을 스크립트에 반영.