sparkdesign 0.4.5 → 0.4.7

package/dist/theme-base.css

@@ -1,13 +1,12 @@
 /* ============================================
- * [POS]: src/tokens/theme-base.css - Tailwind v4 @theme 映射 + 动画 + 公共样式
- * [OUTPUT]: CSS 变量映射到 Tailwind 工具类
+ * [WHO]: Tailwind v4 `@theme` bridge, motion presets, scrollbar helpers — no palette hex here.
+ * [FROM]: Runtime vars from scale (`--font-size-*`, `--spacing-*`, `--radius-*`) and themes (`--token-color-*`).
+ * [TO]: Any bundle that imports tokens and needs Tailwind utilities resolved from CSS variables.
+ * [HERE]: src/tokens/theme-base.css — mapping contract only; literal colors live in `themes/*.css`.
  *
- * 此文件定义了 Token → Tailwind 的映射契约，不包含具体颜色值。
- * 颜色值由 themes/*.css 中的 [data-theme="xxx"] 块定义。
- *
- * 用户自定义主题时只需：
- * 1. 引入此文件（定义映射）
- * 2. 引入自己的主题 CSS（覆盖 --token-color-* 变量）
+ * [PROTOCOL]:
+ * 1. Do not embed theme colors in this file; define `--token-color-*` under `[data-theme]` in theme files.
+ * 2. Custom themes: import this for mappings, then add/override `--token-color-*` in your theme layer.
  * ============================================ */
 
 /* ============================================

package/dist/theme.css

@@ -11,7 +11,7 @@
  * ============================================ */
 
 @import "./theme-base.css";
-@import "./themes/light-qoder.css";
-@import "./themes/dark-qoder.css";
+@import "./themes/light-mint.css";
+@import "./themes/dark-mint.css";
 @import "./themes/light-parchment.css";
 @import "./themes/dark-parchment.css";

package/dist/themes/{dark-qoder.css → dark-mint.css}

@@ -1,5 +1,5 @@
 /* ============================================
- * Theme: Dark (暗色模式)
+ * Theme: Dark Mint (暗色模式)
  * 用户可复制此文件作为自定义主题模板
  * ============================================ */
 

package/dist/themes/{light-qoder.css → light-mint.css}

@@ -1,5 +1,5 @@
 /* ============================================
- * Theme: Light (亮色模式)
+ * Theme: Light Mint (亮色模式)
  * 用户可复制此文件作为自定义主题模板
  * ============================================ */
 

package/dist/tokens/AGENTS.md

@@ -0,0 +1,48 @@
+# src/tokens/
+
+> **P2** | Parent: [Root AGENTS.md](../../AGENTS.md)
+
+## Member list (CSS entrypoints)
+
+| Area | Files | Purpose |
+| ---- | ----- | ------- |
+| Bundle | `index.css` | Recommended full import |
+| Scale | `scale/`, `scale.css` (legacy) | Layout tokens (`data-style`) via config + computed + presets |
+| Theme bridge | `theme-base.css`, `theme.css` (legacy) | Tailwind `@theme` mappings, shared motion, scrollbar helpers |
+| Color packs | `themes/*.css` | Palette definitions (`--token-color-*`) |
+| Agent ontology | `registry/tokens/ontology.json` | Machine-readable token intent, usage, and forbidden patterns |
+| Utilities | `scrollbar-utility.css` | Scrollbar styling helpers |
+
+---
+
+**Covenant:** whenever you add presets, themes, or rename token files, update this table and the root `AGENTS.md` if publishing behavior changes.
+
+---
+
+## Narrative
+
+### Two axes
+
+1. **`data-style`** — spacing, radii, typography presets (`scale/`).
+2. **`data-theme`** — color palettes independent from layout. Define **`--token-color-*`** in `:root` / `[data-theme]`, map to **`--color-*`** inside `@theme` without self-referential loops (critical for CLI consumers).
+
+### Authoring rules
+
+- Never create `@theme` entries such as `--color-primary: var(--color-primary)` — use `--token-color-*` as the source of truth.
+- Components consume **`var(--color-*)`** only; token files own the mapping.
+- When adding a preset or theme, cover spacing, radius, and font scales consistently.
+
+### Consumption modes
+
+| Mode | What happens | Consumer needs Tailwind? |
+| ---- | ------------- | ------------------------- |
+| npm package | `@tailwindcss/cli` emits `dist/sparkdesign.css` | No |
+| CLI copy | User `@import`s token CSS in their app | Tailwind v4 recommended |
+
+### Checklist
+
+- [ ] New `data-style` preset updates `scale/presets/`
+- [ ] New configurable knobs land in `scale/config.css` + `computed.css`
+- [ ] New theme file added under `themes/` and wired through `index.css`
+- [ ] Contrast checked for accessibility
+- [ ] This P2 file reflects the change

package/dist/tokens/index.css

@@ -1,22 +1,13 @@
 /* ============================================
- * [POS]: src/tokens/index.css - Token 系统统一入口
+ * [WHO]: Default token stack entry — wires scale, theme bridge, scrollbar helper, and built-in themes.
+ * [FROM]: `./scale.css`, `theme-base.css`, `themes/*.css`, `scrollbar-utility.css`.
+ * [TO]: Apps that want one import for layout + color tokens; CLI `init` / docs full-import path.
+ * [HERE]: src/tokens/index.css — bundle root; see `src/tokens/AGENTS.md` for cherry-pick imports.
  *
- * 引入方式：
- * 1. 全量引入（默认）: @import "./tokens/index.css";
- * 2. 按需引入:
- *    @import "./tokens/scale/config.css";    // 可配置基础变量
- *    @import "./tokens/scale/computed.css"; // 映射到实际变量
- *    @import "./tokens/theme-base.css";
- *    @import "./tokens/themes/light-qoder.css";
- *
- * 自定义布局配置：
- * @import "./tokens/scale/config.css";
- * @import "./tokens/scale/computed.css";
- * :root { --config-radius-default: 10px; }   // 覆盖配置
- *
- * 自定义颜色主题：
- * @import "./tokens/theme-base.css";
- * @import "./my-custom-theme.css";  // 定义 [data-theme="xxx"] { --token-color-*: ... }
+ * [PROTOCOL]:
+ * 1. When adding a new theme file, import it here and document in P2 `src/tokens/AGENTS.md`.
+ * 2. Custom layout: import `scale/config.css` + `scale/computed.css`, override `--config-*`, then theme layers.
+ * 3. Custom color only: `theme-base.css` + your `[data-theme]` file setting `--token-color-*`.
  * ============================================ */
 
 /* 布局风格 Token (data-style: neutral | compact | soft | sharp | dense) */
@@ -26,8 +17,8 @@
 @import "./theme-base.css";
 
 /* 内置主题 (data-theme) */
-@import "./themes/light-qoder.css";
-@import "./themes/dark-qoder.css";
+@import "./themes/light-mint.css";
+@import "./themes/dark-mint.css";
 @import "./themes/light-parchment.css";
 @import "./themes/dark-parchment.css";
 

package/dist/tokens/scale/presets/compact.css

@@ -1,6 +1,6 @@
 /* ============================================
  * Preset: Compact - 紧凑风格
- * 优化效率，适合信息密集场景
+ * 小幅压缩控件节奏，适合效率型工作台
  * ============================================ */
 
 [data-style="compact"] {
@@ -15,14 +15,25 @@
   --radius-2xl: 12px;
   --radius-3xl: 16px;
 
-  /* Font Size (略小) */
-  --font-size-sm: 12px;
-  --font-size-lg: 14px;
-  --font-size-xl: 16px;
+  /* Font Size (略小但保持阅读舒适) */
+  --font-size-xs: 12px;
+  --font-size-xs--line-height: 16px;
+  --font-size-sm: 13px;
+  --font-size-sm--line-height: 18px;
+  --font-size-base: 14px;
+  --font-size-base--line-height: 20px;
+  --font-size-lg: 15px;
+  --font-size-lg--line-height: 22px;
+  --font-size-xl: 17px;
+  --font-size-xl--line-height: 24px;
   --font-size-2xl: 18px;
+  --font-size-2xl--line-height: 24px;
   --font-size-3xl: 22px;
+  --font-size-3xl--line-height: 28px;
   --font-size-4xl: 28px;
+  --font-size-4xl--line-height: 32px;
   --font-size-5xl: 34px;
+  --font-size-5xl--line-height: 36px;
   --font-size-6xl: 44px;
   --font-size-7xl: 56px;
   --font-size-8xl: 64px;

package/dist/tokens/scale/presets/dense.css

@@ -49,14 +49,25 @@
   /* ChatInput 特殊配置 */
   --chat-status-overlap: 4px;
 
-  /* Font Size (更小) */
-  --font-size-base: 12px;
+  /* Font Size (信息密集：主力 text-sm 也压缩) */
+  --font-size-xs: 11px;
+  --font-size-xs--line-height: 14px;
+  --font-size-sm: 12px;
+  --font-size-sm--line-height: 16px;
+  --font-size-base: 13px;
+  --font-size-base--line-height: 18px;
   --font-size-lg: 14px;
+  --font-size-lg--line-height: 20px;
   --font-size-xl: 14px;
+  --font-size-xl--line-height: 20px;
   --font-size-2xl: 16px;
+  --font-size-2xl--line-height: 22px;
   --font-size-3xl: 18px;
+  --font-size-3xl--line-height: 24px;
   --font-size-4xl: 22px;
+  --font-size-4xl--line-height: 28px;
   --font-size-5xl: 28px;
+  --font-size-5xl--line-height: 32px;
   --font-size-6xl: 36px;
   --font-size-7xl: 44px;
   --font-size-8xl: 56px;

package/dist/tokens/scale/presets/sharp.css

@@ -1,12 +1,14 @@
 /* ============================================
  * Preset: Sharp - 锐利风格
- * 几何精度，无圆角 + 等宽字体
+ * 几何精度，无圆角 + 等宽字体 + 硬朗节奏
  * ============================================ */
 
 [data-style="sharp"] {
-  /* Spacing (与 compact 相同) */
+  /* Spacing (方正、克制，少量压缩) */
   --spacing-3: 10px;
   --spacing-4: 14px;
+  --spacing-5: 18px;
+  --spacing-6: 22px;
   --spacing-9: 32px;
   --spacing-11: 40px;
 
@@ -25,13 +27,23 @@
   --font-sans: var(--config-font-mono);
   font-family: var(--font-sans);
 
-  /* Font Size (与 compact 相同) */
-  --font-size-sm: 12px;
-  --font-size-lg: 14px;
-  --font-size-xl: 16px;
+  /* Font Size (工程感：略紧、等宽、层级清楚) */
+  --font-size-xs: 12px;
+  --font-size-xs--line-height: 16px;
+  --font-size-sm: 13px;
+  --font-size-sm--line-height: 18px;
+  --font-size-base: 14px;
+  --font-size-base--line-height: 20px;
+  --font-size-lg: 15px;
+  --font-size-lg--line-height: 22px;
+  --font-size-xl: 17px;
+  --font-size-xl--line-height: 24px;
   --font-size-2xl: 18px;
+  --font-size-2xl--line-height: 24px;
   --font-size-3xl: 22px;
+  --font-size-3xl--line-height: 28px;
   --font-size-4xl: 28px;
+  --font-size-4xl--line-height: 32px;
   --font-size-5xl: 34px;
   --font-size-6xl: 44px;
   --font-size-7xl: 56px;

package/dist/tokens/scale/presets/soft.css

@@ -4,7 +4,17 @@
  * ============================================ */
 
 [data-style="soft"] {
-  /* 只覆盖 Radius (大圆角) */
+  /* Spacing (舒展留白) */
+  --spacing-3: 14px;
+  --spacing-4: 18px;
+  --spacing-5: 24px;
+  --spacing-6: 28px;
+  --spacing-8: 36px;
+  --spacing-9: 40px;
+  --spacing-11: 48px;
+  --spacing-12: 56px;
+
+  /* Radius (大圆角) */
   --radius-sm: 8px;
   --radius-DEFAULT: 12px;
   --radius-md: 12px;
@@ -13,4 +23,16 @@
   --radius-2xl: 24px;
   --radius-3xl: 28px;
   --radius: var(--radius-DEFAULT);
+
+  /* Font Size (阅读舒适，行高更松) */
+  --font-size-sm: 14px;
+  --font-size-sm--line-height: 22px;
+  --font-size-base: 15px;
+  --font-size-base--line-height: 24px;
+  --font-size-lg: 17px;
+  --font-size-lg--line-height: 26px;
+  --font-size-xl: 20px;
+  --font-size-xl--line-height: 28px;
+  --font-size-2xl: 22px;
+  --font-size-2xl--line-height: 30px;
 }

package/dist/tokens/theme-base.css

@@ -1,13 +1,12 @@
 /* ============================================
- * [POS]: src/tokens/theme-base.css - Tailwind v4 @theme 映射 + 动画 + 公共样式
- * [OUTPUT]: CSS 变量映射到 Tailwind 工具类
+ * [WHO]: Tailwind v4 `@theme` bridge, motion presets, scrollbar helpers — no palette hex here.
+ * [FROM]: Runtime vars from scale (`--font-size-*`, `--spacing-*`, `--radius-*`) and themes (`--token-color-*`).
+ * [TO]: Any bundle that imports tokens and needs Tailwind utilities resolved from CSS variables.
+ * [HERE]: src/tokens/theme-base.css — mapping contract only; literal colors live in `themes/*.css`.
  *
- * 此文件定义了 Token → Tailwind 的映射契约，不包含具体颜色值。
- * 颜色值由 themes/*.css 中的 [data-theme="xxx"] 块定义。
- *
- * 用户自定义主题时只需：
- * 1. 引入此文件（定义映射）
- * 2. 引入自己的主题 CSS（覆盖 --token-color-* 变量）
+ * [PROTOCOL]:
+ * 1. Do not embed theme colors in this file; define `--token-color-*` under `[data-theme]` in theme files.
+ * 2. Custom themes: import this for mappings, then add/override `--token-color-*` in your theme layer.
  * ============================================ */
 
 /* ============================================

package/dist/tokens/theme.css

@@ -11,7 +11,7 @@
  * ============================================ */
 
 @import "./theme-base.css";
-@import "./themes/light-qoder.css";
-@import "./themes/dark-qoder.css";
+@import "./themes/light-mint.css";
+@import "./themes/dark-mint.css";
 @import "./themes/light-parchment.css";
 @import "./themes/dark-parchment.css";

package/dist/tokens/themes/dark-mint.css

@@ -0,0 +1,133 @@
+/* ============================================
+ * Theme: Dark Mint (暗色模式)
+ * 用户可复制此文件作为自定义主题模板
+ * ============================================ */
+
+[data-theme="dark"] {
+  color-scheme: dark;
+  /* --- Primary --- */
+  --token-color-primary: #8EE5A1;
+  --token-color-primary-hover: #9BE6B3;
+  --token-color-primary-active: #73CD94;
+  --token-color-primary-bg: #14261C;
+  --token-color-primary-bg-hover: #1A2E21;
+  --token-color-primary-border: #335942;
+  --token-color-primary-border-hover: #407354;
+  --token-color-primary-text: #8EE5A1;
+  --token-color-primary-text-hover: #9BE6B3;
+  --token-color-primary-text-active: #73CD94;
+  --token-color-text-on-primary: #0D0D0D;
+
+  /* --- Text --- */
+  --token-color-text: #FAF9F5;
+  --token-color-text-secondary: #9C9D9E;
+  --token-color-text-tertiary: #7C7D7F;
+  --token-color-text-quaternary: #717374;
+  --token-color-text-base: #F0F2F3;
+
+  /* --- Border --- */
+  --token-color-border: #404040;
+  --token-color-border-secondary: #2A2A2A;
+  --token-color-border-tertiary: #262626;
+
+  /* --- Fill --- */
+  --token-color-fill: #454545;
+  --token-color-fill-secondary: #363636;
+  --token-color-fill-tertiary: #1A1A1A;
+  --token-color-fill-quaternary: #1A1A1A;
+  --token-color-fill-disable: #525252;
+
+  /* --- Background --- */
+  --token-color-bg-container: #0D0D0D;
+  --token-color-bg-elevated: #080808;
+  --token-color-bg-layout: #050505;
+  --token-color-bg-spotlight: #080808;
+  --token-color-bg-mask: rgba(0, 0, 0, 0.7);
+  /* PlanPart 点阵高亮遮罩渐变（随主题） */
+  --token-color-mask-shimmer-weak: rgba(0, 0, 0, 0.3);
+  --token-color-mask-shimmer-strong: rgba(0, 0, 0, 0.8);
+  --token-color-mask-shimmer-full: rgba(0, 0, 0, 1);
+  --token-color-bg-base: #000000;
+  --token-color-bg-highlight: #d0d0d0;
+  --token-color-bg-highlight-hover: #e0e0e0;
+
+  /* --- Semantic Colors --- */
+  --token-color-link: #8EE5A1;
+  --token-color-error: #FF4D4F;
+  --token-color-error-hover: #FF7875;
+  --token-color-error-bg: #4A1A1B;
+  --token-color-error-bg-hover: #5C2224;
+  --token-color-error-border: #663338;
+  --token-color-info: #0B83F1;
+  --token-color-info-hover: #5EBCFF;
+  --token-color-info-bg: #19080E;
+  --token-color-info-bg-hover: #220A12;
+  --token-color-info-border: #4F1C0E;
+  --token-color-success: #73CD94;
+  --token-color-success-hover: #8EE5A1;
+  --token-color-success-bg: #14261C;
+  --token-color-success-bg-hover: #1A2E21;
+  --token-color-success-border: #335942;
+  --token-color-warning: #FAAD14;
+  --token-color-warning-hover: #FFD666;
+  --token-color-warning-bg: #4A4019;
+  --token-color-warning-bg-hover: #5C4E1F;
+  --token-color-warning-border: #664D19;
+
+  /* --- Accent Colors --- */
+  --token-color-pink: #EC4899;
+  --token-color-pink-bg: #4A1C31;
+  --token-color-pink-bg-hover: #5C2440;
+  --token-color-purple: #615CED;
+  --token-color-purple-bg: #14160E;
+  --token-color-purple-bg-hover: #1C1E14;
+  --token-color-yellow: #FAC414;
+  --token-color-yellow-bg: #4A4030;
+  --token-color-yellow-bg-hover: #5C5040;
+  --token-color-orange: #FA8125;
+  --token-color-orange-bg: #4A1021;
+  --token-color-orange-bg-hover: #5C1429;
+  --token-color-teal: #14B8A6;
+  --token-color-teal-bg: #21080E;
+  --token-color-teal-bg-hover: #2E0E14;
+  --token-color-blue: #0090FF;
+  --token-color-blue-bg: #21120E;
+  --token-color-blue-bg-hover: #2E1A14;
+  --token-color-mauve: #8E8C99;
+  --token-color-mauve-bg: #0E0D0C;
+  --token-color-mauve-bg-hover: #1A1818;
+  --token-color-slate: #363636;
+  --token-color-slate-bg: #1a1a1a;
+  --token-color-slate-bg-hover: #262626;
+  --token-color-lavender: #B99DFF;
+  --token-color-lavender-bg: #131B0E;
+  --token-color-lavender-bg-hover: #1C2614;
+  --token-color-sage: #6BB394;
+  --token-color-sage-bg: #100C0D;
+  --token-color-sage-bg-hover: #1A1418;
+
+  /* --- Select 等组件 (input/ring/popover 等) --- */
+  --token-color-input: var(--token-color-border-tertiary);
+  --token-color-ring: var(--token-color-primary-border);
+  --token-color-popover: var(--token-color-bg-container);
+  --token-color-popover-foreground: var(--token-color-text);
+  --token-color-accent: var(--token-color-fill-secondary);
+  --token-color-accent-foreground: var(--token-color-text);
+  --token-color-muted: var(--token-color-fill-tertiary);
+  --token-color-muted-foreground: var(--token-color-text-secondary);
+  --token-color-background: var(--token-color-bg-base);
+
+  /* --- Diff --- */
+  --token-color-diff-insert: #73CD94;
+  --token-color-diff-insert-bg: #14261C;
+  --token-color-diff-remove: #FC6B83;
+  --token-color-diff-remove-bg: #1C2E2A;
+}
+
+/* SendButton: dark 模式下 normal 状态使用 success 色（与 light 下 bg-bg-highlight 区分） */
+[data-theme="dark"] .SendButton-send {
+  background-color: var(--token-color-success);
+}
+[data-theme="dark"] .SendButton-send:hover:not(:disabled) {
+  background-color: var(--token-color-success-hover);
+}

package/dist/tokens/themes/light-mint.css

@@ -0,0 +1,132 @@
+/* ============================================
+ * Theme: Light Mint (亮色模式)
+ * 用户可复制此文件作为自定义主题模板
+ * ============================================ */
+
+:root,
+[data-theme="light"] {
+  color-scheme: light;
+  /* --- Primary --- */
+  --token-color-primary: #8EE5A1;
+  --token-color-primary-hover: #73CD94;
+  --token-color-primary-active: #5CB870;
+  --token-color-primary-bg: #F1FAF3;
+  --token-color-primary-bg-hover: #E6F7EC;
+  --token-color-primary-border: #CDEFD9;
+  --token-color-primary-border-hover: #B3E6C7;
+  --token-color-primary-text: #141414;
+  --token-color-primary-text-hover: #73CD94;
+  --token-color-primary-text-active: #5CB870;
+  --token-color-text-on-primary: #FDFDFD;
+
+  /* --- Text --- */
+  --token-color-text: #141414;
+  --token-color-text-secondary: #636261;
+  --token-color-text-tertiary: #838280;
+  --token-color-text-quaternary: #8E8C8B;
+  --token-color-text-base: #0F0D0C;
+
+  /* --- Border --- */
+  --token-color-border: #BCBBBA;
+  --token-color-border-secondary: #DDDDDD;
+  --token-color-border-tertiary: #E6E6E6;
+
+  /* --- Fill --- */
+  --token-color-fill: #DFDFDF;
+  --token-color-fill-secondary: #EFEFEF;
+  --token-color-fill-tertiary: #F9F9F9;
+  --token-color-fill-quaternary: #FCFCFC;
+  --token-color-fill-disable: #DAD9D8;
+
+  /* --- Background --- */
+  --token-color-bg-container: #FFFFFF;
+  --token-color-bg-elevated: #F9F9F9;
+  --token-color-bg-layout: #FDFDFD;
+  --token-color-bg-spotlight: #FAFAFA;
+  --token-color-bg-mask: rgba(0, 0, 0, 0.5);
+  /* PlanPart 点阵高亮遮罩渐变（随主题） */
+  --token-color-mask-shimmer-weak: rgba(0, 0, 0, 0.3);
+  --token-color-mask-shimmer-strong: rgba(0, 0, 0, 0.8);
+  --token-color-mask-shimmer-full: rgba(0, 0, 0, 1);
+  --token-color-bg-base: #FFFFFF;
+  --token-color-bg-highlight: #080807;
+  --token-color-bg-highlight-hover: #1a1a1a;
+
+  /* --- Shadow (输入框等浮层，1～4 级与 primary/secondary/tertiary/quaternary 一致，与 data-theme 无关) --- */
+  --token-color-shadow-primary: rgba(0, 0, 0, 0.02);
+  --token-color-shadow-secondary: rgba(0, 0, 0, 0.035);
+  --token-color-shadow-tertiary: rgba(0, 0, 0, 0.055);
+  --token-color-shadow-quaternary: rgba(0, 0, 0, 0.075);
+
+  /* --- Semantic Colors --- */
+  --token-color-link: #5CB870;
+  --token-color-error: #FF4D4F;
+  --token-color-error-hover: #FF7875;
+  --token-color-error-bg: #FFF2F0;
+  --token-color-error-bg-hover: #FFE4E0;
+  --token-color-error-border: #FFCCC7;
+  --token-color-info: #0B83F1;
+  --token-color-info-hover: #5EBCFF;
+  --token-color-info-bg: #E6F7FF;
+  --token-color-info-bg-hover: #D0EFFF;
+  --token-color-info-border: #B0E3FF;
+  --token-color-success: #73CD94;
+  --token-color-success-hover: #8EE5A1;
+  --token-color-success-bg: #F1FAF3;
+  --token-color-success-bg-hover: #E6F7EC;
+  --token-color-success-border: #CDEFD9;
+  --token-color-warning: #FAAD14;
+  --token-color-warning-hover: #FFD666;
+  --token-color-warning-bg: #FFFBE6;
+  --token-color-warning-bg-hover: #FFF3CF;
+  --token-color-warning-border: #FFE5BF;
+
+  /* --- Accent Colors --- */
+  --token-color-pink: #EC4899;
+  --token-color-pink-bg: #F9E3F3;
+  --token-color-pink-bg-hover: #F5D4EB;
+  --token-color-purple: #615CED;
+  --token-color-purple-bg: #EBE9FF;
+  --token-color-purple-bg-hover: #DDDAFF;
+  --token-color-yellow: #FAC414;
+  --token-color-yellow-bg: #FFF3CF;
+  --token-color-yellow-bg-hover: #FFE9A8;
+  --token-color-orange: #FA8125;
+  --token-color-orange-bg: #FFEFDE;
+  --token-color-orange-bg-hover: #FFE3C7;
+  --token-color-teal: #14B8A6;
+  --token-color-teal-bg: #DEF7F1;
+  --token-color-teal-bg-hover: #CAF0E8;
+  --token-color-blue: #0090FF;
+  --token-color-blue-bg: #DEEDFF;
+  --token-color-blue-bg-hover: #C8E3FF;
+  --token-color-mauve: #8E8C99;
+  --token-color-mauve-bg: #F1F2F3;
+  --token-color-mauve-bg-hover: #E4E5E7;
+  --token-color-slate: #404040;
+  --token-color-slate-bg: #FAFAFA;
+  --token-color-slate-bg-hover: #EFEFEF;
+  --token-color-lavender: #B99DFF;
+  --token-color-lavender-bg: #ECE4FF;
+  --token-color-lavender-bg-hover: #E0D4FF;
+  --token-color-sage: #6BB394;
+  --token-color-sage-bg: #EFF3F2;
+  --token-color-sage-bg-hover: #E2EAE8;
+
+  /* --- Select 等组件 (input/ring/popover 等) --- */
+  --token-color-input: var(--token-color-border-tertiary);
+  --token-color-ring: var(--token-color-primary-border);
+  --token-color-popover: var(--token-color-bg-container);
+  --token-color-popover-foreground: var(--token-color-text);
+  --token-color-accent: var(--token-color-fill-secondary);
+  --token-color-accent-foreground: var(--token-color-text);
+  --token-color-muted: var(--token-color-fill-tertiary);
+  --token-color-muted-foreground: var(--token-color-text-secondary);
+  --token-color-background: var(--token-color-bg-base);
+
+  /* --- Diff --- */
+  --token-color-diff-insert: #A6DCBA;
+  --token-color-diff-insert-bg: #D9EBE0;
+  --token-color-diff-remove: #FC6B83;
+  --token-color-diff-remove-bg: #E3D1D5;
+}

package/docs/agent/component-selection.md

@@ -0,0 +1,60 @@
+# Agent Component Selection
+
+This guide is the human-readable companion to `registry/agent-manifest.json`.
+Agents should read the manifest first, then source files only when implementation
+details are needed.
+
+## Entry Points
+
+- `sparkdesign/agent-manifest.json` — package export for agent-facing component semantics.
+- `registry/agent-manifest.json` — source of truth in this repository.
+- `npm run check:agent-manifest` — validates required semantic fields and recipe references.
+
+## Decision Order
+
+1. Choose by `intent`, not by component name similarity.
+2. Check `antiPatterns` before composing a component into a generated screen.
+3. Prefer `recipes` for common agent workflows before inventing a new layout.
+4. Use `cliAdd` when the target app should own copied component source.
+5. Use `packageImport` only when the app already consumes `sparkdesign` as a package.
+
+## Current High-Confidence Coverage
+
+The first manifest version covers the components most likely to be selected by
+design/coding agents:
+
+- `button`
+- `alert`
+- `card`
+- `dialog`
+- `drawer`
+- `file-review-part`
+- `chat-input`
+- `response`
+- `markdown`
+- `permission-card`
+- `tool-invocation-card`
+
+## Recipe Usage
+
+Recipes are intended to prevent agents from flattening rich AI interfaces into
+generic cards and Markdown.
+
+- `assistant-composer` — prompt entry, attachments, send, and permissions.
+- `assistant-response-stream` — generated answer, tools, Markdown, and errors.
+- `focused-task-modal` — compact blocking task or confirmation flow.
+- `settings-drawer` — contextual settings/details while preserving page context.
+- `tool-approval-flow` — explicit approval before risky agent tool actions.
+- `file-review-flow` — agent file changes, review decisions, and approval.
+- `empty-state-with-prompts` — empty states that guide users into AI workflows.
+
+## Maintenance Rule
+
+When adding a component to the manifest:
+
+1. Confirm the component exists in `registry/meta.json`.
+2. Fill `intent`, `slots`, `states`, `a11y`, `composition`, `antiPatterns`, and `agentHints`.
+3. Ensure `packageImport` uses names exported by `src/components/index.ts`.
+4. Ensure `cliAdd` installs the same component id as the manifest key.
+5. Add or update recipes if the component changes how agents should compose screens.
+6. Run `npm run check:agent-manifest`.