@scemoon/cdh 1.0.8 → 1.0.9-beta.2

package/ai-dlc-skill/phases/plan/design_system/component_spec.md

@@ -0,0 +1,398 @@
+# Component Spec — 组件规格模板
+
+所有 UI 组件必须按照本模板编写规格说明，确保一致性、可测试性和可访问性。
+
+## 模板结构
+
+```markdown
+# {组件名}
+
+## 1. Overview
+## 2. Visual Design
+## 3. Props & Types
+## 4. States & Behaviors
+## 5. Composition
+## 6. Accessibility
+## 7. Testing
+## 8. Usage Examples
+```
+
+---
+
+## 1. Overview (概述)
+
+```markdown
+### 组件名称
+{ComponentName}
+
+### 原子层级
+Atom | Molecule | Organism | Template
+
+### 简要描述
+{一句话描述组件做什么}
+
+### 使用场景
+- {场景1}
+- {场景2}
+
+### 代码位置
+`src/components/{category}/{ComponentName}/`
+```
+
+---
+
+## 2. Visual Design (视觉设计)
+
+### 2.1 尺寸变体 (Variants)
+
+| Variant | 高度 | 宽度 | Font Size | 用途 |
+|---------|------|------|-----------|------|
+| xs | 24px | auto | 12px | 次要操作 |
+| sm | 32px | auto | 14px | 紧凑布局 |
+| md | 40px | auto | 14px | 默认 (primary) |
+| lg | 48px | auto | 16px | 主要操作 |
+
+### 2.2 样式变体 (Styles)
+
+| Style | 背景色 | 边框 | 文字色 | 用途 |
+|-------|--------|------|--------|------|
+| primary | `--color-primary` | none | white | 主操作 |
+| secondary | transparent | `--color-border-default` | `--color-text-primary` | 次操作 |
+| ghost | transparent | none | `--color-primary` | 辅助操作 |
+| danger | `--color-danger` | none | white | 危险操作 |
+
+### 2.3 视觉规范
+
+```css
+/* 基础样式 */
+.{component-prefix} {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-2);
+  border-radius: var(--radius-md);
+  font-family: var(--font-family-sans);
+  font-weight: var(--font-weight-medium);
+  transition: all var(--duration-fast) var(--ease-in-out);
+  cursor: pointer;
+  border: 1px solid transparent;
+}
+
+/* Focus Ring */
+.{component-prefix}:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+}
+```
+
+---
+
+## 3. Props & Types (属性与类型)
+
+```typescript
+interface {ComponentName}Props {
+  /** 变体样式 */
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+  /** 尺寸大小 */
+  size?: 'xs' | 'sm' | 'md' | 'lg';
+  /** 禁用状态 */
+  disabled?: boolean;
+  /** 加载状态 */
+  loading?: boolean;
+  /** 左侧图标 */
+  leftIcon?: ReactNode;
+  /** 右侧图标 */
+  rightIcon?: ReactNode;
+  /** 点击回调 */
+  onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+  /** 子元素 */
+  children?: ReactNode;
+  /** 自定义类名 */
+  className?: string;
+  /** 自定义样式 */
+  style?: CSSProperties;
+  /** 完整宽度 */
+  fullWidth?: boolean;
+  /** ARIA label (当 children 不够语义化时) */
+  'aria-label'?: string;
+}
+```
+
+### Props 规范
+
+| 规范 | 要求 |
+|------|------|
+| **必填/可选** | 必须标记哪些是必填 (required)，哪些是可选 |
+| **默认值** | 每个可选 prop 必须有默认值 |
+| **类型安全** | 必须使用 TypeScript 类型，禁止 any |
+| **继承** | 避免继承原生元素属性，使用 composition 替代 |
+| **废弃 (deprecated)** | 标记废弃 prop，保留一个版本后移除 |
+
+---
+
+## 4. States & Behaviors (状态与行为)
+
+### 4.1 状态机
+
+| State | 触发条件 | 视觉表现 | 可访问性 |
+|-------|----------|----------|----------|
+| default | 初始状态 | 正常样式 | 可聚焦 |
+| hover | 鼠标悬停 | 背景/边框变化 | cursor: pointer |
+| active | 鼠标按下 | 颜色加深 | - |
+| focus | Tab 聚焦 / 点击 | focus ring | 可键盘导航 |
+| disabled | disabled=true | 50% opacity, 禁用交互 | aria-disabled |
+| loading | loading=true | 显示 spinner, 禁用交互 | aria-busy |
+
+### 4.2 交互行为
+
+```markdown
+### Click 行为
+- 触发条件: 点击 / Enter / Space (当组件可聚焦时)
+- onClick 回调在 click 事件触发时执行
+- disabled=true 时不触发
+
+### Loading 行为
+- loading=true 时:
+  - 显示 spinner 替换内容
+  - 禁用所有交互
+  - 保持宽度不变 (防止布局抖动)
+- 动画: spinner 旋转 360deg / 1s linear infinite
+
+### Disabled 行为
+- disabled=true 时:
+  - pointer-events: none
+  - opacity: 0.5
+  - aria-disabled: true
+  - Tab 键无法聚焦
+```
+
+### 4.3 键盘导航
+
+| Key | 行为 |
+|-----|------|
+| Tab | 聚焦到组件 |
+| Enter | 触发 onClick |
+| Space | 触发 onClick |
+
+---
+
+## 5. Composition (组合结构)
+
+### 5.1 DOM 结构
+
+```html
+<button class="btn">
+  <span class="btn__icon btn__icon--left">{leftIcon}</span>
+  <span class="btn__text">{children}</span>
+  <span class="btn__icon btn__icon--right">{rightIcon}</span>
+  <span class="btn__spinner" aria-hidden="true"></span>
+</button>
+```
+
+### 5.2 CSS 命名 (BEM)
+
+```css
+.{block} { }
+.{block}__{element} { }
+.{block}--{modifier} { }
+```
+
+| 示例 | 说明 |
+|------|------|
+| `btn__icon--left` | icon 元素的 left 变体 |
+| `btn--primary` | primary 变体 |
+| `btn--disabled` | disabled 状态 |
+
+---
+
+## 6. Accessibility (可访问性)
+
+### 6.1 ARIA 属性
+
+| 属性 | 值 | 条件 |
+|------|-----|------|
+| role | 'button' | 默认 (button 元素不需要) |
+| aria-label | string | 当 children 为空或不够语义化 |
+| aria-disabled | 'true' | disabled=true |
+| aria-busy | 'true' | loading=true |
+| aria-expanded | 'true'/'false' | 如有下拉菜单 |
+| aria-haspopup | 'menu'/'dialog'/... | 如有弹出内容 |
+
+### 6.2 焦点管理
+
+```markdown
+### 焦点规范
+- 必须可通过 Tab 键聚焦
+- Focus ring 必须可见 (2px solid, offset 2px)
+- 焦点环颜色使用 `--color-border-focus`
+- 移动端不需要 focus ring (触摸无键盘)
+
+### 焦点陷阱 (Focus Trap)
+- Modal / Dialog 必须实现焦点陷阱
+- 焦点循环: 最后一个元素 → 第一个元素
+- Escape 键关闭弹窗
+```
+
+### 6.3 屏幕阅读器
+
+```markdown
+### 文本
+- 所有文本必须可被屏幕阅读器读取
+- 图标按钮必须提供 aria-label
+
+### 图片
+- 有意义的图片必须有 alt
+- 装饰性图片 alt=""
+
+### 动态内容
+- aria-live="polite" 用于非紧急更新
+- aria-live="assertive" 仅用于紧急警告
+```
+
+---
+
+## 7. Testing (测试)
+
+### 7.1 单元测试 (Vitest)
+
+```typescript
+describe('{ComponentName}', () => {
+  describe('Rendering', () => {
+    it('renders with default props', () => {});
+    it('renders with custom className', () => {});
+    it('renders children correctly', () => {});
+  });
+
+  describe('Variants', () => {
+    it('renders primary variant', () => {});
+    it('renders secondary variant', () => {});
+    it('renders ghost variant', () => {});
+    it('renders danger variant', () => {});
+  });
+
+  describe('Sizes', () => {
+    it('renders xs size', () => {});
+    it('renders sm size', () => {});
+    it('renders md size', () => {});
+    it('renders lg size', () => {});
+  });
+
+  describe('States', () => {
+    it('renders disabled state', () => {});
+    it('renders loading state with spinner', () => {});
+  });
+
+  describe('Interactions', () => {
+    it('calls onClick when clicked', () => {});
+    it('does not call onClick when disabled', () => {});
+    it('does not call onClick when loading', () => {});
+  });
+
+  describe('Accessibility', () => {
+    it('is focusable', () => {});
+    it('has focus ring on focus', () => {});
+    it('has aria-label when icon only', () => {});
+    it('has aria-disabled when disabled', () => {});
+    it('has aria-busy when loading', () => {});
+  });
+});
+```
+
+### 7.2 Storybook (视觉测试)
+
+```typescript
+// {ComponentName}.stories.tsx
+export default {
+  title: 'Components/Atoms/{ComponentName}',
+  component: {ComponentName},
+  tags: ['autodocs'],
+  argTypes: {
+    variant: { control: 'select', options: ['primary', 'secondary', 'ghost', 'danger'] },
+    size: { control: 'select', options: ['xs', 'sm', 'md', 'lg'] },
+    disabled: { control: 'boolean' },
+    loading: { control: 'boolean' },
+  },
+} as Meta<typeof {ComponentName}>;
+
+export const Default = { args: { children: 'Button' } };
+export const Primary = { args: { variant: 'primary', children: 'Primary' } };
+export const Secondary = { args: { variant: 'secondary', children: 'Secondary' } };
+export const Ghost = { args: { variant: 'ghost', children: 'Ghost' } };
+export const Danger = { args: { variant: 'danger', children: 'Danger' } };
+export const Loading = { args: { loading: true, children: 'Loading...' } };
+export const Disabled = { args: { disabled: true, children: 'Disabled' } };
+export const WithIcon = { args: { leftIcon: <IconPlus />, children: 'Add' } };
+export const FullWidth = { args: { fullWidth: true, children: 'Full Width' } };
+```
+
+### 7.3 测试覆盖率要求
+
+| 层级 | 最低覆盖率 |
+|------|-----------|
+| Atom | 90% |
+| Molecule | 80% |
+| Organism | 70% |
+| Template | 60% |
+| Page | 50% |
+
+---
+
+## 8. Usage Examples (使用示例)
+
+### 8.1 正确用法
+
+```tsx
+// 基础用法
+<Button>Click me</Button>
+
+// 带图标
+<Button leftIcon={<IconPlus />}>Add Item</Button>
+
+// 危险操作
+<Button variant="danger" onClick={handleDelete}>
+  Delete
+</Button>
+
+// 加载状态
+<Button loading={isSubmitting}>Submitting...</Button>
+
+// 禁用状态
+<Button disabled>Not available</Button>
+
+// 充满宽度
+<Button fullWidth>Submit</Button>
+```
+
+### 8.2 错误用法
+
+```tsx
+// ❌ 硬编码颜色
+<Button style={{ backgroundColor: 'blue' }}>Blue</Button>
+
+// ❌ 使用 div 代替 button
+<div onClick={handleClick}>Click</div>
+
+// ❌ 遗漏 loading 状态宽度固定
+<Button loading>{isLoading ? 'Loading...' : 'Submit'}</Button>
+
+// ❌ 遗漏 aria-label
+<Button><IconPlus /></Button> // 无文字时必须有 aria-label
+
+// ❌ 禁用状态仍可点击
+<button disabled={false} onClick={handleClick}>Button</button>
+```
+
+---
+
+## 组件规格检查清单
+
+- [ ] 概述 (Overview) 完整
+- [ ] 视觉设计 (Visual Design) 有变体表格
+- [ ] Props & Types 有 TypeScript 类型定义
+- [ ] States & Behaviors 有完整状态机
+- [ ] Composition 有 DOM 结构和 CSS 命名
+- [ ] Accessibility 有 ARIA 属性说明
+- [ ] Testing 有测试用例和覆盖率要求
+- [ ] Usage Examples 有正确/错误示例
+- [ ] 有对应的 Storybook stories 文件
+- [ ] 有对应的 Vitest 测试文件

package/ai-dlc-skill/phases/plan/design_system/design_tokens.md

@@ -0,0 +1,190 @@
+# Design Tokens — 设计原子
+
+Design Tokens 是设计系统的最小原子单元，通过 CSS 变量形式输出，确保多端一致性。
+
+## 色彩系统 (Color Tokens)
+
+### 语义色 (Semantic Colors)
+
+| Token | Light Mode | Dark Mode | 用途 |
+|-------|------------|-----------|------|
+| `--color-bg-primary` | `#FFFFFF` | `#0F172A` | 主背景 |
+| `--color-bg-secondary` | `#F8FAFC` | `#1E293B` | 次级背景 |
+| `--color-bg-tertiary` | `#F1F5F9` | `#334155` | 卡片/容器背景 |
+| `--color-bg-inverse` | `#0F172A` | `#FFFFFF` | 反色背景 |
+| `--color-text-primary` | `#0F172A` | `#F8FAFC` | 主文字 |
+| `--color-text-secondary` | `#475569` | `#94A3B8` | 次级文字 |
+| `--color-text-tertiary` | `#94A3B8` | `#64748B` | 弱化文字 |
+| `--color-text-inverse` | `#FFFFFF` | `#0F172A` | 反色文字 |
+| `--color-text-disabled` | `#CBD5E1` | `#475569` | 禁用文字 |
+| `--color-border-default` | `#E2E8F0` | `#334155` | 默认边框 |
+| `--color-border-strong` | `#94A3B8` | `#64748B` | 强调边框 |
+| `--color-border-focus` | `#3B82F6` | `#60A5FA` | 聚焦边框 |
+
+### 功能色 (Functional Colors)
+
+| Token | Light Mode | Dark Mode | 用途 |
+|-------|------------|-----------|------|
+| `--color-primary` | `#3B82F6` | `#60A5FA` | 主操作/链接 |
+| `--color-primary-hover` | `#2563EB` | `#3B82F6` | 主色悬停 |
+| `--color-primary-active` | `#1D4ED8` | `#2563EB` | 主色按下 |
+| `--color-primary-subtle` | `#EFF6FF` | `#1E3A5F` | 主色浅底 |
+| `--color-secondary` | `#64748B` | `#94A3B8` | 次级操作 |
+| `--color-secondary-hover` | `#475569` | `#7C8DA5` | 次色悬停 |
+| `--color-success` | `#10B981` | `#34D399` | 成功状态 |
+| `--color-success-subtle` | `#ECFDF5` | `#064E3B` | 成功浅底 |
+| `--color-danger` | `#EF4444` | `#F87171` | 错误/危险 |
+| `--color-danger-hover` | `#DC2626` | `#EF4444` | 危险悬停 |
+| `--color-danger-subtle` | `#FEF2F2` | `#450A0A` | 危险浅底 |
+| `--color-warning` | `#F59E0B` | `#FBBF24` | 警告状态 |
+| `--color-warning-subtle` | `#FFFBEB` | `#451A03` | 警告浅底 |
+| `--color-info` | `#06B6D4` | `#22D3EE` | 信息状态 |
+| `--color-info-subtle` | `#ECFEFF` | `#083344` | 信息浅底 |
+
+### 状态色 (State Colors)
+
+| Token | 用途 |
+|-------|------|
+| `--color-overlay` | 遮罩层 (rgba(0,0,0,0.5)) |
+| `--color-skeleton` | 骨架屏占位 |
+| `--color-skeleton-shine` | 骨架屏动画 |
+
+## 字体系统 (Typography Tokens)
+
+### 字体家族
+
+| Token | 值 | 用途 |
+|-------|---|------|
+| `--font-family-sans` | `Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif` | 主字体 |
+| `--font-family-mono` | `"JetBrains Mono", "Fira Code", Consolas, monospace` | 代码字体 |
+| `--font-family-emoji` | `"Apple Color Emoji", "Segoe UI Emoji", sans-serif` | Emoji |
+
+### 字体大小 (Font Size)
+
+| Token | 值 | 用途 |
+|-------|---|------|
+| `--font-size-xs` | `0.75rem` (12px) | 辅助文字 |
+| `--font-size-sm` | `0.875rem` (14px) | 次要文字 |
+| `--font-size-base` | `1rem` (16px) | 正文 |
+| `--font-size-lg` | `1.125rem` (18px) | 标题 |
+| `--font-size-xl` | `1.25rem` (20px) | 小标题 |
+| `--font-size-2xl` | `1.5rem` (24px) | 页面标题 |
+| `--font-size-3xl` | `1.875rem` (30px) | 大标题 |
+| `--font-size-4xl` | `2.25rem` (36px) | 主标题 |
+
+### 字体粗细 (Font Weight)
+
+| Token | 值 | 用途 |
+|-------|---|------|
+| `--font-weight-normal` | `400` | 正文 |
+| `--font-weight-medium` | `500` | 强调 |
+| `--font-weight-semibold` | `600` | 标题 |
+| `--font-weight-bold` | `700` | 重点 |
+
+### 行高 (Line Height)
+
+| Token | 值 | 用途 |
+|-------|---|------|
+| `--line-height-tight` | `1.25` | 标题 |
+| `--line-height-normal` | `1.5` | 正文 |
+| `--line-height-relaxed` | `1.75` | 长文本 |
+
+## 间距系统 (Spacing Tokens)
+
+基准: 4px
+
+| Token | 值 | REM | 用途 |
+|-------|-----|-----|------|
+| `--space-0` | `0` | 0 | 无间距 |
+| `--space-1` | `4px` | 0.25rem | 紧密间距 |
+| `--space-2` | `8px` | 0.5rem | 小间距 |
+| `--space-3` | `12px` | 0.75rem | 中小间距 |
+| `--space-4` | `16px` | 1rem | 中间距 |
+| `--space-5` | `20px` | 1.25rem | 中大间距 |
+| `--space-6` | `24px` | 1.5rem | 大间距 |
+| `--space-8` | `32px` | 2rem | 较大间距 |
+| `--space-10` | `40px` | 2.5rem | 大间距 |
+| `--space-12` | `48px` | 3rem | 很大间距 |
+| `--space-16` | `64px` | 4rem | 巨大间距 |
+| `--space-20` | `80px` | 5rem | 超大间距 |
+| `--space-24` | `96px` | 6rem | 最大间距 |
+
+## 圆角系统 (Border Radius Tokens)
+
+| Token | 值 | 用途 |
+|-------|-----|------|
+| `--radius-none` | `0` | 无圆角 |
+| `--radius-sm` | `0.125rem` (2px) | 小圆角 |
+| `--radius-md` | `0.375rem` (6px) | 中圆角 |
+| `--radius-lg` | `0.5rem` (8px) | 大圆角 |
+| `--radius-xl` | `0.75rem` (12px) | 特大圆角 |
+| `--radius-2xl` | `1rem` (16px) | 超大圆角 |
+| `--radius-full` | `9999px` | 全圆角 (胶囊) |
+
+## 阴影系统 (Shadow Tokens)
+
+| Token | 值 | 用途 |
+|-------|-----|------|
+| `--shadow-xs` | `0 1px 2px rgba(0,0,0,0.05)` | 极轻阴影 |
+| `--shadow-sm` | `0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06)` | 小阴影 |
+| `--shadow-md` | `0 4px 6px rgba(0,0,0,0.1), 0 2px 4px rgba(0,0,0,0.06)` | 中阴影 |
+| `--shadow-lg` | `0 10px 15px rgba(0,0,0,0.1), 0 4px 6px rgba(0,0,0,0.05)` | 大阴影 |
+| `--shadow-xl` | `0 20px 25px rgba(0,0,0,0.1), 0 10px 10px rgba(0,0,0,0.04)` | 特大阴影 |
+| `--shadow-2xl` | `0 25px 50px rgba(0,0,0,0.25)` | 最大阴影 |
+| `--shadow-inner` | `inset 0 2px 4px rgba(0,0,0,0.06)` | 内阴影 |
+| `--shadow-none` | `none` | 无阴影 |
+
+## 动效系统 (Motion Tokens)
+
+### 时长 (Duration)
+
+| Token | 值 | 用途 |
+|-------|-----|------|
+| `--duration-instant` | `0ms` | 即时 |
+| `--duration-fast` | `100ms` | 快速过渡 |
+| `--duration-normal` | `200ms` | 正常过渡 |
+| `--duration-slow` | `300ms` | 慢速过渡 |
+| `--duration-slower` | `500ms` | 更慢 |
+| `--duration slowest` | `700ms` | 最慢 |
+
+### 缓动曲线 (Easing)
+
+| Token | 值 | 用途 |
+|-------|-----|------|
+| `--ease-linear` | `linear` | 线性 (进度条) |
+| `--ease-in` | `cubic-bezier(0.4, 0, 1, 1)` | 缓入 |
+| `--ease-out` | `cubic-bezier(0, 0, 0.2, 1)` | 缓出 |
+| `--ease-in-out` | `cubic-bezier(0.4, 0, 0.2, 1)` | 缓入缓出 |
+| `--ease-bounce` | `cubic-bezier(0.68, -0.55, 0.265, 1.55)` | 弹性 |
+
+## 图标尺寸 (Icon Size)
+
+| Token | 值 | 用途 |
+|-------|-----|------|
+| `--icon-size-xs` | `12px` | 紧凑图标 |
+| `--icon-size-sm` | `16px` | 小图标 |
+| `--icon-size-md` | `20px` | 中图标 |
+| `--icon-size-lg` | `24px` | 大图标 |
+| `--icon-size-xl` | `32px` | 加大图标 |
+| `--icon-size-2xl` | `48px` | 超大图标 |
+
+## Z-Index 层级
+
+| Token | 值 | 用途 |
+|-------|-----|------|
+| `--z-base` | `0` | 基础层级 |
+| `--z-dropdown` | `100` | 下拉菜单 |
+| `--z-sticky` | `200` | 粘性定位 |
+| `--z-fixed` | `300` | 固定定位 |
+| `--z-modal-backdrop` | `400` | 模态遮罩 |
+| `--z-modal` | `500` | 模态框 |
+| `--z-popover` | `600` | 气泡提示 |
+| `--z-tooltip` | `700` | 工具提示 |
+| `--z-toast` | `800` | 吐司通知 |
+
+## 使用规范
+
+1. **必须使用 CSS 变量**: 所有 token 必须通过 CSS 变量引用，禁止硬编码
+2. **语义化命名**: 优先使用语义色 (`--color-text-primary`)，避免使用视觉色 (`--color-blue-500`)
+3. **主题适配**: 深色模式通过 CSS 变量覆盖实现，无需改变组件代码
+4. **输出格式**: 所有 token 必须以 CSS Custom Properties 格式输出到 `packages/shared/tokens/`