sparkdesign 0.4.5 → 0.4.7

package/AI_README.md

@@ -0,0 +1,60 @@
+# Spark Design AI Entrypoint
+
+This file is the shortest path for design and coding agents that need to use
+Spark Design correctly.
+
+## Read Order
+
+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.
+
+For npm package consumers:
+
+```ts
+import manifest from 'sparkdesign/agent-manifest.json'
+import ontology from 'sparkdesign/token-ontology.json'
+```
+
+## Default Decisions
+
+- 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.
+- Use `data-theme` for color and `data-style` for density, radius, and rhythm.
+
+## Hard Rules
+
+- Do not invent duplicate components when a Spark component already matches the intent.
+- Do not hard-code hex colors, raw rgb/rgba overlays, arbitrary radii, or one-off px spacing in published UI source.
+- Do not flatten structured AI output into plain Markdown when `Response`, `ToolInvocationCard`, `PermissionCard`, or related chat components apply.
+- Do not use accent colors to communicate status without text or icon labels.
+- Do not bypass portal theme inheritance for Dialog, Drawer, Tooltip, DropdownMenu, Toast, or other floating layers.
+
+## Verification Commands
+
+Run these before handing work back:
+
+```bash
+npm run check:agent-manifest
+npm run check:token-ontology
+npm run check:token-antipatterns
+npm run lint
+npm run test:run
+```
+
+For publishing or registry-affecting changes, also run:
+
+```bash
+npm run check:registry-meta
+npm run check:registry
+npm run build
+npm run size
+```
+
+## When Unsure
+
+If the manifest and ontology do not describe the pattern you need, update them
+before relying on source-code intuition. The semantic map must stay aligned with
+the implementation terrain.

package/README.md

@@ -2,9 +2,9 @@
 
 现代化 React 设计系统，支持双维度主题（颜色 theme + 布局 scale），5 种内置布局风格，提供 Basic 基础组件与 Chat 对话流组件，可扩展颜色主题。
 
-**当前版本**：`0.4.5`（[变更说明](docs/NPM发布指南.md)）
+**当前版本**：`0.4.6`（[CLI 快速上手](docs/getting-started-cli.md) / [NPM 快速上手](docs/getting-started.md)）
 
-> 🌟 **纯新手？** 查看 [快速上手指南-新手版](docs/快速上手指南-新手版.md)，一步步带你跑起来！
+> 🌟 **纯新手？** 查看 [CLI 快速上手指南](docs/getting-started-cli.md)，一步步带你跑起来！
 
 > 以下为**安装与使用说明**；仓库结构、开发脚本与贡献方式见文末 [仓库与开发](#仓库与开发)。
 
@@ -12,8 +12,9 @@
 
 - **双维度主题**：`data-theme`（颜色）+ `data-style`（布局），独立切换
 - **5 种布局风格**：neutral / compact / soft / sharp / dense
-- **内置颜色主题**：light / dark
-- **CSS 变量驱动**：组件仅用 token，覆盖变量即可定制
+- **官方起始 preset**：Mint / Parchment
+- **CSS 变量驱动**：覆盖颜色和 scale token 即可定制
+- **图标系统可替换**：通过 `IconsProvider` 接 Lucide、Remix 或自定义图标库
 - **Tailwind 友好**：类名与设计 token 映射，无硬编码色值
 - **组件分层**：Basic 原子组件 + Chat 对话组件，开箱即用
 
@@ -26,6 +27,36 @@
 
 **发布模型**：`sparkdesign` 是唯一发布到 npm 的包。CLI 不是第二个独立 npm 包，而是根包中的 `bin` 入口；因此用户侧既可以 `npm install sparkdesign`，也可以直接 `npx sparkdesign@latest add button`。
 
+### 风格控制模型
+
+不管你用哪种接入方式，真正决定项目风格的都是三层：
+
+- **colors**：颜色 token，决定品牌色、背景、边框、语义色
+- **scale**：布局 token，决定间距、圆角、字号和密度
+- **icons**：图标系统，决定视觉语言
+
+`mint` / `parchment` 只是官方提供的两套 starter preset，更适合当起点和 showcase 示例，而不是长期绑定的唯一主题心智。
+
+### 接入后你实际拿到什么
+
+**CLI 模式**
+
+- `components.json`：记录默认 `appearance / theme / style`
+- `src/sparkdesign-tokens.css` 或注入后的 `src/index.css`：预设好的颜色和 scale token，可直接改
+- `src/components/ui/...`：复制出来的组件源码，可直接改
+- `src/lib/utils.ts`：组件依赖的工具函数
+
+**npm 安装模式**
+
+- 预编译样式：`import 'sparkdesign/style'`
+- token 入口：`import 'sparkdesign/theme.css'` / `import 'sparkdesign/scale.css'`
+- 运行时入口：`ThemeStyleProvider`、`IconsProvider`
+
+也就是说：
+
+- **CLI** 更适合“拿到文件后自己改”
+- **npm** 更适合“先跑起来，再通过 token 和 icon 覆盖”
+
 ---
 
 ## 安装（npm 包）
@@ -42,12 +73,12 @@ npm install sparkdesign
 
 ```bash
 npx sparkdesign init                    # 初始化 components.json、tokens、utils
-npx sparkdesign add button tooltip      # 添加组件到 src/components/qoder/
+npx sparkdesign add button tooltip      # 添加组件到 src/components/ui/
 npx sparkdesign list                    # 列出可用组件
 npx sparkdesign diff button             # 对比本地与注册表差异
 ```
 
-详见 [docs/CLI按需引入方案.md](docs/CLI按需引入方案.md)。
+详见 [docs/cli/on-demand-import.md](docs/cli/on-demand-import.md)。
 
 ---
 
@@ -113,8 +144,10 @@ function App() {
 
 | 主题   | 说明     |
 |--------|----------|
-| `light` | 亮色模式（默认） |
-| `dark`  | 暗色模式 |
+| `light` | Mint 亮色（默认） |
+| `dark`  | Mint 暗色 |
+| `light-parchment` | Parchment 亮色 |
+| `dark-parchment` | Parchment 暗色 |
 
 ```tsx
 // 在根节点或任意父节点设置
@@ -128,7 +161,13 @@ function App() {
 <body data-theme="dark">
 ```
 
-主题对应的 CSS 变量定义在 **theme.css**（如 `--color-primary`、`--color-bg-container` 等）。自定义主题见下文「自定义 theme / scale」。
+如果你使用 React，`ThemeStyleProvider` 还支持按三维组合主题：
+
+- `appearance`: `light | dark`
+- `theme`: `mint | parchment | 自定义对象`
+- `style`: `neutral | compact | soft | sharp | dense`
+
+例如 `appearance="dark" theme="parchment" style="soft"` 会得到 `data-theme="dark-parchment"` 与 `data-style="soft"`。主题对应的 CSS 变量定义在 **theme.css**（如 `--color-primary`、`--color-bg-container` 等）。自定义主题见下文「自定义 theme / scale」。
 
 ### 3. 布局风格（scale）
 
@@ -156,7 +195,15 @@ function App() {
 </div>
 ```
 
-### 4. 自定义 theme / scale
+### 4. 真正决定风格的三件事
+
+- **颜色变量**：决定品牌色、背景、边框、语义色
+- **scale 变量**：决定间距、圆角、字号和组件密度
+- **图标系统**：决定视觉语言和产品气质
+
+官方 `mint` / `parchment` 只是两套 starter preset。无论你用整包还是 CLI，长期稳定的定制入口都应该是 token + icons，而不是依赖 preset 名称本身。
+
+### 5. 自定义 theme / scale
 
 在**先引入设计系统样式之后**，用你自己的 CSS 覆盖变量即可。
 
@@ -180,9 +227,9 @@ function App() {
 }
 ```
 
-完整变量清单见 [NPM 发布指南](https://github.com/nicepkg/spark-design/blob/master/docs/NPM发布指南.md)（颜色 `--color-*`、间距 `--spacing-*`、圆角 `--radius-*`、字号 `--font-size-*` 等）。
+完整变量说明见 [主题自定义指南](docs/guides/theme-customization.md)（颜色 `--color-*`、间距 `--spacing-*`、圆角 `--radius-*`、字号 `--font-size-*` 等）。
 
-### 5. Portal 浮层与主题一致
+### 6. Portal 浮层与主题一致
 
 DropdownMenu、Tooltip 等会挂到 `body`，不会继承局部容器的 `data-theme` / `data-style`。两种做法：
 
@@ -193,11 +240,12 @@ DropdownMenu、Tooltip 等会挂到 `body`，不会继承局部容器的 `data-t
 import { ThemeStyleProvider, Button, DropdownMenu } from 'sparkdesign'
 
 function App() {
-  const theme = 'dark'
+  const appearance = 'dark'
+  const theme = 'mint'
   const style = 'soft'
   return (
-    <ThemeStyleProvider value={{ theme, style }}>
-      <div data-theme={theme} data-style={style}>
+    <ThemeStyleProvider appearance={appearance} theme={theme} style={style}>
+      <div data-theme="dark" data-style={style}>
         <Button>打开</Button>
         <DropdownMenu>...</DropdownMenu>
       </div>
@@ -231,16 +279,20 @@ function App() {
 | **Basic** | 原子级 UI 组件 | Button, IconButton, Tooltip, Select, DropdownMenu, Tabs, Toast, Tag, Progress, Avatar, Table, Slider, Pagination, Collapse, Resizable, Scrollbar, Skeleton, Spinner, Kbd, EllipsisText, Switch, Toggle, ToggleGroup, RadioGroup, AlertDialog, OptionList … |
 | **Chat** | 对话流相关组件 | ChatInput, SendButton, Request, Response, FileCard, FileAttachment, ImageAttachment, FolderButton, ReasoningStep, ToolInvocationCard, PermissionCard, MarkdownBody, GenerationStatusBar, ThinkingIndicator, ImageGenerating, RelatedPrompts, SuggestionPart, SidebarMenu … |
 
-完整导出见 [src/components/index.ts](src/components/index.ts)。图标通过 `IconsProvider` / `useIcon` 注入，可替换为 Lucide、Remix 等，见 [图标自定义说明](docs/图标自定义说明.md)。
+完整导出见 [src/components/index.ts](src/components/index.ts)。图标通过 `IconsProvider` / `useIcon` 注入，可替换为 Lucide、Remix 等，见 [图标自定义说明](docs/guides/icons-customization.md)。
 
 ## 文档（仓库内）
 
 | 文档 | 说明 |
 |------|------|
-| [NPM 发布指南](docs/NPM发布指南.md) | 变量清单、主题覆盖、发布步骤 |
-| [组件入库文档](docs/组件入库文档.md) | 组件与 Showcase 规范 |
-| [图标自定义说明](docs/图标自定义说明.md) | IconsProvider / 替换为 Lucide 等 |
-| [CLI 按需引入方案](docs/CLI按需引入方案.md) | `npx sparkdesign init / add` 使用说明 |
+| [NPM 快速上手](docs/getting-started.md) | 整包引入、ThemeStyleProvider、Portal 主题继承 |
+| [CLI 快速上手](docs/getting-started-cli.md) | `npx sparkdesign init / add` 入门 |
+| [组件入库文档](docs/guides/component-development.md) | 组件与 Showcase 规范 |
+| [图标自定义说明](docs/guides/icons-customization.md) | IconsProvider / 替换为 Lucide 等 |
+| [CLI 按需引入方案](docs/cli/on-demand-import.md) | CLI 架构与按需引入说明 |
+| [Component Lifecycle SOP](docs/sop/component-lifecycle.md) | 组件从开发到发布的固定流程 |
+| [Theme Lifecycle SOP](docs/sop/theme-lifecycle.md) | preset / token / ThemeStyleProvider 维护流程 |
+| [Release Checklist](docs/sop/release-checklist.md) | 发布前后检查单 |
 
 ---
 
@@ -262,7 +314,7 @@ cd apps/showcase && npm install && npm run dev
 |------|------|
 | `npm run dev` | 设计系统开发服务器 |
 | `npm run build` | 生产构建：Vite 输出 JS → @tailwindcss/cli 预编译 CSS → tsc 类型声明 |
-| `npm run build:css` | 仅重新生成预编译 CSS（`dist/qoder-design.css`） |
+| `npm run build:css` | 仅重新生成预编译 CSS（`dist/sparkdesign.css`） |
 | `npm run preview` | 预览构建产物 |
 | `cd apps/showcase && npm run dev` | 组件展示站点 |
 
@@ -280,7 +332,7 @@ src/
 ### 技术栈与规范
 
 - React 19 + TypeScript + Vite 7；Tailwind CSS 4；Radix UI、Framer Motion
-- 项目哲学与 GEB 协议：[CLAUDE.md](https://github.com/nicepkg/spark-design/blob/master/CLAUDE.md)
+- 项目哲学与 GEB 协议：[AGENTS.md](https://github.com/nicepkg/spark-design/blob/master/AGENTS.md)
 
 ---
 

package/cli/dist/commands/add.js

@@ -1,44 +1,53 @@
 /**
- * [INPUT]: components[] from argv, options.overwrite
- * [OUTPUT]: void - 写入组件文件到用户项目
- * [POS]: cli/src/commands/add.ts
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: cli/src/commands/add.ts — Spark Design source; keep aligned with the main library.
  *
- * [PROTOCOL]: 文件逻辑变更时同步更新此 Header
+ * [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.
  */
 import path from 'node:path';
 import fs from 'fs-extra';
 import chalk from 'chalk';
-import { execa } from 'execa';
 import { readConfig, writeConfig, getComponentsBaseAlias, resolveTargetDir } from '../utils/config.js';
 import { getRegistryRoot, getComponentMeta, getComponentSource } from '../utils/registry.js';
 import { stripL3Header, transformImports } from '../utils/transform.js';
-import { projectHasTokens, writeQoderTokensFile, getQoderTokensImportPath } from '../utils/tokens.js';
+import { projectHasTokens, writeSparkTokensFile, getSparkTokensImportPath } from '../utils/tokens.js';
+import { detectPackageManager, getInstallCommand, installDependencies } from '../utils/package-manager.js';
+import { ensureTsAlias } from '../utils/tsconfig.js';
 export async function add(components, options = {}) {
     const cwd = process.cwd();
     const registryRoot = getRegistryRoot();
-    let config = await readConfig(cwd);
+    const config = await readConfig(cwd);
     const hasConfig = await fs.pathExists(path.join(cwd, 'components.json'));
     if (!hasConfig) {
         await writeConfig(config, cwd);
         console.log(chalk.green('✓'), 'Created components.json (default config)');
     }
+    await ensureTsAlias(cwd);
     const hasTokens = await projectHasTokens(cwd);
     if (!hasTokens) {
-        const { path: tokensPath, created } = await writeQoderTokensFile(cwd, registryRoot);
+        const { path: tokensPath, created } = await writeSparkTokensFile(cwd, registryRoot);
         if (created) {
             console.log(chalk.green('✓'), 'Created', tokensPath);
         }
         console.log(chalk.cyan('  To enable component styles, add to your app entry (e.g. main.tsx or layout.tsx):'));
-        console.log(chalk.yellow('  import'), chalk.white(`'${getQoderTokensImportPath()}'`));
+        console.log(chalk.yellow('  import'), chalk.white(`'${getSparkTokensImportPath()}'`));
         console.log(chalk.gray('  (Paste the line above into your entry file.)'));
         console.log(chalk.gray('  Or run'), chalk.cyan('npx sparkdesign init'), chalk.gray('for full setup with tokens in your CSS entry.'));
     }
+    const allDeps = new Set();
     const utilsDest = path.join(cwd, 'src', 'lib', 'utils.ts');
     if (!(await fs.pathExists(utilsDest))) {
         const utilsTemplate = await fs.readFile(path.join(registryRoot, 'lib', 'utils.ts'), 'utf-8');
         await fs.ensureDir(path.dirname(utilsDest));
         await fs.writeFile(utilsDest, utilsTemplate, 'utf-8');
         console.log(chalk.green('✓'), 'Created', utilsDest);
+        allDeps.add('clsx');
+        allDeps.add('tailwind-merge');
     }
     if (!components || components.length === 0) {
         console.log(chalk.cyan('Usage:'), 'npx sparkdesign add button [tooltip] [dropdown-menu]');
@@ -52,7 +61,6 @@ export async function add(components, options = {}) {
     console.log(chalk.gray('  目标目录:'), chalk.cyan(path.relative(cwd, targetDir) || targetDir));
     console.log(chalk.gray('  (components.json → aliases.ui)'));
     console.log('');
-    const allDeps = new Set();
     for (const name of components) {
         const meta = await getComponentMeta(registryRoot, name);
         if (!meta) {
@@ -82,12 +90,14 @@ export async function add(components, options = {}) {
         console.log(chalk.cyan('Installing dependencies...'));
         const depsArray = Array.from(allDeps);
         try {
-            await execa('npm', ['install', ...depsArray], { cwd, stdio: 'inherit' });
-            console.log(chalk.green('✓'), 'Installed', depsArray.length, 'dependencies');
+            const { pm } = await installDependencies(cwd, depsArray);
+            console.log(chalk.green('✓'), `Installed ${depsArray.length} dependencies via ${pm}`);
         }
         catch {
+            const pm = await detectPackageManager(cwd);
+            const install = getInstallCommand(pm, depsArray);
             console.log(chalk.yellow('○'), 'Auto-install failed. Run manually:');
-            console.log('  npm install', depsArray.join(' '));
+            console.log(`  ${install.display}`);
         }
     }
 }

package/cli/dist/commands/diff.js

@@ -1,9 +1,13 @@
 /**
- * [INPUT]: component name from argv
- * [OUTPUT]: void - 打印本地文件与注册表版本的 diff
- * [POS]: cli/src/commands/diff.ts
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: cli/src/commands/diff.ts — Spark Design source; keep aligned with the main library.
  *
- * [PROTOCOL]: 文件逻辑变更时同步更新此 Header
+ * [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.
  */
 import path from 'node:path';
 import fs from 'fs-extra';

package/cli/dist/commands/init.js

@@ -1,18 +1,23 @@
 /**
- * [INPUT]: 无（从 process.cwd() 读取项目）
- * [OUTPUT]: void - 写入 components.json、tokens、utils
- * [POS]: cli/src/commands/init.ts
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: cli/src/commands/init.ts — Spark Design source; keep aligned with the main library.
  *
- * [PROTOCOL]: 文件逻辑变更时同步更新此 Header
+ * [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.
  */
 import path from 'node:path';
 import fs from 'fs-extra';
 import prompts from 'prompts';
 import chalk from 'chalk';
-import { execa } from 'execa';
 import { writeConfig } from '../utils/config.js';
 import { getRegistryRoot } from '../utils/registry.js';
 import { ensureDesignTokens, projectHasTokens } from '../utils/tokens.js';
+import { detectPackageManager, getInstallCommand, installDependencies } from '../utils/package-manager.js';
+import { ensureTsAlias } from '../utils/tsconfig.js';
 const STYLES = [
     { title: 'neutral（平衡标准）', value: 'neutral' },
     { title: 'compact（紧凑）', value: 'compact' },
@@ -20,10 +25,54 @@ const STYLES = [
     { title: 'sharp（几何）', value: 'sharp' },
     { title: 'dense（密集）', value: 'dense' },
 ];
+const APPEARANCES = [
+    { title: 'light（亮色）', value: 'light' },
+    { title: 'dark（暗色）', value: 'dark' },
+];
+const THEMES = [
+    { title: 'mint', value: 'mint', description: '官方绿色主题起点' },
+    { title: 'parchment', value: 'parchment', description: '温暖纸感外观' },
+];
+function getDataThemeLabel(appearance, theme) {
+    if (theme === 'mint') {
+        return appearance;
+    }
+    return `${appearance}-${theme}`;
+}
 function resolveComponentsDir(aliasesComponents) {
     const trimmed = aliasesComponents.replace(/^@\//, '');
     return trimmed ? path.join('src', trimmed) : 'src/components';
 }
+/** 检查样式链路完整性，缺失时输出可复制的修复命令 */
+async function checkStyleChain(cwd, injectedCss) {
+    const pkgPath = path.join(cwd, 'package.json');
+    if (!(await fs.pathExists(pkgPath)))
+        return;
+    const pkg = await fs.readJson(pkgPath);
+    const allDeps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    const pm = await detectPackageManager(cwd);
+    const isVite = Boolean(allDeps['vite'] || allDeps['@vitejs/plugin-react']);
+    if (!allDeps['tailwindcss']) {
+        const deps = isVite
+            ? ['tailwindcss', '@tailwindcss/vite']
+            : ['tailwindcss', '@tailwindcss/postcss'];
+        console.log(chalk.yellow('⚠'), 'Spark Design 需要 Tailwind CSS 4 驱动样式，当前未检测到：');
+        console.log(chalk.cyan(`   ${getInstallCommand(pm, deps).display}`));
+        if (isVite) {
+            console.log(chalk.gray('   然后在 vite.config 中添加插件:'));
+            console.log(chalk.cyan('   import tailwindcss from "@tailwindcss/vite"'));
+            console.log(chalk.cyan('   // plugins: [tailwindcss(), ...]'));
+        }
+    }
+    else if (isVite && !allDeps['@tailwindcss/vite'] && !allDeps['@tailwindcss/postcss']) {
+        console.log(chalk.yellow('⚠'), 'Tailwind 已安装但缺少 Vite 集成插件：');
+        console.log(chalk.cyan(`   ${getInstallCommand(pm, ['@tailwindcss/vite']).display}`));
+    }
+    if (injectedCss) {
+        const rel = path.relative(path.join(cwd, 'src'), injectedCss).replace(/\\/g, '/');
+        console.log(chalk.gray('   确保入口文件（如 main.tsx）引入了样式:'), chalk.cyan(`import './${rel}'`));
+    }
+}
 export async function init() {
     const cwd = process.cwd();
     const registryRoot = getRegistryRoot();
@@ -36,6 +85,20 @@ export async function init() {
             choices: STYLES,
             initial: 0,
         },
+        {
+            type: 'select',
+            name: 'appearance',
+            message: '选择亮暗外观 (appearance)',
+            choices: APPEARANCES,
+            initial: 0,
+        },
+        {
+            type: 'select',
+            name: 'theme',
+            message: '选择颜色主题 (theme family)',
+            choices: THEMES,
+            initial: 0,
+        },
         {
             type: 'text',
             name: 'componentsDir',
@@ -53,10 +116,14 @@ export async function init() {
         process.exit(0);
     }
     const style = answers.style;
+    const appearance = answers.appearance;
+    const theme = answers.theme;
     const rawDir = (answers.componentsDir ?? 'components').toString().trim().replace(/^src\/?/, '');
     const componentsPath = rawDir || 'components';
     const config = {
         style,
+        appearance,
+        theme,
         aliases: {
             components: `@/${componentsPath}`,
             utils: '@/lib/utils',
@@ -65,6 +132,7 @@ export async function init() {
     };
     await writeConfig(config, cwd);
     console.log(chalk.green('✓'), 'Created components.json');
+    await ensureTsAlias(cwd);
     const componentsDir = resolveComponentsDir(config.aliases.components);
     const libDir = path.join(cwd, 'src', 'lib');
     const utilsDest = path.join(libDir, 'utils.ts');
@@ -80,17 +148,24 @@ export async function init() {
         console.log(chalk.yellow('○'), 'Design tokens already present in project');
     }
     else {
-        console.log(chalk.yellow('○'), 'Could not inject tokens (no CSS entry found). Add theme/scale manually.');
+        console.log(chalk.yellow('⚠'), 'Token 注入失败。请手动创建 CSS 入口后重试：');
+        console.log(chalk.cyan('   mkdir -p src && touch src/index.css'));
+        console.log(chalk.gray('   然后重新运行'), chalk.cyan('npx sparkdesign init'));
     }
+    await checkStyleChain(cwd, injected);
     if (answers.installDeps) {
+        const deps = ['class-variance-authority', 'clsx', 'tailwind-merge'];
         try {
-            await execa('npm', ['install', 'class-variance-authority', 'clsx', 'tailwind-merge'], { cwd, stdio: 'inherit' });
-            console.log(chalk.green('✓'), 'Installed dependencies');
+            const { pm } = await installDependencies(cwd, deps);
+            console.log(chalk.green('✓'), `Installed dependencies via ${pm}`);
         }
         catch {
-            console.log(chalk.yellow('○'), 'Run manually: npm install class-variance-authority clsx tailwind-merge');
+            const pm = await detectPackageManager(cwd);
+            const install = getInstallCommand(pm, deps);
+            console.log(chalk.yellow('○'), `Run manually: ${install.display}`);
         }
     }
     await fs.ensureDir(path.join(cwd, componentsDir));
-    console.log(chalk.green('✓'), 'Spark Design initialized. Run'), chalk.cyan('npx sparkdesign add button'), chalk.green('to add components.');
+    console.log(chalk.green('✓'), 'Default theme preset:', chalk.cyan(`appearance=${appearance}`), chalk.cyan(`theme=${theme}`), chalk.gray(`(data-theme="${getDataThemeLabel(appearance, theme)}", data-style="${style}")`));
+    console.log(chalk.green('✓'), 'Spark Design initialized. Run', chalk.cyan('npx sparkdesign add button'), chalk.green('to add components.'));
 }

package/cli/dist/commands/list.js

@@ -1,9 +1,13 @@
 /**
- * [INPUT]: 无
- * [OUTPUT]: void - 打印注册表内所有组件名
- * [POS]: cli/src/commands/list.ts
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: cli/src/commands/list.ts — Spark Design source; keep aligned with the main library.
  *
- * [PROTOCOL]: 文件逻辑变更时同步更新此 Header
+ * [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.
  */
 import chalk from 'chalk';
 import { getRegistryRoot, listComponents } from '../utils/registry.js';

package/cli/dist/index.js

@@ -1,14 +1,17 @@
 #!/usr/bin/env node
 /**
- * [INPUT]: process.argv
- * [OUTPUT]: void - 执行对应子命令并退出
- * [POS]: cli/src/index.ts - Spark Design CLI 入口
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: cli/src/index.ts — Spark Design source; keep aligned with the main library.
  *
  * [PROTOCOL]:
- * 1. 逻辑变更时同步更新此 Header
- * 2. 子命令实现位于 commands/
+ * 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.
  */
 import { program } from 'commander';
+import rootPackageJson from '../../package.json' with { type: 'json' };
 import { init } from './commands/init.js';
 import { add } from './commands/add.js';
 import { list } from './commands/list.js';
@@ -16,7 +19,7 @@ import { diffCmd } from './commands/diff.js';
 program
     .name('sparkdesign')
     .description('Spark Design CLI - 按需添加组件（源码复制到当前项目）')
-    .version('0.1.0');
+    .version(rootPackageJson.version);
 program
     .command('init')
     .description('初始化项目：写入 components.json、tokens、utils')

package/cli/dist/utils/config.js

@@ -1,25 +1,31 @@
 /**
- * [INPUT]: process.cwd() 下的 components.json
- * [OUTPUT]: Config | 默认配置
- * [POS]: cli/src/utils/config.ts
+ * [WHO]: Public exports from this file (see implementation below).
+ * [FROM]: See the import block immediately after this header.
+ * [TO]: sparkdesign package consumers; output of CLI `add` when applicable.
+ * [HERE]: cli/src/utils/config.ts — Spark Design source; keep aligned with the main library.
  *
- * [PROTOCOL]: 文件逻辑变更时同步更新此 Header
+ * [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.
  */
 import path from 'node:path';
 import fs from 'fs-extra';
 const defaultConfig = {
     style: 'neutral',
+    appearance: 'light',
+    theme: 'mint',
     aliases: {
         components: '@/components',
         utils: '@/lib/utils',
         ui: '@/components/ui',
     },
 };
-/** 优先用 aliases.ui 作为组件安装目录，未设时用 components + '/qoder'（兼容旧配置） */
+/** 优先用 aliases.ui 作为组件安装目录，未设时回退到 components + '/ui' */
 export function getComponentsBaseAlias(config) {
-    return config.aliases.ui ?? config.aliases.components + '/qoder';
+    return config.aliases.ui ?? config.aliases.components + '/ui';
 }
-/** 将 alias 解析为绝对目录（如 @/components/qoder → cwd/src/components/qoder） */
+/** 将 alias 解析为绝对目录（如 @/components/ui → cwd/src/components/ui） */
 export function resolveTargetDir(aliasesBase, cwd) {
     const withoutAlias = aliasesBase.replace(/^@\//, '').trim();
     let base = withoutAlias || 'components';
@@ -33,6 +39,8 @@ export async function readConfig(cwd = process.cwd()) {
         const parsed = JSON.parse(content);
         return {
             style: parsed.style ?? defaultConfig.style,
+            appearance: parsed.appearance ?? defaultConfig.appearance,
+            theme: parsed.theme ?? defaultConfig.theme,
             aliases: {
                 components: parsed.aliases?.components ?? defaultConfig.aliases.components,
                 utils: parsed.aliases?.utils ?? defaultConfig.aliases.utils,
@@ -47,7 +55,7 @@ export async function readConfig(cwd = process.cwd()) {
 export async function writeConfig(config, cwd = process.cwd()) {
     const configPath = path.join(cwd, 'components.json');
     await fs.writeJson(configPath, {
-        $schema: 'https://qoder.design/schema.json',
+        $schema: 'https://spark.design/schema.json',
         ...config,
     }, { spaces: 2 });
 }