@captain_z/zsk-skills 0.1.0

package/frontend/typescript/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: zsk:typescript
+description: TypeScript in frontend codebases — red lines (no any / as any /
+  @ts-ignore / empty interface / Object type), must-do (explicit types for
+  public boundaries, union literals, strict + noUncheckedIndexedAccess), API
+  types from backend (not hand-written), type vs interface, generics discipline,
+  unknown over any. Complements quality/code-hygiene for cross-language hygiene.
+category: standard
+domain: frontend
+tier: optional
+related:
+  - ../react-components/SKILL.md
+  - ../api-contract-ts/SKILL.md
+  - ../../quality/code-hygiene/SKILL.md
+triggers:
+  - TypeScript red lines
+  - no any
+  - strict mode
+  - noUncheckedIndexedAccess
+  - type vs interface
+  - generic constraints
+  - API type from backend
+---
+
+# TypeScript · 类型纪律
+
+> **范围**：TypeScript 的**红线 + 必做 + 风格** — 针对 React + Web 生态
+> **前置**：`tsconfig.json` 必须 `strict: true`，否则本文件 70% 规则无法强制
+
+## 红线（CI 必 fail）
+
+### 禁用关键字
+
+- ❌ `any`（除非经 ADR 豁免 + 该行 `// eslint-disable-next-line @typescript-eslint/no-explicit-any` + 理由）
+- ❌ `as any` / `as unknown as X`（**双层断言禁用**：绕过了两层类型系统，等同于 `any`）
+- ❌ `@ts-ignore` / `@ts-nocheck`（改用 `@ts-expect-error` 并注明理由）
+- ❌ `Object` / `Function` 作为类型（用具体签名：`Record<string, unknown>` / `(x: T) => U`）
+- ❌ 空 interface `interface Foo {}`（意图不清：若是占位用 `Record<string, never>`，若要继承请声明字段）
+- ❌ 类型别名和原类型等价（`type Str = string` 没意义）
+- ❌ `!` 非空断言除非紧邻一个刚验证非空的 if（多数场景用**类型收窄**）
+
+### 禁用操作
+
+- ❌ 手写 API 响应 / 请求类型（见"类型来自后端"一节）
+- ❌ 在 `.ts` 里写 `any` 的推断源（比如 `JSON.parse` 结果不收窄就用）
+- ❌ 绕过 strict：在文件顶端加 `// @ts-nocheck`
+
+## 必做
+
+### 公共边界显式类型
+
+以下位置**必须**显式标注类型（不依赖推断）：
+
+| 位置 | 示例 |
+| --- | --- |
+| 导出函数入参 / 返回值 | `export function foo(x: string): User {}` |
+| 组件 Props | `type BtnProps = { ... }` |
+| Hook 入参 / 返回值 | `export function useX(id: string): UseXResult {}` |
+| Event 回调签名 | `onChange: (value: string) => void` |
+| Service 层方法 | `async function getUser(id: string): Promise<User>` |
+| 模块级常量含复杂对象 | `const CONFIG: AppConfig = { ... }` |
+
+**局部变量**可依赖推断（`const user = getUser()`），不用重复标注。
+
+### strict 必开子项
+
+`tsconfig.json`：
+
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,                          // 打开下面全部
+    "noUncheckedIndexedAccess": true,        // arr[0] 推断为 T | undefined
+    "exactOptionalPropertyTypes": true,      // 可选属性和 undefined 区分
+    "noImplicitOverride": true,              // override 必须显式
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}
+```
+
+### 联合字面量优于字符串魔法
+
+```ts
+// ❌
+const status = 'loading'; // 手写错了没人知道
+
+// ✅
+type Status = 'idle' | 'loading' | 'success' | 'error';
+const status: Status = 'loading'; // 拼错 TS 报错
+```
+
+### `unknown` 优于 `any`
+
+接收不可信输入时用 `unknown`，强制消费处收窄：
+
+```ts
+function parse(raw: unknown): User {
+  if (isUser(raw)) return raw; // 收窄
+  throw new Error('invalid user');
+}
+```
+
+### 空值
+
+- **默认用 `undefined`**（符合 JS 引擎语义 + 可选参数自然对齐）
+- **对接后端 `null`** 时：service 层就地归一化为 `undefined` 或保持 `null`，**项目内保持一致**
+- `exactOptionalPropertyTypes` 开启后：`{ x?: string }` 不等于 `{ x: string | undefined }`
+
+## 类型来自后端
+
+API 类型**不手写**。引用 `{{config.paths.api_contracts}}/{service}/types.ts`：
+
+```ts
+import type { UserListResponse, UserCreateRequest } from '{{config.paths.api_contracts}}/user/types';
+
+async function fetchUsers(): Promise<UserListResponse> {
+  const res = await request.get<UserListResponse>('/api/users');
+  return res.data;
+}
+```
+
+**理由**：后端变更时类型自动报错，而不是运行时才发现。详见 [`api-contract-ts`](../api-contract-ts/SKILL.md)。
+
+## type vs interface
+
+| 场景 | 选 type 还是 interface | 理由 |
+| --- | --- | --- |
+| 联合 / 交叉 / 元组 / mapped | `type` | interface 不支持 |
+| Props / 数据模型 / 简单对象 | 两者皆可，**项目内保持一致** | 功能等价 |
+| 需要 declaration merging（全局扩展第三方库） | `interface` | type 不支持 |
+| 需要 extends 多个（复用） | 两者皆可，`type` 用 `&` | 可读性差异 |
+
+**建议**：项目统一用 `type`（更一致，能表达更多结构），只有需要合并时用 `interface`。
+
+## 泛型纪律
+
+### 何时用泛型
+
+- ✅ 参数类型决定返回类型（`function first<T>(arr: T[]): T | undefined`）
+- ✅ 容器 / 高阶抽象（`type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }`）
+- ✅ 组件接受不同数据形态（`<Table<T> columns={...} data={...} />`）
+
+### 泛型命名
+
+- 单字母：`T` / `U` / `V`（简单占位）
+- 描述性：`TData` / `TError` / `TResponse`（语义清晰）
+- 约束：`T extends { id: string }`（别用空 `T`）
+
+### 禁用
+
+- ❌ 泛型没被使用（`function foo<T>(x: string): void` 的 `T` 是僵尸）
+- ❌ 过度泛型化（"以后可能要换类型" = YAGNI）
+- ❌ 泛型默认值用 `any`（用 `unknown` 或具体类型）
+
+## 窄化技巧（淘汰 `!` 和 `as`）
+
+```ts
+// ❌ 非空断言
+const name = user!.name;
+
+// ✅ 收窄
+if (!user) return null;
+const name = user.name;
+
+// ❌ 断言
+const el = document.getElementById('x') as HTMLInputElement;
+
+// ✅ 运行时校验
+const el = document.getElementById('x');
+if (!(el instanceof HTMLInputElement)) throw new Error('x not an input');
+```
+
+### 常见窄化
+
+- `typeof x === 'string'`
+- `Array.isArray(x)`
+- `x instanceof SomeClass`
+- 自定义 type guard：`function isUser(x: unknown): x is User { ... }`
+- `in` 操作符：`'error' in result`
+
+## `import type` 习惯
+
+```ts
+import type { User } from './types';       // 只做类型用途
+import { createUser } from './service';    // 运行时值
+```
+
+**好处**：bundler 可以完全剥离类型，不污染生产 bundle。
+
+## `as const` 与常量对象
+
+```ts
+const PERMISSIONS = ['read', 'write', 'admin'] as const;
+type Permission = typeof PERMISSIONS[number]; // 'read' | 'write' | 'admin'
+```
+
+比手写 `type Permission = 'read' | 'write' | 'admin'` 少一处维护。
+
+## 反模式（禁止）
+
+- ❌ `// @ts-nocheck` 顶在文件头
+- ❌ `const data: any = ...` 然后一路传递
+- ❌ `as unknown as X` 双层断言
+- ❌ 空 interface 作占位符
+- ❌ 手写与后端不同步的 API 类型
+- ❌ 泛型没有使用 / 没有约束
+- ❌ `I` 前缀 / `Type` 后缀（见 [`react-naming`](../react-naming/SKILL.md)）
+
+## 质量门禁
+
+- [ ] `strict: true` + `noUncheckedIndexedAccess: true`
+- [ ] 无新增 `any` / `as any` / `@ts-ignore` / `@ts-nocheck`
+- [ ] 公共边界全部显式类型
+- [ ] API 类型引自 `{{config.paths.api_contracts}}`
+- [ ] 联合字面量替代字符串魔法值
+- [ ] 无非空断言 `!`（或每处有 ADR 链接）
+- [ ] type / interface 项目内一致
+- [ ] `tsc --noEmit` 零 error

package/meta/philosophy/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: zsk:philosophy
+description: Design rationale of the zsk skill set — LLM Wiki × Superpowers ×
+  GSD × project-adaptation synthesis. For contributors needing to understand why
+  zsk is organized the way it is.
+category: meta
+domain: meta
+tier: optional
+related:
+  - ../../system/project-constraints-template/SKILL.md
+triggers:
+  - zsk philosophy
+  - why is zsk organized this way
+  - design rationale
+  - LLM wiki vs superpowers
+  - skill set principles
+---
+
+# Philosophy：LLM Wiki × Superpowers × GSD × 项目适配
+
+## TL;DR
+
+本 skill set 是**四股思想的合成**，目标是产出**通用 + LLM 友好 + 可项目适配 + 有纪律**的软件开发工作流规范。
+
+- **通用**：不绑定任何具体项目、技术栈、组件库
+- **LLM 友好**：frontmatter + 小文件 + 交叉引用
+- **可适配**：项目通过 `PROJECT-CONFIG.yaml` 挂接，不 fork skills
+- **有纪律**：Superpowers 硬原则（证据先于断言、TDD、置信度质疑）
+
+## 四股思想的贡献
+
+### 1. LLM Wiki — 组织哲学
+
+> 原始出处：Karpathy 的 LLM Wiki 模式（完整事实源保存在 zsk 仓库 `.raws/` 目录，不随 skill 分发）。
+
+本 skill set **借鉴**以下组织哲学，不照搬原文的具体运营机制：
+
+- 每份文档 YAML frontmatter（`name` / `description` / `related` / `triggers`）
+- 小而聚焦（单文件 ≤ 300 行，匹配 LLM chunk 读取窗口）
+- 显式交叉引用（`related:` + 编号锚，让引用关系成为一等公民）
+- 确定性路径命名（LLM 能预测文件位置）
+- `description` 字段用**直接陈述风格**告诉 LLM 本文件是什么（主题名词短语 — 关键要点），不以 "Use when…" 开头
+
+#### 借鉴什么 × 有意不采纳什么
+
+Karpathy 原文是**"LLM 持续自维护的活知识库"**；本 skill set 是**"LLM 友好的静态 SDLC 文档"**，两者目的不同，取舍也不同：
+
+| Karpathy 原文要素 | 本 skill set 态度 | 理由 |
+| --- | --- | --- |
+| 层（Raw / Wiki / Schema） | ✅ 借鉴：`_raws/` / `docs/{module}/` / `CLAUDE.md`+`SYSTEM-SPEC.md`+本目录 | 所有权与可变性模型与工程场景天然吻合 |
+| 交叉引用纪律 | ✅ 借鉴并强化为 FR/NFR/US/AC **编号锚** | 工程化对追溯的要求比知识库更严，用编号替代纯 `related:` 链接 |
+| 小文件 + frontmatter | ✅ 借鉴 | 便于 LLM 按需加载 + 人类快速定位 |
+| **Ingest（LLM 批量改多页）** | ❌ 不采纳 | Spec 是**冻结契约**（DoR 明说），不能让 LLM 日常改写 |
+| **Lint（矛盾 / 孤儿 / 过期审计）** | ❌ 不采纳 | 质量门禁 + Code Review + 编号矩阵兜住 |
+| **index.md / log.md 模块级元文件** | ❌ 不采纳 | `docs/{module}/` 本身即聚合目录 |
+| **LLM 独占 wiki 写入权** | ❌ 不采纳 | 工程场景下决策归责于人 |
+
+**一句话**：LLM Wiki 贡献**组织哲学**，7 阶段工作流贡献**工程化纪律**——两者合成，不是任一方的替代或部分实现。
+
+### 2. Superpowers — 工作流骨架
+
+给"软件开发方法论"提供可 skill 化的组织：
+
+- Skill-based orchestration：每个能力一个 skill
+- 线性工作流 + 显式触发条件
+- "Red flags" 反模式告警机制
+- 决策流程图（Graphviz）表达分支
+
+**从 Superpowers 吸收的硬原则（写入所有 stages / workflows）**：
+
+| 原则 | 含义 |
+| --- | --- |
+| 证据先于断言 | 未跑过的命令不得声称"通过" |
+| Red-Green-Refactor | Bugfix / Refactor 默认纪律 |
+| Bug 置信度质疑 | 修 bug 前先问"bug 存在吗、原因对吗、修复有效吗" |
+| 技术严谨 > 性能式同意 | Review 分歧先验证技术事实 |
+
+### 3. GSD (Getting Stuff Done) — 心智模型
+
+给"阶段推进"提供心智依据：
+
+- **Capture** → 收集想法 / 需求 / 问题
+- **Clarify** → 澄清：这是什么？做不做？怎么做？
+- **Organize** → 组织到具体位置（清单、项目、日程）
+- **Reflect** → 回顾 / 审视 / 斟酌
+- **Engage** → 动手执行
+
+映射到本 skill set 的 7 阶段：
+
+| GSD 心智 | 本 skill set 阶段 | 负责什么 |
+| --- | --- | --- |
+| Capture + Clarify | `zsk:proposal` | 为什么做 / 不做什么 |
+| Organize | `zsk:spec` | 做什么（契约 / 验收） |
+| Reflect | `zsk:design` | 怎么做（设计 / ADR） |
+| Engage | `zsk:coding` → `zsk:reviewing` → `zsk:verify` → `zsk:archive` | 动手执行 + 审代码 + 验收 + 沉淀 |
+
+### 4. 项目 SYSTEM-SPEC — 适配层
+
+项目总有定制需求（路径 / 技术栈 / 命名 / 环境）。适配层保证：
+
+- **占位符系统**：`{{config.*}}` 在 skill 内作为抽象变量
+- **优先级层级**：项目覆写 > 通用 skill
+- **不 fork**：通过配置文件覆盖，而非修改 skill 本体
+
+## 合成：5 条设计原则
+
+### 原则 1：通用方法 × 项目配置
+
+```text
+ 方法论（WHAT / HOW 抽象）      配置（WHERE / WHICH 具体）
+        ↓                            ↓
+    .best-practices/      ×     PROJECT-CONFIG.yaml
+        ↘                        ↙
+          运行时解析 → 具体产物（模块 proposal.md / spec.md 等）
+```
+
+- **方法论** → zsk skills（跨项目通用，npm 包）
+- **路径 / 工具 / 命名** → `PROJECT-CONFIG.yaml`（项目本地）
+
+### 原则 2：LLM 优先的组织
+
+- Frontmatter 必须有 `name` / `description` / `category` / `domain` / `related` / `triggers`
+- `description` 用**直接陈述**风格（主题名词短语 — 关键要点），不以 "Use when…" 开头
+- 单文件 ≤ 300 行
+- 显式 `related:` 链接
+- 避免跨文件隐式依赖
+
+### 原则 3：阶段化 + 变更类型 + 领域分簇
+
+- **基础**：7 阶段（Proposal → Spec → Design → Coding → Reviewing → Verify → Archive），**不可删**
+- **分支**：Feature / Bugfix / Refactor（按变更类型差异化填充 7 阶段）
+- **领域**：sdlc / frontend / quality / design-handoff / system / meta
+- Skill 通过 frontmatter `domain:` + `category:` + `tier:` 标注
+
+### 原则 4：基于证据的纪律
+
+- "完成 / 通过 / 修复"必须有**可验证证据链接**
+- TDD 是 Bugfix / Refactor 默认；Feature 视复杂度
+- 修 bug 前必问三问（Superpowers 置信度质疑）
+- Review 分歧时先验证技术，再讨论情感
+
+### 原则 5：编号化交叉引用
+
+> 灵感源头：Karpathy LLM Wiki 的 "cross-references are already there"——好的知识库里，引用关系是一等公民。
+> 工程化强化：我们把纯 `related:` 链接升级为**强编号锚**。
+
+7 阶段文档间建立**编号化追溯链**：
+
+```text
+Proposal  G-{n}  (SMART 目标)
+    ↓
+Spec      US-{n} / FR-{n} / NFR-{n} / AC-{n}   (可被下游锚定)
+    ↓                                          ↑
+Design    FR-{n} → 入口文件 + ADR-{n} + 覆盖任务 (显式回链)
+    ↓
+Coding    每任务声明"覆盖 FR"
+    ↓
+Reviewing / Verify   FR 覆盖矩阵 + AC 勾选兜底
+    ↓
+Archive   Postmortem / ADR 引用原编号保留追溯
+```
+
+**纪律要点**：
+
+- Spec 是编号的**唯一发源地**，Design / Task 只引用不自创
+- 编号只增不改（废弃标记代替删除，合并/拆分留追踪）
+- Bugfix 的"受影响契约项"、Refactor 的"行为不变"都用同一套编号
+- DoR/DoD/质量门禁把编号完整性作为硬性门禁
+
+## 优先级层级（冲突时上位胜出）
+
+1. **用户显式指令**（CLAUDE.md / 会话中的直接请求）
+2. **项目 PROJECT-CONFIG.yaml**（本项目的配置覆写）
+3. **项目 SYSTEM-SPEC.md**（本项目的系统规约）
+4. **项目 docs/system/\***（本项目 ADR / architecture / NFR）
+5. **zsk skills**（通用方法论，本目录）
+6. **`~/.claude/skills/*` 平台级 skill**（如 Superpowers）
+7. **工具默认行为**
+
+## 占位符系统
+
+Skill 文件引用项目特定内容时，一律用 `{{config.*}}` 占位符，由 `project-config.yaml`（CLI `zsk project-init` 产出）填充：
+
+```text
+{{config.paths.srs}}             原始需求文档
+{{config.paths.figma_index}}     设计索引（如有）
+{{config.stack.ui_lib}}          UI 库
+{{config.stack.state_async}}     异步状态库
+{{config.stack.state_shared}}    共享状态
+{{config.i18n.namespace}}        i18n 命名空间
+{{config.git.main_branch}}       主干分支
+```
+
+## 为什么这样合成
+
+- **单独用 Superpowers**：强在工作流骨架，但缺 LLM 组织约束 + 项目适配机制
+- **单独用 GSD**：心智清晰，但没有 skill 化的产物
+- **单独用 LLM Wiki**：结构清晰，但没有方法论灵魂
+- **三者合一 + 项目适配层**：结构 + 方法论 + 心智 + 可复用
+
+## 反模式（Red Flags）
+
+以下情况立即停止并修正：
+
+1. Skill 里出现硬编码项目路径（如 `.raws/SRS.md`）→ 必须改为 `{{config.*}}`
+2. Skill 里推荐特定 UI 库名 → 改为 `{{config.stack.ui_lib}}`
+3. 同一份 skill 做 3+ 件事 → 拆分
+4. 单文件 > 300 行 → 拆分或精简
+5. 文档没 frontmatter → 补齐
+6. `description` 以 "Use when…" 开头 → 重写为直接陈述风格（主题名词短语 — 关键要点）
+7. 引用其他 skill 但没写在 `related:` → 补齐
+8. 模板用了未在 `project-config.yaml` 声明的变量 → 补齐配置模板
+
+## 输出承诺
+
+最终的 skill set 通过 `@captain_z/zsk` CLI 发布，允许：
+
+- ✅ 任意新项目通过 `npx @captain_z/zsk project-init` 接入
+- ✅ 不需要修改 skill 内容，只改 `project-config.yaml`
+- ✅ 允许项目通过 `SYSTEM-SPEC.md` 本地覆写个别规则
+- ✅ 上游 skill 更新不破坏项目（版本化 + config 向后兼容）

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@captain_z/zsk-skills",
+  "version": "0.1.0",
+  "description": "ZNorth Standard Kit — skill content package (SDLC + frontend + quality + design-handoff + system + meta)",
+  "license": "MIT",
+  "files": [
+    "sdlc",
+    "frontend",
+    "quality",
+    "design-handoff",
+    "system",
+    "meta",
+    "bundles.yaml",
+    "README.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./bundles.yaml": "./bundles.yaml"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {}
+}

package/quality/a11y-principles/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: zsk:a11y-principles
+description: Accessibility principles at the concept level — WCAG 2.1 AA
+  baseline, POUR principles, keyboard operation matrix, focus management, aria
+  semantics, contrast ratios, don't-rely-on-color, reduced motion. For Web/JSX
+  implementation (axe-core, jsx-a11y, focus traps in Modal, etc.) see
+  frontend/a11y-web.md.
+category: standard
+domain: quality
+tier: optional
+related:
+  - ../../system/nfr-baseline/SKILL.md
+  - ../../frontend/a11y-web/SKILL.md
+triggers:
+  - accessibility principles
+  - WCAG AA
+  - POUR
+  - keyboard matrix
+  - focus management
+  - aria semantics
+  - contrast ratio
+  - reduced motion
+---
+
+# Quality: A11y Principles（可访问性原则 · 跨栈）
+
+> **范围**：可访问性的**概念层** — WCAG、POUR、键盘、焦点、aria、对比度、色彩、Reduced Motion
+> **不含**：具体实现（JSX label 关联 / axe-core 扫描 / Modal 焦点陷阱 等）— 见 [`frontend/a11y-web`](../../frontend/a11y-web/SKILL.md)
+> **参考规范**：WCAG 2.1 AA、ARIA Authoring Practices Guide（APG）、Section 508
+> **系统基线**：[`system/nfr-baseline`](../../system/nfr-baseline/SKILL.md) 的第 2 类继承本文件
+
+## 基线：WCAG 2.1 AA
+
+所有新增 / 修改界面必须达到 WCAG 2.1 Level AA。
+
+### 四大原则（POUR）
+
+| 原则 | 含义 | 关键要求 |
+| --- | --- | --- |
+| **Perceivable** | 可感知 | 文字替代、对比度、可缩放 |
+| **Operable** | 可操作 | 键盘可达、焦点管理、无时间限制 |
+| **Understandable** | 可理解 | 可读、可预测、输入辅助 |
+| **Robust** | 健壮 | 兼容辅助技术 |
+
+## 键盘操作矩阵（概念层）
+
+所有交互元素必须满足以下键盘等价操作：
+
+| 键位 | 行为 | 通用场景 |
+| --- | --- | --- |
+| `Tab` | 焦点前进 | 所有可交互元素 |
+| `Shift + Tab` | 焦点后退 | 所有可交互元素 |
+| `Enter` | 激活 / 确认 | 按钮、链接、表单提交 |
+| `Space` | 激活 / 切换 | 按钮、复选框、单选 |
+| `Esc` | 取消 / 关闭 | Modal、Popover、菜单 |
+| `↑ ↓` | 列表 / 下拉项移动 | List、Select、Menu |
+| `← →` | 树展开 / 折叠 | Tree、Tabs |
+| `Home / End` | 跳首项 / 尾项 | 列表、树 |
+
+组件特有键位在模块 `spec.md` 的 UE 状态矩阵声明。
+
+## 焦点管理（概念层）
+
+### 基线
+
+- **焦点可见**：焦点态必须有视觉表现（轮廓 / 背景）
+- **焦点顺序**：Tab 顺序符合视觉阅读顺序（不用正数 tabindex）
+- **焦点陷阱**：Modal / Drawer 打开时焦点锁在内；关闭时回到触发元素
+- **跳过链接**：长页面提供"跳到主内容"链接
+
+### Modal / Overlay 规则
+
+1. 打开时焦点移到第一个可交互元素
+2. 循环 Tab 只在 Modal 内
+3. `Esc` 关闭
+4. 关闭时焦点回到触发 Modal 的元素
+
+## aria 最佳实践（概念层）
+
+### Role（语义角色）
+
+- `button` / `link` / `navigation` / `main` / `dialog` / `tree` / `treeitem` / `list` / `listbox`
+- **优先用语义 HTML / 等价平台原生控件**
+- 用原生不行时才加 role
+
+### State（状态属性）
+
+| 属性 | 用途 |
+| --- | --- |
+| `aria-label` | 无可见文字时提供标签 |
+| `aria-labelledby` | 引用已存在的标签元素 |
+| `aria-describedby` | 引用描述（帮助文本 / 错误提示） |
+| `aria-expanded` | 展开 / 折叠（树 / 下拉） |
+| `aria-selected` | 选中态（列表 / 树 / Tab） |
+| `aria-disabled` | 禁用（替代原生 `disabled` 属性时） |
+| `aria-hidden="true"` | 对辅助技术隐藏装饰元素 |
+| `aria-live` | 动态内容变化通知（`polite` / `assertive`） |
+| `aria-invalid` | 表单校验失败 |
+
+### aria 禁用
+
+- ❌ 同时用 `aria-label` 和 `aria-labelledby`
+- ❌ 给纯装饰元素加 role
+- ❌ `aria-hidden="true"` 包住可交互元素
+- ❌ 滥用 `aria-live="assertive"`（打扰读屏用户）
+
+## 对比度与色彩
+
+| 元素 | 最小对比度 |
+| --- | --- |
+| 正文（< 18pt 或 < 14pt 加粗） | **4.5:1** |
+| 大字号（≥ 18pt 或 ≥ 14pt 加粗） | **3:1** |
+| UI 组件边界（按钮、表单） | **3:1** |
+| 焦点指示 | **3:1** |
+
+### 不依赖颜色传递信息
+
+错误态除了红色必须有图标 / 文字；必选字段除了红色 `*` 必须有文字声明。
+
+## 动效（Reduced Motion）
+
+尊重用户系统偏好 `prefers-reduced-motion: reduce`：
+
+- 装饰性 / 过度动效必须在该偏好下关闭
+- 视差效果、弹跳、旋转、自动播放动画必须可关闭
+
+## 图片与媒体（概念层）
+
+- 图片必须有替代文字（装饰图为空字符串，信息图写明含义）
+- 图表 / 数据可视化需要可访问替代文本（data table / 描述）
+- 视频需要字幕；无自动播放音频
+
+## 测试原则
+
+### 自动化
+- Lint 层面的 a11y 规则（按栈选插件）
+- 运行时 a11y 扫描器（按栈选工具，如 axe-core 系）
+- CI 跑扫描关键页面，**零 critical violation** 才可合并
+
+### 手工
+- 键盘只操作一遍关键流程
+- 读屏抽检（VoiceOver / NVDA / TalkBack）
+- 浏览器 / 系统缩放 200% 检查
+
+## 质量门禁
+
+- [ ] 符合 WCAG 2.1 AA
+- [ ] 键盘操作矩阵完整
+- [ ] 焦点可见 + 陷阱 + 回归
+- [ ] aria 属性按场景使用（不滥用）
+- [ ] 对比度达标
+- [ ] 不依赖颜色传递信息
+- [ ] 支持 Reduced Motion
+- [ ] 自动化扫描零 critical
+- [ ] （Web 实现）见 `frontend/a11y-web` 的补充门禁