@bovinphang/frontend-craft 2.7.0 → 2.8.0

package/localized/zh-CN/skills/fec-storybook-component-doc/references/story-patterns.md

@@ -0,0 +1,118 @@
+# Storybook 配置与示例
+
+## 初始化
+
+```bash
+npx storybook@latest init
+```
+
+## main.ts
+
+```ts
+import type { StorybookConfig } from "@storybook/react-vite";
+
+const config: StorybookConfig = {
+  stories: ["../src/**/*.stories.@(ts|tsx)"],
+  addons: [
+    "@storybook/addon-links",
+    "@storybook/addon-essentials",
+    "@storybook/addon-interactions",
+    "@storybook/addon-a11y",
+  ],
+  framework: { name: "@storybook/react-vite", options: {} },
+  docs: { autodocs: "tag" },
+};
+
+export default config;
+```
+
+## Story 示例
+
+```tsx
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./Button";
+
+const meta: Meta<typeof Button> = {
+  title: "Components/Button",
+  component: Button,
+  tags: ["autodocs"],
+  argTypes: {
+    variant: { control: "select", options: ["primary", "secondary", "ghost"] },
+    onClick: { action: "clicked" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+export const Primary: Story = {
+  args: { variant: "primary", children: "Primary Button" },
+};
+```
+
+## 装饰器
+
+```tsx
+import type { Preview } from "@storybook/react";
+import { MemoryRouter } from "react-router-dom";
+import { ThemeProvider } from "../src/app/providers";
+
+const preview: Preview = {
+  decorators: [
+    (Story) => <ThemeProvider>{Story()}</ThemeProvider>,
+    (Story) => <MemoryRouter initialEntries={["/"]}>{Story()}</MemoryRouter>,
+  ],
+};
+
+export default preview;
+```
+
+## MDX 文档
+
+```mdx
+import { Meta, Canvas, Controls, Source } from "@storybook/blocks";
+import * as InputStories from "./Input.stories";
+
+<Meta of={InputStories} />
+
+# Input 输入框
+
+用于用户文本输入，支持校验提示、前后缀图标、字数统计等。
+
+### 何时使用
+
+- 单行文本输入
+- 需要实时校验反馈的表单字段
+
+<Canvas of={InputStories.Default} />
+
+### 属性
+
+<Controls />
+
+### 源码
+
+<Source of={InputStories.Default} />
+```
+
+## 交互测试
+
+```tsx
+import { expect, userEvent, within } from "@storybook/test";
+
+export const FormSubmission: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.type(canvas.getByLabelText("用户名"), "admin");
+    await userEvent.click(canvas.getByRole("button", { name: /登录/ }));
+    await expect(canvas.findByText("登录成功")).resolves.toBeInTheDocument();
+  },
+};
+```
+
+## 视觉回归
+
+```bash
+npx chromatic --project-token=<token>
+npx test-storybook
+```

package/localized/zh-CN/skills/fec-svg-animation/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: fec-svg-animation
+description: 用于实现或审查 SVG 动画、路径绘制、图标动效、Logo 动画、插画动效、微交互、CSS/SMIL/Framer Motion/GSAP 选型、动效无障碍或降级行为；中文触发词包括 SVG 动画、路径描边、动效。
+---
+
+# SVG 动画实现
+
+## 用途
+
+为 SVG 图标、插画和数据可视化提供可维护、可访问、性能可控的动画方案。
+
+## 适用场景
+
+- 需要实现 SVG 图标、Logo、插画或路径描边动画。
+- 需要在 React/Vue 组件中接入 Framer Motion、GSAP 或 CSS 动画。
+- 需要根据 `prefers-reduced-motion` 提供动效降级。
+- 不用于复杂 3D/WebGL 场景；此类场景优先使用 Canvas / Three.js workflow。
+
+## 流程
+
+### 1. 选择动画方式
+
+按复杂度和运行时需求选型：
+
+| 场景 | 推荐 |
+| --- | --- |
+| hover/focus、opacity、transform | CSS animation/transition |
+| 路径描边、简单重复动效 | CSS + `stroke-dasharray` |
+| React 组件状态驱动动画 | Framer Motion |
+| 时间轴、复杂编排、滚动触发 | GSAP |
+| 需要保持零依赖的静态 SVG | CSS 或 SMIL |
+
+如果动效跨越页面转场、滚动叙事或复杂组件编排，应先按交互动效 workflow 判断强度、懒加载和 reduced-motion 策略；本 skill 只负责 SVG 图形本身的路径、形变和图标 motion。
+
+### 2. 使用 CSS 实现路径描边
+
+```tsx
+export function CheckmarkIcon() {
+  return (
+    <svg viewBox="0 0 24 24" className="checkmark" aria-hidden="true">
+      <path
+        className="checkmark-path"
+        d="M5 12.5l4.5 4.5L19 7"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+```
+
+```css
+.checkmark-path {
+  stroke-dasharray: 24;
+  stroke-dashoffset: 24;
+  animation: draw-checkmark 420ms ease-out forwards;
+}
+
+@keyframes draw-checkmark {
+  to {
+    stroke-dashoffset: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .checkmark-path {
+    animation: none;
+    stroke-dashoffset: 0;
+  }
+}
+```
+
+### 3. 在 React 中使用 Framer Motion
+
+```tsx
+import { motion, useReducedMotion } from "framer-motion";
+
+export function AnimatedSparkline({ path }: { path: string }) {
+  const reduceMotion = useReducedMotion();
+
+  return (
+    <svg viewBox="0 0 120 40" role="img" aria-label="趋势图">
+      <motion.path
+        d={path}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        initial={reduceMotion ? false : { pathLength: 0, opacity: 0 }}
+        animate={{ pathLength: 1, opacity: 1 }}
+        transition={{ duration: 0.7, ease: "easeOut" }}
+      />
+    </svg>
+  );
+}
+```
+
+### 4. 使用 GSAP 编排复杂时间轴
+
+```tsx
+import { useLayoutEffect, useRef } from "react";
+import gsap from "gsap";
+
+export function LogoReveal() {
+  const rootRef = useRef<SVGSVGElement>(null);
+
+  useLayoutEffect(() => {
+    if (!rootRef.current) return;
+    const ctx = gsap.context(() => {
+      gsap.timeline({ defaults: { ease: "power2.out" } })
+        .from(".logo-mark", { scale: 0.9, opacity: 0, duration: 0.25 })
+        .from(".logo-line", { strokeDashoffset: 80, duration: 0.55 }, "-=0.1");
+    }, rootRef);
+
+    return () => ctx.revert();
+  }, []);
+
+  return (
+    <svg ref={rootRef} viewBox="0 0 120 32" aria-hidden="true">
+      <circle className="logo-mark" cx="16" cy="16" r="10" />
+      <path className="logo-line" d="M36 16h68" stroke="currentColor" />
+    </svg>
+  );
+}
+```
+
+### 5. 控制运行成本
+
+- 大型 SVG 拆成静态底图和少量可动画节点，不要让每个 path 都参与时间轴。
+- 图标库或 Lottie 替代方案必须按需加载，不进入所有页面的基础包。
+- 循环动画只在可见区域运行，页面隐藏或组件卸载时停止。
+- 移动端减少滤镜、mask、clipPath 和大量渐变叠加。
+
+## 约束
+
+- 优先动画 `transform`、`opacity` 和 SVG 路径属性；避免高频修改 layout 相关属性。
+- 交互控件必须保留可见 focus 状态，动画不能替代状态表达。
+- 所有非装饰性 SVG 必须有可访问名称；装饰性 SVG 使用 `aria-hidden="true"`。
+- 默认尊重 `prefers-reduced-motion`，复杂动效必须提供静态或弱动效降级。
+- 不要把大型 SVG 内联到频繁重渲染的组件中；提取为 memoized 组件或外部资源。
+- 不用动画改变可点击区域、阅读顺序或焦点位置。
+- 不让 SVG 滤镜、模糊、mask 或 clipPath 成为移动端掉帧主因；复杂效果需要设备降级。
+
+## 预期输出
+
+产出一个可复用的 SVG 动画组件或样式方案，包含选型理由、动效降级和可访问性处理。验证时检查动画流畅、无布局抖动、键盘与 reduced-motion 场景可用。

package/localized/zh-CN/skills/fec-tailwind-design-system/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: fec-tailwind-design-system
+description: 用于设计、实现或审查 Tailwind CSS 设计系统、Token 映射、主题扩展、工具类治理、组件变体、暗色模式、响应式工具、safelist 或可维护的 class 组合；中文触发词包括 Tailwind、设计 Token、组件变体、暗色模式、class 管理。
+---
+
+# 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 字符串复制到多个页面。
+5. 处理主题和暗色模式：明确 `class`、`data-theme` 或 CSS 变量方案，避免首次渲染闪烁和对比度回归。
+6. 接入响应式：移动优先组织 utility；复杂布局交给响应式布局工作流，不要只靠堆叠断点前缀碰运气。
+7. 验证样式结果：检查 hover、active、focus-visible、disabled、loading、selected、invalid、dark 和不同断点。
+
+## 约束
+
+- 不把 Tailwind class 当作设计系统本身；真正的系统是 token、组件 API、状态矩阵和使用约束。
+- 不为单个页面随意扩展全局 token；新增 token 必须有语义名称和复用场景。
+- 不使用拼接的动态 class 破坏构建扫描；必要时使用 safelist、映射表或 variant 工具。
+- 不在组件外部覆盖基础组件内部结构来实现变体。
+- 不让暗色模式只靠反色；状态色、边框、阴影、图表和图片都要重新检查。
+
+## 预期输出
+
+输出 Tailwind token 映射、主题配置边界、组件 variant 设计、class 复用策略、暗色模式和响应式验证结果。完成后样式应能被项目组件复用、可搜索、可测试，并与设计系统规则一致。

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

@@ -0,0 +1,59 @@
+# Tailwind 系统模式
+
+## Token 映射
+
+优先使用语义化名称：
+
+| 需求 | 推荐 | 避免 |
+| ---- | ---- | ---- |
+| 品牌色 | `brand.600`, `--color-brand-primary` | 到处复制 `blue-600` |
+| 表面层级 | `surface.canvas`, `surface.panel` | 一次性灰色值 |
+| 圆角 | `radius.control`, `radius.panel` | 随意重复的具体值 |
+| 阴影 | `shadow.floating`, `shadow.focus` | 没有状态含义的装饰阴影 |
+
+如果项目已有 CSS 变量，把 Tailwind token 映射到这些变量，而不是重复维护字面量。
+
+## Variant 归属
+
+长 class 组合应收敛到以下位置之一：
+
+- 带 `variant`、`size`、`tone`、`density`、`state` props 的共享组件。
+- 复合组件的 slot 映射表。
+- CVA、tailwind-variants 或本地 `classNames` 映射等类型化 helper。
+- 只在一个模块内复用时，使用局部常量。
+
+不要根据不受控的用户输入拼接 class 名。使用显式映射：
+
+```ts
+const toneClass = {
+  neutral: "bg-slate-100 text-slate-900",
+  danger: "bg-red-600 text-white",
+  success: "bg-emerald-600 text-white",
+} as const;
+```
+
+## 暗色模式
+
+- 优先选择单一的项目级策略：`class`、`data-theme` 或 CSS 变量。
+- 如果应用支持手动切换主题，在 body 绘制前初始化已选主题，避免首屏先亮后暗或先暗后亮的主题闪烁。
+- 在亮色和暗色主题下都测试 disabled、focus、selected、invalid、chart 和 skeleton 状态。
+- 不要把降低透明度作为 disabled 的唯一提示；要保留对比度和可感知性。
+- Tailwind 项目使用 `darkMode: "class"` 或等价配置时，主题切换逻辑应同时维护根节点 class / data attribute，并持久化用户偏好。
+- CSS 变量方案中，Tailwind token 应引用语义变量；不要为亮色和暗色分别散落两套工具类字面量。
+- 在 `<head>` 或框架等价入口中放置极小同步初始化脚本时，只读取本地主题偏好和系统偏好，不执行业务逻辑、不访问服务端数据。
+- 暗色模式需复核图片亮度、阴影层级、表单控件、第三方组件、图表色板和 focus ring；不要只补背景色。
+
+## 响应式工具类
+
+- 默认 class 列表从移动端布局开始。
+- 只有信息架构变化时，才增加更大断点前缀。
+- 重复出现的响应式区块应沉淀为布局组件或 CSS 容器查询，不要反复复制同一串断点。
+- 控件、标签页、看板和数据单元格使用稳定尺寸，避免 hover 和 loading 状态造成布局跳动。
+
+## 评审清单
+
+- Token 值有语义角色，并且没有分叉既有设计规则。
+- 组件 variants 覆盖 loading、disabled、selected、invalid、focus-visible 和暗色模式。
+- 动态 class 可被静态扫描识别，或已安全加入 safelist。
+- Tailwind 工具类没有破坏可访问性、点击目标或 reduced-motion 要求。
+- 最终 UI 已在移动端、平板和桌面宽度检查过。

package/localized/zh-CN/skills/fec-tdd-workflow/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: fec-tdd-workflow
+description: 用于实现新前端行为、修复 bug 或重构可先由测试描述预期行为的逻辑。适用于组件、hooks/composables、工具函数、API clients、路由守卫或用户工作流；中文触发词包括 TDD、测试驱动、先写测试、红绿重构、回归测试。
+---
+
+# 前端 TDD 工作流
+
+## 用途
+
+用“先写失败测试，再实现最小代码，再重构”的节奏交付前端功能，避免只在实现后补覆盖率。
+
+## 流程
+
+1. 识别可观察行为：用户能看到的 UI、组件契约、hook/composable 返回值、路由守卫结果、API client 输出或错误状态。
+2. 先写一个最小失败测试：
+   - 纯逻辑优先单元测试。
+   - 组件交互优先 Testing Library / Vue Test Utils。
+   - 跨页关键流程优先 Playwright / Cypress。
+3. 运行该测试并确认失败原因正确，失败应来自行为尚未实现，而不是语法、导入或测试环境错误。
+4. 写刚好能通过测试的最小实现，不顺手扩大范围。
+5. 重新运行测试，确认变绿。
+6. 在测试保持通过的前提下重构命名、边界和重复逻辑。
+7. 对 bug 修复，保留能复现问题的回归测试。
+8. 每轮只扩大一个可观察行为；新需求、新边界和新异常路径各自进入下一轮。
+
+## 证明式测试模式
+
+修复缺陷时先让测试失败，再让它通过。若无法先失败，说明测试没有覆盖原始问题，需要收窄输入、断言或测试层级。
+
+## 前端测试选择
+
+| Risk | Preferred Test |
+| ---- | -------------- |
+| utils、schema、状态计算 | 单元测试 |
+| hooks / composables | 单元或轻量集成测试 |
+| 组件 props、emits、交互、状态 | 组件测试 |
+| Router、Provider、Store 协作 | 轻量集成测试 |
+| 登录、支付、权限、关键 CRUD | E2E 测试 |
+
+## 约束
+
+- 不为了 TDD 引入项目没有使用且收益不清晰的新测试框架。
+- 不测试实现细节、私有状态或脆弱 DOM 结构。
+- 不把 E2E 当作所有风险的默认答案；优先选择离风险最近的测试层。
+- 如果现有仓库没有测试基础设施，先输出最小测试落地建议，再请求用户确认是否引入。
+- 不在红灯阶段同时重构；先证明问题，再最小修复，再整理结构。
+
+## 预期输出
+
+- 至少一个先失败后通过的测试覆盖新增或修复行为。
+- 实现保持最小范围，重构只在测试通过后进行。
+- 总结运行过的测试命令、覆盖的行为和未覆盖风险。

package/localized/zh-CN/skills/fec-testing-strategy/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: fec-testing-strategy
+description: 用于规划或审查前端测试策略，按风险选择正确测试层级，将覆盖映射到静态检查、单元测试、组件测试、集成测试、E2E、Storybook/视觉回归、a11y、安全、性能或 CI gates。不要用于编写单个组件/E2E 测试或只是运行现有验证命令；中文触发词包括 测试策略、测试分层、测试计划、覆盖矩阵。
+---
+
+# 前端测试策略
+
+## 用途
+
+按“离代码多近 / 覆盖风险层级”选择测试方法，避免把所有风险都塞进组件测试或 E2E。
+
+## 流程
+
+1. 识别改动类型：纯逻辑、UI 组件、跨模块流程、浏览器能力、视觉稳定性、专项质量风险或发布门禁。
+2. 建立测试层级矩阵，至少区分：
+   - 静态检查：TypeScript、ESLint、格式、依赖安全、构建。
+   - 单元测试：utils、hooks/composables、状态逻辑、schema、纯函数。
+   - 组件测试：props/emits、用户交互、loading/error/empty、mock 边界。
+   - 轻量集成测试：表单 + API mock + 路由/Store/Provider 上下文。
+   - E2E：真实浏览器、跨页面关键旅程、鉴权、支付、权限、CI artifacts。
+   - 视觉/交互文档：Storybook interaction、Chromatic、视觉回归基线。
+   - 专项质量：a11y、安全、性能、兼容性。
+3. 按风险分配覆盖：高频核心路径优先 E2E，复杂组件状态优先组件测试，纯逻辑优先单元测试，跨 provider 协作用轻量集成测试。
+4. 用测试金字塔控制维护成本：
+   - 越靠近纯逻辑，测试越多、越快、越稳定。
+   - E2E 只覆盖用户关键旅程和真实浏览器风险，不覆盖每个分支。
+   - 视觉、a11y、安全和性能属于专项质量层，不塞进普通组件测试。
+5. 检查是否已有命令、测试框架、目录约定和 CI 门禁；沿用项目现状，不为策略文档引入不必要工具。
+6. 规划失败证据：每个高风险项要说明失败时如何定位，例如断言、截图、trace、coverage、日志或报告。
+7. 设计测试数据与 mock 策略：共享 fixture 表达业务场景，测试数据 builder 只封装噪声字段，避免每个测试手写随机对象。
+8. 管理 flaky 风险：把时间、网络、动画、随机数、并发和外部服务标为不稳定来源，并指定隔离、重试和证据产物。
+9. 输出可执行的最小测试计划：每层覆盖什么、不覆盖什么、优先级、建议命令和责任 skill。
+
+## 约束
+
+- 不把测试策略写成泛泛的“多写测试”；每个建议必须对应具体风险。
+- 不要求所有项目都补齐完整测试金字塔；按业务风险和团队维护能力裁剪。
+- 不把 E2E 当作单元/组件测试的替代品；不把组件测试当作真实浏览器兼容保证。
+- 不为小改动强制引入新框架；优先复用仓库已有工具和脚本。
+- 不追求没有风险说明的覆盖率数字；覆盖率只能辅助判断，不能替代场景覆盖。
+- 不把随机 fixture、共享全局状态或依赖执行顺序的测试纳入主干门禁。
+
+## 预期输出
+
+输出测试分层建议、风险到测试层的映射、优先级、建议命令、需新增或调整的测试文件范围，以及明确分流到哪些专项 skill 或 agent。

package/localized/zh-CN/skills/fec-typescript-project-standard/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: fec-typescript-project-standard
+description: 用于创建、配置、审查或调试前端应用、库、SDK、CLI、monorepo 包中的 TypeScript 项目规范，包括 tsconfig、strictness、module/moduleResolution、路径别名、project references、声明文件、package exports、公共 API 类型、DTO、高级泛型、判别联合、类型守卫、类型收窄或类型级回归。React/Vue/Next/Nuxt 组件架构优先使用框架项目 skill；中文触发词包括 TypeScript 项目规范、TS 项目规范、TypeScript 类型安全、类型建模、泛型、判别联合、类型收窄、tsconfig、声明文件。
+---
+
+# 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 契约和工程边界。
+
+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。
+
+## 约束
+
+- 不用 `skipLibCheck`、`any`、无守卫非空断言或宽泛 `as` 掩盖真实边界问题。
+- 不在应用代码中依赖发布包私有深层路径。
+- 不把框架目录结构、组件分层、路由组织或状态管理决策放进本流程；这些交给对应框架或专项流程。
+- 不让生成类型、测试类型或 Node-only 类型污染浏览器运行代码。
+- 不发布只能在源码仓库内解析的路径别名、ambient 声明或隐式全局类型。
+
+## 预期输出
+
+输出应包含 TypeScript 上下文判断、关键 `tsconfig`/package 类型入口建议、类型边界方案、声明文件或 public API 风险、验证命令。完成后项目应能独立 typecheck，公开类型可被消费方解析，类型安全问题有明确收窄或建模方案。

package/localized/zh-CN/skills/fec-typescript-project-standard/references/type-safety-patterns.md

@@ -0,0 +1,102 @@
+# 类型安全模式
+
+## 类型边界审查清单
+
+- DTO 应与外部载荷对应，并在 API 边界处进行转换。
+- 领域模型或视图模型使用前端命名和稳定的联合类型。
+- 组件 props 需命名明确，仅在该文件外复用时才导出。
+- 公开函数必须有显式的参数和返回值类型。
+- 外部输入必须从 `unknown` 开始，通过 schema 校验或类型守卫逐步收窄。
+- 配置映射表优先使用 `as const` 和 `satisfies`，避免宽泛断言。
+
+## 使用 `satisfies` 的配置映射表
+
+```ts
+type Tone = "neutral" | "success" | "warning" | "danger";
+
+const STATUS_TONE = {
+  draft: "neutral",
+  paid: "success",
+  overdue: "danger",
+} as const satisfies Record<string, Tone>;
+
+type InvoiceStatus = keyof typeof STATUS_TONE;
+```
+
+这样既保留了字面量值，又验证了映射表符合预期的值域。
+
+## 映射类型用于表单错误
+
+```ts
+type FieldErrors<TValues extends Record<string, unknown>> = {
+  [Key in keyof TValues]?: string;
+};
+
+interface ProfileFormValues {
+  email: string;
+  displayName: string;
+}
+
+type ProfileFormErrors = FieldErrors<ProfileFormValues>;
+```
+
+## 模板字面量类型用于事件命名
+
+```ts
+interface AnalyticsPayloads {
+  checkoutStarted: { cartId: string };
+  checkoutCompleted: { orderId: string };
+}
+
+type AnalyticsEventName = keyof AnalyticsPayloads;
+type AnalyticsHandlerName = `on${Capitalize<string & AnalyticsEventName>}`;
+```
+
+当项目中已有事件命名规范时使用此模式。不要为一次性字符串引入。
+
+## 更安全的泛型组件模式
+
+```tsx
+interface Entity {
+  id: string;
+}
+
+interface EntityPickerProps<TEntity extends Entity> {
+  items: TEntity[];
+  selectedId: string | null;
+  getLabel: (item: TEntity) => string;
+  onSelect: (item: TEntity) => void;
+}
+
+export function EntityPicker<TEntity extends Entity>({
+  items,
+  selectedId,
+  getLabel,
+  onSelect,
+}: EntityPickerProps<TEntity>) {
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>
+          <button
+            aria-pressed={item.id === selectedId}
+            type="button"
+            onClick={() => onSelect(item)}
+          >
+            {getLabel(item)}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## 类型审查反馈
+
+报告类型安全问题时，需包含：
+
+- 过于宽泛、过于狭窄或不合理的类型边界。
+- 尽管通过 TypeScript 但可能在运行时失败的行为。
+- 最小替换类型或守卫方案。
+- 该变更是否需要测试或类型测试。