(2) Storybook 으로 구축하는 Design System – 컴포넌트 리뷰 w. Chromatic

이전 편에서는 디자인 시스템과 스토리북의 개요에 대해 살펴 보았고, 직접 디자인 시스템 구축을 위한 프로젝트를 신규로 만들어서 디자인 시스템을 이루는 Button 컴포넌트를 구현해 보기도 했다. 이번 편에서는 그 다음 단계로써, 원활한 협업을 위해 만들어진 컴포넌트를 검토하고 리뷰하는 과정에 대해 알아보고자 한다. (실습을 위해 만든 Github Repository 🐈‍⬛ )

Component Review

개요

개발 프로세스에서, 사용자 요구사항이나 디자인 트렌드의 변화 등 다양한 이유로 UI 컴포넌트는 빈번하게 수정되거나 업데이트된다.

이러한 빠른 변화 속에서 컴포넌트 리뷰의 중요성이 드러난다. 리뷰를 통해 팀은 변경 사항을 신속하게 평가하고, 지속적으로 피드백을 주고 받음으로써 결함이나 오류를 조기에 발견하고 대응하는 데 도움을 얻을 수 있다.

따라서 UI 컴포넌트를 리뷰하는 과정은 개발 프로세스 중에 있어 빠져서는 안 될 필수적인 요소이며 프로젝트 성공에도 중요한 역할을 한다고 볼 수 있다.

스토리북에서의 리뷰

스토리북에서 말하는 컴포넌트 리뷰는 작업 중인 UI 컴포넌트들을 퍼블리싱해 이해관계자들을 개발 과정에 포함시키는 과정이다. 이해관계자는 컴포넌트를 리뷰할 때 기능적 혹은 외관적으로 요구 사항이나 기대치를 충족하는지 체크하는 역할을 한다.

리뷰를 통해 얻을 수 있는 이점

UI를 개발하는 건 개발자와 디자이너 그리고 그 외에도 여러 이해관계자 간의 조화를 필요로 하는 '팀 작업'이다. 여기에는 제품 관리자나 마케터 등 다양한 배경에서 전문성을 가진 사람들이 포함된다.

따라서 리뷰라는 건 다양한 이해관계자들 간의 지식과 경험을 공유하고, 이들로부터 다양한 관점에서의 피드백을 수집해, 사용자 경험을 향상시키는 방법을 발견기 위한 수단이다.
또한 이 과정에서 코드의 품질을 높이거나 버그를 발견하고 수정하여 제품의 품질 향상에도 기여하게 될 수 있기도 하다.

그럼 지금부터 스토리북 시스템에서 컴포넌트 리뷰를 진행하려면 어떤 방법을 따를 수 있는지 알아보자.

Review를 위한 Storybook Publishing

작업한 내용을 여러 사람과 공유하여 검토하기 위해 스토리북을 온라인에 게시할 수 있다.
이를 통해서 여러 작업자들이 코드를 직접 건드리거나 로컬에서 개발 환경을 띄워 보는 번거로운 작업 없이도, UI가 제대로 보이는 지 확인할 수 있다.

게시하는 방법에는 몇 가지가 있는데, 오늘은 스토리북 팀에서 유지 관리하는 무료 서비스인 Chromatic을 활용해 UI 리뷰하는 방법에 대해 알아보려 한다.
크로매틱에서 제공하는 몇 가지 유용한 기능이 있는데 그중에서도 UI에 변경된 부분이 있으면 어떤 부분이 어떻게 변경되었는지 비교해서 보여주는 부분이 있는데 매우 편리해 보여서 한 번 사용해 보기로 결정했다.

1) Chromatic 설정

먼저 chromatic.com으로 이동해 회원가입을 진행해준다. 후에 디자인 시스템 코드가 있는 Github Repo와 연동해야 되기 때문에 깃허브 계정으로 가입을 해줬다.

그러면 project setup을 하기 위해 Choose from GitHub / Create a project 2가지 선택지가 나오는데, 전자를 고르고 코드가 있는 적절한 레파지토리를 클릭한다.
이후 project kind를 선택하라고 하면 Storybook을 누르면 된다.

마지막으로 아래 지침에 따라 두 명령어를 실행시키면 프로젝트에 chromatic 패키지가 설치되고, 프로젝트가 퍼블리싱 된다. (이 과정에 수 분이 소요될 수 있다)

2) 배포된 내용 확인

npx chromatic 명령이 성공적으로 실행되었다면 https://www.chromatic.com/build?appId=...로 시작하는 URL을 얻을 수 있다. 브라우저에서 해당 경로로 접근해 보면 아래와 같이 '스토리북을 성공적으로 퍼블리싱 했다'는 내용을 볼 수 있다.

실제로 내가 구현했던 Button 컴포넌트 그리고 4개의 스토리들이 크로매틱 CDN에 인덱싱되고 버전 관리 된다는 내용이 담겨있다.

(참고로 크로매틱 프로젝트를 최초로 생성한 경우, 바로 내용을 볼 수 있는게 아니라 절차 별로 따라할 수 있는 일종의 가이드가 표시되는 것 같으니, 스킵하려면 최하단의 "Already know how Chromatic works? Go to your project" 버튼을 누르면 된다.)

3) 지속적 통합 방법

이렇게 스토리북을 퍼블리싱하기 위한 인프라가 구축되었다. 하지만 앞으로 코드 푸시가 일어날 때마다 Chromatic을 실행하는 이 작업을 매번 수작업으로 반복해야 한다면 얼마나 번거롭고 피곤한 일이 될까? 또한 작업이 누락 될 가능성도 물론 존재한다.

따라서 이를 개선하기 위해 이러한 과정을 자동화 하는 CI 환경을 구성할 수 있다. 여기서는 GitHub Actions를 활용할 것이다. 아래와 같이 워크플로우를 위한 설정파일을 작성한다.

.github/workflows/chromatic.yml

# 워크플로우 이름
name: "Chromatic Publish"

# 워크플로우를 위한 이벤트
on: push

# 작업 목록
jobs:
  chromatic:
    runs-on: ubuntu-latest # 작업을 실행할 OS
    steps: # 작업 단계 
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install dependencies
        run: npm ci

      - name: Run Chromatic
        uses: chromaui/action@latest
        with: # GitHub Action 에 필요한 옵션
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

위의 내용은 상당히 기본적인 설정만을 담고 있다. 추가적인 설정 방법에 대한 모든 내용은 GitHub Docs - Workflow syntax for GitHub Actions에서 찾을 수 있다.

현재 작성된 내용을 간단히 요약해보면 다음과 같다:

• 저장소의 어느 브랜치에서든 상관 없이 푸시가 수행될 때 워크플로우가 트리거된다.
• 워크플로우는 기본적으로 병렬로 실행되는 하나 이상의 작업 목록을 가지는데, 여기서는 chromatic 이라는 이름의 단일 작업이 존재한다.
  • 이 작업은 Ubuntu OS에서 실행되며, 스텝이라는 일련의 단계를 수행한다.
  • 각 스텝은 코드를 체크아웃하고 / 의존성을 설치하고 / 크로매틱을 실행하는 3가지 일을 순서대로 처리한다.

프로젝트 토큰 설정

프로젝트 토큰을 안전하게 유지하고 관리하려면 값을 공개적으로 놔두지 않고 GitHub 에서 secret 으로 관리하는 것이 바람직하므로,CHROMATIC_PROJECT_TOKEN 라는 토큰 값을 추가해준다.

• 프로젝트 토큰 확인: chromatic.com > 프로젝트 선택 > Manage > Configure
• 프로젝트 토큰 등록: GitHub > 프로젝트 선택 > Settings > Secrets and variables > Actions > New repository secret

파일 커밋 및 푸시

이제 로컬에서 작성한 chromatic.yml 파일을 저장소에 푸시하면, 스토리북 퍼블리싱 작업에 대한 자동화 구성은 끝난다. 아래는 방금 커밋한 내용으로 인해 첫번째 Action이 실행된 모습이다. 이렇게 GitHub와 Chromatic의 연동이 완료되었다.

+) GitHub에 Chromatic App 설치

Chromatic에서 Reviews 탭으로 이동해 사진에 보이는 Instal Chromatic on GitHub 버튼을 눌러 깃허브 레파지토리에 크로매틱 앱을 연동할 수 있다.
이 앱은 풀 리퀘스트를 표시할 수 있는 추가 권한을 얻어 크로매틱 사이트 내에서 변경 사항을 승인하도록 하는 것과 같은 추가 기능을 제공한다.

Visual Review Process

이제 크로매틱에서 지원하는 기능을 활용해 본격적으로 시각적 리뷰를 하는 과정에 대해 알아 보자.
그 중 한가지로, 크로매틱에서는 커밋에 대한 컴포넌트 히스토리와 버전에 대해서 확인할 수 있는 기능을 제공한다. 이를 통해 특정 브랜치나 커밋에서의 컴포넌트를 간편하게 시각적으로 볼 수 있다. (스냅샷 처럼)

UI와 관련된 변경 사항을 포함해 Pull Request를 열면 리뷰 프로세스가 자동으로 시작된다. 다양한 이해관계자를 리뷰어로 초대해 UI 피드백을 한 곳에서 수집하고 워크플로를 간소화 시켜보자.

1. 변경 사항 커밋

새 브랜치로 체크아웃 & UI 변경 사항 커밋

git checkout -b improve-button
...
git commit -m "..."
git push -u origin improve-button

Open Pull Request

PR을 생성하면 아래와 같이 "Some checks haven’t completed yet", 일부 확인이 아직 pending 상태에 있음을 알려준다.

UI Review 나 UI Test 우측에 표시된 Details 링크를 클릭하거나, Chromatic에 직접 들어가 Reviews 탭을 확인해 Visual Review 프로세스에 참여 할 수 있다.

2. 팀과 리뷰 공유

Reviews 탭에서는 이렇게 변경 사항이 적용된 UI를 확인할 수 있다.
이곳에서 Assignee에게 이슈를 할당하여, 팀원이 내용을 확인하고 작성한 피드백을 한 곳에 모아 볼 수 있다.

팀원들의 입장에서는 코드를 다루거나 개발 환경을 설정할 필요 없이, 개발 중인 UI를 빠르게 확인해 볼 수 있어 간편함을 느낄 것이다.

변경 사항에 대해 승인하면..

모든 리뷰어로부터 승인을 얻었다면, 이제 코드를 병합할 준비가 되었다는 뜻이다.

3. 병합

깃허브 레파지토리로 돌아가 PR을 살펴보니 이제 모든 체크 사항이 완료로 표시된 걸 볼 수 있다. 이렇게 하여 리뷰 프로세스는 완료된다.

머지 한 이후에는 아래와 같이 Closed 탭에서 이전에 나눴던 리뷰에 대한 히스토리가 남아 있기 때문에, 향후 필요한 경우 해당 내용을 참조하면 이력 확인에도 도움이 된다.

What's The Next Step?

지금까지 Chromatic을 이용한 Visual Review 프로세스에 대해 살펴 보았다. 이를 통해 디자인 시스템의 일관성을 유지하고, 변경 사항을 시각적으로 빠르게 확인해보며, 피드백을 서로 주고 받아 제품에 신속하게 반영하고 배포할 수 있게 되었다.

다음 단계로는 디자인 시스템의 품질을 유지하기 위해 다양한 방면에서 테스트를 수행하는 방법에 대해 알아볼 예정이다.