@pzy560117/codex-harness 0.1.2 → 0.1.4

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

@@ -1,151 +0,0 @@
----
-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

@@ -1,58 +0,0 @@
----
-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

@@ -1,187 +0,0 @@
----
-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    | 权限控制遗漏        | 强制填写权限视图表   |