danielhall/agent-skills

웹사이트를 Figma 디자인 파일로 변환하기

실행 중인 웹 앱을 디자이너가 실제로 재디자인할 수 있는 Figma 파일로 변환합니다. 실제 텍스트, 실제 아이콘, 라이트/다크 모드가 적용된 색상 및 간격 변수, 텍스트 스타일, 재사용 가능한 컴포넌트, 그리고 해당 컴포넌트의 인스턴스로 구성된 모든 페이지를 포함합니다. 스크린샷은 오직 참고 자료로만 사용되며 최종 결과물이 아닙니다.

이 스킬은 Figma 플러그인의 자체 스킬 위에 위치합니다. use_figma 호출 전에 figma-use와 figma-generate-design을 로드하고, 컴포넌트나 변수를 생성할 때는 figma-generate-library를 로드하세요.

사용 시기

• "내 사이트를 Figma에 가져와서 재디자인하고 싶어"
• "이 페이지들을 Figma에 재현해 줘" / "이 앱을 Figma로 푸시해 줘"
• 이런 방식으로 빌드된 Figma 파일에 모바일 프레임이나 새 페이지 추가하기

단계

1. 출처(Source of Truth) 읽기

• 실행 중인 앱과 전역 스타일시트가 디자인 문서보다 우선합니다. 문서는 재디자인 중에 변경될 수 있습니다. 불일치를 발견하면 그 사실을 알리세요.
• 수집할 항목: 테마 토큰(라이트/다크), 폰트 패밀리와 두께, 레이아웃 그리드(거터, 레일, 컬럼 너비), 각 페이지 섹션 뒤에 있는 컴포넌트 파일.
• 텍스트 스타일을 작성하기 전에 figma.listAvailableFontsAsync()를 사용하여 Figma에 폰트가 있는지 확인하세요. 절대 Inter로 자동 대체(Silent Fallback)하지 마세요.

2. Playwright로 참조 스크린샷 캡처 (페이지 캡처 사용 금지)

각 대상 너비(예: 1440 및 390)에서 scripts/ref-screenshots.mjs를 사용하세요. 이 스크립트는 reducedMotion: "reduce"를 설정하므로 스크롤 시 나타나는 애니메이션과 등장 애니메이션이 콘텐츠를 숨기지 않습니다.

generate_figma_design 페이지 캡처는 이 작업에 적합하지 않습니다. 뷰 내 애니메이션 뒤에 있는 콘텐츠는 빈 상태로 캡처되고, 백그라운드 브라우저 탭에서 열린 캡처는 종종 영원히 pending 상태로 남습니다. 만약 사용해야 한다면 한 번에 하나의 탭만 열고 캡처가 참조 자료로 사용된 후에는 삭제하세요. 앱에 캡처 스크립트를 삽입한 경우 작업 후 제거하세요.

3. 코드베이스에서 실제 데이터 및 아이콘 내보내기

앱 자체 데이터 모듈을 가져오고 react-dom/server의 renderToStaticMarkup을 사용하여 아이콘 컴포넌트를 SVG 문자열로 렌더링하는 임시 tsx 스크립트(저장소 외부에 작성하거나 작업 후 삭제)를 작성하세요. 그런 다음:

• currentColor를 실제 색상으로 바꾸고 모든 SVG에 명시적인 width/height를 지정하세요. 아이콘 라이브러리는 1em을 내보내는데, Figma는 이를 크기 조정할 수 없습니다.
• 패스 데이터를 기준으로 아이콘 중복을 제거하세요. 브랜드 맵은 종류 여러 이름을 하나의 로고로 연결합니다.
• CMS 클라이언트를 사용하여 CMS 콘텐츠(제목, 요약, 카테고리)를 다시 입력하는 대신 가져오세요.

4. 먼저 기초 구축하기

각 항목별로 한 번씩 호출하여 생성된 모든 ID를 반환받으세요:

1. 페이지: Foundations, Components, 중단점(Breakpoint)별 페이지.
2. 변수 컬렉션: 테마 색상(라이트/다크 모드), 카테고리 또는 브랜드 색상, 레이아웃 토큰(데스크탑/모바일 모드). 명시적인 scopes와 WEB 코드 구문을 설정하세요.
3. 모든 유형 역할에 대한 텍스트 스타일과 디스플레이 크기의 모바일 변형.
4. 공유된 그림자에 대한 이펙트 스타일.

5. 컴포넌트 구축, 가장 작은 것부터 시작

아이콘, 그다음 프리미티브(버튼, 링크, 타일, 배지, 칩), 그다음 복합 컴포넌트(헤더, 푸터, 히어로, 카드). 페이지가 분리(Detach) 없이 채워질 수 있도록 TEXT, BOOLEAN 및 INSTANCE_SWAP 속성을 노출하세요. 반응형 조각에는 인스턴스에서 크기를 재정의하는 대신 Breakpoint 변형을 제공하세요. 각 그룹을 한 번 스크린샷으로 확인하고, 다음 단계로 넘어가기 전에 잘못된 부분을 수정하세요.

6. 인스턴스로 페이지 조립하기

• 페이지당 하나의 use_figma 호출을 고정된 캔버스 위치에서 수행하여 페이지를 병렬로 빌드할 수 있도록 하세요.
• 절대 위치 대신 자동 레이아웃 패딩(예: 레일과 거터)으로 CSS 그리드를 미러링하세요.
• 행별 카드 높이를 명시적으로 균등화하세요. Figma는 CSS 그리드처럼 형제 요소를 늘리지 않습니다.
• 각 페이지의 전체 높이를 참조 스크린샷과 비교하세요. 몇 퍼센트 이내의 높이 차이는 간격이 올바르다는 것을 의미합니다.

7. 컴포넌트를 코드에 다시 연결하기

Code Connect는 Organization 및 Enterprise 요금제에서만 작동합니다. 먼저 whoami를 확인하세요. 다른 요금제에서는 각 컴포넌트의 description에 소스 경로, 컴포넌트 이름 및 prop 매핑을 작성하고 documentationLinks를 GitHub의 파일로 설정하세요. Dev Mode는 두 정보를 모두 표시합니다. 게시할 수 없는 저장소에 .figma.ts 파일을 추가하지 마세요. Code Connect 패키지 없이 tsc를 중단시킵니다.

8. 정리하기

참조 캡처를 삭제하고, 삽입된 스크립트를 제거하고, 시작한 개발 서버를 중지하고, git status가 깨끗한지 확인하세요.

함정(Pitfalls)

컴포넌트 또는 페이지 스크립트를 작성하기 전에 references/plugin-api-pitfalls.md를 읽으세요. 이 문서는 가장 많은 시간을 소모하는 오류들과 각각의 해결 방법(바운드 페인트 불투명도, resize()가 자동 레이아웃 크기 조정을 잠그는 문제, 속성 키 재설정, 복제된 변형에서 참조 손실, 호출당 크기 제한 등)을 나열합니다.

references/helpers.md에는 모든 페이지 빌드 스크립트 상단에 붙여넣을 만한 작은 도우미 함수들이 있습니다.