💄 [Design] 명함 미확정 시안 확정 — 빈 상태·삭제 동선·이름 표기·파트 컬러 (#1236)

[JEONG-J]

🔗 관련 이슈

Closes #1236

✨ PR 유형

• 디자인 확정 및 UI 반영 ([Design])
• 버그 수정 (미정의 파트가 Admin 색으로 표시되던 문제)
• 접근성 개선 (명함_s 칩 WCAG AA 미달 해소 — 🎨 Design: 명함 화면 접근성 — VoiceOver 라벨 부재 · 파트 칩 대비 미검증 #1235 후속)
• 문서 (기획 레포 설계 문서 추가)

시안이 확정되지 않아 「디자이너 확인 대기」 주석으로 버티고 있던 명함 기능의 네 자리를 확정하고,
확정값을 코드·주석·테스트에 반영했습니다. 확정 근거 전문은 기획 레포 설계 문서에 있습니다.

• 설계 문서: specs/명함_미확정 시안 확정_설계.md

📷 스크린샷 or 영상(UI 변경 시)

시뮬레이터 캡처는 미첨부입니다. 변경이 화면 단위 신규 UI가 아니라 기존 화면의 확정값 반영이라,
아래 표로 변경 전/후를 대신합니다. 리뷰 시 확인 포인트는 §📌 리뷰 포인트에 정리했습니다.

지점	변경 전	변경 후
명함첩 빈 상태	제목·설명·심벌만, 다음 동선 없음	「명함 교환하기」 CTA(.glassProminent) 추가
명함_s 파트/기수 칩	시드@0.8 배경 + 흰 라벨 (라이트 8종 전부 AA 미달)	불투명 혼합 배경 + 검정 라벨 (라이트·다크 8종 5.92~14.92 통과)
미정의 파트 명함	Admin 인디고(#6155F5)로 표시	무채색 grey400 폴백
삭제 다이얼로그	「…지웁니다.」	「…지워요.」

🛠️ 작업내용

1. 빈 상태 — CTA 확정 (시안 12639:33678)

• ReceivedCardsView 의 「명함 0장」 분기를 ContentUnavailableView 3-클로저 형태로 바꾸고
  NavigationLink(value: .exchange) + .buttonStyle(.glassProminent) CTA 1개를 추가했습니다.
• 문구·심벌은 현행 확정입니다. QR 스캔은 툴바에 상존하므로 본문 CTA 는 교환 하나만 둡니다
  — 같은 목적지를 화면에 두 번 두지 않습니다.
• 검색 0건 분기는 건드리지 않았습니다. ContentUnavailableView.search(text:) 가 문구·현지화·
  다크 모드를 보증하고, 검색어를 지우면 곧장 복귀하는 상태라 CTA 가 필요 없습니다.

2. 삭제 동선 — 상세 단독 확정

• 코드 변경 없음. ReceivedCardDetailView 문서 주석에 상세 화면 단독이 확정 사양임을 못 박았습니다.
  (LazyVGrid 라 스와이프 삭제가 구조상 불가하고, 컨텍스트 메뉴는 ✨ Feature: 받은 명함 상세 화면 · 교환 맥락(exchangeContext) 실제 기록 #1227 에서 제거된 상태를 유지합니다.)
• 다이얼로그 메시지의 「지웁니다」 → 「지워요」 1어절만 수정했습니다. 앱 전반이 해요체라 이 문장만
  합쇼체로 어긋나 있었습니다. 제목·버튼 라벨은 현행 확정입니다.

3. 이름 표기 규칙 확정 (시안 12657:35806)

• 명함_l·_m·_s 세 컴포넌트에 같은 로직이 세 벌 복제돼 있던 displayName 을 지우고,
  Domain 의 MyCard.nameWithNickname 하나로 모았습니다. 표기가 바뀌면 이제 한 곳만 고칩니다.
• 명함_l(BusinessCardFaceView)·명함_m(BusinessCardSummaryView) 의 이름 Text 에
  .layoutPriority(1) 을 줬습니다. 이름과 학교가 둘 다 lineLimit(1) 이라 폭이 모자랄 때
  어느 쪽이 잘릴지 규칙이 없었는데, 이름이 1차 식별자이므로 학교가 먼저 말줄임되도록 고정했습니다.
  (명함_s 는 두 값이 VStack 으로 줄이 나뉘어 있어 경합이 없습니다 — 변경하지 않았습니다.)
• minimumScaleFactor 는 넣지 않았습니다. Dynamic Type 설정을 되돌리는 축소는 접근성 역행입니다.

4. 파트 컬러 확정

• 시드 8종 현행 유지 확정. 시안에 없는 iOS 파트만 #FF9500 으로 채운 상태를 확정값으로 굳히고,
  「디자이너 확인」 주석을 확정 주석으로 승격했습니다. color(시스템 컬러, Activity·Notice 사용)는
  건드리지 않았습니다.
• 미정의 파트 폴백 추가 (버그 수정). MyCard.partRaw != nil 이면 part 가 관례상 .admin 으로
  떨어져, 모르는 파트의 명함이 Admin 인디고를 입고 운영진처럼 보이던 문제가 있었습니다.
  UMCPartType.unresolvedSeedColor(grey400)를 추가해 무채색으로 되돌립니다.
• 칩 대비 해소 (🎨 Design: 명함 화면 접근성 — VoiceOver 라벨 부재 · 파트 칩 대비 미검증 #1235). 칩 배경을 알파 합성에서 모드 불변 불투명 혼합색
  (seed.mix(with: .white, by: 0.2, in: .device))으로 바꾸고 라벨을 Color.black 으로 고정했습니다.
  라벨 색만 바꾸는 안은 다크에서 다시 깨집니다 — 검정 라벨은 Admin 2.95·PM 3.47·Design 3.90·Web 4.08 이,
  흰 라벨은 Spring 3.42·Android 3.32·iOS 3.38·Node 2.39 가 미달이라 어느 한 잉크로도 양 모드를 못 덮습니다.
  면을 미리 섞어 두면 라이트 픽셀은 그대로면서 다크에서도 같은 색이 남아, 검정 라벨 하나로
  라이트·다크 8종이 전부 5.92~14.92 로 통과합니다. 이 값은 UMCPartTypeSeedColorTests 의
  대비 테스트가 고정합니다 — 시드나 혼합비가 바뀌면 테스트가 먼저 깨집니다.

5. 테스트

• MyCardTests — nameWithNickname 표기 규칙을 극단 케이스(빈 닉네임·공백뿐인 닉네임·양끝 공백·
  긴 이름·영문 이름·빈 이름)로 파라미터화해 고정했습니다.
• UMCPartTypeSeedColorTests — ① 칩 면 위 검정 라벨의 WCAG 대비가 8종 전부 4.5:1 을 넘는지,
  ② 폴백이 저채도 회색(채널폭 40 미만)이고 시드 8종은 유채색(채널폭 40 초과)인지 고정했습니다.
  폴백이 시드 근처 색으로 바뀌면 「운영진처럼 보임」 버그가 되살아나므로, hex 완전 일치만으로는
  부족해 채도 축으로 단언합니다.
• 프리뷰(BusinessCardPreviewData)에 partRaw 가 채워진 카드를 추가해, 진짜 운영진(인디고)과
  못 읽은 파트(회색)가 나란히 보이도록 했습니다.

📋 추후 진행 상황

아래 4건은 사람(디자인팀)만 내릴 수 있는 판단이라 이 PR 범위 밖입니다.
각 항목은 확정값으로 동작하는 상태로 두었고, 정정이 오면 고칠 지점을 함께 적었습니다.

1. 빈 상태 커스텀 일러스트 — 시안 12639:33678 에 전용 그래픽이 있는지 확인이 필요합니다.
   원본 에셋 제작은 코드로 대신할 수 없습니다. 그때까지 SF Symbol person.crop.rectangle.stack 이 확정값입니다.
2. iOS 파트 공식 시드 변형 색 — 시안에 iOS 변형이 없어 #FF9500 으로 확정했습니다.
   브랜드 팔레트 결정이라 디자이너 몫이며, 나오면 UMCPartType+Color.swift 의 한 값과 테스트만 교체합니다.
3. 이름/닉네임 더미의 의도 — 병기 표기인지 「이름 또는 닉네임」 자리표시자인지는 시안 원본의
   컴포넌트 속성을 열어야 판별됩니다(12657:35806). 병기로 확정했고, 정정되면 MyCard.nameWithNickname
   한 곳만 고치면 됩니다.
4. 명함_s 다크 모드 칩 톤 — 다크 시안이 없어, 어두운 카드 면 위 밝은 불투명 칩의 톤이 의도와 맞는지
   확인이 필요합니다. 대비(4.5:1)는 이미 보증되므로 미감 판단만 남습니다.

코드 리뷰에서 나온 범위 밖 후속 건 2개도 여기 남깁니다.

5. 님 띄어쓰기 불일치 — 이 PR 이 고친 삭제 다이얼로그는 "\(name) 님의"(띄움), 형제 화면인
   CardLinkReceiveViewModel:128 은 "\(card.name)님의"(붙임)입니다. 의존명사 「님」은 띄우는 쪽이
   어문 규범에 맞으므로 후자를 맞추는 방향이지만, 🎨 Design: 명함 미확정 시안 확정 — 빈 상태·삭제 동선·이름 표기·파트 컬러 #1236 범위(명함첩 삭제 동선) 밖이라 건드리지 않았습니다.
6. BusinessCard3DSpike.accentColor(for:) — .admin 을 회색으로 뭉개 「진짜 운영진」과 「못 읽은 파트」를
   구분하지 않습니다. DEBUG 스파이크 하네스이고 🎨 Design: 3D 명함 베이스 USDZ 템플릿 에셋 · 바인딩 앵커 규약 #1246 에서 매핑표를 확정하기로 돼 있어 그대로 뒀습니다.
   그때 partRaw != nil 분기를 함께 옮겨야 이번 수정이 3D 카드로 이어집니다.

이후 작업: 위 확인이 오면 해당 값만 교체 → #1237(Pretendard Bold 반입 / 토큰 수렴) 진행.

📌 리뷰 포인트

• 칩 배경 치환이 라이트 모드 픽셀을 바꾸지 않는지 — seed.opacity(0.8) 을 흰 카드 면에 합성한 것과
  seed.mix(with: .white, by: 0.2, in: .device) 는 sRGB 채널 보간이라 사실상 같은 색입니다.
  카드 면에 깔린 시드 워시(최대 0.15) 때문에 이론상 채널당 3% 이내 차이가 납니다.
• 잉크가 Color.black 인 이유 — grey900 은 다크에서 흰색으로 뒤집힙니다. 면이 모드 불변이므로
  잉크도 모드 불변이어야 합니다. 여기서 grey900 을 쓰면 다크에서 다시 대비가 깨집니다.
• nameWithNickname 이 Domain 에 있는 게 맞는지 — 표시 문자열이지만 명함_l/_m/_s 세 Presentation
  컴포넌트가 공유하는 규칙이고, 기존 partDisplayName 이 이미 같은 자리에 있어 그 선례를 따랐습니다.
• layoutPriority(1) 을 명함_s 에는 넣지 않은 것 — 명함_s 는 이름과 학교가 VStack 으로 줄이 나뉘어
  있어 폭 경합 자체가 없습니다. 넣으면 효과 없는 코드만 늘어납니다.
• partRaw 폴백이 칩 라벨까지 바꾸지는 않는다는 점 — 색만 회색으로 돌리고 라벨은 기존
  partDisplayName(원본 파트명)을 그대로 씁니다. 틀린 이름(운영진)보다 낯선 이름이 낫다는 기존 규칙 유지입니다.
• 폴백만 다이내믹 토큰이라는 예외 — 시드 8종은 raw hex 라 모드 불변이지만 grey400 은
  light #B2B8BF / dark #7C8792 로 갈립니다. 「칩 면은 모드 불변」이라는 전제의 유일한 예외이고,
  검정 라벨 대비가 라이트 12.22 · 다크 7.82 로 양쪽 다 AA 를 넘어 잉크는 그대로 뒀습니다. 주석에 명시했습니다.
• 빈 상태 복귀 갱신은 이 PR 범위 밖 — CTA 로 교환 화면에 갔다 돌아왔을 때의 목록 갱신은
  ReceivedCardsView 의 .task 가 처리합니다(isIdle 이면 load, 아니면 조용히 refresh).
  이미 출시된 상세 화면 삭제 왕복이 같은 경로를 쓰고 있어 새로 생긴 동선이 아닙니다.

✅ Checklist

PR이 다음 요구 사항을 충족하는지 확인해주세요!!!

• 커밋 메시지 컨벤션에 맞게 작성했습니다
  • 해당 링크 : 깃 모지 컨벤션
• 유지-보수를 위해 주석처리를 잘 작성하였는가?
  • 해당 링크 : Xcode 주석 정리
• AppProduct/ 는 건드리지 않았습니다 (절대 규칙 ✨ Feature: LoadingView 제작 #9)
• cd UMCApp && make test 통과