@bovinphang/frontend-craft 2.5.0

package/skills/fec-motion-interaction/references/motion-patterns.md

@@ -0,0 +1,112 @@
+# 交互动效实现模式
+
+## CSS 微交互
+
+```css
+.action {
+  transition:
+    transform 180ms ease,
+    opacity 180ms ease,
+    background-color 180ms ease;
+}
+
+.action:hover {
+  transform: translateY(-1px);
+}
+
+.action:active {
+  transform: translateY(0) scale(0.98);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .action {
+    transition-duration: 1ms;
+  }
+
+  .action:hover,
+  .action:active {
+    transform: none;
+  }
+}
+```
+
+## Framer Motion 组件入场
+
+```tsx
+import { motion, useReducedMotion } from "framer-motion";
+
+export function MotionPanel({ children }: { children: React.ReactNode }) {
+  const reduceMotion = useReducedMotion();
+
+  return (
+    <motion.section
+      initial={reduceMotion ? false : { opacity: 0, y: 12 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.24, ease: [0.16, 1, 0.3, 1] }}
+    >
+      {children}
+    </motion.section>
+  );
+}
+```
+
+## GSAP 时间轴清理
+
+```tsx
+import { useLayoutEffect, useRef } from "react";
+import gsap from "gsap";
+
+export function RevealTimeline() {
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  useLayoutEffect(() => {
+    if (!rootRef.current) return;
+
+    const context = gsap.context(() => {
+      gsap
+        .timeline({ defaults: { ease: "power2.out" } })
+        .from("[data-title]", { opacity: 0, y: 16, duration: 0.28 })
+        .from(
+          "[data-item]",
+          { opacity: 0, y: 10, stagger: 0.04, duration: 0.2 },
+          "-=0.08",
+        );
+    }, rootRef);
+
+    return () => context.revert();
+  }, []);
+
+  return (
+    <div ref={rootRef}>
+      <h2 data-title>Release health</h2>
+      <div data-item>Build</div>
+      <div data-item>Tests</div>
+      <div data-item>Deploy</div>
+    </div>
+  );
+}
+```
+
+## 重型动效懒加载
+
+```tsx
+import { lazy, Suspense } from "react";
+
+const InteractiveShowcase = lazy(() => import("./InteractiveShowcase"));
+
+export function ShowcaseSlot() {
+  return (
+    <Suspense fallback={<div aria-busy="true" />}>
+      <InteractiveShowcase />
+    </Suspense>
+  );
+}
+```
+
+## 审查清单
+
+- 动画目标能用一句话说明，且服务信息层级或状态反馈。
+- 高吞吐界面不使用滚动劫持或长时间入场遮挡。
+- reduced-motion 下信息仍完整，焦点与阅读顺序不变化。
+- 动画库按需加载，持续动画可暂停或卸载清理。
+- 关键设备上检查掉帧、文字遮挡和首屏 bundle 变化。

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

@@ -0,0 +1,117 @@
+---
+name: fec-nextjs-project-standard
+description: Use when creating or reviewing Next.js 14+ App Router projects, file routes, layouts, server/client component boundaries, SSR/SSG/ISR, streaming, metadata, middleware, server actions, or Next-specific data fetching. For generic client React component architecture, apply the project's React conventions separately; Chinese triggers include Next.js, App Router.
+---
+
+# Next.js 项目规范
+
+适用于使用 Next.js 14+ 与 App Router 的仓库。
+
+## Purpose
+
+规范 Next.js 14+ 项目中 App Router、SSR/SSG/ISR 渲染模式、数据获取、路由布局、中间件和 SEO 元数据的工程实践，确保服务端优先、性能优化和可维护性。
+
+## Procedure
+
+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 和敏感逻辑的服务端边界。
+5. 引入第三方库前检查是否支持 Server Component；浏览器专属、动效、图表、编辑器和 WebGL 库必须放进客户端叶子组件并按需加载。
+6. 客户端组件架构问题分流到 React 项目 workflow。
+
+## 项目结构
+
+```
+src/
+├── app/                        # App Router
+│   ├── layout.tsx              # 根布局
+│   ├── page.tsx                # 首页
+│   ├── loading.tsx              # 全局 loading UI
+│   ├── error.tsx                # 全局错误边界
+│   ├── not-found.tsx           # 404
+│   ├── globals.css
+│   │
+│   ├── (auth)/                 # 路由组
+│   │   ├── login/
+│   │   │   └── page.tsx
+│   │   └── register/
+│   │       └── page.tsx
+│   │
+│   ├── (dashboard)/            # 仪表盘路由组
+│   │   ├── layout.tsx          # 共享布局
+│   │   ├── dashboard/
+│   │   │   └── page.tsx
+│   │   └── users/
+│   │       ├── page.tsx
+│   │       └── [id]/
+│   │           └── page.tsx
+│   │
+│   └── api/                    # API Routes
+│       └── users/
+│           └── route.ts
+│
+├── components/                 # 共享组件
+├── lib/                        # 工具、配置
+├── hooks/
+├── services/
+└── types/
+```
+
+## 渲染模式
+
+| 模式    | 使用场景         | 实现方式                                        |
+| ------- | ---------------- | ----------------------------------------------- |
+| **SSR** | 动态、需实时数据 | 默认，`fetch` 不缓存或 `cache: 'no-store'`      |
+| **SSG** | 静态内容         | `generateStaticParams` + 静态 `fetch`           |
+| **ISR** | 定期更新         | `revalidate` 或 `revalidatePath`                |
+| **CSR** | 客户端交互       | `'use client'` + `useEffect` 或 SWR/React Query |
+
+## 数据获取
+
+- 服务端组件：直接 `async` 或 `fetch`，不暴露 `useEffect`
+- 客户端组件：`useEffect` + `useState`，或 SWR / React Query
+- 优先在服务端获取数据，减少客户端水合
+- 使用 `loading.tsx` 和 Suspense 包裹异步区块，提供流式体验
+
+## 路由与布局
+
+- 路由组 `(auth)` 不改变 URL，只影响布局
+- 动态路由 `[id]` 配合 `generateStaticParams` 做 SSG
+- `layout.tsx` 包裹子路由，共享 UI 与布局
+- `page.tsx` 为叶子路由，不可嵌套
+
+## 中间件
+
+- 放在 `middleware.ts` 根目录
+- 用于鉴权、重定向、rewrite、Header 修改
+- 尽量短小，避免阻塞请求
+
+## 元数据与 SEO
+
+- 使用 `metadata` 或 `generateMetadata` 导出
+- 支持 `title`、`description`、`openGraph`、`twitter` 等
+- 动态路由用 `generateMetadata(params)` 生成
+
+## Constraints
+
+- 服务端组件默认，仅在需要客户端交互时加 `'use client'`
+- 不在服务端组件中直接使用 `useState`、`useEffect`、浏览器 API
+- 敏感逻辑（如鉴权）放在服务端或 API Route，不暴露在客户端
+- 图片使用 `next/image`，字体使用 `next/font`
+- 不把密钥、内部 API 地址或服务端 token 放入 `NEXT_PUBLIC_` 环境变量。
+- 不让大型动效库、3D 场景、富文本编辑器或地图 SDK 进入根布局同步 bundle。
+- 首屏媒体必须有确定尺寸、真实资源和合理 priority；不要用远程占位图撑布局。
+
+## 与客户端 UI 模式的分工
+
+- **服务端**：渲染模式、数据获取与缓存、`loading.tsx` / `error.tsx`、路由与布局等以本 skill 为准。
+- **`'use client'` 组件**：组合与复合组件、表单、客户端状态、列表虚拟化、动效与键盘/焦点等，与纯 React 项目一致，遵循项目中的 React 规则（如 `.claude/rules/fec-react.md`）。
+- **权限与客户端数据**：鉴权、RBAC、redirect、客户端 server state 和缓存失效应按对应专项 workflow 处理；Next 服务端 fetch/cache 仍以本 skill 为准。
+
+## Expected Output
+
+- 页面组件按 App Router 约定组织（`app/` 目录、`page.tsx`、`layout.tsx`、`loading.tsx`、`error.tsx`）
+- 渲染模式选择正确（SSR/SSG/ISR/CSR），数据获取路径清晰
+- 元数据和 SEO 配置完整（title、description、openGraph）
+- 敏感逻辑在服务端，客户端组件仅处理交互

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

@@ -0,0 +1,122 @@
+---
+name: fec-nuxt-project-standard
+description: Use when creating or reviewing Nuxt 3 projects, file routes, pages, layouts, SSR/SSG/SPA behavior, Nuxt data fetching, route middleware, plugins, modules, server routes, or Nuxt-specific Vue 3 conventions. For generic Vue component architecture, apply the project's Vue conventions separately; Chinese triggers include Nuxt, Nuxt 3.
+---
+
+# Nuxt 3 项目规范
+
+适用于使用 Nuxt 3 + Vue 3 + TypeScript 的仓库。
+
+## Purpose
+
+规范 Nuxt 3 项目中 SSR/SSG 渲染模式、组合式 API、自动导入、数据获取、路由中间件和模块插件的工程实践，确保约定式开发和类型安全。
+
+## Procedure
+
+1. 先识别目标属于 Nuxt pages/layouts、渲染模式、数据获取、route middleware、plugin/module 还是 server route。
+2. 明确 SSR / SSG / SPA 选择，避免服务端可执行代码依赖 `window` 或 `document`。
+3. 数据获取优先使用 Nuxt 的 `useFetch` / `useAsyncData`，并检查水合一致性。
+4. 路由鉴权、redirect 和权限问题与路由保护 workflow 对齐。
+5. 通用 Vue 组件架构问题分流到 Vue 项目 workflow。
+
+## 项目结构
+
+```
+├── app.vue                    # 根组件
+├── nuxt.config.ts              # Nuxt 配置
+│
+├── pages/                     # 基于文件的路由
+│   ├── index.vue               # /
+│   ├── login.vue               # /login
+│   ├── dashboard/
+│   │   ├── index.vue           # /dashboard
+│   │   └── users/
+│   │       ├── index.vue       # /dashboard/users
+│   │       └── [id].vue       # /dashboard/users/:id
+│   └── [...slug].vue          # 捕获所有
+│
+├── layouts/                   # 布局
+│   ├── default.vue
+│   └── auth.vue
+│
+├── components/                # 自动导入组件
+│   ├── Button/
+│   │   └── Button.vue
+│   └── AppHeader.vue
+│
+├── composables/               # 组合式函数（自动导入）
+│   ├── useAuth.ts
+│   └── useFetch.ts
+│
+├── server/                    # 服务端 API
+│   ├── api/                   # API 路由
+│   │   └── users/
+│   │       └── index.get.ts
+│   ├── middleware/            # 服务端中间件
+│   └── utils/                 # 服务端工具
+│
+├── plugins/                   # 插件
+│   └── i18n.client.ts
+│
+├── middleware/                # 路由中间件
+│   └── auth.ts
+│
+├── public/                    # 静态资源
+├── assets/                    # 需构建的资源
+└── types/                     # 类型定义
+```
+
+## 渲染模式
+
+| 模式    | 配置            | 说明           |
+| ------- | --------------- | -------------- |
+| **SSR** | 默认            | `ssr: true`    |
+| **SSG** | `nuxt generate` | 预渲染所有页面 |
+| **SPA** | `ssr: false`    | 纯客户端渲染   |
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  ssr: true, // 或 false
+});
+```
+
+## 数据获取
+
+- `useFetch` / `useAsyncData`：服务端 + 客户端，自动去重
+- `$fetch`：直接请求，适合服务端或一次性调用
+- `useLazyAsyncData`：不阻塞导航，适合非首屏
+- 避免在 `setup` 顶层混用同步/异步逻辑导致水合不匹配
+
+## 路由与布局
+
+- `pages/` 下文件自动生成路由
+- 动态路由：`[id].vue`、`[...slug].vue`
+- 布局：`layout` 选项或 `layouts/default.vue` 默认
+- 嵌套路由：`pages/parent/child.vue` 需配合 `NuxtPage`
+
+## 中间件
+
+- `middleware/` 下文件自动注册
+- 页面级：`definePageMeta({ middleware: ['auth'] })`
+- 全局：`nuxt.config.ts` 的 `router.middleware`
+- 服务端中间件：`server/middleware/`
+
+## 插件与模块
+
+- 插件：`plugins/*.ts`，支持 `.client`、`.server` 后缀
+- 模块：`modules/` 或 `node_modules`，在 `nuxt.config` 中 `modules: []`
+
+## Constraints
+
+- 服务端可访问的代码不要依赖 `window`、`document`
+- 使用 `useState` 共享状态时注意 SSR 序列化
+- 图片使用 `NuxtImg`，链接使用 `NuxtLink`
+- 避免在 `setup` 顶层使用 `await` 导致阻塞，优先用 `useAsyncData` / `useFetch`
+
+## Expected Output
+
+- 页面按 `pages/` 约定式路由组织，动态路由正确配置
+- 渲染模式（SSR/SSG/SPA）选择正确，`nuxt.config.ts` 配置清晰
+- 数据获取使用 `useFetch` / `useAsyncData`，自动去重和水合
+- Composables 和组件自动导入正确，服务端/客户端边界清晰

package/skills/fec-performance-optimization/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: fec-performance-optimization
+description: Use when diagnosing or improving frontend performance, Core Web Vitals, bundle size, runtime rendering cost, network waterfalls, memory leaks, long tasks, Lighthouse findings, or performance budgets; Chinese triggers include 性能优化, 页面卡顿, 首屏慢, 包体积, Web Vitals.
+---
+
+# 前端性能优化
+
+## Purpose
+
+用可度量的方式定位前端性能瓶颈，并把优化建议收敛到用户主路径、构建产物和运行时证据。
+
+## Procedure
+
+1. 锁定体验目标
+   - 明确问题属于首屏加载、交互延迟、滚动卡顿、内存上涨、网络瀑布、包体积，还是视觉稳定性。
+   - 记录路由、设备、网络条件、浏览器、复现步骤和当前可用指标。
+   - 没有指标时先建立基线，不直接给出“优化一切”的泛化建议。
+
+2. 建立度量基线
+   - 读取项目脚本、构建配置、依赖和已有性能报告。
+   - 对页面体验优先使用 Lighthouse、Performance trace、React Profiler、Vue Devtools、Memory snapshot 或 RUM 数据。
+   - 对包体优先看构建产物、source map、依赖重复、首屏 chunk 和动态 import 边界。
+   - 对运行时卡顿优先看长任务、重复渲染、昂贵计算、同步循环、布局抖动和大列表。
+
+3. 分层定位
+   - 加载层：关键 CSS、字体、图片、脚本阻塞、预加载和缓存。
+   - 渲染层：不稳定 key、过宽 Context、无意义 effect、重复计算、组件树过大。
+   - 数据层：串行请求、重复请求、过大 payload、缺少分页或缓存策略。
+   - 主线程：JSON/CSV 解析、图片处理、复杂排序过滤、同步压缩和大对象深拷贝。
+   - 资源层：事件监听、定时器、订阅、WebGL/Canvas 资源和对象 URL 未释放。
+
+4. 形成优化方案
+   - 每个建议必须绑定位置、影响、改法和验证方式。
+   - 优先处理高频主路径和 P95 体验；低频后台任务不抢占首屏预算。
+   - 先做低风险高收益改动，如懒加载、去重、缓存、尺寸预留、虚拟列表、稳定引用和释放资源。
+   - 对会牺牲可维护性的技巧，必须说明收益证据和替代方案。
+
+5. 验证回归
+   - 重新运行受影响构建、测试和性能采集命令。
+   - 对比优化前后指标或产物体积。
+   - 确认 loading、empty、error、offline、reduced-motion 和移动端状态未被优化破坏。
+
+## Budgets
+
+| Area | Default Target | Notes |
+| ---- | -------------- | ----- |
+| LCP | 约 2.5s 内 | 以核心页面、目标地区网络和真实设备为准 |
+| CLS | 低于 0.1 | 媒体、广告、异步内容需要预留空间 |
+| INP | 约 200ms 内 | 优先拆分长任务和降低交互路径重渲染 |
+| Initial JS | 遵循项目预算 | 没有预算时先报告当前 gzip / brotli 体积 |
+| Main thread | 避免连续长任务 | 大计算考虑分片、缓存或 Worker |
+
+## Checks
+
+- 首屏资源是否包含非首屏组件、图表、编辑器、地图或全量图标库。
+- 图片是否有明确尺寸、合适格式、懒加载和首屏优先级。
+- 列表、表格、时间线是否需要虚拟化或分页。
+- 搜索、筛选、排序是否在热路径重复 O(n*m) 扫描。
+- 请求是否可并行、可缓存、可取消、可复用。
+- 监听、订阅、定时器、AbortController、Object URL、Canvas/WebGL 资源是否对称清理。
+
+## Constraints
+
+- 不做没有目标和证据的过早优化。
+- 不靠关闭功能、删除状态反馈或降低可访问性来换性能分数。
+- 不为一次 Lighthouse 分数牺牲真实用户主路径。
+- 不引入大型新依赖解决小问题；先利用项目已有工具和浏览器能力。
+- 不把后端、网络和浏览器侧问题混为一谈；前端能验证的部分要单独列证据。
+
+## Expected Output
+
+输出性能分析报告，包含基线、指标或观察证据、瓶颈位置、优先级、改法、验证命令和剩余风险。报告保存为 `reports/performance-review-YYYY-MM-DD-HHmmss.md`。

package/skills/fec-pwa-implementation/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: fec-pwa-implementation
+description: Use when adding or reviewing Progressive Web App capabilities such as installability, manifest metadata, Service Worker registration, Workbox caching, offline fallback, app update prompts, maskable icons, or iOS PWA compatibility. Do not use for general API caching or non-installable performance tuning; Chinese triggers include PWA, 离线, Service Worker.
+---
+
+# PWA 实现
+
+## Purpose
+
+让 Web 应用具备可安装、离线兜底和可控更新能力。
+
+## Procedure
+
+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，并验证首次加载、离线访问、更新激活、卸载重装。
+
+## Detailed References
+
+- Load [references/manifest-and-icons.md](references/manifest-and-icons.md) for manifest fields, HTML links, icon requirements, screenshots, and iOS notes.
+- Load [references/service-worker-workbox.md](references/service-worker-workbox.md) for Service Worker registration, Workbox strategies, Vite integration, offline fallback, and update flow.
+
+## Constraints
+
+- Service Worker 仅在 HTTPS 下工作（localhost 除外）。
+- 缓存策略必须区分页面、静态资源、API 与敏感操作；不要把登录、支付、权限接口缓存起来。
+- Service Worker 更新有生命周期延迟；用户可见刷新提示优先于强制刷新。
+- iOS PWA 能力弱于 Android，安装、推送和生命周期都要单独验证。
+- 缓存有配额和逐出机制，必须设置 max entries / max age。
+
+## Expected Output
+
+产出可安装的 Web 应用、离线 fallback、可见更新提示和明确缓存策略。验证 Lighthouse PWA、DevTools Application 面板、离线模式、更新发布和移动端安装流程。
+

package/skills/fec-pwa-implementation/references/manifest-and-icons.md

@@ -0,0 +1,53 @@
+# Manifest、图标与安装入口
+
+## Manifest 示例
+
+```json
+{
+  "name": "我的应用",
+  "short_name": "应用",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#0052cc",
+  "description": "应用描述",
+  "icons": [
+    {
+      "src": "/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any maskable"
+    },
+    {
+      "src": "/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any maskable"
+    }
+  ],
+  "screenshots": [
+    {
+      "src": "/screenshot-desktop.png",
+      "sizes": "1280x720",
+      "type": "image/png",
+      "form_factor": "wide"
+    }
+  ]
+}
+```
+
+## HTML 引用
+
+```html
+<link rel="manifest" href="/manifest.json" />
+<meta name="theme-color" content="#0052cc" />
+<link rel="apple-touch-icon" href="/icon-192.png" />
+```
+
+## 检查要点
+
+- `display: "standalone"` 才有接近原生应用的启动体验。
+- `purpose: "any maskable"` 避免 Android 自适应图标被裁剪。
+- `start_url` 应指向登录后或游客可安全进入的入口。
+- `screenshots` 会影响安装对话框质量。
+- iOS 仍依赖 `apple-touch-icon`，安装提示也通常需要用户手动完成。

package/skills/fec-pwa-implementation/references/service-worker-workbox.md

@@ -0,0 +1,68 @@
+# Service Worker、Workbox 与更新流
+
+## 注册 Service Worker
+
+```ts
+export function registerServiceWorker() {
+  if (!("serviceWorker" in navigator)) return;
+
+  window.addEventListener("load", async () => {
+    const registration = await navigator.serviceWorker.register("/sw.js", {
+      scope: "/",
+    });
+
+    registration.addEventListener("updatefound", () => {
+      const nextWorker = registration.installing;
+      nextWorker?.addEventListener("statechange", () => {
+        if (nextWorker.state === "installed" && navigator.serviceWorker.controller) {
+          showUpdatePrompt();
+        }
+      });
+    });
+  });
+}
+```
+
+## 缓存策略
+
+| 策略 | 适用 | 注意 |
+| --- | --- | --- |
+| `CacheFirst` | 带 hash 的图片、字体、CSS/JS | 必须设置过期策略 |
+| `NetworkFirst` | 页面导航、低风险 GET API | 网络失败才降级缓存 |
+| `StaleWhileRevalidate` | 字体、头像、低风险静态数据 | 用户会先看到旧数据 |
+| `NetworkOnly` | 登录、支付、权限、写操作 | 不进入 SW 缓存 |
+
+## Vite 集成
+
+```ts
+import { VitePWA } from "vite-plugin-pwa";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    VitePWA({
+      registerType: "prompt",
+      injectRegister: "auto",
+      workbox: {
+        globPatterns: ["**/*.{js,css,html,ico,png,svg,woff2}"],
+        runtimeCaching: [
+          {
+            urlPattern: /\.(?:png|jpg|jpeg|svg|gif|webp)$/,
+            handler: "CacheFirst",
+            options: {
+              cacheName: "images",
+              expiration: { maxEntries: 100, maxAgeSeconds: 30 * 24 * 60 * 60 },
+            },
+          },
+        ],
+      },
+    }),
+  ],
+});
+```
+
+## 离线与更新
+
+- 为未缓存页面准备 `/offline.html`，不要让用户只看到浏览器错误页。
+- 更新提示应说明“新版本已可用”，由用户确认刷新。
+- 调试时使用 DevTools Application 面板，必要时清理旧 Service Worker 和 Cache Storage。

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

@@ -0,0 +1,83 @@
+---
+name: fec-react-project-standard
+description: Use when designing or reviewing React + TypeScript project structure, feature/module boundaries, component architecture, hooks organization, routing composition, state/API/error/styling defaults, or repository-wide React conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include React 项目规范, React 组件架构.
+---
+
+# React 项目规范
+
+适用于 React + TypeScript 仓库中的中大型模块建设、页面重构和工程结构设计。
+
+## Purpose
+
+为 React + TypeScript 项目提供工程结构、模块边界和默认实现约定，确保架构清晰、代码可维护。
+
+## Procedure
+
+本 skill 主要解决 React 工程任务“如何设计和落地”的问题，不重复声明基础编码底线。处理 React 工程化任务时，按以下顺序执行：
+
+1. 识别仓库已有约定
+   - 目录组织方式
+   - 样式体系
+   - 状态管理方案
+   - 请求封装方式
+   - 测试框架
+   - UI 组件库 / 设计系统
+
+2. 判断目标属于哪一层
+   - 路由页面
+   - 页面私有组件
+   - feature 业务模块
+   - 全局通用组件
+   - hooks / services / stores / utils
+
+3. 设计边界后再落代码
+   - 哪些逻辑属于页面编排
+   - 哪些逻辑属于 feature
+   - 哪些逻辑应下沉为通用能力
+   - 哪些状态应本地管理，哪些应交给 store / query / URL
+   - 状态归属复杂时使用状态管理流程先做状态清单
+   - DTO、公共 props 或泛型组件复杂时使用 TypeScript 类型安全流程先收敛类型契约
+
+4. 输出时补齐关键质量项
+   - loading / error / empty / data 状态
+   - 错误处理与重试
+   - 类型约束
+   - 关键测试入口
+   - 必要的专项 skill 分流
+   - 依赖是否已存在于 `package.json`，缺失时先给安装命令再使用
+   - 重型 UI 能力（动效、图表、3D、编辑器、地图）是否隔离为 leaf component 并按需加载
+   - 图片、视频、字体等资源是否本地化、可缓存，并避免占位 URL 进入交付
+   - 页面级 Error Boundary、模块级 fallback、API 错误映射和用户可恢复动作是否一致
+   - Tailwind token/variant 或响应式布局需求是否应分流到对应专项 skill
+
+## Detailed References
+
+需要具体 React 项目结构、组件模式、Hooks、路由、状态归属、API 层形状、错误处理、样式默认值、TypeScript 约定或审查清单时，加载 [references/react-project-details.md](references/react-project-details.md)。
+
+## Constraints
+
+- 默认遵守仓库现有全局规则和 React rule
+- 若仓库已有明确目录结构、样式体系、状态管理或请求封装，优先沿用仓库约定
+- 组件文件规模宜约 **300 行**内；逾 **500 行**或复杂度过高须拆分子组件、Hooks、utils、类型
+- 禁止新增类组件（Error Boundary 用 `react-error-boundary` 等库）
+- 禁止绕过模块出口，从 feature 深层路径导入
+- 不要用 `useEffect + setState` 模拟本可直接计算的派生值
+- 避免 prop drilling 过深却不考虑组合或局部封装
+- 不在通用页面组件里同步引入 GSAP、Three.js、Lottie、富文本编辑器或地图 SDK；需要时用动态导入、路由级分包或叶子组件隔离。
+- 不在 React 组件中散落裸 `fetch`、API URL、token refresh 或上传流程；跨边界请求应收敛到 API 集成层。
+- 不用 Error Boundary 处理普通 API 失败；请求错误应优先落到 loading/error/empty/data 状态和可恢复操作。
+
+## Expected Output
+
+- 组件边界清晰，pages/features/components 分层明确
+- Props 类型完整且明确，无 `any` 滥用
+- 可复用逻辑已提取为 hooks，loading/error/empty/data 状态齐全
+- API 层具备类型约束和统一错误处理，状态管理符合就近原则
+- URL 状态、服务端状态、表单状态和全局客户端状态边界明确
+- 关键行为有测试覆盖，关键模块已用 `react-error-boundary` 包裹
+- 超长列表已评估虚拟化，弹窗/复合组件具备键盘与焦点支持
+- 先尊重仓库现状，再给推荐结构
+- 给出必要的文件划分建议
+- 必要时说明为什么这样分层
+- 对新增模块，优先输出最小可落地结构，而不是一次性过度设计
+- 对重构任务，优先保证可迁移性和风险可控