Seed Design

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단계: 상황 분류 및 분기

파악한 상태와 사용자의 질문에 따라 적절한 가이드로 분기합니다.

사용자가 명시적으로 주제를 말한 경우 프로젝트 분석을 건너뛰고 해당 시나리오로 직행해도 됩니다.

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/스니펫 링크 한 번에 조회:

  npx @seed-design/cli@latest docs {component-name}

• 사용자가 원하면 CLI 명령어를 직접 실행 (init, add 등)

4단계: 다음 단계 제안

현재 작업이 끝나면 자연스럽게 다음 단계를 안내합니다.

• 셋업 완료 → "이제 컴포넌트를 추가해볼까요?"
• 컴포넌트 추가 → "테마 설정이나 다른 컴포넌트도 필요하신가요?"
• 파운데이션 안내 → "실제 코드에서 이렇게 사용하면 됩니다"

정보 조회 도구

SEED Design의 모든 문서에는 llms.txt 형태의 LLM 최적화 문서가 있습니다. 컴포넌트 목록, 파운데이션 가이드 등 최신 정보가 필요하면 llms.txt를 WebFetch로 읽어옵니다.

llms.txt 인덱스

개별 문서 조회

https://seed-design.io/llms/react/components/{component-name}.txt
https://seed-design.io/llms/docs/foundation/color/color-system.txt

CLI docs 명령어

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

Components

SEED Design 컴포넌트를 탐색하고 사용하는 방법입니다.

컴포넌트 목록 확인

전체 컴포넌트 목록과 설명은 llms.txt에서 항상 최신 상태로 확인할 수 있습니다:

https://seed-design.io/react/llms.txt

이 URL을 WebFetch로 읽으면 모든 컴포넌트의 이름, 설명, 상세 문서 링크를 얻을 수 있습니다.

컴포넌트 상세 정보 조회

특정 컴포넌트의 props, 사용법, 예제를 알고 싶을 때:

1. CLI docs 명령어 (권장):

   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개 레지스트리로 나뉩니다:

컴포넌트 추가 방법

단일 컴포넌트

npx @seed-design/cli@latest add ui:action-button

여러 컴포넌트

npx @seed-design/cli@latest add ui:action-button ui:checkbox ui:switch

레지스트리 전체

npx @seed-design/cli@latest add-all ui

설치 후 import

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에서 확인할 수 있습니다:

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

주요 토픽별 llms.txt

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

색상

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

타이포그래피

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

Iconography

스페이싱, 테마, 기타

Getting Started

프로젝트에 SEED Design을 처음 도입할 때의 가이드입니다. 아래 예시는 npm 기준이며, 1단계에서 감지한 패키지 매니저에 맞춰 변환합니다.

최단 경로: 5분 안에 첫 컴포넌트 띄우기

1. 패키지 설치

npm install @seed-design/react @seed-design/css

2. seed-design.json 생성

CLI로 생성 (권장):

npx @seed-design/cli@latest init

또는 직접 생성:

{
  "rsc": false,
  "tsx": true,
  "path": "./seed-design"
}

주요 설정:

• rsc: React Server Components 사용 시 true → snippet에 "use client" 유지
• tsx: TypeScript 사용 시 true
• path: snippet이 설치될 디렉토리 경로

3. base.css import

앱의 엔트리 파일에 추가:

import "@seed-design/css/base.css";

4. tsconfig.json 경로 설정

{
  "compilerOptions": {
    "paths": {
      "seed-design/*": ["./seed-design/*"]
    }
  }
}

5. 번들러 플러그인 설정

번들러에 따라 설정이 다릅니다. 상세 내용은 llms.txt를 참조합니다.

Vite (권장)

npm install -D @seed-design/vite-plugin

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

npm install -D @seed-design/rsbuild-plugin

• 상세: https://seed-design.io/llms/react/getting-started/installation/rsbuild.txt

Webpack

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 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. 첫 컴포넌트 추가

npx @seed-design/cli@latest add ui:action-button

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

Migration

Pre-Check Compatibility

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

npx @seed-design/cli@latest compat

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

Install Compatible Snippets

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

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

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

업그레이드 진단은 CLI 프리미티브(docs, compat)를 조합하여 수행합니다. CLI는 데이터 fetch만 담당하고, 이 스킬이 해석과 분석을 담당합니다.

Upgrade Diagnosis Workflow

Step 1: 패키지와 버전 결정

사용자의 요청에서 어떤 패키지의 어떤 버전부터 변경사항을 확인할지 파악합니다. 아래 판단 트리를 따릅니다.

사용자 요청 분석
├─ 패키지와 버전 모두 명확함
│   예: "react 1.2.5에서 최신까지 변경사항 알려줘"
│   → 바로 Step 2로 진행
│
├─ 패키지는 명확하지만 버전이 불명확함
│   예: "react 패키지 업그레이드 변경사항 알려줘"
│   ├─ 프로젝트 환경이 있음 → package.json에서 버전 확인
│   └─ 프로젝트 환경이 없음 → 사용자에게 현재 버전 질문
│
├─ 패키지도 버전도 불명확함
│   예: "seed-design 업그레이드하고 싶어"
│   ├─ 프로젝트 환경이 있음 → package.json에서 설치된 @seed-design/* 패키지 전체 확인
│   └─ 프로젝트 환경이 없음 → 사용자에게 어떤 패키지/버전인지 질문
│
└─ 특정 버전 범위를 지정함
    예: "react 1.2.5에서 1.2.7까지 변경사항"
    → from 버전으로 fetch 후 Step 3에서 범위 필터링

프로젝트 환경에서 버전 확인 방법:

package.json을 직접 읽어 @seed-design/react, @seed-design/css 등의 버전을 확인합니다. package.json이 버전의 source of truth입니다.

사용자에게 질문이 필요한 경우:

패키지나 버전을 특정할 수 없으면 추측하지 말고 반드시 사용자에게 질문하여 명확한 답을 얻은 후 진행합니다.

질문 판단 흐름:

정보 부족 판단
├─ 패키지가 불명확함
│   → 먼저 사용자의 의도를 파악:
│   │
│   ├─ "전체 @seed-design 패키지의 변경사항을 모두 보고 싶으신가요,
│   │    아니면 특정 패키지(react, css 등)를 지정하실 수 있나요?"
│   │
│   ├─ 사용자가 "전체" → 프로젝트 환경이 있으면 package.json에서
│   │   설치된 @seed-design/* 패키지 전체에 대해 각각 진단
│   │
│   └─ 사용자가 특정 패키지 지정 → 해당 패키지로 진행
│
├─ 패키지는 명확하지만 버전이 불명확함 (프로젝트 환경 없음)
│   → "현재 사용 중인 @seed-design/{패키지} 버전이 어떻게 되나요?"
│   → 사용자 답변을 받은 후 해당 버전으로 진행
│
└─ 패키지도 버전도 불명확함 (프로젝트 환경 없음)
    → 위 두 질문을 순서대로 진행:
      1. 먼저 패키지 범위 확인 (전체 vs 특정)
      2. 그다음 버전 확인

질문 원칙:

• 추측하지 말 것 — 잘못된 패키지/버전으로 진행하면 무의미한 결과가 나옴
• 한 번에 하나씩 — 패키지와 버전을 동시에 묻지 말고 순서대로 확인
• 프로젝트 환경이 있으면 질문 최소화 — package.json에서 읽을 수 있는 정보는 직접 확인

Step 2: Changelog fetch

docs --raw 명령으로 changelog를 가져옵니다. Step 1에서 결정된 패키지와 버전에 따라 적절한 경로를 사용합니다.

# 전체 changelog (모든 패키지) — 패키지 목록 파악에도 사용
npx @seed-design/cli@latest docs react/updates/changelog --raw

# 특정 패키지의 버전 인덱스 (사용 가능한 버전 목록)
npx @seed-design/cli@latest docs react/updates/changelog/react --raw

# 특정 패키지의 특정 버전 이후 changelog (가장 일반적인 케이스)
npx @seed-design/cli@latest docs react/updates/changelog/react/1.2.5 --raw

버전이 결정된 경우 마지막 형태({package}/{version})를 사용합니다. 이 엔드포인트는 해당 버전 이후부터 최신까지의 변경사항을 반환합니다.

전체 패키지 목록 확인:

전체 changelog(react/updates/changelog --raw)의 ## @seed-design/{pkg} 헤더를 파싱하면 changelog를 제공하는 모든 패키지 목록을 얻을 수 있습니다. "전체 진단"이 필요한데 프로젝트 환경이 없는 경우(package.json에서 읽을 수 없는 경우) 이 방법으로 패키지 목록을 확인합니다.

프로젝트 환경이 있는 경우에는 package.json의 @seed-design/* 의존성이 곧 대상 패키지 목록이므로 전체 changelog를 fetch할 필요 없이 각 패키지별로 버전 지정 fetch를 사용합니다.

Step 3: 버전 범위 파싱 (필요 시)

llms.txt 엔드포인트는 "since version → latest" 형태로 응답합니다. 사용자가 특정 target 버전까지만 확인하고 싶은 경우 (예: 1.2.5 → 1.2.7), 마크다운에서 해당 버전 범위의 섹션만 추출합니다.

changelog 마크다운 형식:

# @seed-design/react — Changes since {version}

## {latest-version}
### Patch Changes
- ...

## {next-version}
### Patch Changes
- ...

각 ## {version} 섹션이 하나의 릴리즈입니다. target 버전이 있으면 해당 버전보다 높은 섹션만 필터링합니다.

Step 4: 프로젝트 영향도 분석 (선택)

프로젝트 환경이 있는 경우에만 수행합니다.

changelog에서 언급된 컴포넌트/API를 기준으로 프로젝트 코드를 검색합니다:

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

프로젝트 환경이 없으면 changelog 요약만 제공합니다.

Step 5: 영향도 보고

보고 형식:

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

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

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

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

프로젝트 환경이 없는 경우:

## @seed-design/react {from버전} → {to버전} 변경사항

### Breaking Changes
- ...

### Patch Changes
- ...

### Updated Dependencies
- ...

Step 6: 업그레이드 안내

프로젝트 환경이 있는 경우 업그레이드 명령을 안내합니다:

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

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

CLI Primitives

이 스킬이 조합하는 CLI 명령어:

Decision Guide

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

Usage

Core Commands

1) Initialization

npx @seed-design/cli@latest init

질문 없이 기본값으로 만들려면:

npx @seed-design/cli@latest init --yes

2) Add Snippets

npx @seed-design/cli@latest add ui:action-button

여러 항목 추가:

npx @seed-design/cli@latest add ui:action-button ui:alert-dialog

3) Add by Registry

npx @seed-design/cli@latest add-all ui

모든 레지스트리:

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

npx @seed-design/cli@latest compat

특정 항목만 검사:

npx @seed-design/cli@latest compat ui:action-button ui:alert-dialog

컴포넌트 shorthand 검사:

npx @seed-design/cli@latest compat -c action-button -c alert-dialog

모든 레지스트리 항목 검사:

npx @seed-design/cli@latest compat --all

5) Docs 조회

컴포넌트/파운데이션에 대한 문서 링크, LLM용 텍스트 링크, 스니펫 링크를 조회합니다.

인터랙티브 모드 (카테고리 → 섹션 → 항목 순서로 선택):

npx @seed-design/cli@latest docs

특정 항목 직접 조회:

npx @seed-design/cli@latest docs action-button

경로 기반 조회 (카테고리/섹션/항목):

npx @seed-design/cli@latest docs react/components/action-button

카테고리만 지정:

npx @seed-design/cli@latest docs react

카테고리/섹션까지 지정:

npx @seed-design/cli@latest docs react/components

llms.txt 내용을 직접 가져오기 (--raw):

# 컴포넌트 문서 내용
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합니다.

출력 예시 (기본):

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만 출력됩니다.

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

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