docs: add AI tools configuration (Claude, Codex)

.claude/settings.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "language": "korean",
+  "permissions": {
+    "allow": [
+      "Bash(pnpm *)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git branch*)",
+      "Bash(git checkout*)",
+      "Bash(ls*)",
+      "Edit",
+      "Write",
+      "Read"
+    ],
+    "ask": ["Bash(git push*)", "Bash(git commit*)", "Bash(git reset*)", "Bash(rm *)"],
+    "deny": []
+  },
+  "enabledPlugins": {
+    "codex@openai-codex": true
+  },
+  "availableModels": ["sonnet", "opus"],
+  "sandbox": {
+    "network": {
+      "allowLocalBinding": true,
+      "allowedDomains": ["registry.npmjs.org", "npm.pkg.github.com"]
+    }
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pnpm biome check --write --unsafe $CLAUDE_FILE_PATHS",
+            "timeout": 10,
+            "statusMessage": "Biome 포맷팅 중..."
+          }
+        ]
+      }
+    ]
+  }
+}

.codex/config.toml

@@ -0,0 +1,25 @@
+# Project-scoped Codex defaults for this repository.
+# Claude Code의 .claude/settings.json과 동일한 정책을 유지합니다.
+
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+web_search = "cached"
+
+# Claude의 approval_policy와 매칭:
+#   allow → auto-edit (자동 허용)
+#   ask   → on-request (확인 후 실행)
+# git push, git commit, git reset, rm 등은 confirm 필요
+approval_policy = "on-request"
+
+# Claude sandbox와 매칭: network 접근은 registry.npmjs.org, npm.pkg.github.com 허용
+sandbox_mode = "workspace-write"
+
+[sandbox_workspace_write]
+network_access = true
+
+[features]
+codex_hooks = true
+
+# MCP Servers
+[mcp_servers.figma]
+url = "https://mcp.figma.com/mcp"

.codex/hooks.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pnpm biome check --write --unsafe --changed",
+            "statusMessage": "Biome 포맷팅 중...",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

.gitignore

@@ -180,3 +180,5 @@ storybook-static
 
 # Docusaurus
 build/
+
+.claude/settings.local.json

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "figma": {
+          "type": "http",
+          "url": "https://mcp.figma.com/mcp"
+        }
+  }
+}

AGENTS.md

@@ -0,0 +1,27 @@
+# 저장소 가이드라인
+
+## 프로젝트 구조 및 모듈 구성
+
+`packages/*`에 배포 가능한 컴포넌트와 유틸리티가 위치합니다. 각 패키지는 `src/`에 구현체를, `tsup.config.ts`에 빌드 설정을, 컴포넌트 파일 옆에 테스트/스토리를 둡니다. `packages/tokens`는 공유 디자인 토큰을 정의하고, `packages/side`는 전체 export를 집계합니다. `www/`는 Docusaurus 문서 앱이며, `docs/`와 `www/docs/`에 MDX 콘텐츠가 있습니다. 공유 정적 자산은 `public/`과 `www/static/`에 둡니다. 새 컴포넌트는 폴더를 복사하지 말고 `.templates/component`와 `scripts/createComponent.ts`로 스캐폴딩하세요. 배포 패키지가 변경되면 `.changeset/`에 릴리스 노트를 추가하세요.
+
+## 빌드, 테스트, 개발 명령어
+
+- `pnpm install`: Node `22` 환경에서 워크스페이스를 설치합니다.
+- `pnpm create:component`: 템플릿에서 새 컴포넌트 패키지를 스캐폴딩합니다.
+- `pnpm dev:storybook`: `http://localhost:6006`에서 Storybook을 실행합니다.
+- `pnpm test`: `packages/*`에 대한 Vitest 워크스페이스를 실행합니다.
+- `pnpm --filter ./packages/button build`: `tsup`으로 단일 패키지를 빌드합니다. 편집 중인 패키지 경로로 교체하세요.
+- `pnpm --filter ./www dev`: 문서 사이트를 로컬에서 시작합니다.
+- `pnpm format` / `pnpm lint`: Biome 포맷팅 및 린트 수정을 적용합니다.
+
+## 코딩 스타일 및 네이밍 컨벤션
+
+strict TypeScript를 사용하고, 각 패키지의 `src/index.ts`에서 공개 API를 명시하세요. Biome이 포맷팅 기준입니다: 들여쓰기는 스페이스, 싱글 쿼트, 줄 너비 `120`자. 기존 네이밍 패턴을 따르세요: 패키지 폴더는 kebab-case, React 컴포넌트는 PascalCase, 테스트는 `*.test.tsx`, 스토리는 `*.stories.tsx`, vanilla-extract 스타일은 `*.css.ts`. 색상, 간격, 라운딩 값은 하드코딩하지 말고 `packages/tokens` 값을 사용하세요.
+
+## 테스트 가이드라인
+
+모든 동작 변경에 대해 Vitest 커버리지를 추가하거나 업데이트하세요. 테스트는 `happy-dom` 환경에서 실행되며, 검증 대상 컴포넌트 옆에 위치해야 합니다. 접근성 상태, variant 렌더링, controlled/uncontrolled 동작을 커버하세요. Storybook 스토리는 수동 리뷰에 도움이 되지만 테스트를 대체하지 않습니다. 문서 변경은 `pnpm --filter ./www build`로, 컴포넌트 작업은 Storybook에서 해당 스토리를 확인하세요.
+
+## 커밋 및 PR 가이드라인
+
+`feat(chip): add removable variant`와 같은 Conventional Commits를 사용하세요. scope는 짧게, subject는 영어로, `commitlint.config.ts`를 만족하도록 50자 이내로 작성하세요. PR은 `.github/PULL_REQUEST_TEMPLATE.md`를 따르세요: 변경 사항 요약, UI 변경 시 시각 자료 첨부, 스펙과 테스트 추가 여부 확인. 배포 패키지에 영향을 주는 변경이면 `.changeset` 항목을 포함하고 PR 설명에 릴리스 영향을 명시하세요.

CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+이 파일은 Claude Code(claude.ai/code)가 이 저장소의 코드를 다룰 때 참고하는 가이드입니다.
+
+## 프로젝트 개요
+
+**Side (Sipe Design System)** — `@sipe-team/*` 이름으로 GitHub Package Registry에 배포되는 React 컴포넌트 패키지들의 pnpm 모노레포입니다.
+
+## 명령어
+
+```bash
+pnpm install                        # 의존성 설치 (pnpm 9.7.1, Node v22)
+pnpm dev:storybook                  # Storybook 개발 서버 실행 (:6006)
+pnpm build:storybook                # Storybook 빌드
+pnpm lint                           # Biome 린트 + 수정 (변경된 패키지)
+pnpm format                         # Biome 포맷팅
+pnpm test                           # Vitest (변경된 패키지)
+pnpm create:component               # 템플릿에서 새 컴포넌트 스캐폴딩
+pnpm cz                             # 대화형 conventional commit
+
+# 패키지 단위
+pnpm --filter @sipe-team/button test
+pnpm --filter @sipe-team/button build
+pnpm --filter @sipe-team/button typecheck
+
+# 단일 테스트 파일 실행
+pnpm --filter @sipe-team/button vitest run src/Button.test.tsx
+```
+
+## 아키텍처
+
+- **`packages/*`** — 개별 컴포넌트 패키지 (button, input, card, chip, skeleton 등)
+- **`packages/tokens`** — 디자인 토큰 (색상, 간격, 타이포그래피, 라운딩, 그림자, z-index)을 vanilla-extract contract vars로 export
+- **`packages/theme`** — vanilla-extract `assignInlineVars`를 사용한 ThemeProvider, 런타임 테마 전환 (4개 테마, 라이트 모드 기본)
+- **`packages/typography`** — Typography 컴포넌트 시스템
+- **`www/`** — Docusaurus 문서 사이트
+
+## 컴포넌트 패턴
+
+모든 컴포넌트는 다음 구조를 따릅니다:
+
+1. **`Component.tsx`** — `forwardRef` 래퍼, `ComponentProps<'element'>` 확장, variant enum을 `const` 객체로 정의하고 매칭 타입 생성, Radix `Slot`을 통한 `asChild` 지원
+2. **`Component.css.ts`** — Vanilla Extract `recipe()`에 enum 값을 키로 하는 variant 맵, `@sipe-team/tokens`의 `vars` 사용
+3. **`Component.stories.tsx`** — `Meta`/`StoryObj` 타입을 사용하는 Storybook
+4. **`Component.test.tsx`** — Vitest + `@testing-library/react` (happy-dom 환경)
+5. **`index.ts`** — Re-exports
+
+Variant enum 패턴 (값 객체 + 타입 유니온):
+```ts
+export const ButtonSize = { sm: 'sm', lg: 'lg' } as const;
+export type ButtonSize = (typeof ButtonSize)[keyof typeof ButtonSize];
+```
+
+클래스 조합: `clsx(styles.recipe({ variant, size }), conditionalStyles, className)`
+
+## 스타일링 규칙
+
+- 모든 스타일은 **vanilla-extract**의 `recipe()`를 사용하여 variant 처리
+- 디자인 토큰은 반드시 `import { vars } from '@sipe-team/tokens'`로 import — 색상, 간격, 타이포그래피 값을 하드코딩하지 말 것
+- 각 패키지는 소비자를 위해 `./styles.css`를 export
+
+## 린팅 및 포맷팅
+
+- **Biome** (ESLint/Prettier가 아님) — 싱글 쿼트, 스페이스, 줄 너비 120자
+- import 순서 강제: node → react → @sipe-team/* → @vanilla-extract/* → @radix-ui/* → 외부 패키지 → 상대 경로 (그룹 사이 빈 줄)
+- pre-commit hook이 lint-staged를 통해 `biome check --write --unsafe` 실행
+
+## 커밋 컨벤션
+
+형식: `type(scope): subject` — 영어만, subject 최대 50자, scope 최대 20자.
+타입: feat, fix, hotfix, chore, refactor, release, test, docs, ci, build.
+
+## 브랜치 네이밍
+
+`<CATEGORY>/<ISSUENUMBER>-<SUBJECT>` (이슈 번호는 선택)
+
+## 배포
+
+Changesets 기반으로 GitHub Package Registry에 릴리스. 패키지는 타입과 함께 ESM + CJS를 export. 공개 API 변경 시 `.changeset` 파일을 포함하세요.

biome.json

@@ -1,13 +1,15 @@
 {
-  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "$schema": "node_modules/@biomejs/biome/configuration_schema.json",
+  "files": {
+    "ignoreUnknown": false,
+    "includes": ["**", "!**/*.test.js", "!.github"]
+  },
   "formatter": {
     "enabled": true,
     "indentStyle": "space",
     "lineWidth": 120
   },
-  "organizeImports": {
-    "enabled": true
-  },
+
   "linter": {
     "enabled": true,
     "rules": {
@@ -28,8 +30,5 @@
     "formatter": {
       "quoteStyle": "single"
     }
-  },
-  "files": {
-    "ignore": ["dist/*.*"]
   }
 }

package.json

@@ -17,7 +17,7 @@
     "test": "vitest"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
+    "@biomejs/biome": "^2.4.10",
     "@changesets/cli": "^2.27.9",
     "@clack/prompts": "^0.9.0",
     "@commitlint/cli": "^19.6.1",
@@ -63,8 +63,14 @@
   },
   "packageManager": "pnpm@9.7.1",
   "lint-staged": {
-    "*.{ts,tsx}": ["pnpm format", "pnpm lint"],
-    "*.{json,css,js}": ["pnpm format:biome", "pnpm lint:biome"]
+    "*.{ts,tsx}": [
+      "pnpm format",
+      "pnpm lint"
+    ],
+    "*.{json,css,js}": [
+      "pnpm format:biome",
+      "pnpm lint:biome"
+    ]
   },
   "config": {
     "commitizen": {