[Docs/#8] Figma WDS 컴포넌트 매칭 컨벤션 및 /component 스킬 추가

[xeoxxn]

#️⃣연관된 이슈

• Closes Figma WDS 컴포넌트 매칭 컨벤션 및 /component 스킬 추가 #8

🎯 해결하려는 문제가 무엇인가요?

Figma MCP로 Stream 디자인을 코드로 옮길 때마다, 화면에 쓰인 컴포넌트가 원티드 디자인 시스템(WDS)인지 Stream 자체 로컬 컴포넌트인지를 매번 수작업(get_libraries → search_design_system → get_design_context 대조)으로 판별해야 했다. 사람마다 판별·구현 방식이 달라지면 컴포넌트 구조가 제각각이 된다.

❓ 왜 해결해야 하나요?

WDS로 이미 존재하는 컴포넌트를 매번 새로 마크업하면 중복 구현이 생기고, 팀원마다 컴포넌트 파일 구조가 달라져 유지보수가 어려워진다.

⭐ 어떻게 해결했나요?

• docs/conventions/wds-component-usage.md: Stream Figma 파일에서 실제로 쓰이는 WDS 컴포넌트 목록을 이름·componentKey·문서 링크까지 대조해 정리한 참고 문서 (git 추적되는 위치로 이동해 팀원도 볼 수 있게 함)
• docs/conventions/component-convention.md: 컴포넌트 파일 위치(feature 전용 vs 공용), 파일 구조(컴포넌트=파일 하나, Figma variant → Props 유니온 타입), WDS import 규칙, Stream 고유 UI 작성 규칙, 완료 체크리스트
• .claude/skills/component/SKILL.md: /component <figma URL>로 호출하면 WDS 대조 → WDS는 import로 치환, 나머지는 컨벤션대로 새 컴포넌트 작성 → 배치·검증까지 이어지는 워크플로우
• (추가) 실제 화면(공통 레이아웃(375x812) + Bottom Nav 뼈대 구현 #11)으로 /component를 시험 실행하면서 드러난 사례를 wds-component-usage.md/component-convention.md/component/SKILL.md에 반영:
  • 파일 전체에서 확정된 WDS 컴포넌트라도 다른 화면의 인스턴스는 스타일이 다르면 Stream 로컬일 수 있다는 반례(빌릴게 필터 Chip)와, "이름이 같아도 스타일이 다르면 재확인한다"는 규칙 추가
  • Bottom Nav를 WDS 코드 컴포넌트로 썼다가 iOS 반투명 배경·스크롤 감지 로직 문제로 Stream 로컬로 철회한 기록
  • Menu/Resource/Action Area/Trailing Content/Button처럼 이름과 1:1 대응하는 코드 export가 없는 WDS 컴포넌트를, 가장 가까운 공개 컴포넌트(Button)+sx 색상 보정으로 대체한 사례
  • "색상 토큰" 규칙 신설 — hex 하드코딩 대신 get_variable_defs로 확인한 Figma 변수를 index.css의 @theme 토큰으로 등록해 쓰도록 함
• (추가) .claude/skills/figma-check/SKILL.md 신설: /component가 Figma→코드를 만드는 스킬이라면, 이건 반대 방향 — 이미 구현된 코드가 Figma와 1:1로 일치하는지(색상 토큰, WDS 판단 재검증, 박스모델 실측, 컴포넌트 기본값, 스크린샷 비교) 대조해서 리포트하는 검증 전용 스킬. /figma-check <figma URL> [코드 경로]로 호출

🧩 이 PR의 한계 & 트레이드오프

• wds-component-usage.md는 현재 시점 스냅샷이라, Figma 디자인이 바뀌면 다시 대조해야 한다. /component·/figma-check 스킬이 실행될 때마다 새로 확정되는 매핑을 이 문서에 계속 추가하도록 설계했다.
• 실제 화면으로 /component를 시험 실행해보진 않았다 → 이슈 공통 레이아웃(375x812) + Bottom Nav 뼈대 구현 #11(빌릴게 대여 목록 화면, PR [Feat/#11] 공통 레이아웃(375x812) + Bottom Nav 뼈대 구현 #12)에서 실행 완료. 그 과정에서 드러난 교훈을 이 PR에 반영했다.
• figma-check는 아직 실제 화면 하나(빌릴게)에서만 써봤다 — 다른 화면에도 일반적으로 잘 맞는지는 더 써봐야 안다.

⛓️ 기존 기능에 미치는 영향

문서·스킬 추가뿐이라 기존 코드에 영향 없음.

🔀 Edge Case & 실패 시나리오

없음 (문서/스킬 작업)

📋 검토한 대안과 선택 이유

Figma Code Connect(add_code_connect_map)로 WDS 라이브러리에 공식 매핑을 등록하는 것도 검토했으나, WDS는 우리가 소유하지 않은 Community 라이브러리라 Code Connect를 라이브러리 쪽에 직접 걸 수 없어 제외했다. 대신 이름+componentKey 대조 절차를 스킬 내부에 고정했다.

💬 리뷰 포인트

• [c] component-convention.md의 파일 위치 규칙(feature 우선, 재사용 확인되면 components/ui로 승격)이 팀 방향과 맞는지
• [c] figma-check의 검증 체크리스트(색상 토큰/WDS 재검증/박스모델/컴포넌트 기본값/스크린샷) 항목이 충분한지, 빠진 게 있는지

[tnals0924]

LGTM~

[jjunh33]

추가된 컨벤션 및 스킬 확인 완료했습니다~