sparkdesign 0.4.8 → 0.4.10

package/docs/guides/agent-usage.md

@@ -0,0 +1,213 @@
+# Spark Design Agent Usage Guide
+
+> 给 AI agent / coding agent 的执行指南。目标不是介绍组件库是什么，而是约束“在项目里该怎么正确使用它”。
+
+## 1. 默认决策
+
+### 1.1 优先级
+
+默认优先使用 **CLI 按需引入**：
+
+```bash
+npx sparkdesign@latest add button
+```
+
+只有在以下场景才优先考虑整包安装：
+
+- 用户明确要求 `npm install sparkdesign`
+- 目标是快速原型，而不是复制源码后再改
+- 运行环境不方便把组件源码拷入项目
+
+### 1.2 两条使用路径
+
+| 路径 | 适用场景 | Agent 默认行为 |
+|------|----------|----------------|
+| **CLI 按需引入** | 业务项目、需要修改组件源码、希望长期维护本地副本 | **默认优先** |
+| **整包安装** | Showcase、快速试用、低定制场景、只想直接 import | 仅在用户明确要求或项目已采用整包模式时使用 |
+
+## 2. CLI 路径怎么用
+
+### 2.1 常用命令
+
+```bash
+npx sparkdesign@latest init
+npx sparkdesign@latest add button
+npx sparkdesign@latest add response
+npx sparkdesign@latest list
+npx sparkdesign@latest diff button
+```
+
+### 2.2 生成后的默认路径
+
+默认组件会写到：
+
+```text
+src/components/ui/basic/<name>.tsx
+src/components/ui/chat/<name>.tsx
+src/components/ui/chat/<name>/index.tsx
+```
+
+如果项目里已有 `components.json`，以 `aliases.ui` 为准，不要硬猜路径。
+
+### 2.3 CLI 路径下的 import 规则
+
+默认按以下方式导入：
+
+```tsx
+import { Button } from '@/components/ui/basic/button'
+import { Response } from '@/components/ui/chat/response'
+```
+
+不要在 CLI 路径下再写：
+
+```tsx
+import { Button } from 'sparkdesign'
+```
+
+这会把“复制到本地的源码”与“整包运行时”混在一起。
+
+## 3. 整包路径怎么用
+
+### 3.1 安装与导入
+
+```bash
+npm install sparkdesign
+```
+
+```tsx
+import 'sparkdesign/style'
+import { Button, Response } from 'sparkdesign'
+```
+
+### 3.2 整包路径下的样式规则
+
+默认优先：
+
+```tsx
+import 'sparkdesign/style'
+```
+
+只有在消费者自己维护 Tailwind 4 样式管线时，才改用：
+
+```tsx
+import 'sparkdesign/theme.css'
+import 'sparkdesign/scale.css'
+```
+
+## 4. 主题与 Token 硬规则
+
+### 4.1 一律使用 design tokens
+
+选择 token 前，agent 应优先读取：
+
+```tsx
+import ontology from 'sparkdesign/token-ontology.json'
+```
+
+仓库内源文件为：
+
+```text
+registry/tokens/ontology.json
+```
+
+允许：
+
+```tsx
+className="bg-primary text-text rounded-md"
+className="px-[var(--spacing-3)]"
+```
+
+不允许：
+
+```tsx
+className="bg-[#1890FF] text-[#333] rounded-[10px]"
+```
+
+### 4.2 根节点主题
+
+优先在根节点或大容器设置：
+
+```tsx
+<div data-theme="light" data-style="neutral" />
+```
+
+可选值：
+
+- `data-theme`: `light` | `dark` | 自定义主题名
+- `data-style`: `neutral` | `compact` | `soft` | `sharp` | `dense`
+
+### 4.3 Portal / 浮层组件
+
+Tooltip、DropdownMenu、Toast 这类浮层要考虑 theme/style 继承。若项目已用整包并提供 `ThemeStyleProvider`，优先沿用；不要通过强制 remount 的方式“刷新主题”。
+
+## 5. 组件选择规则
+
+### 5.0 先读 Agent Manifest
+
+设计 / coding agent 在选择组件前，优先读取：
+
+```tsx
+import manifest from 'sparkdesign/agent-manifest.json'
+```
+
+仓库内源文件为：
+
+```text
+registry/agent-manifest.json
+```
+
+该 manifest 提供组件 `intent`、`slots`、`states`、`a11y`、`composition`、`antiPatterns` 和常见 `recipes`。选择组件时先按 `intent` 和 `recipes` 匹配，再读源码；不要仅凭组件名相似度决定。
+
+### 5.1 Basic vs Chat
+
+- `basic/*`: 原子 UI，适合表单、控制、布局、通用信息展示
+- `chat/*`: 对话流组件，适合消息、响应、任务、推理步骤、附件、代码块等
+
+### 5.2 不要重复造轮子
+
+若以下组件已存在，优先复用：
+
+- 通用按钮：`button` / `icon-button`
+- 浮层：`tooltip` / `dropdown-menu` / `alert-dialog`
+- 对话输入：`chat-input`
+- AI 响应：`response`
+- 推理步骤：`reasoning-step`
+- 代码卡片：`code-block-part` / `terminal-code-block-part`
+- 任务与计划：`task-part` / `plan-part`
+
+## 6. 改组件时的约束
+
+### 6.1 Registry 是 CLI 模板真相
+
+若改动会影响 `npx sparkdesign add ...` 的结果，优先检查：
+
+- `registry/`
+- `registry/meta.json`
+- `cli/registry/` 是否已由同步脚本刷新
+
+### 6.2 根包是唯一发布入口
+
+不要从 `cli/` 目录单独发布。
+
+正式发布只从仓库根目录执行：
+
+```bash
+npm publish
+```
+
+根包会同时带上：
+
+- 运行时导出（整包）
+- `bin.sparkdesign -> ./cli/dist/index.js`（CLI）
+
+## 7. 给 Agent 的执行清单
+
+开始工作前，优先回答这 5 个问题：
+
+1. 当前项目是在用 **CLI 本地源码**，还是在用 **整包 import**？
+2. 目标组件属于 `basic` 还是 `chat`？
+3. 是否已经有可复用组件，而不是新建一个相似组件？
+4. 样式是否完全基于 token，而不是硬编码？
+5. 如果会影响 CLI，是否同步检查了 `registry/meta.json` 与发布链路？
+
+如果这 5 个问题里有任何一个答不上来，先不要写代码，先补上下文。

package/docs/guides/system-operating-model.md

@@ -0,0 +1,148 @@
+# Spark Design Operating Model
+
+> The system is excellent only when the implementation, documentation, showcase, registry, and agent contract all describe the same product truth.
+
+## Purpose
+
+Showcase companion: `#/system-operating-model`.
+
+Spark Design should feel like a world-class product system, not a folder of UI parts. Every addition must improve four surfaces at once:
+
+- **Product surface:** components are elegant, restrained, accessible, and token-driven.
+- **System surface:** registry, package exports, CLI copies, and metadata stay isomorphic.
+- **Documentation surface:** users can understand when to use a component, how to install it, and how to extend it without reading source first.
+- **Agent surface:** AI tools can select, compose, and verify components from manifest intent instead of guessing from names.
+
+## Principles
+
+### 1. Quiet Excellence
+
+Prefer durable hierarchy over decoration. Components should look precise at rest, clear in motion, and trustworthy under edge cases.
+
+Required signals:
+
+- Stable spacing, radius, typography, and focus states across all `data-style` values.
+- Semantic color usage through tokens, never one-off palettes in component source.
+- Interaction feedback that clarifies state without delaying work.
+- Empty, loading, disabled, error, and dense-content states handled deliberately.
+
+### 2. Isomorphic Maintenance
+
+The map must stay aligned with the terrain. A component is not complete until every public surface agrees.
+
+Required surfaces:
+
+- `registry/` implementation and dependencies.
+- `registry/meta.json` and `cli/registry/meta.json`.
+- `src/components/index.ts` public exports.
+- Showcase config, demo, props table, and localized labels.
+- `registry/agent-manifest.json` intent, slots, states, a11y, recipes, and anti-patterns.
+- P3 headers and P2 module maps when membership changes.
+
+### 3. AI-Friendly Semantics
+
+Spark should be easy for agents to use correctly under time pressure.
+
+Agent-facing data must answer:
+
+- What user intent does this component satisfy?
+- When should an agent choose a different component?
+- What slots and states are expected?
+- What accessibility obligations are non-negotiable?
+- Which components compose well together?
+- Which anti-patterns produce generic or unsafe UI?
+
+If the manifest cannot answer those questions, update the manifest before treating the component as complete.
+
+### 4. Showcase as Product
+
+The showcase is the primary trust surface. It should teach by showing real, polished product usage instead of dumping prop variants.
+
+Every component page should include:
+
+- A strong Overview example that represents the common production use case.
+- One focused block per major dimension: size, state, composition, or variant.
+- Snippets that compile and match the preview.
+- Installation instructions for CLI-first usage.
+- Props that match the actual exported API.
+- Copy that explains when to use the component, not just what props exist.
+
+## Component Addition Flow
+
+Use this sequence for every new component or public API change:
+
+1. **Define intent:** Write the component purpose, non-goals, expected states, and likely compositions.
+2. **Check reuse:** Search existing `basic/*`, `chat/*`, and `agent-manifest.json` before creating anything new.
+3. **Implement in registry:** Keep registry source standalone, tokenized, typed, and free of package-private imports.
+4. **Export publicly:** Add package-facing re-exports under `src/components/` and `src/components/index.ts`.
+5. **Sync registry metadata:** Regenerate and validate `registry/meta.json`; sync CLI registry copies.
+6. **Teach the showcase:** Add demo blocks, config entry, props metadata, and localized page labels.
+7. **Teach agents:** Add or update `registry/agent-manifest.json` with intent, states, a11y, composition, anti-patterns, and hints.
+8. **Update DIP docs:** Refresh P3 headers, P2 maps, and root docs when topology or commands change.
+9. **Verify:** Run the narrow checks that prove the touched surfaces are aligned.
+
+## Quality Gates
+
+Minimum gates for component work:
+
+```bash
+npm run check:agent-manifest
+npm run check:agent-coverage
+npm run check:ai-docs
+npm run check:registry-meta
+npm run check:registry
+npm run check:showcase
+npm run check:showcase-quality
+npm run check:token-antipatterns
+```
+
+Before publishing or merging broad system work, also run:
+
+```bash
+npm run lint
+npm run test:run
+npm run build
+npm run size
+```
+
+## Review Rubric
+
+Use this rubric before calling project-wide polish complete:
+
+| Area | Passing standard |
+| ---- | ---------------- |
+| Structure | Source of truth is clear; registry, CLI, package exports, and docs agree. |
+| Components | APIs are small, typed, tokenized, accessible, and composed from existing primitives. |
+| Showcase | Pages feel product-grade, scannable, and useful for both beginners and advanced users. |
+| Docs | Guides explain decisions, not only commands; SOPs prevent drift. |
+| AI contract | Manifest and token ontology make correct component selection obvious. |
+| Maintenance | Verification commands prove the actual changed surfaces, not only a narrow build path. |
+
+`npm run check:ai-docs` guards the AI-facing semantic layer: package exports,
+published files, relative links, and Showcase companion pages for the operating
+model, prompt recipes, and component selection guide.
+
+`npm run check:showcase-quality` guards the public documentation surface:
+registry-to-showcase coverage, demo exports, props metadata, and locale coverage.
+The default props metadata baseline is 70% and should only move upward. The
+Showcase registry config must not keep parallel `legacy*` maps; `categories`,
+`props`, `dependencies`, and `timeline` are the single source of truth. Duplicate
+component keys inside `props` or `dependencies` are blocked because they silently
+overwrite documentation data.
+
+## Anti-Patterns
+
+- Adding a component because a demo needs one instead of validating reusable intent.
+- Shipping source without CLI registry and metadata alignment.
+- Updating showcase copy without updating agent semantics.
+- Writing a component that looks good only in one theme or one `data-style`.
+- Treating the homepage as marketing while component pages remain weak.
+- Letting docs say "token-driven" while source uses raw colors or arbitrary geometry.
+
+## Coverage Ratchet
+
+`npm run check:showcase-quality` currently enforces a baseline for component page structure, props metadata, and locale coverage. When props tables or localized copy improve, raise the script thresholds instead of letting quality gains remain informal.
+
+## North Star
+
+Spark Design should help humans and agents build calm, coherent AI product interfaces. The strongest version of the project is clean enough for beginners, explicit enough for maintainers, and structured enough for AI systems to use without guesswork.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkdesign",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "type": "module",
   "description": "Modern React Design System with dual-dimension theme system",
   "keywords": [
@@ -17,7 +17,7 @@
   },
   "homepage": "https://spark.design",
   "bin": {
-    "sparkdesign": "./cli/dist/index.js"
+    "sparkdesign": "cli/dist/index.js"
   },
   "exports": {
     ".": {
@@ -32,16 +32,26 @@
     "./theme-base.css": "./dist/theme-base.css",
     "./agent-manifest.json": "./registry/agent-manifest.json",
     "./token-ontology.json": "./registry/tokens/ontology.json",
+    "./ai-readme.md": "./AI_README.md",
+    "./agent-quickref.md": "./AGENT_COMPONENT_LIBRARY_QUICKREF.md",
+    "./agent-prompt-recipes.md": "./docs/agent/prompt-recipes.md",
+    "./agent-component-selection.md": "./docs/agent/component-selection.md",
+    "./agent-token-ontology.md": "./docs/agent/token-ontology.md",
+    "./system-operating-model.md": "./docs/guides/system-operating-model.md",
+    "./agent-usage.md": "./docs/guides/agent-usage.md",
     "./tokens/*": "./dist/tokens/*",
     "./themes/*": "./dist/themes/*",
     "./scale/*": "./dist/scale/*"
   },
   "files": [
     "AI_README.md",
+    "AGENT_COMPONENT_LIBRARY_QUICKREF.md",
     "dist",
     "cli/dist",
     "cli/registry",
     "docs/agent",
+    "docs/guides/agent-usage.md",
+    "docs/guides/system-operating-model.md",
     "registry/agent-manifest.json",
     "registry/tokens/ontology.json"
   ],
@@ -56,10 +66,14 @@
     "gen:registry-meta": "node scripts/generate-registry-meta.mjs",
     "check:registry-meta": "node scripts/generate-registry-meta.mjs --check && node scripts/validate-registry-meta.mjs registry && node scripts/validate-registry-meta.mjs cli",
     "check:agent-manifest": "node scripts/validate-agent-manifest.mjs",
+    "check:ai-docs": "node scripts/check-ai-docs-package.mjs",
     "check:token-ontology": "node scripts/validate-token-ontology.mjs",
     "check:token-antipatterns": "node scripts/check-token-antipatterns.mjs",
     "check:registry": "node scripts/check-registry-sync.mjs",
     "check:showcase": "node scripts/check-showcase-sync.mjs",
+    "check:showcase-quality": "node scripts/check-showcase-quality.mjs",
+    "report:agent-coverage": "node scripts/report-agent-manifest-coverage.mjs",
+    "check:agent-coverage": "node scripts/report-agent-manifest-coverage.mjs --fail-under=100",
     "gen:demo": "node scripts/gen-demo.mjs",
     "build": "vite build && npx @tailwindcss/cli -i src/lib.css -o dist/sparkdesign.css --minify && tsc -p tsconfig.lib.json && npm run build:cli",
     "build:cli": "cd cli && npm run build",
@@ -79,7 +93,7 @@
     "test:smoke:vite": "node scripts/smoke-test-cli.mjs vite",
     "test:smoke:next": "node scripts/smoke-test-cli.mjs nextjs",
     "test:smoke:add": "node scripts/smoke-test-cli.mjs pure-add",
-    "prepublishOnly": "node scripts/generate-registry-meta.mjs && npm run check:agent-manifest && npm run check:token-ontology && npm run check:token-antipatterns && npm run build && node scripts/sync-registry-to-cli.mjs && npm run check:registry-meta"
+    "prepublishOnly": "node scripts/generate-registry-meta.mjs && npm run check:agent-manifest && npm run check:agent-coverage && npm run check:ai-docs && npm run check:token-ontology && npm run check:token-antipatterns && npm run check:showcase-quality && npm run build && node scripts/sync-registry-to-cli.mjs && npm run check:registry-meta"
   },
   "peerDependencies": {
     "react": ">=18.0.0",
@@ -106,6 +120,7 @@
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-separator": "^1.1.8",
     "@radix-ui/react-slider": "^1.3.6",
+    "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-switch": "^1.2.6",
     "@radix-ui/react-tabs": "^1.1.2",
     "@radix-ui/react-toggle": "^1.1.10",
@@ -132,6 +147,7 @@
     "prompts": "^2.4.2",
     "radix-ui": "^1.4.3",
     "react-day-picker": "^9.14.0",
+    "react-hook-form": "^7.76.0",
     "react-i18next": "^16.5.4",
     "react-markdown": "^10.1.0",
     "react-resizable-panels": "^4.6.2",
@@ -163,6 +179,7 @@
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.24",
     "globals": "^16.5.0",
+    "jsdom": "^29.1.1",
     "size-limit": "^12.0.0",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.48.0",