sparkdesign 0.4.9 → 0.4.10

package/dist/src/components/basic/Rating/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * [WHO]: Public Rating re-export.
+ * [FROM]: registry/basic/rating.
+ * [TO]: sparkdesign package consumers; src/components/index.ts barrel.
+ * [HERE]: src/components/basic/Rating/index.tsx — package-facing Rating entrypoint.
+ *
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
+ */
+export { Rating, ratingVariants } from '../../../../registry/basic/rating';
+export type { RatingProps, RatingPrecision } from '../../../../registry/basic/rating';

package/dist/src/components/basic/Stepper/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * [WHO]: Public Stepper re-export.
+ * [FROM]: registry/basic/stepper.
+ * [TO]: sparkdesign package consumers; src/components/index.ts barrel.
+ * [HERE]: src/components/basic/Stepper/index.tsx — package-facing Stepper entrypoint.
+ *
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
+ */
+export { Stepper, StepperItem, StepperIndicator, StepperContent, StepperTitle, StepperDescription, StepperSeparator, } from '../../../../registry/basic/stepper';
+export type { StepperProps, StepperItemProps, StepperIndicatorProps, StepperContentProps, StepperTitleProps, StepperDescriptionProps, StepperSeparatorProps, StepStatus, } from '../../../../registry/basic/stepper';

package/dist/src/components/basic/Timeline/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * [WHO]: Public Timeline re-export.
+ * [FROM]: registry/basic/timeline.
+ * [TO]: sparkdesign package consumers; src/components/index.ts barrel.
+ * [HERE]: src/components/basic/Timeline/index.tsx — package-facing Timeline entrypoint.
+ *
+ * [PROTOCOL]:
+ * 1. Keep this P3 header in sync when the public contract changes.
+ * 2. Update module AGENTS.md (P2) and root AGENTS.md (P1) when boundaries change.
+ * 3. Follow design tokens and explicit type exports.
+ */
+export { Timeline, TimelineItem, TimelineMarker, TimelineConnector, TimelineContent, TimelineTitle, TimelineDescription, TimelineTime, timelineMarkerVariants, } from '../../../../registry/basic/timeline';
+export type { TimelineProps, TimelineItemProps, TimelineMarkerProps, TimelineConnectorProps, TimelineContentProps, TimelineTitleProps, TimelineDescriptionProps, TimelineTimeProps, } from '../../../../registry/basic/timeline';

package/dist/src/components/index.d.ts

@@ -70,6 +70,12 @@ export { Tag, tagVariants } from './basic/Tag';
 export type { TagProps } from './basic/Tag';
 export { Progress } from './basic/Progress';
 export type { ProgressProps } from './basic/Progress';
+export { Rating, ratingVariants } from './basic/Rating';
+export type { RatingProps, RatingPrecision } from './basic/Rating';
+export { Stepper, StepperItem, StepperIndicator, StepperContent, StepperTitle, StepperDescription, StepperSeparator, } from './basic/Stepper';
+export type { StepperProps, StepperItemProps, StepperIndicatorProps, StepperContentProps, StepperTitleProps, StepperDescriptionProps, StepperSeparatorProps, StepStatus, } from './basic/Stepper';
+export { Timeline, TimelineItem, TimelineMarker, TimelineConnector, TimelineContent, TimelineTitle, TimelineDescription, TimelineTime, timelineMarkerVariants, } from './basic/Timeline';
+export type { TimelineProps, TimelineItemProps, TimelineMarkerProps, TimelineConnectorProps, TimelineContentProps, TimelineTitleProps, TimelineDescriptionProps, TimelineTimeProps, } from './basic/Timeline';
 export { CollapsibleCard } from './basic/CollapsibleCard';
 export type { CollapsibleCardProps } from './basic/CollapsibleCard';
 export { SidebarMenu } from './basic/SidebarMenu';
@@ -102,8 +108,6 @@ export { Dialog, DialogTrigger, DialogPortal, DialogOverlay, DialogClose, Dialog
 export type { DialogContentProps, DialogHeaderProps, DialogFooterProps, } from './basic/Dialog';
 export { Drawer, DrawerTrigger, DrawerClose, DrawerPortal, DrawerOverlay, DrawerContent, DrawerHeader, DrawerFooter, DrawerTitle, DrawerDescription, } from './basic/Drawer';
 export type { DrawerContentProps, DrawerHeaderProps, DrawerFooterProps, } from './basic/Drawer';
-export { Sheet, SheetTrigger, SheetClose, SheetPortal, SheetOverlay, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription, sheetVariants, } from './basic/Sheet';
-export type { SheetContentProps, SheetHeaderProps, SheetFooterProps, } from './basic/Sheet';
 export { Popover, PopoverTrigger, PopoverAnchor, PopoverContent, } from './basic/Popover';
 export type { PopoverContentProps } from './basic/Popover';
 export { HoverCard, HoverCardTrigger, HoverCardContent } from './basic/HoverCard';

package/docs/agent/component-selection.md

@@ -8,6 +8,7 @@ details are needed.
 
 - `sparkdesign/agent-manifest.json` — package export for agent-facing component semantics.
 - `registry/agent-manifest.json` — source of truth in this repository.
+- Showcase route `#/agent-component-selection` — visible companion page for the same decision model.
 - `npm run check:agent-manifest` — validates required semantic fields and recipe references.
 - `npm run report:agent-coverage` — reports manifest coverage against `registry/meta.json`.
 - `npm run check:agent-coverage` — fails if manifest coverage drops below 100%.
@@ -25,7 +26,6 @@ details are needed.
 - `sidebar` is the full app-shell primitive set: provider state, trigger, responsive collapse, mobile sheet, and inset content. Package imports expose its menu list as `SidebarNavMenu` / `SidebarNavMenuItem`.
 - `sidebar-menu` is the lightweight data-driven list component exported as `SidebarMenu`; use it when a full app shell would be overkill.
 - `form` is for React Hook Form validation wiring; `field` is for layout-only form rows.
-- `toast` and `sonner` share the same runtime toaster API. Prefer `toast` for Spark semantic naming and `sonner` only when matching that install target.
 
 ## Current High-Confidence Coverage
 
@@ -84,14 +84,12 @@ snapshot.
 - `scrollbar`
 - `select`
 - `separator`
-- `sheet`
 - `sidebar`
 - `sidebar-menu`
 - `shimmering-text`
 - `slider`
 - `skeleton`
 - `spinner`
-- `sonner`
 - `switch`
 - `table`
 - `tag`

package/docs/agent/prompt-recipes.md

@@ -0,0 +1,167 @@
+# Spark Design Prompt Recipes
+
+These prompts are for AI coding agents that need to build with Spark Design
+without flattening the system into generic UI. They assume the agent can inspect
+files, run commands, and edit code.
+
+Showcase companion: `#/agent-prompt-recipes`.
+
+## How To Use
+
+1. Pick the recipe closest to the task.
+2. Paste it into the agent with the product-specific requirements.
+3. Keep the hard rules intact.
+4. Ask the agent to report which Spark surfaces it verified.
+
+## Universal Spark Contract
+
+Add this block to any prompt when quality matters:
+
+```text
+Use Spark Design as a system, not as loose components.
+
+Before implementation:
+- Read registry/agent-manifest.json and choose components by intent, states,
+  accessibility, composition, and antiPatterns.
+- Read registry/tokens/ontology.json before writing styles.
+- Prefer npx sparkdesign@latest add <component> for business apps that should
+  own copied source.
+- Use package imports only if the app already consumes sparkdesign as a runtime.
+
+Hard rules:
+- Do not invent duplicate components when Spark already covers the intent.
+- Do not hard-code hex colors, raw rgba overlays, arbitrary radii, or one-off
+  spacing in published UI.
+- Preserve data-theme for color and data-style for layout density/radius/rhythm.
+- Keep portal UI consistent with the active theme/style.
+- For AI workflows, prefer chat components such as ChatInput, Response,
+  ToolInvocationCard, PermissionCard, ReasoningStep, TaskPart, PlanPart,
+  FileReviewPart, and RelatedPrompts instead of plain cards and Markdown.
+
+Before handoff:
+- Run the narrow checks that prove the changed surfaces.
+- Report changed files, validation commands, and any remaining risk.
+```
+
+## Recipe 1: Install Spark In A New App
+
+```text
+Set up Spark Design in this React app.
+
+Requirements:
+- Determine whether this project should use CLI copied source or package imports.
+- Prefer CLI copied source unless the project already uses sparkdesign as a
+  runtime dependency or I explicitly ask for package mode.
+- If using CLI mode, run npx sparkdesign@latest init and add only the components
+  needed for the screen.
+- Configure Tailwind CSS 4 correctly, including @tailwindcss/vite and @source
+  for copied Spark components.
+- Set data-theme and data-style on the root or document element.
+- Verify dark mode and at least one portal component if the screen uses overlays.
+
+Do not mix CLI copied-source imports with package imports.
+Do not leave Vite starter CSS fighting Spark tokens.
+```
+
+## Recipe 2: Select Components For A Product Screen
+
+```text
+Design and implement this product screen using Spark Design.
+
+Task:
+[Describe the screen, users, data density, and primary workflow.]
+
+Process:
+1. Read registry/agent-manifest.json.
+2. List the Spark components selected by intent and explain why each one fits.
+3. Check antiPatterns for every selected component before composing the screen.
+4. Read registry/tokens/ontology.json and choose token families before styling.
+5. Implement the screen with tokenized classes and existing Spark primitives.
+6. Keep workflows efficient: use icons for tools, segmented controls for modes,
+   toggles for binary settings, and menus for option sets.
+
+Verification:
+- No duplicate local component that Spark already provides.
+- No hard-coded hex/rgb, arbitrary radii, or arbitrary spacing unless explained.
+- Text fits on desktop and mobile.
+- Keyboard/focus behavior remains intact for controls and overlays.
+```
+
+## Recipe 3: Build An AI Workflow
+
+```text
+Build this AI workflow with Spark Design chat components.
+
+Workflow:
+[Describe prompt entry, tool calls, files, approvals, reasoning, generated
+content, error handling, and follow-up prompts.]
+
+Use Spark chat components where they match intent:
+- ChatInput for prompt composition and attachments.
+- Response or Markdown for generated answers.
+- ToolInvocationCard for tool execution visibility.
+- PermissionCard or AskUserPart for approval/confirmation.
+- ReasoningStep, PlanPart, TaskPart, or BrowserActionPart for structured agent
+  progress.
+- FileCard, FileAttachment, FileReviewPart, and GeneratedImagesGrid for files.
+- RelatedPrompts for next actions.
+
+Do not flatten tool calls, approvals, or reasoning into plain Markdown.
+Expose state clearly: pending, streaming, success, blocked, skipped, failed.
+```
+
+## Recipe 4: Add Or Change A Component
+
+```text
+Add or change this Spark component while keeping the system isomorphic.
+
+Component intent:
+[Describe what user problem the component solves and what it should not solve.]
+
+Required sequence:
+1. Search existing registry/basic, registry/chat, and registry/agent-manifest.json
+   to confirm this component is not a duplicate.
+2. Implement source of truth in registry/.
+3. Keep dependencies public and copy-safe for CLI users.
+4. Export component and prop types through src/components/.
+5. Regenerate or validate registry/meta.json and sync cli/registry if needed.
+6. Add showcase demo blocks with production-like examples and matching snippets.
+7. Add props metadata and localized labels.
+8. Update registry/agent-manifest.json with intent, slots, states, a11y,
+   composition, antiPatterns, and agentHints.
+9. Update P3 headers and P2 AGENTS.md maps.
+10. Run component, registry, showcase, token, and manifest checks.
+
+Do not call the component complete until registry, CLI, package exports,
+showcase, docs, and agent manifest agree.
+```
+
+## Recipe 5: Audit A Spark Change
+
+```text
+Review this Spark Design change as a maintainer.
+
+Prioritize:
+- Behavioral bugs and regressions.
+- Drift between registry, CLI, package exports, showcase, docs, and manifest.
+- Token misuse: hard-coded colors, raw rgba, arbitrary spacing/radius, theme
+  inheritance failures, and one-off visual language.
+- Accessibility gaps: labels, roles, focus states, keyboard behavior, status
+  text, and color-only meaning.
+- Showcase quality: examples should teach real usage and snippets should compile.
+- AI friendliness: manifest intent and antiPatterns should prevent bad agent
+  choices.
+
+Return findings first with file/line references, then open questions, then a
+short verification summary.
+```
+
+## Maintainer Checklist
+
+- Prompt picked the correct consumption path: CLI copied source or package import.
+- Prompt forced manifest and ontology reads before implementation.
+- Prompt preserved theme/style axes and portal inheritance.
+- Prompt required showcase and docs updates when public behavior changed.
+- Prompt required agent manifest updates for new or changed components.
+- Prompt kept AI-facing docs package-visible when guidance changed.
+- Prompt included concrete verification commands and evidence.

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.9",
+  "version": "0.4.10",
   "type": "module",
   "description": "Modern React Design System with dual-dimension theme system",
   "keywords": [
@@ -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,12 @@
     "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",
@@ -81,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:agent-coverage && 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",