101 lines
7.7 KiB
YAML
101 lines
7.7 KiB
YAML
# design-brief-spec — 디자인·비주얼 산출물의 "제약층" 계약 (DESIGN.md 패턴 내재화)
|
|
#
|
|
# 왜 존재하나 (근거 E3, 웹조사):
|
|
# 디자인 직무의 working-method는 프레임워크·프로세스 '서술'이다(무엇처럼 보이나).
|
|
# LLM은 이 추론층이 비어 있으면 '그럴듯하지만 generic한 값'으로 채운다(fabricates the reasoning layer).
|
|
# → 평균적·일반적 산출. 전문가는 값이 아니라 *제약(constraint)·판단로직·구체 레퍼런스*를 준다.
|
|
# "잘 고른 8개 규칙이 토큰 2배보다 나쁜 산출을 더 막는다."
|
|
# source: https://processtopixels.substack.com/p/writing-a-designmd-file-claude-can
|
|
# https://github.com/VoltAgent/awesome-design-md
|
|
# https://www.nngroup.com/articles/vague-prototyping/
|
|
# https://stensyl.ai/blog/reference-images-ai-style-consistency
|
|
#
|
|
# 어디에 쓰나: FAM-DESIGN(DES-PROD/PLATFORM/INTERNAL)·DOC-VISUAL 엔게이지먼트의 필수 입력.
|
|
# context-package-spec.yaml schema.design-brief가 이 파일을 ref로 가리킨다.
|
|
# worker는 design-brief 없이 시작 금지(= "context-package 없이 시작 금지"의 디자인판).
|
|
|
|
design-brief-spec:
|
|
version: 1
|
|
|
|
# 앵커 순서는 강제다 — brief가 항상 먼저(토큰·미학보다 문제·독자·목표가 앞).
|
|
required-anchors: [brief, references, tokens, decisions, donts]
|
|
|
|
schema:
|
|
# P2 S1 — brief-phase 분리: direction 승인 전/후 구분
|
|
brief-phase: # pre-direction | system-ready
|
|
approved-direction-ref: # system-ready 필수 — 승인 방향 불변 report 경로
|
|
approved-direction-sha256: # system-ready 필수 — staleness 대조
|
|
|
|
# ⓪ (선택·additive) DISCOVERY — 기존 프로젝트/시스템 조사 결과.
|
|
# design-system 파이프라인(/design-system)이 스택을 못박기 전에 채운다.
|
|
# 그린필드면 생략 가능(required-anchors 아님 → backward compatible).
|
|
# 기존 시스템이 있으면 이 블록이 reuse/adapt/create 판단의 근거가 된다.
|
|
existing-system:
|
|
stack: # 기존 프레임워크/번들러/언어/CSS 방식 (없으면 greenfield)
|
|
design-system: # 기존 디자인시스템/컴포넌트 라이브러리/테마 (경로·이름)
|
|
tokens-source: # 기존 토큰 SoT 위치 (있으면 재사용 대상 — 새로 만들지 말 것)
|
|
components: # 재사용 가능한 기존 컴포넌트 인벤토리
|
|
brand: # 기존 브랜드 색·타이포·로고 제약
|
|
data-density: # 데이터 밀도(dashboard/table-heavy vs marketing/low) — 토큰·레이아웃에 직결
|
|
# 스택/시스템 판단 — 조사 후 무엇을 할지. 스택은 고정값이 아니라 preset(선택)다.
|
|
stack-decision:
|
|
choice: # reuse | adapt | create (기존 시스템 있으면 create보다 reuse/adapt 우선)
|
|
preset: # create일 때만: greenfield-react | <해당 스택 관례>
|
|
rationale: # 왜 이 판단인지 (기존 시스템 적합성 근거)
|
|
|
|
# ① 제품/산출물 브리프 — 필수·최상단. 미학 이전에 문제·독자·목표를 언어화.
|
|
brief:
|
|
what: 무엇을 만드나 (한 문장)
|
|
who: 누가 쓰나 (독자·사용 맥락)
|
|
must-accomplish: 이 산출물이 반드시 달성해야 하는 것 (성공 조건)
|
|
|
|
# ② 레퍼런스 — 형용사가 아니라 구체 신호. 독창성은 여기서 나온다.
|
|
# 규칙: 3–6개 집중(20개 산만보다 6개 집중이 낫다). 각 레퍼런스는 '나르는 신호'를 명명.
|
|
# 금지: "modern/clean/minimal/sleek" 같은 인터넷-평균 형용사(= generic 유발).
|
|
references:
|
|
- name: # 구체 대상(예: "Linear", "Stripe docs", "C4 container 다이어그램")
|
|
signal: # 그것이 나르는 *구체* 신호(예: "13px base·4px grid·단일 accent color")
|
|
why-relevant: # 이 산출물에 왜 이 신호를 빌리나
|
|
references-rules:
|
|
- 3–6개로 제한. 스타일이 잡히면 더 넣어도 drift만 는다.
|
|
- 형용사가 아니라 신호(텍스처·밀도·간격·색 규율·표기)를 명명한다.
|
|
- 하나의 순수 레퍼런스가 열 개의 모호한 무드보드보다 낫다(모델은 혼합 신호를 평균낸다).
|
|
|
|
# ③ 토큰 — 값+의도+경계. 경계(Don't)가 빠지면 일관성이 무너진다.
|
|
# UI: 색·타이포·간격. 다이어그램: notation 토큰(shape=무엇, arrow=무엇, color=예약).
|
|
tokens:
|
|
- name: # 예: primary / body-scale / gap / node-shape / edge-color
|
|
value: # 예: #1B4DFF / 13px·1.5 / 8px grid / rounded-rect / gray
|
|
intent: # 언제·왜 쓰나 (예: "CTA·active state 표시")
|
|
boundary: # 절대 하지 않는 것 (예: "배경/장식 금지, 화면당 1회")
|
|
|
|
# ④ 판단로직 — 언제 A vs B. 컴포넌트/다이어그램 분할의 결정 규칙.
|
|
decisions:
|
|
- question: # 예: "card vs list row?" / "한 그림 vs 분할?"
|
|
rule: # 결정 규칙 (예: "3필드 초과·독립 액션 있으면 card, 아니면 list")
|
|
|
|
# ⑤ Don'ts — 명시적 anti-pattern 8±. 가드레일이 토큰보다 나쁜 산출을 더 막는다.
|
|
donts:
|
|
- 'gradient 금지 · status color는 의미 전용(장식 금지) · one diagram one message 위반 금지 (예시)'
|
|
|
|
# 다이어그램 전용 확장 (DOC-VISUAL) — diagram-craft skill과 짝.
|
|
diagram-extension:
|
|
abstraction-first: 도구보다 추상화 계층(C4 레벨)·독자·전달 메시지를 먼저 정한다.
|
|
c4-level: L1 System Context / L2 Container(가장 범용) / L3 Component(복잡할 때만) / L4 Code(자동생성)
|
|
engine-priority:
|
|
- d2: 소프트웨어 아키텍처·의존성·중첩 컨테이너 (1급, 레이아웃엔진 dagre/elk·테마·CI 친화)
|
|
- excalidraw: 설명·손그림·워크숍 발산 (.excalidraw, roughness·auto-layout)
|
|
- mermaid: 최후 폴백만 (경량·플랫폼 네이티브지만 실무급 아님)
|
|
notation-discipline: 그림마다 스코프 한 줄 제목 + 범례 + 일관된 방향 + 예약색. 한 그림에 한 메시지.
|
|
exhibit-schema-in-renderer: "{type: d2, code, layout?: dagre|elk, theme?: int, sketch?: bool, pad?: int}"
|
|
|
|
rules:
|
|
- 'discovery-first(design-system 엔게이지먼트): existing-system을 조사해 stack-decision(reuse/adapt/create)을 정한 뒤 스택을 고른다. 기존 시스템이 있으면 스택 강제(create) 금지 — reuse/adapt 우선. existing-system/stack-decision은 additive(그린필드면 생략 가능, required-anchors 아님).'
|
|
- brief가 references·tokens보다 항상 먼저다(문제·독자·목표 우선).
|
|
- references는 형용사가 아니라 구체 신호로 3–6개. generic 형용사 금지.
|
|
- 모든 token은 value뿐 아니라 intent+boundary를 갖는다(경계 없는 토큰 금지).
|
|
- donts는 최소 5개 이상 명시(빈 가드레일 금지 — 침묵을 모델이 generic으로 채운다).
|
|
- 다이어그램은 abstraction-first(레벨·독자·메시지) → 엔진(D2 우선) 순. Mermaid는 폴백.
|
|
- design-brief는 completion-record가 아니다(불변 아님, 엔게이지먼트 입력 아티팩트). 산출물 보고서는 별도 .report.yaml.
|
|
- 'design-system-brief 는 brief-phase=system-ready 이며 approved-direction-ref/sha256 를 인용한다(P2). reference-cluster·색·typography·token 은 승인 방향에서 확정하고 발명하지 않는다. pre-direction(direction-input-brief)에는 확정 시각 항목 금지(발산 전 고착 방지).'
|