@pzy560117/codex-harness 0.1.4 → 0.1.6

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/fixing-motion-performance/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: fixing-motion-performance
+description: Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.
+---
+
+# fixing-motion-performance
+
+Fix animation performance issues.
+
+## how to use
+
+- `/fixing-motion-performance`
+  Apply these constraints to any UI animation work in this conversation.
+
+- `/fixing-motion-performance <file>`
+  Review the file against all rules below and report:
+  - violations (quote the exact line or snippet)
+  - why it matters (one short sentence)
+  - a concrete fix (code-level suggestion)
+
+Do not migrate animation libraries unless explicitly requested. Apply rules within the existing stack.
+
+## when to apply
+
+Reference these guidelines when:
+- adding or changing UI animations (CSS, WAAPI, Motion, rAF, GSAP)
+- refactoring janky interactions or transitions
+- implementing scroll-linked motion or reveal-on-scroll
+- animating layout, filters, masks, gradients, or CSS variables
+- reviewing components that use will-change, transforms, or measurement
+
+## rendering steps glossary
+
+- composite: transform, opacity
+- paint: color, borders, gradients, masks, images, filters
+- layout: size, position, flow, grid, flex
+
+## rule categories by priority
+
+| priority | category | impact |
+|----------|----------|--------|
+| 1 | never patterns | critical |
+| 2 | choose the mechanism | critical |
+| 3 | measurement | high |
+| 4 | scroll | high |
+| 5 | paint | medium-high |
+| 6 | layers | medium |
+| 7 | blur and filters | medium |
+| 8 | view transitions | low |
+| 9 | tool boundaries | critical |
+
+## quick reference
+
+### 1. never patterns (critical)
+
+- do not interleave layout reads and writes in the same frame
+- do not animate layout continuously on large or meaningful surfaces
+- do not drive animation from scrollTop, scrollY, or scroll events
+- no requestAnimationFrame loops without a stop condition
+- do not mix multiple animation systems that each measure or mutate layout
+
+### 2. choose the mechanism (critical)
+
+- default to transform and opacity for motion
+- use JS-driven animation only when interaction requires it
+- paint or layout animation is acceptable only on small, isolated surfaces
+- one-shot effects are acceptable more often than continuous motion
+- prefer downgrading technique over removing motion entirely
+
+### 3. measurement (high)
+
+- measure once, then animate via transform or opacity
+- batch all DOM reads before writes
+- do not read layout repeatedly during an animation
+- prefer FLIP-style transitions for layout-like effects
+- prefer approaches that batch measurement and writes
+
+### 4. scroll (high)
+
+- prefer Scroll or View Timelines for scroll-linked motion when available
+- use IntersectionObserver for visibility and pausing
+- do not poll scroll position for animation
+- pause or stop animations when off-screen
+- scroll-linked motion must not trigger continuous layout or paint on large surfaces
+
+### 5. paint (medium-high)
+
+- paint-triggering animation is allowed only on small, isolated elements
+- do not animate paint-heavy properties on large containers
+- do not animate CSS variables for transform, opacity, or position
+- do not animate inherited CSS variables
+- scope animated CSS variables locally and avoid inheritance
+
+### 6. layers (medium)
+
+- compositor motion requires layer promotion, never assume it
+- use will-change temporarily and surgically
+- avoid many or large promoted layers
+- validate layer behavior with tooling when performance matters
+
+### 7. blur and filters (medium)
+
+- keep blur animation small (<=8px)
+- use blur only for short, one-time effects
+- never animate blur continuously
+- never animate blur on large surfaces
+- prefer opacity and translate before blur
+
+### 8. view transitions (low)
+
+- use view transitions only for navigation-level changes
+- avoid view transitions for interaction-heavy UI
+- avoid view transitions when interruption or cancellation is required
+- treat size changes as potentially layout-triggering
+
+### 9. tool boundaries (critical)
+
+- do not migrate or rewrite animation libraries unless explicitly requested
+- apply these rules within the existing animation system
+- never partially migrate APIs or mix styles within the same component
+
+## common fixes
+
+```css
+/* layout thrashing: animate transform instead of width */
+/* before */ .panel { transition: width 0.3s; }
+/* after */  .panel { transition: transform 0.3s; }
+
+/* scroll-linked: use scroll-timeline instead of JS */
+/* before */ window.addEventListener('scroll', () => el.style.opacity = scrollY / 500)
+/* after */  .reveal { animation: fade-in linear; animation-timeline: view(); }
+```
+
+```js
+// measurement: batch reads before writes (FLIP)
+// before — layout thrash
+el.style.left = el.getBoundingClientRect().left + 10 + 'px';
+// after — measure once, animate via transform
+const first = el.getBoundingClientRect();
+el.classList.add('moved');
+const last = el.getBoundingClientRect();
+el.style.transform = `translateX(${first.left - last.left}px)`;
+requestAnimationFrame(() => { el.style.transition = 'transform 0.3s'; el.style.transform = ''; });
+```
+
+## review guidance
+
+- enforce critical rules first (never patterns, tool boundaries)
+- choose the least expensive rendering work that matches the intent
+- for any non-default choice, state the constraint that justifies it (surface size, duration, or interaction requirement)
+- when reviewing, prefer actionable notes and concrete alternatives over theory

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/frontend-design/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: frontend-design
+description: Frontend Design Skill
+---
+
+# Frontend Design Skill
+
+创建独特的、生产级的前端界面，避免通用的"AI风格"美学。
+
+## 上游 Skill 接入
+
+前端 UI 任务默认先检查并组合以下已安装 skill：
+
+| 能力 | Skill | 用法 |
+|------|-------|------|
+| 设计语言与整体质感 | `impeccable` | 处理信息架构、视觉层级、排版、间距、色彩、响应式、空/错/加载态和整体 polish |
+| 审美判断与抗默认风格 | `design-taste-frontend`（目录 `taste-skill/`） | 纠正 AI 默认布局、字体、动效、图标和 Tailwind 反模式 |
+| UI 工程基线 | `baseline-ui` | 检查 Tailwind、组件结构、可访问 primitive、加载骨架、交互状态 |
+| 可访问性修复 | `fixing-accessibility` | 处理键盘、焦点、ARIA、语义、表单标签和 reduced motion |
+| 元数据修复 | `fixing-metadata` | 处理标题、描述、Open Graph、社交卡片和 favicon |
+| 动效性能 | `fixing-motion-performance` | 审核动画 duration、transform/opacity、layout thrashing、reduced motion |
+| 图标检索 | `better-icons` | 需要图标时搜索并提取 Iconify SVG；不要凭空画低质量图标 |
+| 大厂 DESIGN.md | `brand-design-md` | 用户提到 Apple、Stripe、Notion、Linear、Claude 等品牌风格时，先拉取 DESIGN.md 再设计 |
+
+`motion-ai-kit` 是 Motion 官方 Motion+ AI Kit，公开 GitHub 没有可直接安装的 skill；如果本机后续安装了 `motion-ai-kit`，动画/动效任务优先使用它，再用 `fixing-motion-performance` 做性能兜底。
+
+## 使用顺序
+
+1. 先从需求或 PRD 中提取产品类型、用户、核心场景、品牌/竞品参照和约束。
+2. 如果出现明确品牌风格，使用 `brand-design-md` 获取 DESIGN.md；如果项目已有 `PRODUCT.md`/`DESIGN.md`，使用 `impeccable` 的上下文规则。
+3. 用 `design-taste-frontend` 设定设计方差、动效强度、信息密度，避免默认 AI UI。
+4. 进入实现前，用 `baseline-ui` 补齐组件、状态、响应式、可访问 primitive 和 Tailwind 规则。
+5. 涉及图标时用 `better-icons`；涉及动画时用 `motion-ai-kit`（若已安装）或 `fixing-motion-performance`。
+6. 交付前至少跑一遍 `fixing-accessibility`、`fixing-motion-performance`；页面级交付同时跑 `fixing-metadata`。
+
+## 设计思维
+
+编码前，理解上下文并确定大胆的美学方向：
+- **目的**: 这个界面解决什么问题？谁在使用？
+- **调性**: 选择一个极端：极简主义、极繁主义、复古未来、有机自然、奢华精致、俏皮玩具风、杂志编辑风、粗野主义、装饰艺术、柔和粉彩、工业实用等
+- **约束**: 技术要求（框架、性能、可访问性）
+- **差异化**: 什么让这个设计令人难忘？
+
+## 美学指南
+
+- **字体**: 选择独特有趣的字体，避免 Arial、Inter 等通用字体
+- **色彩**: 使用 CSS 变量保持一致性，主色配锐利的强调色
+- **动效**: 使用 CSS 动画和微交互，React 项目用 Motion 库
+- **空间构图**: 非对称、重叠、对角线流动、打破网格
+- **背景细节**: 渐变网格、噪点纹理、几何图案、层叠透明度
+
+## 禁止事项
+
+- 不用 Inter、Roboto、Arial 等过度使用的字体
+- 不用紫色渐变配白色背景这种陈词滥调
+- 不用可预测的布局和组件模式
+- 每个设计都应该独特，在明暗主题、字体、美学之间变化
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/frontend-first-workflow/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: frontend-first-workflow
+description: AI Frontend First Development Workflow
+---
+
+# AI 前端先行开发工作流
+
+> 目标：通过"早期 AI 生图反哺需求 → 规格图 → 前端代码 → API契约 → 后端实现"的流程，减少返工，确保前后端一致性
+
+## 流程概览
+
+```mermaid
+flowchart TD
+    A[需求初稿] --> B[页面清单初稿]
+    B --> C[需求-界面轻量追溯矩阵]
+    C --> D[页面规章草案]
+    D --> E[Early AI Image Brief]
+    E --> F[第一轮 AI 界面方向图]
+    F --> G{Early UI Review}
+    G -->|不通过| E
+    G -->|通过| H[反哺 PRD/页面/状态/字段]
+    H --> I[完整需求与测试追溯]
+    I --> J[前置难点研究]
+    J --> K[Design Brief + CSS/Token 规范]
+    K --> L[第二轮 AI 多状态规格图]
+    L --> M{UI Image Review}
+    M -->|不通过| L
+    M -->|通过| N[图片转前端规格]
+    N --> O[前端代码 + Mock 数据]
+    O --> P[提取 API 契约]
+    P --> Q[后端设计与实现]
+    Q --> R[前后端联调]
+    R --> S{功能评审}
+    S -->|不通过| N
+    S -->|通过| T[完成]
+```
+
+## 早期视觉闸门
+
+UI-facing feature 不能等完整 PRD、测试矩阵和 Design Brief 都完成后才第一次生图。只要满足以下条件，就必须先进入第一轮 AI 生图：
+
+- 产品目标、非目标、范围和角色已有初稿。
+- P0 页面清单已有初稿。
+- 每条 P0/P1 需求至少映射到页面、区域、字段、操作和状态。
+- 已写出 `docs/design/page-rules-draft.md`，包含页面类型、信息密度、基础视觉方向、关键组件、状态要求和禁止事项。
+
+第一轮图片是"方向图"，用于暴露需求、页面和信息架构问题；第二轮图片是"规格图"，用于锁定状态、组件、响应式和可编码细节。
+
+## 审美急救包 Skill 路由
+
+UI-facing feature 进入本流程时，按任务类型组合以下 skill：
+
+| 阶段 | 必用/可选 Skill | 作用 |
+|------|-----------------|------|
+| 需求映射 | `requirements-design-template` | 在需求阶段记录品牌参照、反参照、设计方差、动效强度、信息密度 |
+| 设计方向 | `impeccable` + `design-taste-frontend` | 建立整体审美、信息架构、视觉层级、token 和 anti-slop 约束 |
+| 品牌风格 | `brand-design-md` | 用户要求 Apple/Stripe/Notion/Linear/Claude 等风格时拉取 DESIGN.md |
+| UI 工程基线 | `baseline-ui` | 约束 Tailwind、组件 primitive、状态覆盖、响应式和加载骨架 |
+| 图标 | `better-icons` | 搜索并提取真实 SVG 图标，避免低质量自绘图标 |
+| 动效 | `motion-ai-kit`（如已安装）或 `fixing-motion-performance` | 规划动画并检查性能、reduced motion、layout thrashing |
+| 可访问性 | `fixing-accessibility` | 键盘、焦点、ARIA、语义、表单标签 |
+| 页面交付 | `fixing-metadata` | title/meta/OG/social card/favicon |
+
+## Frontend Skill Intake 闸门
+
+写 `docs/design/early-ai-image-brief.md` 之前，必须先完成 Frontend Skill Intake，不能只拿页面清单直接写生图提示词。
+
+最低必读 skill：
+
+- `ui-ux-pro-max`：行业/产品类型、设计风格、信息密度和视觉参照。
+- `impeccable`：审美判断、anti-slop、信息层级和视觉完整度。
+- `design-taste-frontend`：布局、比例、留白、字体、颜色、组件质感。
+- `baseline-ui`：响应式、状态覆盖、可访问性、组件稳定尺寸。
+- `frontend-design`：页面组织、组件层级和可实现性。
+- `better-icons`：图标体系和按钮图标策略。
+- `fixing-accessibility`：关键表单、导航、焦点和语义约束。
+- `fixing-motion-performance`：动效强度、reduced motion 和性能禁区。
+
+按项目条件补读：
+
+- 有指定品牌或风格时读 `brand-design-md`。
+- 已确定 Vue/Arco、React、Next.js 等栈时读对应框架 skill。
+- 有后台/表格/运营工具时读 `frontend-patterns` 和 `state-management`。
+
+Frontend Skill Intake 必须产出 `docs/design/frontend-skill-intake.md`，至少包含：
+
+- `skill_sources`：已读取的 skill 名称和使用原因。
+- `visual_principles`：整体视觉原则、反参照和禁用风格。
+- `density_rules`：移动端、后台、表单、表格的信息密度。
+- `component_rules`：导航、卡片、表格、筛选、详情抽屉、表单、弹窗、底部栏等组件约束。
+- `state_rules`：正常、空、加载、错误、权限、业务异常状态。
+- `responsive_rules`：移动端/桌面端断点、固定比例和不允许挤压的区域。
+- `copy_rules`：关键中文文案、短句规则和禁止乱码。
+- `prompt_enrichment_matrix`：每个页面的视觉层级、组件、状态、字段、操作、约束和禁止项。
+
+`early-ai-image-brief.md` 和后续 `ai-image-brief.md` 必须引用 `frontend-skill-intake.md`，并把 `prompt_enrichment_matrix` 写进每个页面的生图 prompt。缺少该 intake 时，不进入 AI 生图。
+
+## 阶段产出物
+
+| 阶段        | 产出物                 | 评审点                     |
+| ----------- | ---------------------- | -------------------------- |
+| 1. 需求骨架 | `prd-lite.md` 初稿 + `page-inventory.md` 初稿 + 轻量 `requirement-interface-matrix.md` | 是否足以生第一轮方向图 |
+| 2. 页面规章 | `docs/design/page-rules-draft.md` | 信息密度、基础视觉方向、关键组件、状态和禁止事项是否明确 |
+| 2.5 前端 Skill Intake | `docs/design/frontend-skill-intake.md` | 是否已把前端 skills 约束转成页面级 prompt enrichment matrix |
+| 3. 早期 AI 生图 | `early-ai-image-brief.md` + `artifacts/ai-images/early/` | 页面方向、信息架构和布局是否能支撑需求 |
+| 4. 早期图片评审 | `early-ui-review.md` | 图片是否暴露需求缺口，并已反哺 PRD/页面/状态/字段 |
+| 5. 完整需求映射 | 页面清单 + 需求-界面追溯矩阵 + 测试追溯 | 每条需求是否覆盖到界面、状态、字段、接口和验收 |
+| 6. 难点研究 | difficulty-research | 高风险问题是否已在编码前研究 |
+| 7. 设计规范 | Design Brief + CSS/Token 规范 | 第二轮生图输入是否足够精确 |
+| 8. 规格 AI 生图 | 多状态界面设计图 | 状态是否完整、细节是否充分 |
+| 9. 图片评审 | ui-image-review | 需求、状态、CSS 是否匹配 |
+| 10. 图转规格 | image-to-frontend-spec | 图片是否转成可编码前端规格 |
+| 11. 前端开发 | 前端代码 + Mock 数据 | 交互是否符合预期 |
+| 12. API 契约 | OpenAPI/接口文档 | 字段命名、数据结构是否一致 |
+| 13. 后端开发 | 后端代码 + 真实 API | 接口是否符合契约 |
+| 14. 联调验收 | 完整功能 | 端到端流程是否通畅 |
+
+## 常见问题与解决方案
+
+| 问题         | 表现                             | 解决方案             | 模板文件                                     |
+| ------------ | -------------------------------- | -------------------- | -------------------------------------------- |
+| 界面状态不全 | 只有正常态，缺空态/加载态/错误态 | 强制使用状态覆盖清单 | #[[file:templates/page-spec-template.md]]    |
+| 细节不够     | 缺字段校验、操作反馈、数据格式   | 强制填写字段规格表   | #[[file:templates/page-spec-template.md]]    |
+| 前后不一致   | 命名/状态值/数据结构不一致       | 建立一致性检查清单   | #[[file:templates/consistency-checklist.md]] |
+| 需求没落界面 | 写完需求后不知道在哪个页面实现 | 需求-界面追溯矩阵 | `requirement-interface-matrix.md` |
+| 编码时才研究 | 到实现阶段才发现难点 | 前置难点研究 | `difficulty-research.md` |
+| 图片不能编码 | 图好看但缺 CSS/组件/状态规格 | 图转前端规格 | `image-to-frontend-spec.md` |
+| 生图过晚 | PRD/测试/接口写完后才发现页面承载不了 | 早期 AI 生图 + early-ui-review 反哺需求 | `early-ai-image-brief.md`, `early-ui-review.md` |
+
+## 相关模板
+
+使用时请引用对应模板：
+
+| 模板           | 用途                   | 引用方式                   |
+| -------------- | ---------------------- | -------------------------- |
+| 页面规格模板   | 定义单个页面的完整规格 | `#page-spec-template`    |
+| 一致性检查清单 | 评审时检查前后端一致性 | `#consistency-checklist` |
+| AI生图提示词   | 生成界面设计图的提示词 | `#ai-ui-prompts`         |
+| API契约模板    | 从前端提取后端接口规范 | `#api-contract-template` |
+| 需求-界面矩阵 | 需求到界面、状态、字段、接口、验收的追溯 | `requirement-interface-matrix.md` |
+| 难点研究模板 | 编码前研究高风险难点 | `difficulty-research.md` |
+| 图转规格模板 | 把通过评审的图片转成前端实现规格 | `image-to-frontend-spec.md` |
+
+## Early UI Review 检查清单
+
+- [ ] 每条 P0/P1 需求都能在第一轮方向图中找到页面证据。
+- [ ] 页面数量、导航路径和主任务没有明显过长或过载。
+- [ ] 首页、详情、购物车/结算、订单/售后、后台列表/表单/详情等关键页面的信息密度合理。
+- [ ] 后台表格列、筛选、批量操作、详情抽屉、审计入口能承载运营工作。
+- [ ] 移动端底部导航、支付中断、无网络、库存不足、认证失效等关键状态有位置。
+- [ ] 图片没有新增 Product Spec 没有的功能。
+- [ ] 评审结论已回填到 PRD、页面清单、状态矩阵和需求-界面追溯矩阵。
+
+## 评审检查清单
+
+### 界面评审 ⚠️ 必查
+
+- [ ] 所有必要状态都有设计图（正常/空/加载/错误）
+- [ ] 每条 P0/P1 需求都能在界面图中找到证据
+- [ ] 边界场景都有处理方案（超长/超多/为空）
+- [ ] 字段规格完整（类型/格式/校验/错误提示）
+- [ ] 操作反馈明确（成功/失败/确认）
+- [ ] 权限视图区分清晰
+- [ ] CSS / Token 与 Design Brief 一致
+- [ ] 图片没有新增需求之外的功能
+
+### 一致性评审 ⚠️ 必查
+
+- [ ] 命名一致性：同一概念在所有页面使用相同名称
+- [ ] 状态值一致性：前后端状态值映射明确
+- [ ] 交互一致性：相同操作在所有页面行为一致
+
+### API契约评审 ⚠️ 必查
+
+- [ ] 字段命名与前端一致
+- [ ] 数据类型与前端一致
+- [ ] 错误码定义完整
+
+## 返工原因 Top5
+
+| 排名 | 返工原因            | 预防措施             |
+| ---- | ------------------- | -------------------- |
+| 1    | 缺少空态/错误态设计 | 强制填写状态覆盖清单 |
+| 2    | 字段校验规则不明确  | 强制填写字段规格表   |
+| 3    | 前后端命名不一致    | 建立命名一致性表     |
+| 4    | 操作反馈不明确      | 强制填写操作反馈表   |
+| 5    | 权限控制遗漏        | 强制填写权限视图表   |