@umacloud/knowledge 1.0.1

package/frontend/01-standards/accessibility-standard.md

@@ -0,0 +1,74 @@
+---
+id: accessibility-standard
+title: 无障碍标准（a11y · 商业级 · WCAG）
+domain: frontend
+category: 01-standards
+difficulty: intermediate
+tags: [无障碍, accessibility, a11y, wcag, aria, 键盘, 屏幕阅读器, 对比度, 焦点, 语义化, 商业级]
+quality_score: 92
+last_updated: 2026-06-19
+---
+
+# 无障碍标准（a11y · 商业级 · WCAG）
+
+> 无障碍不是可选项——它是商业产品的法律合规要求（ADA/欧盟无障碍法案/信通院）与用户覆盖问题。目标对齐 **WCAG 2.1 AA**。AI 生成的 UI 常忽略 a11y，必须显式要求。
+
+## 1. 语义化 HTML（地基）
+
+- 用**语义标签**：`<button>` `<a>` `<nav>` `<main>` `<header>` `<h1-h6>` `<label>` `<table>`，而不是一堆 `<div onClick>`。
+- 标题层级正确（一个 `<h1>`，逐级 h2/h3，不跳级、不为样式滥用）。
+- 列表用 `<ul>/<ol>`，表格数据用 `<table>` + `<th scope>`。
+- 用语义元素就自带键盘/焦点/角色，少写 ARIA。
+
+## 2. 键盘可达
+
+- **所有交互都能纯键盘完成**：Tab 顺序合理、可聚焦、可 Enter/Space 触发。
+- 焦点**可见**（清晰 focus ring，不要 `outline:none` 不补替代）。
+- 自定义控件（下拉/弹窗/标签页）实现对应键盘交互（方向键/Esc 关闭/焦点陷阱）。
+- 跳过导航链接（skip to content）便于键盘/屏读用户。
+
+## 3. ARIA（语义不够时才补，别滥用）
+
+- 优先语义 HTML；不得已才用 ARIA role/属性。
+- 表单错误 `aria-invalid` + `aria-describedby` 关联错误文本；动态更新用 `aria-live`/`role="alert"`。
+- 弹窗 `role="dialog"` + `aria-modal` + 焦点管理（打开聚焦、关闭归还、焦点陷阱）。
+- 图标按钮要有 `aria-label`；纯装饰图标 `aria-hidden`。
+- **错误 ARIA 比没有更糟**——不确定就用语义 HTML。
+
+## 4. 视觉与对比
+
+- 文本对比度 ≥ **4.5:1**（大字 3:1）；UI 组件/状态对比 ≥ 3:1。
+- **不只靠颜色**传达信息（错误/状态加图标/文本，照顾色盲）。
+- 支持放大到 200% 不破版；尊重 `prefers-reduced-motion`（减少动画）。
+- 触控目标足够大（≥44px）。
+
+## 5. 图片与媒体
+
+- 图片有 `alt`（装饰图 `alt=""`）；复杂图表有文字说明。
+- 视频有字幕、音频有文字稿（如适用）。
+
+## 6. 表单 a11y
+
+- 每个输入关联 `<label>`（不要只用 placeholder 当标签）。
+- 必填/格式要求明确告知；错误可被屏读播报并定位。
+- 分组用 `<fieldset>/<legend>`。
+
+## 7. 反模式（出现即不合格）
+
+- `<div onClick>` 当按钮（不可键盘、无角色）；`outline:none` 去掉焦点环不补。
+- 只用颜色表达错误/状态；对比度不达标。
+- placeholder 当 label；图片无 alt；图标按钮无 label。
+- 弹窗无焦点管理；自定义控件不可键盘操作。
+- 滥用/错误 ARIA。
+
+## 8. 最低交付 checklist
+
+- [ ] 语义化 HTML（button/a/nav/label/标题层级）；少 div onClick。
+- [ ] 全键盘可达 + 可见焦点 + 弹窗焦点管理 + skip link。
+- [ ] 表单 label 关联、错误 aria-invalid/live、图标按钮 aria-label、装饰 aria-hidden。
+- [ ] 对比度 ≥4.5:1、不只靠颜色、支持 200% 缩放、尊重 reduced-motion、触控≥44px。
+- [ ] 图片 alt、复杂内容文字替代。
+- [ ] 用 axe/Lighthouse 自测 a11y。
+
+---
+**参考**：WCAG 2.1 AA、WAI-ARIA Authoring Practices、MDN 无障碍、axe-core/Lighthouse 审计。

package/frontend/01-standards/admin-dashboard-and-crud.md

@@ -0,0 +1,72 @@
+---
+id: admin-dashboard-and-crud
+title: 后台管理与 CRUD 系统标准（商业级必读）
+domain: frontend
+category: 01-standards
+difficulty: intermediate
+tags: [后台, admin, 管理系统, crud, 数据表格, 列表, 过滤, 批量操作, rbac, 权限, 审计, 导出, 表单, 商业级]
+quality_score: 93
+last_updated: 2026-06-19
+---
+
+# 后台管理与 CRUD 系统标准（商业级必读）
+
+> 绝大多数 B2B/SaaS 都有后台管理系统。它看似简单(增删改查)，但商业级要求数据表格、批量操作、权限、审计都做到位——纯底座常做成"能用但很糙"的管理台。
+
+## 1. 数据表格（列表页核心）
+
+- **服务端分页 + 排序 + 过滤**（数据量大不能前端全量）；分页/过滤参数走后端，列表接口有上限。
+- 列可配置：显隐、排序、固定列、列宽；表头排序、多条件筛选（含日期范围、状态、关键词）。
+- **批量操作**：多选 + 批量删除/导出/改状态，带二次确认与进度；操作幂等。
+- 行内操作（编辑/删除/查看）+ 详情抽屉/页；空态/加载态(骨架)/错误态。
+- 大数据用虚拟滚动；导出大数据走后台异步任务(见后台任务标准)生成下载。
+
+## 2. 表单（增改）
+
+- 遵循表单与校验标准（受控/schema/前后端双校验/字段级错误/防重复提交）。
+- 复杂表单分步/分组；关联选择(异步搜索下拉)；草稿保存；离开未保存提醒。
+- 创建/编辑复用表单组件；提交成功反馈 + 列表刷新。
+
+## 3. 权限（RBAC，后台必须）
+
+- **基于角色的访问控制**：用户-角色-权限；菜单/页面/按钮/数据级权限。
+- **前端隐藏 + 后端强制**：前端按权限隐藏入口提升体验，但**后端必须再校验**(对象级授权，防越权)，绝不只靠前端隐藏。
+- 数据范围权限（只能看/改自己部门/自己的数据）；超管与普通角色分离。
+
+## 4. 审计与可追溯（商业后台关键）
+
+- **操作审计日志**：谁、何时、对什么、做了什么(创建/修改/删除/导出)，关键操作留痕可查。
+- 重要数据用**软删除** + 变更历史；敏感操作(改权限/删数据/导出)额外审计 + 必要时二次确认。
+- 导出有权限控制与审计(防数据泄露)。
+
+## 5. 体验与一致性
+
+- 统一布局（侧边导航 + 顶部 + 内容区）、统一组件库(Ant Design/Element Plus/Arco 等成熟后台 UI)、一致的交互范式。
+- 面包屑、保留筛选状态(刷新/返回不丢)、可分享的列表 URL(查询参数)。
+- 响应式(至少平板可用)；深色可选；大量数据下性能。
+- 用成熟后台框架/脚手架(如 Ant Design Pro)对齐规范，别从零搓。
+
+## 6. 后端配套
+
+- CRUD API 遵循 API 规范(资源/状态码/分页/校验/错误信封)；列表接口支持过滤/排序/分页参数。
+- 批量/导出走事务 + 幂等 + 异步(大数据)；删除软删 + 审计。
+- 权限在服务层强制(对象级+数据范围)；审计日志统一切面记录。
+
+## 7. 反模式（出现即不合格）
+
+- 列表前端全量加载、无服务端分页/过滤；大数据卡死。
+- 无批量操作 / 批量无确认无幂等；导出大数据同步阻塞。
+- 权限只前端隐藏、后端不校验(可越权)；无数据范围权限。
+- 无操作审计、关键操作无留痕；硬删除不可追溯。
+- 从零搓表格/表单不用成熟后台库；筛选状态刷新即丢。
+
+## 8. 最低交付 checklist
+
+- [ ] 列表服务端分页+排序+多条件过滤+上限；批量操作(多选/确认/幂等/进度)；三态；大数据虚拟滚动/异步导出。
+- [ ] 表单遵循校验标准+复用+草稿/未保存提醒。
+- [ ] RBAC：菜单/按钮/数据级权限，前端隐藏 + 后端强制(对象级+数据范围)。
+- [ ] 操作审计日志(谁/何时/对什么/做了什么)+软删除+变更历史+敏感操作二次确认。
+- [ ] 统一布局+成熟后台 UI 库+面包屑+筛选状态保留+可分享 URL+响应式。
+
+---
+**参考**：Ant Design Pro / Element Plus 后台、服务端分页表格、RBAC、操作审计、数据范围权限、异步导出。

package/frontend/01-standards/design-tokens-complete.md

@@ -0,0 +1,444 @@
+---
+id: design-tokens-complete
+title: Design Token 完整指南
+domain: frontend
+category: 01-standards
+difficulty: intermediate
+tags: [complete, design, frontend, tailwind, token, tokens, 分层架构, 命名规范]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# Design Token 完整指南
+
+## 概述
+
+Design Token 是设计系统的最小单元，用于存储颜色、字体、间距、圆角、阴影等视觉属性的命名变量。Token 充当设计与开发之间的单一事实来源 (Single Source of Truth)，确保品牌一致性、多主题支持和跨平台适配。
+
+### 为什么需要 Design Token
+
+- **一致性**: 全产品使用统一的视觉语言
+- **可维护性**: 修改一个 Token 即可全局生效
+- **多主题**: 浅色/深色/品牌主题只需切换 Token 集
+- **跨平台**: 同一 Token 输出 CSS / iOS / Android / Flutter 等格式
+- **设计-开发协同**: 设计师和开发者使用同一套命名系统
+
+---
+
+## Token 分层架构
+
+### 三层模型
+
+```
+┌──────────────────────────────────┐
+│  Component Token (组件级)         │   button-primary-bg
+│  直接绑定到组件属性                │   card-border-radius
+├──────────────────────────────────┤
+│  Semantic Token (语义级)          │   color-bg-primary
+│  表达意图，不绑定具体组件           │   spacing-lg
+├──────────────────────────────────┤
+│  Primitive Token (基础级)         │   blue-600
+│  原始设计值，直接对应色值/数值       │   16px
+└──────────────────────────────────┘
+```
+
+### 示例映射
+
+```
+Primitive:   blue-600 = #2563EB
+Semantic:    color-bg-primary = {blue-600}
+Component:   button-primary-bg = {color-bg-primary}
+```
+
+---
+
+## Token 命名规范
+
+### 命名结构
+
+```
+{category}-{property}-{modifier}-{state}
+
+# 示例
+color-bg-primary           # 类别-属性-修饰符
+color-text-secondary       # 类别-属性-修饰符
+spacing-lg                 # 类别-修饰符
+radius-md                  # 类别-修饰符
+shadow-card-hover          # 类别-修饰符-状态
+font-size-heading-1        # 类别-属性-修饰符
+```
+
+### 颜色 Token
+
+```css
+:root {
+  /* Primitive: 原始色板 */
+  --primitive-blue-50: #EFF6FF;
+  --primitive-blue-100: #DBEAFE;
+  --primitive-blue-500: #3B82F6;
+  --primitive-blue-600: #2563EB;
+  --primitive-blue-700: #1D4ED8;
+  --primitive-blue-900: #1E3A5F;
+
+  --primitive-gray-50: #F9FAFB;
+  --primitive-gray-100: #F3F4F6;
+  --primitive-gray-200: #E5E7EB;
+  --primitive-gray-500: #6B7280;
+  --primitive-gray-700: #374151;
+  --primitive-gray-900: #111827;
+
+  /* Semantic: 语义色 */
+  --color-bg-page: var(--primitive-gray-50);
+  --color-bg-surface: #FFFFFF;
+  --color-bg-primary: var(--primitive-blue-600);
+  --color-bg-primary-hover: var(--primitive-blue-700);
+  --color-bg-danger: #DC2626;
+
+  --color-text-primary: var(--primitive-gray-900);
+  --color-text-secondary: var(--primitive-gray-500);
+  --color-text-on-primary: #FFFFFF;
+  --color-text-link: var(--primitive-blue-600);
+  --color-text-danger: #DC2626;
+
+  --color-border-default: var(--primitive-gray-200);
+  --color-border-focus: var(--primitive-blue-500);
+}
+```
+
+### 间距 Token
+
+```css
+:root {
+  /* 基于 4px 网格系统 */
+  --spacing-0: 0px;
+  --spacing-1: 4px;      /* 0.25rem */
+  --spacing-2: 8px;      /* 0.5rem */
+  --spacing-3: 12px;     /* 0.75rem */
+  --spacing-4: 16px;     /* 1rem */
+  --spacing-5: 20px;     /* 1.25rem */
+  --spacing-6: 24px;     /* 1.5rem */
+  --spacing-8: 32px;     /* 2rem */
+  --spacing-10: 40px;    /* 2.5rem */
+  --spacing-12: 48px;    /* 3rem */
+  --spacing-16: 64px;    /* 4rem */
+  --spacing-20: 80px;    /* 5rem */
+  --spacing-24: 96px;    /* 6rem */
+
+  /* 语义间距 */
+  --spacing-page-x: var(--spacing-6);       /* 页面水平内边距 */
+  --spacing-section-y: var(--spacing-16);   /* 区块垂直间距 */
+  --spacing-card-padding: var(--spacing-6); /* 卡片内边距 */
+  --spacing-input-x: var(--spacing-3);      /* 输入框水平内边距 */
+  --spacing-input-y: var(--spacing-2);      /* 输入框垂直内边距 */
+}
+```
+
+### 字体 Token
+
+```css
+:root {
+  /* 字体族 */
+  --font-family-sans: "Inter", "Noto Sans SC", system-ui, -apple-system, sans-serif;
+  --font-family-mono: "JetBrains Mono", "Fira Code", monospace;
+
+  /* 字号 */
+  --font-size-xs: 0.75rem;     /* 12px */
+  --font-size-sm: 0.875rem;    /* 14px */
+  --font-size-base: 1rem;      /* 16px */
+  --font-size-lg: 1.125rem;    /* 18px */
+  --font-size-xl: 1.25rem;     /* 20px */
+  --font-size-2xl: 1.5rem;     /* 24px */
+  --font-size-3xl: 1.875rem;   /* 30px */
+  --font-size-4xl: 2.25rem;    /* 36px */
+
+  /* 字重 */
+  --font-weight-regular: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+
+  /* 行高 */
+  --line-height-tight: 1.25;
+  --line-height-normal: 1.5;
+  --line-height-relaxed: 1.75;
+
+  /* 语义字体组合 */
+  --font-heading-1: var(--font-weight-bold) var(--font-size-4xl)/var(--line-height-tight) var(--font-family-sans);
+  --font-heading-2: var(--font-weight-semibold) var(--font-size-3xl)/var(--line-height-tight) var(--font-family-sans);
+  --font-body: var(--font-weight-regular) var(--font-size-base)/var(--line-height-normal) var(--font-family-sans);
+  --font-caption: var(--font-weight-regular) var(--font-size-sm)/var(--line-height-normal) var(--font-family-sans);
+}
+```
+
+### 圆角与阴影 Token
+
+```css
+:root {
+  /* 圆角 */
+  --radius-none: 0;
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-xl: 16px;
+  --radius-full: 9999px;
+
+  /* 阴影 */
+  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
+  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1);
+  --shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1);
+
+  /* 动效 */
+  --duration-fast: 150ms;
+  --duration-normal: 250ms;
+  --duration-slow: 400ms;
+  --easing-default: cubic-bezier(0.4, 0, 0.2, 1);
+  --easing-in: cubic-bezier(0.4, 0, 1, 1);
+  --easing-out: cubic-bezier(0, 0, 0.2, 1);
+}
+```
+
+---
+
+## 多主题支持
+
+### CSS 变量主题切换
+
+```css
+/* 浅色主题（默认） */
+:root, [data-theme="light"] {
+  --color-bg-page: #F9FAFB;
+  --color-bg-surface: #FFFFFF;
+  --color-text-primary: #111827;
+  --color-text-secondary: #6B7280;
+  --color-border-default: #E5E7EB;
+}
+
+/* 深色主题 */
+[data-theme="dark"] {
+  --color-bg-page: #0F172A;
+  --color-bg-surface: #1E293B;
+  --color-text-primary: #F1F5F9;
+  --color-text-secondary: #94A3B8;
+  --color-border-default: #334155;
+}
+
+/* 跟随系统 */
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) {
+    --color-bg-page: #0F172A;
+    --color-bg-surface: #1E293B;
+    --color-text-primary: #F1F5F9;
+    --color-text-secondary: #94A3B8;
+    --color-border-default: #334155;
+  }
+}
+```
+
+### 主题切换实现
+
+```tsx
+// React 主题切换 Hook
+function useTheme() {
+  const [theme, setTheme] = useState<"light" | "dark" | "system">(() => {
+    return (localStorage.getItem("theme") as "light" | "dark") || "system";
+  });
+
+  useEffect(() => {
+    const root = document.documentElement;
+    if (theme === "system") {
+      root.removeAttribute("data-theme");
+    } else {
+      root.setAttribute("data-theme", theme);
+    }
+    localStorage.setItem("theme", theme);
+  }, [theme]);
+
+  return { theme, setTheme };
+}
+```
+
+---
+
+## Tailwind CSS 集成
+
+### tailwind.config.ts 映射
+
+```typescript
+import type { Config } from "tailwindcss";
+
+const config: Config = {
+  theme: {
+    extend: {
+      colors: {
+        bg: {
+          page: "var(--color-bg-page)",
+          surface: "var(--color-bg-surface)",
+          primary: "var(--color-bg-primary)",
+        },
+        text: {
+          primary: "var(--color-text-primary)",
+          secondary: "var(--color-text-secondary)",
+        },
+        border: {
+          default: "var(--color-border-default)",
+        },
+      },
+      spacing: {
+        "page-x": "var(--spacing-page-x)",
+        "section-y": "var(--spacing-section-y)",
+      },
+      borderRadius: {
+        card: "var(--radius-md)",
+        button: "var(--radius-md)",
+      },
+      boxShadow: {
+        card: "var(--shadow-md)",
+      },
+      fontFamily: {
+        sans: ["var(--font-family-sans)"],
+        mono: ["var(--font-family-mono)"],
+      },
+    },
+  },
+};
+
+export default config;
+```
+
+---
+
+## 工具链
+
+### Style Dictionary
+
+```json
+// tokens/color/base.json
+{
+  "color": {
+    "blue": {
+      "600": { "value": "#2563EB", "type": "color" }
+    },
+    "bg": {
+      "primary": {
+        "value": "{color.blue.600}",
+        "type": "color",
+        "description": "Primary background color"
+      }
+    }
+  }
+}
+```
+
+```javascript
+// config.js
+module.exports = {
+  source: ["tokens/**/*.json"],
+  platforms: {
+    css: {
+      transformGroup: "css",
+      buildPath: "output/css/",
+      files: [{ destination: "design-tokens.css", format: "css/variables" }],
+    },
+    ios: {
+      transformGroup: "ios-swift",
+      buildPath: "output/ios/",
+      files: [{ destination: "DesignTokens.swift", format: "ios-swift/class.swift" }],
+    },
+    android: {
+      transformGroup: "android",
+      buildPath: "output/android/",
+      files: [{ destination: "design_tokens.xml", format: "android/resources" }],
+    },
+  },
+};
+```
+
+### Figma Token Studio
+
+```
+Figma Token Studio -> JSON export -> Style Dictionary -> CSS / iOS / Android
+```
+
+---
+
+## 组件级 Token 使用
+
+```css
+/* 按钮组件 Token */
+.btn {
+  padding: var(--spacing-input-y) var(--spacing-input-x);
+  border-radius: var(--radius-md);
+  font: var(--font-body);
+  transition: all var(--duration-fast) var(--easing-default);
+}
+
+.btn-primary {
+  background: var(--color-bg-primary);
+  color: var(--color-text-on-primary);
+}
+
+.btn-primary:hover {
+  background: var(--color-bg-primary-hover);
+}
+
+/* 卡片组件 Token */
+.card {
+  background: var(--color-bg-surface);
+  border: 1px solid var(--color-border-default);
+  border-radius: var(--radius-lg);
+  padding: var(--spacing-card-padding);
+  box-shadow: var(--shadow-sm);
+}
+```
+
+---
+
+## 治理与维护
+
+### Token 变更流程
+
+1. 设计师在 Figma 更新 Token
+2. 导出 JSON 到仓库
+3. CI 自动运行 Style Dictionary 构建
+4. 视觉回归测试验证变更
+5. PR Review 后合并
+
+### Token 审计
+
+```bash
+# 检查未使用的 Token
+grep -r "var(--" src/ | grep -oP "var\(--[^)]+\)" | sort -u > used-tokens.txt
+grep -oP "^\s*--[^:]+:" styles/tokens.css | sed 's/://;s/^\s*//' | sort -u > defined-tokens.txt
+diff defined-tokens.txt used-tokens.txt
+```
+
+---
+
+## 常见反模式
+
+| 反模式 | 问题 | 正确做法 |
+|--------|------|----------|
+| 直接写死色值 | 主题无法切换 | 始终引用 Token |
+| Primitive Token 直接用于组件 | 语义丢失 | 用 Semantic Token 间接引用 |
+| Token 命名含具体色值 | 深色模式失效 | 按意图命名 (primary, danger) |
+| Token 数量爆炸 | 维护困难 | 控制在 100-200 个 |
+| 不同组件重复定义相同值 | 不一致风险 | 统一为共享 Token |
+
+---
+
+## Agent Checklist
+
+在 AI 编码流水线中实现 Design Token 时，必须逐项检查：
+
+- [ ] Token 采用三层架构（Primitive -> Semantic -> Component）
+- [ ] 命名遵循 {category}-{property}-{modifier}-{state} 结构
+- [ ] 颜色按语义命名（bg-primary, text-secondary），不按色值命名
+- [ ] 间距基于 4px 网格（4/8/12/16/24/32/48/64）
+- [ ] 字体定义族、大小、字重、行高的完整 Token
+- [ ] 支持浅色/深色主题切换（CSS 变量 + data-theme）
+- [ ] 深色主题由显式 Token 映射生成，不是简单反转
+- [ ] Tailwind 配置映射到 Token 变量
+- [ ] 所有组件样式通过 Token 引用，不直接写魔法数字
+- [ ] Token 数量控制在 100-200 个以内
+- [ ] Token 变更有审计流程（设计同步 -> 构建 -> 视觉回归）
+- [ ] Token 文件是机器可解析的 JSON/YAML 格式

package/frontend/01-standards/forms-and-validation.md

@@ -0,0 +1,77 @@
+---
+id: forms-and-validation
+title: 前端表单与校验标准（商业级必读）
+domain: frontend
+category: 01-standards
+difficulty: intermediate
+tags: [表单, form, 校验, validation, 受控, 错误提示, 提交状态, 多步, 可访问性, a11y, 乐观更新, 商业级]
+quality_score: 95
+last_updated: 2026-06-19
+---
+
+# 前端表单与校验标准（商业级必读）
+
+> 表单是商业前端最复杂、最影响转化与体验的部分，也是 AI 最容易做得粗糙的地方（没校验、没错误态、没加载态、不可访问）。本标准给出商业级表单的完整要求。
+
+## 1. 受控与状态
+
+- 输入用**受控组件**（值绑定 state），或用成熟表单库（React Hook Form / Formik / VeeValidate）管理状态、校验、提交。
+- 表单状态明确：`idle / validating / submitting / success / error`，UI 据此切换。
+- 复杂表单用表单库 + schema 校验（Zod/Yup），不要手写一堆 useState + if。
+
+## 2. 校验（双端，前端体验 + 后端兜底）
+
+- **前端校验**给即时反馈（格式、必填、范围、一致性如两次密码），但**绝不替代后端校验**。
+- **后端永远再校验一遍**（前端可绕过）；前端展示后端返回的字段级错误（对齐错误信封 `details[].field`）。
+- 校验时机：失焦(blur)校验单字段 + 提交时校验全表单；不要每个按键就报红打断输入。
+- 校验规则尽量与后端共享（同一份 schema/常量），避免前后端规则漂移。
+
+## 3. 错误展示
+
+- **字段级错误**显示在对应输入下方，文案具体可行动（"密码至少 8 位" 而非 "无效"）。
+- 提交失败的**整体错误**（如 409 邮箱已注册、网络错误）在表单顶部/对应字段提示。
+- 错误用颜色 + 图标 + 文本（不只靠颜色，照顾色盲）；`aria-invalid` + `aria-describedby` 关联错误。
+- 后端 422 字段错误自动映射到对应输入。
+
+## 4. 提交状态与防重复
+
+- 提交中**禁用提交按钮 + loading 指示**，防重复提交。
+- 创建/支付类提交配合后端**幂等键**防重复下单/扣款。
+- 提交成功给明确反馈（跳转/toast/inline success）；失败保留用户已填内容，不清空。
+- 网络慢时有反馈，不让用户以为卡死。
+
+## 5. 体验细节
+
+- 合理的 `type`（email/tel/number/password）、`autocomplete`、`inputmode`，移动端键盘正确。
+- 必填标注清晰；占位符不当标签用（要有真 `<label>`）。
+- 长表单分组/分步（multi-step），有进度指示，可返回上一步且保留数据。
+- 危险操作（删除/不可逆）二次确认。
+- 自动聚焦首个字段 / 出错时聚焦首个错误字段。
+
+## 6. 可访问性（a11y，商业必做）
+
+- 每个输入有关联 `<label for>`（或 aria-label）；不要只靠 placeholder。
+- 错误用 `aria-invalid` + `role="alert"`/`aria-live` 让屏读播报。
+- 键盘可完整操作；焦点顺序合理；提交可回车。
+- 对比度达标；触控目标够大。
+
+## 7. 反模式（出现即不合格）
+
+- 没有任何校验，或只有前端校验（后端不验）。
+- 只画 happy path：没有 loading/error/disabled 态，提交可重复点。
+- 错误只变红框没有文案，或文案泛泛（"出错了"）。
+- 用 placeholder 当 label；无 `<label>`；不可键盘操作。
+- 提交失败清空用户输入；每个按键就报红。
+- 密码/支付表单无强度/格式反馈、无防重复提交。
+
+## 8. 最低交付 checklist
+
+- [ ] 受控/表单库 + schema 校验；状态机 idle/submitting/success/error 清晰。
+- [ ] 前端即时校验 + 后端兜底校验；422 字段错误映射到输入。
+- [ ] 字段级 + 整体错误，文案具体可行动，颜色+图标+文本+aria。
+- [ ] 提交中禁用+loading 防重复；创建/支付配合幂等；成功明确反馈、失败保留输入。
+- [ ] 正确 input type/autocomplete；真 `<label>`；长表单分步保留数据；危险操作二次确认。
+- [ ] a11y：label 关联、aria-invalid/live、键盘可达、对比度达标。
+
+---
+**参考**：React Hook Form / Zod、WCAG 表单可访问性、WAI-ARIA、HTML 表单最佳实践。