Skill

---
name: seed-design
description: SEED Design 통합 가이드. 프로젝트 셋업, 컴포넌트 탐색/사용, 파운데이션(색상·타이포·스페이싱) 활용, 테마/스타일링, CLI 워크플로우(init/add/add-all/compat/docs/upgrade), 스니펫 버전 호환성, 업그레이드 진단까지 커버. 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` |
| 패키지 업그레이드 진단 | `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 | 컴포넌트 목록, 설치/스타일링 가이드 |
| Design | https://seed-design.io/docs/llms.txt | 파운데이션(색상, 타이포, 스페이싱 등) |

### 개별 문서 조회

```text
https://seed-design.io/llms/react/components/{component-name}.txt
https://seed-design.io/llms/docs/foundation/color/color-system.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/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` | 패키지 업그레이드 진단 | 업그레이드 질문 시 |

# 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>` 태그에 테마 속성 추가:

```html
<html data-seed-color-mode="system" data-seed-user-color-scheme="light">
```

- `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 <ActionButton>시작하기</ActionButton>;
}
```

## 셋업 완료 후 다음 단계

- 컴포넌트 탐색/추가: `references/components.md` 참조
- 파운데이션(색상, 타이포, 스페이싱) 활용: `references/foundation.md` 참조
- 전체 React 문서 인덱스: https://seed-design.io/react/llms.txt
- 디자인 가이드라인 인덱스: https://seed-design.io/docs/llms.txt

# 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

SEED Design의 파운데이션 — 색상, 타이포그래피, 스페이싱, 테마 시스템을 활용하는 가이드입니다.

## 파운데이션 문서 참조

디자인 가이드라인의 전체 목록은 llms.txt에서 확인할 수 있습니다:

```text
https://seed-design.io/docs/llms.txt
```

## 주요 토픽별 llms.txt

상세 정보가 필요하면 WebFetch로 해당 URL을 읽어옵니다.

### 색상

| 토픽 | URL |
|------|-----|
| 색상 시스템 개요 | https://seed-design.io/llms/docs/foundation/color/color-system.txt |
| 역할 기반 색상 | https://seed-design.io/llms/docs/foundation/color/color-role.txt |
| 팔레트 | https://seed-design.io/llms/docs/foundation/color/palette.txt |

핵심 원칙: 역할 기반 색상(`--seed-color-fg-*`, `--seed-color-bg-*`, `--seed-color-stroke-*`)을 우선 사용합니다. 팔레트 색상(`--seed-color-palette-*`)은 역할 기반으로 커버되지 않는 예외 상황에만 사용합니다.

### 타이포그래피

| 토픽 | URL |
|------|-----|
| 타이포그래피 개요 | https://seed-design.io/llms/docs/foundation/typography/overview.txt |

핵심 원칙: 스케일은 t1(가장 작음)부터 t10(가장 큼). CSS 변수 `--seed-font-size-t{n}`, `--seed-line-height-t{n}`, `--seed-font-weight-*`로 사용합니다.

### 스페이싱, 테마, 기타

| 토픽 | URL |
|------|-----|
| 스페이싱 | https://seed-design.io/llms/docs/foundation/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/docs/foundation/elevation.txt |
| Radius (모서리) | https://seed-design.io/llms/docs/foundation/radius.txt |
| Motion (애니메이션) | https://seed-design.io/llms/docs/foundation/motion.txt |
| Gradient | https://seed-design.io/llms/docs/foundation/gradient.txt |

# 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/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
```

### 5) Upgrade Changelog

패키지의 현재 버전과 최신 버전 사이의 변경사항을 확인합니다.

전체 패키지 한 번에 조회:

```bash
npx @seed-design/cli@latest upgrade --all
```

특정 패키지만 조회:

```bash
npx @seed-design/cli@latest upgrade react
```

### 6) 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
```

출력 예시:

```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/ui/action-button.tsx
```

`snippet` 줄은 `ui` 또는 `breeze` 레지스트리 항목에만 출력됩니다. 파운데이션 등 스니펫이 없는 항목은 `docs`와 `llms.txt`만 출력됩니다.

오타가 포함된 경로를 입력하면 유사한 유효 경로를 제안합니다:

```text
react/component/action-buton: 문서를 찾을 수 없어요.

💡 이것을 의미했나요?
   - react/components/action-button
```

## seed-design.json Settings

주요 필드:

- `path`: 스니펫 출력 루트 경로
- `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

## Pre-Check Compatibility

업데이트 전에 먼저 `compat` 명령으로 현재 설치된 스니펫의 버전 호환 상태를 확인합니다.

```bash
npx @seed-design/cli@latest compat
```

호환성 이슈가 있으면 종료 코드 `1`로 끝나므로 CI에서도 게이트로 사용할 수 있습니다.

## Install Compatible Snippets

프로젝트의 `@seed-design/react` 버전과 맞는 스니펫이 필요하면 `--baseUrl`을 사용합니다.

```bash
npx @seed-design/cli@latest add --baseUrl https://1-0.seed-design.pages.dev ui:action-button
```

```bash
npx @seed-design/cli@latest add-all --baseUrl https://1-1.seed-design.pages.dev ui
```

## Resolve Custom File Conflicts

CLI는 파일 내용이 다르면 diff를 보여주고 아래 중 하나를 선택하게 합니다.

1. `overwrite`: 기존 파일을 새 내용으로 덮어쓰기
2. `backup`: 기존 파일을 `legacy-<파일명>-<timestamp>`로 백업 후 교체
3. `skip`: 현재 파일 유지

## Decision Guide

- 커스텀 변경이 거의 없고 최신 스니펫 기준으로 재정렬할 때: `overwrite`
- 커스텀 변경을 보존하면서 안전하게 이전할 때: `backup`
- 레거시 구현을 당장 유지하고 점진 전환할 때: `skip`

## Recommended Flow

1. `compat`으로 현재 불일치 항목을 먼저 파악합니다.
2. 대상 컴포넌트를 작은 단위로 나눠서 `--baseUrl`로 업데이트합니다.
3. 충돌 파일은 우선 `backup`을 선택해 안전망을 확보합니다.
4. 동작/스타일 검증 후 필요하면 백업 파일의 커스텀을 수동 반영합니다.

# Upgrade Diagnosis

## Overview

`upgrade` 명령은 프로젝트에 설치된 `@seed-design/*` 패키지의 현재 버전과 최신 버전 사이의 변경사항(changelog)을 가져옵니다. 기본은 인터랙티브 UI로 출력되며, `--raw` 사용 시 순수 마크다운으로 출력됩니다.

## Upgrade Diagnosis Workflow

이 스킬이 호출되면 아래 순서로 프로젝트 영향도를 진단합니다.

### Step 1: Changelog 수집

사용자가 특정 패키지를 언급했는지에 따라 명령이 달라집니다.

**패키지 미지정 → 전체 패키지 탐색:**

```bash
npx @seed-design/cli@latest upgrade --all --raw
```

`--all --raw` 옵션으로 설치된 모든 `@seed-design/*` 패키지의 changelog를 순수 마크다운으로 한 번에 수집합니다. 최신 버전인 패키지는 "already up to date"로 표시됩니다.

**특정 패키지 지정 → 해당 패키지만 탐색:**

```bash
npx @seed-design/cli@latest upgrade react --raw
npx @seed-design/cli@latest upgrade css --raw
```

사용자가 "react 패키지만 확인해줘" 등으로 특정 패키지를 언급하면 해당 패키지만 조회합니다.

### Step 2: 프로젝트 코드 탐색

changelog에서 언급된 컴포넌트/API를 기준으로 사용자 프로젝트에서 해당 코드를 검색합니다.

- **Breaking Changes / Minor Changes**: 변경된 컴포넌트 이름, prop 이름, API 시그니처를 프로젝트에서 grep
- **Patch Changes**: 버그 수정으로 인한 동작 변경이 프로젝트에 영향을 주는지 확인
- **Updated Dependencies**: 하위 패키지 변경이 프로젝트의 직접 import에 영향을 주는지 확인

### Step 3: 영향도 보고

changelog 항목별로 프로젝트 영향 여부를 분류하여 보고합니다.

보고 형식:

```md
## 업그레이드 진단: @seed-design/react {현재버전} → {최신버전}

### 수정 필요
- [변경 내용]: [영향받는 파일과 라인] — [수정 방법]

### 확인 권장
- [변경 내용]: [관련 파일] — [확인 포인트]

### 영향 없음
- [변경 내용]: 프로젝트에서 사용하지 않음
```

전체 패키지 탐색 시 패키지별로 위 형식을 반복합니다. 이미 최신인 패키지는 간략히 표시합니다.

### Step 4: 업그레이드 안내

진단 결과에 따라 업그레이드 명령을 안내합니다.

```bash
bun add @seed-design/react@{최신버전}
```

수정이 필요한 항목이 있으면 업그레이드 전후로 어떤 코드를 바꿔야 하는지 구체적인 diff를 제시합니다.

## Commands

```bash
# 전체 패키지 changelog 조회 (LLM/스크립트용)
npx @seed-design/cli@latest upgrade --all --raw

# 특정 패키지만 조회 (LLM/스크립트용)
npx @seed-design/cli@latest upgrade react --raw

# 인터랙티브 UI로 확인
npx @seed-design/cli@latest upgrade --all
npx @seed-design/cli@latest upgrade react
```

### Options

- `--all`: 설치된 모든 @seed-design 패키지의 변경사항을 확인
- `--raw`: UI 없이 순수 마크다운 출력. LLM 파이프에 유용
- `--cwd <path>`: 작업 디렉토리 지정 (기본: 현재 디렉토리)
- `--baseUrl <url>`: changelog를 가져올 docs 서버 URL (기본: https://seed-design.io)

## Decision Guide

- 최신 버전과 동일하면 "이미 최신 버전" 으로 종료됩니다.
- Breaking Changes가 있으면 반드시 수정 후 업그레이드합니다.
- Patch 릴리스는 대체로 안전하지만, 회귀 가능성을 고려해 변경사항을 확인한 후 업그레이드하는 것을 권장합니다.
- Updated Dependencies에서 하위 패키지를 직접 import하는 경우 해당 변경사항도 확인합니다.