feat(controls): Storybook 세팅 및 P0/P0.5 컴포넌트 스토리 추가

- @storybook/react-vite@8 + @storybook/addon-essentials@8 설치
- .storybook/main.ts, preview.tsx 설정 (라이트/다크 테마 토글 포함)
- 18개 컴포넌트 스토리 파일 생성 (Button ~ Skeleton)
- 루트 pnpm storybook 편의 스크립트 추가 (port 6007)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: SOIV

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Status
 
-Phase 1.5 진행 중 (2026-04-13 기준). Core UI Shell은 mock으로 동작하며 실제 백엔드 API 엔드포인트는 미구현. `packages/controls`에 React 컴포넌트 미구현 (`ready: false` 상태).
+Phase 1.5 진행 중 (2026-04-13 기준). Core UI Shell은 mock으로 동작하며 실제 백엔드 API 엔드포인트는 미구현. `packages/controls` P0/P0.5 컴포넌트 구현 완료 (`ready: true`). Storybook 세팅 완료 (port 6007).
 
 ---
 
@@ -29,6 +29,9 @@ pnpm --filter api test                      # api만
 pnpm --filter core test                     # core만
 pnpm exec vitest run apps/api/src/loader/index.test.ts  # 단일 파일
 
+# Storybook (controls 컴포넌트 확인)
+pnpm storybook         # http://localhost:6007 (port 6006 충돌 시 6007 사용)
+
 # 타입 체크
 pnpm typecheck
 ```

package.json

@@ -23,6 +23,7 @@
     "test": "pnpm --recursive test",
     "lint": "pnpm --recursive lint",
     "typecheck": "pnpm --recursive typecheck",
-    "format": "pnpm --recursive format"
+    "format": "pnpm --recursive format",
+    "storybook": "pnpm --filter @fieldstack/controls storybook"
   }
 }

packages/controls/.storybook/main.ts

@@ -0,0 +1,12 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  stories: ['../src/stories/**/*.stories.@(ts|tsx)'],
+  addons: ['@storybook/addon-essentials'],
+  framework: {
+    name: '@storybook/react-vite',
+    options: {},
+  },
+};
+
+export default config;

packages/controls/.storybook/preview.tsx

@@ -0,0 +1,33 @@
+import type { Preview, Decorator } from '@storybook/react';
+import '../src/styles/controls.css';
+
+const withTheme: Decorator = (Story, context) => {
+  const theme = (context.globals.theme as string) ?? 'light';
+  document.documentElement.setAttribute('data-theme', theme);
+  return <Story />;
+};
+
+const preview: Preview = {
+  globalTypes: {
+    theme: {
+      description: 'Color theme',
+      defaultValue: 'light',
+      toolbar: {
+        title: 'Theme',
+        icon: 'circlehollow',
+        items: [
+          { value: 'light', icon: 'sun', title: 'Light' },
+          { value: 'dark', icon: 'moon', title: 'Dark' },
+        ],
+        dynamicTitle: true,
+      },
+    },
+  },
+  decorators: [withTheme],
+  parameters: {
+    layout: 'centered',
+    backgrounds: { disable: true },
+  },
+};
+
+export default preview;

packages/controls/package.json

@@ -15,14 +15,21 @@
   "scripts": {
     "build": "tsc",
     "test": "vitest run --passWithNoTests",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "storybook": "storybook dev -p 6006",
+    "storybook:build": "storybook build"
   },
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18"
   },
   "devDependencies": {
+    "@storybook/addon-essentials": "^8.6.18",
+    "@storybook/react-vite": "^8.6.18",
     "@types/react": "^19.2.14",
+    "@vitejs/plugin-react": "^4",
+    "storybook": "^8",
+    "vite": "^5",
     "vitest": "^2.1.9"
   }
 }

packages/controls/src/stories/Alert.stories.tsx

@@ -0,0 +1,22 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Alert } from '../components/Alert.js';
+
+const meta: Meta<typeof Alert> = {
+  title: 'Controls/Alert',
+  component: Alert,
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Alert>;
+
+export const Success: Story = { args: { variant: 'success', message: '저장되었습니다.' } };
+export const Warning: Story = { args: { variant: 'warning', message: '변경사항이 저장되지 않을 수 있습니다.' } };
+export const Error: Story = { args: { variant: 'error', message: '오류가 발생했습니다. 다시 시도해주세요.' } };
+export const Info: Story = { args: { variant: 'info', message: '시스템 점검이 예정되어 있습니다.' } };
+export const WithTitle: Story = {
+  args: { variant: 'error', title: '인증 실패', message: '이메일 또는 비밀번호를 확인해주세요.' },
+};
+export const Closable: Story = {
+  args: { variant: 'info', message: '닫기 버튼이 있는 알림입니다.', closable: true },
+};

packages/controls/src/stories/Button.stories.tsx

@@ -0,0 +1,27 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from '../components/Button.js';
+
+const meta: Meta<typeof Button> = {
+  title: 'Controls/Button',
+  component: Button,
+  args: { children: 'Button' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Button>;
+
+export const Primary: Story = { args: { variant: 'primary', children: 'Primary' } };
+export const Secondary: Story = { args: { variant: 'secondary', children: 'Secondary' } };
+export const Danger: Story = { args: { variant: 'danger', children: 'Danger' } };
+export const Ghost: Story = { args: { variant: 'ghost', children: 'Ghost' } };
+export const Loading: Story = { args: { variant: 'primary', loading: true, children: 'Loading' } };
+export const Disabled: Story = { args: { variant: 'primary', disabled: true, children: 'Disabled' } };
+export const Sizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
+      <Button size="sm" variant="primary">Small</Button>
+      <Button size="md" variant="primary">Medium</Button>
+      <Button size="lg" variant="primary">Large</Button>
+    </div>
+  ),
+};

packages/controls/src/stories/Checkbox.stories.tsx

@@ -0,0 +1,34 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Checkbox, CheckboxGroup } from '../components/Checkbox.js';
+
+const meta: Meta = { title: 'Controls/Checkbox' };
+export default meta;
+
+export const Single: StoryObj = {
+  render: () => {
+    const [checked, setChecked] = useState(false);
+    return <Checkbox checked={checked} onChange={setChecked} label="동의합니다" />;
+  },
+};
+
+export const Indeterminate: StoryObj = {
+  render: () => <Checkbox checked={false} indeterminate onChange={() => {}} label="일부 선택됨" />,
+};
+
+export const Group: StoryObj = {
+  render: () => {
+    const [values, setValues] = useState<string[]>(['a']);
+    return (
+      <CheckboxGroup
+        values={values}
+        onChange={setValues}
+        options={[
+          { label: '항목 A', value: 'a' },
+          { label: '항목 B', value: 'b' },
+          { label: '항목 C (비활성)', value: 'c', disabled: true },
+        ]}
+      />
+    );
+  },
+};

packages/controls/src/stories/EmptyState.stories.tsx

@@ -0,0 +1,24 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { EmptyState } from '../components/EmptyState.js';
+
+const meta: Meta<typeof EmptyState> = {
+  title: 'Controls/EmptyState',
+  component: EmptyState,
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof EmptyState>;
+
+export const Default: Story = {
+  args: { icon: '📭', title: '데이터가 없습니다', description: '항목을 추가하면 여기에 표시됩니다.' },
+};
+
+export const WithAction: Story = {
+  args: {
+    icon: '📦',
+    title: '모듈이 없습니다',
+    description: '마켓플레이스에서 모듈을 설치해보세요.',
+    action: { label: '마켓플레이스 보기', onClick: () => alert('navigate') },
+  },
+};

packages/controls/src/stories/FormField.stories.tsx

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { FormField } from '../components/FormField.js';
+import { Input } from '../components/Input.js';
+
+const meta: Meta = { title: 'Controls/FormField' };
+export default meta;
+
+export const Default: StoryObj = {
+  render: () => (
+    <FormField label="이메일" htmlFor="email">
+      <Input id="email" type="email" placeholder="name@example.com" />
+    </FormField>
+  ),
+};
+
+export const Required: StoryObj = {
+  render: () => (
+    <FormField label="이름" htmlFor="name" required>
+      <Input id="name" placeholder="홍길동" />
+    </FormField>
+  ),
+};
+
+export const WithError: StoryObj = {
+  render: () => (
+    <FormField label="이메일" htmlFor="email-err" required error="올바른 이메일 형식이 아닙니다.">
+      <Input id="email-err" type="email" defaultValue="invalid" />
+    </FormField>
+  ),
+};
+
+export const WithHelpText: StoryObj = {
+  render: () => (
+    <FormField label="비밀번호" htmlFor="pw" helpText="영문·숫자·특수문자 포함 8자 이상">
+      <Input id="pw" type="password" placeholder="비밀번호 입력" />
+    </FormField>
+  ),
+};