Skill

---
name: seed-design
description: SEED Design 통합 가이드. 공통 컴포넌트 스펙과 파운데이션을 공식 문서에서 찾고, React·Lynx 프로젝트의 구현·설치·CLI·마이그레이션을 대상 플랫폼에 맞게 안내하며, 지원되는 플랫폼의 사용 상태를 Doctor로 진단한다. SEED Design 관련 질문, 컴포넌트 사용법, 색상·타이포·스페이싱, 셋업, 스니펫, 업그레이드, "잘 쓰고 있나?", "뭘 고쳐야 하나?" 같은 요청이면 이 스킬을 사용한다.
user-invocable: true
argument-hint: "[질문 또는 주제]"
---

# SEED Design

SEED Design의 공식 문서와 CLI를 단일 원천으로 사용합니다. 이 스킬에는 문서 내용을 복사하지 않고, **공통 디자인 지식 → 플랫폼 구현 → 플랫폼별 Doctor**로 이어지는 탐색·판정 절차만 둡니다.

## 1. 요청을 먼저 분류

프로젝트를 조사하기 전에 요청을 다음 중 하나로 분류합니다.

| 분류 | 예 | 플랫폼 판별 |
|---|---|---|
| 공통 컴포넌트 스펙·Foundations | Anatomy, Properties, Guidelines, 색상, 타이포그래피, 스페이싱 | 불필요 |
| 플랫폼 구현 | 사용법, Props, 설치, 셋업, 스니펫, 코드 작성, CLI 실행 | 필요 |
| Doctor·마이그레이션 | 사용 상태 진단, deprecated, 호환성, 업그레이드 | 필요 |

공통 스펙이나 Foundations만 묻는다면 프로젝트가 없어도 바로 공통 문서를 읽습니다. 구현 코드까지 함께 묻는다면 공통 문서를 먼저 읽은 다음, 플랫폼을 판별하고 해당 플랫폼 문서를 결합합니다.

## 2. 플랫폼 판별

플랫폼에 따라 결과가 달라지는 요청에만 아래 순서를 적용합니다.

1. **사용자가 명시한 플랫폼**: React 또는 Lynx
2. **대상 워크스페이스의 설정**: `seed-design.json.framework`
3. **대상 워크스페이스의 직접 의존성**
   - React: `@seed-design/react`, `@seed-design/css`
   - Lynx: `@seed-design/lynx-react`, `@seed-design/lynx-css` 또는 `@lynx-js/react`

높은 순위의 명확한 단서를 낮은 순위의 단서로 덮어쓰지 않습니다. 단, 같은 대상 안에서 설정과 의존성이 충돌한다면 설정이 낡았을 수 있으므로 사용자에게 확인합니다.

모노레포에서는 루트 `package.json`만 보지 말고 요청 대상 워크스페이스를 먼저 찾습니다. 루트 요청에서 React와 Lynx 워크스페이스가 함께 발견되거나 대상 경로가 불명확하면, 구현·설치·Doctor를 시작하기 전에 어느 워크스페이스 또는 플랫폼인지 묻습니다.

단서가 없거나 한 단계에서 여러 플랫폼이 동시에 잡혀도 사용자에게 묻습니다. **불확실한 상황에서 React를 기본값으로 사용하지 않습니다.** 이는 에이전트의 문서 라우팅 규칙이며, 기존 CLI의 공개 동작이나 `seed-design.json` 기본값을 바꾸는 규칙이 아닙니다.

플랫폼 판별 뒤에는 다음 프로젝트 정보도 필요할 때만 수집합니다.

- `seed-design.json`의 `path`와 해당 디렉토리의 `@file` 헤더 파일 → 스니펫 설치 여부
- 설치된 `@seed-design/*` 버전
- 번들러 설정 (`vite.config`, `rsbuild.config`, `webpack.config` 등)
- lock 파일로 판별한 패키지 매니저 (`bun` → `pnpm` → `yarn` → `npm`)

## 3. 공식 문서 라우팅

문서 경로를 추측하지 말고 완전히 한정된 `docs` CLI 경로를 사용합니다.

| 필요한 정보 | 먼저 실행할 명령 |
|---|---|
| 공통 컴포넌트 스펙 | `npx @seed-design/cli@latest docs docs/components/{id} --raw` |
| Foundations | `npx @seed-design/cli@latest docs docs/foundations/{topic} --raw` |
| React 구현 | `npx @seed-design/cli@latest docs react/components/{id} --raw` |
| Lynx 구현 | `npx @seed-design/cli@latest docs lynx/components/{id} --raw` |

`{topic}`은 `color`, `color-role`, `typography`, `spacing`, `radius`, `elevation`, `motion`처럼 공식 인덱스에 있는 실제 id를 사용합니다. 문서 URL이 `/foundations/color/color-role`처럼 중첩돼 있어도 CLI id는 `color-role`일 수 있으므로 URL 경로를 그대로 넣지 않습니다.

- 공통 컴포넌트 인덱스: `https://seed-design.io/components/llms.txt`
- Foundations 인덱스: `https://seed-design.io/foundations/llms.txt`
- React 구현 인덱스: `https://seed-design.io/react/llms.txt`
- Lynx 구현 인덱스: `https://seed-design.io/lynx/llms.txt`

### 컴포넌트 답변 순서

1. 스펙 질문이면 공통 컴포넌트 문서만 읽습니다.
2. 구현 질문이면 플랫폼을 판별하고 해당 플랫폼 문서를 읽습니다.
3. 스펙과 구현을 함께 묻는다면 공통 문서를 먼저 읽고, 판별된 플랫폼 문서를 이어서 읽습니다.
4. 공통 문서 id와 구현 문서 id가 다르면 공통 문서의 Platform 표와 플랫폼 구현 인덱스로 실제 id를 찾습니다.
5. 선택한 플랫폼 문서나 registry 항목이 없으면 그 플랫폼의 구현·문서가 없다고 알립니다. 다른 플랫폼 문서로 대체하지 않습니다.

스니펫이 필요하면 선택한 플랫폼 registry만 사용합니다.

```text
https://seed-design.io/__registry__/{react|lynx}/{registryId}/index.json
https://seed-design.io/__registry__/{react|lynx}/{registryId}/{itemId}.json
```

개별 스니펫 경로는 `{itemId}/index.json`이 아니라 `{itemId}.json`입니다.

### CLI 문서

CLI 명령어와 설정의 canonical 문서는 현재 React 문서 트리 아래에 있습니다.

- `/llms/react/getting-started/cli/commands.txt`
- `/llms/react/getting-started/cli/configuration.txt`

이 위치는 문서 정보 구조일 뿐 CLI 지원 범위를 뜻하지 않습니다. `init`, `add`, `add-all`, `compat`, `docs`와 `seed-design.json.framework`, `--framework react|lynx`는 두 플랫폼을 지원합니다. 실제 실행 대상은 위 플랫폼 판별 결과에 맞추고, 필요한 경우 `--framework`를 명시합니다. `--seed-react-version`은 이름 그대로 React 전용입니다.

## 4. 판단이 필요한 절차

| 요청 | 읽을 참조 |
|---|---|
| 스니펫 버전 맞추기, 파일 충돌, 패키지 호환 | [migration.md](references/migration.md) |
| changelog 해석과 업그레이드 경로 | [upgrade.md](references/upgrade.md) |
| 코드 사용 상태 진단 | [doctor.md](references/doctor.md) |

마이그레이션과 업그레이드도 플랫폼을 먼저 판별합니다. 참조 파일의 React 전용 옵션이나 호환표를 Lynx에 적용하지 말고, 선택된 플랫폼의 패키지와 changelog만 대조합니다.

Doctor 요청은 [doctor.md](references/doctor.md)의 지원표를 먼저 확인합니다.

- React Doctor: [doctor-react.md](references/doctor-react.md)를 함께 읽고 프로필에 적힌 룰만 실행합니다.
- Lynx Doctor: 현재 미지원입니다. React 프로필이나 React 룰을 대신 실행하지 말고 지원 범위를 알립니다.

Doctor는 문제를 찾는 진단이고, `upgrade.md`는 실제로 버전을 올리는 절차입니다. 진단이 버전 격차를 알려도 사용자가 수정을 요청하기 전에는 업그레이드를 실행하지 않습니다.

## 5. 코드 작성과 기존 코드 진단

`rules/`의 룰은 SEED 코드를 작성할 때 지킵니다. Doctor에서는 선택된 플랫폼 프로필이 활성화한 룰만 소급 적용합니다.

- [outdated-version](rules/outdated-version.md): 직접 설치한 패키지 버전 격차
- [snippet-generation](rules/snippet-generation.md): 설치 스니펫과 선택된 플랫폼 registry의 세대 차이
- [no-deprecated-component](rules/no-deprecated-component.md): deprecated 컴포넌트·스니펫·토큰·옵션
- [component-guidelines](rules/component-guidelines.md): 공통 디자인 문서에서 도출한 기준과 선택된 플랫폼 구현의 대조

토큰은 문서·CSS·플랫폼 API에서 표기가 달라질 수 있습니다. 공통 Foundations 문서에서 의미와 토큰을 확인한 뒤, 코드 표기는 선택된 플랫폼 구현 문서에서 확인합니다. 한 플랫폼의 코드 표기를 다른 플랫폼에 복사하지 않습니다.

## 6. 응답과 실행 원칙

- 공식 문서를 실제로 읽고 근거 링크와 함께 답합니다.
- 설치·실행 명령은 대상 프로젝트의 패키지 매니저에 맞춥니다.
- read-only 진단과 실제 수정 요청을 구분합니다.
- 없는 경로나 API를 추측하지 않습니다.
- 작업이 끝나면 현재 맥락에 맞는 다음 단계만 짧게 제안합니다.

# 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-<파일명>-<timestamp>`로 백업 후 교체
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 & 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 를 참고하세요.

**`references/doctor.md`와의 경계**: 무엇이 얼마나 뒤졌고 코드의 어디가 문제인지 알아내는 것은 진단(`references/doctor.md`)이고, **실제로 올리는 절차가 여기**입니다. 진단이 "major 하나 뒤졌다"까지 말하면 그다음을 이 문서가 받습니다.

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

- 호환 위반이 있으면 종료 코드 `1`로 끝납니다. 범위를 좁히려면 `-c <component>`, 전체 registry를 보려면 `-a`를 씁니다.

패키지 간 호환은 아래 기준으로 직접 판단합니다.

**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` | 설치된 스니펫의 호환 진단 (위반 시 종료 코드 1) |
| `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로 전파될 수 있음을 고려합니다.