[Storybook] Storybook MDX 마크다운으로 템플릿 작성하기

 

최근 사내 디자인 시스템을 개발하면서 Stroybook을 활용하여 컴포넌트 문서화를 진행하고 있다. 마크다운 파일에서 직접 jsx, tsx를 활용할 수 있는 MDX를 활용하여 문서를 작성하고 있는데

 

무엇보다 익숙한 마크다운 문법과 컴포넌트 코드를 분리할 수 있다는 장점을 활용할 수 있어 개별 컴포넌트마다 MDX 파일로 컴포넌트 문서를 관리하고 있다. 이번 포스팅에서는 Stroybook에서 MDX 파일을 활용한 방법과 템플릿을 공유해본다.

 

Storybook에서 MDX 설정

 

Storybook에서 MDX를 활용하기 위해서는 Storybook에서 제공하는 플러그인이 필요하다.

 

혹시 설치가 되어있지 않다면 다음 플러그인을 설치한다. 자세한 설치방법은 https://www.npmjs.com/package/@storybook/addon-docs에서 확인할 수 있다.

 

npm install --save @storybook/addon-docs @storybook/preset-typescript mdx-loader

 

설치가 완료되면 다음 구성을 .storybook/main.js 파일에 추가해준다. 

 

module.exports = {
  stories: ['../src/**/*.stories.mdx'],
  addons: ['@storybook/addon-docs'],
};

 

 

폴더구조

 

기본적으로 폴더구조는 다음과 같으며 이번 포스팅에서는 Button 컴포넌트를 예시로 들어보겠다.

 

컴포넌트 단위의 폴더 내부에 개발한 Button.tsx와 mdx, story 파일을 함께 생성해준다.

 

(type과 style은 본인의 취향에 맞게 설정해준다.)

 

- Button
    - Button.tsx
    - Button.mdx
    - Button.stories.tsx
    - Button.types.ts (선택사항)
    - Button.styled.ts (선택사항)
    - index.ts

 

 

MDX 작성하기

 

기존에는 Storybook에서 제공하는 Canvas에서만 Story를 작성하다보니 컴포넌트에 대한 설명, props, args 등이 혼재되어 코드가 복잡해지는 문제가 발생헀다.

 

따라서 컴포넌트 설명에 대한 문서화는 mdx파일에서, Preview, Props, Args에 대한 예시 코드는 story파일에서 최대한 분리하려고 한다.

 

1. 프로젝트 및 개발환경에 필요한 Button.tsx 컴포넌트 생성
2. Button.mdx 파일에서 해당 컴포넌트에 대한 MDX 문서 작성
3. mdx 파일에서 preview 및 컴포넌트 설명에 대한 Story를 Button.storeis.tsx 파일에서 생성

 

컴포넌트를 생성하면 mdx 파일을 생성해준다. 아래 코드는 예시 템플릿이다.

// Button.mdx
import { Canvas } from "@storybook/addon-docs";
import {
  VariantUsage,
  DisableUsage,
  SizeUsage,
  SelectedUsage,
} from "./Button.stories";

# Button

<br />
<br />

## Usage

```tsx
<Button
  text={"버튼 텍스트"}
  styleVariant={ButtonStyleVariant.Primary}
  size={ButtonSize.Standard}
  selected={true}
  disabled={false}
/>
```

<br />
<br />

## Overview

<code>project-ui</code>에서 사용중인 <strong>Button</strong> 컴포넌트 입니다.

<br />
<br />

## Variant

<code>ButtonStyleVariant</code> enum을 통해 정의되며, styleVariant prop으로 지정할
수 있습니다.
<br />
기본값은 Primary이며 <strong>Primary, Secondary, Link, Modal, Switch</strong>가
존재합니다.

<Canvas of={VariantUsage} />

<br />
<br />

## Disable

조건에 따라 <code>disabled</code> 속성을 사용할 수 있습니다. disabled 스타일은 ButtonStyleVariant에 따라 달라집니다.

<Canvas of={DisableUsage} />

<br />
<br />

## Size

<strong>Standard, Medium, Small</strong>사이즈 속성을 사용합니다. 
추후 반응형 적용시 수정될 수 있습니다.

<Canvas of={SizeUsage} />

<br />
<br />

## Selected

버튼이 여러개 존재할 경우 필요에 따라 <code>selected</code>속성을 사용할 수 있습니다.

<Canvas of={SelectedUsage} />

<br />
<br />

## Another Property

 

MDX 문서 작성에 공식은 없으니 본인의 취향, 혹은 팀원들과의 협업을 통해 규칙을 정하면 좋을 것 같다.

 

필자는 다음과 같이 컴포넌트 문서에 대해 구성하였다.

 

• Usage : 컴포넌트의 기본 사용법
• Overview : 컴포넌트의 개략적인 설명. 사용 용도
• Protery : 컴포넌트 속성값에 대한 자세한 설명. ex) variant, size, typography 등등

 

컴포넌트에 전체적인 설명이나 사용법은 대략적으로 서술하더라도, 필드값 혹은 속성값에 대한 부분은 자세히 설명하는게 좋다고 생각한다.

 

문서화라는게 개발자뿐만 아니라 디자이너 및 협업하는 팀원들과 소통하는 과정이기 때문이다.

 

혼자 컴포넌트를 개발하고 작성할땐 본인의 코드이기 때문에 잘 알겠지만, 협업하는 팀원 입장에서는 생소할 수 있기 때문이다.

 

따라서 속성값이 많고 귀찮더라도 최대한 예시를 들어서, 풀어서 설명하면 소통하기 수월 할 것이다.

 

아래 사진들은 mdx파일을 Storybook으로 실행했을 때의 화면들이다.

 

mdx 파일을 Storybook에서 실행한 화면

 

 

Icon Story 예시

 

설명하고 싶은 컴포넌트에 대한 MDX파일을 작성하면 스토리북의 Canvas를 통해 Component.stories.tsx에서 생성한 예시 코드들을 보여줄 수 있다.

 

// TextField.stories.tsx

export const TextFieldUsage: StoryObj = {
  argTypes: {
    label: {
      control: "text",
      default: "",
    },
    placeholder: {
      control: "text",
      default: "",
    },
    type: {
      control: "select",
      options: ["search", "text", "email", "password", "number"],
    },
    isAllowClear: {
      control: { type: "boolean" },
    },
  },
  render: (args) => {
    return (
      <Stack width={"375px"} height={500}>
        <TextField
          type={"text"}
          label={"라벨"}
          placeholder={"내용을 입력해주세요."}
          onChange={onChange}
          {...args}
        />
      </Stack>
    );
  },
};

 

argTypes를 지정하고 컴포넌트에 args로 넘겨주면 Storybook 페이지에서 다양한 속성들을 테스트 해볼 수 있다. 

 

해당링크에서 'radio', 'range'등 다양한 옵션을 확인할 수 있으니 필요한 옵션들을 가져다 써보자.