@bovinphang/frontend-craft 2.5.0 → 2.7.0

package/skills/fec-react-project-standard/references/react-runtime-patterns.md

@@ -0,0 +1,293 @@
+# React runtime patterns
+
+## 常用 UI 与状态模式
+
+以下模式可与本 skill 其他章节（Hooks、状态管理、性能优化、错误处理）对照使用；**按业务复杂度与团队熟悉度选用**，避免为模式而模式。思路参考业界常见的 React 前端模式实践（如组件组合、复合组件、性能与无障碍等）。
+
+### 组合优于继承
+
+- 用**小颗粒子组件** + `children` / 显式 props 拼装界面，而不是在 React 中搭建类继承层次。
+- 示例：`Card` + `CardHeader` + `CardBody`，由使用方组合，而不是一个巨型 `Card` 用大量布尔 props 分支。
+
+### 复合组件（Compound Components）
+
+- 根组件通过 **Context** 向子组件提供内部状态（如当前 Tab、打开/关闭）。
+- 子组件在 `useContext` 为空时**抛错或断言**，明确「必须在 Provider 树内使用」。
+- API 表面保持可读：`<Tabs><TabList><Tab /></TabList></Tabs>`。
+
+### Render Props / 函数子
+
+- 适用：封装**数据获取与三态**（loading / error / data），把**渲染决策**交给父级。
+- 与 **自定义 Hook** 二选一即可：多数场景 `useXxx()` + 普通组件更直观；仅在需要强约束「同层渲染逻辑」时保留 Render Props。
+
+### Context + useReducer
+
+- 适合**中等复杂度、多子树共享**的客户端状态，且更新可归约为明确 `action`。
+- 避免把高频变化的大对象塞进顶层 Context；服务端数据仍优先 **React Query / SWR**。
+- 大型全局业务状态继续用仓库已选的 **Zustand / Redux Toolkit / Jotai**。
+
+### 表单
+
+- 受控字段 + 校验错误对象是一类可行实现；中大型表单优先 **React Hook Form**（或 Formik）+ **Zod**，复杂表单值、DTO 和校验类型契约分流到 `fec-typescript-project-standard`。
+- 避免单组件内巨型 `useState` 表单对象与重复校验逻辑，可拆字段子组件或抽 `useFormSchema`。
+
+### Error Boundary
+
+- **不要**在业务代码中手写 React **类组件**形式的 Error Boundary；统一使用 **`react-error-boundary`**（或团队认可的同类库）在**模块边界**兜底渲染失败（与本章「错误处理」、`error-handling.md` 一致）。
+- 用 `FallbackComponent` 与 `resetErrorBoundary` 提供「重试」；**日志上报**放在库的 **`onError`**（等回调）中，生产代码避免长期依赖 `console.log`（见 TypeScript 规则）。
+
+
+### 动画与过渡
+
+- 列表进出场可用 **Framer Motion** 的 `AnimatePresence` + `key`，或 CSS `transition`；注意减少布局抖动与 `prefers-reduced-motion`（与无障碍策略一致时）。
+
+### 无障碍与焦点
+
+- 自定义下拉、标签页等：**`role` / `aria-*`**、**方向键 / Enter / Escape** 行为与焦点环可见。
+- 弹窗：打开时将焦点移入对话框，关闭时**恢复**触发元素焦点；可用 **`focus-trap-react`** 或类似方案，与 `fec-accessibility-check` skill 互补。
+
+### Next.js 与服务端组件
+
+- **App Router、Server Components、服务端数据获取与缓存**见 **`fec-nextjs-project-standard`**；客户端交互模式仍以本章与 Hooks 规范为准。
+
+---
+
+
+## Hooks 设计模式
+
+### 适合抽为自定义 Hook 的场景
+
+- 数据获取与三态管理
+- 表单状态逻辑
+- 分页、筛选、排序编排
+- 事件监听与副作用清理
+- 可在多个组件复用的交互逻辑
+
+### 推荐原则
+
+- 统一使用 `use` 前缀命名
+- 返回对象而非数组，方便按需解构，增强可读性和扩展性
+- 状态和行为封装在一起
+- Hook 内部处理 `loading / error / data`
+- 对外暴露清晰的最小接口，不泄漏无关内部细节
+
+### 示例
+
+```tsx
+function useUserList(params: QueryParams) {
+  const [data, setData] = useState<User[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetch = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await getUserList(params);
+      setData(res.list);
+    } catch (e) {
+      setError(e as Error);
+    } finally {
+      setLoading(false);
+    }
+  }, [params]);
+
+  useEffect(() => {
+    fetch();
+  }, [fetch]);
+
+  return { data, loading, error, refetch: fetch };
+}
+```
+
+### Hook 使用原则
+
+- `useEffect` 必须有正确依赖和清理逻辑
+- `useMemo` / `useCallback` 不要滥用，只有在稳定引用确实重要时再加
+- 不在条件分支或循环中调用 hooks
+- 已引入 React Query / SWR 时，数据请求优先走这些库，而不是自己重复造一套缓存层
+
+---
+
+## 路由组织
+
+### 推荐方式
+
+- 路由配置集中管理
+- 路径常量化
+- 页面组件按需懒加载
+- 权限控制放在 guard 层，而不是散落在页面组件内
+- 分页、筛选、排序等 URL 驱动状态优先与地址栏同步
+
+### 示例
+
+```tsx
+const routes: RouteObject[] = [
+  {
+    path: "/",
+    element: <MainLayout />,
+    children: [
+      { index: true, element: <DashboardPage /> },
+      { path: "users", element: <UserListPage /> },
+      { path: "users/:id", element: <UserDetailPage /> },
+      { path: "settings", element: <SettingsPage /> },
+    ],
+  },
+  { path: "/login", element: <LoginPage /> },
+  { path: "*", element: <NotFoundPage /> },
+];
+```
+
+```tsx
+const UserListPage = lazy(() => import("@/pages/UserList/UserListPage"));
+
+function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const { isAuthenticated } = useAuth();
+  if (!isAuthenticated) return <Navigate to="/login" replace />;
+  return <>{children}</>;
+}
+```
+
+---
+
+## 状态管理选型
+
+| 状态类型           | 推荐方案                                          |
+| ------------------ | ------------------------------------------------- |
+| 组件内临时 UI 状态 | `useState` / `useReducer`                         |
+| 跨组件共享业务状态 | Zustand / Redux Toolkit / Jotai（按仓库实际选择） |
+| 服务端数据缓存     | React Query / SWR                                 |
+| URL 驱动状态       | 路由参数 / `useSearchParams`                      |
+| 表单状态           | React Hook Form / Formik                          |
+
+### 核心原则
+
+- 就近管理：状态尽量放在最近的公共祖先
+- 单一数据源：同一份数据不要维护多份
+- 派生优于同步：可计算值优先在渲染期计算
+- 服务端数据优先交给请求库管理，不手动塞进全局 store
+- 不要因为“以后可能会用到”就把局部状态提前升级为全局状态
+
+---
+
+## API 层规范
+
+### 设计原则
+
+- 请求基础设施集中在 `services/`
+- 业务 API 按 feature 拆分，而不是全部堆在一个文件
+- 请求参数和响应结果都应有明确类型
+- 认证、错误格式化、通用拦截放在请求层统一处理
+- 页面和组件不要直接散落拼接请求细节
+
+### 示例
+
+```ts
+// services/request.ts
+const request = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE_URL,
+  timeout: 10000,
+});
+
+request.interceptors.response.use(
+  (res) => res.data,
+  (error) => {
+    if (error.response?.status === 401) {
+      redirectToLogin();
+    }
+    return Promise.reject(normalizeError(error));
+  },
+);
+```
+
+```ts
+// features/user/api.ts
+export function getUserList(
+  params: UserQueryParams,
+): Promise<PageResult<User>> {
+  return request.get("/users", { params });
+}
+
+export function updateUser(id: string, data: UpdateUserDTO): Promise<User> {
+  return request.put(`/users/${id}`, data);
+}
+```
+
+---
+
+## 错误处理
+
+### 必须覆盖的状态
+
+- Loading
+- Error
+- Empty
+- Data
+
+### 推荐做法
+
+- 关键功能模块使用 Error Boundary 包裹，避免局部异常导致全页白屏
+- 异步请求失败时必须给用户可见反馈
+- 重要操作提供重试能力
+- 不要吞错，不写空 `catch`
+
+### 示例（`react-error-boundary`，函数式 Fallback）
+
+```tsx
+import { ErrorBoundary } from "react-error-boundary";
+
+function ModuleErrorFallback({
+  resetErrorBoundary,
+}: {
+  resetErrorBoundary: () => void;
+}) {
+  return (
+    <div>
+      模块加载失败
+      <button type="button" onClick={resetErrorBoundary}>
+        重试
+      </button>
+    </div>
+  );
+}
+
+export function UserDashboardSection() {
+  return (
+    <ErrorBoundary FallbackComponent={ModuleErrorFallback}>
+      <UserDashboard />
+    </ErrorBoundary>
+  );
+}
+```
+
+---
+
+## Suspense 与懒加载
+
+适用场景：
+
+- 路由级页面
+- 图表、富文本编辑器、地图、重型表格等大体积组件
+- 初始化成本较高的模块
+
+示例：
+
+```tsx
+const HeavyChart = lazy(() => import("./components/HeavyChart"));
+
+function Dashboard() {
+  return (
+    <Suspense fallback={<ChartSkeleton />}>
+      <HeavyChart data={chartData} />
+    </Suspense>
+  );
+}
+```
+
+建议：
+
+- 路由级优先 `lazy + Suspense`
+- `fallback` 优先使用 Skeleton 或更贴近内容的占位态，而不是纯 spinner
+
+---
+

package/skills/fec-refactor-clean/SKILL.md

@@ -41,8 +41,11 @@ description: Use when safely removing dead frontend code, unused exports, stale
 - 不用“看起来没人用”作为证据；必须有搜索、工具输出、类型错误消失或测试保护。
 - 不把依赖大版本升级伪装成清理；升级风险、release notes 和 lockfile 变更应分流到依赖升级工作流。
 
+## 详细参考
+
+撰写清理报告时，加载 [references/report-template.md](references/report-template.md)。
+
 ## Expected Output
 
 - 清理报告保存为 `reports/refactor-clean-YYYY-MM-DD-HHmmss.md`。
-- 报告包含候选项、风险分类、已清理项、跳过原因、运行命令和剩余风险。
 - 代码清理后相关验证命令通过，或明确说明阻塞原因。

package/skills/fec-refactor-clean/references/report-template.md

@@ -0,0 +1,42 @@
+# 重构清理报告模板
+
+```markdown
+# 重构清理报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 清理范围: 文件 / 模块 / 依赖 / 路由 / 样式
+
+## 基线验证
+
+| 命令 | 清理前状态 | 清理后状态 | 备注 |
+| --- | --- | --- | --- |
+| `npm run lint` | 失败 / 通过 / 未运行 | 失败 / 通过 / 未运行 | ... |
+
+## 候选项与证据
+
+| 候选项 | 证据 | 风险分类 |
+| --- | --- | --- |
+| `path/to/file.ts` | 工具输出 / rg 搜索 / 类型检查 | SAFE / CAUTION / DANGER / UPGRADE |
+
+## 已清理项
+
+- 删除或修改的文件、导出、样式、依赖或配置
+- 每项清理对应的证据
+
+## 跳过原因
+
+- CAUTION / DANGER 项为什么没有自动处理
+- 需要人工确认、运行时验证或专项流程的内容
+
+## 验证命令
+
+- 执行的 lint、type-check、test、build 或手工验证
+- 关键输出摘要
+
+## 剩余风险
+
+- 动态引用、运行时模板、插件元数据或外部入口风险
+- 建议后续清理或依赖升级项
+```
+
+清理完成后，将报告保存到 `reports/refactor-clean-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/skills/fec-responsive-layout/references/responsive-layout-patterns.md

@@ -41,6 +41,14 @@
 - 低优先级元数据移入详情行、抽屉或可展开面板。
 - 小屏仍要保留排序、筛选、分页和选择能力。
 - 虚拟滚动只解决 DOM 数量问题，不能解决信息层级问题。
+- 表格可以局部横向滚动，但页面整体不应出现无意水平溢出。
+
+## 响应式媒体
+
+- 图片和视频要有稳定尺寸、`aspect-ratio` 或容器约束，避免加载后推挤布局。
+- 需要多尺寸资源时使用 `srcset`、`sizes` 或 `<picture>`，不要让移动端下载桌面大图。
+- 非首屏图片默认懒加载；首屏主体图按框架能力设置明确优先级。
+- 媒体裁切必须保留主体信息；不要为了填满卡片裁掉产品、人物、图表关键区域。
 
 ## 触控与视口检查
 
@@ -49,6 +57,8 @@
 - 固定底部栏和操作条必须考虑 `env(safe-area-inset-bottom)`。
 - 对话框和抽屉需要适配虚拟键盘导致的视口变化。
 - 只在 hover 时出现的内容必须提供点击、焦点或常驻可见替代方案。
+- iOS/Android 横竖屏切换后，主操作、焦点位置和滚动容器仍应可达。
+- 需要局部滚动的区域应明确最大高度和滚动边界，避免页面和内部容器互相抢滚动。
 
 ## 验证清单
 
@@ -57,3 +67,4 @@
 - 1024-1440px：内容宽度有约束，扫描路径清晰。
 - 长标签、翻译文本、数字以及 empty/error/loading 状态不会撑坏固定格式控件。
 - 横竖屏切换不会困住焦点或隐藏主操作。
+- 虚拟键盘弹出时，输入框、提交按钮和错误提示不被遮挡。

package/skills/fec-security-review/SKILL.md

@@ -18,10 +18,10 @@ description: Use when reviewing frontend security risks such as XSS, CSRF, sensi
 5. 高危问题标记为阻塞合并；前端校验只能改善体验，不能作为唯一安全边界。
 6. 输出分级安全报告；报告格式见 [references/report-template.md](references/report-template.md)。
 
-## Detailed References
+## 详细参考
 
-- Load [references/security-checklist.md](references/security-checklist.md) for XSS, CSP, sensitive data, CSRF, dependency, and input validation details.
-- Load [references/report-template.md](references/report-template.md) when writing the security review report.
+- 需要 XSS、CSP、敏感数据、CSRF、依赖和输入校验细节时，加载 [references/security-checklist.md](references/security-checklist.md)。
+- 撰写安全审查报告时，加载 [references/report-template.md](references/report-template.md)。
 
 ## Constraints
 

package/skills/fec-source-driven-development/SKILL.md

@@ -20,6 +20,7 @@ description: Use when frontend decisions depend on framework, library, browser,
    - 首选官方文档、规范、源码、release notes、migration guide、类型定义和项目内测试。
    - 第三方文章只能作为线索，不能作为最终依据。
    - 对快速变化的库记录包名、版本、文档日期或页面标题。
+   - 当用户要求从本地知识库、项目资料库或 `knowledge/` 目录回答问题时，先走本地知识检索，不使用网络搜索补事实。
 
 3. 提炼决策
    - 写清当前版本推荐做法、弃用做法、限制条件和迁移注意事项。
@@ -38,6 +39,31 @@ description: Use when frontend decisions depend on framework, library, browser,
 6. 留下轻量决策记录
    - 当结论会影响公共接口、依赖版本、目录规范或团队工作流时，补充 ADR/变更记录或交给文档同步流程。
 
+## Local Knowledge Retrieval
+
+当用户指定本地知识库路径，或默认 `knowledge/` 目录存在时，可用本流程回答资料库问题、抽取证据或辅助决策。
+
+1. 定位根目录
+   - 用户明确指定路径时使用该路径。
+   - 否则检查当前项目下 `knowledge/` 是否存在；不存在时说明未找到默认知识库并请求路径。
+   - 不用文件 glob 判断目录是否存在。
+
+2. 分层导航
+   - 优先读取根目录和子目录中的 `data_structure.md`。
+   - 根据目录说明选择最相关的少量分支，不一次性遍历整个知识库。
+   - 记录候选文件、主题、时间/版本范围和为什么相关。
+
+3. 渐进检索
+   - Markdown、文本、日志：先用关键词搜索，再局部读取命中上下文。
+   - PDF：处理前先确认可用工具和提取路线，优先提取到临时文本后再检索，避免把整份 PDF 打进上下文。
+   - Excel：处理前先确认读取/分析路线，先看工作表、列名和少量样例，再按字段过滤或聚合。
+   - 默认最多 5 轮关键词迭代；每轮根据已找到证据调整同义词、缩写和范围。
+
+4. 回答与溯源
+   - 先给结论，再列文件路径、章节、页码、工作表或行号附近作为依据。
+   - 证据不足时说明查过哪些路径、缺什么信息，以及用户如何缩小范围。
+   - 不把知识库外的网络信息混入答案，除非用户另行要求查外部来源。
+
 ## Source Priority
 
 | Priority | Source | Use |

package/skills/fec-state-management/SKILL.md

@@ -123,7 +123,7 @@ const migrationPlan: StateMigrationItem[] = [
 ];
 ```
 
-## Detailed References
+## 详细参考
 
 需要 Store 形状示例、选择器模式、URL 状态同步、持久化适配器、SSR 边界或审查清单时，加载 [references/state-patterns.md](references/state-patterns.md)。
 

package/skills/fec-storybook-component-doc/SKILL.md

@@ -18,9 +18,9 @@ description: Use when setting up or reviewing Storybook component documentation,
 5. 需要自动化时接入 interaction tests、addon-a11y、Chromatic 或 Storybook Test Runner；这些能力服务于组件文档和设计系统展示，不承接跨页业务旅程。
 6. 设计系统组件应记录 token 来源、Tailwind/class 变体、暗色模式、响应式尺寸和不支持的组合，避免消费者靠猜测拼装。
 
-## Detailed References
+## 详细参考
 
-- Load [references/story-patterns.md](references/story-patterns.md) for `main.ts`, `preview.ts`, stories, decorators, MDX, interaction tests, and visual regression examples.
+- 需要 `main.ts`、`preview.ts`、stories、decorators、MDX、交互测试和视觉回归示例时，加载 [references/story-patterns.md](references/story-patterns.md)。
 
 ## Constraints
 

package/skills/fec-tailwind-design-system/references/tailwind-system-patterns.md

@@ -35,9 +35,13 @@ const toneClass = {
 ## 暗色模式
 
 - 优先选择单一的项目级策略：`class`、`data-theme` 或 CSS 变量。
-- 如果应用支持手动切换主题，在 body 绘制前初始化已选主题。
+- 如果应用支持手动切换主题，在 body 绘制前初始化已选主题，避免首屏先亮后暗或先暗后亮的主题闪烁。
 - 在亮色和暗色主题下都测试 disabled、focus、selected、invalid、chart 和 skeleton 状态。
 - 不要把降低透明度作为 disabled 的唯一提示；要保留对比度和可感知性。
+- Tailwind 项目使用 `darkMode: "class"` 或等价配置时，主题切换逻辑应同时维护根节点 class / data attribute，并持久化用户偏好。
+- CSS 变量方案中，Tailwind token 应引用语义变量；不要为亮色和暗色分别散落两套工具类字面量。
+- 在 `<head>` 或框架等价入口中放置极小同步初始化脚本时，只读取本地主题偏好和系统偏好，不执行业务逻辑、不访问服务端数据。
+- 暗色模式需复核图片亮度、阴影层级、表单控件、第三方组件、图表色板和 focus ring；不要只补背景色。
 
 ## 响应式工具类
 

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

@@ -0,0 +1,54 @@
+---
+name: fec-typescript-project-standard
+description: Use when creating, configuring, reviewing, or debugging TypeScript project standards across frontend apps, libraries, SDKs, CLIs, monorepo packages, tsconfig, strictness, module/moduleResolution, path aliases, project references, declaration files, package exports, public API types, DTOs, advanced generics, discriminated unions, type guards, type narrowing, or type-level regressions. Prefer framework project skills for React/Vue/Next/Nuxt component architecture; Chinese triggers include TypeScript 项目规范, TS 项目规范, TypeScript 类型安全, 类型建模, 泛型, 判别联合, 类型收窄, tsconfig, 声明文件.
+---
+
+# TypeScript 项目规范
+
+## Purpose
+
+统一 TypeScript 层的工程配置、类型边界和发布产物规则。适用于前端应用、组件库、SDK、CLI、monorepo package 和纯 TypeScript 工具库，但不接管 React、Vue、Next.js、Nuxt 或 Vite 的框架架构职责。
+
+## Procedure
+
+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 契约和工程边界。
+
+2. 收敛 `tsconfig`
+   - 默认开启 `strict`，不要为通过构建关闭 `noImplicitAny`、`strictNullChecks` 或 `exactOptionalPropertyTypes` 等关键约束。
+   - 按运行环境选择 `target`、`lib`、`module` 和 `moduleResolution`；浏览器应用、Node 脚本、库包不要共用一份含混配置。
+   - 将基础配置、应用配置、测试配置和构建声明配置拆开，避免测试全局类型污染生产代码。
+   - 路径别名必须同时被 TypeScript、bundler、test runner 和发布产物理解；库包不得发布无法解析的源码别名。
+
+3. 设计类型边界
+   - 外部输入、DTO、领域模型、UI view model、组件 props 和工具函数 API 分层命名。
+   - public API 的参数和返回值显式标注，内部局部变量优先依赖推断。
+   - 外部数据先以 `unknown` 接收，再通过 schema 或 type guard 收窄。
+   - 复杂泛型、判别联合、DTO 映射、类型守卫和类型测试加载 [类型安全参考](references/type-safety.md)；需要高级模式时加载 [类型安全模式](references/type-safety-patterns.md)。
+
+4. 固定发布与声明产物
+   - 库包必须确认 `package.json` 的 `exports`、`types`、`files` 和实际构建产物一致。
+   - 不默认双包发布；只有明确消费方需要时才同时产出 ESM/CJS，并验证类型入口不分叉。
+   - 通过 `tsc --emitDeclarationOnly`、构建工具声明插件或 API extractor 产出 `.d.ts`，并在发布前检查声明文件可被消费方解析。
+   - 不把测试、fixture、内部工具、未稳定类型或私有路径暴露到 package exports。
+
+5. 验证 TypeScript 质量
+   - 优先使用仓库已有脚本，如 `typecheck`、`build`、`test`、`lint` 和 package pack dry-run。
+   - Vite、Next、Nuxt 等构建不等于完整类型检查；CI 必须有独立 typecheck 或等效验证。
+   - 类型改动影响 public API 时补类型测试、编译期断言或消费方 fixture。
+
+## Constraints
+
+- 不用 `skipLibCheck`、`any`、无守卫非空断言或宽泛 `as` 掩盖真实边界问题。
+- 不在应用代码中依赖发布包私有深层路径。
+- 不把框架目录结构、组件分层、路由组织或状态管理决策放进本流程；这些交给对应框架或专项流程。
+- 不让生成类型、测试类型或 Node-only 类型污染浏览器运行代码。
+- 不发布只能在源码仓库内解析的路径别名、ambient 声明或隐式全局类型。
+
+## Expected Output
+
+输出应包含 TypeScript 上下文判断、关键 `tsconfig`/package 类型入口建议、类型边界方案、声明文件或 public API 风险、验证命令。完成后项目应能独立 typecheck，公开类型可被消费方解析，类型安全问题有明确收窄或建模方案。

package/skills/{fec-typescript-type-safety → fec-typescript-project-standard}/references/type-safety-patterns.md

@@ -97,6 +97,6 @@ export function EntityPicker<TEntity extends Entity>({
 报告类型安全问题时，需包含：
 
 - 过于宽泛、过于狭窄或不合理的类型边界。
-- 尽管通过 TypeScript 但可能在运行时失败的行為。
+- 尽管通过 TypeScript 但可能在运行时失败的行为。
 - 最小替换类型或守卫方案。
 - 该变更是否需要测试或类型测试。

package/skills/{fec-typescript-type-safety/SKILL.md → fec-typescript-project-standard/references/type-safety.md}

@@ -1,13 +1,8 @@
----
-name: fec-typescript-type-safety
-description: Use when designing, implementing, or reviewing TypeScript type contracts, advanced generics, discriminated unions, type guards, API DTOs, component props, public utility types, or type-level regressions in frontend projects. Prefer code review for broad PR review; Chinese triggers include TypeScript 类型安全, 类型建模, 泛型, 判别联合, 类型收窄.
----
-
 # TypeScript 类型安全
 
 ## Purpose
 
-为前端代码建立可演进的类型契约，减少 `any`、断言和运行时形状漂移。
+为前端和 TypeScript 工程建立可演进的类型契约，减少 `any`、断言和运行时形状漂移。
 
 ## Procedure
 
@@ -140,10 +135,6 @@ type UserStatus = UserViewModel["status"];
 type _UserStatusTest = Expect<Equal<UserStatus, "active" | "disabled">>;
 ```
 
-## Detailed References
-
-涉及高级泛型约束、映射类型、模板字面量类型、类型测试、DTO 映射或类型审查清单时，加载 [references/type-safety-patterns.md](references/type-safety-patterns.md)。
-
 ## Constraints
 
 - 避免 `any`、无守卫的非空断言和不相关类型之间的强制 `as`。

package/skills/fec-ui-design/SKILL.md

@@ -20,33 +20,44 @@ description: Use when building, reviewing, or improving frontend UI that needs p
    - 判断这是日常高频工具、营销展示、内容阅读、可视化探索、游戏，还是配置/管理后台。
    - 如果已有 Figma、Sketch、MasterGo、Pixso、墨刀、摹客或截图是事实来源，优先还原设计上下文，不自行发明方向。
 
-2. 定义审美主张
+2. 读取设计语境
+   - 在决定布局、色彩、字体或动效前，先写出一行设计读取：页面类型、目标受众、主要任务、品牌约束和可信赖感来源。
+   - 判断当前界面是视觉型网站、作品/品牌展示、产品营销、工具工作区、数据密集界面、移动原生流程，还是设计稿还原任务。
+   - 如果 brief 有明显分歧，例如“极简但强烈实验性”，只问一个会改变方向的问题；否则基于上下文做出明确选择。
+   - 受监管、公共服务、医疗、金融、儿童或强可访问性场景优先稳定、清晰和可恢复，不为审美冒险牺牲可用性。
+
+3. 定义审美主张
    - 写出目标用户、使用场景、可信赖感来源和一个可被记住的视觉锚点。
    - 视觉锚点可以来自信息结构、真实媒体、数据形态、行业材质、字体性格、交互节奏或空间组织，而不是空泛装饰。
    - 表现力必须服务业务语境：工具型界面重效率和稳定，展示型页面重主体识别和记忆点。
-   - 为页面类型设定设计拨盘：信息密度、视觉张力、动效强度、内容说服力和媒体真实性；这些拨盘必须随任务变化，而不是沿用同一套模板。
+   - 为页面类型设定设计拨盘：视觉张力、动效强度、信息密度、媒体真实性和内容说服力；这些拨盘必须随任务变化，而不是沿用同一套模板。
+   - 工具型和数据型界面默认提高信息密度、降低装饰动效；营销、作品集和品牌页可以提高视觉张力，但仍要保证首屏任务、主体和 CTA 可见。
+   - 设计拨盘用于约束实现选择：高视觉张力不等于混乱排版，高动效强度不等于滚动劫持，高媒体真实性不等于堆 stock 氛围图。
 
-3. 生成或读取设计系统
+4. 生成或读取设计系统
    - 若项目还没有设计系统，可运行 `node skills/fec-ui-design/scripts/design-system.mjs "<product audience tone>" --project "<name>"` 生成建议。
    - 若需要跨会话复用，使用 `--persist` 生成 `design-system/<project>/MASTER.md`；页面差异用 `--page <page>` 写入 `pages/<page>.md`。
    - 构建具体页面时先读页面 override，再读 Master；页面规则只覆盖差异，不复制全量设计系统。
 
-4. 建立首屏与视觉层级
+5. 建立首屏与视觉层级
    - 工具型界面：首屏直接呈现核心工作区、列表、表格、画布或编辑器。
    - 落地页：H1 使用品牌、产品、地点、人名或明确品类，价值说明放在辅助文案。
    - 产品/对象页：首屏必须可见真实产品、对象、状态或可检查媒体。
    - 首屏应留下一个明确记忆点，但不能遮挡核心任务、导航和状态反馈。
    - 营销和产品页需要先写清受众、痛点、承诺、证据和行动入口；文案结构服务转化，但不使用夸张、空泛或不可验证的声明。
+   - 视觉型页面的首屏不能只是文字、渐变和装饰物；需要真实产品、人物、空间、品牌应用、数据状态或可检查的生成资产承担主体信息。
+   - 导航在桌面端应保持单行且高度克制；CTA 文案保持短而清楚，桌面端不应换成多行按钮。
 
-5. 组织视觉语言
+6. 组织视觉语言
    - 字体：优先沿用项目字体体系；若任务允许建立新方向，选择能表达产品性格的标题/正文字体组合，并保证可读性。
    - 色彩：明确主色、功能色、中性色和强调色的角色，避免所有元素平均用力。
    - 空间：根据任务选择高密度、留白、非对称、分栏、画布式或编辑器式布局，不套用固定卡片模板。
    - 动效：只为页面入场、层级展开、状态确认、错误反馈和重点引导建立节奏，并尊重 `prefers-reduced-motion`。
    - 媒体：优先使用真实产品、真实状态、真实图表、可检查截图或本地生成资产；不要用模糊氛围图、占位 URL 或无关插画替代主体信息。
    - 图表：先判断数据任务是趋势、比较、构成、分布还是流程，再选择图表，不把所有数据都做成卡片或饼图。
+   - 视觉参考：没有权威设计稿且页面视觉质量是核心目标时，可先生成或收集分区级参考图，再从图中提取布局、层级、色彩和媒体策略；不要把整站压成一个不可读长图。
 
-6. 对齐设计系统、组件与 token
+7. 对齐设计系统、组件与 token
    - 先复用项目已有组件、token、图标库、路由和布局约定。
    - 缺少 token 时集中补齐或明确记录，不要在多个组件里散落硬编码。
    - 复杂 UI 在实现前写出复用组件、新建组件、响应式策略和状态覆盖。
@@ -54,15 +65,18 @@ description: Use when building, reviewing, or improving frontend UI that needs p
    - Tailwind 专项 token、variant、dark mode 和 class 治理分流到 Tailwind 设计系统工作流；跨设备布局、容器查询和触摸目标分流到响应式布局工作流。
    - 组件 API 应区分基础组件、业务组件和页面私有组件；避免让单个 `variant` 同时承担语义、尺寸、密度和权限含义。
 
-7. 打磨几何、文本和状态
+8. 打磨几何、文本和状态
    - 嵌套圆角遵循“外层圆角约等于内层圆角 + 间距”的光学关系。
    - 非对称图标、播放三角、箭头、星标等需要按视觉中心微调。
    - 标题和短文本可使用 `text-wrap: balance` 或 `text-wrap: pretty`。
    - 表格、价格、计数器、计时器使用 `font-variant-numeric: tabular-nums`。
    - 小控件点击区域至少 40x40px，空间允许时优先 44x44px。
    - focus ring 用于键盘定位，hover/active 用于鼠标反馈，disabled 不只靠透明度表达。
+   - 不在连续多个区块重复同一种三卡片、左右交错或大标题加右侧说明段落；每个区块的布局服务该区块的具体信息任务。
+   - Bento 和 feature grid 的格子数量必须由真实内容决定，不用空格子补构图；多格网格至少有明确主次、媒体或状态差异。
+   - 小型 uppercase eyebrow 要克制使用，不能成为每个区块的节奏拐杖。
 
-8. 验证设计结果
+9. 验证设计结果
    - 检查 loading、empty、error、disabled、hover、focus、selected 状态。
    - 在 mobile(375px)、tablet(768px)、desktop(1440px) 检查文案是否溢出或遮挡。
    - 对依赖图片、图表、画布或 3D 的界面，确认资源真实渲染且承担主体信息。
@@ -70,11 +84,14 @@ description: Use when building, reviewing, or improving frontend UI that needs p
    - 检查首屏是否同时具备任务入口、主体识别、可信证据和下一屏内容线索；若只剩装饰，应回到信息架构重做。
    - 对生产级控件补齐 hover、active、focus-visible、disabled、loading、selected、invalid 和 skeleton 状态。
    - 对仪表盘、表格、编辑器和配置台检查扫描路径、密度、固定尺寸和重复使用时的疲劳感。
+   - 对营销页、作品集和品牌页检查首屏是否适配常见小笔记本高度，导航是否单行，CTA 是否对比合格且不换行。
+   - 复核是否存在连续三段以上相同 section 结构、重复 zigzag、重复三卡片、卡片套卡片、假截图或没有主体信息的视觉资产。
 
 ## Constraints
 
 - 不把工具型应用做成营销落地页；首屏应是可用工作区。
 - 不用通用紫色渐变、装饰光斑、堆叠卡片或空泛 hero 作为默认方案。
+- 不用三等分 feature cards、连续 zigzag、重复 eyebrow、假产品截图或不可检查媒体作为默认页面节奏。
 - 不使用无语境默认字体、均匀无重点配色、重复圆角卡片和模板化双栏 hero 来替代真实设计判断。
 - 不在卡片里再套大卡片；页面分区优先用全宽区域或无框布局。
 - 不用可见文案解释控件本该表达的功能，常见动作优先用图标和 tooltip。
@@ -84,6 +101,7 @@ description: Use when building, reviewing, or improving frontend UI that needs p
 - 不用不可检查的远程占位图、通用 stock 氛围图或 lorem 文案作为交付主体；缺素材时明确生成、制作或降级为真实结构化内容。
 - 不让视觉 polish 破坏键盘路径、触摸目标、文本可读性或低端设备性能。
 - 不把 Tailwind、组件库或 Storybook 文档等实现载体当成设计方向本身；它们应承接已经明确的产品语境和 token 边界。
+- 不因参考系统偏好而强制某个框架、图标库、动效库或 CSS 工具；始终优先遵循当前项目依赖和设计系统。
 
 ## Expected Output