@bovinphang/frontend-craft 2.5.0

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

@@ -0,0 +1,37 @@
+---
+name: fec-storybook-component-doc
+description: Use when setting up or reviewing Storybook component documentation, design-system presentation, isolated component state previews, stories, addons, decorators, MDX docs, component-state interaction checks, visual baselines, or Chromatic. For real-browser cross-page journeys or broader coverage planning, choose the matching testing workflow first; Chinese triggers include Storybook, 组件文档, Design System, 视觉回归.
+---
+
+# Storybook 组件文档化
+
+## Purpose
+
+为 UI 组件建立文档化、设计系统展示和隔离状态预览环境；交互与视觉测试只覆盖 Storybook 场景内的组件状态。
+
+## Procedure
+
+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 变体、暗色模式、响应式尺寸和不支持的组合，避免消费者靠猜测拼装。
+
+## 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.
+
+## Constraints
+
+- Story 需随组件 prop 变更同步更新。
+- Provider 依赖必须通过 decorator 补齐。
+- Storybook 构建产物 `storybook-static/` 不应提交到 Git。
+- Storybook 用于开发和组件文档，不替代生产页面 SEO。
+- Storybook 视觉基线用于组件状态；跨页面截图和真实路由流程分流到 E2E workflow。
+- 大型组件库需控制 stories glob 和 addon 开销。
+- 不用 Storybook 隐藏组件 API 问题；若变体组合爆炸，应先收敛组件职责或拆分组件。
+
+## Expected Output
+
+可交互的组件文档和设计系统展示站点，每个组件状态都有隔离预览，Props 表格可生成，关键 Storybook 场景有可选 play 测试或视觉回归基线。

package/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" },
+};
+```
+
+## Decorators
+
+```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} />
+```
+
+## Interaction Test
+
+```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();
+  },
+};
+```
+
+## Visual Regression
+
+```bash
+npx chromatic --project-token=<token>
+npx test-storybook
+```

package/skills/fec-svg-animation/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: fec-svg-animation
+description: Use when implementing or reviewing SVG animation, path drawing, icon motion, logo animation, illustration motion, micro-interactions, CSS/SMIL/Framer Motion/GSAP choices, motion accessibility, or fallback behavior; Chinese triggers include SVG 动画, 路径描边, 动效.
+---
+
+# SVG 动画实现
+
+## Purpose
+
+为 SVG 图标、插画和数据可视化提供可维护、可访问、性能可控的动画方案。
+
+## When to Use
+
+- 需要实现 SVG 图标、Logo、插画或路径描边动画。
+- 需要在 React/Vue 组件中接入 Framer Motion、GSAP 或 CSS 动画。
+- 需要根据 `prefers-reduced-motion` 提供动效降级。
+- 不用于复杂 3D/WebGL 场景；此类场景优先使用 Canvas / Three.js workflow。
+
+## Procedure
+
+### 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 和大量渐变叠加。
+
+## Constraints
+
+- 优先动画 `transform`、`opacity` 和 SVG 路径属性；避免高频修改 layout 相关属性。
+- 交互控件必须保留可见 focus 状态，动画不能替代状态表达。
+- 所有非装饰性 SVG 必须有可访问名称；装饰性 SVG 使用 `aria-hidden="true"`。
+- 默认尊重 `prefers-reduced-motion`，复杂动效必须提供静态或弱动效降级。
+- 不要把大型 SVG 内联到频繁重渲染的组件中；提取为 memoized 组件或外部资源。
+- 不用动画改变可点击区域、阅读顺序或焦点位置。
+- 不让 SVG 滤镜、模糊、mask 或 clipPath 成为移动端掉帧主因；复杂效果需要设备降级。
+
+## Expected Output
+
+产出一个可复用的 SVG 动画组件或样式方案，包含选型理由、动效降级和可访问性处理。验证时检查动画流畅、无布局抖动、键盘与 reduced-motion 场景可用。

package/skills/fec-tailwind-design-system/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: fec-tailwind-design-system
+description: Use when designing, implementing, or reviewing Tailwind CSS design systems, token mapping, theme extension, utility class governance, component variants, dark mode, responsive utilities, safelists, or maintainable class composition; Chinese triggers include Tailwind, 设计 Token, 组件变体, 暗色模式, class 管理.
+---
+
+# Tailwind 设计系统
+
+适用于用 Tailwind CSS 承载产品设计系统、组件变体和主题规则的前端任务。需要具体配置、variant、class 组织和迁移细节时加载 [references/tailwind-system-patterns.md](references/tailwind-system-patterns.md)。
+
+## Purpose
+
+让 Tailwind 项目中的 token、主题、组件变体和响应式样式可维护，而不是把一次性 utility class 散落到业务代码里。
+
+## Procedure
+
+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 和不同断点。
+
+## Constraints
+
+- 不把 Tailwind class 当作设计系统本身；真正的系统是 token、组件 API、状态矩阵和使用约束。
+- 不为单个页面随意扩展全局 token；新增 token 必须有语义名称和复用场景。
+- 不使用拼接的动态 class 破坏构建扫描；必要时使用 safelist、映射表或 variant 工具。
+- 不在组件外部覆盖基础组件内部结构来实现变体。
+- 不让暗色模式只靠反色；状态色、边框、阴影、图表和图片都要重新检查。
+
+## Expected Output
+
+输出 Tailwind token 映射、主题配置边界、组件 variant 设计、class 复用策略、暗色模式和响应式验证结果。完成后样式应能被项目组件复用、可搜索、可测试，并与设计系统规则一致。

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

@@ -0,0 +1,55 @@
+# 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 的唯一提示；要保留对比度和可感知性。
+
+## 响应式工具类
+
+- 默认 class 列表从移动端布局开始。
+- 只有信息架构变化时，才增加更大断点前缀。
+- 重复出现的响应式区块应沉淀为布局组件或 CSS 容器查询，不要反复复制同一串断点。
+- 控件、标签页、看板和数据单元格使用稳定尺寸，避免 hover 和 loading 状态造成布局跳动。
+
+## 评审清单
+
+- Token 值有语义角色，并且没有分叉既有设计规则。
+- 组件 variants 覆盖 loading、disabled、selected、invalid、focus-visible 和暗色模式。
+- 动态 class 可被静态扫描识别，或已安全加入 safelist。
+- Tailwind 工具类没有破坏可访问性、点击目标或 reduced-motion 要求。
+- 最终 UI 已在移动端、平板和桌面宽度检查过。

package/skills/fec-tdd-workflow/SKILL.md

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

package/skills/fec-testing-strategy/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: fec-testing-strategy
+description: Use when planning or reviewing a frontend testing strategy, selecting the right test layer by risk, mapping coverage across static checks, unit tests, component tests, integration tests, E2E, Storybook/visual regression, a11y, security, performance, or CI gates. Do not use to write individual component/E2E tests or merely run existing validation commands; Chinese triggers include 测试策略, 测试分层, 测试计划, 覆盖矩阵.
+---
+
+# 前端测试策略
+
+## Purpose
+
+按“离代码多近 / 覆盖风险层级”选择测试方法，避免把所有风险都塞进组件测试或 E2E。
+
+## Procedure
+
+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。
+
+## Constraints
+
+- 不把测试策略写成泛泛的“多写测试”；每个建议必须对应具体风险。
+- 不要求所有项目都补齐完整测试金字塔；按业务风险和团队维护能力裁剪。
+- 不把 E2E 当作单元/组件测试的替代品；不把组件测试当作真实浏览器兼容保证。
+- 不为小改动强制引入新框架；优先复用仓库已有工具和脚本。
+- 不追求没有风险说明的覆盖率数字；覆盖率只能辅助判断，不能替代场景覆盖。
+- 不把随机 fixture、共享全局状态或依赖执行顺序的测试纳入主干门禁。
+
+## Expected Output
+
+输出测试分层建议、风险到测试层的映射、优先级、建议命令、需新增或调整的测试文件范围，以及明确分流到哪些专项 skill 或 agent。

package/skills/fec-typescript-type-safety/SKILL.md

@@ -0,0 +1,157 @@
+---
+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`、断言和运行时形状漂移。
+
+## Procedure
+
+### 1. 先确定类型边界
+
+把类型分为外部输入、领域模型、UI view model、组件 props、工具函数 API。不要让后端 DTO、表单模型和 UI 展示模型互相冒充。
+
+```ts
+interface UserDto {
+  id: string;
+  display_name: string;
+  status: "ACTIVE" | "DISABLED";
+}
+
+interface UserViewModel {
+  id: string;
+  displayName: string;
+  status: "active" | "disabled";
+}
+
+export function mapUserDto(dto: UserDto): UserViewModel {
+  return {
+    id: dto.id,
+    displayName: dto.display_name,
+    status: dto.status === "ACTIVE" ? "active" : "disabled",
+  };
+}
+```
+
+### 2. 用 `unknown` 和收窄处理不可信数据
+
+外部输入先校验再使用。不要用 `as` 让编译器闭嘴。
+
+```ts
+interface ApiErrorBody {
+  message: string;
+}
+
+function isApiErrorBody(value: unknown): value is ApiErrorBody {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "message" in value &&
+    typeof value.message === "string"
+  );
+}
+
+export function getApiErrorMessage(value: unknown): string {
+  return isApiErrorBody(value) ? value.message : "Unexpected error";
+}
+```
+
+### 3. 用判别联合表达状态机
+
+异步状态、权限分支、支付状态等有限状态，用判别字段让新增分支在编译期暴露。
+
+```ts
+type Loadable<T> =
+  | { state: "idle" }
+  | { state: "loading" }
+  | { state: "success"; data: T }
+  | { state: "error"; error: Error };
+
+function assertNever(value: never): never {
+  throw new Error(`Unhandled state: ${JSON.stringify(value)}`);
+}
+
+export function renderUserState(user: Loadable<{ name: string }>): string {
+  switch (user.state) {
+    case "idle":
+      return "Ready";
+    case "loading":
+      return "Loading";
+    case "success":
+      return user.data.name;
+    case "error":
+      return user.error.message;
+    default:
+      return assertNever(user);
+  }
+}
+```
+
+### 4. 让泛型服务调用方，而不是炫技
+
+泛型应减少重复并保持调用方推断清晰。复杂类型超过阅读成本时，优先拆具名类型。
+
+```ts
+interface SelectOption<TValue extends string | number> {
+  label: string;
+  value: TValue;
+}
+
+interface SelectProps<TValue extends string | number> {
+  value: TValue;
+  options: Array<SelectOption<TValue>>;
+  onChange: (value: TValue) => void;
+}
+
+export function Select<TValue extends string | number>({
+  value,
+  options,
+  onChange,
+}: SelectProps<TValue>) {
+  return (
+    <select value={value} onChange={(event) => onChange(event.target.value as TValue)}>
+      {options.map((option) => (
+        <option key={option.value} value={option.value}>
+          {option.label}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+### 5. 用类型测试保护公共类型
+
+公共工具类型、组件库类型和 SDK 类型，应有轻量类型测试或编译期断言。
+
+```ts
+type Equal<TLeft, TRight> =
+  (<T>() => T extends TLeft ? 1 : 2) extends <T>() => T extends TRight ? 1 : 2
+    ? true
+    : false;
+
+type Expect<T extends true> = T;
+
+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`。
+- 不把大型匿名类型堆在函数参数或 JSX props 上；提取具名类型表达业务含义。
+- 不为简单业务过度设计递归条件类型；类型复杂度应服务可维护性。
+- 公共 API 的输入输出必须显式标注，局部变量可依赖推断。
+- 类型建模不能替代运行时校验；外部数据仍需 schema 或 type guard。
+
+## Expected Output
+
+产出清晰的类型边界、可收窄的数据模型、必要的类型测试和验证命令。评审时应列出类型风险、运行时影响、推荐建模方式和是否需要专项修复。