feat: add Storybook design system

.github/workflows/chromatic.yml

@@ -0,0 +1,37 @@
+name: Chromatic
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: read
+
+jobs:
+  chromatic:
+    name: Publish Storybook
+    if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.8.0
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Publish to Chromatic
+        uses: chromaui/action@latest
+        with:
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          exitOnceUploaded: true

.github/workflows/test.yml

@@ -37,8 +37,12 @@ jobs:
         run: pnpm typecheck
       - name: Test
         run: pnpm test:run
+      - name: Build Storybook
+        run: pnpm build-storybook
       - name: Install Playwright browsers
         run: pnpm exec playwright install --with-deps chromium
+      - name: Test Storybook
+        run: pnpm test:storybook
       - name: E2E
         run: pnpm test:e2e
   go:

.gitignore

@@ -55,3 +55,11 @@ next-env.d.ts
 
 # air
 /tmp
+
+/debug-storybook.log
+/build-storybook.log
+/storybook-build.log
+/chromatic.log
+/chromatic-build-*.xml
+/chromatic-diagnostics.json
+/storybook-static/

.storybook/main.ts

@@ -0,0 +1,10 @@
+import type { StorybookConfig } from '@storybook/nextjs-vite';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  addons: ['@storybook/addon-vitest', '@storybook/addon-a11y', '@storybook/addon-docs'],
+  framework: '@storybook/nextjs-vite',
+  staticDirs: ['../public'],
+};
+
+export default config;

.storybook/preview.tsx

@@ -0,0 +1,107 @@
+import type { Decorator, Preview } from '@storybook/nextjs-vite';
+import { useEffect, useRef, type ReactNode } from 'react';
+import { ThemeProvider, useTheme } from 'next-themes';
+import { useGlobals } from 'storybook/preview-api';
+import 'slick-carousel/slick/slick.css';
+import 'slick-carousel/slick/slick-theme.css';
+import '@/styles/globals.css';
+
+type Theme = 'light' | 'dark';
+
+type ThemeSyncProps = {
+  globalTheme: Theme;
+  updateGlobals: (globals: Record<string, unknown>) => void;
+  children: ReactNode;
+};
+
+function ThemeSync({ globalTheme, updateGlobals, children }: ThemeSyncProps) {
+  const { resolvedTheme, setTheme } = useTheme();
+  const previousGlobalTheme = useRef(globalTheme);
+  const initialized = useRef(false);
+
+  useEffect(() => {
+    if (resolvedTheme !== 'light' && resolvedTheme !== 'dark') {
+      return;
+    }
+
+    if (!initialized.current) {
+      initialized.current = true;
+      setTheme(globalTheme);
+      return;
+    }
+
+    if (previousGlobalTheme.current !== globalTheme) {
+      previousGlobalTheme.current = globalTheme;
+      setTheme(globalTheme);
+      return;
+    }
+
+    if (resolvedTheme !== globalTheme) {
+      updateGlobals({ theme: resolvedTheme });
+    }
+  }, [globalTheme, resolvedTheme, setTheme, updateGlobals]);
+
+  return children;
+}
+
+const WithTheme: Decorator = (Story, context) => {
+  const [, updateGlobals] = useGlobals();
+  const theme = context.globals.theme === 'dark' ? 'dark' : 'light';
+  const themeClassName = theme === 'dark' ? 'DarkTheme' : 'LightTheme';
+
+  document.body.classList.toggle('DarkTheme', theme === 'dark');
+  document.body.classList.toggle('LightTheme', theme === 'light');
+
+  return (
+    <ThemeProvider
+      defaultTheme={theme}
+      enableSystem={false}
+      storageKey={`storybook-theme-${context.id}`}
+    >
+      <ThemeSync globalTheme={theme} updateGlobals={updateGlobals}>
+        <div className={`${themeClassName} min-h-screen p-6`} data-app-root>
+          <Story />
+        </div>
+      </ThemeSync>
+    </ThemeProvider>
+  );
+};
+
+const preview: Preview = {
+  decorators: [WithTheme],
+  globalTypes: {
+    theme: {
+      description: 'Component theme',
+      toolbar: {
+        icon: 'paintbrush',
+        items: [
+          { value: 'light', title: 'Light' },
+          { value: 'dark', title: 'Dark' },
+        ],
+        dynamicTitle: true,
+      },
+    },
+  },
+  initialGlobals: {
+    theme: 'light',
+  },
+  parameters: {
+    layout: 'fullscreen',
+    nextjs: {
+      appDirectory: true,
+      navigation: {
+        pathname: '/',
+      },
+    },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+
+    a11y: { test: 'error' },
+  },
+};
+
+export default preview;

README.md

@@ -18,6 +18,7 @@
   - [アーキテクチャ](#アーキテクチャ)
   - [環境構築](#環境構築)
   - [スポンサー記事](#スポンサー記事)
+  - [Storybook](#storybook)
   - [Terraform](#terraform)
   - [テスト](#テスト)
   - [OneSignalテスト通知](#onesignalテスト通知)
@@ -30,8 +31,7 @@
 
 <ul>
   <li><a href="https://realunivlog.com">リアル大学生</a></li>
-  <li><a href="https://www.figma.com/design/Fa4LsgTvBhWAu4sIcwYy1O/NextBlogApp?node-id=2102-4673">Figma（Archived Design Tokens）</a></li>
-  <li><a href="https://www.figma.com/design/Fa4LsgTvBhWAu4sIcwYy1O/NextBlogApp?node-id=0-1">Figma（Archived UI）</a></li>
+  <li><a href="https://master--6a922f631bdb93f72e661b33.chromatic.com/">Storybook</a></li>
 </ul>
 
 <p align="right">(<a href="#top">トップへ</a>)</p>
@@ -45,69 +45,16 @@
 | CMS               | microCMS, Zenn RSS                             |
 | Infrastructure    | Cloudflare Pages, Vercel, Amazon S3, Terraform |
 | Environment setup | Node.js, pnpm, Docker Compose                  |
-| CI/CD             | GitHub Actions, CodeQL, Dependabot             |
-| Design            | Canva（Figmaはアーカイブ済み）                 |
+| CI/CD             | GitHub Actions, Chromatic, CodeQL, Dependabot  |
+| Design            | Storybook, Canva                               |
 | Google            | AdSense, Analytics, Search Console, reCAPTCHA  |
 | Integrations      | PWA, OneSignal, Sentry, Iframely, Instagram    |
 
 <p align="right">(<a href="#top">トップへ</a>)</p>
 
 ## アーキテクチャ
 
-```mermaid
-flowchart TB
-  developer[Developer] --> github[GitHub Repository]
-
-  subgraph ci[CI]
-    github --> actions[GitHub Actions]
-    actions --> quality[Lint / Typecheck / Test / CodeQL]
-  end
-
-  subgraph build[Static Build]
-    github --> pagesBuild[Cloudflare Pages Build<br/>pnpm build]
-    microcms[microCMS<br/>Blog / Category / Tag] --> pagesBuild
-    zenn[Zenn RSS] --> pagesBuild
-    pagesBuild --> generated[Static Output<br/>HTML / JS / CSS / RSS / sitemap]
-  end
-
-  generated --> pages[Cloudflare Pages<br/>out]
-  pages --> browser[User Browser]
-
-  subgraph runtime[Browser Runtime]
-    browser --> app[Next.js Client App]
-    app --> thirdParty[Google Analytics / AdSense<br/>OneSignal / Iframely / Instagram]
-    app -. Client errors .-> sentry[Sentry]
-  end
-
-  subgraph vercelFunctions[Vercel Functions]
-    app --> searchApi[Vercel Go Function<br/>/api/search]
-    searchApi --> microcmsBlogContentApi[microCMS<br/>Blog Content API]
-    searchApi --> zenn
-    app --> sendEmailApi[Vercel Go Function<br/>/api/sendemail]
-    recaptchaApi[Vercel Go Function<br/>/api/recaptcha]
-    sendEmailApi --> smtp[SMTP / Gmail]
-    sendEmailApi --> recaptcha[Google reCAPTCHA]
-    recaptchaApi --> recaptcha
-    cron[Vercel Cron<br/>/api/cron/linkchecker] --> linkcheckerApi[Vercel Go Function<br/>Link Checker]
-    linkcheckerApi --> microcmsBlogContentApi
-    linkcheckerApi --> smtp
-    linkcheckerApi --> zenn
-    linkcheckerApi --> s3
-    linkcheckerApi --> oneSignalApi
-    linkcheckerApi --> pagesDeployHook[Cloudflare Pages Deploy Hook]
-    pagesDeployHook --> pagesBuild
-    microcmsWebhook[microCMS<br/>Content Webhook] --> microcmsbackupApi[Vercel Go Function<br/>/api/webhook/microcmsbackup]
-    microcmsbackupApi --> microcmsBlogContentApi
-    microcmsbackupApi --> s3[AWS S3<br/>Backup CSV<br/>Notification Marker]
-    microcmsbackupApi --> oneSignalApi[OneSignal<br/>Push Notification API]
-  end
-
-  searchApi -. Server errors .-> sentry
-  sendEmailApi -. Server errors .-> sentry
-  recaptchaApi -. Server errors .-> sentry
-  linkcheckerApi -. Server errors .-> sentry
-  microcmsbackupApi -. Server errors .-> sentry
-```
+![NextBlogAppアーキテクチャ](public/images/architecture/nextblogapp.png)
 
 <p align="right">(<a href="#top">トップへ</a>)</p>
 
@@ -168,6 +115,28 @@ microCMSの`blog` APIに以下のフィールドを追加する。
 
 <p align="right">(<a href="#top">トップへ</a>)</p>
 
+## Storybook
+
+共通UIと主要な表示状態はStorybookで確認する。ツールバーからLight／Darkテーマを切り替えられ、AccessibilityパネルとブラウザテストでWCAG違反や操作を検証できる。
+
+```bash
+# Storybookを起動
+pnpm storybook
+
+# 静的Storybookを生成
+pnpm build-storybook
+
+# Chromiumをインストール（初回またはPlaywright更新後）
+pnpm exec playwright install chromium
+
+# StoryとアクセシビリティをChromiumで検証
+pnpm test:storybook
+```
+
+Storyは対象コンポーネントと同じディレクトリの`index.stories.tsx`へ配置する。基礎スタイルと共通fixtureは`src/stories/`で管理する。
+
+<p align="right">(<a href="#top">トップへ</a>)</p>
+
 ## Terraform
 
 ```
@@ -200,6 +169,10 @@ pnpm lint
 pnpm typecheck
 pnpm test:run
 
+# Storybookの静的ビルド / ブラウザテスト
+pnpm build-storybook
+pnpm test:storybook
+
 # Goの静的解析 / テスト（Docker）
 docker compose run --rm go go vet ./...
 docker compose run --rm go go test ./...
@@ -247,6 +220,7 @@ scripts/send-onesignal-test-notifications.sh --send
 ```text
 .
 ├── .github/workflows/  # CI/CD・運用ワークフロー
+├── .storybook/         # Storybook設定
 ├── api/                # Vercel Functionsのエントリーポイント
 ├── cmd/                # ローカルGo APIサーバー
 ├── docker/             # 開発用Dockerイメージ
@@ -258,6 +232,7 @@ scripts/send-onesignal-test-notifications.sh --send
 ├── src/
 │   ├── app/             # Next.js App Router
 │   ├── components/      # UIコンポーネント
+│   ├── stories/         # 基礎スタイル・共通Story fixture
 │   ├── config/          # 環境変数の参照
 │   ├── contents/        # 固定ページのコンテンツ
 │   ├── hooks/           # React Hooks

eslint.config.mjs

@@ -1,3 +1,6 @@
+// For more info, see https://github.com/storybookjs/eslint-plugin-storybook#configuration-flat-config-format
+import storybook from 'eslint-plugin-storybook';
+
 import eslint from '@eslint/js';
 import tseslint from 'typescript-eslint';
 import nextPlugin from '@next/eslint-plugin-next';
@@ -75,4 +78,5 @@ export default [
       '@typescript-eslint/no-explicit-any': 'off',
     },
   },
+  ...storybook.configs['flat/recommended'],
 ];