Communitygithub.com

figma-state-board

코드로부터 기능의 모든 UI 상태를 인벤토리화하여 하나의 Figma 캔버스에 배치합니다(State Board). 프로토타입이 이미 처리한 상태는 실제 화면으로 그리고, 누락된 에러, 빈 상태, 로딩 상태는 갭 체크로 분류하여 스펙 필수 항목과 제안 항목으로 나눕니다. 사용자가 'state board', 'Figma에 이 기능의 모든 상태', '어떤 에러 화면이 누락되었나요'와 같이 요청하거나 기존 보드를 업데이트할 때 사용합니다.

figma-state-board란 무엇인가요?

Figma State Board 스킬은 개발 중인 기능의 모든 UI 상태를 코드에서 추출하여 하나의 Figma 섹션에 체계적으로 배치하는 전문 도구입니다. 프로토타입이 이미 구현한 상태는 실제 화면으로 그리고, 구현되지 않은 상태는 '갭 체크(Gap check)' 섹션에 분류합니다. 이때 갭 체크는 '스펙에 명시됨(In spec)'과 '제안됨(Suggested)'으로 세분화하여, 디자이너, 엔지니어, QA, PM 모두가 공유할 수 있는 상태 목록을 제공합니다. 이 스킬은 state-discovery(상태 인벤토리), code-to-figma(코드에서 Figma로 화면 전환) 등 동일한 플러그인의 다른 스킬들과 협력하여 전체 워크플로우를 관리하며, 모든 기술 스택과 제품 유형에 적용 가능합니다. 사용자의 언어로 행렬, 카드 이름, 설명을 작성하고, 보드의 고정 레이블은 영어 또는 중국어 번체로 제공됩니다. 주요 단계로는 입력 확인, 상태 인벤토리, 보드 스켈레톤 생성, 화면 구축(복사, 코드 재구축 또는 브라우저 스크린샷), 감사가 포함되며, Figma의 호출 예산과 확장성을 고려한 스케일 가드 지침을 따릅니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/byby325/code-to-figma-ui-states/tree/HEAD/skills/figma-state-board

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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.md1단계 전에 읽기
디자인 시스템에 바인딩figma-library-binding1단계에서 확인, 5단계에서 사용
상태 인벤토리화, 갭 찾기state-discovery2단계
코드에서 화면 재구축code-to-figma5단계, 경로 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 링크를 받는 즉시 두 가지 작업을 먼저 수행하십시오. 인벤토리가 완료될 때까지 파일에 그릴 수 없다는 것을 알게 되는 것을 기다리지 마십시오:

  1. 읽기 및 쓰기 액세스 확인: create_session을 실행한 다음 하나의 읽기 전용 use_figma를 실행(페이지 및 최상위 노드 나열). "해당 파일에 액세스할 수 없습니다"라고 보고되면 whoami를 사용하여 MCP에 로그인된 계정을 확인하고 사용자에게 두 가지 옵션 제공: 편집 가능한 상태로 해당 계정과 파일 공유, 또는 커넥터 설정에서 액세스 권한이 있는 계정으로 로그인(전환 후 원래 계정의 파일은 열 수 없음).
  2. 호출 예산 추정: 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에 해당:

  1. 화면 및 컴포넌트 찾기: 대상 파일에 이미 완전한 목업 화면이 있으면 복사하고 상태를 변경(변형 전환, 레이어 숨기기)하는 것이 제품에 가장 가깝습니다. 다음으로 search_design_system 및 로컬 컴포넌트를 사용합니다. 둘 다 없으면 코드의 구조와 스타일에서 로컬 레이어를 구축합니다. 색상, 글꼴 크기 및 간격을 프로젝트의 변수에 바인딩합니다. 목업과 코드가 일치하지 않으면 코드를 따르고 설명에 기록합니다.
    • 제품 글꼴을 Figma 런타임에 로드할 수 없는 경우(예: Arial) 기존 텍스트를 변경하지 마십시오. 새 텍스트의 경우 호환되는 너비의 글꼴(Arial → Arimo)을 사용하고 사용한 위치를 보고서에 나열합니다.
  2. 먼저 기기당 하나의 대표 화면을 구축하고 스크린샷을 프로토타입 또는 라이브 화면과 비교합니다: 텍스트, 간격, 모서리 반경 및 토큰이 모두 정확할 때만 진행합니다. 비교할 대상이 없으면 보고서에 해당 화면이 비교되지 않았음을 명시합니다.
  3. 대표 화면에서 클론 또는 인스턴스 및 재정의를 사용하여 나머지 프로토타입 카드를 생성하며, 이 상태에서 다른 것만 변경합니다.

경로 C:

  1. 캡처: web-capture.md의 1-3단계를 따라 config에서 shotOnly: true로 설정합니다. 2배율로 shot/<ID>.jpg를 쓰고 레이아웃 트리를 건너뜁니다. stats.json을 읽습니다: 4096px에 대한 경고는 화면이 하나의 이미지에 비해 너무 길다는 의미이므로 여러 개의 뷰포트 높이 카드로 캡처합니다.
  2. 업로드하기 전에 모든 스크린샷을 로컬에서 확인합니다. 이것이 경로 C의 비교 단계입니다: 잘못된 상태, 완료되지 않은 스피너 또는 샷에 남아 있는 개발자 도구는 여기서 수정하는 데 비용이 들지 않습니다.
  3. 업로드: 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라는 이름의 레이어로 페이지에 배치되며 다음 단계에서 카드로 이동합니다. 파일 이름을 바꾸지 마십시오.
  4. SECTION_ID가 바뀐 screenshot-slots.js를 audit.js(6단계)와 동일한 use_figma 호출에서 실행합니다: 각각을 async 함수에 래핑하고 순서대로 호출한 다음 보드 섹션에서 await section.screenshot()을 수행하여 두 결과를 반환하기 전에 보드의 사진이 동일한 호출로 반환되도록 합니다. 각 슬롯을 스크린샷에 맞게 크기를 조정하고 placed, missing 및 skipped를 반환합니다. missing에 있는 카드에 대해 다시 업로드합니다.
  5. 나중에 스크린샷 카드를 편집 가능한 레이어로 전환하려면 경로 B로 해당 카드를 재구축하고 동일한 slotId를 전달합니다. 재구축이 사진을 대체합니다.

완료 조건: 각 기기의 대표 화면 스크린샷을 확인했으며 프로토타입과 일치하거나 비교할 대상이 없음을 명시했습니다. 경로 B는 code-to-figma의 완료 기준도 충족해야 합니다. 경로 C에서 모든 프로토타입 카드가 placed에 있거나 보고서에 포함되지 않은 카드가 나열됩니다.

6. 감사

  1. 두 감사 스크립트를 모두 실행하고 SECTION_ID를 대상 섹션으로 바꿉니다. 둘 다 동일한 use_figma 호출에 붙여넣습니다(각각을 async 함수에 래핑하고 순서대로 호출하고 두 결과를 모두 반환)하여 예산에서 한 번의 호출을 절약합니다:
    • audit.js: 보드 감사. 그룹에 제목과 설명이 있는지, 중복 카드 ID, 캐…

…(truncated)

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

code-to-figma

Rebuild screens from a running web app as native, editable Figma layers (Auto Layout, components, instances) and diff them against browser screenshots — not a screenshot import or a Code layer. Use when the user asks to "turn this page into Figma", "code to Figma", "push this screen to Figma" or "rebuild the UI in Figma". 把 Web 專案實際跑出來的畫面重建成 Figma 原生圖層:造狀態、抽 DOM 版面樹,建 Auto Layout 和 component/instance,再跟瀏覽器截圖比對。單一畫面或一批畫面都能用,不需要做情境稿。Use when 使用者要「code to figma」「把這頁轉成 Figma」「從程式重建畫面」「push 畫面到 Figma」,或 figma-state-board 走路線 B。產出是可編輯圖層,不是 Code layer 或截圖。

figma-library-binding

Bind Figma screens to a design system library — tokens only on exact value matches, swap icons and components for library versions, and list unmatched values for designers instead of snapping to the nearest token. Use when the user asks to "bind tokens", "use library components" or "find unbound colors". 把 Figma 畫面綁到專案的 design system library:顏色、圓角、邊框、間距、字級完全相同才綁 token,圖示和元件換成 library 版本,沒有對應的值列給設計決定,不取最近值。Use when 使用者要「綁 library」「綁 token」「換成 design system 元件」「檢查沒綁 variable 的顏色」,或 code-to-figma、figma-state-board 的畫面要綁 design system。

관련 스킬