🎨 실무에서 통하는 디자인 시스템 설계와 Storybook 활용법
React 프로젝트를 진행하다 보면 자연스럽게 드는 생각이 하나 있어요.
“공통 UI 요소가 자꾸 반복되는데, 좀 더 체계적으로 정리할 수 없을까?”
이때 필요한 게 바로 디자인 시스템입니다. 그리고 이를 문서화하고 테스트할 수 있는 최고의 도구는 바로 Storybook이죠.
이번 글에서는 디자인 시스템을 왜 쓰는지부터, 어떻게 구성하면 실무에 유리한지, 그리고 Storybook을 통해 어떻게 문서화하고 협업까지 연결할 수 있는지를 정리해봤어요.
디자인 시스템은 일관된 UI/UX를 제공하기 위한 설계 기준이에요.
예를 들어 팀원들이 만든 버튼이 다 제각각이면 유지보수도 어렵고 사용자 경험도 들쑥날쑥하죠.
이런 문제를 막기 위해 공통 컴포넌트, 스타일 가이드, 디자인 토큰 등을 하나로 정리한 시스템이 필요합니다.
이런 것들을 미리 정리해두면 개발도 빨라지고, 유지보수도 쉬워지고, 협업도 편해집니다.
토큰과 컴포넌트를 분리해두면 규모가 커져도 정리가 잘 돼요.
src/
├── components/ # Button, Input, Card 등 공통 UI 컴포넌트
├── designSystem/
│ ├── tokens/ # 색상, 타이포, 여백 등 디자인 토큰
│ │ ├── colors.js
│ │ ├── spacing.js
│ │ └── typography.js
│ └── index.js # 모든 토큰 모듈화
├── pages/ # 실제 페이지 단위 컴포넌트
└── App.jsx
디자인 토큰은 스타일 기준값을 변수처럼 관리하는 것이에요.
한 번만 정의해두면, 나중에 전체 테마 바꾸기도 편하고, 디자이너 피드백 반영도 훨씬 수월해요.
// designSystem/tokens/colors.js
export const colors = {
primary: "#3B82F6", // Tailwind blue-500
secondary: "#F3F4F6",
danger: "#EF4444",
text: "#1F2937",
};
// designSystem/tokens/typography.js
export const fontSize = {
sm: "0.875rem",
base: "1rem",
xl: "1.25rem",
};
variant, icon, disabled 같은 props도 추가해두면 더 유연한 컴포넌트가 됩니다.
// components/Button.jsx
import { colors } from "../designSystem/tokens/colors";
export default function Button({ label, onClick, variant = "primary" }) {
const style = {
backgroundColor: colors[variant],
color: "#fff",
padding: "8px 16px",
borderRadius: "8px",
fontSize: "0.875rem",
};
return <button onClick={onClick} style={style}>{label}</button>;
}
Storybook은 컴포넌트를 독립적으로 개발하고 테스트할 수 있도록 해주는 도구예요.
디자이너, 기획자, QA가 개발 서버를 보지 않고도 UI 상태를 확인할 수 있게 해주죠.
Docs 탭, Controls, Canvas를 통해 컴포넌트의 상태와 props를 바로 확인하고 테스트할 수 있어요.
Storybook에서는
npx storybook init
npm run storybook
// Button.stories.jsx
import Button from "./Button";
export default {
title: "Components/Button",
component: Button,
};
export const Primary = {
args: {
label: "확인",
variant: "primary",
},
};
npm run build-storybook
이렇게 하면 디자이너가 디자인을 바꾸면, 바로 코드에 반영되도록 자동화할 수 있어요.
처음엔 ‘왜 굳이 이렇게까지 해야 해?’ 싶을 수 있지만,
컴포넌트가 많아지고, 팀원이 늘어나고, 유지보수를 하게 될수록 디자인 시스템의 필요성을 절실히 느낍니다.
작은 프로젝트부터라도 토큰 하나, 버튼 하나부터 시작해보세요.
다음 글에서는 실제로 디자인 토큰을 자동 변환하고, Storybook을 GitHub Pages에 배포하는 과정을 공유할게요!
👉다음 글 : Express 기반 유튜버 API 프로젝트