디자인 시스템 chromatic 및 템플릿 생성 추가 (#13)

Hys-Lee · web-flow · commit fdba8e8427d9 · 2025-06-11T15:33:11.000+09:00
* feat: Chromatic UI 테스팅 github action 실험 적용

* feat: chromatic 설치

* feat: chromatic ci 관련 yarn-&gt;npm으로 변경

* feat: chromatic 실험용 Test 컴폰너트 ui 변경

* feat: chromatic github action 패키지 버전 수정

* feat: chromatic ci 중단 옵션 수정

* feat: upstream PR에 대해 작동하도록 수정

* feat: 크로마틱 연동 테스트

* feat: 스토리북 plop통한 템플릿 생성 기능 추가

* docs: 스토리북 Intro 문서 수정

* feat: 크로마틱 연동 upstream에 적용하도록 수정

* docs: 스토리북 Intro 스타일 수정

* docs: 프로젝트 README에 디자인시스템 배포 페이지 추가

* fix: 디자인 시스템 chromatic 연결 프로젝트 변경

다른 프로젝트랑 연결 되어 있었기에 수정.

* feat: chromatic github action에서 pull request target 방식으로 수정

forked에서의 pull request로는 secret을 사용할 수 없기 때문에.
diff --git a/.github/workflows/chromatic.yml b/.github/workflows/chromatic.yml
@@ -0,0 +1,48 @@
+name: Chromatic UI Verification
+
+on:
+  pull_request_target:
+    branches:
+      - main # main 브랜치로의 PR 발생 시 실행
+    types: [opened, synchronize, reopened] # PR이 열리거나, 업데이트되거나, 다시 열릴 때 실행
+
+jobs:
+  chromatic-test:
+    # 레포와 PR유저 제한. Dependabot은 의존성 업데이트를 자동화하는 GitHub의 봇.
+    if: github.repository == 'prography/10th-Motimo-FE' &&
+      (
+      github.event.pull_request.user.login == 'Hys-Lee' ||
+      github.event.pull_request.user.login == 'devgony' ||
+      startsWith(github.actor, 'dependabot')
+      )
+
+    permissions:
+      contents: read # 코드 체크아웃에 필요
+      pull-requests: read # PR 정보 읽기에 필요 (pull_request_target 사용 시)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR code
+        uses: actions/checkout@v4
+        with:
+          # PR의 최신 커밋을 가져옵니다. PR_target의 위험성을 낮춥니다.
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0 # Chromatic이 Git 히스토리를 분석할 수 있도록 함
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20" # 프로젝트에 맞는 Node.js 버전
+
+      - name: Install dependencies
+        run: npm install # 또는 npm install
+
+      - name: Build Storybook (선택 사항, 필요시)
+        run: npm run build-storybook # 또는 npm run build-storybook
+
+      - name: Run Chromatic
+        uses: chromaui/action@12.2.0
+        with:
+          # 👇 Chromatic 프로젝트 토큰 (Secrets에 저장 권장)
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          # 👇 true로 설정하면 리뷰되지 않은 변경이 있을 경우 CI를 실패시킴
+          exitZeroOnChanges: false
diff --git a/.gitignore b/.gitignore
@@ -49,6 +49,7 @@ next-env.d.ts
 # storybook
 *storybook.log
 storybook-static-shared
+storybook-static
 
 
 # local environment - vscode
diff --git a/.storybook/CHANGELOG.mdx b/.storybook/CHANGELOG.mdx
@@ -4,8 +4,10 @@ import { Meta } from "@storybook/blocks";
 
 # Change Log
 
-## [0.0.1] - 2025-05-20
+## [0.1.0] - 2025-06-10
+
+스토리북 템플릿 생성 기능 추가 및 Intro 수정
 
-### Started
+## [0.0.1] - 2025-05-20
 
-- 스토리북 관리 시작
+스토리북 관리 시작
diff --git a/.storybook/Introduction.mdx b/.storybook/Introduction.mdx
@@ -5,71 +5,132 @@ import { Meta } from "@storybook/blocks";
 # **MOTIMO Design System**
 
 <br />
-## 사용가이드
 
-[스토리북 배포 주소 나중에 설정]
+## 1. 스토리북 둘러보기
 
-<br />
+### 배포
 
-## 작성법
+<a href="10th-motimo-storybook.vercel.app">10th-motimo-storybook.vercel.app</a>
 
-#### 스토리
+### 사용법
 
-- 기본 스토리 사용 방식을 따른다.
+- 사이드바에서 원하는 컴포넌트를 선택합니다.
 
-- title을 통해 사이드바의 디렉토리를 구성한다.
+- **Docs**를 통해 컴포넌트 전체 정보를 한 눈에 볼 수 있습니다.
 
-- 사용법은 다음과 같다.
+- 스토리별 탭은 Control, Actions, Design, Interactions, Visual tests가
+  존재합니다.
 
-  ```typescript
-  // Test.stories.tsx
-  import Test from "./Test";
-  import { StoryObj } from "@storybook/react";
+- **Controls 탭**에서 Props 값을 확인 또는 변경해볼 수 있습니다. 각 Prop에
+  대한 설명도 이곳에서 볼 수 있습니다.
 
-  // meta는 공통 옵션.
-  const meta = {
-    title: "Example/Test",
-    component: Test,
-    args: {
-      children: "asdf",
-    },
-  };
-  export default meta;
-
-  type Story = StoryObj<typeof meta>;
-
-  // Primary는 공통. argTypes를 사용해 상호작용 가능하도록 한다.
-  export const Primary: Story = {
-    argTypes: {
-      children: {
-        control: "text",
-        description: "보통은 텍스트를 입력하겠지",
-        table: {
-          category: "이야호",
-        },
-      },
-    },
-    args: {
-      children: "버튼",
-    },
-  };
+- **Actions 탭**에서 이벤트 핸들러(콜백 함수)가 호출될 때 발생하는 동작을
+  기록하고 시각적으로 볼 수 있습니다.
 
-  // 기타 스토리들은 args를 기본으로 간단히 처리함
-  export const Ex1: Story = {
-    args: {
-      children: "기본값",
-    },
-  };
-  ```
+- **Design 탭**에서 실제 figma에 작성된 컴포넌트 디자인을 볼 수 있습니다.
+  스토리북에 등록된 컴포넌트와 비교해보세요.
 
-#### 자동화
+- **Interactions 탭**에서 각 스토리별 play함수에 등록된 상호작용 테스트 결과를
+  확인할 수 있습니다.
 
-plop.js를 사용해서 추후 story들 자동 생성 예정.
+- **Visual test 탭**에서 Chromatic과 연결해 컴포넌트 디자인 변경을 리뷰받을 수
+  있습니다. 변화가 unreviewed시 PR되지 않으니 주의하세요.
+
+<br />
+사용을 위해선 Story작성 시 이벤트 핸들러 props에 함수를 주입하면 됩니다.
+<br />
+
+## 2. 스토리 작성 가이드 (기여자를 위한 안내)
+
+### 스토리 파일 작성법 (`*.stories.tsx`)
+
+- `npm run generate:story` 혹은 `npm run generate:story {컴포넌트 경로}`를 통해 컴포넌트의 스토리북 템플릿을 생성한다.
+
+- **필수로, meta의 title을 스토리북 사이드바에 맞게 적절히 수정해야 한다**
+
+- argTypes 필드를 직접 작성하지 않으면, 컴포넌트 props에 대한 type 및 interface를 보고 자동 등록됩니다.
+
+```typescript
+interface TestProps {
+  /**discription입니다*/
+  children: ReactNode;
+}
+
+const Test = ({children}:TestProps)=>{
+  ...
+}
+```
+
+- 선택적으로 커스텀 할 수 있으며, 이를 위한 내부 코드는 아래와 같이 구성된다.
+
+```typescript
+// Test.stories.tsx
+import Test from "./Test";
+import { StoryObj } from "@storybook/react";
+
+/**
+ * 1. meta는 컴포넌트별 공통 옵션입니다.
+ */
+const meta = {
+  title: "Components/Test", // Storybook 사이드바 경로 (프로젝트 규칙에 맞게 수정)
+  component: Test, // 컴포넌트 등록
+  parameters: {
+    // Canvas 레이아웃을 중앙으로 정렬하거나 패딩을 추가할 수 있습니다.
+    layout: "centered",
+  },
+  // Docs 탭 자동 생성을 위해 필요합니다.
+  tags: ["autodocs"],
+  // Controls Addon에서 Props를 어떻게 제어할지, 설명을 추가합니다.
+  // 모든 스토리에 적용될 기본 Props (선택 사항)
+  args: {
+    // 예시: label: '라벨',
+  },
+} satisfies Meta<typeof Test>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * 2. 개별 스토리 작성: 컴포넌트의 다양한 상태와 예시를 보여줍니다.
+
+ *    기본 UI variants들을 스토리로 작성하지만, edge case들을 작성할 수도 있습니다.
+
+ *    각 스토리에 맞는 args를 작성하는 것을 기본으로 합니다.
+ */
+
+// Primary: 가장 기본적인 스토리, 필수로 존재해야 합니다.
+//          반드시 argTypes가 존재해야 합니다. (수기로 작성하든, 비워서 자동완성 시키든)
+export const Primary: Story = {
+  argTypes: {
+    children: {
+      control: "text",
+      description: "텍스트로 입력 될 것임.",
+      table: {
+        category: "이야호",
+      },
+    },
+  },
+
+  // argTypes가 존재할 때, args는 기본값의 역할을 합니다.
+  args: {
+    children: "버튼",
+  },
+};
+
+// UI variatns들을 스토리로 생성합니다.
+// 추가적인 스토리 예시:
+export const LongText: Story = {
+  args: {
+    children: "동해물과백두산이마르고닳도록하느님이보우하사우리나라만세",
+  },
+};
+```
 
 ## 디자인 토큰
 
-디자인 토큰 스토리북 반영 추후 예정
+디자인 토큰 스토리북 Introduction 소개에 반영 추후 예정
 
 ## 버전
 
-[0.0.1] - 2025-05-21
+[0.1.0] - 2025-06-10
diff --git a/.storybook/main.ts b/.storybook/main.ts
@@ -24,11 +24,15 @@ const config: StorybookConfig = {
     "@storybook/addon-docs",
     "@storybook/addon-designs",
     "@storybook/addon-interactions",
+    "@chromatic-com/storybook",
   ],
   framework: {
     name: "@storybook/nextjs",
     options: {},
   },
   staticDirs: [path.resolve(__dirname, "../public")],
+  typescript: {
+    reactDocgen: "react-docgen-typescript",
+  },
 };
 export default config;
diff --git a/README.md b/README.md
@@ -9,6 +9,10 @@
 
 ## ✨ Motimo 프론트엔드 레포지토리에 오신 것을 환영합니다!
 
+> 디자인 시스템 배포 페이지
+
+<a href="10th-motimo-storybook.vercel.app">10th-motimo-storybook.vercel.app</a>
+
 ## 🚀 Motimo 프론트엔드의 핵심 목표
 
 ## 🛠️ 기술 스택
diff --git a/chromatic.config.json b/chromatic.config.json
@@ -0,0 +1,5 @@
+{
+  "onlyChanged": true,
+  "projectId": "Project:6845878ba6d5224aab43a4b2",
+  "zip": true
+}
diff --git a/components/shared/Test.stories.tsx b/components/shared/Test.stories.tsx
@@ -1,38 +1,49 @@
-// Test.stories.tsx
-import Test from "./Test";
-import { StoryObj } from "@storybook/react";
+// plop-templates/story.tsx.hbs
+import type { Meta, StoryObj } from "@storybook/react";
+import Test from "./Test"; // 실제 컴포넌트 파일 임포트
 
-// meta는 공통 옵션.
 const meta = {
-  title: "Example/Test",
+  title: "Components/Test", // Storybook 사이드바 경로 (프로젝트 규칙에 맞게 수정)
   component: Test,
-  args: {
-    children: "asdf",
+  parameters: {
+    // Canvas 레이아웃을 중앙으로 정렬하거나 패딩을 추가할 수 있습니다.
+    layout: "centered",
   },
-};
+  // Docs 탭 자동 생성을 위해 필요합니다.
+  tags: ["autodocs"],
+  // Controls Addon에서 Props를 어떻게 제어할지, 설명을 추가합니다.
+  // argTypes: {
+  //   // 예시: backgroundColor: { control: 'color', description: '컴포넌트 배경색' },
+  // },
+  // 모든 스토리에 적용될 기본 Props (선택 사항)
+  // args: {
+  //   // 예시: label: 'Test',
+  // },
+} satisfies Meta<typeof Test>;
+
 export default meta;
 
 type Story = StoryObj<typeof meta>;
 
-// Primary는 공통. argTypes를 사용해 상호작용 가능하도록 한다.
+// 가장 기본적인 Primary 스토리 (필수 권장)
 export const Primary: Story = {
-  argTypes: {
-    children: {
-      control: "text",
-      description: "보통은 텍스트를 입력하겠지",
-      table: {
-        category: "이야호",
-      },
-    },
+  args: {
+    // Primary 스토리에만 적용될 Props
+    children: "123",
   },
+};
+/*
+// 추가적인 스토리 예시:
+export const Secondary: Story = {
   args: {
-    children: "버튼",
+    label: 'Secondary Test',
   },
 };
 
-// 기타 스토리들은 args를 기본으로 간단히 처리함
-export const Ex1: Story = {
+export const Large: Story = {
   args: {
-    children: "기본값",
+    size: 'large',
+    label: 'Large Test',
   },
 };
+*/
diff --git a/components/shared/Test.tsx b/components/shared/Test.tsx
@@ -1,9 +1,14 @@
 import { ReactNode } from "react";
 
-const Test = ({ children }: { children: ReactNode }) => {
+interface TestProps {
+  /**discription입니다*/
+  children: ReactNode;
+}
+
+const Test = ({ children }: TestProps) => {
   return (
     <>
-      <button>{children}</button>
+      <button className="bg-gray-300">{children}</button>
     </>
   );
 };
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
diff --git a/plop-templates/story.tsx.hbs b/plop-templates/story.tsx.hbs
diff --git a/plopfile.js b/plopfile.js
