pattern_id: cards-3col-persona
category: cards
version: 0.1.0  # staging draft
provenance:
  source_frame: "45:16 / Frame 1171281191"
  reference_html: ../block-tests/bim-3roles-cards.html
  reference_render: ../block-tests/_renders/bim-3roles-cards_v8.png

description: |
  N개의 평행한 stakeholder/관점/카테고리 카드. 각 카드는 상단 원형 뱃지(역할 라벨),
  배경 이미지+컬러 오버레이, 본문 bullet 리스트(custom marker), 그리고 optional 하단 사진을 포함.
  R13 (Custom-Marker Bullet List) sub-pattern을 카드 본문에 사용.

# AI 블록 선택기가 매칭에 사용하는 조건
when:
  relation_type:
    - parallel-stakeholders   # 발주자/시공자/설계자 같이 여러 주체의 관점
    - multi-perspective       # 같은 주제를 여러 시각으로
    - role-comparison         # 역할별 책임/목표/특징 나열
    - parallel-categories     # N개 카테고리의 병렬 항목 나열
  content_shape:
    columns_count: { min: 2, max: 4 }
    items_per_column: { min: 1, max: 12 }

not_for:
  - linear_process            # 순차적 단계
  - single_main_message       # 단일 핵심 메시지
  - hierarchical_tree         # 트리/계층

# 슬롯 정의
slots:
  marker_icon:
    type: image
    required: true
    description: bullet 마커 (체크박스/점/화살표/PNG 등). 모든 컬럼 공통.

  columns:
    type: list
    required: true
    min: 2
    max: 4
    item:
      role_label:
        type: tuple
        items: [string, string]    # ["발주자", "목표"] — 2 line label
        required: true

      role_color:
        type: color                # CSS color (hex, rgb, hsl)
        required: true
        description: 뱃지 라벨 색 + (옵션) overlay tint

      bg_image:
        type: image
        required: true
        description: 카드 배경 사진/일러스트

      overlay_image:
        type: image
        required: false            # 없으면 단색 BG만
        description: 배경 위 컬러 오버레이 (보통 80% opacity)

      badge:
        type: object
        required: true
        properties:
          outer_image: { type: image, required: true }
          inner_image: { type: image, required: true }

      bullet_items:
        type: list
        required: true
        min: 1
        max: 12
        item:
          text:
            type: string
            required: true
            max_chars: 25            # zone width 기준 가이드
          compact:
            type: boolean
            default: false
            description: 2줄 들어가는 긴 항목인 경우 true. 텍스트 길이로 자동 결정 가능.

      bottom_photo:
        type: image
        required: false            # ★ 사진 없는 mdx도 매칭 가능
        description: 카드 하단 보조 사진. 없으면 bullet-list가 더 많은 공간 사용.

# 디자인 토큰 (외부 override 가능)
tokens:
  block_w:           { default: 1280, unit: px }
  block_h:           { default: 948,  unit: px }
  font_body_size:    { default: "0.95rem" }
  font_body_lh:      { default: 2.125 }     # 단일 line item line-height ratio
  font_body_lh_compact: { default: 1.25 }   # 2-line item line-height ratio
  col_gap:           { default: "0.3%" }
  card_padding_top:  { default: "4.3%" }
  marker_w:          { default: "1.25rem" }
  marker_h:          { default: "1.25rem" }
  marker_gap:        { default: "0.45rem" }

# zone 적합성
min_size_px:
  width: 720
  height: 540
max_size_px:
  width: 2600
  height: 2000

# 적용 sub-pattern
sub_patterns:
  - id: bullet-list-with-marker
    rule: R13
    location: card-body > .bullet-list

# 우선순위 (다른 블록과 경합 시)
priority: 50

# 1:1 reference 와의 차이 (intentional)
diff_from_reference:
  - "Figma 절대 좌표 → flex layout (반응형)"
  - "Figma 픽셀 fixed values → CSS 변수 + % 비율"
  - "letter-spacing 보정 제거 → 자연 wrap"
  - "explicit <br> 제거 → 자연 wrap (텍스트 길이로 결정)"
  - "compact class 수동 → 텍스트 길이로 자동 (또는 외부 입력)"
  - "사진 absolute → flex item, optional"