Storybook SoT 전략

05. Storybook 중심 Single Source of Truth 전략

전략 개요

Storybook(코드 컴포넌트 카탈로그) 을 디자인 시스템의 SoT로 두고, Figma는 그 코드 컴포넌트의 시각 명세/스펙 미러로 사용하는 전략입니다. "코드가 진실이다"라는 원칙을 가장 강하게 적용한 전략.

[React Components Repo]
        │
        ▼
[Storybook (배포된 카탈로그)]
        │
        ├─→ Chromatic (시각 회귀 테스트)
        ├─→ Figma "Story" 플러그인으로 임베드
        └─→ Code Connect 매핑
                │
                ▼
        [Figma Library Components]
        (코드 컴포넌트와 1:1 매핑된 스펙)
Plain Text
복사

핵심 도구

•

Storybook 7+

•

Chromatic: Storybook 호스팅 + 시각 회귀

•

Figma Code Connect: Figma 컴포넌트  코드 컴포넌트 매핑

•

story.to.design 또는 html.to.design: Storybook → Figma 자동 변환

•

Figma Storybook Connect 플러그인

적용 시나리오

•

개발자 주도 조직, 코드 우선 문화

•

컴포넌트 단위 재사용성이 매우 중요한 제품 (B2B SaaS, 대시보드)

•

시각 회귀 테스트가 중요한 환경

•

디자이너가 코드 컴포넌트를 신뢰하고 사용할 의지가 있음

단계별 워크플로

1) Storybook 셋업

npx storybook@latest init
Bash
복사

모든 컴포넌트마다 *.stories.tsx 작성:

export default { component: Button } satisfies Meta<typeof Button>
export const Primary: Story = { args: { variant: 'primary', children: 'Click' } }
export const Secondary: Story = { args: { variant: 'secondary', children: 'Click' } }
TypeScript
복사

2) Chromatic 배포

•

Chromatic 가입 → 토큰 발급

•

GitHub Actions로 PR마다 자동 배포 + 시각 회귀 검증

3) Figma Code Connect 매핑

button.figma.tsx:

import { Button } from './Button'
import figma from '@figma/code-connect'

figma.connect(Button, '<https://figma.com/>...?node-id=1-2', {
  props: {
    variant: figma.enum('Variant', { Primary: 'primary', Secondary: 'secondary' }),
    label: figma.string('Label'),
  },
  example: ({ variant, label }) => <Button variant={variant}>{label}</Button>,
})
TypeScript
복사

npx figma connect publish
Bash
복사

4) Figma에 Storybook 임베드

•

디자이너가 Figma에서 Story URL을 임베드 노드로 추가

•

항상 최신 코드 컴포넌트 시각 확인 가능

5) story.to.design으로 Figma 컴포넌트 자동 생성 (선택)

•

Storybook 스토리 → Figma 컴포넌트 자동 변환

•

디자이너가 그릴 필요 없이 Figma Library가 항상 최신

운영 규칙

•

컴포넌트 추가/변경은 코드에서만 → Storybook PR

•

디자이너는 Figma에서 컴포넌트를 인스턴스로만 사용 (직접 그리기 금지)

•

Code Connect 매핑이 없는 컴포넌트는 사용 금지

•

Storybook이 빨간색이면 Figma도 잠금 (배포 게이트)

장점

•

디자인-코드 1:1 매핑 보장 (Code Connect)

•

시각 회귀 테스트로 회귀 사고 방지

•

디자이너가 항상 "동작 가능한 컴포넌트" 사용

•

신규 입사자 온보딩 자료로 최강 (Storybook 한 곳에 다 있음)

한계

•

초기 구축 비용 매우 큼

•

디자이너 자유도 ↓ (정해진 컴포넌트만 사용 가능)

•

디자인 탐색 단계(스케치, 와이어프레임)와 안 맞음

•

Code Connect 매핑 유지보수 부담

Figma Make / MCP와의 결합

•

Make는 PoC/탐색 단계에서만 사용 → Storybook 컴포넌트로 이관 후 본격 사용

•

MCP가 코드 생성 시 Storybook 컴포넌트만 import하도록 프롬프트 강제

•

AI가 새 컴포넌트 만들기 전에 Storybook에 유사 컴포넌트 검색하도록 지시