@scemoon/cdh 1.0.7 → 1.0.9-beta.1

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

@@ -0,0 +1,299 @@
+# Iconography — 图标规范
+
+图标是 UI 的重要视觉元素，必须统一管理和使用。
+
+## 图标库选择
+
+| 平台 | 推荐图标库 | 备选 |
+|------|------------|------|
+| **Web** | Heroicons | Lucide, Font Awesome, Feather |
+| **Native** | SF Symbols (iOS) / Material Icons (Android) | React Native Vector Icons |
+| **Desktop** | Lucide (Electron) / Native (Tauri) | - |
+| **WXA** | Vant Weapp Icon | iconfont |
+| **MYA** | Ant Design Mini Icon | - |
+| **TTA** | 字节官方 icon | - |
+
+## 图标尺寸规范
+
+| Token | 值 | 用途 |
+|-------|-----|------|
+| `--icon-size-xs` | `12px` | 紧凑文字旁 (如 Badge 内) |
+| `--icon-size-sm` | `16px` | 小尺寸 (如 List Item) |
+| `--icon-size-md` | `20px` | 默认尺寸 (如 Button 内) |
+| `--icon-size-lg` | `24px` | 大尺寸 (如 Empty State) |
+| `--icon-size-xl` | `32px` | 加大 (如 Feature Card) |
+| `--icon-size-2xl` | `48px` | 超大 (如导航图标) |
+
+## 图标与文字比例
+
+| 场景 | 图标尺寸 | 文字尺寸 | 间距 |
+|------|----------|----------|------|
+| Button 内 | 16-20px | 14-16px | 8px |
+| Input 内 | 16px | 14px | 8px |
+| List Item | 16-20px | 14px | 8-12px |
+| Card 标题 | 20-24px | 16-18px | 8px |
+| 导航菜单 | 24px | 14px | 12px |
+| Empty State | 48-64px | 14px | 16px |
+
+## 图标 Stroke 规范
+
+| 场景 | Stroke Width | 用途 |
+|------|--------------|------|
+| 细线图标 | 1.5px | 紧凑布局 |
+| 标准图标 | 2px | 默认 |
+| 粗线图标 | 2.5px | 强调 |
+
+```css
+/* Heroicons outline 样式 */
+.icon {
+  width: var(--icon-size-md);
+  height: var(--icon-size-md);
+  stroke-width: 2;
+  stroke: currentColor;
+  fill: none;
+}
+```
+
+## SVG 图标使用规范
+
+### 正确使用方式
+
+```tsx
+// ✅ 使用 SVG 组件
+import { BeakerIcon } from '@heroicons/react/24/outline';
+
+<BeakerIcon className="h-5 w-5" />
+
+// ✅ 定制颜色
+<BeakerIcon className="h-5 w-5 text-blue-500" />
+
+// ✅ 定制尺寸
+<BeakerIcon className="h-8 w-8" />
+
+// ✅ 使用当前文字颜色
+<BeakerIcon className="h-5 w-5" style={{ color: 'var(--color-text-secondary)' }} />
+```
+
+### 错误使用方式
+
+```tsx
+// ❌ 硬编码颜色
+<BeakerIcon className="h-5 w-5 text-gray-500" />
+
+// ❌ 使用 img 标签
+<img src="/icons/beaker.svg" alt="Beaker" />
+
+// ❌ 使用 font-icon (如 Font Awesome)
+<i className="fas fa-beaker"></i>
+
+// ❌ 缺少 aria-label
+<BeakerIcon />  // 可访问性缺失
+```
+
+## 图标分类
+
+### 操作类图标
+
+| 图标名 | 用途 | 示例 |
+|--------|------|------|
+| plus | 添加 | 新建、添加 |
+| minus | 移除 | 删除、减少 |
+| x-mark | 关闭 | 关闭弹窗 |
+| check | 确认 | 勾选、完成 |
+| pencil | 编辑 | 编辑内容 |
+| trash | 删除 | 删除操作 |
+| arrow-right | 导航 | 下一页、下一步 |
+| arrow-left | 返回 | 返回、上一页 |
+| magnifying-glass | 搜索 | 搜索按钮 |
+
+### 状态类图标
+
+| 图标名 | 用途 |
+|--------|------|
+| check-circle | 成功状态 |
+| exclamation-circle | 警告状态 |
+| x-circle | 错误状态 |
+| information-circle | 信息状态 |
+| clock | 加载中 |
+| spinner (动画) | 加载中 |
+
+### 导航类图标
+
+| 图标名 | 用途 |
+|--------|------|
+| home | 首页 |
+| user | 个人中心 |
+| cog (settings) | 设置 |
+| bell | 通知 |
+| envelope | 消息 |
+| shopping-cart | 购物车 |
+
+### 业务类图标
+
+| 图标名 | 用途 |
+|--------|------|
+| currency-dollar | 支付相关 |
+| chart-bar | 统计 |
+| photo | 图片相关 |
+| document | 文档 |
+| folder | 文件夹 |
+| cloud-arrow-up | 上传 |
+
+## 可访问性
+
+### 装饰性图标
+
+```tsx
+// ✅ 装饰性图标 - 屏幕阅读器忽略
+<button>
+  <BeakerIcon className="h-5 w-5" aria-hidden="true" />
+  <span>Add Item</span>
+</button>
+```
+
+### 含义性图标
+
+```tsx
+// ✅ 有含义的图标 - 必须有 aria-label
+<button aria-label="Search">
+  <MagnifyingGlassIcon className="h-5 w-5" />
+</button>
+
+// ✅ 配合文字说明
+<button aria-describedby="search-hint">
+  <MagnifyingGlassIcon className="h-5 w-5" aria-hidden="true" />
+</button>
+<span id="search-hint" className="sr-only">搜索商品</span>
+```
+
+### 屏幕阅读器专用文本
+
+```css
+/* .sr-only: 仅屏幕阅读器可见 */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+## 图标动画
+
+### Loading Spinner
+
+```css
+@keyframes spin {
+  from { transform: rotate(0deg); }
+  to { transform: rotate(360deg); }
+}
+
+.animate-spin {
+  animation: spin 1s linear infinite;
+}
+```
+
+### 图标过渡
+
+```css
+/* 悬停时图标位移 */
+.button:hover .icon {
+  transform: translateX(2px);
+  transition: transform var(--duration-fast) var(--ease-out);
+}
+
+/* 悬停时图标颜色变化 */
+.button:hover .icon {
+  color: var(--color-primary-hover);
+}
+```
+
+## 平台特殊处理
+
+### Web (React)
+
+```tsx
+// 使用 Heroicons
+import { IconName } from '@heroicons/react/24/outline';
+
+<IconName className="h-5 w-5" aria-hidden="true" />
+```
+
+### Native (React Native)
+
+```tsx
+// iOS - SF Symbols
+import { SFSymbol } from 'react-native-sfsymbols';
+
+// Android - Material Icons
+import Icon from 'react-native-vector-icons/MaterialIcons';
+
+// 通用
+import { Ionicons } from '@expo/vector-icons';  // 跨平台
+```
+
+### 小程序
+
+```xml
+<!-- WXA / MYA / TTA - 使用 Vant Weapp Icon -->
+<van-icon name="success" />
+
+<!-- 或使用 iconfont -->
+<view class="iconfont icon-success"></view>
+```
+
+## 图标文件命名
+
+```
+icons/
+├── outline/           # 线框风格
+│   ├── arrow-right.svg
+│   ├── check.svg
+│   └── ...
+├── solid/             # 实心风格
+│   ├── arrow-right.svg
+│   ├── check.svg
+│   └── ...
+└── custom/            # 自定义业务图标
+    ├── logo.svg
+    ├── brand-icon.svg
+    └── ...
+```
+
+## 图标管理规则
+
+| 规则 | 说明 |
+|------|------|
+| 单一来源 | 只从指定图标库引入，不混用 |
+| 全局注册 | 图标组件全局注册，按需引入 |
+| 禁止新增 | 不随意新增图标，优先复用现有 |
+| 统一尺寸 | 使用规范的 6 个尺寸 |
+| 统一 stroke | stroke-width 统一为 2px (outline) |
+| 支持颜色 | 图标颜色必须可通过 CSS 变量控制 |
+| 支持旋转 | loading 类图标支持动画 |
+
+## 常用图标清单 (Web)
+
+```
+基础操作: plus, minus, x-mark, check, pencil, trash, share, download, upload
+导航箭头: arrow-right, arrow-left, arrow-up, arrow-down, chevron-right
+状态: check-circle, x-circle, exclamation-circle, information-circle
+通用: home, user, cog, bell, envelope, search, heart, star
+业务: currency-dollar, chart-bar, photo, document, folder, cloud
+```
+
+## 评审清单
+
+- [ ] 只使用指定的图标库
+- [ ] 所有图标尺寸符合 6 档规范
+- [ ] stroke-width 统一为 2px (outline)
+- [ ] 装饰性图标有 aria-hidden="true"
+- [ ] 含义性图标有 aria-label
+- [ ] 图标颜色通过 currentColor 或 CSS 变量设置
+- [ ] loading 图标有 spin 动画
+- [ ] 图标文件按 outline/solid/custom 分类

package/ai-dlc-skill/phases/plan/design_system/platform_ui/desktop.md

@@ -0,0 +1,318 @@
+# Desktop UI 规范 — Electron & Tauri
+
+桌面端 UI 规范，支持 macOS / Windows / Linux。
+
+## 技术栈
+
+| 框架 | 渲染引擎 | UI 方案 |
+|------|----------|---------|
+| **Electron** | Chromium | React + Tailwind / Ant Design |
+| **Tauri** | WebView (系统) | React + Tailwind |
+
+## 窗口规范
+
+### 最小窗口尺寸
+
+```typescript
+// main window config
+const mainWindowConfig = {
+  minWidth: 1024,
+  minHeight: 600,
+  defaultWidth: 1280,
+  defaultHeight: 800,
+};
+```
+
+| 场景 | 最小尺寸 | 推荐尺寸 |
+|------|----------|----------|
+| 通用应用 | 1024x600 | 1280x800 |
+| 复杂工具 | 1280x720 | 1440x900 |
+| 全屏应用 | 1920x1080 | - |
+
+### 窗口边框
+
+| 平台 | 窗口框架 |
+|------|----------|
+| macOS | 使用原生标题栏 (traffic lights) |
+| Windows | 使用原生标题栏或自定义 |
+| Linux | 使用原生标题栏 |
+
+### 窗口状态
+
+```typescript
+interface WindowState {
+  isMaximized: boolean;
+  isMinimized: boolean;
+  isFullScreen: boolean;
+  bounds: { x: number; y: number; width: number; height: number };
+}
+```
+
+## 原生菜单 (Native Menu)
+
+### macOS 菜单结构
+
+```typescript
+// Electron
+const template: MenuItemConstructorOptions[] = [
+  {
+    label: 'App Name',
+    submenu: [
+      { label: 'About', role: 'about' },
+      { type: 'separator' },
+      { label: 'Preferences', accelerator: 'Cmd+,', click: () => {} },
+      { type: 'separator' },
+      { label: 'Quit', accelerator: 'Cmd+Q', role: 'quit' },
+    ],
+  },
+  {
+    label: 'File',
+    submenu: [
+      { label: 'New', accelerator: 'Cmd+N', click: () => {} },
+      { label: 'Open', accelerator: 'Cmd+O', click: () => {} },
+      { type: 'separator' },
+      { label: 'Save', accelerator: 'Cmd+S', click: () => {} },
+    ],
+  },
+  {
+    label: 'Edit',
+    submenu: [
+      { label: 'Undo', accelerator: 'Cmd+Z', role: 'undo' },
+      { label: 'Redo', accelerator: 'Cmd+Shift+Z', role: 'redo' },
+      { type: 'separator' },
+      { label: 'Cut', accelerator: 'Cmd+X', role: 'cut' },
+      { label: 'Copy', accelerator: 'Cmd+C', role: 'copy' },
+      { label: 'Paste', accelerator: 'Cmd+V', role: 'paste' },
+    ],
+  },
+  {
+    label: 'View',
+    submenu: [
+      { label: 'Reload', accelerator: 'Cmd+R', role: 'reload' },
+      { label: 'Toggle DevTools', accelerator: 'Cmd+Alt+I', role: 'toggleDevTools' },
+      { type: 'separator' },
+      { label: 'Actual Size', accelerator: 'Cmd+0', role: 'resetZoom' },
+      { label: 'Zoom In', accelerator: 'Cmd+=', role: 'zoomIn' },
+      { label: 'Zoom Out', accelerator: 'Cmd+-', role: 'zoomOut' },
+      { type: 'separator' },
+      { label: 'Toggle Fullscreen', accelerator: 'Cmd+Ctrl+F', role: 'togglefullscreen' },
+    ],
+  },
+  {
+    label: 'Window',
+    submenu: [
+      { label: 'Minimize', accelerator: 'Cmd+M', role: 'minimize' },
+      { label: 'Maximize', click: () => {} },
+      { type: 'separator' },
+      { label: 'Close', accelerator: 'Cmd+W', role: 'close' },
+    ],
+  },
+];
+```
+
+### Tauri 菜单
+
+```rust
+// src-tauri/src/main.rs
+use tauri::MenuBuilder;
+
+let menu = MenuBuilder::new(app)
+  .item(&MenuItem::new("About", true, None::<&str>))
+  .separator()
+  .item(&MenuItem::new("Preferences", true, Some("CmdOrCtrl+,")))
+  .separator()
+  .item(&MenuItem::new("Quit", true, Some("CmdOrCtrl+Q")))
+  .build()?;
+```
+
+## 快捷键规范
+
+### 全局快捷键
+
+| 快捷键 | macOS | Windows/Linux | 功能 |
+|--------|-------|---------------|------|
+| 新建 | Cmd+N | Ctrl+N | 新建 |
+| 打开 | Cmd+O | Ctrl+O | 打开 |
+| 保存 | Cmd+S | Ctrl+S | 保存 |
+| 关闭 | Cmd+W | Ctrl+W | 关闭当前 |
+| 退出 | Cmd+Q | Alt+F4 | 退出应用 |
+| 撤销 | Cmd+Z | Ctrl+Z | 撤销 |
+| 重做 | Cmd+Shift+Z | Ctrl+Y | 重做 |
+| 复制 | Cmd+C | Ctrl+C | 复制 |
+| 粘贴 | Cmd+V | Ctrl+V | 粘贴 |
+| 全选 | Cmd+A | Ctrl+A | 全选 |
+| 查找 | Cmd+F | Ctrl+F | 查找 |
+| 设置 | Cmd+, | Ctrl+, | 偏好设置 |
+
+### 应用内快捷键
+
+| 快捷键 | 功能 |
+|--------|------|
+| Cmd+1~9 | 切换 Tab |
+| Cmd+[ | 后退 |
+| Cmd+] | 前进 |
+| Cmd++ | 放大 |
+| Cmd+- | 缩小 |
+| Cmd+0 | 实际大小 |
+
+## 系统托盘 (System Tray)
+
+### Electron Tray
+
+```typescript
+// main process
+import { Tray, Menu, nativeImage } from 'electron';
+
+const tray = new Tray(nativeImage.createFromPath('icon.png'));
+
+const contextMenu = Menu.buildFromTemplate([
+  { label: 'Show', click: () => mainWindow.show() },
+  { label: 'Quit', click: () => app.quit() },
+]);
+
+tray.setContextMenu(contextMenu);
+tray.setToolTip('App Name');
+```
+
+### 托盘图标尺寸
+
+| 平台 | 图标尺寸 |
+|------|----------|
+| macOS | 22x22 (template image) |
+| Windows | 16x16, 32x32 |
+| Linux | 22x22 |
+
+## 拖拽区域 (Drag Region)
+
+### 自定义标题栏拖拽
+
+```css
+/* 拖拽区域样式 */
+.titlebar-drag-region {
+  -webkit-app-region: drag;
+  app-region: drag;
+}
+
+/* 排除按钮 */
+.titlebar-button {
+  -webkit-app-region: no-drag;
+  app-region: no-drag;
+}
+```
+
+```tsx
+// React
+<div className="titlebar-drag-region">
+  <span className="title">App Name</span>
+  <div className="titlebar-buttons">
+    <button className="titlebar-button" onClick={handleMinimize}>-</button>
+    <button className="titlebar-button" onClick={handleMaximize}>+</button>
+    <button className="titlebar-button" onClick={handleClose}>x</button>
+  </div>
+</div>
+```
+
+## 上下文菜单 (Context Menu)
+
+```typescript
+// Electron
+const contextMenu = Menu.buildFromTemplate([
+  { label: 'Cut', accelerator: 'Cmd+X', role: 'cut' },
+  { label: 'Copy', accelerator: 'Cmd+C', role: 'copy' },
+  { label: 'Paste', accelerator: 'Cmd+V', role: 'paste' },
+  { type: 'separator' },
+  { label: 'Select All', accelerator: 'Cmd+A', role: 'selectAll' },
+]);
+
+window.addContextMenuListener((event) => {
+  event.preventDefault();
+  contextMenu.popup();
+});
+```
+
+## 通知 (Notifications)
+
+```typescript
+// Electron
+new Notification({
+  title: 'New Message',
+  body: 'You have a new message from John',
+  icon: 'icon.png',
+  silent: false,
+}).show();
+```
+
+## 自动更新
+
+```typescript
+// Electron
+import { autoUpdater } from 'electron-updater';
+
+autoUpdater.on('update-available', () => {
+  // 显示更新提示
+});
+
+autoUpdater.on('update-downloaded', () => {
+  // 提示用户重启安装
+});
+
+autoUpdater.checkForUpdates();
+```
+
+## 文件对话框
+
+```typescript
+// 打开文件
+const result = await dialog.showOpenDialog({
+  properties: ['openFile'],
+  filters: [
+    { name: 'Images', extensions: ['jpg', 'png', 'gif'] },
+    { name: 'All Files', extensions: ['*'] },
+  ],
+});
+
+// 保存文件
+const result = await dialog.showSaveDialog({
+  defaultPath: 'untitled.txt',
+  filters: [
+    { name: 'Text', extensions: ['txt'] },
+  ],
+});
+```
+
+## 窗口间通信 (IPC)
+
+```typescript
+// main.ts
+ipcMain.handle('get-user-data', async () => {
+  return await fetchUserData();
+});
+
+// renderer.ts
+const userData = await window.electronAPI.getUserData();
+```
+
+## 暗色模式
+
+```typescript
+// 监听系统主题变化
+const { nativeTheme } = require('electron');
+
+nativeTheme.on('updated', () => {
+  document.documentElement.dataset.theme = nativeTheme.shouldUseDarkColors ? 'dark' : 'light';
+});
+```
+
+## 评审清单
+
+- [ ] 最小窗口尺寸 ≥ 1024x600
+- [ ] 原生菜单完整 (File/Edit/View/Window/Help)
+- [ ] 全局快捷键不冲突
+- [ ] 支持系统托盘
+- [ ] 支持上下文菜单
+- [ ] 支持文件对话框
+- [ ] 支持拖拽文件到窗口
+- [ ] 支持深色模式
+- [ ] 支持自动更新
+- [ ] macOS traffic lights 可用
+- [ ] 窗口状态持久化