브랜드 시스템은(는) 무엇을 하나요?
웹 제품 리포지토리의 루트에 위치하는 브랜드 북과 디자인 시스템을 스캐폴딩합니다 — 장문의 BRAND.md(작업 참조 문서, 20개 섹션)와 짝을 이루는 BRAND.html(이해 관계자용 인쇄 가능한 요약, 약 A4 7페이지 분량, Chrome 헤드리스로 BRAND.pdf로 렌더링), 그리고 Tailwind v4 @theme용 tokens.css도 함께 생성합니다.
이 스킬은 문서를 저작합니다. 자매 스킬인 brand-assets은 픽셀을 생성합니다(SVG 파비콘, PWA 팩, apple-touch-icon). 완전한 브랜드 롤아웃을 위해 두 스킬을 순서대로 호출하세요.
다섯 가지 산출물
| 산출물 | 설명 | 방법 |
|---|---|---|
BRAND.md | 20개 섹션의 장문 작업 참조 문서 | templates/BRAND.md.tmpl via scripts/new-brand-book.sh |
BRAND.html | A4 7페이지 인쇄 가능 요약 | templates/BRAND.html.tmpl via 동일 스크립트 |
BRAND.pdf | Chrome 헤드리스로 렌더링 | scripts/render-pdf.sh |
tokens.css | Tailwind v4 @theme + :root + [data-theme="dark"] | templates/tokens.css.tmpl + scripts/extract-tokens.py |
tokens.json | W3C DTCG 형식 (Style Dictionary / Tokens Studio용) | scripts/extract-tokens.py --format dtcg |
워크플로우 (의사 결정 트리)
-
처음부터 시작? — 먼저 시그니처 무브 인터뷰를 실행하세요: templates/signature-interview.md.tmpl을 리포지토리에 복사하고 스캐폴딩 전에 모든 질문에 답하세요. 각 질문이 중요한 이유는 reference/signature-moves.md를 참조하세요. 이 과정 없이 출력은 템플릿에 불과합니다; 이 과정을 거치면 비로소 브랜드가 됩니다.
-
새 브랜드 북을 스캐폴딩? — scripts/new-brand-book.sh를 인터뷰 답변을 플래그로 전달하여 실행하세요. 출력 디렉토리에
BRAND.md,BRAND.html,tokens.css,signature-interview.md가 생성됩니다. -
특정 장(chapter) 초안 작성? — 해당 참조 문서를 불러오세요:
- §0 아이디어 / §2 프리미티브 / §3 시그니처 무브 → reference/signature-moves.md
- §5 로고 + 파비콘 팩 → reference/favicon-pack.md
- §6 색상 → reference/color.md + reference/tokens.md
- §7 타이포그래피 → reference/typography.md
- §10 표면 및 소재 → reference/surfaces.md
- §11 모션 → reference/motion.md
- §13 보이스 & 톤 → reference/voice-and-tone.md
- §14 접근성 → reference/accessibility.md
- §17 Tailwind v4
@theme→ reference/tailwind-v4.md - 히브리어 / 아랍어 / RTL → reference/rtl.md
-
파비콘 + PWA 팩? — 이 스킬에서는 자산을 생성하지 마세요. reference/favicon-pack.md가 요구사항(시스템 인식 SVG 파비콘, 불투명 apple-touch-icon, maskable PWA, OG 라이트+다크 쌍)을 명세합니다. 명세와 소스 SVG를 brand-assets 스킬의
icon-pack.sh에 전달하세요. -
출시 전 명암 대비 감사 → scripts/audit-contrast.py. 본문에 대해 WCAG 2.2 AA (4.5:1), 대형 텍스트/UI/포커스 링에 대해 3:1. 테마별(라이트 + 다크)로 실행됩니다. 결과 매트릭스를 §14에 붙여넣으세요.
-
PDF 렌더링 → scripts/render-pdf.sh. Chrome 헤드리스 사용.
BRAND.html로부터BRAND.pdf를 생성합니다. -
기존 브랜드 북 감사 → scripts/audit-outline.py. 20개 섹션 개요를 검증하고, 누락된 결정 로그 항목에 플래그를 지정하며, §2 시그니처 프리미티브에 8개 미만의 사용처가 문서화된 경우 경고합니다.
-
BRAND.md와 프로덕션 CSS 간의 드리프트 탐지 → scripts/check-consistency.py. 브랜드 북은 코드가 조용히 문서와 달라질 때 실패합니다. BRAND.md의 색상 토큰을 하나 이상의 대상 CSS 파일과 비교하고 16진수 드리프트가 있으면 0이 아닌 값으로 종료합니다. CI에 연결하세요.
-
스캐폴딩 전 인터뷰 강제 →
--require-interview path/to/signature-interview.md를 scripts/new-brand-book.sh에 전달하세요. 인터뷰에 아직 채워지지 않은{{PLACEHOLDER}},{{TODO}}또는> …답변 행이 있으면 스캐폴딩을 거부합니다. 강력 권장됩니다.
규칙
-
스캐폴딩 전에 안티-템플릿 무브를 요구하세요. 인터뷰는 선택 사항이 아닙니다. 하나의 발명된 고유 명사, 세 가지 반증 가능한 원칙, 과거 실수에서 얻은 세 가지 실제 금지사항, 브랜드의 목소리로 작성된 150단어 음성 샘플, 그리고 모범 사례를 의도적으로 깨는 하나의 시그니처 무브가 필요합니다. 이것들이 없으면 브랜드 북은 템플릿에 불과합니다. reference/signature-moves.md 참조.
-
액센트는 라이트/다크에서 일정하게 유지하세요. 표면과 텍스트 의미론적 토큰만 테마 간에 교체됩니다. 유일하게 채도가 높은 브랜드 색상은 두 모드에서 동일합니다 — 이것이 시스템 환경설정에 관계없이 시그니처 프리미티브가 같은 의미를 가지게 하는 핵심입니다. templates/tokens.css.tmpl에 인코딩되어 있습니다.
-
Nathan Curtis 분류법에 따른 3계층 토큰. 프리미티브 (
--color-cream: #F3EAD3) → 의미론적 (--bg: var(--color-cream)) → 컴포넌트 (--btn-bg: var(--bg-elevated)). 프리미티브는@theme에, 의미론적 토큰은:root에, 다크 모드 오버라이드는[data-theme="dark"]에 들어갑니다. reference/tokens.md 참조. -
WCAG 2.2 AA는 2026년의 법적 최소 기준입니다. APCA가 아닙니다 — APCA는 2023년 7월 WCAG 3에서 제외되었고 아직 복귀하지 않았습니다. AA는 본문 4.5:1, 대형/UI/포커스 3:1, 24×24 대상 크기 최소값을 의미합니다. scripts/audit-contrast.py로 감사; reference/accessibility.md 참조.
-
RTL은 부록이 아닌 기초입니다. 제품이 히브리어나 아랍어로 제공된다면, CSS 논리 속성(
margin-left대신margin-inline-start)을 첫날부터 사용하세요; 사후에 수정하는 비용은 처음부터 설계하는 것보다 10~50배 비쌉니다. reference/rtl.md 참조. -
브랜드 북은 그 자체가 브랜드의 인스턴스여야 합니다.
BRAND.html템플릿은 제품 자체의 팔레트와 서체를 사용합니다 — 따라서 문서는 1페이지부터 브랜드처럼 보입니다. 브랜드 북의 자체 스타일링이 설파하는 규칙을 통과하지 못한다면 잘못된 것입니다. -
다크 모드는 시스템-우선, 토글-차선. 기본적으로
prefers-color-scheme를 존중하고, 명시적인 사용자 오버라이드는localStorage에 유지합니다. 내비게이션에 눈에 띄는 다크 모드 토글을 넣는 것은 안티패턴입니다. reference/favicon-pack.md의 시스템 인식 SVG 파비콘 규칙도 같은 논리를 따릅니다.
비목표(Non-goals)
- 로고 아트워크 생성 — 이는 image-generation의 몫입니다.
- 기계적 자산 파이프라인(PNG → SVG 벡터화, 아이콘 팩 생성, 크기별 래스터화) — 이는 brand-assets의 몫입니다.
- 실제 컴포넌트 구축 —
BRAND.md의 §18이 명세를 문서화합니다; react-components와 frontend-design이 구현합니다. - 브랜드 스토리텔링 / 마케팅 카피라이팅 — §13은 어떻게 쓸지를 규정할 뿐, 무엇을 쓸지는 다루지 않습니다.
- 카피 번역 — 이 스킬은 RTL 인식 구조를 스캐폴딩하지만 번역하지는 않습니다.
- 브랜드 북을 제품처럼 버전 관리 — 제자리에서 업데이트하고, 명확한 메시지와 함께 커밋하며, 리포지토리 루트에 하나의 진실 공급원(source of truth)을 유지합니다.
표준 20개 섹션 개요 (BRAND.md.tmpl이 생성하는 내용)
| # | 섹션 | 핵심 필수 요소 |
|---|---|---|
| 0 | 아이디어 | 한 문장 핵심 아이디어 + "X를 제외한 모든 것을 벗겨내라" 테스트 |
| 1 | 마크 읽기(Reading the mark) | 로고의 3~5가지 동시적 해석 |
| 2 | 시그니처 프리미티브 | 모든 표면에 나타나는 의미론적 토큰 — 8개 이상의 사용처 |
| 3 | 시그니처 무브 | 로고 없이 브랜드를 식별하는 5~7가지 요소 |
| 4 | 브랜드 본질 | 우리의 정체성/아닌 것/톤/포지셔닝 문장 |
| 5 | 로고 시스템 | 변형, 여백 공간, 최소 크기, 금지사항, 파비콘 + PWA 팩 요구사항 |
| 6 | 색상 시스템 | 코어 + 확장 + 중성 + 의미론적 토큰, 62/30/8 비율, 라이트/다크 일관성 |
| 7 | 타이포그래피 | 서체, 표 형식 숫자, 척도, 줄 길이(measure), RTL 처리, 워드마크 처리 |
| 8 | 아이콘그래피 | 스타일, 색상 규칙(액센트 절대 사용 금지), 크기 토큰, RTL 뒤집기 |
| 9 | 간격 및 레이아웃 | 8포인트 그리드, 컨테이너, 둥근 모서리 + 동심원 반지름 규칙 |
| 10 | 표면 및 소재 | 기본 + 떠있는(floating) 소재, 그레인 오버레이, 히어로 배경 |
| 11 | 모션 | 원칙, 토큰, 시그니처 애니메이션, reduced-motion 동작 |
| 12 | 이미지 및 일러스트레이션 | 사진 규칙, 일러스트레이션 스타일, 안티패턴 |
| 13 | 보이스 & 톤 | 규칙, 감정 상태별 톤 매트릭스, 같은 생각의 3단계 확장, RTL 특이사항 |
| 14 | 접근성 | WCAG 2.2 AA 명암 대비 매트릭스, 포커스 링, reduced motion, RTL 동등성 |
| 15 | 참조 집합 | 브랜드가 위치한 선반과 그렇지 않은 것 |
| 16 | 안티패턴 | 구체적인 "하지 말아야 할 것" 목록 — 금지된 구체적인 나쁜 습관 |
| 17 | 구현 — Tailwind v4 @theme | 전체 블록, :root + [data-theme="dark"], body 규칙 |
| 18 | 컴포넌트 | 버튼, 링크, 입력, 카드, 배지, 내비게이션, 알림, 대화상자, 산문(prose), 랜딩 프리미티브 |
| 19 | 마이그레이션 계획 | 폐기되는 항목; 토큰/패턴별 ✅/⚠️/❌; 날짜 |
| 20 | 이것이 아닌 것 + 결정 로그 | 비목표 + 근거가 포함된 결정의 날짜별 표 |
빠른 실행
# 리포지토리 루트에 새 브랜드 북 스캐폴딩
~/.claude/skills/brand-system/scripts/new-brand-book.sh \
--product "Agentiko" \
--positioning "WhatsApp 안에서 사는 진짜 노동자." \
--palette-bg '#F3EAD3' \
--palette-fg '#0E1320' \
--palette-accent '#B85A3A' \
--signature-primitive "음성 점" \
--primary-font "Rubik" \
--locale "ko" \
--output-dir .
# 명암 대비 감사
~/.claude/skills/brand-system/scripts/audit-contrast.py \
--bg '#F3EAD3' --fg '#0E1320' --accent '#B85A3A'
# 인쇄용 PDF 렌더링
~/.claude/skills/brand-system/scripts/render-pdf.sh BRAND.html BRAND.pdf
# 나중에: 기존 브랜드 북을 개요와 대조하여 확인
~/.claude/skills/brand-system/scripts/audit-outline.py BRAND.md
관련 스킬
- brand-assets — 기계적 SVG/PNG 파이프라인; 이 스킬 실행 후 실행하여 파비콘 팩을 생성하세요.
- image-generation — 이 스킬을 실행하기 전에 로고/히어로 이미지를 디자인하세요.
- frontend-design — §18 컴포넌트를 프로덕션 코드로 구현하세요.
- react-components — §18이 작성된 후 컴포넌트 프리미티브를 구축하세요.