(4) Storybook 으로 구축하는 Design System – 문서화와 Autodocs

이 글은 Storybook의 공식 튜토리얼인 Design Systems for Developers를 학습하기 위해 작성한 시리즈의 일환으로, 오늘은 스토리북에서 제공하는 문서화 관련 기능에 대해 정리한 내용을 담아보았다.

들어가며

😮‍💨 문서화 작업은 귀찮고 지루한 것이다?
🤣 그래도 꼭 필요한 것이지 않겠어?

문서화(Documentation)는 반복적이고 시간도 적지 않게 소요되는 작업이다. 또한 한 번 작업하고 끝나는 것이 아니라 최신화를 위해선 지속적인 업데이트와 유지보수가 필요하기도 하다.
하지만 문서화가 잘 되어 있으면 의사소통과 협업이 수월해지는 효과를 누릴 수 있기 때문에 매우 중요하다고도 할 수 있다.

현재 만들고 있는게 디자인 시스템을 최대로 활용하려면, 수많은 컴포넌트를 사람들이 볼 수 있게 널리 배포해야 하는데, 이에 가장 적합한 도구가 바로 "사용자 매뉴얼"이라 볼 수 있는 문서라는 도구이다.

따라서 오늘은 디자인 시스템을 구축할 때 도움이 되는 스토리북의 문서화 관련 기능에 대해 알아볼 것이다.

문서화의 중요성

문서화가 지치고 어려운 작업이라는 점에는 많은 사람들이 공감할 것이다.
그렇지만, 협업하여 UI를 개발하거나, 개발된 UI를 언제 어떻게 사용하면 되는지 알리는 데 있어선 문서화만큼 유용한 도구는 또 없을 것이다.

문서화의 어려움

그렇다면 문서화는 왜 어려운 작업으로 여겨질까? 그 이유로는 몇 가지를 떠올려 볼 수 있다.

• 문서화 작업에 시간이 많이 걸리고 유지보수에도 많은 노력이 든다
• 또한 문서 작성 이외의 작업들(가령 어떤 곳에서 작성할지/작성 도구/누가 작성하는가 등)에 대한 추가적인 고려도 필요하다
• 문서가 만들어지자 마자 새로운 기능 추가로 인해 해당 문서는 바로 구식(outdated)이 될 수 있어 최신 상태를 유지하기 어렵다

따라서 개발을 진행하며 문서화의 이점을 최대한 누리기 위해서는 효과적인 문서화를 위한 방안이 필요하다.

효과적인 문서화를 위한 요구사항

문서화를 성공적으로 작성하고 유지보수 하면서도, 방해가 되는 부분을 최소한으로 줄이기 위해서 예를 들면 다음과 같은 고려가 필요하다.

• 🔄 최신 코드와 동기화 되어야 한다
• ✍️ 익숙한 도구로 작성되어야 한다 (Ex. Markdown 문법)
• ⚡️ 유지보수 시간을 최소화 해야 한다
• 📐 보일러플레이트를 제공해 같은 내용을 여러번 작성하지 않도록 해야 한다
• 🎨 복잡한 사용 사례나 컴포넌트에 대해 커스터마이징이 가능해야 한다

다행히도 스토리북이 기본 기능으로 자동 문서화 기능을 제공하여, 그 덕에 큰 노력을 쏟아 붓거나 많이 고민하지 않고도 간단하게 컴포넌트에 대한 문서와 사용 예제를 여러 사람에게 제공할 수 있다.

Storybook의 자동 문서화 기능

스토리북은 기본적으로 자동 문서화 기능을 제공한다. 개발하면서 컴포넌트 스토리를 작성하면, 동시에 나중에 참고해 볼 수 있는 기본적인 문서가 만들어진다.

이렇게 컴포넌트 문서화를 자동화하여, 개발자는 문서 작성에 소요되는 시간을 줄이고 또 다른 개발자들에게 컴포넌트 기능을 명확하게 전달할 수 있는 효과를 누릴 수 있다.

지금부터 스토리북에서 제공하는 Automatic documentation, 줄여서 Autodocs라 불리는 기능에 대해 알아보자.

Autodocs란?

Autodocs는 UI 컴포넌트의 포괄적인 내용에 대해 신속, 간단하게 문서로 만들어 낼 수 있는 강력한 도구다.
이를 활용하면 작성한 스토리를 살아있는 문서로 변환할 수 있으며, 추가적인 구문을 사용해 작성된 문서를 확장하는 것 또한 가능하다.

다만 아무리 '자동' 문서화 라고 해도, 약간의 기본적인 설정은 필요하다. 스토리북이 컴포넌트의 메타데이터(Ex. args, argTypes, parameters)를 추론해서 문서화를 하는 것이기 때문이다.

Autodocs 설정 방법

스토리 파일의 tag 프로퍼티가 "autodocs"를 포함하고 있다면, 해당 컴포넌트에 대한 문서 페이지가 자동으로 생성된다.

컴포넌트 수준 활성화 방법:

const meta: Meta<typeof Button> = {
  title: "Primitives/Button",
  component: Button,
  // ⬇️ 컴포넌트에 대해 문서 자동 생성 기능을 활성화
  tags: ["autodocs"],
  // 다른 설정들..
};
export default meta;

프로젝트 수준 활성화 방법 (.storybook/preview.ts):

import type { Preview } from "@storybook/react";
const preview: Preview = {
  // ⬇️ 모든 스토리에 대해 문서 자동 생성 활성화
  tags: ["autodocs"],
  // 다른 설정들..
}
export default preview;

자동으로 만들어진 문서의 모습은 이와 같은 모습이다. 최소한의 실행 가능한 문서를 위한 구성이라 생각하면 된다.

그렇지만 이 기본적인 구성 만으로도 컴포넌트가 실제 렌더링되어지는 모습과, 가질 수 있는 속성값 목록, 그리고 해당 속성값 선택 시 실시간으로 반영되는 모습 등을 확인할 수 있다.

Storybook 문서 커스터마이징

여러 컴포넌트에서 반복되고 중복되는 문서화 프로세스를 단순화하기 위해 autodocs를 활용할 수 있었다.

하지만 자동 생성되는 문서를 그대로 사용하지 않고 커스터마이징 해서 쓰려 하거나, 원하는 템플릿을 아예 처음부터 새로 만들어 문서에 적용시키고자 하는 요구 사항도 있을 수 있다.

이를 위해 스토리북은 MDX 형식의 파일과 여러 Doc blocks를 이용해 개발자가 문서를 렌더링하는 방법을 직접 제어하도록 하고 있다.

MDX란?

Markdown 문법과 JavaScript/JSX를 혼합해 풍부하고 인터랙티브한 문서를 작성하기 위한 포맷

MDX는 한 파일 내에서 마크다운 문법으로 간결하고 읽기 쉬운 구문을 작성하고, CSF(Component Story Format)으로 정의된 스토리를 가져올 수 있으며, JS/JSX 코드 블록을 포함하는 이 모든 작업을 할 수 있는 도구이다.

기존에 Button 컴포넌트의 문서를 MDX로 새로 작성해보자.

Button.mdx

import { Canvas, Meta } from "@storybook/blocks";

import * as ButtonStories from "./Button.stories.tsx";

<Meta of={ButtonStories} />

# Button

레이블 혹은 아이콘으로 구성된 버튼을 표시합니다.

<Canvas of={ButtonStories.Example} />

정말로 한 파일 내에서 마크다운 문법으로 기본적인 구조를 작성하고, JSX 문법으로 필요한 구성요소를 불러오고 있으며, 이전에 작성했던 스토리를 참조해오고 있다.

이제 스토리북으로 가서 문서를 확인해보면, Button의 문서가 아래와 같이 렌더링된다.

Doc Blocks란?

문서 페이지를 구성하고, 인터랙티브한 예제와 설명을 제공하는 데 사용되는 블록

Doc blocks는 스토리북에서 문서화를 목적으로 사용되는 특정한 컴포넌트의 모음이다. 주로 사용되는 곳은 2군데로, MDX 내에서나 혹은 문서 템플릿 내에서 쓰이곤 한다.
참고로 위 예제 코드에서 사용된 Meta, Canvas가 바로 doc block에 해당한다.

주요 doc blocks:

• Meta: 문서의 메타데이터를 정의
  • title: unattached (사이드바의 지정한 위치에 문서 생성, 스토리 파일과 연결 X)
  • name: attached (사이드바의 컴포넌트 스토리 파일과 연결)
• Story: 모든 어노테이션(parameters, args, loaders, decorators, play function)이 적용된 특정 CSF 파일의 스토리 렌더링
• ArgTypes: 특정 컴포넌트에 대한 arg 테이블을 생성해, 가능한 속성의 설명과 사용법 표시
• Description: 컴포넌트나 스토리에 정의된 주석을 불러 와 표시
  • story에서parameters.docs.description.story 혹은
  • meta에서 parameters.docs.description.component
• Primary: 스토리 파일에 처음 정의된 스토리(기본 스토리) 표시
• Canvas: 컴포넌트 스토리 렌더링(코드 예제를 함께 제공)

이외에도 지원되는 여러 종류의 doc block 들을 활용해서, 더욱 풍부하고 구조적인 문서를 만들어 볼 수 있다.

Ex) 커스텀 템플릿 적용하기

스토리북의 기본 문서 템플릿을 대체하기 위한 예시

MDX 파일이 템플릿 전용임을 나타내기 위해 Meta Doc block에 isTemplate 속성을 전달해야 한다.

DocTemplate.mdx

import { Meta, Title, Primary, Controls, Stories } from "@storybook/blocks";

<Meta isTemplate />

<Title />

# Default implementation

<Primary />

## Inputs

The component accepts the following inputs (props):

<Controls />

---

## Additional variations

Listed below are additional variations of the component.

<Stories />

.storybook/preview.ts

const preview: Preview = {
  parameters: {
    // 다른 설정들.. 
    docs: {
      page: DocTemplate,
    },
  },
};

export default preview;

Ex) 커스텀 문서 작성하기

MDX 문법과 다양한 Doc Block을 활용해서 원하는 구조대로 컴포넌트 문서를 작성한 예시

Button.mdx

import { Canvas, Meta, Story, Source, Description, ArgTypes } from "@storybook/blocks";

import * as ButtonStories from "./Button.stories.tsx";

<Meta of={ButtonStories} name="Special Docs" />

# Button

레이블 혹은 아이콘으로 구성된 버튼을 표시합니다.

<Canvas>
  <Story of={ButtonStories.Example} />
</Canvas>

## Usage

<Source code={`<Button variant="primary" label="Button" />`} />

## Examples

### Variants

<Description of={ButtonStories.BasicButton} />
<Story of={ButtonStories.BasicButton} />
<ArgTypes of={ButtonStories.BasicButton} include={["variant"]} />
<Source
  code={`<Button label="Default" />
<Button variant="danger" label="Destructive" />
<Button variant="outlined" label="Cancel" />
<Button variant="subtle" label="Subtle" />
<Button variant="ghost" label="Ghost" />
<Button variant="link" label="Link" />
`}
/>

<br />

### Sizes

<Description of={ButtonStories.ButtonSize} />
<Story of={ButtonStories.ButtonSize} />
<ArgTypes of={ButtonStories.ButtonSize} include={["size"]} />
<Source
  code={`<Button size="sm" label="Small" />
<Button label="Medium" />
<Button size="lg" label="Large" />
`}
/>

<br />

### With Icon

<Description of={ButtonStories.IconButton} />
<Story of={ButtonStories.IconButton} />
<Source
  code={`<Button icon="mail" label="Login with Email" />
<Button variant="outlined" icon="send" label="Send" />
<Button variant="subtle" label="Loading" loading />
<Button icon="delete" label="Delete" disabled />
<Button icon="plus" onlyIcon pill />
<Button variant="subtle" icon="plus" onlyIcon />
`}
/>

Storybook 문서 빌드

현재까지는 만들어진 문서를 보려면, 이 프로젝트에서 스토리북을 로컬에 띄워서 보는 방법 밖에는 없다.
따라서 문서화된 페이지를 여러 사람에게 보여주려면 온라인에 publishing 해야된다.

스토리북에서 문서만 빌드하기 위해 package.json에 아래 스크립트를 새로 추가한다.

{
  "scripts": {
    "build-storybook-docs": "storybook build --docs",
  }
}

그런 다음엔 CLI 나 CI 도구에서 해당 명령을 npm run build-storybook-docs 로 실행하여 만들어지는 정적 사이트(storybook-static 디렉토리에 있음)를 적절한 배포 도구(Netlify, Vercel 등)로 배포하도록 설정하면 된다.

마치며

지금까지 스토리북의 기능을 활용해 UI 컴포넌트를 문서화 하는 방법에 대해 알아보았다.
이제 이렇게 만든 문서를 활용해, UI 컴포넌트들의 사용 방법을 배우고자 하는 사람들에게 보여줄 수 있다.
아무래도 여러 사람들이 쉽게 이해할 수 있고 가독성이 좋은 문서를 만들기 위해서는, MDX 문법에 대해서도 잘 알면 좋을것 같고 다른 여러 프로젝트의 잘 만들어진 개발 문서도 많이 읽어 보면 좋을 것 같다.

다음 편에서는 디자인 시스템을 실제로 다른 프로젝트에서 사용할 수 있도록, 패키지 관리자를 통해 패키징하는 방법에 대해 알아 볼 예정이다.