# Spark Design Agent Quick Reference

> 给进入本仓库的 agent 的 1 页速查卡。详细说明见 [docs/guides/agent-usage.md](./docs/guides/agent-usage.md)；组件选择见 [docs/agent/component-selection.md](./docs/agent/component-selection.md)；项目级质量标准见 [docs/guides/system-operating-model.md](./docs/guides/system-operating-model.md)；可复制提示词见 [docs/agent/prompt-recipes.md](./docs/agent/prompt-recipes.md)。

## 默认选择

- 默认优先：`npx sparkdesign@latest add <component>`
- 次选：`npm install sparkdesign`
- 只有用户明确要整包 import，或项目已经在用整包时，才优先走整包

## 两条路径不要混用

### CLI 本地源码模式

使用：

```bash
npx sparkdesign@latest init
npx sparkdesign@latest add button
```

默认导入：

```tsx
import { Button } from '@/components/ui/basic/button'
import { AssistantResponse } from '@/components/ui/chat/response'
import { DotmSquare3 } from '@/components/ui/motion/dotm-square-3'
```

不要再写：

```tsx
import { Button } from 'sparkdesign'
```

### 整包模式

使用：

```bash
npm install sparkdesign
```

导入：

```tsx
import 'sparkdesign/style'
import { AssistantResponse, Button } from 'sparkdesign'
```

## 样式硬规则

- 一律优先 design tokens，不要硬编码颜色、圆角、间距
- 根节点优先设置 `data-theme` 和 `data-style`
- Portal / 浮层组件要考虑 theme/style 继承，不要靠 remount 刷主题

允许：

```tsx
className="bg-primary text-text rounded-md"
className="px-[var(--spacing-3)]"
```

不允许：

```tsx
className="bg-[#1890FF] text-[#333] rounded-[10px]"
```

## 组件选择

- 先读 `registry/agent-manifest.json`，按 intent、states、a11y、composition、antiPatterns 选择
- `basic/*`: 通用 UI
- `chat/*`: 对话流 UI
- `motion/*`: 动效标识与微交互 UI
- 常见组合优先看 manifest recipes，不要只按组件名猜

优先复用已有组件：

- `button` / `icon-button`
- `tooltip` / `dropdown-menu` / `alert-dialog`
- `chat-input`
- `response` / `AssistantResponse`
- `reasoning-step`
- `code-block-part` / `terminal-code-block-part`
- `task-part` / `plan-part`
- `dotm-square-3`

## 影响 CLI 时必须检查

- `registry/`
- `registry/meta.json`
- `cli/registry/` 是否已同步
- `npm run check:registry-meta`

## 组件完成定义

组件不只是源码文件。公开变更完成前，必须让这些表面一致：

- registry 源码与 CLI 副本
- 主包导出与 props 类型
- showcase demo / config / props / 本地化标签
- `registry/agent-manifest.json` 的 intent、states、a11y、composition、antiPatterns
- P3 header 与相关 P2 map

## 发布规则

- **唯一发布入口是仓库根目录**
- 不要从 `cli/` 目录执行 `npm publish`
- 根包 `sparkdesign` 同时承载：
  - 运行时整包
  - `bin.sparkdesign -> ./cli/dist/index.js`

## 开工前先回答 5 个问题

1. 当前项目是在用 CLI 本地源码，还是整包 import？
2. 目标组件属于 `basic`、`chat` 还是 `motion`？
3. 是否已有可复用组件？
4. 样式是否完全基于 token？
5. 改动会不会影响 CLI registry 与发布链路？