# 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)에는 확정 시각 항목 금지(발산 전 고착 방지).'