Menu
packages/react에서 Figma 디자인을 Panda CSS + Ark UI 기반 React 컴포넌트로 구현하는 파이프라인. 새 컴포넌트 생성과 기존 컴포넌트 업데이트 모두 지원한다. Figma URL이나 컴포넌트 이름이 주어졌을 때 사용한다.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | react-component-pipeline |
| description | packages/react에서 Figma 디자인을 Panda CSS + Ark UI 기반 React 컴포넌트로 구현하는 파이프라인. 새 컴포넌트 생성과 기존 컴포넌트 업데이트 모두 지원한다. Figma URL이나 컴포넌트 이름이 주어졌을 때 사용한다. |
packages/react에서 Figma 디자인 → Panda CSS + Ark UI React 컴포넌트를 만드는 전체 파이프라인.
| 레이어 | 도구 |
|---|---|
| 헤드리스 UI | @ark-ui/react (ark.button, ark.div 등) |
| 스타일링 | Panda CSS (defineRecipe, styled()) |
| 디자인 토큰 | packages/design-tokens/build/panda/tokens.ts → panda.config.ts |
| 빌드 | pnpm codegen → tsdown → pnpm cssgen |
| 스토리 | Storybook 10, CSF3, variantMap 기반 |
이 파이프라인은 "묻는 것과 결정하는 것을 구분"하는 style을 기본으로 한다. 결정마다 아래 3-tier에 따라 처리한다.
사용자에게 옵션(A/B/(추천)C)과 trade-off를 제시하고 선택을 받는다.
해당 기준:
hasX + x 중복, variant 재해석 필요 등)이 보일 때 — 디자이너 의도인지 tool artifact인지 분간이 필요함결정은 에이전트가 내리되, PR 본문의 Decisions 섹션에 근거를 남겨 리뷰어가 뒤집을 여지를 둔다.
해당 기준:
InfoList → <ul>/<li>, NavBar → <nav>, Button → <button>)에이전트가 바로 결정하고 진행한다. 사용자에게 별도 확인하거나 PR에 특별히 강조하지 않는다.
해당 기준:
feat/{kebab-name}, 파일 naming, 기본 commit 메시지 형식)mcp_Question 등으로) 묶어 제시한다. 매 결정마다 따로 왕복하지 않는다.구현 전에 반드시 아래 파일들을 읽어서 현재 패턴을 파악한다.
packages/react/src/recipes/button.ts # recipe 구조, compound variant 패턴
packages/react/src/components/button/button.tsx # forwardRef, styled(), props 설계
packages/react/src/components/button/button.stories.tsx # CSF3 + variantMap 패턴
packages/react/panda.config.ts # recipe 등록 방식
packages/design-tokens/build/panda/tokens.ts # 사용 가능한 semantic token 전체 목록
ls packages/design-tokens/build/panda/tokens.ts
파일이 없으면 pnpm --filter @bubbly-design-system/design-tokens build를 먼저 실행한다.
ls packages/react/src/components/
ls packages/react/src/recipes/
REST API로 데이터를 뽑기 전에, Figma 노드의 스크린샷을 먼저 확인한다. 디자이너가 docs 프레임에 시각적으로만 전달한 정보(레이아웃 가이드, 간격 표기, 상태별 비교, 사용 예시 등)가 있을 수 있고, 이건 JSON에는 담기지 않는다.
Figma URL에서 fileKey와 nodeId를 추출한다:
https://www.figma.com/design/<FILE_KEY>/<NAME>?node-id=<NODE_ID>
node-id의 -를 :로 변환 (예: 2604-10660 → 2604:10660)Guard: 안전한 scale 자동 계산 (LLM 8000px 제한)
LLM의 이미지 처리는 한 변이 8000px을 초과하면 세션이 죽는다. 이미지 요청 전에 노드 크기를 확인하고, 8000px 이하가 되는 scale을 자동 계산한다.
source .env && curl -s \
-H "X-Figma-Token: $FIGMA_PAT" \
"https://api.figma.com/v1/files/{FILE_KEY}/nodes?ids={NODE_ID}&depth=1" \
| python3 -c "
import json, sys, math
data = json.load(sys.stdin)
node = list(data['nodes'].values())[0]['document']
box = node.get('absoluteBoundingBox', {})
w, h = box.get('width', 0), box.get('height', 0)
max_dim = max(w, h)
if max_dim == 0:
print('scale=1')
sys.exit(0)
# 8000px 이하가 되는 최대 scale (0.01~4 범위, 소수점 둘째자리)
safe_scale = min(4, math.floor(8000 / max_dim * 100) / 100)
safe_scale = max(0.01, safe_scale)
print(f'node: {w:.0f}x{h:.0f}')
print(f'scale={safe_scale} -> {w*safe_scale:.0f}x{h*safe_scale:.0f}')
"
출력된 scale 값을 아래 이미지 요청에 그대로 사용한다.
source .env && curl -s \
-H "X-Figma-Token: $FIGMA_PAT" \
"https://api.figma.com/v1/images/{FILE_KEY}?ids={NODE_ID}&format=png&scale={SAFE_SCALE}"
응답의 images 객체에서 URL을 받아 webfetch나 look_at 도구로 내용을 확인한다.
스크린샷에서 확인할 것:
Figma에 여러 섹션(노드)이 있으면 모든 섹션의 스크린샷을 확인한다. 하나의 컴포넌트가 Background/Standard처럼 여러 섹션으로 나뉘어 문서화되어 있을 수 있다.
위에서 추출한 fileKey와 nodeId를 사용한다:
https://www.figma.com/design/<FILE_KEY>/<NAME>?node-id=<NODE_ID>
node-id의 -를 :로 변환 (예: 2604-10660 → 2604:10660)source .env && curl -s \
-H "X-Figma-Token: $FIGMA_PAT" \
"https://api.figma.com/v1/files/{FILE_KEY}/nodes?ids={NODE_ID}&depth=3"
결과가 크므로 explore 에이전트에 위임하여 아래를 추출한다:
color=brand, type=solid, size=medium, state=default)fills[].color.a (색상 알파)와 fills[].opacity (fill 레벨 불투명도). 실제 표현은 color.a × fill.opacityfill.opacity도 추출. opacity=0이면 투명, opacity=0.2이면 반투명 등stroke.opacity까지 확인base에 backgroundColor 추가base에 넣으면 fill이 없어야 할 상태에서도 배경색이 보여 다른 컴포넌트 합성 시 문제가 생긴다 (예: Skeleton 위에 동색 배경 → 애니메이션 안 보임)Figma에는 JSON/스크린샷만 보면 놓치는 디자이너 노트가 body 프레임 내부에 박혀 있는 경우가 많다. 능동적으로 찾는다.
스캔 대상:
info 컴포넌트 / Badge instance — "In progress", "추후 확장", "한계" 등의 텍스트. 설계 의도나 제한 사항을 담음TEXT 노드 — "~~때문에 이렇게 되어있음", "개발단에선 ~~로" 같은 맥락 설명흔히 발견되는 노트 유형:
| 노트 유형 | 해석 |
|---|---|
| "Figma 한계로 A이지만 실제로는 B" | 코드에서는 B로 구현 (Figma를 mechanical 번역하지 말 것) |
| "추후 확장 예정" / "In progress" | 현재는 미구현/미정이지만 API 설계 시 확장 여지 고려 |
| "A의 책임은 B가 가져간다" | 역할 재분배 의도. 순진한 Figma 구조를 그대로 옮기지 말 것 |
| "모든 요소는 X prop을 따라간다" | cascade / inherit 전략으로 구현 |
1-A에서 docs 프레임이 보였다면, 그 프레임 자체를 REST API로 depth=3~5로 다시 긁어서 모든 text 노드를 수거한다. info instance가 있으면 그 내부 text까지 꺼낸다.
사용자가 별도 docs 이미지를 제공한 경우에도 동일하게 교차 확인한다:
이 단계를 건너뛰면 하드코딩된 색상값이 들어가서 토큰 시스템이 깨진다.
packages/design-tokens/build/panda/tokens.ts를 열고, Figma에서 추출한 rgba 값을 semantic token 이름으로 매핑한다.
매핑 순서:
tokens.colors에서 기본 색상 찾기 (예: rgb(133 102 255) → colors.violet.400)semanticTokens.colors에서 용도 찾기 (예: colors.violet.400 → surface.brand.default)backgroundColor: 'surface.brand.default')자주 쓰이는 매핑:
| 용도 | semantic token |
|---|---|
| brand solid 배경 | surface.brand.default |
| brand solid hover | surface.brand.default-hover |
| ghost/outline hover 배경 | surface.transparent-hover |
| neutral 아이콘/텍스트 | content.neutral.default |
| outline 테두리 | border.neutral.default |
| outline hover 테두리 | border.neutral.default-hover |
| disabled 배경 | surface.disabled |
| disabled 텍스트/아이콘 | content.disabled |
| 흰색 (solid 위) | static.white |
| focus ring | var(--colors-neutral-600) (inner), var(--colors-neutral-50) (outer) |
구현 전에 아래 결정을 확정한다. Working style의 3-tier에 따라 각 지점을 ASK / DECIDE+문서화 / DECIDE silently 중 하나로 처리한다.
Phase 1에서 뽑은 스펙을 기계적으로 옮기지 말고, 결정 지점을 먼저 식별한다. 각 지점마다 3-tier 중 어디인지 판단하고 대응한다.
훑어볼 카테고리 (모두 필수):
a. Figma 한계 · 이상 패턴
hasX boolean + x slot/prop 동시 존재 → x?: ReactNode 하나로 통합 (Tier 2)color)를 안 타는 경우 (예: brand variant인데 swapped icon만 neutral) → Tier 1으로 의도 확인b. 공개 API 표면 → Tier 1
A + B) vs namespaced (A.Root + A.Item)children) vs props passthroughc. 접근성 · 시맨틱 HTML → Tier 2
<div> vs <ul>/<li> vs <nav> — 컴포넌트 이름이 가리키는 semantic으로 결정aria-hidden, role, aria-label 필요성d. behavior 기본값 → Tier 1 (defensible 대안 2+ 개) 또는 Tier 2 (한 방향이 명확)
defaultVariants 그대로면 Tier 3)e. 내부 구현 → Tier 3
판단 플로우:
각 결정 지점:
├─ Tier 1? → 사용자에게 옵션 + 추천 제시, 응답 대기
├─ Tier 2? → 결정 + Phase 5의 PR Decisions 섹션에 1~2줄 근거 메모 준비
└─ Tier 3? → 조용히 가장 단순한 방법으로 결정
Tier 1 질문은 한 번에 묶어서 (mcp_Question 등) 제시한다. 매 결정마다 따로 왕복하지 않는다.
Figma에서 섹션이 나뉘어 있어도 코드에서는 하나의 컴포넌트 + variant가 이 레포의 패턴이다.
분리 기준: 동작/접근성 규칙이 다를 때만 분리. 시각 차이만이면 variant로 통합.
| 체크 | 설명 |
|---|---|
| Figma 값 그대로 | variant 값은 Figma variantOptions 배열의 값을 그대로 사용한다. 예: Figma에서 radius가 ['8px', '16px', 'full']이면 코드에서도 '8px' | '16px' | 'full'로 선언. sm/md/lg 등으로 임의 리네이밍하지 않는다. 어떤 이유로든 변경이 필요하면 반드시 사용자에게 묻는다. |
| HTML 충돌 | type은 <button>의 네이티브 속성. 기존 Button이 이미 type을 쓰므로 새 축은 다른 이름 사용 (예: appearance) |
| 기존 컴포넌트 일관성 | 같은 의미의 축은 같은 이름 사용 (color, size 등) |
| Figma 용어 반영 | Figma에서 ghost라 하면 ghost 사용 (Button의 weak와 다른 개념) |
Figma에서 전체 조합 중 일부만 디자인되어 있으면:
파일을 생성하거나 수정하기 직전에 반드시 현재 브랜치를 확인한다.
git branch --show-current
현재 브랜치 확인
├─ main인가?
│ ├─ YES → "새 브랜치를 만들까요?"
│ │ ├─ 만든다 → 브랜치 이름 선택 (추천 이름 제시)
│ │ └─ 안 만든다 → main에서 바로 작업
│ │
│ └─ NO → "현재 브랜치({name})에서 작업할까요?"
│ ├─ 이 브랜치에서 작업한다 → 진행
│ ├─ main으로 돌아가서 새 브랜치를 만든다 → 브랜치 이름 선택
│ └─ main으로만 돌아간다 → main에서 작업
브랜치 이름 추천 형식: feat/{kebab-name} (예: feat/icon-button)
브랜치 전환 시 주의:
git stash가 아니라 변경사항을 들고 이동한다git checkout -b {new-branch} → 현재 uncommitted 변경사항이 그대로 새 브랜치에 붙는다git checkout main && git checkout -b {new-branch} — unstaged 변경사항은 자동으로 따라온다git stash pop으로 복원한다1. src/recipes/{kebab-name}.ts ← recipe 먼저
2. panda.config.ts ← recipe 등록
3. `pnpm --filter @bubbly-design-system/react codegen` ← styled-system 타입 생성
4. src/components/{kebab-name}/{kebab-name}.tsx ← 컴포넌트
5. src/components/{kebab-name}/index.ts ← 배럴
6. src/index.ts ← 루트 배럴에 추가
7. src/components/{kebab-name}/{kebab-name}.stories.tsx ← 스토리
codegen(3번)을 빼먹으면 styled-system/recipes에서 import 에러가 난다.
전체 빌드는 pnpm --filter @bubbly-design-system/react build로 codegen → bundle → cssgen을 한번에 돌릴 수 있다.
import { defineRecipe } from '@pandacss/dev';
const disabledStyles = {
cursor: 'not-allowed',
backgroundColor: 'surface.disabled',
color: 'content.disabled',
} as const;
export const {camelName}Recipe = defineRecipe({
className: '{kebab-name}',
base: {
display: 'inline-flex',
alignItems: 'center',
justifyContent: 'center',
cursor: 'pointer',
overflow: 'clip',
position: 'relative',
outline: 'none',
border: 'none',
userSelect: 'none',
flexShrink: 0,
transition: 'background-color 150ms ease-out',
_focusVisible: {
boxShadow:
'0 0 0 2px var(--colors-neutral-600), 0 0 0 4px var(--colors-neutral-50)',
},
},
variants: {
// 각 축을 빈 객체로 선언 (스타일은 compoundVariants에서)
},
compoundVariants: [
// 디자인된 조합만 정의
// 순서: 레이아웃 → 색상/시각 → 상태
],
defaultVariants: {
// Figma의 기본 variant 값 그대로
},
});
주의:
base에 공통 스타일만 (모든 variant에 적용되는 것)variants에 축 선언. 축 고유 스타일이 있으면 여기에 (예: size별 icon 크기)compoundVariants에 조합별 색상/padding/border-radius 등'use client';
import { ark } from '@ark-ui/react/factory';
import { type CSSProperties, forwardRef, type ReactNode } from 'react';
import { styled } from 'styled-system/jsx';
import { {camelName} } from 'styled-system/recipes';
const Styled = styled(ark.{htmlElement}, {camelName});
type StyledProps = Parameters<typeof Styled>[0];
export type {PascalName}Props = Omit<StyledProps, 'children'> & {
// 컴포넌트 고유 props (loading, icon 등)
};
export const {PascalName} = forwardRef<HTML{Element}Element, {PascalName}Props>(
function {PascalName}({ /* destructure custom props */ ...props }, ref) {
return (
<Styled ref={ref} {...props}>
{/* children / icon / slot */}
</Styled>
);
},
);
체크리스트:
'use client' 맨 위forwardRef + named function expressionaria-label 같은 접근성 필수 props는 required로ReactNode 타입 (기존 Button 패턴)'--{name}-icon-size': '24px'fontSize: 'var(--{name}-icon-size)' 필수 — @bubbly-design-system/icons는 size 기본값이 1em이므로, fontSize를 설정해야 아이콘이 올바른 크기로 렌더된다import { {camelName}Recipe } from './src/recipes/{kebab-name}';
// theme.recipes에 추가
recipes: {
button: buttonRecipe,
{camelName}: {camelName}Recipe, // key = styled-system/recipes에서의 import 이름
},
컴포넌트 배럴 (src/components/{kebab-name}/index.ts):
export { {PascalName}, type {PascalName}Props } from './{kebab-name}';
루트 배럴 (src/index.ts):
export { {PascalName}, type {PascalName}Props } from './components/{kebab-name}';
import type { Meta, StoryObj } from '@storybook/react';
import { {camelName} } from 'styled-system/recipes';
import { {PascalName} } from './{kebab-name}';
const { variantMap } = {camelName};
const meta: Meta<typeof {PascalName}> = {
title: 'Components/{PascalName}',
component: {PascalName},
argTypes: {
// variantMap에서 control 자동 생성
// variant: { control: 'select', options: variantMap.variant },
},
args: {
// 기본 props
},
};
export default meta;
type Story = StoryObj<typeof {PascalName}>;
export const Default: Story = {};
export const Disabled: Story = { args: { disabled: true } };
// variant 조합 showcase, 상태별 showcase 등
스토리 패턴:
args만 바꿔서 exportrender() 함수에서 variantMap.{axis}.map()으로 매트릭스아이콘 사용:
@bubbly-design-system/icons에서 import한다@bubbly-design-system/icons가 있어야 한다 (없으면 pnpm --filter @bubbly-design-system/react add -D @bubbly-design-system/icons)import { IconArrowRight, IconPlus } from '@bubbly-design-system/icons';기존 컴포넌트를 수정할 때는 아래 흐름을 따른다.
src/recipes/{name}.ts에서 variants 또는 compoundVariants 수정pnpm codegen 실행 → styled-system/recipes/{name}.d.ts 타입 갱신 확인dist/styles.css에서 변경 확인pnpm --filter @bubbly-design-system/react build
성공 기준:
styled-system/recipes/{name}.d.ts — variant 타입 정확styled-system/recipes/{name}.mjs — compound variants 포함dist/styles.css — 클래스 생성됨dist/index.mjs — export 포함됨변경한 모든 파일에 대해:
lsp_diagnostics(filePath, severity="error")
에러 0이어야 한다.
아래 표를 채워서 self-check한다:
| 항목 | Figma 값 | 구현 값 | 일치 |
|---|---|---|---|
| variant 축 이름/값 | |||
| 색상 토큰 매핑 | |||
| padding/size | |||
| border-radius | |||
| hover 동작 | |||
| disabled 동작 | |||
| focus ring |
불일치 항목이 있으면 수정 후 다시 빌드.
pnpm storybook:react
포트 6006에서 Components/{PascalName}으로 시각 확인.
빌드와 LSP가 통과해도 한 번 더 자기 비평. Tier 3 ("조용히 결정")에서 쌓인 의사결정이 과하거나 단순화 여지가 있는지 찾는다.
체크 포인트:
<span> 안에 <span> 같은 중복 래핑<div>인데 의미상 <ul>, <button>, <nav> 등이 맞지 않는가?color: '#...', padding: '4px' 같은 raw 값은 token 매핑으로발견한 것들은 사용자에게 "이 부분 리팩터링할까요?" 형태로 한 번에 묶어 제안한다. 여러 번 리팩터 왕복하지 않는다.
발견 게 없으면 그냥 Phase 5로 진행.
모든 검증이 끝나면 사용자에게 아래 형식으로 결과를 보고한다.
| 파일 | 역할 |
|---|---|
src/recipes/{kebab-name}.ts | Panda CSS recipe (variant 축, compound variants, 기본값) |
src/components/{kebab-name}/{kebab-name}.tsx | React 컴포넌트 (forwardRef, props, 렌더링 로직) |
src/components/{kebab-name}/index.ts | 컴포넌트 배럴 export |
src/components/{kebab-name}/{kebab-name}.stories.tsx | Storybook 스토리 (variant showcase, 상태별 데모) |
| 파일 | 수정 내용 |
|---|---|
panda.config.ts | theme.recipes에 새 recipe 등록 |
src/index.ts | 루트 배럴에 컴포넌트/타입 export 추가 |
| 항목 | 결과 |
|---|---|
pnpm build | exit code 0 |
| LSP diagnostics (변경 파일 전체) | 에러 0 |
styled-system/recipes/{name} 타입 생성 | 확인 |
dist/styles.css 클래스 생성 | 확인 |
dist/index.mjs export 포함 | 확인 |
| Figma 대비 검증 표 | 전 항목 일치 |
pnpm storybook:react
포트 6006 → Components/{PascalName}에서 시각 확인.
완료 보고에 이어 PR 초안을 작성한다. 생성은 사용자 승인 후에만.
커밋 분리 전략:
check-types 스크립트 추가)은 별도 커밋PR 제목: Conventional Commits 형식 (feat(react): ..., fix(react): ...). 레포 CONTRIBUTING.md 참조.
PR 본문 구조 (레포 CONTRIBUTING.md와 일치):
✓ 표기. GitHub task list - [ ]는 쓰지 않음 (PR 리스트에 "n/n" 진행률로 잡혀서 오해 유발)Closes #N, PR은 Follows #N초안을 사용자에게 보여주고 피드백을 받은 뒤 git push + gh pr create 실행. 승인 없이 먼저 PR을 만들지 않는다 (글로벌 AGENTS.md 규칙).
| 함정 | 해결 |
|---|---|
| codegen 안 돌림 → import 에러 | recipe 등록 후 반드시 pnpm codegen 또는 pnpm build |
| Figma rgba를 하드코딩 | 반드시 semantic token으로 변환 |
| Figma 섹션 분리 = 코드 분리? | 아님. 시각 차이만이면 variant로 통합 |
type prop 충돌 | HTML button의 type과 겹침. 기존 Button이 이미 사용 중이므로 새 시각 축은 appearance 등 사용 |
| compound variant 순서 | 나중에 정의된 게 이김. 레이아웃 → 색상 → 특수 순 |
| Figma에 없는 조합 | compound variant 미정의 → base만 적용. 의도적 |
| xsmall 등 Figma 미확인 값 | 추정치 쓰되 검증 표에 "확인 필요" 표시 |
| Figma fill opacity 누락 | fills[].color.a만 보면 안 된다. fills[].opacity (fill 레벨)도 있어서 실제 표현은 color.a × fill.opacity. opacity=0이면 투명, 0.2이면 반투명. strokes도 동일 |
| 컴포넌트 레벨 fills만 추출 | 아이콘/텍스트 색상은 하위 노드(depth 2+)에 있다. 상태별 색상 변화 확인 시 children fills도 재귀적으로 추출 |
borderRadius: 'full' | tokens.ts의 radii.full = 999px. 사용 가능 |
| 스토리에서 인라인 SVG 사용 | @bubbly-design-system/icons에서 import한다. 인라인 SVG placeholder를 쓰지 않는다 |
boxShadow: inset으로 border 구현 | 절대 위치 자식(<img> 등)이 부모의 inset shadow 위에 페인팅되어 border가 보이지 않는다. border가 콘텐츠 위에 보여야 하면 &::after pseudo-element로 구현한다 (position: absolute; inset: 0; borderRadius: inherit; pointerEvents: none; zIndex: 1). Button의 neutral/weak state-layer 패턴 참고 |
recipe base에 backgroundColor 무조건 추가 | Figma에서 특정 variant에서만 fill이 있으면 base에 넣지 않는다. 예: placeholder에서만 배경색이 있고 loading에서는 없는 경우, base에 넣으면 loading 시 합성된 Skeleton이 동색 배경에 묻혀 애니메이션이 안 보인다 |