seed-design

SEED Design

将 SEED Design 的官方文档和 CLI 作为唯一信息源。本技能不复制文档内容，只规定一套探索与判断流程，依次涵盖通用设计知识 → 平台实现 → 平台专属 Doctor。

1. 先对请求进行分类

调查项目之前，先将请求归为以下类别之一。

分类	示例	是否需要判断平台
通用组件规范·Foundations	Anatomy、Properties、Guidelines、颜色、排版、间距	不需要
平台实现	用法、Props、安装、设置、代码片段、编写代码、运行 CLI	需要
Doctor·迁移	使用状态诊断、deprecated、兼容性、升级	需要

如果只询问通用规范或 Foundations，即使没有项目，也可以直接查阅通用文档。如果同时询问实现代码，则先查阅通用文档，再判断平台，并结合该平台的文档。

SEED 仓库工作路由

如果当前仓库的 package.json 名称为 @seed-design/project，且请求涉及仓库工作而非面向使用者的说明，则先阅读以下专用技能。此表只提供入口，不会将各项流程复制到本文档中。

请求	使用的技能
调查组件路径、API 对比、颜色 token；实现、编写文档	seed-component
变更影响、验证、基准分支计划、changeset、明确要求的提交	seed-change
标记 deprecated、迁移、移除	seed-deprecation
生成 PR snapshot 并确认结果	seed-snapshot-release

仅有查询和计划结果时，不要开始编写文件或提交。如果 seed-change 的分支结果为 unknown，则不要提交。

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

不要用低优先级的线索覆盖高优先级的明确信息。但如果同一目标中的配置与依赖冲突，配置可能已过时，应向用户确认。

在 monorepo 中，不要只查看根目录的 package.json，应先找到请求所针对的工作区。如果在根目录请求中同时发现 React 和 Lynx 工作区，或目标路径不明确，则在开始实现、安装或 Doctor 之前，先询问用户要使用哪个工作区或平台。

如果没有线索，或同一层级同时发现多个平台，也应询问用户。**不确定时，不要默认使用 React。**这是 Agent 的文档路由规则，并不改变现有 CLI 的公开行为或 seed-design.json 的默认值。

判断平台后，仅在需要时收集以下项目资料。

• seed-design.json 中的 path 以及该目录中带有 @file 标头的文件 → 是否已安装代码片段
• 已安装的 @seed-design/* 版本
• 打包工具配置（vite.config、rsbuild.config、webpack.config 等）
• 根据 lock 文件判断包管理器（bun → pnpm → yarn → npm）

3. 官方文档路由

不要将文档列表和支持范围复制到技能中。每次收到请求时，都先阅读以下索引，并严格遵循索引提供的链接。

• 全部文档索引：https://seed-design.io/llms.txt
• React 文档索引：https://seed-design.io/react/llms.txt
• Lynx 文档索引：https://seed-design.io/lynx/llms.txt

在一次请求的执行过程中，维护一组经过 URL 规范化的文档。全部索引、选定的平台索引及各个 leaf 文档，每个 URL 只读取一次；后续步骤和规则复用相同内容。在报告的 references 中重复同一 URL 是为了保留来源，并不表示需要再次读取。不要假设存在 HTTP 缓存。

遵循以下顺序。

1. 从全部文档索引中查找通用 Components、Foundations、Patterns，或所选平台当前的入口。
2. 如果是平台实现请求，则阅读所选平台的索引，并根据标题、category 和说明查找所需文档。
3. 打开索引提供的 leaf URL，查阅实际约定。不要根据记忆中的路径或 URL 拼接出 leaf 文档。
4. 如果索引可以正常读取，但其中没有相关条目，则判断当前没有官方文档。如果无法读取索引本身，则不能确认文档不存在。

使用 CLI 的 docs 命令时，也应先在索引中确认文档和 id。不要假设 URL 路径与 CLI id 相同；如果无法确认 id，则直接读取索引中的 URL。

组件回答顺序

1. 如果是规范问题，只阅读通用组件文档。
2. 如果是实现问题，先判断平台，再阅读对应的平台文档。
3. 如果同时询问规范和实现，先阅读通用文档，再阅读判断出对应平台的文档。
4. 如果通用文档 id 与实现文档 id 不同，则通过通用文档的 Platform 表和所选平台索引查找实际 id。
5. 如果所选平台的文档或 registry 条目不存在，则告知用户该平台没有相应实现或文档。不要用其他平台的文档替代。

如果需要代码片段，只使用所选平台的 registry。

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

单个代码片段的路径是 {itemId}.json，而不是 {itemId}/index.json。

CLI 文档

在全部索引或平台索引中查找与 CLI、Commands、Configuration 对应的当前链接，并阅读其内容。不要仅凭文档位于哪个平台目录树下，就推断其支持的平台或选项。命令、标志和配置字段只能使用关联文档或已安装 CLI 源码明确列出的值。

4. 판단이 필요한 절차

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

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

Doctor 요청은 doctor.md의 적응형 탐색 절차를 먼저 따릅니다.

1. 사용자 지정 경로
2. node_modules, .git, .claude/worktrees를 제외한 seed-design.json
3. 설정 발견 여부와 관계없이 직접 @seed-design/* 의존성이 있는 workspace
4. 두 후보를 package 경계로 중복 제거
5. 사용자 명시 → framework → 직접 의존성 순의 플랫폼 확정
6. 공개 진입점과 앱·라이브러리 빌드 증거에 따른 비배타적 역할 판정

• React Doctor: doctor-react.md를 함께 읽습니다.
• Lynx Doctor: doctor-lynx.md를 함께 읽습니다.

플랫폼 프로필은 문서 지원 현황을 복제하지 않고 인덱스·패키지·registry 탐색의 시작점만 제공합니다. 일반 진단은 공통 룰 전체를 scope에 넣고, 현재 인덱스에서 발견한 공식 계약과 각 룰의 적용 조건으로 검사 여부를 정합니다. 사용자가 config·setup·foundations·components·compatibility·library 중 범주를 지정했다면 그 범주만 실행합니다. 여러 workspace의 전체 진단은 리포트를 workspace별로 따로 만듭니다.

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

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

rules/의 룰은 SEED 코드를 작성할 때 지키는 계약이자 Doctor의 판정 기준입니다. Doctor에서는 선택된 플랫폼 프로필과 각 룰의 적용 조건을 함께 사용합니다.

• project-config: 현재 CLI 설정 계약, framework 충돌, snippet path·alias 연결
• package-compatibility: 플랫폼 패키지 설치본 조합
• project-setup: 선택된 플랫폼 문서가 요구하는 앱 설치·스타일 연결
• snippet-compatibility: 현재 패키지와 설치 스니펫의 CLI compat 결과
• foundation-contract: 토큰 존재·공개성·내부 스타일 API 의존
• library-authors: 공식 저자 문서가 있는 플랫폼의 peer·external·CSS·배포 계약
• outdated-version: 직접 설치한 패키지의 최신 세대 격차만
• snippet-generation: 설치 스니펫과 registry의 최신 세대 차이만
• no-deprecated-component: 플랫폼에 유효한 출처가 있는 deprecated 항목만
• component-guidelines: 공통 디자인 문서와 매핑 가능한 플랫폼 구현의 대조

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

6. 응답과 실행 원칙

• 공식 문서를 실제로 읽고 근거 링크와 함께 답합니다.
• 설치·실행 명령은 대상 프로젝트의 패키지 매니저에 맞춥니다.
• read-only 진단과 실제 수정 요청을 구분합니다.
• Doctor 결과는 schema v2 YAML을 단일 원천으로 임시 디렉토리에 기록하고, 사용자가 "YAML만"을 명시하지 않으면 같은 디렉토리에 HTML 리포트도 함께 생성합니다. 대상 프로젝트에는 쓰지 않습니다.
• 각 finding의 remediation에는 대상·문제·요구사항·제약·근거·검증을 포함한 복사 가능한 수정 프롬프트를 기록합니다. 프롬프트를 만드는 것은 진단이며, 사용자가 별도로 수정을 요청하기 전에는 실행하지 않습니다.
• 없는 경로나 API를 추측하지 않습니다.
• 작업이 끝나면 현재 맥락에 맞는 다음 단계만 짧게 제안합니다.