@bovinphang/frontend-craft 2.5.0

package/skills/fec-legacy-to-modern-migration/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: fec-legacy-to-modern-migration
+description: Use when planning or implementing an intentional migration from JavaScript, jQuery, HTML/CSS, server-rendered templates, or MPA legacy frontend code to React + TypeScript or Vue 3 + TypeScript while preserving behavior. Do not use for routine legacy bug fixes that stay in the old stack; Chinese triggers include 遗留项目, 技术栈升级, jQuery 迁移.
+---
+
+# 传统前端到现代框架迁移
+
+适用于将 JavaScript + jQuery + HTML/CSS 多页面应用（MPA）或服务端模板渲染项目，迁移至 React + TypeScript 或 Vue 3 + TypeScript 单页面应用（SPA）的场景。
+
+## Purpose
+
+指导将 jQuery/MPA 传统前端项目渐进迁移至 React + TypeScript 或 Vue 3 + TypeScript，提供迁移策略、概念映射、分阶段步骤和实施约束，确保功能等价和风险可控。
+
+## 迁移策略选择
+
+| 策略                        | 适用情况                             | 优点                         | 风险                         |
+| --------------------------- | ------------------------------------ | ---------------------------- | ---------------------------- |
+| **渐进式（Strangler Fig）** | 大型项目、需持续交付、团队熟悉度不足 | 风险可控、可分批上线、可回滚 | 新旧并存期长、需维护两套代码 |
+| **一次性重写**              | 中小型项目、业务稳定、有充足时间窗口 | 目标架构清晰、无历史包袱     | 周期长、上线压力大、回滚困难 |
+
+**推荐**：优先考虑渐进式，除非项目规模小且业务简单。
+
+## 概念映射
+
+### jQuery → React
+
+| 遗留模式                                   | React 对应                             |
+| ------------------------------------------ | -------------------------------------- |
+| `$(selector).html(content)`                | 声明式 JSX + state 驱动渲染            |
+| `$(document).on('click', '.btn', handler)` | `onClick` + 事件委托由 React 处理      |
+| `$.ajax()` / `$.get()`                     | `fetch` / `axios` + React Query 或 SWR |
+| 全局变量 / 命名空间存储状态                | `useState` / `useContext` / Zustand    |
+| `$(el).show()` / `$(el).hide()`            | 条件渲染 `{visible && <Component />}`  |
+| 手动 DOM 操作 `append` / `remove`          | 数据驱动，通过 setState 触发重渲染     |
+| 模板字符串拼接 HTML                        | JSX 组件 + props                       |
+| 多页面 + 服务端路由                        | React Router 客户端路由                |
+
+### jQuery → Vue 3
+
+| 遗留模式                                   | Vue 3 对应                                         |
+| ------------------------------------------ | -------------------------------------------------- |
+| `$(selector).html(content)`                | 模板 + `ref` / `reactive` 驱动渲染                 |
+| `$(document).on('click', '.btn', handler)` | `@click` + 事件修饰符                              |
+| `$.ajax()` / `$.get()`                     | `fetch` / `axios` + VueUse `useFetch` 或 Vue Query |
+| 全局变量 / 命名空间存储状态                | `ref` / `reactive` / Pinia                         |
+| `$(el).show()` / `$(el).hide()`            | `v-show` / `v-if`                                  |
+| 手动 DOM 操作                              | 数据驱动，通过响应式更新视图                       |
+| 模板字符串拼接 HTML                        | 单文件组件 `<template>` + props                    |
+| 多页面 + 服务端路由                        | Vue Router 客户端路由                              |
+
+### 通用映射
+
+| 遗留概念                          | 现代对应                                   |
+| --------------------------------- | ------------------------------------------ |
+| 页面级 JS 入口（每页一个 script） | 路由 + 懒加载页面组件                      |
+| 公共 JS 模块（utils、ajax 封装）  | `services/`、`utils/`、类型化 API 层       |
+| 内联样式 / 页面级 CSS             | CSS Modules / Tailwind / styled-components |
+| 服务端模板变量                    | 通过 API 获取 + 前端状态管理               |
+| 表单提交 + 整页刷新               | 表单库 + 客户端校验 + API 调用             |
+
+## 迁移前分析
+
+在动手迁移前，必须完成以下分析并输出**迁移分析报告**：
+
+1. **存量盘点**
+   - 页面数量、功能模块数量
+   - 依赖的 jQuery 插件及替代方案（如 DataTables → TanStack Table）
+   - 现有 API 调用方式、是否有统一封装
+   - 是否有服务端模板（JSP/Thymeleaf/EJS 等）需改为纯前端渲染
+
+2. **依赖关系**
+   - 页面间共享的 JS/CSS 模块
+   - 跨页面复用的业务逻辑
+   - 与后端的接口契约（是否需调整）
+
+3. **迁移优先级**
+   - 按业务价值、复杂度、耦合度排序
+   - 优先迁移独立模块、低耦合页面
+   - 识别可复用的工具函数、常量、类型定义
+
+## 分阶段迁移流程
+
+### 阶段 0：准备
+
+- 搭建新项目脚手架（Vite + React/Vue + TypeScript）
+- 配置 ESLint、Prettier、测试框架
+- 建立 `services/request.ts` 统一请求层，与现有 API 兼容
+- 将遗留项目中的 `utils`、`constants` 逐步迁移并补充类型
+
+### 阶段 1：基础层
+
+- 迁移并类型化 API 调用（`$.ajax` → `axios`/`fetch`）
+- 迁移工具函数（日期、格式化、校验等）
+- 迁移常量、枚举、类型定义
+- 建立路由骨架，占位未迁移页面（重定向或 iframe 嵌入旧页面）
+
+### 阶段 2：按模块/页面迁移
+
+- 每次迁移一个完整功能或页面
+- 从简单到复杂：静态页 → 列表页 → 表单页 → 复杂交互页
+- 迁移时提取可复用组件，遵循目标 React 或 Vue 项目的目录结构
+- 每完成一个模块，补充单元测试和 E2E 关键路径
+
+### 阶段 3：收尾
+
+- 移除旧代码入口，全面切换至 SPA
+- 配置 404、错误边界、全局错误处理
+- 性能优化（懒加载、代码分割、缓存策略）
+- 文档更新、部署流程调整
+
+## 重构实施要求
+
+迁移时需遵循以下实施约束，确保视觉与交互一致、代码更简洁易维护。
+
+### 图片与图标
+
+- 直接使用原项目的图片资源路径，不重新托管或替换
+- 可使用 SVG 图片（`<img src="*.svg" />` 或 CSS `background-image`），**禁止使用内联 SVG**（`<svg>...</svg>` 直接写在组件中）
+- **若原项目使用了 iconfont 或 IcoMoon 图标，重构时继续使用**，保持图标体系一致；不替换为其他图标方案（如独立 SVG、其他图标库）
+- 图标优先使用原项目已有的图标文件（iconfont / IcoMoon / 已有 SVG），必要时可引入 SVG 文件作为独立资源
+
+### 国际化（i18n）
+
+- 新栈代码（React / Vue 等）中的用户可见文案须走项目 i18n，不在新代码里硬编码中/英文案
+- 遗留 HTML/JS 中**不要新增**用户可见硬编码文案，除非纯静态且仓库尚无可用 i18n 接入点；改动文案前先查 locales 是否已有条目，并同步主要语言文件
+- key 按页面/模块/语义组织，复用既有 key；仅当旧 key 为对外契约时才做映射过渡，详见项目规则中的 **国际化 (i18n)**（`templates/shared/rules/fec-i18n.md` 内「遗留代码与迁移场景」）
+
+### 样式
+
+- 布局样式对齐原项目视觉效果，但**只参考原项目效果，不照搬其 CSS**
+- 优先使用 **flex 弹性布局**，避免 `float`、复杂 `position`、冗余嵌套
+- 避免不合理写法：如 `!important` 滥用、过深选择器、重复定义
+- **组件中禁止使用内联样式**（`style={{ ... }}` / `style="..."`），样式统一放在 CSS Modules、Tailwind 类或样式文件中，便于维护
+
+### 目标
+
+- **视觉和交互**：与原项目一致，用户无感知差异
+- **代码质量**：更简洁、易维护，符合目标框架规范
+- **业务功能**：与原项目保持一致，**不得缺失功能**；迁移前后行为等价
+
+## 迁移检查清单
+
+每个迁移单元完成后，确认：
+
+- [ ] 业务逻辑与旧实现一致，无功能遗漏，功能完整等价
+- [ ] 类型定义完整，无 `any` 滥用
+- [ ] API 调用使用统一 request 层，错误处理完整
+- [ ] 表单校验、loading、空状态、错误状态已实现
+- [ ] 可访问性：表单有 label、交互可键盘操作
+- [ ] 无 XSS 风险（用户输入已转义或使用安全 API）
+- [ ] 关键路径有测试覆盖
+- [ ] 符合目标框架的项目规范（参考目标 React / Vue 项目约定）
+- [ ] 图片使用原项目资源，无内联 SVG；若原项目用 iconfont/IcoMoon 则继续使用
+- [ ] 样式参考原项目效果但不照搬 CSS，优先 flex 布局，无内联样式
+- [ ] 视觉与交互与原项目一致，代码更简洁易维护
+- [ ] 新代码路径文案已 i18n；遗留层未扩大硬编码；locales 检索与多语言同步已完成（参见 i18n 规则迁移补充清单）
+
+## Constraints
+
+- 迁移前必须先输出迁移分析报告，明确策略、优先级和风险
+- 不要在一次迁移中同时改架构、改 UI、改接口
+- 优先保证功能等价，再考虑优化和现代化
+- 迁移过程中保持旧系统可运行，避免大爆炸式上线
+- 遇到 jQuery 插件无现成替代时，可暂时用 iframe 或微前端方式嵌入，待后续替换
+- **图片与图标**：使用原项目图片资源，可用 SVG 文件，禁止内联 SVG；若原项目用 iconfont/IcoMoon 则继续使用
+- **样式**：参考原项目效果不照搬 CSS，优先 flex 布局，组件禁止内联样式
+- **目标**：视觉与交互一致、代码更简洁易维护，业务功能不得缺失
+
+## Detailed References
+
+撰写迁移分析或迁移计划报告时，加载 [references/migration-report-template.md](references/migration-report-template.md)。
+
+## Expected Output
+
+- 迁移分析报告保存为 `reports/migration-plan-YYYY-MM-DD-HHmmss.md`，包含策略选择、存量盘点、依赖关系、分阶段步骤、风险与回滚方案
+- 迁移后的业务功能与原项目完全等价，无功能缺失
+- 视觉与交互与原项目一致，用户无感知差异
+- 类型定义完整，无 `any` 滥用，API 调用统一且类型安全
+- 图片使用原项目资源，样式使用 flex 布局，无内联样式
+- 新代码文案已 i18n，关键路径有测试覆盖

package/skills/fec-legacy-to-modern-migration/references/migration-report-template.md

@@ -0,0 +1,41 @@
+# 迁移分析报告模板
+
+```markdown
+# 迁移分析报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 评审工具: frontend-craft
+
+## 策略选择
+- 渐进式 / 一次性重写:
+- 理由:
+
+## 存量盘点
+- 页面数量:
+- 功能模块:
+- jQuery 插件:
+- 服务端模板:
+- API 调用方式:
+
+## 依赖关系
+- 共享 JS/CSS:
+- 跨页面逻辑:
+- 后端接口契约:
+
+## 迁移优先级
+- 第一批:
+- 第二批:
+- 暂缓:
+
+## 分阶段步骤
+- 阶段 0:
+- 阶段 1:
+- 阶段 2:
+- 阶段 3:
+
+## 风险与回滚
+- 风险:
+- 回滚方案:
+```
+
+迁移分析或计划完成后，将报告保存到 `reports/migration-plan-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/skills/fec-legacy-web-standard/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: fec-legacy-web-standard
+description: Use when maintaining or safely modifying existing non-framework frontend code: vanilla JavaScript, jQuery, HTML/CSS, MPA pages, server-rendered templates, legacy plugins, or long-lived code that should stay in its current stack. Use migration skill when planning a move to React/Vue/TypeScript; Chinese triggers include 传统前端, 原生 JS, jQuery.
+---
+
+# 传统前端项目规范（JS + jQuery + HTML）
+
+## Purpose
+
+在不重写技术栈的前提下安全维护 vanilla JS、jQuery、HTML/CSS 和服务端模板项目。
+
+## Procedure
+
+1. 先确认本次改动是维护旧栈还是迁移；迁移到 React/Vue/TypeScript 时切换到现代化迁移 workflow。
+2. 沿用现有架构和代码风格，优先修复问题，不在一次改动中引入多项现代化。
+3. JavaScript 用 IIFE/命名空间减少全局污染，事件绑定优先委托到合理容器。
+4. DOM 更新缓存选择器、批量操作、转义用户输入；Ajax 必须处理 loading、error、空状态和防重复提交。
+5. HTML/CSS 保持语义、label、alt、BEM/既有命名和低选择器深度。
+6. 安全重点检查 `.html()`、`innerHTML`、URL 参数渲染、CSRF token 和文件上传。
+
+## Detailed References
+
+涉及 jQuery 命名空间、事件绑定、Ajax、XSS 转义、文件组织和维护清单示例时，加载 [references/legacy-patterns.md](references/legacy-patterns.md)。
+
+## Constraints
+
+- 在现有架构内改进，不要引入与项目格格不入的现代框架。
+- 渐进增强优于推倒重来。
+- 禁止用 `innerHTML` / `.html()` 直接插入用户输入。
+- 避免全局变量污染。
+- 每次聚焦一个维护点，避免顺手重构整个模块。
+
+## Expected Output
+
+改动与旧项目风格一致，无全局变量泄漏，事件和 DOM 操作可维护，Ajax 状态完整，用户输入已转义，渐进改进不破坏现有功能。

package/skills/fec-legacy-web-standard/references/legacy-patterns.md

@@ -0,0 +1,85 @@
+# 传统前端维护模式
+
+## 命名空间
+
+```javascript
+var App = App || {};
+App.UserModule = (function ($) {
+  "use strict";
+
+  function init() {
+    bindEvents();
+    loadData();
+  }
+
+  function bindEvents() {
+    $(document).on("click", ".js-submit-btn", handleSubmit);
+  }
+
+  return { init: init };
+})(jQuery);
+```
+
+## 事件与 DOM
+
+- 事件触发元素用 `.js-*` class，与样式 class 分离。
+- 缓存频繁使用的选择器。
+- 批量 DOM 操作用 `DocumentFragment` 或一次性插入。
+- 页面卸载或模块销毁时解绑事件或调用插件 destroy。
+
+## Ajax
+
+```javascript
+function fetchUserList(params) {
+  return $.ajax({
+    url: "/api/v1/users",
+    method: "GET",
+    data: params,
+    dataType: "json",
+  })
+    .done(function (res) {
+      if (res.code === 0) renderList(res.data);
+      else showError(res.message);
+    })
+    .fail(function () {
+      showError("网络错误，请稍后重试");
+    })
+    .always(function () {
+      hideLoading();
+    });
+}
+```
+
+## XSS 转义
+
+```javascript
+$(".username").text(userData.name);
+
+function escapeHtml(str) {
+  var div = document.createElement("div");
+  div.appendChild(document.createTextNode(str));
+  return div.innerHTML;
+}
+```
+
+## 文件组织
+
+```text
+project/
+├── css/
+│   ├── common.css
+│   └── pages/user-list.css
+├── js/
+│   ├── lib/jquery.min.js
+│   ├── common/utils.js
+│   └── pages/user-list.js
+└── pages/
+```
+
+## 检查清单
+
+- 没有全局变量泄漏。
+- 事件绑定在合理容器上。
+- Ajax 处理 loading/error/empty。
+- 用户输入已转义。
+- 未扩大第三方库或框架依赖。

package/skills/fec-list-virtualization/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: fec-list-virtualization
+description: Use when optimizing or reviewing large lists, virtual scrolling, windowing, react-window, TanStack Virtual, variable-height rows, dynamic measurement, infinite scroll, grid virtualization, or scroll performance; Chinese triggers include 虚拟列表, 大列表优化, 滚动性能.
+---
+
+# 列表虚拟化优化
+
+## Purpose
+
+通过窗口化只渲染可视区域，解决大列表 DOM 过多和滚动卡顿。
+
+## Procedure
+
+1. 先确认列表规模和瓶颈：500+ 项、滚动掉帧、DOM 节点过多或内存飙升才引入虚拟化。
+2. 固定高度列表用 `react-window`；动态高度、跨框架或高级场景用 TanStack Virtual；遗留项目可维护 `react-virtualized`。
+3. 明确 item size、overscan、容器高度、key、滚动容器和 resize 行为。
+4. 无限滚动时分离数据分页和 DOM 虚拟化；数据获取可联用数据获取 workflow。
+5. 验证 DOM 节点数、滚动 FPS、键盘/屏幕阅读器体验和 Ctrl+F/SEO 限制。
+
+## Detailed References
+
+涉及固定高度列表、可变/动态高度、无限滚动、网格虚拟化和性能注意事项时，加载 [references/virtualization-patterns.md](references/virtualization-patterns.md)。
+
+## Constraints
+
+- SEO 关键内容不要只存在于虚拟项中。
+- 浏览器原生 Ctrl+F 无法搜索未挂载项目。
+- Row 根元素必须透传虚拟库提供的 style/measure ref。
+- overscan 过大会浪费内存，过小会白屏。
+- 动态高度测量要处理 ResizeObserver 和布局抖动。
+
+## Expected Output
+
+10000+ 项列表滚动接近 60fps，DOM 节点数稳定在可视区域及缓冲区范围，内存从 O(n) 降至 O(visible)。

package/skills/fec-list-virtualization/references/virtualization-patterns.md

@@ -0,0 +1,52 @@
+# 虚拟列表模式
+
+## 固定高度列表
+
+```tsx
+import { FixedSizeList as List } from "react-window";
+
+const Row = ({ index, style, data }: { index: number; style: React.CSSProperties; data: User[] }) => (
+  <div style={style}>{data[index].name}</div>
+);
+
+export const UserList = ({ users }: { users: User[] }) => (
+  <List height={500} itemCount={users.length} itemSize={48} width="100%" itemData={users}>
+    {Row}
+  </List>
+);
+```
+
+## 可变高度
+
+```tsx
+import { VariableSizeList as List } from "react-window";
+
+const getItemSize = (index: number) => (items[index].hasSummary ? 120 : 60);
+
+<List height={600} itemCount={items.length} itemSize={getItemSize} width="100%">
+  {CardRow}
+</List>;
+```
+
+## 动态高度
+
+```tsx
+const virtualizer = useVirtualizer({
+  count: messages.length,
+  getScrollElement: () => parentRef.current,
+  estimateSize: () => 60,
+  overscan: 5,
+});
+```
+
+动态内容需要测量元素并处理 ResizeObserver。
+
+## 无限滚动
+
+- `count` 包含 loader 占位项。
+- 最后一个虚拟项进入视口时调用 `fetchNextPage()`。
+- 不要在 render 中无条件触发请求，使用 effect 或明确状态保护。
+
+## 网格虚拟化
+
+二维网格使用 `FixedSizeGrid` 或 TanStack Virtual 的 row/column 双轴方案，确保单元格 style 透传。

package/skills/fec-monorepo-project-standard/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: fec-monorepo-project-standard
+description: Use when creating, reviewing, or restructuring frontend monorepos with pnpm workspace, Turborepo, Nx, multi-package dependency boundaries, task orchestration, package naming, or package publishing; Chinese triggers include monorepo, workspace, 多包.
+---
+
+# Monorepo 项目规范
+
+适用于使用 pnpm workspace、Turborepo 或 Nx 的多包前端仓库。
+
+## Purpose
+
+规范 Monorepo 项目的目录结构、依赖管理、任务编排和包发布流程，确保多包协作的构建效率和版本一致性。
+
+## Procedure
+
+1. 先确认仓库是否已使用 pnpm workspace、Turborepo 或 Nx，并沿用现有包命名与任务约定。
+2. 将应用放在 `apps/`，共享库、配置和工具放在 `packages/` 或既有等价目录。
+3. 内部依赖使用 `workspace:*`，通过依赖图驱动构建顺序。
+4. 为 build、lint、test 配置可缓存、可并行、可增量的根任务，并明确输入、输出和环境变量。
+5. 在 Turborepo/Nx 中配置 affected/changed 范围命令，CI 优先跑受影响包，同时保留主干全量验证入口。
+6. 发布包前检查包边界、循环依赖、exports、peer dependencies 和版本策略。
+
+## 工具选择
+
+| 工具               | 适用 | 特点                       |
+| ------------------ | ---- | -------------------------- |
+| **pnpm workspace** | 基础 | 依赖提升、链接、脚本聚合   |
+| **Turborepo**      | 推荐 | 缓存、并行、依赖图         |
+| **Nx**             | 大型 | 增量构建、云缓存、插件生态 |
+
+## 目录结构
+
+### pnpm + Turborepo
+
+```
+├── package.json                # 根 package，workspace 配置
+├── pnpm-workspace.yaml         # workspace 包列表
+├── turbo.json                  # Turborepo 配置
+│
+├── apps/
+│   ├── web/                    # 主应用
+│   │   ├── package.json
+│   │   └── ...
+│   ├── admin/                  # 管理后台
+│   └── docs/                   # 文档站
+│
+├── packages/
+│   ├── ui/                     # 共享 UI 组件
+│   │   ├── package.json
+│   │   └── src/
+│   ├── utils/                  # 工具函数
+│   ├── config-eslint/         # 共享 ESLint 配置
+│   └── config-typescript/     # 共享 TS 配置
+│
+└── tooling/                    # 构建/测试工具（可选）
+    └── scripts/
+```
+
+### pnpm-workspace.yaml
+
+```yaml
+packages:
+  - "apps/*"
+  - "packages/*"
+```
+
+## 依赖管理
+
+- 内部包使用 `workspace:*` 协议
+- 根 `package.json` 统一部分依赖版本，子包可覆盖
+- 禁止循环依赖，通过 `pnpm why` 检查
+
+```json
+{
+  "dependencies": {
+    "@repo/ui": "workspace:*",
+    "@repo/utils": "workspace:*"
+  }
+}
+```
+
+## Turborepo 任务编排
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**"]
+    },
+    "lint": {
+      "dependsOn": ["^build"]
+    },
+    "test": {
+      "dependsOn": ["^build"]
+    }
+  }
+}
+```
+
+- `^build` 表示先执行依赖包的 build
+- `outputs` 用于缓存命中判断
+- `inputs` 应包含源码、配置、锁文件和环境相关文件；不要把 `.env` secret 值写入缓存 key
+- 远程缓存要区分可信 CI 与本地开发，避免把含敏感信息的产物上传
+
+## Nx 任务编排
+
+```json
+{
+  "targetDefaults": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["{projectRoot}/dist"],
+      "cache": true
+    }
+  }
+}
+```
+
+## 包命名
+
+- 内部包：`@org/package-name` 或 `@repo/package-name`
+- 发布到 npm：遵循 `@scope/name` 规范
+
+## Constraints
+
+- 子包之间通过 `workspace:*` 引用，不发布到 npm 再安装
+- 共享配置（ESLint、TS）放在 `packages/config-*`，子包 extends
+- 构建顺序由依赖图决定，不手动指定无关依赖
+- 根目录执行 `pnpm -r build` 或 `turbo run build` 时，所有包按序构建
+- 禁止循环依赖，新增包时通过 `pnpm why` 检查依赖链
+- CI cache 只缓存依赖安装目录和任务产物，不缓存未验证的构建状态
+- affected 构建不能替代发布前全量验证；主干或 release 分支仍需完整质量门禁
+
+## Expected Output
+
+- Monorepo 目录结构清晰（`apps/` 应用、`packages/` 共享包、`tooling/` 工具）
+- `pnpm-workspace.yaml` 和 `turbo.json` / `nx.json` 配置正确
+- 内部包使用 `workspace:*` 协议，无循环依赖
+- 构建、lint、test 任务可通过根命令一键执行，缓存命中率高
+- CI 能区分 affected 快速反馈和 release 全量验证，缓存配置不会泄露密钥或隐藏依赖边界问题

package/skills/fec-motion-interaction/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: fec-motion-interaction
+description: Use when designing, implementing, or reviewing frontend interaction motion, page transitions, scroll animation, Framer Motion, GSAP, Lottie, CSS animation, motion intensity, animation performance, reduced-motion behavior, or cinematic but accessible UI motion. Do not use for SVG-only path drawing, Canvas/WebGL rendering, or ordinary hover states; Chinese triggers include 动效设计, 交互动效, 页面转场, 滚动动画, Framer Motion, GSAP.
+---
+
+# 交互动效
+
+适用于需要把页面转场、滚动叙事、组件入场、微交互和反馈节奏设计成可维护、可降级、可验证的前端动效任务。需要具体实现模式时加载 [motion-patterns.md](references/motion-patterns.md)。
+
+## Purpose
+
+为前端界面选择合适动效工具、强度和质量门禁。
+
+## Procedure
+
+1. 判断动效职责
+   - 先写清动效服务的用户意图：定位、反馈、层级变化、状态确认、叙事引导或品牌记忆。
+   - 工具型界面默认克制，优先保障扫描效率；营销页和作品页可增加节奏，但不能遮挡主要信息。
+   - 若动效只装饰而不改善理解、反馈或品牌识别，应删掉或改成静态视觉处理。
+   - loading、skeleton、toast、错误提示和成功反馈属于状态沟通；动效只能增强反馈节奏，不能替代文本、语义或可见状态。
+
+2. 选择技术路线
+   - CSS transition/keyframes：hover、focus、toast、简单入场和小型状态反馈。
+   - Framer Motion：React 状态驱动、布局过渡、列表编排和可中断的组件级动画。
+   - GSAP：时间轴、滚动触发、复杂序列和跨元素精确编排。
+   - Lottie：设计工具输出的图标或空状态动画，按需懒加载。
+   - CSS scroll-driven animation：可接受渐进增强且无需旧浏览器一致性时使用。
+
+3. 定义强度等级
+   - Level 1-2：只用 150-250ms opacity/transform，适合后台、表单和高频工具。
+   - Level 3-4：加入短 stagger、局部 spring 和轻量 reveal，适合仪表盘、设置页和管理台。
+   - Level 5-6：加入视差、布局 morph、指针响应，适合产品展示和交互式首页。
+   - Level 7+：使用滚动叙事、固定段落或 3D/WebGL 配合，必须单独做移动端和 reduced-motion 降级。
+
+4. 建立性能边界
+   - 只高频动画 `transform`、`opacity`，谨慎使用 `filter` 和 `clip-path`。
+   - GSAP、Lottie、Three.js、重型动画组件必须动态导入或隔离在叶子组件。
+   - 持续动画需要暂停条件：不可见、标签页隐藏、用户关闭、低电量或 reduced motion。
+   - 不在滚动事件中同步读写布局；使用 IntersectionObserver、ScrollTimeline 或节流后的 rAF。
+
+5. 设计可访问降级
+   - 所有非必要动效读取 `prefers-reduced-motion`，降级为静态、淡入或即时状态。
+   - 自动播放或循环动效若超过 5 秒，应提供暂停方式或只在局部非关键区域运行。
+   - 不闪烁超过每秒 3 次；不要用动效作为唯一状态提示。
+   - focus ring、错误提示、成功反馈必须在无动效时同样清楚。
+   - 手势动画必须有点击、键盘或明确控件替代；拖拽、滑动和长按不能成为唯一操作路径。
+
+6. 验证交付
+   - 在 375px、768px、1440px 检查动效是否遮挡文案、按钮或表格内容。
+   - 检查首次加载 bundle 是否因动效库显著膨胀。
+   - 手动开启 reduced motion，确认动画被禁用或弱化。
+   - 用性能面板或实际设备确认滚动和关键交互没有明显掉帧。
+
+## Constraints
+
+- 不在同一个组件内混用 Framer Motion 和 GSAP 控制同一元素。
+- 不用动效掩盖 loading、empty、error、disabled 等状态缺失。
+- 不为普通后台表格、配置页和高频工作台默认加入大幅视差或滚动劫持。
+- 不动画 `width`、`height`、`top`、`left`、`margin`、`padding` 等会频繁触发布局的属性。
+- 不把大型 Lottie JSON、GSAP 插件或 3D 场景放入首屏同步包。
+- 不让动画改变阅读顺序、焦点顺序或键盘可达性。
+- 不用 skeleton 长时间占位掩盖真实加载失败；超过预期时应转入可理解的 loading、retry 或 error 状态。
+
+## Expected Output
+
+输出应包含动效目的、技术选型、强度等级、降级策略、性能边界和验证结果。完成后交互动效应帮助用户理解状态和层级，在 reduced-motion 与低端设备上仍可用，并且不显著拖慢首屏或滚动体验。