file: (mcp)/docs-mcp.mdx
# Docs MCP
AI Agent가 SEED 문서에 직접 접근할 수 있는 MCP 서버를 제공합니다.
## 소개 \[#소개]
[`@seed-design/docs-mcp`](https://github.com/daangn/seed-design/tree/dev/packages/docs-mcp)는 SEED 문서를 위한 공식 MCP(Model Context Protocol) 서버입니다.
이 MCP 서버를 사용하면 AI Agent가 다음 정보에 직접 접근할 수 있습니다:
- **React 컴포넌트**: 설치, props, 사용 예시
- **Design Guidelines**: 컴포넌트 해부도, 속성, 사용 가이드라인
- **Foundation**: 색상, 타이포그래피, 간격 등 디자인 토큰
- **Rootage**: 디자인 토큰과 컴포넌트 스펙 원본 데이터
- **아이콘**: 아이콘 검색 및 사용법
Figma 연결 없이 독립적으로 실행되며, SEED를 사용하는 프로젝트에서 AI 도구의 문서 이해도를 높일 수 있습니다.
## 설치 \[#설치]
```sh
claude mcp add seed-docs -- npx -y @seed-design/docs-mcp
```
```sh
codex mcp add seed-docs -- npx -y @seed-design/docs-mcp
```
`~/.gemini/settings.json` 파일에 다음을 추가합니다:
```json
{
"mcpServers": {
"seed-docs": {
"command": "npx",
"args": ["-y", "@seed-design/docs-mcp"]
}
}
}
```
```json
{
"mcpServers": {
"seed-docs": {
"command": "npx",
"args": ["-y", "@seed-design/docs-mcp"],
"type": "stdio"
}
}
}
```
[Cursor MCP에 대해 자세히 알아보기](https://docs.cursor.com/context/model-context-protocol)
`~/Library/Application Support/Claude/claude_desktop_config.json` 파일에 다음을 추가합니다:
```json
{
"mcpServers": {
"seed-docs": {
"command": "npx",
"args": ["-y", "@seed-design/docs-mcp"]
}
}
}
```
## 사용 가능한 도구 \[#사용-가능한-도구]
### Discovery \[#discovery]
#### `discover_tools` \[#discover\_tools]
사용 가능한 모든 도구를 탐색하고 각 도구의 용도를 확인합니다. MCP 서버에 처음 연결했을 때 호출하면 유용합니다.
**파라미터:**
| 이름 | 타입 | 설명 |
| ---------- | ----------- | --------------------------------------------------------------------------------- |
| `query` | string (선택) | 도구를 필터링할 검색어 (예: 'installation', 'component') |
| `category` | string (선택) | 카테고리 필터 (`discovery`, `react`, `breeze`, `design-guidelines`, `rootage`, `icons`) |
**예시:**
```
discover_tools({ query: "component" })
```
***
### React Components \[#react-components]
#### `list_react_components` \[#list\_react\_components]
사용 가능한 모든 SEED React 컴포넌트 목록을 반환합니다.
**파라미터:** 없음
**예시 응답:**
```
Found 45 React components:
- ActionButton (action-button)
- AlertDialog (alert-dialog)
- Avatar (avatar)
- Badge (badge)
...
```
#### `get_react_component` \[#get\_react\_component]
특정 React 컴포넌트의 상세 문서를 반환합니다. 설치 방법, props, 사용 예시가 포함됩니다.
**파라미터:**
| 이름 | 타입 | 설명 |
| --------------- | ------ | ------------------------------------------------------ |
| `componentName` | string | 컴포넌트 이름 (kebab-case, 예: `action-button`, `text-field`) |
**예시:**
```
get_react_component({ componentName: "action-button" })
```
#### `get_react_changelog` \[#get\_react\_changelog]
SEED React 패키지의 변경 이력을 반환합니다. 버전 업그레이드 시 변경 사항을 확인할 때 유용합니다.
**파라미터:** 없음
***
### React 섹션별 도구 \[#react-섹션별-도구]
React 문서의 각 섹션에 접근하는 도구들입니다. 각 섹션마다 `list_*`와 `get_*` 도구가 제공됩니다.
| 섹션 | list 도구 | get 도구 | 설명 |
| --------------- | ---------------------------- | --------------------------- | ----------------- |
| Getting Started | `list_react_getting_started` | `get_react_getting_started` | 설치, CLI, 스타일링 설정 |
| Stackflow | `list_react_stackflow` | `get_react_stackflow` | Stackflow 통합 가이드 |
| Developer Tools | `list_react_developer_tools` | `get_react_developer_tools` | Codemod, Figma 통합 |
| Migration | `list_react_migration` | `get_react_migration` | 마이그레이션 가이드 |
| AI Integration | `list_react_ai_integration` | `get_react_ai_integration` | AI 도구 통합 |
| Updates | `list_react_updates` | `get_react_updates` | 버전 업데이트 정보 |
#### 사용 예시 \[#사용-예시]
먼저 `list_*` 도구로 사용 가능한 문서를 확인합니다:
```
list_react_getting_started()
```
응답:
```
# SEED React - Getting Started Topics
- Installation - Vite (path: installation/vite)
- Installation - Manual (path: installation/manual)
- CLI - Commands (path: cli/commands)
- CLI - Configuration (path: cli/configuration)
- Styling - Theming (path: styling/theming)
- Styling - Tailwind CSS (path: styling/tailwind-css)
```
원하는 문서의 `path`를 사용해 상세 내용을 가져옵니다:
```
get_react_getting_started({ path: "installation/vite" })
```
***
### Breeze \[#breeze]
Breeze는 프로젝트에 바로 사용할 수 있는 유틸리티 UI 컴포넌트 모음입니다.
#### `list_breeze_components` \[#list\_breeze\_components]
사용 가능한 Breeze 컴포넌트 목록을 반환합니다.
**파라미터:** 없음
**예시 응답:**
```
Found 1 Breeze components:
- AnimateNumber (animate-number)
```
#### `get_breeze_component` \[#get\_breeze\_component]
특정 Breeze 컴포넌트의 상세 문서를 반환합니다.
**파라미터:**
| 이름 | 타입 | 설명 |
| --------------- | ------ | ----------------------------------------- |
| `componentName` | string | 컴포넌트 이름 (kebab-case, 예: `animate-number`) |
**예시:**
```
get_breeze_component({ componentName: "animate-number" })
```
***
### Design Guidelines \[#design-guidelines]
컴포넌트의 디자인 가이드라인 문서에 접근합니다. 해부도(anatomy), 속성, 사용 권장사항 등이 포함됩니다.
#### `list_docs_components` \[#list\_docs\_components]
디자인 가이드라인이 있는 컴포넌트 목록을 반환합니다.
**파라미터:** 없음
**예시 응답:**
```
Found 25 component design guidelines:
- ActionButton (action-button)
- Avatar (avatar)
- BottomSheet (bottom-sheet)
...
```
#### `get_docs_component` \[#get\_docs\_component]
특정 컴포넌트의 디자인 가이드라인을 반환합니다.
**파라미터:**
| 이름 | 타입 | 설명 |
| --------------- | ------ | ---------------------------------------- |
| `componentName` | string | 컴포넌트 이름 (kebab-case, 예: `action-button`) |
**예시:**
```
get_docs_component({ componentName: "action-button" })
```
***
### Rootage \[#rootage]
SEED의 Rootage 스펙(디자인 토큰 및 컴포넌트 스펙의 원본 JSON 데이터)에 접근합니다.
#### `get_rootage` \[#get\_rootage]
Rootage 리소스를 반환합니다. 경로 없이 호출하면 사용 가능한 모든 리소스 목록을 반환합니다.
**파라미터:**
| 이름 | 타입 | 설명 |
| ------ | ----------- | ----------------------------------------------------------- |
| `path` | string (선택) | 리소스 경로 (예: `/color.json`, `/components/action-button.json`) |
**예시:**
리소스 목록 조회:
```
get_rootage()
```
특정 리소스 조회:
```
get_rootage({ path: "/components/action-button.json" })
```
***
### Icons \[#icons]
SEED 아이콘을 검색하고 사용법을 확인합니다.
#### `list_icons` \[#list\_icons]
아이콘 목록을 반환합니다. 타입, 변형, 서비스별로 필터링할 수 있습니다.
**파라미터:**
| 이름 | 타입 | 설명 |
| --------- | ----------- | ------------------------------------- |
| `type` | string (선택) | 아이콘 타입 (`monochrome`, `multicolor`) |
| `variant` | string (선택) | 모노크롬 아이콘 변형 (`line`, `fill`) |
| `service` | string (선택) | 멀티컬러 아이콘의 서비스 카테고리 (예: `중고거래`, `부동산`) |
| `limit` | number (선택) | 반환할 최대 개수 (기본값: 50, 최대: 200) |
**예시:**
```
list_icons({ type: "monochrome", variant: "line", limit: 20 })
```
#### `search_icons` \[#search\_icons]
키워드로 아이콘을 검색합니다. 영어와 한국어 검색을 모두 지원합니다.
**파라미터:**
| 이름 | 타입 | 설명 |
| ------- | ----------- | ----------------------------------- |
| `query` | string | 검색어 (예: `arrow`, `화살표`, `shopping`) |
| `type` | string (선택) | 아이콘 타입 필터 |
| `limit` | number (선택) | 반환할 최대 개수 (기본값: 20, 최대: 100) |
**예시:**
```
search_icons({ query: "화살표" })
```
**예시 응답:**
```
Found 15 icons matching "화살표":
View in browser: https://seed-design.io/foundations/iconography/library?search=화살표
- icon_arrow_left_line [monochrome] (line)
Matched: arrow, 화살표, left
- icon_arrow_right_line [monochrome] (line)
Matched: arrow, 화살표, right
...
```
#### `get_icon_details` \[#get\_icon\_details]
특정 아이콘의 상세 정보와 React 컴포넌트 import 문을 반환합니다.
**파라미터:**
| 이름 | 타입 | 설명 |
| ---------- | ------ | ---------------------------------- |
| `iconName` | string | 아이콘 이름 (예: `icon_arrow_left_line`) |
**예시:**
```
get_icon_details({ iconName: "icon_arrow_left_line" })
```
**예시 응답:**
```markdown
# icon_arrow_left_line
**Type:** monochrome
**Variant:** line
**Keywords:** arrow, left, back, 화살표, 왼쪽
## Usage
### React
\`\`\`tsx
import { IconArrowLeftLine } from "@karrotmarket/react-monochrome-icon"
\`\`\`
## Documentation
View this icon: https://seed-design.io/foundations/iconography/library?icon=icon_arrow_left_line
```
***
## 프로그래매틱 사용 \[#프로그래매틱-사용]
`@seed-design/docs-mcp`는 npm 패키지로 설치하여 커스텀 MCP 서버에 통합할 수 있습니다.
### 설치 \[#설치-1]
```bash
npm install @seed-design/docs-mcp
# 또는
bun add @seed-design/docs-mcp
```
### 사용 예시 \[#사용-예시-1]
```javascript
import { server } from "@seed-design/docs-mcp/server";
import { initializeTools } from "@seed-design/docs-mcp/tools";
// 도구 초기화
await initializeTools(server);
// 원하는 transport와 함께 사용
// 예: stdio, HTTP, SSE 등
```
***
## 개발 \[#개발]
로컬에서 개발하거나 테스트할 때 사용하는 명령어입니다.
```bash
# 의존성 설치
bun install
# 개발 모드 실행 (stdio)
bun run dev
# 빌드
bun run build
# 린트
bun run lint
# 타입 검사
bun run typecheck
```
### MCP Inspector로 테스트 \[#mcp-inspector로-테스트]
[MCP Inspector](https://github.com/modelcontextprotocol/inspector)를 사용하면 브라우저에서 도구를 테스트할 수 있습니다:
```bash
npx @modelcontextprotocol/inspector bun ./dist/stdio.js
```
---
file: (mcp)/figma-mcp.mdx
# Figma MCP
AI Agent를 활용해 Figma 디자인을 React 코드로 변환하는 Model Context Protocol(MCP)를 제공합니다.
## 빠른 설치 \[#빠른-설치]
[Figma 설정](https://www.figma.com/settings)에서 Personal Access Token (PAT)을 발급받을 수 있습니다.
- **PAT가 있는 경우**: Figma URL을 복사해서 AI Agent에게 전달하는 REST API 방식으로 사용할 수 있습니다.
- **PAT가 없는 경우**: Figma 플러그인을 통해 실시간으로 선택한 레이어를 가져오는 WebSocket 방식을 사용해야 합니다.
각 방식의 상세한 차이점은 아래 [설치](#설치) 섹션을 참고하세요.
```bash
claude mcp add seed-design-figma \
--env FIGMA_PERSONAL_ACCESS_TOKEN=${FIGMA_PERSONAL_ACCESS_TOKEN} \
-- bunx -y @seed-design/mcp@latest
```
```bash
codex mcp add seed-design-figma \
--env FIGMA_PERSONAL_ACCESS_TOKEN=${FIGMA_PERSONAL_ACCESS_TOKEN} \
-- bunx -y @seed-design/mcp@latest
```
`~/.gemini/settings.json` 파일에 다음을 추가합니다:
```json
{
"mcpServers": {
"seed-design-figma": {
"command": "bunx",
"args": ["-y", "@seed-design/mcp@latest"],
"env": {
"FIGMA_PERSONAL_ACCESS_TOKEN": ""
}
}
}
}
```
`~/Library/Application Support/Claude/claude_desktop_config.json` 파일에 다음을 추가합니다:
```json
{
"mcpServers": {
"seed-design-figma": {
"command": "bunx",
"args": ["-y", "@seed-design/mcp@latest"],
"env": {
"FIGMA_PERSONAL_ACCESS_TOKEN": ""
}
}
}
}
```
먼저 백그라운드에서 WebSocket 서버를 실행하고, Figma에서 [MCP 플러그인](https://www.figma.com/community/plugin/1496384010980477154)을 설치합니다.
WebSocket 서버 실행을 위해 Bun 런타임이 필요합니다. `--bun` flag를 사용해주세요.
```bash
bunx --bun @seed-design/mcp@latest socket
```
그 다음 MCP 서버를 등록합니다.
```bash
claude mcp add seed-design-figma \
-- bunx -y @seed-design/mcp@latest
```
```bash
codex mcp add seed-design-figma \
-- bunx -y @seed-design/mcp@latest
```
`~/.gemini/settings.json` 파일에 다음을 추가합니다:
```json
{
"mcpServers": {
"seed-design-figma": {
"command": "bunx",
"args": ["-y", "@seed-design/mcp@latest"]
}
}
}
```
`~/Library/Application Support/Claude/claude_desktop_config.json` 파일에 다음을 추가합니다:
```json
{
"mcpServers": {
"seed-design-figma": {
"command": "bunx",
"args": ["-y", "@seed-design/mcp@latest"]
}
}
}
```
## 설치 \[#설치]
### Figma 접근 방식 선택 \[#figma-접근-방식-선택]
**Figma URL과 Personal Access Token으로 레이어 정보를 가져옵니다.**
1. [Figma 설정](https://www.figma.com/settings)에서 Personal Access Token을 발급받습니다.
토큰에 다음 권한을 부여해주세요.
- `file_content:read`
- `file_metadata:read`
- `file_variables:read`
- `library_assets:read`
- `library_content:read`
- `team_library_content:read`
- `file_dev_resources:read`
2. MCP가 환경 변수를 통해 해당 토큰을 사용할 수 있도록 합니다. [MCP 서버 등록](#mcp-서버-등록) 단계에서 `FIGMA_PERSONAL_ACCESS_TOKEN` 환경 변수를 설정해주세요.
**WebSocket 서버와 Figma 플러그인을 통해 Figma 앱에서 실시간으로 선택한 레이어 정보를 가져옵니다.**
`get_selection` 등 실시간 선택 기반 도구는 이 방식에서만 동작합니다.
1. 백그라운드에서 WebSocket 서버를 실행합니다.
WebSocket 서버 실행을 위해 Bun 런타임이 필요합니다. `--bun` flag를 사용해주세요.
```bash
bunx --bun @seed-design/mcp@latest socket
```
2. Figma에서 [MCP 플러그인](https://www.figma.com/community/plugin/1496384010980477154)을 설치하고 실행합니다.
### MCP 서버 등록 \[#mcp-서버-등록]
#### `--mode` 옵션으로 도구 범위 제한하기 \[#--mode-옵션으로-도구-범위-제한하기]
MCP 서버 실행 시 `--mode` 옵션을 명시하면 해당 모드에서 사용 가능한 도구만 등록하여 context 크기를 줄일 수 있습니다.
`--mode` 옵션을 제공하지 않는 경우 기본값으로 `all` 모드가 사용됩니다.
| 모드 | 도구 | 비고 |
| ----------- | ---------------- | --------------------------------- |
| `all` (기본값) | 모든 도구 등록 | PAT 있으면 REST 우선, WS 전용 도구는 WS 사용 |
| `rest` | REST API 도구만 등록 | `get_selection` 등 WS 전용 도구 미등록 |
| `websocket` | WebSocket 도구만 등록 | 현재 모든 도구가 WebSocket 동작 가능, PAT 무시 |
`FIGMA_PERSONAL_ACCESS_TOKEN` 환경 변수를 설정해야 합니다.
항상 REST API만 사용한다면 `--mode=rest` 플래그를 추가해도 됩니다.
```json title=".mcp.json"
{
"mcpServers": {
"seed-design-figma": {
"command": "bunx",
"args": ["-y", "@seed-design/mcp@latest"],
"env": {
"FIGMA_PERSONAL_ACCESS_TOKEN": "${FIGMA_PERSONAL_ACCESS_TOKEN}"
}
}
}
}
```
`FIGMA_PERSONAL_ACCESS_TOKEN` 환경 변수는 설정하지 않아도 됩니다.
항상 WebSocket만 사용한다면 `--mode=websocket` 플래그를 추가해도 됩니다.
```json title=".mcp.json"
{
"mcpServers": {
"seed-design-figma": {
"command": "bunx",
"args": ["-y", "@seed-design/mcp@latest"]
}
}
}
```
### 사용하기 \[#사용하기]
1. Figma에서 레이어의 URL을 복사(⌘ + L)합니다.
2. LLM 도구에게 요청합니다.
```
https://www.figma.com/design/abc123/MyDesign?node-id=123-456 이 레이어의 React 코드를 가져와주세요.
```
1. Figma에서 레이어를 선택합니다.
2. LLM 도구에게 요청합니다.
```
지금 선택한 레이어의 React 코드를 가져와주세요.
```
## 주요 툴 목록 \[#주요-툴-목록]
### REST API + WebSocket 공통 \[#rest-api--websocket-공통]
Figma URL 또는 `fileKey` + `nodeId`를 전달하면 REST API로, `nodeId`만 전달하면 WebSocket으로 동작합니다. 모든 모드에서 등록됩니다.
| 툴 | 설명 |
| ------------------------------- | ------------------------------------ |
| `get_node_info` | 레이어의 구조 정보를 반환합니다. |
| `get_nodes_info` | 여러 레이어의 구조 정보를 한 번에 반환합니다. |
| `get_node_react_code` | 레이어의 React 코드를 생성합니다. |
| `get_component_info` | 컴포넌트의 key와 속성 정의를 반환합니다. |
| `find_nodes` | 하위 레이어를 이름(정규식)으로 검색하여 ID 목록을 반환합니다. |
| `retrieve_color_variable_names` | SEED 색상 변수 이름 목록을 반환합니다. |
### WebSocket 전용 \[#websocket-전용]
Figma 플러그인과 통신이 필요합니다. `websocket` 또는 `all` 모드에서 등록됩니다.
| 툴 | 설명 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `get_selection` | 현재 선택한 레이어의 ID를 반환합니다. |
| `get_document_info` | 현재 열린 Figma 문서의 정보를 반환합니다. |
| `export_node_as_image` | 레이어를 이미지(PNG, JPG, SVG, PDF)로 내보냅니다. |
| `add_annotations` | 레이어에 [Annotation](https://help.figma.com/hc/en-us/articles/20774752502935-Add-measurements-and-annotate-designs)을 추가합니다. |
| `get_annotations` | 레이어의 Annotation을 가져옵니다. |
| `join_channel` | 특정 채널에 참가합니다. |
## 커스텀 설정 사용하기 \[#커스텀-설정-사용하기]
`get_node_react_code`는 기본적으로 SEED Figma 컴포넌트만 인식합니다. 팀 내부 디자인 시스템이나 커스텀 컴포넌트를 사용하는 경우, ComponentHandler를 작성해 Figma 컴포넌트를 원하는 React 컴포넌트로 매핑할 수 있습니다.
MCP 서버 설정에 `--config` flag를 추가해 커스텀 설정 파일이 로드될 수 있도록 합니다.
`--config` flag는 Bun 런타임이 필요합니다. `--bun` flag를 사용해주세요.
```bash
bunx --bun @seed-design/mcp@latest --config /path/to/config.ts
```
### 지원하는 설정 파일 형식 \[#지원하는-설정-파일-형식]
`@seed-design/mcp`는 다음 확장자의 설정 파일을 지원합니다:
- `.js`
- `.mjs`
- `.ts`
- `.mts`
### 설정 파일 예시 \[#설정-파일-예시]
```typescript
import {
type react,
defineComponentHandler,
createElement,
} from "@seed-design/figma";
export default {
extend: {
componentHandlers: [
(_deps: react.ComponentHandlerDeps) =>
defineComponentHandler(
"figma_component_key",
({ componentProperties: props }) => {
const tone = props.Tone.value.toLowerCase();
return createElement("CustomButton", {
tone,
});
},
),
],
},
} satisfies react.CreatePipelineConfig;
```
### SEED Figma MCP로 ComponentHandler 작성하기 \[#seed-figma-mcp로-componenthandler-작성하기]
SEED Figma Slider 컴포넌트를 SEED React ``로 매핑하는 [ComponentHandler 예시](https://github.com/daangn/seed-design/blob/dev/packages/figma/src/codegen/targets/react/component/handlers/slider.ts)를 확인할 수 있습니다.
#### 프롬프트 복사 \[#프롬프트-복사]
아래 프롬프트를 복사해 파일로 저장합니다.
````markdown
# ComponentHandler Implementation Guide
## Initial Context Gathering
1. **Analyze Figma Selection**:
- Use `get_selection()` to examine the currently selected node(s)
- If no selection exists, prompt the user to select a specific component node
- Verify the selected node is a component that can be transformed
2. **Retrieve Component Information**:
- Use `get_component_info(nodeId)` to extract detailed information about the component
- Collect the component key, all component properties, and variant definitions
- Identify any nested components or instances that might need special handling
## Component Analysis and Planning
3. **Determine Component Structure**:
- Analyze the component's visual structure, layout, and behavior patterns
- If the target React component implementation is unknown, request an example or props interface
- Identify which Figma properties should map to which React props
4. **Define Transformation Strategy**:
- Plan how to handle variants, properties, nested components and children
- Determine if additional utilities or helper functions are needed
- Consider edge cases and special requirements for this component
## Implementation
5. **Create Component Handler**:
- Implement the handler using the following pattern:
```typescript
import {
createElement,
defineComponentHandler,
type InferComponentDefinition,
type react,
} from "@seed-design/figma";
// Define component properties based on Figma definition
export type ComponentNameProperties = InferComponentDefinition<{
// Map all component properties from Figma
// Example:
PropertyName: {
type: "VARIANT" | "TEXT" | "BOOLEAN" | "INSTANCE_SWAP";
variantOptions?: string[]; // For VARIANT type
defaultValue?: string | boolean;
};
}>;
// Create and export the handler
export const createComponentNameHandler = (_deps: react.ComponentHandlerDeps) =>
defineComponentHandler(
"component-key-from-figma", // Replace with actual component key
({ componentProperties: props }) => {
// Transform Figma properties to React props
// Use conditionals for variants and property handling
return createElement(
"ComponentName", // The React component name
{
// Map properties appropriately
propName: props.PropertyName.value,
// Add additional props as needed
},
[], // Nested elements if any (undefined or omitted if not needed)
"Optional comment for accessibility or development notes, use sparingly",
);
},
);
```
## Validation and Testing
6. **Verify Handler Functionality**:
- Test the handler with different component variants
- Ensure all properties are correctly mapped and transformed
- Check that nested components and children are handled properly
## Best Practices
- Create reusable helper functions for common transformation patterns
- Handle edge cases and optional properties gracefully
- Add descriptive comments for complex transformations
- Consider performance implications for deeply nested components
- Ensure type safety throughout the transformation process
````
#### 프롬프트 실행 \[#프롬프트-실행]
저장된 프롬프트 파일과 구현해야 할 컴포넌트 파일을 맥락으로 전달하며 프롬프트를 실행합니다.
```bash
@CustomButton.tsx @ComponentHandlerRule.md CustomButton 컴포넌트의 ComponentHandler를 구현해주세요.
```
#### 결과 확인 \[#결과-확인]
프롬프트 실행 결과로 생성된 ComponentHandler를 확인합니다.
```typescript
import {
createElement,
defineComponentHandler,
type InferComponentDefinition,
type react,
} from "@seed-design/figma";
export type CustomButtonProperties = InferComponentDefinition<{
tone: {
type: "VARIANT";
variantOptions: ["neutral", "brand"];
};
}>;
export const createCustomButtonHandler = (_deps: react.ComponentHandlerDeps) =>
defineComponentHandler(
"figma_component_key",
({ componentProperties: props }) => {
const tone = props.tone.value.toLowerCase();
return createElement("CustomButton", {
tone,
});
},
);
```
#### 설정 파일 적용 \[#설정-파일-적용]
생성된 ComponentHandler를 설정 파일에 추가합니다.
```typescript
import { type react } from "@seed-design/figma";
import { createCustomButtonHandler } from "./CustomButton";
export default {
extend: {
componentHandlers: [createCustomButtonHandler],
},
} satisfies react.CreatePipelineConfig;
```
---
file: skill.mdx
# Skill
SEED 통합 가이드. 프로젝트 셋업, 컴포넌트 탐색/사용, 파운데이션(색상·타이포·스페이싱) 활용, 테마/스타일링, CLI 워크플로우(init/add/add-all/compat/docs/upgrade), 스니펫 버전 호환성, 업그레이드 진단까지 커버.
## Installation \[#installation]
`seed-design` 스킬을 설치하려면 다음 명령어를 사용하세요.
- npm: npx skills add https://github.com/daangn/seed-design --skill seed-design
- pnpm: pnpm dlx skills add https://github.com/daangn/seed-design --skill seed-design
- yarn: yarn dlx skills add https://github.com/daangn/seed-design --skill seed-design
- bun: bun x skills add https://github.com/daangn/seed-design --skill seed-design
## File Structure \[#file-structure]
## SKILL.md \[#skillmd]
````md
---
name: seed-design
description: SEED Design 통합 가이드. 프로젝트 셋업, 컴포넌트 탐색/사용, 파운데이션(색상·타이포·스페이싱) 활용, 테마/스타일링, CLI 워크플로우(init/add/add-all/compat/docs), 스니펫 버전 호환성, 업그레이드 진단까지 커버. SEED Design 관련 질문이면 이 스킬을 사용한다. 사용자가 "SEED 어떻게 써?", "컴포넌트 뭐 있어?", "색상 토큰 쓰는 법", "디자인시스템 셋업" 같은 질문을 하면 반드시 이 스킬을 로드한다.
user-invocable: true
argument-hint: "[질문 또는 주제]"
---
# SEED Design
당근의 디자인 시스템 SEED Design을 프로젝트에 도입하고 활용할 때 사용하는 통합 가이드입니다. 처음 셋업부터 컴포넌트 사용, 파운데이션 활용, CLI 운영까지 모든 단계를 안내합니다.
## 동작 방식
이 스킬이 호출되면 아래 순서로 동작합니다.
### 1단계: 프로젝트 상태 파악
사용자의 프로젝트를 분석하여 현재 상태를 파악합니다.
- `seed-design.json` 존재 여부 → 초기 설정 완료 여부
- `package.json`에서 `@seed-design/react`, `@seed-design/css` 설치 여부와 버전
- 번들러 종류 감지 (`vite.config`, `rsbuild.config`, `webpack.config` 등)
- `seed-design/` 디렉토리 존재 여부 → 스니펫 설치 여부
- 패키지 매니저 감지 (lock 파일 기준):
- `bun.lockb` / `bun.lock` → bun
- `pnpm-lock.yaml` → pnpm
- `yarn.lock` → yarn
- `package-lock.json` 또는 기본 → npm
이후 모든 패키지 설치/실행 명령어는 감지된 패키지 매니저에 맞춰 안내합니다.
### 2단계: 상황 분류 및 분기
파악한 상태와 사용자의 질문에 따라 적절한 가이드로 분기합니다.
| 상황 | 참조 |
|------|------|
| `seed-design.json` 없음 → 처음 셋업이 필요 | `references/getting-started.md` |
| 컴포넌트 관련 질문 (어떤 컴포넌트 있어?, 버튼 쓰고 싶은데) | `references/components.md` |
| 파운데이션/토큰 질문 (색상, 타이포, 스페이싱, 테마) | `references/foundation.md` |
| CLI 명령어 관련 (init, add, docs 등) | `references/usage.md` |
| 스니펫 버전 맞추기/파일 충돌 | `references/migration.md` |
| 버전 업그레이드·호환 진단 (react↔css, 마이그레이션 경로) | `references/upgrade.md` |
사용자가 명시적으로 주제를 말한 경우 프로젝트 분석을 건너뛰고 해당 시나리오로 직행해도 됩니다.
### 3단계: 안내 + 실행
- 기존 문서 링크 제공: `https://seed-design.io/react/components/{component-name}`
- llms.txt URL로 상세 정보 참조: `https://seed-design.io/llms/react/components/{component-name}.txt`
- CLI `docs` 명령어로 문서/llms.txt/스니펫 링크 한 번에 조회:
```bash
npx @seed-design/cli@latest docs {component-name}
```
- 사용자가 원하면 CLI 명령어를 직접 실행 (init, add 등)
### 4단계: 다음 단계 제안
현재 작업이 끝나면 자연스럽게 다음 단계를 안내합니다.
- 셋업 완료 → "이제 컴포넌트를 추가해볼까요?"
- 컴포넌트 추가 → "테마 설정이나 다른 컴포넌트도 필요하신가요?"
- 파운데이션 안내 → "실제 코드에서 이렇게 사용하면 됩니다"
## 정보 조회 도구
SEED Design의 모든 문서에는 llms.txt 형태의 LLM 최적화 문서가 있습니다. 컴포넌트 목록, 파운데이션 가이드 등 최신 정보가 필요하면 llms.txt를 WebFetch로 읽어옵니다.
### llms.txt 인덱스
| 영역 | 인덱스 URL | 용도 |
|------|-----------|------|
| React | https://seed-design.io/react/llms.txt | 컴포넌트 목록, 설치/스타일링 가이드 |
| Foundations | https://seed-design.io/foundations/llms.txt | 파운데이션(색상, 타이포, 스페이싱 등) |
| Components | https://seed-design.io/components/llms.txt | 컴포넌트 디자인 스펙(Anatomy, Properties, Guidelines) |
### 개별 문서 조회
```text
https://seed-design.io/llms/react/components/{component-name}.txt
https://seed-design.io/llms/foundations/color.txt
```
### CLI docs 명령어
```bash
npx @seed-design/cli@latest docs {component-name}
# 출력:
# - docs: https://seed-design.io/react/components/action-button
# - llms.txt: https://seed-design.io/llms/react/components/action-button.txt
# - snippet: https://raw.githubusercontent.com/daangn/seed-design/refs/heads/dev/docs/registry/react/ui/action-button.tsx
```
## Reference Files
| 파일 | 용도 | 읽는 시점 |
|------|------|-----------|
| `references/getting-started.md` | 처음 셋업 가이드 | seed-design.json이 없거나 셋업 질문 시 |
| `references/components.md` | 컴포넌트 탐색/추가 방법 | 컴포넌트 관련 질문 시 |
| `references/foundation.md` | 파운데이션 llms.txt 인덱스 | 색상, 타이포, 스페이싱, 테마 질문 시 |
| `references/usage.md` | CLI 명령어 상세 | CLI 사용법 질문 시 |
| `references/migration.md` | 스니펫 버전 맞추기/파일 충돌 해결 | 스니펫 버전 불일치 시 |
| `references/upgrade.md` | 버전 업그레이드·호환 진단 (react↔css, changelog, 마이그레이션 경로) | 업그레이드·호환 질문 시 |
````
## References \[#references]
### getting-started.md \[#getting-startedmd]
````md
# Getting Started
프로젝트에 SEED Design을 처음 도입할 때의 가이드입니다. 아래 예시는 npm 기준이며, 1단계에서 감지한 패키지 매니저에 맞춰 변환합니다.
## 최단 경로: 5분 안에 첫 컴포넌트 띄우기
### 1. 패키지 설치
```bash
npm install @seed-design/react @seed-design/css
```
### 2. seed-design.json 생성
CLI로 생성 (권장):
```bash
npx @seed-design/cli@latest init
```
또는 직접 생성:
```json
{
"rsc": false,
"tsx": true,
"path": "./seed-design"
}
```
주요 설정:
- `rsc`: React Server Components 사용 시 `true` → snippet에 `"use client"` 유지
- `tsx`: TypeScript 사용 시 `true`
- `path`: snippet이 설치될 디렉토리 경로
### 3. base.css import
앱의 엔트리 파일에 추가:
```ts
import "@seed-design/css/base.css";
```
### 4. tsconfig.json 경로 설정
```json
{
"compilerOptions": {
"paths": {
"seed-design/*": ["./seed-design/*"]
}
}
}
```
### 5. 번들러 플러그인 설정
번들러에 따라 설정이 다릅니다. 상세 내용은 llms.txt를 참조합니다.
#### Vite (권장)
```bash
npm install -D @seed-design/vite-plugin
```
```ts
// vite.config.ts
import { seedDesign } from "@seed-design/vite-plugin";
export default defineConfig({
plugins: [seedDesign()],
});
```
- Vite 7 이하는 `vite-tsconfig-paths` 추가 필요
- 상세: https://seed-design.io/llms/react/getting-started/installation/vite.txt
#### Rsbuild
```bash
npm install -D @seed-design/rsbuild-plugin
```
- 상세: https://seed-design.io/llms/react/getting-started/installation/rsbuild.txt
#### Webpack
```bash
npm install -D @seed-design/webpack-plugin
```
- 상세: https://seed-design.io/llms/react/getting-started/installation/webpack.txt
#### Manual (번들러 플러그인 없이)
- 상세: https://seed-design.io/llms/react/getting-started/installation/manual.txt
### 6. 테마 설정
HTML의 `` 태그에 테마 속성 추가:
```html
```
- `data-seed-color-mode`: `system` | `light-only` | `dark-only`
- `data-seed-user-color-scheme`: `light` | `dark` (system 모드에서 OS 설정 반영)
번들러 플러그인을 사용하면 이 설정이 자동으로 적용됩니다.
### 7. 첫 컴포넌트 추가
```bash
npx @seed-design/cli@latest add ui:action-button
```
```tsx
import { ActionButton } from "seed-design/ui/action-button";
function App() {
return 시작하기;
}
```
## 셋업 완료 후 다음 단계
- 컴포넌트 탐색/추가: `references/components.md` 참조
- 파운데이션(색상, 타이포, 스페이싱) 활용: `references/foundation.md` 참조
- 전체 React 문서 인덱스: https://seed-design.io/react/llms.txt
- 디자인 가이드라인 인덱스: https://seed-design.io/docs/llms.txt
````
### components.md \[#componentsmd]
````md
# Components
SEED Design 컴포넌트를 탐색하고 사용하는 방법입니다.
## 컴포넌트 목록 확인
전체 컴포넌트 목록과 설명은 llms.txt에서 항상 최신 상태로 확인할 수 있습니다:
```text
https://seed-design.io/react/llms.txt
```
이 URL을 WebFetch로 읽으면 모든 컴포넌트의 이름, 설명, 상세 문서 링크를 얻을 수 있습니다.
## 컴포넌트 상세 정보 조회
특정 컴포넌트의 props, 사용법, 예제를 알고 싶을 때:
1. **CLI docs 명령어** (권장):
```bash
npx @seed-design/cli@latest docs {component-name}
```
문서 링크, llms.txt 링크, snippet 링크를 한 번에 출력합니다.
2. **llms.txt URL** (WebFetch로 직접 읽기):
```
https://seed-design.io/llms/react/components/{component-name}.txt
```
3. **문서 사이트**:
```
https://seed-design.io/react/components/{component-name}
```
## 레지스트리 구조
컴포넌트는 4개 레지스트리로 나뉩니다:
| 레지스트리 | 용도 | 추가 명령어 |
|-----------|------|------------|
| `ui` | 핵심 UI 컴포넌트 | `npx @seed-design/cli@latest add ui:{name}` |
| `block` | 복합 패턴 (페이지 레이아웃 등) | `npx @seed-design/cli@latest add block:{name}` |
| `breeze` | 유틸리티 컴포넌트 | `npx @seed-design/cli@latest add breeze:{name}` |
| `lib` | 저수준 유틸리티 | `npx @seed-design/cli@latest add lib:{name}` |
## 컴포넌트 추가 방법
### 단일 컴포넌트
```bash
npx @seed-design/cli@latest add ui:action-button
```
### 여러 컴포넌트
```bash
npx @seed-design/cli@latest add ui:action-button ui:checkbox ui:switch
```
### 레지스트리 전체
```bash
npx @seed-design/cli@latest add-all ui
```
### 설치 후 import
```tsx
import { ActionButton } from "seed-design/ui/action-button";
import { Checkbox } from "seed-design/ui/checkbox";
```
## snippet 커스터마이징
CLI로 추가된 컴포넌트는 프로젝트의 `seed-design/` 디렉토리에 snippet으로 설치됩니다. node_modules가 아닌 프로젝트 코드이므로 자유롭게 수정할 수 있습니다.
단, 업데이트 시 충돌이 발생할 수 있으므로 커스텀 변경이 큰 경우 `backup` 전략을 사용하는 것이 안전합니다. 상세는 `references/migration.md`를 참조하세요.
````
### foundation.md \[#foundationmd]
````md
# Foundation
SEED Design의 파운데이션 — 색상, 타이포그래피, 스페이싱, 테마 시스템을 활용하는 가이드입니다.
## 파운데이션 문서 참조
디자인 가이드라인의 전체 목록은 llms.txt에서 확인할 수 있습니다:
```text
https://seed-design.io/foundations/llms.txt
```
## 주요 토픽별 llms.txt
상세 정보가 필요하면 WebFetch로 해당 URL을 읽어옵니다.
### 색상
| 토픽 | URL |
|------|-----|
| 색상 시스템 개요 | https://seed-design.io/llms/foundations/color.txt |
| 역할 기반 색상 | https://seed-design.io/llms/foundations/color/color-role.txt |
| 팔레트 | https://seed-design.io/llms/foundations/color/palette.txt |
핵심 원칙: 역할 기반 색상(`--seed-color-fg-*`, `--seed-color-bg-*`, `--seed-color-stroke-*`)을 우선 사용합니다. 팔레트 색상(`--seed-color-palette-*`)은 역할 기반으로 커버되지 않는 예외 상황에만 사용합니다.
### 타이포그래피
| 토픽 | URL |
|------|-----|
| 타이포그래피 개요 | https://seed-design.io/llms/foundations/typography.txt |
핵심 원칙: 스케일은 t1(가장 작음)부터 t10(가장 큼). CSS 변수 `--seed-font-size-t{n}`, `--seed-line-height-t{n}`, `--seed-font-weight-*`로 사용합니다.
### Iconography
| 토픽 | URL |
|------|-----|
| Overview | https://seed-design.io/llms/foundations/iconography.txt |
| Usage | https://seed-design.io/llms/foundations/iconography/usage.txt |
| Library | https://seed-design.io/llms/foundations/iconography/library.txt |
### 스페이싱, 테마, 기타
| 토픽 | URL |
|------|-----|
| 스페이싱 | https://seed-design.io/llms/foundations/spacing.txt |
| 테마 | https://seed-design.io/llms/react/getting-started/styling/theming.txt |
| Tailwind CSS 연동 | https://seed-design.io/llms/react/getting-started/styling/tailwind-css.txt |
| Elevation (그림자) | https://seed-design.io/llms/foundations/elevation.txt |
| Radius (모서리) | https://seed-design.io/llms/foundations/radius.txt |
| Motion (애니메이션) | https://seed-design.io/llms/foundations/motion.txt |
| Gradient | https://seed-design.io/llms/foundations/gradient.txt |
````
### usage.md \[#usagemd]
````md
# Usage
## Core Commands
### 1) Initialization
```bash
npx @seed-design/cli@latest init
```
질문 없이 기본값으로 만들려면:
```bash
npx @seed-design/cli@latest init --yes
```
### 2) Add Snippets
```bash
npx @seed-design/cli@latest add ui:action-button
```
여러 항목 추가:
```bash
npx @seed-design/cli@latest add ui:action-button ui:alert-dialog
```
### 3) Add by Registry
```bash
npx @seed-design/cli@latest add-all ui
```
모든 레지스트리:
```bash
npx @seed-design/cli@latest add-all --all
```
### 4) Compatibility Check
현재 프로젝트의 seed-design 패키지와 스니펫 요구 버전이 맞는지 검사합니다.
React: `@seed-design/react`, `@seed-design/css` / Lynx: `@seed-design/lynx-react`, `@seed-design/lynx-css`
```bash
npx @seed-design/cli@latest compat
```
특정 항목만 검사:
```bash
npx @seed-design/cli@latest compat ui:action-button ui:alert-dialog
```
컴포넌트 shorthand 검사:
```bash
npx @seed-design/cli@latest compat -c action-button -c alert-dialog
```
모든 레지스트리 항목 검사:
```bash
npx @seed-design/cli@latest compat --all
```
구조화 출력이 필요하면 `--json`을 사용합니다.
```bash
npx @seed-design/cli@latest compat --json
```
> `compat`은 **스니펫**이 요구하는 범위만 검사합니다. 설치된 패키지들끼리(react↔css) 맞는지는 CLI가 판정하지 않으니 `upgrade.md`의 Step 2를 참고하세요 — 2.x는 `peerDependencies` 선언이 정답이고, 1.x는 [v1 업그레이드 문서](https://seed-design.io/llms/react/updates/upgrade/v1.txt)의 호환표를 봐야 합니다.
### 5) Docs 조회
컴포넌트/파운데이션에 대한 문서 링크, LLM용 텍스트 링크, 스니펫 링크를 조회합니다.
인터랙티브 모드 (카테고리 → 섹션 → 항목 순서로 선택):
```bash
npx @seed-design/cli@latest docs
```
특정 항목 직접 조회:
```bash
npx @seed-design/cli@latest docs action-button
```
경로 기반 조회 (카테고리/섹션/항목):
```bash
npx @seed-design/cli@latest docs react/components/action-button
```
카테고리만 지정:
```bash
npx @seed-design/cli@latest docs react
```
카테고리/섹션까지 지정:
```bash
npx @seed-design/cli@latest docs react/components
```
llms.txt 내용을 직접 가져오기 (`--raw`):
```bash
# 컴포넌트 문서 내용
npx @seed-design/cli@latest docs react/components/action-button --raw
# 전체 changelog
npx @seed-design/cli@latest docs react/updates/changelog --raw
# 특정 패키지 changelog
npx @seed-design/cli@latest docs react/updates/changelog/react --raw
# 특정 버전 이후 변경사항
npx @seed-design/cli@latest docs react/updates/changelog/react/1.2.9 --raw
```
`--raw` 옵션은 llms.txt 내용을 fetch하여 stdout으로 출력합니다. LLM 파이프나 스크립트에서 유용합니다. `--raw` 사용 시 쿼리가 필수입니다.
docs index에 없는 깊은 경로(패키지별 changelog, 버전별 changelog 등)도 `--raw` 모드에서는 직접 URL을 구성하여 fetch합니다.
출력 예시 (기본):
```text
action-button
- docs: https://seed-design.io/react/components/action-button
- llms.txt: https://seed-design.io/llms/react/components/action-button.txt
- snippet: https://raw.githubusercontent.com/daangn/seed-design/refs/heads/dev/docs/registry/react/ui/action-button.tsx
```
`snippet` 줄은 `ui` 또는 `breeze` 레지스트리 항목에만 출력됩니다. 파운데이션 등 스니펫이 없는 항목은 `docs`와 `llms.txt`만 출력됩니다.
오타가 포함된 경로를 입력하면 유사한 유효 경로를 제안합니다:
```text
react/component/action-buton: 문서를 찾을 수 없어요.
💡 이것을 의미했나요?
- react/components/action-button
```
## seed-design.json Settings
주요 필드:
- `path`: 스니펫 출력 루트 경로
- `framework`: 대상 프레임워크 (`react` | `lynx`, 기본값 `react`)
- `tsx`: TypeScript 변환 여부
- `rsc`: `"use client"` 유지 여부
- `telemetry`: 익명 사용 데이터 수집 여부
## Reference Links
- Commands: https://seed-design.io/llms/react/getting-started/cli/commands.txt
- Configuration: https://seed-design.io/llms/react/getting-started/cli/configuration.txt
````
### migration.md \[#migrationmd]
````md
# Migration (스니펫)
> 패키지 버전 업그레이드·호환 진단(react↔css, changelog, 마이그레이션 경로)은 `upgrade.md`를 참고하세요. 이 문서는 **스니펫**을 프로젝트 버전에 맞추고 파일 충돌을 해결하는 방법입니다.
## Pre-Check Compatibility
업데이트 전에 먼저 `compat` 명령으로 현재 설치된 스니펫의 버전 호환 상태를 확인합니다.
```bash
npx @seed-design/cli@latest compat
```
호환성 이슈가 있으면 종료 코드 `1`로 끝나므로 CI에서도 게이트로 사용할 수 있습니다. 이 명령은 **스니펫만** 검사합니다 — react↔css 패키지 간 호환은 아래 절차나 `upgrade.md` Step 2를 따르세요.
## Package Version Compatibility
`compat`은 **스니펫**이 요구하는 범위만 검사합니다. `@seed-design/react`·`@seed-design/css`·`@seed-design/stackflow` **패키지끼리** 맞는지는 아래 기준으로 판단합니다.
**SEED React 2 이상이면 `peerDependencies` 선언이 곧 정답입니다.** 2.0.0부터 strict SemVer를 따르므로 설치본의 선언을 그대로 신뢰하면 됩니다.
```bash
cat node_modules/@seed-design/react/package.json | grep -A5 peerDependencies
```
**1.x 구간은 선언에 상한이 없거나 누락된 경우가 있어 선언만으로 판단하면 안 됩니다.** 이 시기의 호환표와 알려진 비호환 조합은 아래 문서에 정리돼 있으니, 1.x 조합을 판정해야 하면 반드시 먼저 읽습니다.
- `https://seed-design.io/llms/react/updates/upgrade/v1.txt` (섹션: 패키지 간 버전 호환성)
핵심 규칙만 요약하면 이렇습니다. 정확한 하한과 예외는 위 문서의 표를 따릅니다.
- `@seed-design/css`는 `@seed-design/react`와 **같은 마이너 라인**이어야 하고, 표의 하한 이상이어야 합니다. 라인이 다르면(react 1.1.x + css 1.2.x) 호환되지 않습니다.
- `@seed-design/stackflow`는 1.2 라인이 없어 1.1 라인이 css 1.1·1.2를 함께 지원합니다. 단 WAAPI 경계(stackflow 1.1.22 / css 1.1.25·1.2.11)를 섞으면 화면 전환이 깨집니다.
- 표에 없는(문서 작성 이후 배포된) 버전은 위 `peerDependencies` 확인 방식으로 판정합니다.
버전 구간을 추측하지 말고 문서의 표를 실제로 읽고 대조합니다.
## Install Compatible Snippets
프로젝트에 설치된 SEED 버전과 맞는 스니펫이 필요하면 버전 옵션을 사용합니다. CLI가 해당 버전이 배포된 레지스트리 주소를 자동으로 찾아줍니다.
```bash
npx @seed-design/cli@latest add --seed-react-version 1.2 ui:action-button
```
`add-all`도 동일하게 동작합니다.
```bash
npx @seed-design/cli@latest add-all --seed-react-version 1.2 ui
```
레지스트리 주소를 직접 알고 있다면 `--baseUrl`로 지정할 수도 있습니다.
```bash
npx @seed-design/cli@latest add --baseUrl https://v1-2.seed-design.io ui:action-button
```
## Resolve Custom File Conflicts
CLI는 파일 내용이 다르면 diff를 보여주고 아래 중 하나를 선택하게 합니다.
1. `overwrite`: 기존 파일을 새 내용으로 덮어쓰기
2. `backup`: 기존 파일을 `legacy-<파일명>-`로 백업 후 교체
3. `skip`: 현재 파일 유지
비대화형(CI·스크립트)에서는 `--on-diff` 플래그로 미리 정합니다.
```bash
npx @seed-design/cli@latest add --on-diff backup ui:action-button
```
`--on-diff`는 `overwrite` | `backup`만 받습니다. `skip`은 인터랙티브 선택에서만 가능합니다.
## Decision Guide
- 커스텀 변경이 거의 없고 최신 스니펫 기준으로 재정렬할 때: `overwrite`
- 커스텀 변경을 보존하면서 안전하게 이전할 때: `backup`
- 레거시 구현을 당장 유지하고 점진 전환할 때: `skip`
## Recommended Flow
1. `compat`으로 현재 불일치 항목을 먼저 파악합니다.
2. 대상 컴포넌트를 작은 단위로 나눠서 버전 옵션(`--seed-react-version`)으로 업데이트합니다.
3. 충돌 파일은 우선 `backup`을 선택해 안전망을 확보합니다.
4. 동작/스타일 검증 후 필요하면 백업 파일의 커스텀을 수동 반영합니다.
````
### upgrade.md \[#upgrademd]
````md
# Upgrade & Compatibility Diagnosis
## Overview
업그레이드 진단은 CLI 프리미티브(`docs`, `compat`)를 조합하여 수행합니다. **CLI는 데이터 fetch를 담당하고, 이 스킬은 해석·판단·경로 제시를 담당합니다.**
다루는 세 가지:
- **패키지 간 호환**: 설치된 `@seed-design/react`와 `@seed-design/css`가 서로 맞는지 — **CLI가 판정하지 않습니다.** 2.x는 peer 선언, 1.x는 v1 호환표로 이 스킬이 판단합니다 (Step 2)
- **스니펫 호환**: 설치된 스니펫이 현재 패키지 버전을 만족하는지 (`compat`)
- **버전 업그레이드**: 현재 → 목표 버전 사이의 변경사항과 마이그레이션 경로 (`docs ... changelog`)
소비자용 업그레이드 문서는 https://seed-design.io/react/updates/upgrade 를 참고하세요.
SDK·공유 라이브러리 저자용 문서는 https://seed-design.io/react/getting-started/library-authors 를 참고하세요.
## 2.0 전후 버저닝 정책 (먼저 판단)
SEED는 **2.0을 분기점**으로 정책이 다르므로 진단 방식도 달라집니다.
| 구간 | 정책 | 진단 방식 |
| --- | --- | --- |
| **2.0 이상** | strict SemVer. breaking은 major에서만. minor·patch는 하위 호환. 의도적인 색상·디자인 변경도 major에서만(틀린 값 수정은 patch). | minor/patch 업그레이드는 안전. major를 넘을 때만 breaking을 확인. `peerDependencies` 선언을 신뢰. |
| **2.0 미만 (0.x·1.x)** | minor·patch에서도 breaking 가능. react↔css가 lockstep(같은 minor)이던 구간 존재. | v1 업그레이드 문서의 호환표로 react↔css 호환을 판단. minor 업그레이드도 breaking 확인 필요. |
`@seed-design/css/vars/component/typography`를 제외한 `@seed-design/css/vars/component/*` 경로는 SemVer 보장 대상이 아닙니다. rootage component spec 변경에 따라 minor·patch에서도 이름이나 구조가 바뀔 수 있으므로, 프로젝트 영향도 분석에서 직접 import 여부를 확인합니다.
## Changelog 경로 규칙 (반드시 준수)
changelog fetch URL을 조립할 때:
- **카테고리는 항상 `react`** — framework가 lynx여도 `react/updates/changelog/...`를 사용합니다. (`lynx/updates/changelog/...`는 404)
- **package slug = 패키지명에서 `@seed-design/` 제거**: `@seed-design/react`→`react`, `@seed-design/css`→`css`, `@seed-design/lynx-react`→`lynx-react`, `@seed-design/lynx-css`→`lynx-css`
| 목적 | 경로 |
| --- | --- |
| 특정 버전 이후 changelog | `react/updates/changelog/{slug}/{version}` |
| 버전 인덱스(사용 가능한 버전 목록) | `react/updates/changelog/{slug}` |
| 전체 changelog(모든 패키지) | `react/updates/changelog` |
## Workflow
### Step 1: 패키지와 버전 결정
사용자의 요청에서 **어떤 패키지**의 **어떤 버전부터** 확인할지 파악합니다.
```text
사용자 요청 분석
├─ 패키지·버전 모두 명확함 (예: "react 1.2.5에서 최신까지") → Step 2
├─ 패키지만 명확함 (예: "react 업그레이드 변경사항")
│ ├─ 프로젝트 환경 있음 → package.json에서 버전 확인
│ └─ 없음 → 사용자에게 현재 버전 질문
├─ 둘 다 불명확함 (예: "seed-design 업그레이드하고 싶어")
│ ├─ 프로젝트 환경 있음 → package.json의 @seed-design/* 전체 확인
│ └─ 없음 → 패키지 범위(전체/특정) → 버전 순서로 질문
└─ 특정 범위 지정 (예: "1.2.5에서 1.2.7까지") → from으로 fetch 후 Step 4에서 필터
```
**버전 확인**: **실제로 설치된 버전**을 읽습니다. `package.json`의 `^1.1.0`은 "1.1.0이 설치됨"이 아니라 "1.1.x를 받아들임"이라, 이걸 from으로 쓰면 이미 적용된 변경까지 마이그레이션 대상으로 잘못 보고합니다.
```bash
cat node_modules/@seed-design/react/package.json | grep '"version"'
```
**fallback**: node_modules나 lockfile을 읽을 수 없을 때만 선언 범위의 하한을 from으로 씁니다(`^1.1.0`→`1.1.0`). 이 경우 결과가 과다 보고일 수 있음을 함께 안내합니다.
**질문 원칙**: 추측 금지(잘못된 패키지/버전은 무의미한 결과). 한 번에 하나씩. 프로젝트 환경이 있으면 package.json에서 읽어 질문 최소화.
### Step 2: 현재 호환 진단
**패키지끼리(react↔css)의 호환은 CLI가 판정하지 않습니다.** `compat`은 설치된 **스니펫**이 요구하는 범위만 검사합니다.
```bash
npx @seed-design/cli@latest compat --json
```
- `--json`의 `snippets.issues`에 스니펫 호환 위반이 담깁니다. 사람용 출력은 `--json` 없이.
패키지 간 호환은 아래 기준으로 직접 판단합니다.
**2.0 이상 — `peerDependencies` 선언이 정답입니다.** strict SemVer를 따르므로 설치본의 선언을 그대로 신뢰합니다.
```bash
cat node_modules/@seed-design/react/package.json | grep -A5 peerDependencies
```
**1.x — 선언만으로 판단하면 안 됩니다.** 상한이 없거나 누락된 구간이 있어, 선언은 통과하지만 실제로는 스타일이 어긋나는 조합이 있습니다. 버전별 호환표와 알려진 비호환 조합을 아래 문서에서 읽고 대조합니다. 구간을 추측하지 말고 표를 실제로 확인하세요.
- `https://seed-design.io/llms/react/updates/upgrade/v1.txt` (섹션: 패키지 간 버전 호환성)
요약하면 `css`는 `react`와 **같은 마이너 라인**이면서 표의 하한 이상이어야 하고, `stackflow`는 1.2 라인이 없어 css 두 라인을 함께 지원하되 WAAPI 경계(stackflow 1.1.22 / css 1.1.25·1.2.11)를 섞으면 안 됩니다. 정확한 하한과 예외는 표를 따릅니다.
> lynx 계열(`@seed-design/lynx-react`·`lynx-css`)은 이 호환표의 대상이 아닙니다. 스니펫 검사와 changelog 기반 진단(Step 3 이후)으로 진행합니다.
### Step 3: Changelog fetch
위 **경로 규칙**에 따라 조립합니다.
```bash
npx @seed-design/cli@latest docs react/updates/changelog/react/{from버전} --raw
```
이 엔드포인트는 **from 버전 이후부터 최신까지** 모든 변경을 반환합니다(응답 최상단이 최신). 별도로 최신 버전을 조회할 필요가 없습니다.
**버전이 존재하지 않으면(404 등)**: 버전 인덱스(`react/updates/changelog/{slug}`)로 사용 가능한 버전을 확인하고 사용자에게 올바른 버전을 안내합니다. 추측하지 마세요.
### Step 4: target 버전까지 필터 (필요 시)
엔드포인트는 "from → latest"를 반환하므로, 사용자가 특정 target까지만 원하면 그보다 높은 섹션을 제외합니다. 각 `## {version}` 섹션을 SemVer로 비교해 **target보다 높은(>) 버전 섹션을 제거**합니다. (예: 1.2.5→1.2.7 요청 시 2.0.0·1.2.10·1.2.8 제외, 1.2.6·1.2.7만 사용.)
changelog 섹션 형식: `## {version}` 아래 `### Major Changes` / `### Minor Changes` / `### Patch Changes` / `### Updated Dependencies`.
### Step 5: 마이그레이션 경로 구성
목표까지 가는 경로를 구성합니다.
- **breaking 경계**: changelog의 Major/Minor Changes와 "BREAKING CHANGE"·"재설치 필요" 표시를 모읍니다. 1.x 구간의 경계(1.0.0·1.1.0·1.2.0)는 v1 업그레이드 문서에 구간별로 정리돼 있습니다.
- **재설치 snippet**: 경계에서 재설치가 필요한 컴포넌트는 `add ui:{component}`로 다시 받도록 안내합니다.
- **react↔css 함께 올리기**: 1.x 구간을 넘나들면 react와 css를 호환되는 버전으로 **함께** 올려야 합니다(한쪽만 올리면 클래스네임이 어긋나 스타일이 깨짐). Step 2의 호환 범위를 사용합니다.
- **component vars 직접 import 확인**: `@seed-design/css/vars/component/typography`를 제외한 `@seed-design/css/vars/component/*` 사용처가 있으면 SemVer 비보장 경로로 분류하고, 공개 API나 런타임 로직 의존을 제거하도록 안내합니다.
### Step 6: 프로젝트 영향도 분석 (선택)
프로젝트 환경이 있을 때만 수행합니다. changelog에서 언급된 컴포넌트/API를 프로젝트 코드에서 grep:
- **Breaking/Minor Changes**: 변경된 컴포넌트·prop·API 시그니처를 grep
- **Patch Changes**: 버그 수정으로 인한 동작 변경 영향 확인
- **Updated Dependencies**: 하위 패키지 변경이 직접 import에 영향을 주는지 확인
- **Component vars**: `@seed-design/css/vars/component/*` 직접 import 확인(`typography` 제외)
### Step 7: 보고 (상황별 형식)
**A. 업그레이드 필요 (breaking 있음)**
```md
## 업그레이드 진단: @seed-design/react {현재} → {목표}
### 수정 필요
- [변경]: [영향 파일·라인] — [수정 방법]
### 확인 권장
- [변경]: [관련 파일] — [확인 포인트]
### 영향 없음
- [변경]: 프로젝트에서 사용하지 않음
```
**B. 이미 최신**
```md
@seed-design/react: {버전} = 최신. 업그레이드 불필요.
(설치된 스니펫 외에 모든 registry 항목까지 검사하려면 `compat --all`)
```
**C. 다패키지** — 패키지별 요약 테이블 + 통합 breaking + 단계별 경로
```md
| 패키지 | 현재 | 목표/최신 | 호환 | 액션 |
| --- | --- | --- | --- | --- |
| @seed-design/react | ... | ... | ✓/⚠ | ... |
| @seed-design/css | ... | ... | ✓/⚠ | ... |
```
### Step 8: 업그레이드 안내
1단계에서 감지한 패키지 매니저에 맞춰 안내합니다 (아래는 bun 예시).
```bash
bun add @seed-design/react@{react목표} @seed-design/css@{css목표}
```
**두 패키지는 버전 번호가 다릅니다**(예: react 2.0.4 ↔ css 2.2.1). 같은 번호를 맞춰 설치하면 없는 버전이거나 호환되지 않는 조합이 됩니다. css 목표 버전은 Step 2의 기준으로 따로 산출하세요 — 2.x는 react의 peer 선언 범위에서, 1.x는 v1 호환표에서.
1.x 구간은 react·css를 함께 올립니다. 재설치가 필요한 snippet은 `add ui:{component}`로. 업그레이드 후 다시 `compat`으로 스니펫을 검증합니다.
## CLI Primitives
| 명령어 | 역할 |
| --- | --- |
| `compat --json` | 설치된 스니펫의 호환 진단(구조화 출력) |
| `compat --all` | 설치 여부와 무관하게 모든 registry 항목의 스니펫 호환 검사 |
| `docs react/updates/changelog/{slug}/{ver} --raw` | from 버전 이후 changelog |
| `docs react/updates/changelog/{slug} --raw` | 버전 인덱스(버전 목록) |
| `docs react/updates/changelog --raw` | 전체 changelog(모든 패키지) |
## Decision Guide
- 최신과 동일 → "이미 최신".
- **2.0 이상**: minor/patch는 안전(strict semver). major를 넘을 때 breaking 확인.
- **2.0 미만**: minor도 breaking 가능 → 항상 changelog 확인 + react↔css 호환을 v1 호환표로 확인.
- react↔css는 호환 범위 안에서 **함께** 올립니다.
- Breaking이 있으면 수정 후 업그레이드.
- `@seed-design/css/vars/component/typography`를 제외한 component vars 직접 import는 제거 또는 대체를 권장합니다.
## SDK·공유 라이브러리 진단
SDK·공유 라이브러리는 `/react/getting-started/library-authors` 문서의 기준을 함께 적용합니다.
- `@seed-design/*`는 `peerDependencies`로 선언하고 `dependencies`에 넣지 않습니다.
- 빌드 결과물에 `@seed-design/*`를 포함하지 않도록 external 처리합니다.
- 라이브러리 코드에서 `@seed-design/css/*.css`를 직접 import하지 않습니다.
- SEED 2.0 transition에서는 검증 후 `~1.2.0 || ^2.0.0` 같은 dual-compat 범위로 프로젝트 전환을 막지 않도록 합니다. 1.x 구간은 minor에 breaking이 있을 수 있어 caret(`^1.2.0`)이 아니라 tilde를 씁니다.
## 다패키지 진단
프로젝트의 `@seed-design/*` 각각에 대해 Step 1~5를 수행하고 Step 7-C 형식으로 통합 보고합니다. react는 css를 의존하므로 css 변경이 react로 전파될 수 있음을 고려합니다.
````