본문으로 건너뛰기

Storybook으로 디자이너와 개발자 협업 시작하기

· 약 5분
Braun Park
Braun Park
Curious Developer

이번에 새로운 디자이너님과 협업을 하게 되었는데, 초기 단계부터 시작하는 거라서 처음부터 디자인 시스템을 잡고 가기로 했습니다.

이전 프로젝트에서 경험했던 문제들:

  • 디자이너: "개발자들이 피그마와 다르게 구현해요"
  • 개발자: "디자인이 개발 중에 자주 바뀌어요"
  • 공통: 스크린샷 주고받기, 반복적인 확인 과정
  • 결과: 소통 비용 증가, 일관성 부족

그래서 이번에는 다르게 접근하기로 했습니다: 처음부터 Storybook으로 디자인 시스템을 구축하고, 체계적인 협업 프로세스를 만들어보기로 했습니다.

이 포스트에서는 Next.js에서 Storybook을 설치하고 디자이너와 협업하기 위한 초기 세팅 과정을 공유하겠습니다.

🎯 Storybook 도입 계획과 기대 효과​

해결하고 싶은 문제들:

  • 디자인-개발 간 소통 비용 최소화
  • 컴포넌트 일관성 확보
  • 실시간 디자인 리뷰 환경 구축

기대하는 효과:

  • 피드백 시간 단축 (스크린샷 공유 → 실시간 확인)
  • 디자인 일관성 향상 (통합 컴포넌트 라이브러리)
  • 개발 효율성 증대 (컴포넌트 재사용)

🚀 Next.js 프로젝트에 Storybook 설정하기​

1. Storybook 설치​

# Next.js 프로젝트 루트에서
npx storybook@latest init

Next.js를 자동 감지하고 필요한 설정을 완료해줍니다.

2. Styled-Components 연동​

컴포넌트별 스타일 캡슐화로 디자이너가 직관적으로 이해할 수 있습니다:

npm install styled-components
npm install --save-dev @storybook/addon-styled-components babel-plugin-styled-components

테마 설정​

// src/styles/theme.js
export const theme = {
  colors: {
    primary: '#007bff',
    secondary: '#6c757d',
    success: '#28a745',
    danger: '#dc3545',
    gray: {
      100: '#f8f9fa',
      300: '#dee2e6',
      500: '#6c757d',
      900: '#212529'
    }
  },
  spacing: {
    xs: '4px',
    sm: '8px',
    md: '16px',
    lg: '24px',
    xl: '32px'
  },
  breakpoints: {
    mobile: '0px',
    tablet: '768px',
    desktop: '1024px'
  },
  // 미디어 쿼리 헬퍼
  media: {
    tablet: '@media (min-width: 768px)',
    desktop: '@media (min-width: 1024px)'
  }
};

3. 반응형 설정​

3단계 브레이크포인트로 설정:

// .storybook/preview.js
export const parameters = {
  viewport: {
    viewports: {
      mobile: {
        name: 'Mobile',
        styles: { width: '375px', height: '812px' }
      },
      tablet: {
        name: 'Tablet',
        styles: { width: '768px', height: '1024px' }
      },
      desktop: {
        name: 'Desktop',
        styles: { width: '1280px', height: '800px' }
      }
    }
  }
};

🎨 디자이너 친화적인 컴포넌트 스토리 작성​

Button 컴포넌트 예시​

// src/components/Button.jsx
import styled from 'styled-components';

const StyledButton = styled.button`
  padding: ${props => props.theme.spacing.sm} ${props => props.theme.spacing.md};
  font-size: ${props => props.theme.typography.fontSize.sm};
  border: none;
  border-radius: 6px;
  cursor: pointer;
  transition: all 0.2s ease;

  /* 크기별 스타일 */
  ${props => props.size === 'small' && `
    padding: ${props.theme.spacing.xs} ${props.theme.spacing.sm};
  `}

  ${props => props.size === 'large' && `
    padding: ${props.theme.spacing.md} ${props.theme.spacing.lg};
    font-size: ${props.theme.typography.fontSize.lg};
  `}

  /* 변형별 스타일 */
  ${props => props.variant === 'primary' && `
    background-color: ${props.theme.colors.primary};
    color: white;
    &:hover { background-color: #0056b3; }
  `}

  /* 반응형 */
  ${props => props.theme.media.tablet} {
    padding: ${props => props.theme.spacing.md} ${props => props.theme.spacing.lg};
  }
`;

export default function Button({
  variant = 'primary',
  size = 'medium',
  children,
  ...props
}) {
  return (
    <StyledButton variant={variant} size={size} {...props}>
      {children}
    </StyledButton>
  );
}

디자이너가 조작하기 쉬운 스토리​

// src/components/Button.stories.js
export default {
  title: 'Components/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    variant: {
      description: '버튼의 스타일 변형',
      control: 'select',
      options: ['primary', 'secondary']
    },
    size: {
      description: '버튼의 크기',
      control: 'select',
      options: ['small', 'medium', 'large']
    }
  }
};

export const Primary = {
  args: {
    variant: 'primary',
    children: '확인'
  }
};

export const AllSizes = {
  render: () => (
    <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
      <Button size="small">작은 버튼</Button>
      <Button size="medium">보통 버튼</Button>
      <Button size="large">큰 버튼</Button>
    </div>
  )
};

🔗 피그마와 Storybook 연동하기​

피그마 애드온 설치​

npm install --save-dev @storybook/addon-design

피그마 링크 연동​

각 컴포넌트의 피그마 링크를 연결하면 Design 탭에서 원본 디자인과 구현을 나란히 비교할 수 있습니다:

// Button.stories.js
export default {
  title: 'Components/Button',
  component: Button,
  parameters: {
    design: {
      type: 'figma',
      url: 'https://www.figma.com/file/ABC123/Design-System?node-id=123%3A456'
    }
  }
};

👥 계획하고 있는 협업 워크플로우​

1. 디자이너 온보딩 계획​

디자이너분께 전달할 예정인 가이드:

🔗 스토리북 링크: https://your-storybook.web.app

📖 사용법:
- 좌측 메뉴에서 컴포넌트 선택
- Controls 패널에서 속성값 실시간 변경 가능
- 우측 상단에서 모바일/태블릿/데스크톱 뷰 전환
- Design 탭에서 피그마 원본과 비교

피드백 주시면 바로 반영하겠습니다!

2. 디자인 토큰 정리 요청 계획​

체계적인 협업을 위해 디자이너에게 요청할 예정인 정리 항목:

🎨 컬러 팔레트:

  • Primary, Secondary 색상
  • Success, Warning, Error 색상
  • Gray 스케일 (100, 200, 300, 500, 900)

📝 타이포그래피:

  • 폰트 패밀리
  • 폰트 크기 (Small, Medium, Large)
  • 폰트 굵기

📏 스페이싱:

  • 기본 간격 단위 (4px, 8px, 16px, 24px...)

3. 제안하는 피드백 프로세스​

앞으로 이런 방식으로 협업하려고 합니다:

  1. 컴포넌트 개발 완료 → 스토리북 자동 배포
  2. 지라 티켓 생성 → 스토리북 링크와 함께 리뷰 요청
  3. 디자이너 리뷰 → Controls로 직접 테스트
  4. 지라 댓글로 구체적인 피드백:
    • 어떤 컴포넌트의 어떤 상태에서
    • 어떤 부분이 수정 필요한지
    • 스크린샷과 함께
  5. 개발자 수정 후 → 지라에서 재검토 요청

이렇게 하면 피드백이 체계적으로 관리되고, 나중에 히스토리 추적도 쉬울 것 같습니다.

💡 협업을 위한 준비 사항​

디자이너분을 위한 계획​

  1. 부담스럽지 않게 시작: 처음에는 화면 공유로 사용법 설명 예정
  2. 구체적인 가이드: 어떤 부분을 확인해야 하는지 명확히 안내할 예정
  3. 점진적 자율성: 익숙해지면 혼자서도 확인할 수 있도록 지원할 계획

개발 시 고려할 사항들​

  1. 피그마 Dev Mode 적극 활용: 정확한 수치와 CSS 코드 추출
  2. 실시간 비교: 스토리북과 피그마를 나란히 두고 픽셀 퍼펙트 구현
  3. 체계적인 네이밍: 디자이너가 이해하기 쉬운 컴포넌트명과 props명 사용

간단한 예제 공유​

현재 Storybook에 간단한 Button 컴포넌트를 구현해서 디자이너분과 공유했습니다.

앞으로 이런 식으로 각 컴포넌트를 하나씩 구축해가며 디자인 시스템을 완성해나갈 예정입니다.

📝 마무리​

이번 포스트에서는 Storybook을 처음 도입하는 과정과 앞으로의 협업 계획을 정리해봤습니다.

아직 초기 단계이지만, 소통의 효율성을 높이고 일관성 있는 디자인 시스템을 구축하는 것이 목표입니다.

지금까지의 진행상황​

  1. Storybook 기본 설치: Next.js + styled-components 환경 구성 완료
  2. 피그마 애드온 설정: 디자인과 구현을 비교할 수 있는 환경 준비
  3. 간단한 예제: Button 컴포넌트로 첫 공유 완료
  4. 협업 프로세스 설계: 지라 기반 피드백 시스템 계획

앞으로의 계획​

  • 디자이너분과 함께 디자인 토큰 정리
  • 주요 컴포넌트들 하나씩 스토리북으로 구현
  • 지라를 통한 체계적인 피드백 프로세스 적용
  • 점진적으로 디자인 시스템 완성

아직 도입 효과를 측정하기는 이르지만, 체계적인 접근으로 더 나은 협업 환경을 만들어가려고 합니다.

혹시 Storybook으로 디자이너와 협업해본 경험이 있으시다면 댓글로 팁을 공유해주세요! 🚀