Figma State Board
상태 보드(State Board)는 하나의 캔버스에 기능이 가질 수 있는 모든 상태를 배치하는 Figma 섹션입니다. 그룹은 기기, 탭 또는 주제별로 나뉩니다. 각 카드에는 'ID · 이름', '트리거; 결과' 및 제품 화면이 포함됩니다. 마지막 그룹인 **갭 체크(Gap check)**는 프로토타입에는 아직 없지만 기능에 필요한 상태를 나열합니다. 디자이너, 엔지니어, QA 및 PM 모두가 공유하는 상태 목록으로 사용합니다.
프로젝트 코드는 일반적으로 실제 백엔드에 연결되지 않은 목업 데이터로 구축된 프로토타입입니다. 따라서 상태를 "구현됨 / 아직 구현되지 않음"으로 나누지 마십시오. 한 가지 질문만 하세요: 프로토타입이 이 상태를 구축합니까? 카드에는 세 가지 태그만 있습니다:
- 프로토타입(Prototype): 프로토타입에 이 분기가 있습니다. 실제 화면을 그리고 태그 레이블은 없음.
- 스펙에 명시됨(In spec): AC, 스펙, 목업 또는 사용되지 않는 i18n 카피에 언급되었지만 프로토타입이 구축하지 않음. 갭 체크에 배치.
- 제안됨(Suggested): 스펙이나 프로토타입 모두 언급하지 않음. 코드 증거 또는 기능 유형에서 유추. 갭 체크에 배치.
모든 스택과 모든 제품에 적용됩니다. board-format.md는 보드 사양의 소스 오브 트루스입니다.
언어. 행렬, 카드 이름, 설명, 와이어프레임 텍스트 및 보고서는 사용자의 언어로 작성합니다. 보드의 고정 레이블(태그, 갭 체크, 적용 범위 요약, 와이어프레임 제목, 레이어 이름)은 BOARD.lang에서 가져옵니다. 사용자가 중국어 번체로 작업하는 경우 'zh-TW', 그렇지 않으면 'en'입니다. 다른 언어는 영어 레이블을 유지하고 카드 텍스트는 사용자의 언어로 작성합니다.
이 스킬은 전체 흐름, 보드 및 감사를 담당합니다. 다른 작업은 동일한 플러그인의 다른 스킬에 위임됩니다:
| 작업 | 사용 | 시기 |
|---|---|---|
| 스케일 가드 | scale-guard.md | 1단계 전에 읽기 |
| 디자인 시스템에 바인딩 | figma-library-binding | 1단계에서 확인, 5단계에서 사용 |
| 상태 인벤토리화, 갭 찾기 | state-discovery | 2단계 |
| 코드에서 화면 재구축 | code-to-figma | 5단계, 경로 B에서 |
이 스킬의 자체 파일:
- board-format.md: 보드 레이아웃, 글꼴 크기, 태그 및 카드 ID 규칙. 그리기 전에 읽기.
- board-skeleton.js: 행렬에서 보드 스켈레톤 및 갭 와이어프레임을 만듭니다. 4단계에서 사용.
- screenshot-slots.js: 업로드된 브라우저 스크린샷을 카드에 맞춥니다. 5단계 경로 C에서 사용.
- audit.js: 보드 감사. 6단계에서 사용.
프로젝트에 자체 UI 규칙 스킬(예: 프로젝트의 UI 가이드라인 스킬)이 있는 경우 제품 화면 토큰, 명명 및 승인에 대해 이를 따릅니다.
단계
1. 입력 확인
누락된 항목을 요청:
- 코드 소스: 저장소, 브랜치, 기능 진입점(라우트, 페이지, 화면 또는 컴포넌트)
- 규칙 소스: Jira AC, PRD, Confluence, 오류 코드 문서. 없으면 "없음"이라고 작성. 갭 체크에 더 많은 카드가 있음.
- 대상: Figma 파일 및 페이지. 새 섹션 또는 기존 상태 보드 업데이트. 연습 보드 또는 다른 사람과 공유할 보드의 경우 팀의 공유 연습 파일 사용 (board-format.md "공유 연습 파일" 규칙 참조). 대상이 기존 파일인 경우 사용자에게 현재 메모리 사용량을 보고하도록 요청 (scale-guard.md).
- 차원: 상태가 달라지는 축(기기 너비, 로그인 상태, 역할, 탭, 데이터 볼륨, 상호 작용 순서…) 및 각 기기의 뷰포트 너비.
- 제품 화면 소스: 대상 파일 또는 라이브러리의 컴포넌트, 또는 실행 중인 프로토타입 / 개발 서버. 없으면 와이어프레임만 그릴 수 있음. 미리 알림.
- 디자인 시스템 라이브러리: 제품 화면이 바인딩되어야 하는 라이브러리 (figma-library-binding). 없으면 "없음"이라고 작성.
Figma 링크를 받는 즉시 두 가지 작업을 먼저 수행하십시오. 인벤토리가 완료될 때까지 파일에 그릴 수 없다는 것을 알게 되는 것을 기다리지 마십시오:
- 읽기 및 쓰기 액세스 확인:
create_session을 실행한 다음 하나의 읽기 전용use_figma를 실행(페이지 및 최상위 노드 나열). "해당 파일에 액세스할 수 없습니다"라고 보고되면whoami를 사용하여 MCP에 로그인된 계정을 확인하고 사용자에게 두 가지 옵션 제공: 편집 가능한 상태로 해당 계정과 파일 공유, 또는 커넥터 설정에서 액세스 권한이 있는 계정으로 로그인(전환 후 원래 계정의 파일은 열 수 없음). - 호출 예산 추정: scale-guard.md "MCP 호출 예산"에 따라 이 실행에 필요한 호출 수를 추정하고
whoami의 대상 파일 플랜의 시트 수와 비교합니다. 충분하지 않으면 먼저 알리고 사용자가 선택하도록 합니다: 경로 C(카드의 브라우저 스크린샷. 전체 보드에 약 3회 호출. 5단계), 배치로 분할, 파일 전환, 또는 더 적은 비교 수행.
완료 조건: 6개 항목 모두 명확한 값이 있거나 사용자가 명시적으로 해당되지 않는다고 말함. 대상 파일을 읽을 수 있음. 호출 예산이 충분하거나 사용자가 작업 분할 방법을 선택함.
2. 상태 인벤토리화 및 상태 행렬 구축
state-discovery를 사용하여 행렬을 구축합니다. board-format.md의 규칙에 따라 미리 카드 ID를 할당합니다.
사용자가 행렬을 확인할 때까지 그리지 마십시오. 그룹 분할 방법, 병합할 카드 및 유지할 제안된 카드는 이 단계에서 결정됩니다. 그린 후 변경하는 데 훨씬 더 많은 비용이 듭니다. 프로토타입 카드가 150개를 초과하는 경우 scale-guard.md를 따르고 사용자에게 카드 병합, 페이지 분할 또는 파일 분할을 결정하도록 요청하십시오. 결정할 때까지 그리지 마십시오.
3. 각 카드에 대한 데이터 준비
- 프로토타입: 고정 목업 데이터 또는 스토리북 스토리로 재현합니다. 목업 레이어에 누락된 데이터를 추가합니다. 스크린샷만을 위해 컴포넌트에 분기를 추가하지 마십시오.
- 스펙에 명시됨, 제안됨: 프로토타입에 화면이 없으므로 데이터가 필요하지 않습니다. 와이어프레임을 그립니다. 스펙에 명시됨 카드의 경우 와이어프레임에 스펙 요구 사항과 출처를 기록합니다.
완료 조건: 모든 프로토타입 카드에 재현 가능한 데이터가 있거나 "Figma 전용 예시"로 명확하게 표시됨.
4. 보드 스켈레톤 구축
먼저 Figma 플러그인의 두 스킬인 figma-use 및 figma-generate-design을 로드합니다(Claude Code의 경우 figma:figma-use / figma:figma-generate-design. Figma 플러그인이 없으면 get_figma_skill을 사용하여 skill://figma/figma-use/SKILL.md 등을 읽고 skillNames에 resource: 접두사를 사용).
대상이 기존 파일인 경우 쓰기 전에 사용자에게 버전을 저장하도록 요청합니다. 직접 구축한 카드를 삭제하거나 재구축하기 전에도 동일하게 적용됩니다. 대상 페이지에 당신이 구축한 것 외에는 아무것도 없는 경우(완전히 새 파일, 빈 페이지) 저장을 건너뛸 수 있습니다. 보고서에 명시하십시오.
새로운 상태 보드의 경우 board-skeleton.js를 사용합니다: 2단계에서 확인된 행렬을 상단의 BOARD에 채우고 전체 스크립트를 하나의 use_figma 호출에 붙여넣습니다. board-format.md에 따라 섹션(이름은 "<프로젝트>-<기능>"이며 페이지의 기존 콘텐츠 오른쪽에 배치) → 보드 제목, 부제목, 적용 범위 요약(자동 계산) → 그룹 → 시나리오 → 카드를 구축합니다. 마지막 그룹은 갭 체크이며 와이어프레임이 그려집니다. 프로토타입 카드 화면은 placeholder = true인 플레이스홀더 슬롯으로 시작합니다. 스크립트는 각 카드의 slotId를 반환하며, 5단계에서 화면을 구축할 때 전달합니다. 공유 파일에서 기능당 하나의 페이지를 사용하고 BOARD.pageName을 페이지 이름으로 설정합니다. 위의 "언어"에 따라 BOARD.lang을 설정하고 각 갭 카드의 tag를 'spec'(스펙에 명시됨) 또는 'suggested'(제안됨)로 설정합니다.
기존 상태 보드를 업데이트할 때는 스켈레톤 스크립트를 실행하지 마십시오. 대신 다음 규칙을 사용:
- 모든 변형 전에 대상 노드를 다시 읽습니다. 디자이너가 수동으로 이동하거나 분할했을 수 있습니다.
- 영향을 받은 카드만 변경합니다. ID는 유지합니다. 새 카드는 해당 그룹의 마지막 번호 뒤에 계속됩니다.
- 프로토타입이 갭 체크 카드의 상태를 구축하면 해당 카드를 속한 그룹으로 이동하고 태그를 제거하고 새 ID를 부여하며 설명에 이전 G ID를 기록합니다.
- 적용 범위 요약의 숫자를 다시 계산합니다.
- 사용자가 다른 언어로 작성하더라도 추가하는 레이블에 대해 보드의 기존 언어를 유지합니다. 레이블이 혼합된 보드는 읽기 어렵습니다.
- 오른쪽의 디자이너 노트 영역이나 피드백 섹션은 건드리지 마십시오.
완료 조건: 모든 프로토타입 카드에 플레이스홀더 슬롯과 slotId가 있음. 모든 갭 체크 와이어프레임이 그려짐.
5. Figma에서 화면 구축
use_figma를 사용하여 네이티브 레이어를 구축하고 4단계의 플레이스홀더 슬롯에 배치합니다. send_code_to_figma는 코드 레이어를 가져오고 편집 가능한 디자인 레이어를 생성하지 않으므로 상태 보드에 적합하지 않습니다.
경로 B에서 code-to-figma "Figma에 쓰기 위한 하드 규칙"을 따르고 한 번에 하나의 화면만 보냅니다. 프로토타입 카드가 100개를 초과하거나 고유 이미지가 20개를 초과하는 경우 scale-guard.md에 따라 각 그룹 후에 사용자에게 메모리 사용량을 보고하도록 요청합니다. 쓰는 동안 scale-guard.md 중지 조건(호출 제한 도달 포함)에 도달하면 중지하고 재시도하지 마십시오.
먼저 경로를 선택하고 사용자와 확인:
- 경로 A: 목업 복사(기본값). 대상 파일 또는 라이브러리에 완전한 목업 화면이 있는 경우 사용합니다. 변수를 바인딩하고 Auto Layout을 유지할 수 있습니다.
- 경로 B: 프로젝트 코드에서 재구축. 대상 파일에 복사할 목업이 없거나 사용자가 목업 붙여넣기 대신 코드에서 재구축을 요청하는 경우 사용합니다. code-to-figma를 따르고
slotId를__alBuild에 전달합니다. 제품 화면은 카드의 플레이스홀더 슬롯에 들어갑니다. 현재 웹 프론트엔드만 지원. - 경로 C: 브라우저 스크린샷. 각 프로토타입 카드는 실행 중인 앱의 스크린샷을 표시합니다. 아무것도 재구축되지 않습니다. 전체 보드는 카드 수에 관계없이 약 3회의 계수된 호출을 사용하므로 호출 예산이 경로 B를 감당할 수 없을 때(Starter 플랜, View 및 Collab 시트) 또는 사용자가 상태 목록과 갭 체크만 필요한 경우 제공하십시오. 화면은 그림이며 편집 가능한 레이어가 아닙니다. 제공할 때와 보고서에서 다시 언급하십시오. 웹 프론트엔드만 지원. 단계는 아래 "경로 C"에 있습니다.
경로 A 및 B에서 제품 화면은 screen-structure.md를 따라야 합니다: 화면 루트 프레임 너비 고정 = W; 자식이 정렬된 컨테이너에 Auto Layout; 그룹 없음; 반복되는 UI는 컴포넌트로(다른 상태의 경우 변형); 캐러셀 컨테이너는 클립하고 Hug 사용 안 함; 긴 텍스트는 채우기 + 자동 높이. 갭 체크 카드(스펙에 명시됨, 제안됨)는 board-format.md의 와이어프레임 사양을 따릅니다. 가짜 제품 UI를 그리지 마십시오.
다음 1-3단계는 경로 A에 해당:
- 화면 및 컴포넌트 찾기: 대상 파일에 이미 완전한 목업 화면이 있으면 복사하고 상태를 변경(변형 전환, 레이어 숨기기)하는 것이 제품에 가장 가깝습니다. 다음으로
search_design_system및 로컬 컴포넌트를 사용합니다. 둘 다 없으면 코드의 구조와 스타일에서 로컬 레이어를 구축합니다. 색상, 글꼴 크기 및 간격을 프로젝트의 변수에 바인딩합니다. 목업과 코드가 일치하지 않으면 코드를 따르고 설명에 기록합니다.- 제품 글꼴을 Figma 런타임에 로드할 수 없는 경우(예: Arial) 기존 텍스트를 변경하지 마십시오. 새 텍스트의 경우 호환되는 너비의 글꼴(Arial → Arimo)을 사용하고 사용한 위치를 보고서에 나열합니다.
- 먼저 기기당 하나의 대표 화면을 구축하고 스크린샷을 프로토타입 또는 라이브 화면과 비교합니다: 텍스트, 간격, 모서리 반경 및 토큰이 모두 정확할 때만 진행합니다. 비교할 대상이 없으면 보고서에 해당 화면이 비교되지 않았음을 명시합니다.
- 대표 화면에서 클론 또는 인스턴스 및 재정의를 사용하여 나머지 프로토타입 카드를 생성하며, 이 상태에서 다른 것만 변경합니다.
경로 C:
- 캡처: web-capture.md의 1-3단계를 따라 config에서
shotOnly: true로 설정합니다. 2배율로shot/<ID>.jpg를 쓰고 레이아웃 트리를 건너뜁니다.stats.json을 읽습니다: 4096px에 대한 경고는 화면이 하나의 이미지에 비해 너무 길다는 의미이므로 여러 개의 뷰포트 높이 카드로 캡처합니다. - 업로드하기 전에 모든 스크린샷을 로컬에서 확인합니다. 이것이 경로 C의 비교 단계입니다: 잘못된 상태, 완료되지 않은 스피너 또는 샷에 남아 있는 개발자 도구는 여기서 수정하는 데 비용이 들지 않습니다.
- 업로드:
nodeIds를 카드 순서대로 카드의slotId로 설정하여upload_assets를 호출합니다(호출당 최대 60개). submitUrl을 한 줄에 하나씩 파일에 쓰고 동일한 순서로 스크린샷을 보냅니다:python3 al-upload.py urls.txt capture/shot/C01.jpg capture/shot/C02.jpg.upload_assets가 슬롯을 채우지 못하면currentPageId및count와 함께 호출합니다. 스크린샷은<ID>.jpg라는 이름의 레이어로 페이지에 배치되며 다음 단계에서 카드로 이동합니다. 파일 이름을 바꾸지 마십시오. SECTION_ID가 바뀐 screenshot-slots.js를 audit.js(6단계)와 동일한use_figma호출에서 실행합니다: 각각을 async 함수에 래핑하고 순서대로 호출한 다음 보드 섹션에서await section.screenshot()을 수행하여 두 결과를 반환하기 전에 보드의 사진이 동일한 호출로 반환되도록 합니다. 각 슬롯을 스크린샷에 맞게 크기를 조정하고placed,missing및skipped를 반환합니다.missing에 있는 카드에 대해 다시 업로드합니다.- 나중에 스크린샷 카드를 편집 가능한 레이어로 전환하려면 경로 B로 해당 카드를 재구축하고 동일한
slotId를 전달합니다. 재구축이 사진을 대체합니다.
완료 조건: 각 기기의 대표 화면 스크린샷을 확인했으며 프로토타입과 일치하거나 비교할 대상이 없음을 명시했습니다. 경로 B는 code-to-figma의 완료 기준도 충족해야 합니다. 경로 C에서 모든 프로토타입 카드가 placed에 있거나 보고서에 포함되지 않은 카드가 나열됩니다.
6. 감사
- 두 감사 스크립트를 모두 실행하고
SECTION_ID를 대상 섹션으로 바꿉니다. 둘 다 동일한use_figma호출에 붙여넣습니다(각각을 async 함수에 래핑하고 순서대로 호출하고 두 결과를 모두 반환)하여 예산에서 한 번의 호출을 절약합니다:- audit.js: 보드 감사. 그룹에 제목과 설명이 있는지, 중복 카드 ID, 캐…
…(truncated)