@scemoon/cdh 1.0.9 → 1.0.10-beta.1

package/ai-dlc-skill/phases/deliver/rules.md

@@ -1,61 +0,0 @@
-# Deliver Rules (DLV-*) + Stack Rules (STK-*)
-
-## DLV-001: Unified Stack Preview Before Production
-**Severity:** MUST
-**Description:** Every release MUST deploy as unified stack preview with per-component e2e + cross-stack e2e passing before production.
-**Valid:** `deploy_stack --preview` → `pytest aidlc/tests/cross-stack/ --stack-url $STACK_URL`.
-**Invalid:** Deploying only one component to preview.
-
-## DLV-002: Production Approval Gate
-**Severity:** MUST
-**Description:** Production deployment requires explicit human approval reviewing per-component e2e, cross-stack e2e, staging smoke, and contract-diff.md.
-**Valid:** Human reviews all reports and explicitly approves.
-**Invalid:** Automated production deployment triggered solely by test pass.
-
-## DLV-003: Stack BVT Validation
-**Severity:** MUST
-**Description:** After production deploy, BVT MUST run against the stack. Failure triggers automatic stack rollback.
-**Valid:** `bvt ${PRODUCTION_URL}` → fail → `deploy_stack --rollback`.
-**Invalid:** BVT skip or success with errors.
-
-## DLV-004: Per-Component Preview URL Isolation
-**Severity:** MUST
-**Description:** e2e tests run against dynamic preview URLs, never hardcoded production URLs.
-**Valid:** `pytest apps/web/tests/e2e/ --preview-url $WEB_URL`.
-**Invalid:** Hardcoded `https://prod.example.com` in tests.
-
-## STK-001: Component Scope Declaration
-**Severity:** MUST
-**Description:** Every spec delta, design doc, task list MUST declare `affects:`.
-**Valid:** `affects: [web, backend, contracts]`.
-**Invalid:** Missing `affects` declaration.
-
-## STK-002: Cross-Component Tasks Have Edges
-**Severity:** MUST
-**Description:** Tasks consuming a contract MUST have explicit `depends_on` edge to producing task.
-**Valid:** `depends_on: [int-contract-auth-login, be-login-endpoint]`.
-**Invalid:** Implicit dependency with no DAG edge.
-
-## STK-003: Cross-Stack E2E Mandatory for ≥2 Components
-**Severity:** MUST
-**Description:** Changes affecting ≥2 components MUST have cross-stack e2e testing real flow between components.
-**Valid:** Real web client against real backend preview.
-**Invalid:** Cross-stack test that mocks the other component.
-
-## STK-004: Unified Stack Deploy
-**Severity:** MUST
-**Description:** Shared environments MUST use `deploy_stack` orchestrator, not per-component ad-hoc deploys.
-**Valid:** `deploy_stack --preview` deploys all components.
-**Invalid:** Ad-hoc per-component deploy to shared preview.
-
-## STK-005: Cross-Component Build Config Injection
-**Severity:** MUST
-**Description:** All client builds receive `BACKEND_URL` as build-time env var, never hardcoded.
-**Valid:** `pnpm --filter web build --env BACKEND_URL=$BACKEND_URL`.
-**Invalid:** Hardcoded URLs in `.env.production`.
-
-## STK-006: Stack-Level Rollback
-**Severity:** MUST
-**Description:** Rollback is stack operation. Entire previous stable version reverts together.
-**Valid:** `deploy_stack --rollback v1.2.3` reverts all components.
-**Invalid:** Rolling back only backend while leaving clients on new version.

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

@@ -1,268 +0,0 @@
-# Accessibility — 可访问性规范
-
-所有 UI 组件必须符合 WCAG 2.1 AA 标准，确保残障人士可正常使用。
-
-## WCAG 2.1 核心标准
-
-| 原则 | 级别 | 要求 |
-|------|------|------|
-| **可感知** | A | 文本替代、媒体字幕、适应性内容 |
-| **可操作** | A | 键盘可访问、无陷阱、足够时间 |
-| **可理解** | A | 语言可读、可预测、输入帮助 |
-| **健壮** | A | 兼容性、状态可访问性 |
-
-### 对比度要求
-
-| 内容类型 | AA 标准 | AAA 标准 |
-|----------|---------|----------|
-| 正常文本 (<18px / <14px bold) | 4.5:1 | 7:1 |
-| 大文本 (≥18px / ≥14px bold) | 3:1 | 4.5:1 |
-| UI 组件/图形 | 3:1 | 3:1 |
-
-### 字体大小规范
-
-```css
-/* 最小可访问字体 */
---font-size-min-accessible: 14px;  /* 正常文本 */
---font-size-min-accessible-large: 18px;  /* 大文本 */
-```
-
-## 焦点管理 (Focus Management)
-
-### Focus Ring 规范
-
-```css
-/* 所有可交互元素的 focus ring */
-:focus-visible {
-  outline: 2px solid var(--color-border-focus);
-  outline-offset: 2px;
-}
-
-/* 移除默认 focus ring */
-:focus:not(:focus-visible) {
-  outline: none;
-}
-```
-
-### 焦点顺序
-
-```markdown
-### Tab 顺序规则
-1. 逻辑顺序: 从左到右，从上到下
-2. 焦点顺序必须与视觉顺序一致
-3. 模态弹窗必须捕获焦点 (focus trap)
-4. 关闭弹窗后焦点需返回触发元素
-5. 跳过链接 (#main-content) 必须是第一个可聚焦元素
-```
-
-### 焦点陷阱 (Focus Trap)
-
-```typescript
-// Modal / Dialog 必须实现焦点陷阱
-const focusTrap = (container: HTMLElement) => {
-  const focusable = container.querySelectorAll(
-    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
-  );
-  const first = focusable[0] as HTMLElement;
-  const last = focusable[focusable.length - 1] as HTMLElement;
-
-  const handleKeyDown = (e: KeyboardEvent) => {
-    if (e.key !== 'Tab') return;
-    if (e.shiftKey && document.activeElement === first) {
-      e.preventDefault();
-      last.focus();
-    } else if (!e.shiftKey && document.activeElement === last) {
-      e.preventDefault();
-      first.focus();
-    }
-  };
-
-  container.addEventListener('keydown', handleKeyDown);
-  first?.focus();
-};
-```
-
-## 键盘导航 (Keyboard Navigation)
-
-### 标准键盘交互
-
-| Key | 组件 | 行为 |
-|-----|------|------|
-| Tab | 全局 | 移动到下一个可聚焦元素 |
-| Shift+Tab | 全局 | 移动到上一个可聚焦元素 |
-| Enter | Button / Link | 激活 |
-| Space | Button / Checkbox | 激活 / 切换 |
-| Escape | Modal / Dropdown | 关闭 |
-| Arrow Up/Down | Menu / Select | 上下导航 |
-| Arrow Left/Right | Tab / Slider | 左右切换 |
-
-### 可交互元素最小集合
-
-```markdown
-必须可键盘操作:
-- [ ] 所有 Button
-- [ ] 所有 Link
-- [ ] 所有 Input / Textarea
-- [ ] 所有 Select
-- [ ] 所有 Checkbox / Radio / Switch
-- [ ] 所有 MenuItem
-- [ ] 所有 Modal / Dialog
-- [ ] 所有 Tooltip (可通过键盘触发)
-```
-
-## ARIA 规范
-
-### ARIA 属性速查
-
-| 属性 | 用途 | 示例 |
-|------|------|------|
-| aria-label | 为元素提供可访问名称 | `<button aria-label="关闭">X</button>` |
-| aria-describedby | 关联描述元素 | `<input aria-describedby="hint-email">` |
-| aria-required | 标记必填 | `<input aria-required="true">` |
-| aria-invalid | 标记错误 | `<input aria-invalid="true">` |
-| aria-disabled | 标记禁用 | `<button aria-disabled="true">` |
-| aria-expanded | 展开/收起状态 | `<button aria-expanded="false">` |
-| aria-hidden | 隐藏于屏幕阅读器 | `<span aria-hidden="true">icon</span>` |
-| aria-live | 动态区域 | `<div aria-live="polite">result</div>` |
-| aria-busy | 加载状态 | `<div aria-busy="true">` |
-| aria-current | 当前项 | `<a aria-current="page">Home</a>` |
-| role | 语义角色 | `<div role="dialog">` |
-
-### 常见 ARIA 模式
-
-```markdown
-### Button vs Link
-- Button: 执行操作 (onClick) → <button> 或 <div role="button">
-- Link: 导航 → <a href>
-
-### Form Field
-<input
-  id="email"
-  type="email"
-  aria-required="true"
-  aria-invalid="false"
-  aria-describedby="email-hint email-error"
-/>
-<span id="email-hint">用于接收验证码</span>
-<span id="email-error" aria-live="polite"></span>
-
-### Modal/Dialog
-<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
-  <h2 id="dialog-title">确认删除</h2>
-  <p>确定要删除此项吗？</p>
-  <button>取消</button>
-  <button>确定</button>
-</div>
-
-### Tabs
-<div role="tablist">
-  <button role="tab" aria-selected="true" aria-controls="panel-1">Tab 1</button>
-  <button role="tab" aria-selected="false" aria-controls="panel-2">Tab 2</button>
-</div>
-<div role="tabpanel" id="panel-1">Content 1</div>
-<div role="tabpanel" id="panel-2" hidden>Content 2</div>
-```
-
-## 屏幕阅读器支持
-
-### 必需内容
-
-```markdown
-### 图片
-- 有意义图片: alt="描述内容"
-- 装饰图片: alt="" (空)
-
-### 图标
-- 纯装饰图标: aria-hidden="true"
-- 有意义图标: aria-label 或可见文字
-
-### 动态内容
-- 非紧急更新: aria-live="polite"
-- 紧急警告: aria-live="assertive"
-- Toast: role="status" 或 role="alert"
-
-### 表单错误
-- 错误提示必须关联到对应输入框 (aria-describedby)
-- 错误必须可被屏幕阅读器即时读取
-```
-
-### 辅助技术测试清单
-
-```markdown
-- [ ] NVDA + Chrome 测试
-- [ ] VoiceOver + Safari 测试
-- [ ] JAWS + Chrome 测试 (可选)
-```
-
-## 运动与动画
-
-### 减少运动 (Reduce Motion)
-
-```css
-/* 尊重用户减少动画偏好 */
-@media (prefers-reduced-motion: reduce) {
-  *,
-  *::before,
-  *::after {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
-  }
-}
-```
-
-### 动画规范
-
-| 类型 | 最大时长 | 缓动 |
-|------|----------|------|
-| 微交互 | 100-200ms | ease-out |
-| 状态切换 | 200-300ms | ease-in-out |
-| 展开/折叠 | 300-500ms | ease-in-out |
-| 页面过渡 | 300-500ms | ease-in-out |
-
-## 色彩相关
-
-### 不应仅依赖颜色传达信息
-
-```markdown
-❌ 错误: 红色边框表示错误
-✅ 正确: 红色边框 + 错误图标 + 错误文字 + aria-invalid
-
-❌ 错误: 灰色表示禁用
-✅ 正确: 灰色 + aria-disabled="true" + 鼠标事件禁用
-```
-
-## 移动端触摸
-
-```markdown
-### 触摸目标尺寸
-- 最小: 44x44 CSS pixels (Apple) / 48x48 dp (Material Design)
-- 推荐: 48x48 CSS pixels
-
-### 触摸间距
-- 相邻可触摸元素间距 ≥ 8px
-- 防止误触相邻元素
-```
-
-## 法规与标准
-
-| 标准 | 要求级别 |
-|------|----------|
-| WCAG 2.1 (A) | 强制 (MUST) |
-| WCAG 2.1 (AA) | 推荐 (SHOULD) |
-| WCAG 2.1 (AAA) | 可选 (MAY) |
-| EN 301 549 (欧盟) | 政府采购 |
-| Section 508 (美国) | 政府/公共机构 |
-
-## 评审清单
-
-- [ ] 所有文本对比度 ≥ 4.5:1 (AA)
-- [ ] 所有 UI 组件对比度 ≥ 3:1 (AA)
-- [ ] 所有交互元素可通过键盘操作
-- [ ] 所有图标按钮有 aria-label
-- [ ] 所有表单有错误提示和关联
-- [ ] 模态框实现焦点陷阱
-- [ ] 支持 prefers-reduced-motion
-- [ ] 触摸目标 ≥ 44x44px
-- [ ] 通过 axe-core 自动检测
-- [ ] 通过屏幕阅读器手动测试

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

@@ -1,341 +0,0 @@
-# Atomic Design — 原子化设计分层
-
-Atomic Design 是 UI 组件的分层方法论，将界面拆解为 5 个层级：Atom → Molecule → Organism → Template → Page。
-
-## 层级总览
-
-```
-Page
-  └── Template
-        └── Organism
-              └── Molecule
-                    └── Atom
-```
-
-| 层级 | 定义 | 复杂度 | 可复用性 |
-|------|------|--------|----------|
-| **Atom** | 最小单元，不可拆分 | 低 | 全局复用 |
-| **Molecule** | 2-3 个 Atom 简单组合 | 低 | 全局复用 |
-| **Organism** | 多个组件复杂组合 | 中 | 跨功能复用 |
-| **Template** | 页面骨架布局 | 中 | 同类型页面复用 |
-| **Page** | 具体页面实例 | 高 | 特定页面 |
-
----
-
-## Atom — 原子
-
-**定义**: 最小 UI 单元，不可再拆分，拥有自己的 markup 和样式。
-
-### 类型
-
-| 类型 | 示例组件 |
-|------|----------|
-| **基础** | Button, Input, Textarea, Select, Checkbox, Radio, Switch |
-| **显示** | Badge, Tag, Avatar, Progress, Tooltip |
-| **导航** | Tab, Breadcrumb, Pagination |
-| **媒体** | Icon, Image, Video |
-| **反馈** | Spinner, Skeleton, Alert |
-
-### Atom 规范
-
-```markdown
-## Button
-
-### Variants
-- primary: 主操作按钮
-- secondary: 次级操作
-- ghost: 透明背景
-- danger: 危险操作
-
-### Sizes
-- sm: 高度 32px, font-size xs
-- md: 高度 40px, font-size sm (default)
-- lg: 高度 48px, font-size base
-
-### States
-- default: 默认
-- hover: 悬停
-- active: 按下
-- focus: 聚焦 (focus ring)
-- disabled: 禁用
-- loading: 加载中
-
-### Props (示例)
-- variant: 'primary' | 'secondary' | 'ghost' | 'danger'
-- size: 'sm' | 'md' | 'lg'
-- disabled: boolean
-- loading: boolean
-- leftIcon: ReactNode
-- rightIcon: ReactNode
-- fullWidth: boolean
-```
-
-### 设计要求
-
-- 必须可通过 CSS 变量覆盖外观
-- 必须支持键盘聚焦状态 (focus ring)
-- 尺寸需符合 spacing token
-- 文字颜色需满足 WCAG 对比度要求
-
----
-
-## Molecule — 分子
-
-**定义**: 2-3 个 Atom 组合，形成具有单一功能职责的组件。
-
-### 类型
-
-| 类型 | 示例组件 |
-|------|----------|
-| **表单** | SearchBar (Input + Button), FormField (Label + Input + ErrorText), DatePicker |
-| **卡片** | CardHeader (Avatar + Title + Subtitle), CardFooter (Meta + Action) |
-| **数据** | DataRow (Label + Value), StatCard (Icon + Value + Label) |
-| **导航** | NavItem (Icon + Text + Badge), BreadcrumbItem |
-| **媒体** | ImageWithCaption (Image + Caption), VideoPlayer |
-
-### Molecule 规范
-
-```markdown
-## SearchBar
-
-### Composition
-- Input (Atom)
-- Button (Atom)
-- 可选: Dropdown for filter
-
-### States
-- default: 默认
-- focus: Input 聚焦
-- loading: 搜索中 (Button loading)
-- results: 显示结果
-- empty: 无结果
-
-### Props
-- placeholder: string
-- onSearch: (value: string) => void
-- isLoading: boolean
-- value: string
-
-### 行为
-- Enter 触发搜索
-- 搜索时显示 loading 状态
-- 清空按钮在有内容时显示
-```
-
-### 设计要求
-
-- Molecule 应有明确的单一职责
-- 内部 Atom 状态需联动（如 Input 禁用时 Button 也禁用）
-- 可接收外部样式覆盖 (className / style props)
-
----
-
-## Organism — 有机体
-
-**定义**: 多个 Molecule/Atom 组合，形成独立的功能区块，可跨功能复用。
-
-### 类型
-
-| 类型 | 示例组件 |
-|------|----------|
-| **布局** | Header, Sidebar, Footer |
-| **数据** | DataTable, ListView, CardGrid |
-| **表单** | LoginForm, RegisterForm, FilterPanel |
-| **导航** | MainNav, TabPanel |
-| **反馈** | ToastContainer, Modal, ConfirmDialog |
-
-### Organism 规范
-
-```markdown
-## DataTable
-
-### Composition
-- TableHeader (Organism): 排序按钮 + 列选择
-- TableRow (Molecule): 多列数据
-- TableFooter (Organism): 分页信息
-- 内部状态: columns, sortConfig, selectedRows
-
-### States
-- loading: 骨架屏
-- empty: 空状态插画
-- error: 错误提示
-- populated: 正常数据
-
-### Props
-- columns: Column[]
-- data: T[]
-- sortable: boolean
-- selectable: boolean
-- pagination: PaginationConfig
-- onSort: (key: string, dir: 'asc' | 'desc') => void
-- onSelect: (rows: T[]) => void
-
-### 可复用部分
-- TableHeader 可单独作为 Organism
-- TableRow 可单独作为 Molecule
-```
-
-### 设计要求
-
-- Organism 应是独立功能块，不依赖父级数据
-- 内部状态需合理管理 (local state vs external state)
-- 必须处理空状态、加载状态、错误状态
-
----
-
-## Template — 模板
-
-**定义**: 页面骨架布局，定义内容区域的结构和位置关系，不含具体业务数据。
-
-### 类型
-
-| 类型 | 用途 |
-|------|------|
-| **ListTemplate** | 列表页模板 (Header + Filter + Table + Pagination) |
-| **DetailTemplate** | 详情页模板 (Header + Content + Sidebar) |
-| **FormTemplate** | 表单页模板 (Header + Form + Actions) |
-| **DashboardTemplate** | 仪表盘模板 (Header + StatsGrid + Charts) |
-| **AuthTemplate** | 认证页模板 (CenterCard + Logo + Form) |
-
-### Template 规范
-
-```markdown
-## ListTemplate
-
-### Layout Structure
-┌─────────────────────────────────────┐
-│ Header: Title + Actions              │
-├─────────────────────────────────────┤
-│ FilterBar: Search + Filters + Sort  │
-├─────────────────────────────────────┤
-│ DataTable / ListView                │
-│ (内容区域，可滚动)                    │
-├─────────────────────────────────────┤
-│ Pagination                          │
-└─────────────────────────────────────┘
-
-### 占位区域
-- Header: 高度 64px, 固定
-- FilterBar: 高度 56px
-- Pagination: 高度 48px
-- 内容区: flex-1, 可滚动
-
-### Responsive
-- Desktop: 完整布局
-- Tablet: FilterBar 可折叠
-- Mobile: 单列列表
-```
-
-### 设计要求
-
-- Template 只定义布局结构，不含业务逻辑
-- 必须支持响应式断点
-- 主要内容区域需可滚动
-
----
-
-## Page — 页面
-
-**定义**: Template 的具体实例，填充真实数据和业务逻辑。
-
-### 类型
-
-| 类型 | 示例 |
-|------|------|
-| **业务页面** | UserListPage, ProductDetailPage, OrderPage |
-| **认证页面** | LoginPage, RegisterPage, ForgotPasswordPage |
-| **设置页面** | AccountSettingsPage, NotificationSettingsPage |
-| **错误页面** | NotFoundPage, ErrorPage |
-
-### Page 规范
-
-```markdown
-## UserListPage
-
-### Uses Template
-- ListTemplate
-
-### Data Binding
-- Header: 动态标题 "用户管理"
-- FilterBar: 用户状态筛选 (全部/活跃/禁用)
-- DataTable: 用户列表数据
-- Pagination: 总页数 100
-
-### State Management
-- URL state: ?page=1&status=active&search=xxx
-- Local state: 选中行、弹窗可见性
-- Server state: 用户列表 (React Query / SWR)
-
-### Side Effects
-- 页面加载时获取数据
-- 筛选变化时重置页码并刷新
-- 删除用户后刷新列表
-
-### Routes
-- /users (列表)
-- /users/:id (详情)
-- /users/new (新建)
-```
-
-### 设计要求
-
-- Page 是路由级别的组件
-- Page 负责数据获取和业务逻辑，布局委托给 Template
-- Page 需处理 SEO (metadata)、权限控制
-
----
-
-## 目录结构约定
-
-```
-src/
-├── components/
-│   ├── atoms/           # Atom 组件
-│   │   ├── Button/
-│   │   ├── Input/
-│   │   └── ...
-│   ├── molecules/       # Molecule 组件
-│   │   ├── SearchBar/
-│   │   ├── FormField/
-│   │   └── ...
-│   ├── organisms/       # Organism 组件
-│   │   ├── Header/
-│   │   ├── DataTable/
-│   │   └── ...
-│   └── templates/       # Template 组件
-│       ├── ListTemplate/
-│       ├── DetailTemplate/
-│       └── ...
-├── pages/               # Page 组件 (按路由组织)
-│   ├── UserListPage/
-│   └── ProductDetailPage/
-```
-
----
-
-## 设计决策规则
-
-| 场景 | 决策 |
-|------|------|
-| 新组件是 Atom 还是 Molecule？ | 看是否需要多个 Atom 组合才能完成功能 |
-| 新组件是 Molecule 还是 Organism？ | 看是否有多个功能区块 / 是否独立存在 |
-| 是 Organism 还是 Template？ | Organism 是功能块，Template 是布局结构 |
-| 是 Template 还是 Page？ | Template 无业务数据，Page 是具体实例 |
-| 何时新建组件？ | 发现重复 UI 模式时抽取，而非预判 |
-| 组件复用边界？ | 同一功能类型内复用，跨类型不强行复用 |
-
----
-
-## 评审清单
-
-新组件创建时检查：
-
-- [ ] 属于正确的原子层级
-- [ ] 有对应的 `ComponentName.stories.tsx` (Storybook)
-- [ ] 有对应的 `ComponentName.test.tsx` (Vitest)
-- [ ] 支持 Design Tokens (CSS 变量)
-- [ ] 支持深色模式
-- [ ] 有完整的 Props TypeScript 类型
-- [ ] 有必要的 ARIA 属性
-- [ ] 处理了 disabled / loading / error / empty 状态
-- [ ] 单元测试覆盖率 ≥ 80%