@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/design/design-brief.md

@@ -1,178 +1,183 @@
-# Design Brief 模板
-
-> 目标: 把口头设计偏好、设计稿和产品需求翻译成前端可实现、可审查、可回归的设计真相源。
-
-## 1. 基本信息
-
-- 产品名称:
-- Feature ID:
-- 功能主题:
-- 设计来源: Figma / 截图 / AI 视觉探索 / 现有页面延展 / 其他
-- 设计负责人:
-- 当前状态: Draft / Review / Approved / Changed
-- 目标质量等级: P0 / P1 / P2 / P3
-- 最后更新:
-
-## 2. 设计目标
-
-- 这次设计要解决的核心问题:
-- 优先优化的体验指标:
-- 主要用户:
-- 主要使用场景:
-- 本期不优化的体验:
-
-## 3. 信息架构
-
-| 层级 | 内容 / 区域 | 目的 | 优先级 |
-| --- | --- | --- | --- |
-| L1 | | | P0 |
-| L2 | | | P1 |
-
-## 4. 视觉方向
-
-- 主题风格:
-- 品牌气质:
-- 关键词:
-- 避免的风格:
-- 参考页面 / 竞品:
-
-## 4.1 审美验收与反模式
-
-| 项目 | 标准 | 禁止事项 | 验收方式 |
-| --- | --- | --- | --- |
-| 信息层级 | | | visual review |
-| 密度与扫描 | | | screenshot |
-| 主操作识别 | | | interaction / visual |
-| 状态识别 | | | story / visual |
-| 品牌一致性 | | | design review |
-
-## 5. 色彩策略
-
-| Token / 用途 | 值 | 使用场景 | 禁用场景 |
-| --- | --- | --- | --- |
-| primary | | | |
-| background | | | |
-| success | | | |
-| warning | | | |
-| danger | | | |
-
-## 6. 排版与密度
-
-- 字体:
-- 标题层级:
-- 正文层级:
-- 数字 / 数据展示风格:
-- 信息密度:
-- 表格行高:
-- 表单控件高度:
-
-## 7. 布局与组件原则
-
-| 类型 | 原则 | 复用来源 | 禁止事项 |
-| --- | --- | --- | --- |
-| 页面布局 | | | |
-| 表格 / 列表 | | | |
-| 表单 | | | |
-| 弹窗 / 抽屉 | | | |
-| 状态反馈 | | | |
-
-## 8. 交互原则
-
-| 交互 | 行为 | 反馈 | 约束 |
-| --- | --- | --- | --- |
-| 主按钮 | | | |
-| 次按钮 | | | |
-| hover / focus / active | | | |
-| 加载 | | | |
-| 错误 | | | |
-| 空态 | | | |
-| 批量操作 | | | |
-
-## 8.1 UX Writing
-
-| 场景 | 文案原则 | 示例 | 禁止事项 |
-| --- | --- | --- | --- |
-| 空态 | | | |
-| 筛选无结果 | | | |
-| 加载 | | | |
-| 错误 | | | |
-| 权限不足 | | | |
-| 保存成功 / 失败 | | | |
-
-## 9. 动效等级
-
-| 场景 | 动效 | 时长 | easing | reduced motion | 是否必需 |
-| --- | --- | --- | --- | --- | --- |
-| 页面切换 | | | | | 否 |
-| 列表刷新 | | | | | 否 |
-| 弹窗出现 | | | | | 是/否 |
-| 抽屉出现 | | | | | 是/否 |
-| 筛选 chip 增删 | | | | | 是/否 |
-| 骨架屏 / 进度反馈 | | | | | 是 |
-
-动效约束:
-
-- 首选 `transform` 和 `opacity`。
-- 不允许动效隐藏错误、禁用、权限不足或保存失败。
-- 必须说明 reduced motion 下的替代行为。
-
-## 10. 响应式要求
-
-| 断点 | 宽度 | 布局变化 | 筛选策略 | 表格 / 列表策略 | 操作区策略 | 必须验证的页面 |
-| --- | --- | --- | --- | --- | --- | --- |
-| Desktop | >= 1200px | | | | | |
-| Tablet | 768-1199px | | | | | |
-| Mobile | < 768px | | | | | |
-
-响应式约束:
-
-- 移动端主要流程不能只依赖横向滚动。
-- 表格转卡片时必须说明字段优先级。
-- 长文本、长数字、长标签必须有截断、换行或 tooltip 规则。
-
-## 11. 可访问性要求
-
-- 对比度要求:
-- 键盘可达性:
-- 焦点顺序:
-- 语义化 / ARIA:
-- 状态提示:
-- 错误提示与屏幕阅读器:
-- 弹窗 / 抽屉 focus trap:
-- reduced motion:
-- 触控目标尺寸:
-
-## 11.1 性能预算
-
-| 风险 | 预算 / 阈值 | 策略 | 验证方式 |
-| --- | --- | --- | --- |
-| 首屏依赖 | | | |
-| 列表 / 表格规模 | | | |
-| 图片 / 图标 | | | |
-| 动效帧率 | | | |
-| 数据刷新频率 | | | |
-
-## 12. 真相源优先级
-
-```text
-设计稿 > Design Brief > Product Spec
-```
-
-冲突处理:
-
-- 视觉细节冲突时以设计稿为准。
-- 视觉稿缺失时以本 Design Brief 为准。
-- 功能逻辑以 Product Spec 为准。
-- 如果 Product Spec 和设计稿表达冲突，先阻塞并更新真相源，不直接编码。
-
-## 13. 交付物清单
-
-- [ ] 设计稿或 Figma 页面
-- [ ] `screen-states.md`
-- [ ] `component-map.md`
-- [ ] `design-tokens.json`
-- [ ] `frontend-architecture.md`
-- [ ] 需要补的 stories 清单
-- [ ] 关键页面 visual regression 清单
-- [ ] 无障碍 / 键盘访问要求
-- [ ] 性能预算与验证方式
+# Design Brief 模板
+
+> 目标: 把口头设计偏好、设计稿和产品需求翻译成前端可实现、可审查、可回归的设计真相源。
+
+## 1. 基本信息
+
+- 产品名称:
+- Feature ID:
+- 功能主题:
+- 设计来源: Figma / 截图 / AI 视觉探索 / 现有页面延展 / 其他
+- 设计负责人:
+- 当前状态: Draft / Review / Approved / Changed
+- 目标质量等级: P0 / P1 / P2 / P3
+- 最后更新:
+
+## 2. 设计目标
+
+- 这次设计要解决的核心问题:
+- 优先优化的体验指标:
+- 主要用户:
+- 主要使用场景:
+- 本期不优化的体验:
+
+## 3. 信息架构
+
+| 层级 | 内容 / 区域 | 目的 | 优先级 |
+| --- | --- | --- | --- |
+| L1 | | | P0 |
+| L2 | | | P1 |
+
+## 4. 视觉方向
+
+- 主题风格:
+- 品牌气质:
+- 关键词:
+- 避免的风格:
+- 参考页面 / 竞品:
+
+## 4.1 审美验收与反模式
+
+| 项目 | 标准 | 禁止事项 | 验收方式 |
+| --- | --- | --- | --- |
+| 信息层级 | | | visual review |
+| 密度与扫描 | | | screenshot |
+| 主操作识别 | | | interaction / visual |
+| 状态识别 | | | story / visual |
+| 品牌一致性 | | | design review |
+
+## 5. 色彩策略
+
+| Token / 用途 | 值 | 使用场景 | 禁用场景 |
+| --- | --- | --- | --- |
+| primary | | | |
+| background | | | |
+| success | | | |
+| warning | | | |
+| danger | | | |
+
+## 6. 排版与密度
+
+- 字体:
+- 标题层级:
+- 正文层级:
+- 数字 / 数据展示风格:
+- 信息密度:
+- 表格行高:
+- 表单控件高度:
+
+## 7. 布局与组件原则
+
+| 类型 | 原则 | 复用来源 | 禁止事项 |
+| --- | --- | --- | --- |
+| 页面布局 | | | |
+| 表格 / 列表 | | | |
+| 表单 | | | |
+| 弹窗 / 抽屉 | | | |
+| 状态反馈 | | | |
+
+## 8. 交互原则
+
+| 交互 | 行为 | 反馈 | 约束 |
+| --- | --- | --- | --- |
+| 主按钮 | | | |
+| 次按钮 | | | |
+| hover / focus / active | | | |
+| 加载 | | | |
+| submitting | | | |
+| 错误 | | | |
+| retry | | | |
+| offline | | | |
+| 空态 | | | |
+| 批量操作 | | | |
+
+## 8.1 UX Writing
+
+| 场景 | 文案原则 | 示例 | 禁止事项 |
+| --- | --- | --- | --- |
+| 空态 | | | |
+| 筛选无结果 | | | |
+| 加载 | | | |
+| 错误 | | | |
+| 权限不足 | | | |
+| 保存成功 / 失败 | | | |
+
+## 9. 动效等级
+
+| 场景 | 动效 | 时长 | easing | reduced motion | 是否必需 |
+| --- | --- | --- | --- | --- | --- |
+| 页面切换 | | | | | 否 |
+| 列表刷新 | | | | | 否 |
+| 弹窗出现 | | | | | 是/否 |
+| 抽屉出现 | | | | | 是/否 |
+| 筛选 chip 增删 | | | | | 是/否 |
+| 骨架屏 / 进度反馈 | | | | | 是 |
+
+动效约束:
+
+- 首选 `transform` 和 `opacity`。
+- 不允许动效隐藏错误、禁用、权限不足或保存失败。
+- 必须说明 reduced motion 下的替代行为。
+
+## 10. 响应式要求
+
+| 断点 | 宽度 | 布局变化 | 筛选策略 | 表格 / 列表策略 | 操作区策略 | 必须验证的页面 |
+| --- | --- | --- | --- | --- | --- | --- |
+| Desktop | >= 1200px | | | | | |
+| Tablet | 768-1199px | | | | | |
+| Mobile | < 768px | | | | | |
+
+响应式约束:
+
+- 移动端主要流程不能只依赖横向滚动。
+- 表格转卡片时必须说明字段优先级。
+- 长文本、长数字、长标签必须有截断、换行或 tooltip 规则。
+- 必须说明安全区、键盘弹起和底部操作栏在移动端的处理方式。
+
+## 11. 可访问性要求
+
+- 对比度要求:
+- 键盘可达性:
+- 焦点顺序:
+- 语义化 / ARIA:
+- 状态提示:
+- 错误提示与屏幕阅读器:
+- 弹窗 / 抽屉 focus trap:
+- reduced motion:
+- 触控目标尺寸:
+- 安全区 / 键盘遮挡策略:
+
+## 11.1 性能预算
+
+| 风险 | 预算 / 阈值 | 策略 | 验证方式 |
+| --- | --- | --- | --- |
+| 首屏依赖 | | | |
+| 列表 / 表格规模 | | | |
+| 图片 / 图标 | | | |
+| 动效帧率 | | | |
+| 数据刷新频率 | | | |
+
+## 12. 真相源优先级
+
+```text
+设计稿 > Design Brief > Product Spec
+```
+
+冲突处理:
+
+- 视觉细节冲突时以设计稿为准。
+- 视觉稿缺失时以本 Design Brief 为准。
+- 功能逻辑以 Product Spec 为准。
+- 如果 Product Spec 和设计稿表达冲突，先阻塞并更新真相源，不直接编码。
+
+## 13. 交付物清单
+
+- [ ] 设计稿或 Figma 页面
+- [ ] `screen-states.md`
+- [ ] `component-map.md`
+- [ ] `design-tokens.json`
+- [ ] `frontend-architecture.md`
+- [ ] 需要补的 stories 清单
+- [ ] 关键页面 visual regression 清单
+- [ ] 无障碍 / 键盘访问要求
+- [ ] 性能预算与验证方式

package/package-source/docs/codex-harness-engineering/templates/design/design-tokens.json

@@ -1,88 +1,88 @@
-{
-  "color": {
-    "bg": {
-      "default": "#FFFFFF",
-      "subtle": "#F6F7F9",
-      "inverse": "#111827"
-    },
-    "text": {
-      "primary": "#111827",
-      "secondary": "#4B5563",
-      "muted": "#6B7280",
-      "inverse": "#FFFFFF"
-    },
-    "border": {
-      "default": "#D1D5DB",
-      "strong": "#9CA3AF"
-    },
-    "status": {
-      "success": "#15803D",
-      "warning": "#B45309",
-      "danger": "#B91C1C",
-      "info": "#1D4ED8"
-    }
-  },
-  "spacing": {
-    "xs": 4,
-    "sm": 8,
-    "md": 12,
-    "lg": 16,
-    "xl": 24
-  },
-  "radius": {
-    "sm": 4,
-    "md": 8,
-    "lg": 12
-  },
-  "typography": {
-    "fontFamily": {
-      "base": "system-ui, sans-serif",
-      "mono": "Consolas, monospace"
-    },
-    "fontSize": {
-      "sm": 12,
-      "md": 14,
-      "lg": 16,
-      "xl": 20
-    },
-    "fontWeight": {
-      "regular": 400,
-      "medium": 500,
-      "bold": 700
-    },
-    "lineHeight": {
-      "sm": 1.4,
-      "md": 1.5,
-      "lg": 1.6
-    }
-  },
-  "shadow": {
-    "sm": "0 1px 2px rgba(0, 0, 0, 0.08)",
-    "md": "0 4px 12px rgba(0, 0, 0, 0.12)"
-  },
-  "motion": {
-    "duration": {
-      "fast": 120,
-      "base": 160,
-      "slow": 220
-    },
-    "easing": {
-      "standard": "cubic-bezier(0.2, 0, 0, 1)",
-      "exit": "cubic-bezier(0.4, 0, 1, 1)"
-    },
-    "reducedMotion": "respect-user-preference"
-  },
-  "breakpoint": {
-    "mobile": 768,
-    "tablet": 1200
-  },
-  "zIndex": {
-    "dropdown": 20,
-    "drawer": 40,
-    "modal": 50,
-    "toast": 60
-  },
-  "touchTarget": {
-    "min": 44
-  }
-}
+{
+  "color": {
+    "bg": {
+      "default": "#FFFFFF",
+      "subtle": "#F6F7F9",
+      "inverse": "#111827"
+    },
+    "text": {
+      "primary": "#111827",
+      "secondary": "#4B5563",
+      "muted": "#6B7280",
+      "inverse": "#FFFFFF"
+    },
+    "border": {
+      "default": "#D1D5DB",
+      "strong": "#9CA3AF"
+    },
+    "status": {
+      "success": "#15803D",
+      "warning": "#B45309",
+      "danger": "#B91C1C",
+      "info": "#1D4ED8"
+    }
+  },
+  "spacing": {
+    "xs": 4,
+    "sm": 8,
+    "md": 12,
+    "lg": 16,
+    "xl": 24
+  },
+  "radius": {
+    "sm": 4,
+    "md": 8,
+    "lg": 12
+  },
+  "typography": {
+    "fontFamily": {
+      "base": "system-ui, sans-serif",
+      "mono": "Consolas, monospace"
+    },
+    "fontSize": {
+      "sm": 12,
+      "md": 14,
+      "lg": 16,
+      "xl": 20
+    },
+    "fontWeight": {
+      "regular": 400,
+      "medium": 500,
+      "bold": 700
+    },
+    "lineHeight": {
+      "sm": 1.4,
+      "md": 1.5,
+      "lg": 1.6
+    }
+  },
+  "shadow": {
+    "sm": "0 1px 2px rgba(0, 0, 0, 0.08)",
+    "md": "0 4px 12px rgba(0, 0, 0, 0.12)"
+  },
+  "motion": {
+    "duration": {
+      "fast": 120,
+      "base": 160,
+      "slow": 220
+    },
+    "easing": {
+      "standard": "cubic-bezier(0.2, 0, 0, 1)",
+      "exit": "cubic-bezier(0.4, 0, 1, 1)"
+    },
+    "reducedMotion": "respect-user-preference"
+  },
+  "breakpoint": {
+    "mobile": 768,
+    "tablet": 1200
+  },
+  "zIndex": {
+    "dropdown": 20,
+    "drawer": 40,
+    "modal": 50,
+    "toast": 60
+  },
+  "touchTarget": {
+    "min": 44
+  }
+}