React Native, Web 크로스 플랫폼 디자인 시스템 Storybook 구축하기

📒 React Native, Web 크로스 플랫폼 디자인 시스템 Storybook 구축하기

---

React Native로 앱을 만들고, 같은 디자인을 웹앱에도 적용해야 하는 상황이 반복 되어, 팀과 함께 react-native-web 기반의 크로스 플랫폼 디자인 시스템을 만들었습니다.  컴포넌트는 잘 나왔는데, 문제가 하나 있었습니다.

 
22개 컴포넌트가 전부 Compound Component(합성 컴포넌트) 패턴이라 "어떻게 조합해서 쓰는 건데?"라는 질문에 코드만 보여주기엔 한계가 있었습니다. 결국 Storybook을 직접 셋업했고, 그 과정에서 webpack 설정과 꽤 오래 싸웠습니다. 그 경험을 공유해보려 합니다.
 
환경 정보

• React Native, Expo
• Storybook 8.6.4 (@storybook/react-webpack5)
• react-native-web 0.19.10
• @storybook/addon-react-native-web 0.0.27
• Yarn Workspaces (모노레포)

 

📌 왜 크로스 플랫폼 디자인 시스템이 필요했는가

앱 내에서 웹뷰를 통한 웹앱 기능이 점점 늘어나고 있었습니다. 앱은 React Native로, 웹앱은 별도로 만들면 같은 디자인 스펙인데 구현이 두 벌이 됩니다. 디자인 불일치는 당연하고, 수정사항 반영도 두 번 해야 하죠.
 

react-native-web이 이 문제를 해결해줬습니다. React Native 컴포넌트를 그대로 웹에서 렌더링할 수 있으니, 디자인 시스템을 하나만 만들면 앱과 웹 둘 다 쓸 수 있었습니다. 실제로 Expo Web(expo-web)으로 웹앱 프로젝트를 구축하고 디자인 시스템을 적용하니, 앱 내 웹앱 기능 개발 시간이 꽤 줄었습니다.

 
디자인 시스템 자체는 팀이 함께 개발했습니다. 22개 컴포넌트, 12개 커스텀 훅, 5개 Context Provider까지 구조가 잘 잡혔는데, 문서화 환경은 없었습니다.
 

Compound Component 패턴 특성상 Button.Label, Button.Icon 같은 서브 컴포넌트를 어떻게 조합하는지 시각적으로 보여주는 환경이 필요했습니다.

 

📌 왜 React Native Storybook이 아니라 Storybook Web인가

🔎 처음엔 React Native Storybook으로 시작

처음 떠올린 건 당연히 @storybook/react-native였습니다. React Native 프로젝트니까 RN용 Storybook을 쓰는 게 자연스럽죠.

그런데 실제로 써보니 불편함이 있었습니다. 컴포넌트를 확인하려면 시뮬레이터를 실행하거나 실제 핸드폰을 연결해야 합니다. 브라우저에서 바로 열어볼 수가 없으니, 코드 수정 → 확인 → 수정의 피드백 루프가 느려집니다.
 

🔎 기존 Storybook 기능의 부재

더 큰 문제는 웹 Storybook에서 당연히 쓸 수 있는 기능들이 RN 버전에서는 빠져있거나 제한적이라는 점이었습니다.

• Controls 패널에서 props를 실시간으로 바꿔보기
• Docs 모드에서 MDX로 인터랙티브 문서 만들기
• Canvas에서 소스 코드와 렌더 결과를 나란히 보기

디자인 시스템 문서화에는 이런 기능들이 핵심인데, RN Storybook에서는 addon 생태계가 웹 대비 부족했습니다.
팀 전체가 브라우저에서 컴포넌트를 바로 확인하고, 링크 하나로 공유할 수 있어야 했습니다.
 

🔎 Storybook Web + react-native-web 조합 선택

이미 react-native-web이 프로젝트에 있으니, RN 컴포넌트를 웹에서 렌더링하는 건 가능한 상태였습니다. 여기에 @storybook/addon-react-native-web이 브릿지(Bridge) 역할을 해줍니다. React Native의 View, Text, Pressable 같은 컴포넌트를 react-native-web으로 변환해서, Storybook의 Webpack5 환경에서 렌더링할 수 있게 해주는 addon입니다.

결과적으로 웹 Storybook의 모든 기능(Controls, Docs, Canvas, addon 생태계)을 그대로 쓰면서 RN 컴포넌트를 렌더링할 수 있게 됐습니다.
 

📌 Storybook 환경 구성

🔎 모노레포 구조와 Storybook 위치

프로젝트는 Yarn Workspaces로 모노레포를 구성했습니다. 루트에 디자인 시스템 라이브러리, example/ 디렉토리에 Expo 예제 앱과 Storybook이 함께 들어있는 구조입니다.

design-system/              ← 루트: 디자인 시스템 라이브러리
├── src/                    ← 컴포넌트, 훅, 테마
├── example/                ← Expo 예제 앱 + Storybook
│   ├── .storybook/         ← Storybook 설정
│   ├── src/stories/        ← 스토리 파일 (.stories.tsx, .mdx)
│   └── package.json
└── package.json            ← workspaces: ["example"]

네이티브 개발은 Metro 번들러(포트 8081)로, Storybook은 Webpack5(포트 6006)로 각각 독립적으로 실행됩니다. 루트 package.json에서 workspace 스크립트로 연결해두면 편합니다.

{
  "scripts": {
    "storybook": "yarn workspace example storybook",
    "build-storybook": "yarn workspace example build-storybook"
  }
}

 

🔎 핵심 설정: .storybook/main.ts

Storybook의 진입점인 main.ts입니다. 프레임워크는 @storybook/react-webpack5를 사용하고, 핵심은 addon 구성입니다.

import type { StorybookConfig } from "@storybook/react-webpack5";

const config: StorybookConfig = {
  stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
  addons: [
    "@storybook/addon-webpack5-compiler-babel",
    "@storybook/addon-essentials",
    "@storybook/addon-interactions",
    "@storybook/addon-react-native-web", // RN → 웹 브릿지
    "@storybook/addon-react-native-server",
    "storybook-addon-deep-controls", // 중첩 props 제어
    "@storybook/addon-docs",
  ],
  framework: "@storybook/react-webpack5",
  // ... webpack 커스터마이징은 아래 섹션에서
};

여기서 핵심은 @storybook/addon-react-native-web입니다. 이 addon이 없으면 React Native의 View, Text 같은 컴포넌트를 Webpack이 해석하지 못합니다.

storybook-addon-deep-controls도 디자인 시스템에서는 유용했습니다. Compound Component 패턴 특성상 중첩된 객체 형태의 props가 많은데, 기본 Controls 패널로는 이를 제어할 수 없습니다. 이 addon이 중첩 props를 펼쳐서 각각 개별 컨트롤로 보여줍니다.

 

🔎 디자인 시스템 Provider로 스토리 감싸기: preview.tsx

디자인 시스템의 모든 컴포넌트는 최상위 Provider 안에서 동작합니다. 테마, 아이콘 에셋, 설정값을 Context로 제공하는 Provider인데, Storybook 스토리에서도 이걸 감싸줘야 합니다.

import { DSProvider, ToastProvider } from "my-design-system";
import { icons, illustrations } from "my-design-asset";
import { View } from "react-native";

const preview: Preview = {
  decorators: [
    (Story: any) => (
      <DSProvider
        assets={{
          icons: icons,
          illustrations: illustrations,
        }}
      >
        <View style={{ flexDirection: "row", justifyContent: "center" }}>
          <View style={{ width: 400 }}>
            <Story />
          </View>
        </View>
        <ToastProvider />
      </DSProvider>
    ),
  ],
};

400px 너비의 컨테이너로 감싸서 모바일 뷰를 시뮬레이션합니다. Provider에 아이콘 에셋을 넘기는 것도 잊으면 안 됩니다. 안 넘기면 Icon 컴포넌트가 전부 에러를 뱉습니다.
 

📌 Webpack 커스터마이징

addon 설치하고 스토리 파일 몇 개 만들면 끝날 줄 알았습니다. 현실은 webpackFinal 설정을 꽤 만져야 했습니다.

🔎 SVG 처리 파이프라인

React Native에서는 react-native-svg-transformer로 SVG를 컴포넌트로 변환합니다. Metro 번들러가 이걸 처리하죠. 그런데 Storybook은 Webpack5를 사용하니, SVG 처리 파이프라인을 별도로 구성해야 합니다.

먼저 기존 이미지 룰에서 SVG를 제외하고, @svgr/webpack으로 SVG를 React 컴포넌트로 변환하는 룰을 추가합니다. 여기에 string-replace-loader를 체이닝해서 하드코딩된 색상 값을 동적 테마용으로 치환합니다.

webpackFinal: async (config) => {
  // 기존 이미지 룰에서 SVG 제외
  const imageRule = config.module?.rules?.find(
    (rule) => rule && typeof rule === "object" && rule.test instanceof RegExp && rule.test.test(".svg")
  );
  if (imageRule && typeof imageRule === "object") {
    imageRule.exclude = /\.svg$/;
  }

  // SVG → React 컴포넌트 변환 + 색상 치환
  config.module?.rules?.push({
    test: /\.svg$/,
    use: [
      { loader: "@svgr/webpack", options: { svgo: false } },
      {
        loader: "string-replace-loader",
        options: {
          search: "#222222",
          replace: "current",
          flags: "g",
        },
      },
    ],
  });

  return config;
};

#222222를 current로 치환하는 이유는 아이콘의 fill 색상을 런타임에서 테마 컬러로 동적 변경하기 위해서입니다. SVG 원본에 하드코딩된 색상이 남아있으면 테마가 적용되지 않습니다.

 

🔎 Node.js 폴리필 문제

Storybook을 처음 실행하면 tty와 os 모듈을 찾을 수 없다는 에러가 납니다. 이 모듈들은 Node.js 내장 모듈인데, Webpack5부터는 브라우저 환경에서 Node.js 폴리필을 자동으로 포함하지 않습니다.

config.resolve.fallback = {
  ...config.resolve.fallback,
  tty: require.resolve("tty-browserify"),
  os: require.resolve("os-browserify/browser"),
};

tty-browserify와 os-browserify를 devDependencies에 설치하고 fallback으로 연결하면 해결됩니다.

 

🔎 모노레포 모듈 해석 문제

디자인 시스템이 참조하는 에셋 패키지에서 문제가 발생했습니다. 해당 패키지의 package.json에 exports 필드가 정의되어 있는데, Webpack이 이를 해석하는 과정에서 모듈을 제대로 찾지 못했습니다.

// 직접 파일 경로로 alias 우회
config.resolve.alias = {
  ...(config.resolve.alias || {}),
  "my-design-asset": path.resolve(__dirname, "../node_modules/my-design-asset/dist/index.js"),
};

exports 필드를 우회해서 빌드 산출물의 실제 파일 경로로 직접 매핑하는 방식입니다. 모노레포 환경에서 패키지 간 참조 시 이런 문제가 자주 발생합니다.

 

📌 플랫폼별 차이를 넘어서

React Native 컴포넌트를 웹에서 렌더링하면 "대부분은" 잘 동작합니다. 하지만 플랫폼 간 동작이 다른 영역이 있고, 디자인 시스템에서는 이걸 .web.tsx 파일로 분리해서 해결했습니다.

 

🔎 .web.tsx 전략

Metro 번들러와 Webpack 모두 플랫폼별 파일 해석을 지원합니다. LinearGradient.tsx와 LinearGradient.web.tsx가 있으면, 웹 환경에서는 자동으로 .web.tsx를 가져옵니다.

네이티브 (LinearGradient.tsx): react-native-linear-gradient 라이브러리 사용

웹 (LinearGradient.web.tsx): CSS linear-gradient 사용

// LinearGradient.web.tsx
const LinearGradient: React.FC<LinearGradientProps> = ({ gradient, direction = "horizontal", children }) => {
  const cssGradient = useMemo(() => {
    const colors = gradients[gradient].join(", ");
    switch (direction) {
      case "horizontal":
        return `linear-gradient(to right, ${colors})`;
      case "vertical":
        return `linear-gradient(to bottom, ${colors})`;
      default:
        return `linear-gradient(to right, ${colors})`;
    }
  }, [gradient, direction]);

  return (
    <div style={{ backgroundImage: cssGradient }}>
      <View>{children}</View>
    </div>
  );
};

Modal도 마찬가지입니다.
 

네이티브에서는 React Native의 Modal 컴포넌트를 쓰지만, 웹에서는 createPortal로 document.body에 렌더링합니다. 바텀시트(BottomSheet)의 웹 버전에서는 window.innerHeight가 문제였습니다. 레이아웃 로드 전에 JS가 실행되면 높이 값이 0으로 잡히기 때문에, fallback 처리가 필요했습니다.

 

const getWindowHeight = () => {
  // 레이아웃 로드 전 JS가 실행되면 window.innerHeight가 0
  if (typeof window !== "undefined" && window.innerHeight > 0) {
    return window.innerHeight;
  }
  return Dimensions.get("window").height || 800;
};

 

🔎 애니메이션 호환성

React Native의 Animated API에서 useNativeDriver: true 옵션은 애니메이션을 네이티브 스레드에서 실행합니다. 성능이 좋죠. 그런데 웹에서는 네이티브 드라이버가 없습니다. useNativeDriver: true를 그대로 두면 크래시가 납니다.

// usePressAnimation.ts
const supportsNativeDriver = (type: AnimationTypes) => {
  const supportedAnimations: AnimationTypes[] = ["scale", "opacity", "rotate"];
  return supportedAnimations.includes(type) && Platform.OS !== "web";
};

// 애니메이션 실행 시 조건부 적용
Animated.timing(animationValue, {
  toValue,
  duration: config.duration,
  easing: config.easing,
  useNativeDriver: supportsNativeDriver(type),
}).start();

Platform.OS !== 'web' 한 줄로 분기하는 간단한 해결책입니다. 웹에서는 JS 스레드 애니메이션으로 fallback되지만, Storybook 문서화 용도로는 충분합니다.

 

🔎 Icon 컴포넌트의 SVG gradient ID 충돌

이건 Storybook 특유의 문제였습니다. 한 페이지에 같은 그래픽 아이콘을 여러 개 렌더링하면 SVG 내부의 linearGradient ID가 중복되어 색상이 꼬이는 현상이 발생했습니다.

 

원인은 SVG의 gradient 정의가 <defs> 안에서 고정된 ID를 사용하기 때문입니다. 같은 SVG가 두 번 렌더링되면 같은 ID가 두 개가 되고, 브라우저는 먼저 찾은 것을 참조합니다.

// gradient ID 충돌 해결
const uniqueId = useId();
const suffix = uniqueId.replace(/:/g, "_");
const idMap = new Map<string, string>();

// 모든 gradient 정의 요소의 ID에 고유 suffix 추가
const defsElements = svg.querySelectorAll("linearGradient, radialGradient, pattern, clipPath, mask, filter");
defsElements.forEach((el: Element) => {
  const oldId = el.getAttribute("id");
  if (oldId) {
    const newId = `${oldId}_${suffix}`;
    idMap.set(oldId, newId);
    el.setAttribute("id", newId);
  }
});

// url(#oldId) 참조도 새 ID로 업데이트
const allElements = svg.querySelectorAll("*");
allElements.forEach((el: Element) => {
  ["fill", "stroke", "clip-path", "mask", "filter"].forEach((attr) => {
    const value = el.getAttribute(attr);
    if (value?.includes("url(#")) {
      const match = value.match(/url\(#([^)]+)\)/);
      if (match?.[1] && idMap.has(match[1])) {
        el.setAttribute(attr, `url(#${idMap.get(match[1])})`);
      }
    }
  });
});

React의 useId() 훅으로 인스턴스마다 고유한 suffix를 생성하고, 렌더링 후 SVG DOM을 순회하면서 모든 ID와 url(#) 참조를 일괄 교체합니다. Storybook처럼 한 화면에 같은 아이콘이 여러 번 나타나는 환경에서 필요한 처리였습니다.

 

📌 스토리 작성 패턴

Webpack 설정을 넘기고 나면, 스토리 작성은 비교적 수월합니다.
 

🔎 Compound Component 스토리

디자인 시스템의 모든 컴포넌트가 Compound Component 패턴이라, 스토리에서 조합 방식을 보여주는 게 핵심입니다.

// Button.stories.tsx
const meta: Meta<typeof Button> = {
  title: "Components/Button",
  component: Button,
  argTypes: {
    variant: {
      control: "select",
      options: ["primary", "secondary", "disabled"],
      description: "버튼의 스타일 변형을 설정합니다.",
    },
    size: {
      control: "select",
      options: ["lg", "md", "sm"],
    },
    isLoading: { control: "boolean" },
  },
};

export const WithIcon: Story = {
  render: (args) => (
    <Button {...args}>
      <View style={{ flexDirection: "row", alignItems: "center" }}>
        <Button.Icon name="add-user" />
        <Button.Label>추가하기</Button.Label>
      </View>
    </Button>
  ),
};

Button 안에 Button.Icon과 Button.Label을 어떻게 조합하는지 시각적으로 보여줍니다. argTypes로 테마, 크기, 로딩 상태를 Controls 패널에서 실시간으로 바꿔볼 수 있습니다.

 

🔎 MDX 문서화

스토리만으로는 "이 컴포넌트를 어떻게 쓰는 거야?"라는 질문에 충분하지 않습니다. @storybook/addon-docs를 추가하면 MDX 파일로 인터랙티브 문서를 만들 수 있습니다. @storybook/blocks에서 제공하는 Canvas(렌더 결과 + 소스 코드)와 Controls를 한 페이지에 배치하는 방식입니다.

import { Canvas, Controls } from "@storybook/blocks";
import * as ButtonStories from "./Button.stories";

# Button

기본적인 형태의 버튼 컴포넌트입니다.
각 요소들을 조합해 다양한 형태의 버튼을 만들 수 있습니다.

## `<Button />` (Button.Container)

<Canvas of={ButtonStories.Default} sourceState="shown" />
<Controls of={ButtonStories.Default} />

## Snippet

VSCode에서 아래 명령어를 입력하여 사용할 수 있습니다.

sourceState='shown'으로 소스 코드를 기본 펼침 상태로 보여줍니다. 컴포넌트의 렌더 결과, 소스 코드, props 컨트롤이 한 눈에 들어오니 별도의 README 없이도 팀원이 바로 사용할 수 있습니다.

추가로, VSCode 스니펫도 같은 페이지에 문서화해서 button-label-only 같은 스니펫 명령어를 바로 확인할 수 있게 했습니다.

 

🔎 스토리 문서 작성 자동화

스토리와 MDX 문서의 구조는 컴포넌트마다 거의 동일합니다.
 
`meta` 정의, `argTypes` 설정, 렌더 함수, MDX의 `Canvas`/`Controls` 배치까지 패턴이 반복되죠. 22개 컴포넌트에 대해 이걸 매번 수동으로 작성하는 건 반복 작업이었습니다. 그래서 Claude Code 스킬(Skill)을 만들어 자동화했습니다.
 
컴포넌트의 props 타입과 서브 컴포넌트 구조를 읽어서 `.stories.tsx`와 `.mdx` 파일을 자동 생성하는 방식입니다. 컴포넌트를 수정했을 때도 스킬을 실행하면 문서가 같이 업데이트되니, 코드와 문서가 따로 노는 상황을 줄일 수 있었습니다.
 

📌 Docs 모드로 가볍게 빌드하기

Storybook은 프론트 개발자만 보는 도구가 아닙니다. 디자인팀과도 공유되는 문서이기도 하죠.
 
앞서 MDX 문서화 섹션에서 봤듯이, 하나의 MDX 파일에 컴포넌트의 렌더 결과, 소스 코드, Controls, 스니펫까지 전부 담아뒀습니다. 컴포넌트 하나에 필요한 정보가 MDX 한 페이지에 다 들어있으니, 굳이 풀 인터랙티브 Storybook을 빌드할 필요가 없었습니다.
 

storybook build --docs 명령어를 사용하면 이 MDX 문서 페이지만 정적으로 빌드합니다. 산출물이 가볍고, 정적 HTML이라 별도 서버 없이 어디든 호스팅할 수 있습니다. 디자이너도 브라우저에서 컴포넌트가 실제로 어떻게 렌더링되는지, 어떤 variant가 있는지 바로 확인할 수 있습니다.

 

---

 
쓰다 보니 Storybook 세팅 하나에 webpack config, SVG 파이프라인, 폴리필, 모듈 해석, 플랫폼별 분기까지 건드린 게 꽤 많았다는 걸 새삼 느낍니다. 돌이켜보면 하나하나는 큰 문제가 아니었는데, 처음 만나면 원인을 찾기가 쉽지 않은 것들이었습니다.
 

그래도 확실한 건, Compound Component 패턴으로 만든 디자인 시스템에서 Storybook의 예제와 시각화 자료가 개발에 큰 도움이 되었다는 점입니다. 코드만 봐서는 Button.Label과 Button.Icon을 어떻게 조합하는지 감이 안 오지만, Storybook에서 렌더 결과와 소스 코드를 나란히 보면 바로 이해가 됩니다. React Native 프로젝트에 Storybook 도입을 고민 중이라면 꼭 시도해보시길 권합니다.