bovinphang/frontend-craft

# 无障碍实现规范（WCAG 2.2 AA）

## 用途

确保前端 UI 对残障用户可访问，满足 WCAG 2.2 AA 的核心要求，并能被键盘、屏幕阅读器、触控和缩放用户稳定使用。

## 流程

1. 检查语义结构：landmark、标题层级、表单 label、按钮/链接可访问名称、表格语义和图片 alt。
2. 检查键盘路径：Tab 顺序、Enter/Space/Esc 行为、焦点可见、关闭后焦点恢复。
3. 检查复杂组件：对话框、菜单、标签页、树、抽屉、表格和自定义控件的 ARIA 状态。
4. 检查动态状态：loading、empty、error、toast 和异步更新需要被屏幕阅读器感知。
5. 检查视觉与触控可读性：文本/背景对比、focus ring、缩放到 200%、减少动效偏好、触摸目标尺寸和移动端虚拟键盘行为。
6. 用真实键盘路径复核关键流程，必要时补充屏幕阅读器或浏览器无障碍树观察；屏幕阅读器流程见 [references/screen-reader-testing.md](references/screen-reader-testing.md)。

# 项目吸收与原创化融合

## 用途

将一个或多个参考系统中的优秀思想、能力和工程实践，转化为当前项目中原创、可维护、符合目标项目风格的改进。

适用于吸收、借鉴、对标、迁移或融合另一个代码库、产品、框架、库、服务、CLI、插件、文档体系、AI/Agent 工具链、架构或工程工作流。普通 Bug 修复、单独 API 使用问题或直接文件格式转换不应使用本 Skill，除非用户明确要求项目级吸收或适配。

## 流程

1. 明确目标和参考系统：
   - 将当前仓库视为目标系统，它的架构、命名、测试、发布模型和维护边界是事实来源。
   - 将外部仓库、上传压缩包、文档、示例、产品描述或运行体验视为参考系统，它们只提供证据和启发。
   - 识别吸收范围：产品能力、架构模式、领域模型、接口协议、数据流、运行时行为、开发体验、质量体系、交付流程、文档知识或生态扩展。

# API 集成

适用于前端与后端边界的类型、错误、鉴权、上传、实时通信和用户状态设计。需要具体代码模式时加载 [integration-patterns.md](references/integration-patterns.md)。

## 用途

规范前端 API 集成边界，让请求、错误、鉴权和实时数据可维护。

## 流程

1. 明确接口所有权
   - 同团队 TypeScript 全栈可考虑 tRPC 或共享 schema。
   - 多语言或多消费者 API 优先 OpenAPI/GraphQL codegen。
   - 小型内部应用可用 typed fetch wrapper，但类型必须集中维护。

# 前后端需求交接

## 用途

把前端页面和交互所需的数据、动作、状态和疑问整理成后端可讨论的需求说明。

## 流程

1. 明确功能上下文
   - 说明页面、流程或组件是什么，面向哪类用户，以及用户完成任务的成功状态。
   - 如果已有设计稿、路由、用户故事或权限角色，先把它们作为事实来源。

2. 描述前端展示需求
   - 按屏幕或组件列出需要展示的信息、信息之间的关系、排序/过滤/分页需求和可见性规则。

# 浏览器存储

## 用途

根据数据大小、安全要求和生命周期选择合适的客户端存储方案。

## 流程

1. 先判断数据敏感度、体积、生命周期、是否需要跨 Tab、是否需要随请求发送。
2. 小量非敏感偏好用 localStorage；Tab 级临时数据用 sessionStorage；大量结构化数据或离线缓存用 IndexedDB；认证态优先 httpOnly cookie。
3. 封装统一 key 前缀、JSON parse/stringify、异常处理、过期清理和 quota 兜底。
4. 敏感数据按安全规则处理，不把明文 token、密码、信用卡信息放进可被 JS 读取的存储。
5. 审查隐私模式、存储配额、清理策略和跨浏览器兼容性。

# Canvas 与 Three.js

## 用途

在浏览器中实现高性能 2D/3D 图形渲染。

## 流程

1. 先选渲染层：标准 UI 用 DOM；简单 2D 图形/签名/粒子用 Canvas 2D；3D 模型、空间交互和复杂粒子用 Three.js/WebGL；React 项目中的声明式 3D 用 React Three Fiber。
2. 为渲染容器定义稳定尺寸、DPI 适配和 resize 行为；Canvas 不会自动随 CSS 清晰缩放。
3. 动画循环使用 `requestAnimationFrame`，不可见或无变化时暂停，卸载时取消。
4. Three.js 必须释放 geometry/material/texture/renderer，并移除事件监听和 observer。
5. Shader/WebGL 任务先识别是 SDF、ray marching、noise、particle、post-processing、multipass 还是调试问题，再决定是否需要原生 WebGL2、Three.js ShaderMaterial 或 R3F。
6. WebGL2 适配时检查 GLSL 版本、入口函数、varying/in-out、texture API、uniform 使用和函数声明顺序，避免白屏只留控制台错误。

# 前端代码评审

## 评审模式与覆盖范围

用户明确指定的范围优先于默认行为。采用以下三种审核模式：

- **改动审核**：仅在明确要求或当前任务已明确最近改动、本次修改、暂存区、PR 或提交上下文时，审核这些改动及必要上下文。本地模式在请求范围内检查暂存、未暂存差异及相关未跟踪项目文件；仅要求暂存区时只审核暂存改动。无改动时说明没有可审核的改动，不自动切换到最近提交或扩大范围。
- **指定范围审核**：用户指定文件或目录时，建立范围内文件清单，审核其中现有代码，包括未改动代码；不要求 Git 差异。
- **全项目审核（默认）**：未指定范围或改动上下文，或明确要求审核整个项目时，建立项目自有前端代码、相关测试、配置和依赖声明的清单，再按模块分批审核，包括未改动代码；不要求 Git 差异。

先选择范围，再收集差异。仅指定文件或目录表示全量审核该范围；路径与明确改动请求同时出现时，仅增量审核该路径的改动。未限定的调用即使存在 Git 改动也默认全项目审核。开始审核时说明选定模式和目标范围。修改后自动委托审核时，显式传入本次改动范围，避免无范围调用触发全项目审核。

默认排除依赖目录、构建产物、缓存、生成文件和第三方代码，并记录排除项。保持前端职责边界，不宣称完成后端专项审核。目标不存在或范围内无相关文件时，明确说明，不替换为其他范围。

# 代码坏味道诊断

## 概览
基于具体证据诊断结构问题。坏味道是进一步调查的信号，不等于必须修改代码的结论。

## 执行流程
1. 明确分析范围和项目事实。
2. 收集结构、依赖方向、职责和变化耦合证据。
3. 对照[坏味道目录](references/smell-catalog.md)。
4. 执行[误判检查](references/detection-guide.md)。
5. 根据[坏味道到重构手法映射](references/smell-to-refactoring-map.md)报告置信度、影响和候选方案。
6. 如果用户只要求诊断，不修改业务代码。

## Finding 输出契约

# 组件测试

## 用途

用贴近代码和用户行为的测试验证纯逻辑、组件契约与轻量模块协作，减少重构和 UI 交互回归。

## 流程

### 1. 先确定测试层级

- 单元测试：纯函数、hooks/composables、utils、状态逻辑、schema。
- 组件测试：props/emits、回调、用户交互、loading/error/empty、mock 边界。
- 轻量集成测试：表单 + API mock + Router/Store/Provider 上下文。

# Server State 数据获取

## 用途

为前端 server state 建立清晰的数据获取、缓存、失效和提交边界，避免请求状态散落在页面组件中。

## 流程

1. 判断状态来源：来自服务端且需要缓存、去重、刷新、分页或 mutation 时使用请求缓存方案；纯本地 UI 状态用组件 state 或 store。
2. 先沿用项目已有数据获取库；新增依赖时 React/Vue/Solid/Svelte 可考虑 TanStack Query，也可沿用 SWR、Nuxt/Nitro 数据获取或项目封装。
3. 设计稳定 cache key/query key：结构包含实体、动作和所有影响结果的参数。
4. API 函数保持纯请求函数，数据 hook/composable 负责缓存、select、loading/error/empty 状态。
5. mutation 成功后 invalidation；需要即时反馈时使用 optimistic update 并在失败时回滚。

# 前端诊断框架

## 用途

用证据驱动的分类、收集、假设、验证和修复流程定位前端故障，避免凭直觉扩大改动范围。

## 流程

所有前端问题诊断遵循统一流程：

### Step 1: 分类（Classify）

识别问题类型和影响范围：

# 依赖升级

适用于前端依赖升级、漏洞修复、大版本迁移和 lockfile 风险评审。需要具体流程和检查清单时加载 [references/dependency-upgrade-workflow.md](references/dependency-upgrade-workflow.md)。

## 用途

用来源驱动和小批验证的方式升级依赖，降低破坏性变更、供应链风险和 CI 回归。

## 流程

1. 建立事实基线：读取 package manager、lockfile、Node 版本、workspace 范围、CI 命令和当前验证状态。
2. 分类升级目标：安全修复、补丁升级、小版本升级、大版本迁移、框架迁移、构建工具迁移或依赖清理。
3. 查证来源：对版本敏感的库读取官方 release notes、migration guide、peer dependency、Node/browser 支持和弃用项。
4. 拆小批次：安全补丁可集中处理；大版本、构建工具、框架和测试工具必须单独批次验证。

# 文档同步

## 用途

从代码、配置、测试、类型、脚本和运行时模板同步前端项目文档，避免 README、docs、环境变量说明、API/路由说明、架构决策和迁移说明与实际项目行为漂移。

## 流程

1. 识别项目栈、文档入口和本次需要同步的范围；README 同步必须扫描根目录 `README*`、`docs/*/README*`、包、应用、部署或运行时相关 README，并排除 `node_modules`、构建产物和第三方依赖目录。
2. 收集事实来源：`package.json`、lockfile、框架和构建配置、`.env.example`、路由、API clients 或 server routes、types/schemas、组件、测试、CI、build/deploy config。
3. 比对 README、docs、ADR、changelog、example prompts、setup/deploy/env docs 中的命令、环境变量、路由、API 行为、部署步骤和支持矩阵。
4. 只更新稳定的公共约定；不要把临时调试结论、一次性报告或未落地设计写入长期文档。
5. 若仓库已有多语言文档或国际化 README，主 README 的公共事实更新后必须检查其它语言 README 是否需要同步；功能名称、命令名、脚本名、包名、组件/API 名称、报告文件名、路径、环境变量、路由/API 名称、版本约束和支持矩阵必须跨语言一致。
6. 产品文案可保持本地化表达，但不得保留旧事实、旧默认推荐或过期示例；无法高质量翻译时，至少同步关键事实，并在输出中标出人工翻译风险。

# 可编辑技术图表工作流

## 用途

生成、校验和导出可继续编辑的 draw.io / diagrams.net 技术图表。

## 流程

1. 判断图表路线
   - 需要长期维护在 Markdown 中的简单图，优先 Mermaid。
   - 需要官方图标、泳道、复杂布局、层/标签/元数据、可编辑 PNG/SVG/PDF 或 `.drawio` 源时，使用本工作流。
   - 需要快速浏览器打开或分享时，用 [diagram-url.mjs](scripts/diagram-url.mjs) 生成 URL；需要本地可审计交付时，始终保存 `.drawio` 源。
   - 用户已经有 Mermaid 或 CSV 内容时，可用 `diagram-url.mjs --create --type mermaid|csv` 交给 diagrams.net 导入；需要长期维护或精确形状时，再转成 XML。
   - 如果当前宿主已经配置 draw.io MCP App/Tool，可把它作为预览或编辑入口；本 skill 不要求安装 MCP server。

# E2E 测试规范

## 用途

用真实浏览器验证关键用户旅程，发现单元测试无法覆盖的集成风险。

## 流程

1. 明确关键旅程：登录、购买、创建、搜索、权限、支付等跨页面流程优先；若只是选择测试层级，先做测试分层规划。
2. 新项目优先 Playwright；已有 Cypress 项目沿用 Cypress，不为迁移而迁移。
3. 用 Page Object 或 fixtures 封装登录、页面定位器和共享数据，spec 中避免裸选择器。
4. 断言用户可见结果，依赖 Locator 自动等待、网络响应或可见状态，不使用固定 sleep。
5. CI 必须上传 HTML report、截图、trace 或视频；flaky 用例要隔离、复现、标注来源并关联 issue。
6. 调试失败时先读 trace、console、network 和截图，再改测试；不要把真实产品缺陷误判成 flaky。

# 表单处理

## 用途

管理表单状态、校验和提交，避免复杂表单输入卡顿。

## 流程

1. 先识别框架、项目既有表单库、schema 校验库、组件库和复杂度；10+ 字段、动态字段、联动校验、文件上传、多步流程或输入卡顿时再引入专门表单方案。
2. 按项目栈选型：React 可考虑 React Hook Form + Zod；Vue 可考虑 vee-validate / FormKit + Zod、Yup 或 Valibot；简单表单可用框架原生状态和基础校验。
3. 用运行时 schema 或明确校验函数守住外部输入边界；TypeScript 类型可从 schema 推导，但不要只写 TS 类型。
4. 明确默认值、字段注册、受控/非受控边界和组件库适配；错误提示用 `aria-invalid`、`aria-describedby` 和 `role="alert"`。
5. 提交时处理 loading、服务端错误、重复提交和 reset；大型表单用局部订阅和子组件隔离控制重渲染。

# 图片生成与图表工作流

## 用途

生成或编辑图表、视觉资产和图片工作流，并对导出的 PNG 做可复查的自检与修复迭代。

## 流程

1. 判断产物类型
   - 文本、结构和连线准确性优先时，用 Mermaid、SVG、HTML/CSS、canvas 或图表库生成可编辑源，再导出 PNG。
   - 需要单文件浏览器打开、暗/亮主题和结构化 QA 的系统蓝图、架构图、部署拓扑、Agent runtime、memory flow、before-after architecture、流程、序列、数据流、生命周期、runbook、状态机或 PII/数据血缘图时，使用 HTML technical diagrams。
   - 流程地图、审批流、自动化运行、异常路径和循环运营流需要清晰的起止节点、决策、参与者、步骤编号和摘要，但不需要 diagrams.net 时，在 Mermaid 不可用或明确需要浏览器泳道/主题交付时，使用兼容 HTML `workflow` 路线。
   - 系统、Agent、memory、数据或 tool-call 图需要语义节点形状、有含义的连线和可浏览器打开、可导出、可 QA 的源文件时，使用主题化 HTML technical diagrams。
   - 用户需要在本地浏览器里看到节点和连线实时出现，或需要在会话中拖拽、改标签、删除、缩放并快速导出草图时，使用交互式实时图表路线。

# 按设计稿实现

## 用途

基于设计工具（Figma、Sketch、MasterGo、Pixso、墨刀、摹客）的设计上下文，高保真实现页面或组件，强调组件复用、设计 Token 映射、可访问性和面向生产的前端实现。

## 支持的设计工具

| 工具     | MCP 集成                  | 获取设计数据方式                          |
| -------- | ------------------------- | ----------------------------------------- |
| Figma    | `figma` / `figma-desktop` | API 获取设计结构、变量定义                |
| Sketch   | `sketch`                  | MCP 获取设计选区截图                      |
| MasterGo | `mastergo`                | API 获取 DSL 结构数据                     |
| Pixso    | `pixso`                   | 本地 MCP 获取帧数据和代码                 |

# 传统前端到现代框架迁移

适用于将 JavaScript + jQuery + HTML/CSS 多页面应用（MPA）、服务端模板渲染项目或旧框架代码，渐进迁移到 React、Vue、Next.js、Nuxt、TypeScript，或保留 MPA 形态但现代化模块、构建、类型和测试的场景。

## 用途

指导传统前端项目渐进迁移到目标现代栈，提供迁移策略、概念映射、分阶段步骤和实施约束，确保功能等价和风险可控。

## 流程

1. 先识别目标栈、迁移边界和是否保留 MPA/服务端模板形态。
2. 加载 [references/migration-strategy-and-mapping.md](references/migration-strategy-and-mapping.md)，选择渐进式或一次性重写策略，并明确遗留模式到目标栈的映射。
3. 加载 [references/migration-execution-checklist.md](references/migration-execution-checklist.md)，完成存量盘点、依赖分析、优先级排序和分阶段迁移计划。
4. 撰写迁移分析或迁移计划报告时，加载 [references/migration-report-template.md](references/migration-report-template.md)。

# 传统前端项目规范（JS + jQuery + HTML）

## 用途

在不重写技术栈的前提下安全维护 vanilla JS、jQuery、HTML/CSS 和服务端模板项目。

## 流程

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 和文件上传。

# 列表虚拟化优化

## 用途

通过窗口化只渲染可视区域，解决大列表 DOM 过多和滚动卡顿。

## 流程

1. 先确认列表规模和瓶颈：500+ 项、滚动掉帧、DOM 节点过多或内存飙升才引入虚拟化。
2. 先遵循项目现有框架、依赖和设计系统约束，再按场景选库：React 可考虑 `react-window` 或 TanStack Virtual；Vue/Solid/Svelte、动态测量、网格或跨框架场景优先考虑 TanStack Virtual；遗留 `react-virtualized` 只维护不新增。
3. 明确 item size、overscan、容器高度、key、滚动容器和 resize 行为。
4. 无限滚动时分离数据分页和 DOM 虚拟化；数据获取可联用数据获取 workflow。
5. 验证 DOM 节点数、滚动 FPS、键盘/屏幕阅读器体验和 Ctrl+F/SEO 限制。

# Monorepo 项目规范

适用于使用 pnpm workspace、Turborepo 或 Nx 的多包前端仓库。

## 用途

规范 Monorepo 项目的目录结构、依赖管理、任务编排和包发布流程，确保多包协作的构建效率和版本一致性。

## 流程

1. 先确认仓库是否已使用 pnpm workspace、Turborepo 或 Nx，并沿用现有包命名与任务约定。
2. 将应用放在 `apps/`，共享库、配置和工具放在 `packages/` 或既有等价目录。
3. 内部依赖使用 `workspace:*`，通过依赖图驱动构建顺序。
4. 为 build、lint、test 配置可缓存、可并行、可增量的根任务，并明确输入、输出和环境变量。

# 交互动效

适用于需要把页面转场、滚动叙事、组件入场、微交互和反馈节奏设计成可维护、可降级、可验证的前端动效任务。需要具体实现模式时加载 [motion-patterns.md](references/motion-patterns.md)。

## 用途

为前端界面选择合适动效工具、强度和质量门禁。

## 流程

1. 判断动效职责
   - 先写清动效服务的用户意图：定位、反馈、层级变化、状态确认、叙事引导或品牌记忆。
   - 工具型界面默认克制，优先保障扫描效率；营销页和作品页可增加节奏，但不能遮挡主要信息。
   - 若动效只装饰而不改善理解、反馈或品牌识别，应删掉或改成静态视觉处理。

# Next.js 项目规范

适用于使用 Next.js 14+ 与 App Router 的仓库。

## 用途

规范 Next.js 14+ 项目中 App Router、SSR/SSG/ISR 渲染模式、数据获取、路由布局、中间件和 SEO 元数据的工程实践，确保服务端优先、性能优化和可维护性。

## 流程

1. 先识别目标属于 App Router、布局、服务端数据、middleware、metadata 还是客户端交互。
2. 默认服务端组件优先；只有需要浏览器 API、交互状态或事件处理时才使用 `'use client'`。
3. 明确 SSR / SSG / ISR / CSR 渲染模式和 Next fetch/cache 策略。
4. 为路由补齐 `loading.tsx`、`error.tsx`、`not-found.tsx`、metadata 和敏感逻辑的服务端边界。

# Nuxt 3 项目规范

适用于使用 Nuxt 3 + Vue 3 + TypeScript 的仓库。

## 用途

规范 Nuxt 3 项目中 SSR/SSG 渲染模式、组合式 API、自动导入、数据获取、路由中间件和模块插件的工程实践，确保约定式开发和类型安全。

## 流程

1. 先识别目标属于 Nuxt pages/layouts、渲染模式、数据获取、route middleware、plugin/module 还是 server route。
2. 明确 SSR / SSG / SPA 选择，避免服务端可执行代码依赖 `window` 或 `document`。
3. 数据获取优先使用 Nuxt 的 `useFetch` / `useAsyncData`，并检查水合一致性。
4. 路由鉴权、redirect 和权限问题与路由保护 workflow 对齐。

# 前端性能优化

## 用途

用可度量的方式定位前端性能瓶颈，并把优化建议收敛到用户主路径、构建产物和运行时证据。

## 流程

1. 锁定体验目标
   - 明确问题属于首屏加载、交互延迟、滚动卡顿、内存上涨、网络瀑布、包体积，还是视觉稳定性。
   - 记录路由、设备、网络条件、浏览器、复现步骤和当前可用指标。
   - 没有指标时先建立基线，不直接给出“优化一切”的泛化建议。

2. 建立度量基线

# PWA 实现

## 用途

让 Web 应用具备可安装、离线兜底和可控更新能力。

## 流程

1. 确认 PWA 是否值得做：面向移动端/桌面安装、弱网离线、重复访问场景时优先；纯内部后台、强实时流媒体或只需要普通缓存时不要强行 PWA。
2. 先补齐 manifest、图标、主题色和 HTML 引用；图标至少覆盖 192/512，Android 需 maskable，iOS 需 apple touch icon。
3. 注册 Service Worker，并设计更新提示；不要静默 `skipWaiting()` 后强刷用户页面。
4. 用 Workbox 或框架插件管理 precache/runtime cache；登录、支付、权限变更等敏感请求必须走网络。
5. 提供 offline fallback 页面和安装提示 UI，并验证首次加载、离线访问、更新激活、卸载重装。

# React 项目规范

适用于 React + TypeScript 仓库中的中大型模块建设、页面重构和工程结构设计。

## 用途

为 React + TypeScript 项目提供工程结构、模块边界和默认实现约定，确保架构清晰、代码可维护。

## 流程

本 skill 主要解决 React 工程任务“如何设计和落地”的问题，不重复声明基础编码底线。处理 React 工程化任务时，按以下顺序执行：

1. 识别仓库已有约定
   - 目录组织方式

# 重构清理

## 用途

在验证保护下识别并清理无用前端代码，减少技术债，同时避免误删动态引用、路由入口、配置文件和运行时约定。

## 流程

1. 先建立基线：运行或确认当前 lint、type-check、test、build 的状态。
2. 收集候选项：
   - 优先使用仓库已有工具，如 knip、depcheck、ts-prune、eslint、TypeScript。
   - 没有工具时，用 `rg` 检查引用、导出、路由、注册点和文档入口。
3. 按风险分类：
   - SAFE：测试夹具、未引用工具函数、明确未导出的私有组件。

# 技能：保持行为的重构

## 用途

以小步、可验证、可回滚的方式重组仍在使用的前端代码，同时保持用户、调用方、测试、路由和集成能够观察到的行为不变。

## 核心契约

每次执行都遵守以下规则：

1. **行为保持**：纯重构只改变内部结构，不主动改变可观察行为。
2. **修改前基线**：编辑前先记录当前可用验证结果。
3. **一次只做一个主要重构**：每一步只有一个主要结构意图。
4. **每一步都验证**：完成一步后立即运行最小但有效的验证。

# API 类重构

## 概览
只有在证据和前置条件支持时才使用对应手法。一次只执行一个主要结构变换，并在完成后立即验证。

## 执行流程
1. 在[API 类重构详细卡片](references/api-refactorings.md)确认手法和前置条件。
2. 记录受影响行为与差异预算。
3. 只执行该手法最小可行的一步。
4. 在组合下一手法之前验证当前步骤。
5. 公共契约、生命周期、状态身份或实际范围超出预期时停止并重新评估。

## 快速索引
详细 Reference 包含本 family 的 10 个标准手法，每项均包括意图、信号、不适用条件、操作步骤、行为保持检查、相关坏味道、组合关系、JS/TS/React/Vue 注意事项、前端适配和原创示例。

# 重构目录选择

## 概览
把完整重构目录作为决策辅助，而不是自动套用的配方。只有当证据、前置条件和行为契约匹配时，才选择最小可验证的手法。

## 工作流
1. 在[重构目录索引](references/catalog-index.md)定位标准手法。
2. 若从坏味道或症状出发，使用[选择指南](references/selection-guide.md)比较成因和候选手法。
3. 若需要多个步骤，使用[组合指南](references/composition-guide.md)只安排当前代码真正需要的前置关系。
4. 确定手法后再按需加载对应 family 的详细资料。

## 选择规则
- 一个坏味道可能对应多个候选，先确认真实成因。
- 优先可回滚、局部、小范围的变换，而不是直接大改架构。

# 条件控制类重构

## 概览
只有在证据和前置条件支持时才使用对应手法。一次只执行一个主要结构变换，并在完成后立即验证。

## 执行流程
1. 在[条件控制类重构详细卡片](references/conditional-refactorings.md)确认手法和前置条件。
2. 记录受影响行为与差异预算。
3. 只执行该手法最小可行的一步。
4. 在组合下一手法之前验证当前步骤。
5. 公共契约、生命周期、状态身份或实际范围超出预期时停止并重新评估。

## 快速索引
详细 Reference 包含本 family 的 6 个标准手法，每项均包括意图、信号、不适用条件、操作步骤、行为保持检查、相关坏味道、组合关系、JS/TS/React/Vue 注意事项、前端适配和原创示例。

# 数据重组类重构

## 概览
只有在证据和前置条件支持时才使用对应手法。一次只执行一个主要结构变换，并在完成后立即验证。

## 执行流程
1. 在[数据重组类重构详细卡片](references/data-refactorings.md)确认手法和前置条件。
2. 记录受影响行为与差异预算。
3. 只执行该手法最小可行的一步。
4. 在组合下一手法之前验证当前步骤。
5. 公共契约、生命周期、状态身份或实际范围超出预期时停止并重新评估。

## 快速索引
详细 Reference 包含本 family 的 5 个标准手法，每项均包括意图、信号、不适用条件、操作步骤、行为保持检查、相关坏味道、组合关系、JS/TS/React/Vue 注意事项、前端适配和原创示例。

# 封装类重构

## 概览
只有在证据和前置条件支持时才使用对应手法。一次只执行一个主要结构变换，并在完成后立即验证。

## 执行流程
1. 在[封装类重构详细卡片](references/encapsulation-refactorings.md)确认手法和前置条件。
2. 记录受影响行为与差异预算。
3. 只执行该手法最小可行的一步。
4. 在组合下一手法之前验证当前步骤。
5. 公共契约、生命周期、状态身份或实际范围超出预期时停止并重新评估。

## 快速索引
详细 Reference 包含本 family 的 9 个标准手法，每项均包括意图、信号、不适用条件、操作步骤、行为保持检查、相关坏味道、组合关系、JS/TS/React/Vue 注意事项、前端适配和原创示例。

# 函数类重构

## 概览
只有在证据和前置条件支持时才使用对应手法。一次只执行一个主要结构变换，并在完成后立即验证。

## 执行流程
1. 在[函数类重构详细卡片](references/function-refactorings.md)确认手法和前置条件。
2. 记录受影响行为与差异预算。
3. 只执行该手法最小可行的一步。
4. 在组合下一手法之前验证当前步骤。
5. 公共契约、生命周期、状态身份或实际范围超出预期时停止并重新评估。

## 快速索引
详细 Reference 包含本 family 的 11 个标准手法，每项均包括意图、信号、不适用条件、操作步骤、行为保持检查、相关坏味道、组合关系、JS/TS/React/Vue 注意事项、前端适配和原创示例。

# 继承关系类重构

## 概览
只有在证据和前置条件支持时才使用对应手法。一次只执行一个主要结构变换，并在完成后立即验证。

## 执行流程
1. 在[继承关系类重构详细卡片](references/inheritance-refactorings.md)确认手法和前置条件。
2. 记录受影响行为与差异预算。
3. 只执行该手法最小可行的一步。
4. 在组合下一手法之前验证当前步骤。
5. 公共契约、生命周期、状态身份或实际范围超出预期时停止并重新评估。

## 快速索引
详细 Reference 包含本 family 的 11 个标准手法，每项均包括意图、信号、不适用条件、操作步骤、行为保持检查、相关坏味道、组合关系、JS/TS/React/Vue 注意事项、前端适配和原创示例。

# 搬移特性类重构

## 概览
只有在证据和前置条件支持时才使用对应手法。一次只执行一个主要结构变换，并在完成后立即验证。

## 执行流程
1. 在[搬移特性类重构详细卡片](references/moving-refactorings.md)确认手法和前置条件。
2. 记录受影响行为与差异预算。
3. 只执行该手法最小可行的一步。
4. 在组合下一手法之前验证当前步骤。
5. 公共契约、生命周期、状态身份或实际范围超出预期时停止并重新评估。

## 快速索引
详细 Reference 包含本 family 的 9 个标准手法，每项均包括意图、信号、不适用条件、操作步骤、行为保持检查、相关坏味道、组合关系、JS/TS/React/Vue 注意事项、前端适配和原创示例。

# 技能：重构验证

## 用途

定义可观察行为契约，并为每个结构步骤选择足够且不过度的验证证据。

## 流程

1. 在重要编辑前记录相关行为契约。
2. 将安全网分为 A、B、C 三个等级。
3. 运行并记录修改前基线。
4. 根据当前步骤的风险和边界选择验证方式。
5. 每个结构步骤后立即运行最小有效检查。
6. 新增失败出现时先回滚当前步骤，再扩大排查。

# 响应式布局

适用于需要让页面、工具界面、表格、仪表盘或组件在多设备上稳定工作的前端任务。需要布局模式和检查清单时加载 [references/responsive-layout-patterns.md](references/responsive-layout-patterns.md)。

## 用途

用内容优先、移动优先和容器感知的方式设计响应式布局，避免只靠固定断点修补溢出。

## 流程

1. 明确信息优先级：小屏先保留核心任务、关键操作和反馈；次要信息折叠、延后或移入详情层。
2. 选择布局策略：简单页面用 mobile-first 断点；嵌套组件、卡片网格和侧栏优先考虑 container query。
3. 设计流式尺寸：用 `minmax()`、`clamp()`、`aspect-ratio`、`max-width`、`min-width: 0` 和稳定网格轨道控制伸缩。
4. 处理数据密集界面：表格、列表、看板和编辑器需要明确横向滚动、列优先级、冻结列或移动端摘要视图。

# 路由保护

## 用途

为前端应用建立清晰的认证、授权和重定向边界，避免越权访问与闪烁渲染。

## 适用场景

- 页面需要登录后访问，或不同角色看到不同路由。
- 需要实现 React Router、Next.js、Nuxt 或 Vue Router 的路由守卫。
- 登录过期、权限不足、组织/租户切换需要统一处理。
- 不用于替代服务端授权；前端路由保护只能改善体验，不能作为唯一安全边界。

## 流程

# 前端安全审查

## 评审模式与覆盖范围

用户明确指定的范围优先于默认行为。采用以下三种审核模式：

- **改动审核**：仅在明确要求或当前任务已明确最近改动、本次修改、暂存区、PR 或提交上下文时，审核这些改动及必要上下文。本地模式在请求范围内检查暂存、未暂存差异及相关未跟踪项目文件；仅要求暂存区时只审核暂存改动。无改动时说明没有可审核的改动，不自动切换到最近提交或扩大范围。
- **指定范围审核**：用户指定文件或目录时，建立范围内文件清单，审核其中现有代码，包括未改动代码；不要求 Git 差异。
- **全项目审核（默认）**：未指定范围或改动上下文，或明确要求审核整个项目时，建立项目自有前端代码、相关测试、配置和依赖声明的清单，再按模块分批审核，包括未改动代码；不要求 Git 差异。

先选择范围，再收集差异。仅指定文件或目录表示全量审核该范围；路径与明确改动请求同时出现时，仅增量审核该路径的改动。未限定的调用即使存在 Git 改动也默认全项目审核。开始审核时说明选定模式和目标范围。修改后自动委托审核时，显式传入本次改动范围，避免无范围调用触发全项目审核。

默认排除依赖目录、构建产物、缓存、生成文件和第三方代码，并记录排除项。保持前端职责边界，不宣称完成后端专项审核。目标不存在或范围内无相关文件时，明确说明，不替换为其他范围。

# 来源驱动开发

## 用途

在前端实现、评审和架构决策中优先依据项目内事实、官方文档和当前版本行为，避免沿用过时经验或未经验证的假设。

## 流程

1. 判断是否需要查源
   - 涉及框架新版本、路由、渲染模式、缓存、构建工具、浏览器 API、包发布格式、鉴权协议或公共接口时必须查源。
   - 涉及项目约定时先读本仓库 README、配置、模板、已有实现、测试和迁移记录。
   - 只是稳定语言语法或明显局部重构时，可使用项目现有模式作为事实来源。

2. 收集权威材料

# 前端状态管理

## 用途

为前端状态确定清晰归属，避免全局 store 膨胀、重复缓存和派生状态同步错误。

## 流程

### 1. 先分类状态来源

不要先选 Redux、Zustand、Pinia 或 Context。先把每个状态标到唯一归属，再决定工具。

| 状态类型         | 典型例子                             | 默认归属                 |
| ---------------- | ------------------------------------ | ------------------------ |

# Storybook 组件文档化

## 用途

为 UI 组件建立文档化、设计系统展示和隔离状态预览环境；交互与视觉测试只覆盖 Storybook 场景内的组件状态。

## 流程

1. 初始化或识别现有 Storybook 配置，沿用项目框架适配器、stories glob、主题和构建命令。
2. 每个组件的 Story 覆盖默认态、主要变体、尺寸、语义 tone、disabled、loading、error、empty、selected、invalid 和关键边缘状态。
3. 依赖 Router、Store、i18n、ThemeProvider 的组件用 decorators 包裹，不在 Story 中复制应用入口。
4. 复杂组件用 MDX 补充使用说明、Props、slots/children、variant 矩阵、状态示例、可访问性要求和源码展示。
5. 需要自动化时接入 interaction tests、addon-a11y、Chromatic 或 Storybook Test Runner；这些能力服务于组件文档和设计系统展示，不承接跨页业务旅程。
6. 设计系统组件应记录 token 来源、Tailwind/class 变体、暗色模式、响应式尺寸和不支持的组合，避免消费者靠猜测拼装。

# SVG 动画实现

## 用途

为 SVG 图标、插画和数据可视化提供可维护、可访问、性能可控的动画方案。

## 适用场景

- 需要实现 SVG 图标、Logo、插画或路径描边动画。
- 需要在 React/Vue 组件中接入 Framer Motion、GSAP 或 CSS 动画。
- 需要根据 `prefers-reduced-motion` 提供动效降级。
- 不用于复杂 3D/WebGL 场景；此类场景优先使用 Canvas / Three.js workflow。

## 流程

# Tailwind 设计系统

适用于用 Tailwind CSS 承载产品设计系统、组件变体和主题规则的前端任务。需要具体配置、variant、class 组织和迁移细节时加载 [references/tailwind-system-patterns.md](references/tailwind-system-patterns.md)。

## 用途

让 Tailwind 项目中的 token、主题、组件变体和响应式样式可维护，而不是把一次性 utility class 散落到业务代码里。

## 流程

1. 识别现状：确认 Tailwind 版本、配置位置、暗色模式策略、组件库、CSS 变量、设计 token 和 class 合并工具。
2. 建立 token 边界：颜色、间距、圆角、阴影、字体、z-index 和断点优先从项目 token 或 `theme.extend` 派生。
3. 设计组件变体：按钮、输入框、卡片、弹窗、表格等基础组件用集中 variant API 表达尺寸、语义、状态和密度。
4. 控制 class 复杂度：重复组合沉淀为组件、slot、variant 或局部 helper；不要把长 class 字符串复制到多个页面。

# 前端 TDD 工作流

## 用途

用“先写失败测试，再实现最小代码，再重构”的节奏交付前端功能，避免只在实现后补覆盖率。

## 流程

1. 识别可观察行为：用户能看到的 UI、组件契约、hook/composable 返回值、路由守卫结果、API client 输出或错误状态。
2. 先写一个最小失败测试：
   - 纯逻辑优先单元测试。
   - 组件交互优先 Testing Library / Vue Test Utils。
   - 跨页关键流程优先 Playwright / Cypress。
3. 运行该测试并确认失败原因正确，失败应来自行为尚未实现，而不是语法、导入或测试环境错误。

# 前端测试策略

## 用途

按“离代码多近 / 覆盖风险层级”选择测试方法，避免把所有风险都塞进组件测试或 E2E。

## 流程

1. 识别改动类型：纯逻辑、UI 组件、跨模块流程、浏览器能力、视觉稳定性、专项质量风险或发布门禁。
2. 建立测试层级矩阵，至少区分：
   - 静态检查：TypeScript、ESLint、格式、依赖安全、构建。
   - 单元测试：utils、hooks/composables、状态逻辑、schema、纯函数。
   - 组件测试：props/emits、用户交互、loading/error/empty、mock 边界。
   - 轻量集成测试：表单 + API mock + 路由/Store/Provider 上下文。

# TypeScript 项目规范

## 用途

统一 TypeScript 层的工程配置、类型边界和发布产物规则。适用于前端应用、组件库、SDK、CLI、monorepo package 和纯 TypeScript 工具库，但不接管 React、Vue、Next.js、Nuxt 或 Vite 的框架架构职责。

## 流程

1. 识别 TypeScript 上下文
   - 应用项目：优先检查 `tsconfig` 分层、strictness、路径别名、类型检查脚本和框架生成类型。
   - 组件库或 SDK：优先检查 public API、声明文件、package exports、peer dependencies 类型边界和发布前 pack 校验。
   - CLI 或 Node 工具：优先检查 Node 目标版本、ESM/CJS 策略、`moduleResolution`、shebang 产物和 `process.env` 类型边界。
   - Monorepo package：优先检查 project references、composite build、包间导入边界和 workspace 路径别名是否泄漏到发布产物。
   - React、Vue、Next.js、Nuxt 等框架的组件架构、路由组织和状态管理归对应框架 skill；本流程只处理跨框架 TypeScript 契约和工程边界。

# UI 设计

适用于需要把前端界面推进到“符合产品语境、可扫描、可信赖、有辨识度，并且细节稳定”的 UI 任务。需要系统化设计建议时，加载 [design-intelligence.md](references/design-intelligence.md)；需要长期沉淀设计系统时，加载 [master-page-overrides.md](references/master-page-overrides.md)；上线前做 UI/UX QA 时，加载 [pre-delivery-checklist.md](references/pre-delivery-checklist.md)。

可执行设计系统生成器位于 [design-system.mjs](scripts/design-system.mjs)，其原创知识包包括 [product-rules.json](data/product-rules.json)、[style-archetypes.json](data/style-archetypes.json)、[ux-quality-rules.json](data/ux-quality-rules.json) 和 [stack-ui-rules.json](data/stack-ui-rules.json)。

## 用途

为页面、组件、仪表盘和工具界面建立设计方向，并完成可落地的视觉与交互 polish。

## 流程

1. 明确界面的工作
   - 先说清它帮助用户完成什么任务，而不是先选颜色或布局。

# 验证并修复

## 用途

自动化执行已有验证命令，分析失败原因并安全修复，确保质量门禁达标。

## 流程

1. 从 package.json 或仓库文档中识别可用命令。
2. 优先按以下顺序执行：
   - lint
   - type-check
   - unit/integration tests
   - build

# Vite 项目规范

适用于 Vite 应用、组件库、开发服务器和构建配置的设计与审查。

## 用途

规范 Vite 配置、安全边界和构建性能，避免开发环境与生产构建的常见陷阱。

## 流程

1. 识别项目类型
   - 应用项目优先检查 `root`、`base`、`server.proxy`、`envPrefix`、`build` 和框架插件。
   - 组件库项目优先检查 `build.lib`、类型产物、peer dependencies external 和导出入口。
   - Monorepo 额外检查 `server.fs.allow`、路径别名和包依赖边界。

# Vue 3 项目规范

适用于使用 Vue 3 + TypeScript 的仓库。

## 用途

为 Vue 3 + TypeScript 项目提供工程结构、组件边界、Composables 和默认实现约定，确保约定式开发和类型安全。

## 流程

1. 识别仓库已有 Vue 约定：目录、路由、Pinia、请求层、样式体系、组件库和测试框架。
2. 划分页面、业务组件、通用组件、composables、stores、services 和 utils 的边界。
3. 优先沿用 `<script setup lang="ts">`、组合式 API 和仓库现有自动导入/模块出口约定。
4. 输出时补齐状态归属、API 层、错误处理、样式隔离和专项 skill 分流。

# 网页视频演示

## 用途

把文章、口播稿、课程、产品讲解或技术分享转成可录屏的 16:9 网页演示。产物应像一个可点击推进的视频舞台：每一步承载一个口播节拍，视觉设计服务内容节奏，并能用浏览器稳定录制。

## 流程

1. 判断输入形态
   - 用户给文章或长文时，先拆成口播稿和 outline。
   - 用户给现成口播稿时，保留原顺序，只补 outline、章节和 step。
   - 用户只给主题但没有内容时，先要求素材、大纲或目标要点；不要替用户虚构整篇内容。

2. 生成内容计划

# Web Workers

## 用途

把昂贵计算移出主线程，保持输入、滚动和动画响应。

## 流程

1. 先确认瓶颈：任务超过约 10ms、用户输入延迟明显、FPS 下滑或大文件解析/图像处理/加密计算才考虑 Worker。
2. 选择通信模型：简单任务用 `postMessage`，函数式 RPC 用 Comlink，大量并行小任务用 Worker pool，跨 Tab 同步用 SharedWorker。
3. 设计消息协议：请求/响应类型、错误类型、取消或超时策略都要明确。
4. 传大对象时优先 Transferable Objects；不要让结构化克隆吞掉 Worker 带来的收益。
5. 在组件或页面卸载时 `terminate()`，并通过 Profiler、Performance 面板或 FPS 指标验证主线程改善。

# Accessibility Implementation Specification (WCAG 2.2 AA)

## Purpose

Ensure the front-end UI is accessible to users with disabilities, meets the core requirements of WCAG 2.2 AA, and is stable for keyboard, screen reader, touch, and zoom users.

## Procedure

1. Check the semantic structure: landmark, title level, form label, button/link accessible name, table semantics and image alt.
2. Check the keyboard path: Tab order, Enter/Space/Esc behavior, focus visible, focus restored after closing.
3. Check the ARIA status of complex components: dialog boxes, menus, tabs, trees, drawers, tables, and custom controls.
4. Check dynamic status: loading, empty, error, toast and asynchronous updates need to be perceived by screen readers.
5. Check visual and touch readability: text/background contrast, focus ring, zoom to 200%, reduced animation preference, touch target size, and mobile virtual keyboard behavior.
6. Use the real keyboard path to review the key process, and if necessary, add a screen reader or browser accessibility tree observation; see [references/screen-reader-testing.md](references/screen-reader-testing.md) for the screen reader process.

# Integration of project absorption and originality

## Purpose

Convert excellent ideas, capabilities, and engineering practices from one or more reference systems into improvements in the current project that are original, maintainable, and consistent with the target project style.

Suitable for absorbing, borrowing, benchmarking, migrating or integrating another code base, product, framework, library, service, CLI, plug-in, documentation system, AI/Agent tool chain, architecture or engineering workflow. This Skill should not be used for general bug fixes, individual API usage issues, or direct file format conversions, unless the user explicitly requests project-level ingestion or adaptation.

## Procedure

1. Clarify goals and reference systems:
- Treat the current repository as the target system and its architecture, naming, testing, release model and maintenance boundaries as the source of truth.
- Treat external repositories, uploaded packages, documentation, examples, product descriptions or running experiences as reference systems that only provide evidence and inspiration.
- Identify the scope of absorption: product capabilities, architectural patterns, domain models, interface protocols, data flow, runtime behavior, development experience, quality system, delivery process, documentation knowledge or ecological expansion.

# API integration

Suitable for front-end and back-end boundary types, errors, authentication, uploads, real-time communication and user status design. Load [integration-patterns.md](references/integration-patterns.md) when specific code patterns are required.

## Purpose

Standardize front-end API integration boundaries to make requests, errors, authentication, and real-time data maintainable.

## Procedure

1. Clarify interface ownership
   - For TypeScript full stack in the same team, tRPC or shared schema can be considered.
   - Multi-language or multi-consumer API preferred OpenAPI/GraphQL codegen.
   - Typed fetch wrapper can be used for small internal applications, but types must be maintained centrally.

# Handover of front-end and back-end requirements

## Purpose

Organize the data, actions, status, and questions required for front-end pages and interactions into discussion-ready requirements for the back-end.

## Procedure

1. Clarify the functional context
- Describe what the page, process, or component is, what type of user it is intended for, and the success status of the user completing the task.
   - If there are existing designs, routes, user stories, or permission roles, use them as sources of truth first.

2. Describe front-end display requirements
   - List information to be displayed by screen or component, relationships between information, sorting/filtering/pagination requirements and visibility rules.

# Browser storage

## Purpose

Choose the appropriate client storage solution based on data size, security requirements, and lifecycle.

## Procedure

1. First determine the data sensitivity, volume, life cycle, whether it needs to be spread across tabs, and whether it needs to be sent with the request.
2. Use localStorage for a small amount of non-sensitive preferences; use sessionStorage for tab-level temporary data; use IndexedDB for large amounts of structured data or offline caching; prioritize httpOnly cookies for authentication status.
3. Encapsulate unified key prefix, JSON parse/stringify, exception handling, expiration cleanup and quota protection.
4. Sensitive data is processed according to security rules, and plain text tokens, passwords, and credit card information are not put into storage that can be read by JS.
5. Review privacy mode, storage quotas, sanitization policies, and cross-browser compatibility.

# Canvas and Three.js

## Purpose

Enable high-performance 2D/3D graphics rendering in the browser.

## Procedure

1. First select the rendering layer: DOM for standard UI; Canvas 2D for simple 2D graphics/signatures/particles; Three.js/WebGL for 3D models, spatial interactions and complex particles; React Three Fiber for declarative 3D in React projects.
2. Define stable size, DPI adaptation, and resize behavior for the render container; Canvas does not automatically scale cleanly with CSS.
3. The animation loop uses `requestAnimationFrame`, which is paused when it is invisible or has no changes, and canceled when it is uninstalled.
4. Three.js must release geometry/material/texture/renderer and remove event listeners and observers.
5. Shader/WebGL tasks first identify whether it is an SDF, ray marching, noise, particle, post-processing, multipass or debugging issue, and then decide whether native WebGL2, Three.js ShaderMaterial or R3F is required.
6. Check the GLSL version, entry function, varying/in-out, texture API, uniform usage and function declaration order when adapting to WebGL2 to avoid white screen leaving only console errors.

# Front-end code review

## Review modes and coverage

User-specified scope takes precedence over the default. Use the following three review modes:

- **Change review**: only when recent changes, current edits, staged changes, a PR or a commit are explicitly requested or clearly established by the active task, review those changes and necessary context. For local changes, inspect staged and unstaged diffs and relevant untracked project files within the requested scope; a staged-only request reviews only staged changes. If there are no changes, report that there is nothing to review; do not switch to recent commits or expand scope automatically.
- **Targeted review**: when files or directories are specified, inventory and review existing code in that scope, including unchanged code; no Git diff is required.
- **Project review (default)**: when no scope or change context is specified, or when the entire project is requested, inventory project-owned frontend code, related tests, configuration and dependency declarations, then review in module batches, including unchanged code; no Git diff is required.

Select scope before collecting diffs. A file/directory alone means full review of that scope; a path combined with an explicit change request restricts incremental review to that path. An unqualified invocation defaults to project review even if Git changes exist. At review start, state the selected mode and target scope. When automatically delegating review after edits, pass the current change scope explicitly; do not trigger project review merely because the reviewer was called.

Exclude dependency directories, build outputs, caches, generated files and third-party code by default, and record exclusions. Keep the frontend responsibility boundary; this is not a backend audit. A nonexistent target or a scope with no relevant files must be reported explicitly, not replaced with another scope.

# Code Smell Diagnosis

## Overview
Diagnose structural problems from concrete evidence. A smell is a prompt to investigate, not proof that code must change.

## Procedure
1. Establish the requested scope and project facts.
2. Collect concrete structural and change-coupling evidence.
3. Match evidence against [the smell catalog](references/smell-catalog.md).
4. Apply [false-positive checks](references/detection-guide.md).
5. Report confidence, impact, and candidates from [the mapping guide](references/smell-to-refactoring-map.md).
6. If the request is diagnosis-only, do not modify business code.

## Finding Contract

#Component testing

## Purpose

Use tests close to the code and user behavior to verify pure logic, component contracts, and lightweight module collaboration to reduce refactoring and UI interaction regression.

## Procedure

### 1. First determine the test level

- Unit testing: pure functions, hooks/composables, utils, state logic, schema.
- Component testing: props/emis, callbacks, user interaction, loading/error/empty, mock boundaries.
- Lightweight integration testing: form + API mock + Router/Store/Provider context.

# Server State data acquisition

## Purpose

Establish clear data acquisition, caching, invalidation and submission boundaries for front-end server state to avoid request state being scattered among page components.

## Procedure

1. Determine the source of the state: use the request caching scheme when it comes from the server and needs caching, deduplication, refreshing, paging or mutation; use component state or store for purely local UI state.
2. First use the existing data acquisition library of the project; when adding dependencies, you can consider TanStack Query for React/Vue/Solid/Svelte, or you can also use SWR, Nuxt/Nitro data acquisition or project encapsulation.
3. Stable design cache key/query key: The structure contains entities, actions and all parameters that affect the results.
4. The API function remains a pure request function, and the data hook/composable is responsible for cache, select, loading/error/empty status.
5. Invalidation after mutation succeeds; use optimistic update when immediate feedback is needed and rollback when failure occurs.

# Front-end diagnostic framework

## Purpose

Use an evidence-driven triage, collection, hypothesis, verification, and remediation process to locate front-end faults and avoid relying on intuition to expand the scope of changes.

## Procedure

All front-end problem diagnosis follows a unified process:

### Step 1: Classify

Identify problem type and scope of impact:

# Dependency upgrade

Suitable for front-end dependency upgrades, bug fixes, major version migrations and lockfile risk reviews. Load [references/dependency-upgrade-workflow.md](references/dependency-upgrade-workflow.md) when you need specific processes and checklists.

## Purpose

Reduce disruptive changes, supply chain risks, and CI regressions by upgrading dependencies in a provenance-driven and small-batch verification manner.

## Procedure

1. Establish a baseline of truth: Read package manager, lockfile, Node version, workspace scope, CI commands, and current verification status.
2. Classified upgrade goals: security fixes, patch upgrades, minor version upgrades, major version migrations, framework migrations, build tool migrations, or dependency cleanup.
3. Verify sources: For version-sensitive libraries, read official release notes, migration guide, peer dependency, Node/browser support and deprecation items.
4. Split into smaller batches: Security patches can be processed centrally; large versions, build tools, frameworks and testing tools must be verified in separate batches.

# Document synchronization

## Purpose

Synchronize front-end project documentation from code, configuration, tests, types, scripts and runtime templates to avoid README, docs, environment variable descriptions, API/routing descriptions, architectural decisions and migration notes from drifting from actual project behavior.

## Procedure

1. Identify the project stack, document entry and the scope that needs to be synchronized this time; README synchronization must scan the root directory `README*`, `docs/*/README*`, package, application, deployment or runtime related README, and exclude `node_modules`, build products and third-party dependency directories.
2. Gather sources of truth: `package.json`, lockfile, framework and build configurations, `.env.example`, routes, API clients or server routes, types/schemas, components, tests, CI, build/deploy config.
3. Compare commands, environment variables, routes, API behaviors, deployment steps and support matrix in README, docs, ADR, changelog, example prompts, setup/deploy/env docs.
4. Only update stable public conventions; do not write temporary debugging conclusions, one-time reports or unimplemented designs into long-term documents.
5. If the warehouse already has multilingual documents or internationalized README, after updating the public facts of the main README, you must check whether other language READMEs need to be synchronized; function names, command names, script names, package names, component/API names, report file names, paths, environment variables, routing/API names, version constraints, and support matrices must be consistent across languages.
6. Product copy can maintain localized expression, but must not retain old facts, old default recommendations, or expired examples; when high-quality translation is not possible, at least synchronize key facts, and mark the risks of manual translation in the output.

# Editable technical chart workflow

## Purpose

Generate, verify and export draw.io / diagrams.net technical diagrams that can be edited further.

## Procedure

1. Determine the chart route
   - Simple diagrams in Markdown that need long-term maintenance, Mermaid is preferred.
   - Use this workflow when you need official icons, swimlanes, complex layouts, layers/tags/metadata, editable PNG/SVG/PDF or `.drawio` sources.
   - When you need fast browser opening or sharing, use [diagram-url.mjs](scripts/diagram-url.mjs) to generate the URL; when you need local auditable delivery, always save the `.drawio` source.
   - If the user already has Mermaid or CSV content, they can use `diagram-url.mjs --create --type mermaid|csv` to import it to diagrams.net; when long-term maintenance or precise shape is required, convert it to XML.
   - If the draw.io MCP App/Tool has been configured on the current host, it can be used as a preview or editing entrance; this skill does not require the installation of MCP server.

# E2E Test Specification

## Purpose

Validate key user journeys with real browsers and uncover integration risks not covered by unit tests.

## Procedure

1. Clarify the key journeys: cross-page processes such as login, purchase, creation, search, permissions, payment, etc. are given priority; if you only choose the test level, do the test hierarchical planning first.
2. New projects will be given priority by Playwright; existing Cypress projects will continue to use Cypress and will not be migrated for the sake of migration.
3. Use Page Object or fixtures to encapsulate login, page locator and shared data, and avoid naked selectors in the spec.
4. Assert that the user can see the results, relying on Locator automatic waiting, network response or visible status, without using fixed sleep.
5. CI must upload HTML report, screenshots, trace or video; Flaky use cases must be isolated, reproduced, marked with sources and associated with issues.
6. When debugging fails, read the trace, console, network and screenshots first, and then change the test; do not misjudge real product defects as flaky.

# Form processing

## Purpose

Manage form status, verification and submission to avoid lags in complex form input.

## Procedure

1. First identify the framework, existing form library of the project, schema verification library, component library and complexity; then introduce special form solutions when there are 10+ fields, dynamic fields, linkage verification, file upload, multi-step process or input lag.
2. Select according to project stack: React can consider React Hook Form + Zod; Vue can consider vee-validate / FormKit + Zod, Yup or Valibot; simple forms can use the framework's native state and basic verification.
3. Use runtime schema or explicit validation functions to guard external input boundaries; TypeScript types can be deduced from the schema, but don’t just write TS types.
4. Clarify default values, field registration, controlled/uncontrolled boundaries and component library adaptation; use `aria-invalid`, `aria-describedby` and `role="alert"` for error prompts.
5. Handle loading, server-side errors, repeated submissions and resets when submitting; use local subscriptions and sub-component isolation to control re-rendering of large forms.

# Image generation and chart workflow

## Purpose

Generate or edit diagrams, visual assets, and image workflows, and perform reviewable self-checks and repair iterations on exported PNGs.

## Procedure

1. Determine product type
   - When accuracy of text, structure, and connections is a priority, use Mermaid, SVG, HTML/CSS, canvas, or a graphics library to generate editable sources and then export as PNG.
   - Use HTML technical diagrams when the user needs a browser-ready single file with dark/light theme support for system blueprints, architecture, deployment topology, agent runtime, memory flow, before-after architecture, workflow, sequence, data-flow, lifecycle, runbook, state-machine, or PII/data-lineage diagrams.
   - Use the compatible HTML `workflow` route when Mermaid is unavailable or browser-specific lane/style delivery is required for process maps, approvals, automation runs, exception paths, and cyclical operating flows that need readable start/end, decision, actor, numbered-step, and summary treatment without requiring diagrams.net.
   - Use themed HTML technical diagrams when a system, agent, memory, data, or tool-call map needs semantic node shapes, flow-aware arrows, and a browser-ready source that can still be exported and QA-checked.
   - Use the interactive live diagram route when the user benefits from watching nodes and edges appear incrementally in a local browser, or when they want to drag, relabel, remove, zoom, and export a quick diagram during the session.

# Implement according to design draft

## Purpose

Based on the design context of design tools (Figma, Sketch, MasterGo, Pixso, Mokou, Mock), high-fidelity implementation of pages or components emphasizes component reuse, design token mapping, accessibility, and production-oriented front-end implementation.

## Supported design tools

| Tools | MCP Integration | How to obtain design data |
| -------- | ------------------------- | ----------------------------------------- |
| Figma | `figma` / `figma-desktop` | API to obtain design structure and variable definitions |
| Sketch | `sketch` | MCP Get screenshot of design selection |
| MasterGo | `mastergo` | API to get DSL structure data |
| Pixso | `pixso` | Local MCP gets frame data and code |

# Migration from traditional front-end to modern framework

Suitable for scenarios where you are gradually migrating JavaScript + jQuery + HTML/CSS multi-page applications (MPA), server-side template rendering projects, or legacy framework code to React, Vue, Next.js, Nuxt, TypeScript, or retaining MPA form but modernizing modules, builds, types, and tests.

## Purpose

Guide the gradual migration of traditional front-end projects to the target modern stack, provide migration strategies, concept mapping, phased steps and implementation constraints to ensure functional equivalence and controllable risks.

## Procedure

1. First identify the target stack, migration boundaries and whether to retain the MPA/server template form.
2. Load [references/migration-strategy-and-mapping.md](references/migration-strategy-and-mapping.md), select a progressive or one-time rewrite strategy, and clarify the mapping of legacy patterns to the target stack.
3. Load [references/migration-execution-checklist.md](references/migration-execution-checklist.md) to complete inventory inventory, dependency analysis, prioritization and phased migration plan.
4. When writing a migration analysis or migration plan report, load [references/migration-report-template.md](references/migration-report-template.md).

# Traditional front-end project specifications (JS + jQuery + HTML)

## Purpose

Safely maintain vanilla JS, jQuery, HTML/CSS and server-side template projects without rewriting the technology stack.

## Procedure

1. First confirm whether this change is to maintain the old stack or migrate; switch to the modern migration workflow when migrating to React/Vue/TypeScript.
2. Use the existing architecture and coding style, prioritize fixing problems, and do not introduce multiple modernizations in one change.
3. JavaScript uses IIFE/namespace to reduce global pollution, and event binding is delegated to reasonable containers first.
4. DOM updates cache selectors, batch operations, and escapes user input; Ajax must handle loading, error, empty status, and prevention of repeated submissions.
5. HTML/CSS maintains semantics, label, alt, BEM/existing naming and low selector depth.
6. Key security checks: `.html()`, `innerHTML`, URL parameter rendering, CSRF token and file upload.

# List virtualization optimization

## Purpose

Only the visible area is rendered through windowing, which solves the problem of excessive DOM and stuck scrolling in large lists.

## Procedure

1. First confirm the list size and bottleneck: 500+ items, scrolling frame drops, too many DOM nodes, or memory surge before introducing virtualization.
2. First follow the existing framework, dependencies and design system constraints of the project, and then select the library according to the scenario: React can consider `react-window` or TanStack Virtual; Vue/Solid/Svelte, dynamic measurement, grid or cross-framework scenarios give priority to TanStack Virtual; the legacy `react-virtualized` is only maintained and not added.
3. Clarify item size, overscan, container height, key, rolling container and resize behavior.
4. Separate data paging and DOM virtualization during infinite scrolling; data acquisition can be combined with the data acquisition workflow.
5. Verify DOM node count, scrolling FPS, keyboard/screen reader experience, and Ctrl+F/SEO limitations.

# Monorepo Project Specifications

For multi-package front-end repositories using pnpm workspace, Turborepo or Nx.

## Purpose

Standardize the directory structure, dependency management, task orchestration and package release process of the Monorepo project to ensure the build efficiency and version consistency of multi-package collaboration.

## Procedure

1. First confirm whether the repository has used pnpm workspace, Turborepo or Nx, and continue to use the existing package naming and task conventions.
2. Place applications in `apps/` and shared libraries, configuration and tools in `packages/` or existing equivalent directories.
3. Internal dependencies use `workspace:*` to drive the build sequence through the dependency graph.
4. Configure cacheable, parallelizable, and incremental root tasks for build, lint, and test, and specify input, output, and environment variables.

# Interactive effects

It is suitable for front-end animation tasks that need to design page transitions, scrolling narratives, component introductions, micro-interactions and feedback rhythms into maintainable, degradable and verifiable forms. Load [motion-patterns.md](references/motion-patterns.md) when a specific implementation pattern is required.

## Purpose

Choose the right animation tools, intensity, and quality gates for your front-end interface.

## Procedure

1. Determine animation responsibilities
   - First write down the user intention of the dynamic effect service: positioning, feedback, level changes, status confirmation, narrative guidance or brand memory.
   - The tool-based interface is restrained by default, and priority is given to ensuring scanning efficiency; the marketing page and work page can increase the rhythm, but cannot block the main information.
   - If animation is merely decorative and does not improve understanding, feedback or brand recognition, it should be deleted or replaced with a static visual treatment.

# Next.js project specifications

For repositories using Next.js 14+ with App Router.

## Purpose

Standardize engineering practices for App Router, SSR/SSG/ISR rendering modes, data acquisition, route layout, middleware and SEO metadata in Next.js 14+ projects to ensure server-side priority, performance optimization and maintainability.

## Procedure

1. First identify whether the target belongs to App Router, layout, server data, middleware, metadata or client interaction.
2. Default server-side components take precedence; use `'use client'` only when browser API, interactive state or event handling is required.
3. Clarify SSR / SSG / ISR / CSR rendering mode and Next fetch/cache strategy.
4. Complete the server-side boundaries of `loading.tsx`, `error.tsx`, `not-found.tsx`, metadata and sensitive logic for routing.

# Nuxt 3 Project Specifications

For repositories using Nuxt 3 + Vue 3 + TypeScript.

## Purpose

Standardize the engineering practices of SSR/SSG rendering mode, combined API, automatic import, data acquisition, routing middleware and module plug-ins in the Nuxt 3 project to ensure conventional development and type safety.

## Procedure

1. First identify whether the target belongs to Nuxt pages/layouts, rendering mode, data acquisition, route middleware, plugin/module or server route.
2. Clarify SSR / SSG / SPA selection to avoid server-side executable code relying on `window` or `document`.
3. For data acquisition, Nuxt’s `useFetch` / `useAsyncData` is used first, and the hydration consistency is checked.
4. Route authentication, redirection and permission issues are aligned with the route protection workflow.

# Front-end performance optimization

## Purpose

Use measurable methods to locate front-end performance bottlenecks, and converge optimization suggestions to the user's main path, build products, and runtime evidence.

## Procedure

1. Lock in experience goals
   - Clarify whether the problem is first screen loading, interaction delay, scrolling lag, memory increase, network waterfall, packet size, or visual stability.
   - Document routes, devices, network conditions, browsers, replication steps, and currently available metrics.
   - When there are no indicators, establish a baseline first and do not directly give generalized suggestions of "optimizing everything".

2. Establish a measurement baseline

# PWA implementation

## Purpose

Make web applications installable, offline and controllable to update.

## Procedure

1. Confirm whether PWA is worth doing: priority is given to mobile/desktop installations, weak network offline, and repeated access scenarios; do not force PWA when it is purely internal backend, has strong real-time streaming media, or only requires ordinary caching.
2. First complete the manifest, icon, theme color and HTML reference; the icon covers at least 192/512, Android needs to be maskable, and iOS needs apple touch icon.
3. Register the Service Worker and design an update prompt; do not forcefully refresh the user page after silently `skipWaiting()`.
4. Use Workbox or framework plug-in to manage precache/runtime cache; sensitive requests such as login, payment, and permission changes must go through the network.
5. Provide offline fallback page and installation prompt UI, and verify initial loading, offline access, update activation, uninstallation and reinstallation.

# React project specifications

Suitable for medium and large module construction, page reconstruction and engineering structure design in React + TypeScript warehouse.

## Purpose

Provide engineering structure, module boundaries and default implementation conventions for React + TypeScript projects to ensure clear architecture and maintainable code.

## Procedure

This skill mainly solves the problem of "how to design and implement" React engineering tasks, without repeating the basic coding bottom line. When handling React engineering tasks, perform them in the following order:

1. Identify the warehouse and have an agreement
   - Directory organization

# Refactoring and cleaning

## Purpose

Identify and clean up unused front-end code under validation protection, reducing technical debt while avoiding accidentally deleting dynamic references, routing entries, configuration files, and runtime conventions.

## Procedure

1. Establish a baseline first: run or confirm the current status of lint, type-check, test, and build.
2. Collect candidates:
   - Prioritize the use of existing tools in the warehouse, such as knip, depcheck, ts-prune, eslint, and TypeScript.
   - When tools are not available, use `rg` to check references, exports, routes, registration points and document entries.
3. Classification by risk:
   - SAFE: test fixtures, unreferenced tool functions, explicitly unexported private components.

# Skill: Behavior-Preserving Refactoring

## Purpose

Restructure live frontend code in small, evidence-backed steps while preserving the behavior users, callers, tests, routes, and integrations can observe.

## Core Contract

Every execution follows these rules:

1. **Behavior Preservation** — pure refactoring intentionally changes structure, not observable behavior.
2. **Green Baseline First** — record available verification before editing.
3. **One Refactoring at a Time** — one primary structural intent per step.
4. **Verify Every Step** — run the narrowest meaningful check immediately after each step.

# API Refactorings

## Overview
Use this family after evidence identifies a fitting structural transformation. Apply one primary technique at a time and verify immediately.

## Procedure
1. Confirm the selected technique and its preconditions in [API Refactorings](references/api-refactorings.md).
2. Record affected behavior and a diff budget.
3. Apply only the selected technique's smallest viable step.
4. Verify the step before composing another transformation.
5. Stop and reassess when public contracts, lifecycle, state identity, or actual scope exceed expectations.

## Quick Reference
The family reference contains 10 canonical techniques with intent, signals, avoid conditions, mechanics, preservation checkpoints, smell links, composition hints, JavaScript/TypeScript notes, React/Vue notes, adaptation guidance, and original frontend examples.

# Refactoring Catalog Selection

## Overview
Use the complete catalog as a decision aid, not as a list of automatic recipes. Select the smallest technique whose preconditions fit the evidence and behavior contract.

## Workflow
1. Locate the standard technique in [the catalog index](references/catalog-index.md).
2. If starting from a smell or symptom, use [the selection guide](references/selection-guide.md) to compare causes and alternatives.
3. If several transformations are needed, use [the composition guide](references/composition-guide.md) to order only the prerequisites that fit the current code.
4. Load the referenced family detail only when the technique is selected.

## Selection Rules
- A smell can have several valid candidates; determine the actual cause first.
- Prefer reversible, local transformations over broad redesign.

# Conditional Logic Refactorings

## Overview
Use this family after evidence identifies a fitting structural transformation. Apply one primary technique at a time and verify immediately.

## Procedure
1. Confirm the selected technique and its preconditions in [Conditional Logic Refactorings](references/conditional-refactorings.md).
2. Record affected behavior and a diff budget.
3. Apply only the selected technique's smallest viable step.
4. Verify the step before composing another transformation.
5. Stop and reassess when public contracts, lifecycle, state identity, or actual scope exceed expectations.

## Quick Reference
The family reference contains 6 canonical techniques with intent, signals, avoid conditions, mechanics, preservation checkpoints, smell links, composition hints, JavaScript/TypeScript notes, React/Vue notes, adaptation guidance, and original frontend examples.

# Data Refactorings

## Overview
Use this family after evidence identifies a fitting structural transformation. Apply one primary technique at a time and verify immediately.

## Procedure
1. Confirm the selected technique and its preconditions in [Data Refactorings](references/data-refactorings.md).
2. Record affected behavior and a diff budget.
3. Apply only the selected technique's smallest viable step.
4. Verify the step before composing another transformation.
5. Stop and reassess when public contracts, lifecycle, state identity, or actual scope exceed expectations.

## Quick Reference
The family reference contains 5 canonical techniques with intent, signals, avoid conditions, mechanics, preservation checkpoints, smell links, composition hints, JavaScript/TypeScript notes, React/Vue notes, adaptation guidance, and original frontend examples.

# Encapsulation Refactorings

## Overview
Use this family after evidence identifies a fitting structural transformation. Apply one primary technique at a time and verify immediately.

## Procedure
1. Confirm the selected technique and its preconditions in [Encapsulation Refactorings](references/encapsulation-refactorings.md).
2. Record affected behavior and a diff budget.
3. Apply only the selected technique's smallest viable step.
4. Verify the step before composing another transformation.
5. Stop and reassess when public contracts, lifecycle, state identity, or actual scope exceed expectations.

## Quick Reference
The family reference contains 9 canonical techniques with intent, signals, avoid conditions, mechanics, preservation checkpoints, smell links, composition hints, JavaScript/TypeScript notes, React/Vue notes, adaptation guidance, and original frontend examples.

# Function Refactorings

## Overview
Use this family after evidence identifies a fitting structural transformation. Apply one primary technique at a time and verify immediately.

## Procedure
1. Confirm the selected technique and its preconditions in [Function Refactorings](references/function-refactorings.md).
2. Record affected behavior and a diff budget.
3. Apply only the selected technique's smallest viable step.
4. Verify the step before composing another transformation.
5. Stop and reassess when public contracts, lifecycle, state identity, or actual scope exceed expectations.

## Quick Reference
The family reference contains 11 canonical techniques with intent, signals, avoid conditions, mechanics, preservation checkpoints, smell links, composition hints, JavaScript/TypeScript notes, React/Vue notes, adaptation guidance, and original frontend examples.