figma-access

Figma 접근

하나의 명령줄 도구로 Figma와 작업합니다. 이 도구는 KDL을 출력하고 데이터 파일을 .kdl로 저장합니다. 노드당 한 줄이며, 노드의 일반 필드는 key=value 형태로 해당 줄에 기록되므로 grep, awk, sed로 직접 작업할 수 있습니다. 예외는 spec(자체적인 한 줄-노드-당-한-줄 텍스트 개요 출력), daemon log(데몬의 로그 줄을 그대로 출력), render, screenshot, image-fills, compare(이미지 파일 저장, stdout 요약은 여전히 KDL)입니다. 두 가지 접근 방식이 있습니다:

• REST (file, node, spec, render, image-fills, api): 사용자의 토큰으로 URL을 통해 모든 파일을 읽습니다. 파일이 열려 있을 필요가 없습니다. 읽기는 로컬에 캐시되고 속도 제한 시 재시도됩니다.
• Plugin (exec, screenshot, selection, logs, changes, call): 백그라운드 데몬이 Figma Desktop에서 실행 중인 Desktop Bridge 플러그인과 통신합니다. 파일을 변경하는 유일한 방법입니다. 여기서 주요 도구는 exec로, 파일에서 Figma Plugin API JavaScript를 실행합니다.

references/tips.md에는 실제 실행 경험에서 얻은 교훈이 상황별로 정리되어 있습니다. 이는 가이드라인이지 규칙이 아닙니다: 현재 상황에 맞는 섹션을 읽고 케이스에 맞게 조정하세요.

규칙

• 토큰을 절대 노출하지 마십시오. 출력, 로깅, 에코하지 말고 figma-access api /v1/me로 테스트하십시오.
• 변경 전후를 항상 확인하십시오. 모든 가시적 결과는 코드가 아닌 이미지로 판단하십시오.
• 값을 추측하지 말고 읽으십시오; 렌더링이 결정합니다. 색상, 크기, 간격, 글꼴, 텍스트는 파일에서 가져오고, 이미지에서 눈으로 판단하지 마십시오. 파일 데이터와 렌더링이 다를 경우, 렌더링이 사용자가 보는 결과입니다.
• 사용자가 요청한 것만 변경하십시오. 읽는 것은 항상 괜찮습니다. 요청에 명시되지 않은 한 사용자의 기존 작업을 삭제하거나 덮어쓰지 마십시오.
• 타임아웃은 실패가 아닙니다. Figma는 실행 중인 스크립트를 중단할 수 없습니다. 다시 실행하기 전에 logs와 파일을 확인하십시오.

워크플로우

1. 설정

1. <skill>은 이 SKILL.md의 디렉터리입니다. 도구를 bun <skill>/scripts/figma-access.js COMMAND ...로 실행하십시오; 이 파일은 figma-access COMMAND ...로 작성합니다. Bun에서 실행되며 Node가 아닙니다: 항상 bun으로 시작하고, node로 시작하지 마십시오. 작성한 JavaScript나 TypeScript 헬퍼도 bun으로 실행하십시오. 명령어를 줄이려면 각 쉘 호출 시작 시 쉘 함수를 정의하십시오 (fa(){ bun <skill>/scripts/figma-access.js "$@"; }; fa ...). 변수는 사용하지 마십시오: zsh는 변수를 단어로 분할하지 않습니다. 전달하는 모든 URL과 노드 ID를 따옴표로 묶으십시오: ?, &, ;는 쉘에서 특수 문자입니다. bun이 없으면 사용자에게 https://bun.sh 에서 설치하라고 알리고 중단하십시오.
2. figma-access --help를 한 번 실행하고, 각 명령어를 처음 사용하기 전에 figma-access <command> --help를 실행하십시오. 종료 코드: 0 정상, 1 Figma 오류 보고, 2 잘못된 인수, 3 데몬/플러그인/토큰 사용 불가. references/tips.md의 "출력 읽기" 섹션에서 형식과 검색 방법을 설명합니다.
3. references/tips.md의 "경로 선택"에서 설명하는 대로 요청에서 경로를 선택하십시오: URL과 읽기 전용 작업 → REST; 파일 변경 → 플러그인; 둘 다 함께 사용 가능.

2a. REST 연결

1. figma-access api /v1/me를 실행하십시오. "토큰 없음" 메시지가 나오면 사용자가 토큰을 설정한 위치를 찾아 동일한 명령어에서 로드하십시오 (references/tips.md의 "토큰" 섹션 참조). 설정된 곳이 없을 때만 사용자에게 토큰을 요청하십시오 (Figma: 설정 > 보안 > 개인 액세스 토큰, 파일 콘텐츠 읽기 권한 필요).
2. figma-access file <url>을 실행하여 페이지와 최상위 프레임을 확인하십시오. references/tips.md의 "올바른 노드 찾기" 지침에 따라 작업할 노드를 선택하십시오.

2b. 플러그인 연결

1. figma-access status를 실행하십시오. 필요시 데몬을 시작합니다.
   • 파일 목록이 표시됨: 계속 진행.
   • 파일 없음: figma-access files를 실행하십시오. 플러그인을 기다립니다. 종료 코드 3으로 종료되면 figma-access setup을 실행하고 사용자에게 steps를 평이한 언어로 설명하십시오: 인쇄된 매니페스트 경로에서 플러그인을 한 번 가져온 후, 파일에서 Plugins > Development > Figma Desktop Bridge를 실행하고 창을 열어 두십시오. 사용자가 실행 중임을 알리면 다시 figma-access files를 실행하십시오.
2. 둘 이상의 파일이 연결된 경우: 이후 모든 명령어에 --file <fileKey>를 전달하십시오.

3. 디자인 이해

1. 질문에 답하는 가장 작은 뷰를 읽으십시오. 개요부터 시작하여 작업하는 부분만 상세히 확인:
   • 구조: figma-access node <url|key> <id> --outline 2 (REST), 또는 references/plugin-api.md의 페이지-개요 레시피 (플러그인);
   • 코드에 필요한 모든 것, 가시 노드당 한 줄: figma-access spec <url|key> <id> -o <file>; 큰 프레임의 경우 node ... -o <file>로 한 번 저장하고 이후 모든 spec에 --from <file>을 전달하십시오 (references/tips.md의 "속도 제한과 캐시" 참조);
   • 사용자가 "이것" 또는 "선택된 것"이라고 말할 때: figma-access selection;
   • 어떻게 보이는지: figma-access render <key> <id> (REST, 정확한 크기) 또는 figma-access screenshot <id> (플러그인), 그런 다음 이미지를 엽니다.
2. node의 reports(글꼴, 이미지 채우기, 제거된 숨겨진 레이어 수)를 읽으십시오. references/tips.md의 "숨겨진 레이어"와 "디자인 이미지 읽기"를 참조하십시오.
3. 컴포넌트, 변형, 변수 및 스타일의 경우, 변경하거나 복사하기 전에 실제 구조를 읽고, 중복을 만들지 말고 기존 것을 재사용하십시오.

4. 작업 수행

디자인을 코드로 구현. 코드를 작성하기 전에 references/tips.md의 "디자인에서 코드로"를 읽으십시오: 초기 빌드 후 남는 대부분의 차이점(이미지 자르기, 글꼴, 텍스트 오프셋, 페이지 너비)이 여기에 설명되어 있습니다. 코드는 사용자나 프로젝트가 지정한 위치(사용자가 명명한 경로 또는 프로젝트 자체 구조)에 작성하십시오; _swe/figma-access/에는 렌더, 저장된 노드 파일, 스펙, 스크린샷, 스크립트와 같은 작업 아티팩트만 보관합니다.

1. 프레임을 배율 1로 렌더링하여 참조로 사용하고, 프레임이 길면 부분적으로 읽으십시오.
2. 프레임의 spec을 파일에 작성하고, 페이지 콘텐츠가 시작되는 모서리에 --origin을 설정한 후 모든 값을 여기서 가져오십시오. 이미지를 다시 빌드하지 말고 ICON 또는 MASKED로 표시된 것은 렌더링하십시오. 자동 레이아웃 프레임은 저장된 상자가 아닌 spec이 출력하는 방향, 간격, 패딩, 크기 조정을 기반으로 빌드하고, 자동 레이아웃이 없는 그룹 및 프레임의 자식은 상자 위치에 배치하십시오. 모든 노드를 저장된 상자에 절대 위치로 배치하지 마십시오 (수동 또는 생성기 사용): 이는 모든 오래된 상자를 복사하고, 텍스트가 길어지면 깨지며, 창에 적응할 수 없습니다. LAYOUT DRIFT로 표시된 모든 부분을 렌더링과 대조하십시오.
3. 모든 가중치의 글꼴을 나열하십시오; 공개되지 않은 패밀리의 파일을 프로젝트에서 찾고, 여전히 누락된 것과 파일에서 얻을 수 없는 다른 것은 한 메시지로 사용자에게 물어보십시오. 도착할 때까지, 또는 물어볼 수 없을 때까지 대체 글꼴을 사용하고 그렇게 말하십시오.
4. 장치 또는 브라우저 크롬은 생략하고 페이지가 창에 적응하도록 하십시오: 프레임의 너비는 그려진 화면이므로 배경과 구분선은 창 전체에 걸치고 콘텐츠 열은 중앙에 배치합니다 (사용자가 고정 너비를 요청하지 않은 경우).
5. 섹션별로 빌드한 다음 figma-access compare <reference.png> <page> --nodes <node file> --wide <px>로 페이지를 참조와 측정하십시오: 페이지를 캡처하고, 각 섹션의 다른 픽셀과 이를 설명하는 이동, 각 텍스트 스타일과 노드의 오프셋, 누락된 항목을 출력하고, 차이 이미지를 작성하며, 더 넓은 창을 확인합니다. --nodes를 사용하면 프레임 자식에서 섹션을 가져오고 프레임 그림자가 넓힌 참조를 자릅니다. 캡처와 차이 이미지도 살펴보고 각 섹션이 일치할 때까지 반복하십시오. 사용자가 픽셀 완벽 또는 1:1 결과를 요청하고 해당 스킬이 세션에 나열된 경우, 이 렌더링을 디자인 이미지로 사용하십시오.

파일 변경. 플러그인을 통해:

1. references/plugin-api.md의 API 강제 사항과 배치 방법에 따라 Plugin API 코드로 변경 사항을 작성하고 figma-access exec로 실행하십시오. 긴 코드는 작업 파일(예: _swe/figma-access/)에 저장하고 exec -f로 실행하십시오. 다음에 필요한 ID는 항상 return하십시오; 긴 작업에는 --timeout 30s 이상을 추가하십시오.
2. 준비된 플러그인 루틴(컴포넌트 세트, 린트 및 접근성 감사, 이미지 채우기, 주석, FigJam 및 Slides 도우미)이 포함된 작업에는 figma-access call <METHOD> '<json>'을 사용하십시오; figma-access methods <filter>는 파라미터를 나열합니다.
3. 매번 출력을 읽으십시오: ok #false인 경우 원인을 수정하고 재시도 전에 부분 작업을 제거하십시오; resultAnalysis 아래 warning이 있으면 ID와 이름을 확인하십시오; 스크립트 자체 추적은 figma-access logs --since 2m을 사용하십시오.
4. 생성하거나 변경한 모든 노드의 스크린샷을 찍고(작은 노드는 --scale 2) 요청과 비교하십시오. 수정하고 다시 스크린샷을 찍으십시오; 세 번 시도 후에도 여전히 누락된 부분이 있으면 사용자에게 무엇이 남았고 이유가 무엇인지 알리십시오.

references/tips.md의 "플러그인 작업" 섹션에서 일반적인 문제를 다룹니다.

5. 보고

읽거나 변경한 내용을 노드 이름과 ID, 작성한 렌더, 스크린샷, 파일 경로와 함께 사용자에게 알리십시오. 수행하지 않은 작업, 가정한 사항(대체 글꼴, 건너뛴 숨겨진 레이어, 생략된 크롬), 확인되지 않은 사항을 모두 명시하십시오.

문제 해결

• "Rate limit exceeded" (429): CLI가 이미 대기 후 재시도했습니다. references/tips.md의 "속도 제한과 캐시"를 따르고, 다음 큰 읽기 전에 1분을 기다리십시오.
• 종료 코드 3, 연결된 파일 없음: 플러그인이 해당 파일에서 실행 중이지 않거나 아직 검색 중입니다(몇 초마다 확인). 사용자에게 다시 실행하도록 요청하십시오. figma-access daemon log는 연결 발생 시 표시합니다.
• 다른 도구가 동일한 플러그인 사용 (예: figma-console-mcp): 둘 다 함께 작동합니다; figma-access status는 이 데몬이 파일을 가지고 있는지 보여줍니다.
• 스킬 업데이트 후 오래된 동작: figma-access setup을 다시 실행하고, 사용자에게 Figma에서 매니페스트를 다시 가져오도록 요청한 후 figma-access daemon restart를 실행하십시오.
• "Plugin disconnected before it answered": 사용자가 플러그인이나 파일을 닫았거나 플러그인이 다시 로드되었습니다. 변경을 반복하기 전에 파일을 확인하십시오.