sparkdesign 0.4.8 → 0.4.10

package/AGENT_COMPONENT_LIBRARY_QUICKREF.md

@@ -0,0 +1,117 @@
+# 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 { Response } from '@/components/ui/chat/response'
+```
+
+不要再写：
+
+```tsx
+import { Button } from 'sparkdesign'
+```
+
+### 整包模式
+
+使用：
+
+```bash
+npm install sparkdesign
+```
+
+导入：
+
+```tsx
+import 'sparkdesign/style'
+import { Button, Response } 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
+- 常见组合优先看 manifest recipes，不要只按组件名猜
+
+优先复用已有组件：
+
+- `button` / `icon-button`
+- `tooltip` / `dropdown-menu` / `alert-dialog`
+- `chat-input`
+- `response`
+- `reasoning-step`
+- `code-block-part` / `terminal-code-block-part`
+- `task-part` / `plan-part`
+
+## 影响 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`？
+3. 是否已有可复用组件？
+4. 样式是否完全基于 token？
+5. 改动会不会影响 CLI registry 与发布链路？

package/AI_README.md

@@ -7,8 +7,11 @@ Spark Design correctly.
 
 1. `registry/agent-manifest.json` — choose components by intent, slots, states, accessibility, composition, and anti-patterns.
 2. `registry/tokens/ontology.json` — choose token families by semantic purpose before writing styles.
-3. `docs/guides/agent-usage.md` — consumption rules for CLI copy vs package import.
-4. Component source only after the manifest tells you which component to use.
+3. `docs/guides/system-operating-model.md` — quality bar for structure, showcase, AI semantics, and maintenance gates.
+4. `docs/agent/component-selection.md` — decision order, name boundaries, recipes, and manifest maintenance.
+5. `docs/agent/prompt-recipes.md` — copyable prompts for install, screen composition, AI workflows, component changes, and audits.
+6. `docs/guides/agent-usage.md` — consumption rules for CLI copy vs package import.
+7. Component source only after the manifest tells you which component to use.
 
 For npm package consumers:
 
@@ -22,7 +25,9 @@ import ontology from 'sparkdesign/token-ontology.json'
 - Prefer `npx sparkdesign@latest add <component>` when building a business app that should own component source.
 - Prefer `import { Component } from 'sparkdesign'` only for prototypes, showcase usage, or projects already using the package runtime.
 - Use `basic/*` for product primitives and `chat/*` for assistant, tool, file, reasoning, and response flows.
+- Choose components by manifest intent and anti-patterns before matching by name.
 - Use `data-theme` for color and `data-style` for density, radius, and rhythm.
+- Treat showcase, docs, registry metadata, and agent manifest updates as one public contract when a component changes.
 
 ## Hard Rules
 

package/README.md

@@ -2,7 +2,7 @@
 
 现代化 React 设计系统，支持双维度主题（颜色 theme + 布局 scale），5 种内置布局风格，提供 Basic 基础组件与 Chat 对话流组件，可扩展颜色主题。
 
-**当前版本**：`0.4.6`（[CLI 快速上手](docs/getting-started-cli.md) / [NPM 快速上手](docs/getting-started.md)）
+**当前版本**：`0.4.9`（[CLI 快速上手](docs/getting-started-cli.md) / [NPM 快速上手](docs/getting-started.md)）
 
 > 🌟 **纯新手？** 查看 [CLI 快速上手指南](docs/getting-started-cli.md)，一步步带你跑起来！
 
@@ -17,6 +17,9 @@
 - **图标系统可替换**：通过 `IconsProvider` 接 Lucide、Remix 或自定义图标库
 - **Tailwind 友好**：类名与设计 token 映射，无硬编码色值
 - **组件分层**：Basic 原子组件 + Chat 对话组件，开箱即用
+- **AI 友好契约**：`agent-manifest.json` + token ontology + component selection guide 让 agent 按 intent、states、a11y、composition 和 anti-patterns 选择组件
+- **可复制 Agent Recipes**：安装、页面组合、AI 工作流、组件维护和审查都有提示词模板
+- **同构维护流程**：registry、CLI、showcase、docs、P2/P3 与发布门禁保持一致
 
 ## 两种使用方式
 

package/cli/registry/AGENTS.md

@@ -4,7 +4,7 @@
 
 ## Member list
 
-- `basic/` — alert, alert-dialog, aspect-ratio, avatar, breadcrumb, button, button-group, calendar, card, carousel, chart, checkbox, collapse, collapsible, collapsible-card, combobox, command, context-menu, data-table, date-picker, dialog, direction, drawer, dropdown-menu, empty, field, hover-card, icon-button, input, input-group, input-otp, item, kbd, label, menubar, native-select, navigation-menu, option-list, pagination, popover, progress, radio-group, resizable, scroll-area, scrollbar, select, separator, sheet, shimmering-text, sidebar-menu, skeleton, slider, sonner, spinner, switch, table, tabs, tag, textarea, toggle, tooltip, typography.
+- `basic/` — accordion, alert, alert-dialog, aspect-ratio, avatar, badge, breadcrumb, button, button-group, calendar, card, carousel, chart, checkbox, collapse, collapsible, collapsible-card, combobox, command, context-menu, data-table, date-picker, dialog, direction, drawer, dropdown-menu, ellipsis-text, empty, field, form, hover-card, icon-button, input, input-group, input-otp, item, kbd, label, menubar, native-select, navigation-menu, option-list, pagination, popover, progress, radio-group, rating, resizable, scroll-area, scrollbar, select, separator, shimmering-text, sidebar, sidebar-menu, skeleton, slider, spinner, stepper, switch, table, tabs, tag, textarea, timeline, toggle, tooltip, typography.
 - `chat/` — ask-user-part, browser-action-part, chat-input, code-block-part, conversation-anchor-nav, file-attachment, file-card, file-review-part, folder-button, generated-images-grid, generation-status-bar, hint-banner, image-attachment, image-generating, markdown, mermaid-part, permission-card, plan-part, queue-indicator, reasoning-step, related-prompts, response, send-button, streaming-markdown-block, task-part, terminal-code-block-part, thinking-indicator, tool-invocation-card, user-message, user-question, user-question-answer.
 - `lib/` — file-icon-maps, use-mermaid-render, utils; helper modules copied with registry components when needed.
 - `tokens/` — index.css, theme.css, theme-base.css, scale.css, ontology.json, scrollbar utility, theme presets, and scale token packs.