@captain_z/zsk-skills 0.1.0

package/README.md

@@ -0,0 +1,263 @@
+# @captain_z/zsk-skills
+
+ZNorth Standard Kit 的内容包：**46 颗原子 skill**，按领域分簇组织，通过 `npx @captain_z/zsk add` 可安装到 Claude / Codex / Gemini 等多 harness。
+
+## 合规审查（ARCHITECTURE §4.4 硬指标）
+
+| 检查项 | 结果 | 说明 |
+| --- | --- | --- |
+| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 46/46 | 结构化 lint 通过 |
+| `name` 以 `zsk:` 前缀，扁平 slug | ✓ 46/46 | 命名空间统一 |
+| `description` 以 `Use when…` 开头（trigger-optimized） | ✓ 46/46 | 触发匹配句式 |
+| `category` / `domain` / `tier` 枚举值合法 | ✓ 46/46 | stage/workflow/standard/resource/meta · core/optional |
+| `triggers` 数组非空 | ✓ 46/46 | 每颗至少 4 个关键词 |
+| 无硬编码项目名 / 技术栈（统一 `{{config.*}}` 占位符） | ✓ | harness-neutral |
+| `related:` 相对路径合法（build 已重写） | ✓ | 无孤儿引用 |
+| 单文件 ≤ 300 行 | ⚠ 41/46 | 5 个 frontend skill 超标（见技术债） |
+
+**技术债**（不阻塞 CI，`tools/lint-frontmatter.ts` 当前降级 warn）：
+
+| 文件 | 行数 |
+| --- | --- |
+| `frontend/a11y-web/SKILL.md` | 370 |
+| `frontend/testing-web/SKILL.md` | 351 |
+| `frontend/nfr-web/SKILL.md` | 352 |
+| `frontend/security-web/SKILL.md` | 311 |
+| `frontend/performance-web/SKILL.md` | 305 |
+
+清理手法见 `memory/project_tech_debts_lint_frontmatter.md`；完成后把 `max-lines` 从 `warn` 升回 `error`。
+
+## 使用方法通则
+
+zsk skill 是 LLM **按需自动触发**的资产：
+
+1. **安装**：`npx @captain_z/zsk add` → 选 bundle（或 custom 多选）+ 目标路径（`~/.claude/skills/` / `~/.codex/skills/` / 自定义）→ 落盘
+2. **自动发现**：LLM（Claude Code / Codex / Gemini CLI）会话启动时扫描 skill 目录，读取每份 `SKILL.md` 的 frontmatter
+3. **自动触发**：遇到匹配 `description` 或 `triggers` 的任务时，LLM 载入对应 SKILL.md 的完整内容
+4. **手动触发**（可选）：会话中显式说 "用 `zsk:spec`"、"走 `zsk:feature` 工作流"，LLM 直接载入指定 skill
+
+**典型消费路径**（production，安装后）：
+- `~/.claude/skills/<domain>/<slug>/SKILL.md` — Claude Code
+- `~/.codex/skills/<domain>/<slug>/SKILL.md` — Codex
+- `@captain_z/zsk-skills/<domain>/<slug>/SKILL.md` — 通过 npm 读
+
+## 领域总览
+
+| 领域 | skill 数 | 职责 |
+| --- | --- | --- |
+| `sdlc/` | 17 | 7 阶段 SDLC + 3 变更工作流 + task 执行框架 |
+| `frontend/` | 16 | React + Web 层实现规范 |
+| `quality/` | 5 | 跨栈质量原则 |
+| `design-handoff/` | 2 | 设计交付方法论 |
+| `system/` | 5 | 工程宪法级资源 |
+| `meta/` | 1 | 元信息 |
+| **总计** | **46** | |
+
+## 安装套件（bundles.yaml）
+
+| name | skills | 场景 |
+| --- | --- | --- |
+| `sdlc-only` | 10 | 纯流程骨架（7 阶段 + 3 工作流），不涉及技术栈 |
+| `frontend-project`（推荐） | 29 | SDLC 10 + Frontend 16 + Quality 3 |
+| `frontend-with-design-handoff` | 31 | frontend-project + Figma 交付 2 |
+| `custom` | 交互 | 通过 `zsk add` 任意多选 |
+
+## Skill 清单（按领域）
+
+> 内容由 `tools/catalog.ts` 从各 SKILL.md frontmatter 生成。重生成：`pnpm catalog`。
+
+### `sdlc/` — SDLC · 7 阶段 + 3 变更工作流 + task 框架（17）
+
+- **`zsk:proposal`** *[stage 1 · stage · core]*
+  Use when starting a new change (feature / bugfix / refactor) and you need to frame the why, success criteria, out-of-scope boundary, alternatives considered, and risks before any spec work. Always the first stage of the 7-stage SDLC.
+  触发：`new feature proposal` · `bug report` · `refactor trigger` · `SMART goals`
+
+- **`zsk:spec`** *[stage 2 · stage · core]*
+  Use when the proposal is approved and you need to write the behavioral contract — User Stories (INVEST), FR / NFR / AC numbering, BDD scenarios, edge cases, term glossary. Stage 2 of the 7-stage SDLC.
+  触发：`writing spec` · `user stories` · `acceptance criteria` · `FR NFR numbering`
+
+- **`zsk:design`** *[stage 3 · stage · core]*
+  Use when the spec is frozen and you need to translate FR/NFR into concrete implementation plans — ADR decisions, architecture diagrams (C4 + sequence), file responsibilities, FR→code mapping, error handling, rollback, observability. Stage 3 of the 7-stage SDLC.
+  触发：`technical design` · `ADR architecture decision` · `C4 diagram` · `FR mapping`
+
+- **`zsk:coding`** *[stage 4 · stage · core]*
+  Use when the design is frozen and you need to execute — write code and tests, follow branch/commit conventions, enforce TDD for bugfix/refactor, respect dependency hygiene, pass local quality gates before review. Stage 4 of the 7-stage SDLC.
+  触发：`implementing design` · `TDD red green refactor` · `conventional commits` · `gitlab flow`
+
+- **`zsk:reviewing`** *[stage 5 · stage · core]*
+  Use when submitting or receiving a PR for code review — self-checklist, reviewer checklist, Conventional Comments prefixes, technical-rigor-over-performative-agreement when receiving feedback, dispute escalation path. Stage 5 of the 7-stage SDLC. This is the code-view (does the diff look right); the contract-view is zsk:verify.
+  触发：`code review` · `PR review` · `conventional comments` · `receiving feedback`
+
+- **`zsk:verify`** *[stage 6 · stage · core]*
+  Use when about to merge to main — the hard "evidence before assertion" gate. Requires DoD fully green, FR coverage matrix complete, AC checklist ticked with links, validation records with reproducible evidence. Stage 6 of the 7-stage SDLC. This is the contract-view; the code-view is zsk:reviewing.
+  触发：`acceptance verification` · `definition of done` · `FR coverage matrix` · `evidence before assertion`
+
+- **`zsk:archive`** *[stage 7 · stage · core]*
+  Use when closing an iteration — move historical snapshots to docs/{module}/archive/, write postmortem (P0/P1 mandatory), update changelog (SemVer + Keep a Changelog), flush ADRs, update SYSTEM-SPEC if cross-module constraints emerged, feed back to standards/system docs. Stage 7 of the 7-stage SDLC.
+  触发：`archive iteration` · `postmortem` · `changelog` · `ADR flush`
+
+- **`zsk:bugfix-tasks`** *[core]*
+  Use when implementing a bugfix — the TDD-enforced task template. Step 1 Red (write failing reproduction test), Step 2 Green (minimal fix, no opportunistic refactor), Step 3 Regression (adjacent scenarios), Step 4 Evidence (before/after reproduction). Requires Superpowers' 3 confidence questions before starting.
+  触发：`bugfix task template` · `TDD bug fix` · `red green regression` · `bug confidence questions`
+
+- **`zsk:dor-dod`** *[core]*
+  Use when transitioning between SDLC stages to gate starting a task (DoR) and closing a task (DoD). Generic DoR/DoD for all change types; frontend-specific rows (UE matrix / ue-mcp / 三语 i18n / 视觉回归 / axe) are in frontend:dor-dod-frontend.
+  触发：`definition of ready` · `definition of done` · `DoR DoD` · `task gate`
+
+- **`zsk:refactor-tasks`** *[core]*
+  Use when implementing a refactor — the characterization + small-step atomic task template. Step 1 capture behavior baseline, Step 2 apply one Fowler technique per atomic commit (revert on red), Step 3 Parallel Change for large refactors (Expand → Migrate → Contract), Step 4 prepare behavior-unchanged evidence.
+  触发：`refactor task template` · `characterization baseline` · `Fowler techniques` · `Parallel Change tasks`
+
+- **`zsk:task`** *[core]*
+  Use when you need the cross-stage task execution mindset — what a task is, how it threads spec → verify, which template to pick by change type, cross-stage hard principles. Not for writing a specific task; use zsk:task-structure for that.
+  触发：`task framework` · `task execution overview` · `cross-stage tasks` · `which task template`
+
+- **`zsk:task-evidence`** *[core]*
+  Use when handing a task to verify — fill the FR coverage matrix (every FR/NFR from spec has coverage task + acceptance evidence), AC checklist with reproducible links, validation records per gate (lint/type-check/test/security/etc.). Enforces "evidence before assertion" — links must be clickable and reproducible.
+  触发：`FR coverage matrix` · `AC verification` · `validation record` · `evidence links`
+
+- **`zsk:task-structure`** *[core]*
+  Use when writing a tasks.md — set task granularity (0.5-2 person-days), two-level structure (parent/child, no deeper), estimation unit (T-shirt or Fibonacci), required fields per task (status/owner/covers-FR/deliverable/verification), FR coverage numbering rules.
+  触发：`task granularity` · `task estimation` · `T-shirt sizing` · `story points`
+
+- **`zsk:task-tracking`** *[core]*
+  Use when executing tasks and tracking dependencies (Mermaid graph), blockers (dated log with severity H/M/L and escalation rules), milestones (stage exits with committed dates), and task state transitions (TODO → DOING → DONE, with BLOCKED requiring log entry). Includes **§6 每任务交互契约**：LLM 执行单任务后必须 "更新状态 → 填证据 → 短汇报 → 等人类确认"，不自动连跑。
+  触发：`task dependency graph` · `blocker log` · `milestones` · `task state flow`
+
+- **`zsk:bugfix`** *[workflow · core]*
+  Use when fixing an existing defect end-to-end — triage → reproduce → RCA (5 Whys with confidence questions) → TDD fix (red first) → regression coverage → postmortem (P0/P1 mandatory). Enforces Superpowers' bug confidence questioning discipline.
+  触发：`bug fix workflow` · `fix defect` · `RCA` · `5 whys`
+
+- **`zsk:feature`** *[workflow · core]*
+  Use when building a new feature end-to-end — orchestrates the 7 SDLC stages for the feature change type. Walks you through brainstorming → writing-plans → plan-eng-review → executing-plans+TDD → requesting/receiving-code-review → verification-before-completion → finishing-a-development-branch.
+  触发：`new feature workflow` · `feature end to end` · `start feature` · `feature stages`
+
+- **`zsk:refactor`** *[workflow · core]*
+  Use when refactoring code without changing observable behavior — Fowler catalog, characterization tests as baseline, small atomic commits, Parallel Change / Strangler Fig for large refactors. Enforces "behavior preserved" as a hard contract (any behavior change means it's not a refactor).
+  触发：`refactor workflow` · `Fowler refactoring` · `characterization test` · `Parallel Change`
+
+### `frontend/` — Frontend · React + Web 层实现规范（16）
+
+- **`zsk:spec-frontend`** *[stage 2 · stage · optional]*
+  Use when writing spec.md for a frontend component / page — adds Component Public Contract (Props / Events / TS types), UE state matrix with a11y attributes, UE/MCP reference, and the 6-category Frontend NFR (performance / a11y / security / i18n / compat / observability). Extends the generic zsk:spec framework.
+  触发：`frontend spec` · `Component Public Contract` · `Props Event Contract` · `UE state matrix`
+
+- **`zsk:design-frontend`** *[stage 3 · stage · optional]*
+  Use when writing design.md for a frontend module — adds Props/state/event implementation mapping, UE-state-to-structure mapping, Figma-to-implementation mapping, performance budget (Core Web Vitals), ErrorBoundary placement. Extends the generic zsk:design framework.
+  触发：`frontend design` · `Props implementation mapping` · `UE state to structure` · `Figma to implementation`
+
+- **`zsk:review-frontend`** *[stage 5 · stage · optional]*
+  Use when reviewing frontend code in a PR — frontend-specific self-checklist and reviewer checklist covering TypeScript red lines (no any / @ts-ignore), React hooks rules, dangerouslySetInnerHTML, large-list performance hazards, visual regression, i18n three-language sync, jsx-a11y. Extends zsk:reviewing generic checklist.
+  触发：`frontend code review` · `React review checklist` · `TypeScript red lines` · `hooks review`
+
+- **`zsk:dor-dod-frontend`** *[optional]*
+  Use when transitioning between SDLC stages for frontend modules — frontend-specific DoR/DoD rows on top of the generic checklist. Covers UE state matrix completeness, ue-mcp.md registration, visual regression, three-language i18n sync, a11y (keyboard/aria/focus), frontend NFR (CWV) evidence.
+  触发：`frontend DoR DoD` · `frontend definition of ready done` · `UE matrix gate` · `visual regression gate`
+
+- **`zsk:feature-tasks-frontend`** *[optional]*
+  Use when building a new frontend component/page feature — the 7-category mandatory task template (事实源对齐 / Props 契约 / UE-MCP 刷新 / UE 状态 / 测试 / 视觉回归 / 质量门禁). Enforces TDD-first, contract-driven, evidence-before-assertion.
+  触发：`frontend feature tasks` · `component tasks template` · `7 category tasks` · `Props UE state visual regression`
+
+- **`zsk:nfr-web`** *[optional]*
+  Use when establishing concrete Web-side thresholds for the 7-category NFR framework — Core Web Vitals (LCP/INP/CLS/TTFB/TTI targets), WCAG 2.1 AA itemized rules, Web security NFR items, i18n language list + baseline + entry + RTL, browser/OS/device compatibility matrix, responsive breakpoints, observability (web-vitals + error reporting), reliability (ErrorBoundary + timeout + retry). Inherits system/nfr-baseline; modules declare deviations only.
+  触发：`Web NFR` · `CWV thresholds` · `WCAG AA rules` · `browser matrix`
+
+- **`zsk:a11y-web`** *[standard · optional]*
+  Use when implementing accessibility in React/JSX — label association (htmlFor/wrap), aria props usage, Modal focus trap (inert + initialFocus + restoreFocus), dialog role, live regions for async, skip link, axe-core + jsx-a11y toolchain, keyboard event handlers, prefers-reduced-motion. Implementation layer; principles (WCAG, POUR, contrast) live in quality/a11y-principles.
+  触发：`jsx a11y` · `focus trap` · `Modal accessibility` · `axe-core`
+
+- **`zsk:api-contract-ts`** *[standard · optional]*
+  Use when integrating a TypeScript frontend with a backend API — never hand-write API types, always consume from the shared types package or generated codegen. Covers source-of-truth pattern (backend-owned types), codegen workflows (OpenAPI / GraphQL / tRPC / Protobuf), breaking-change handling, version discipline, runtime validation (Zod at boundary), and service-layer shape. Pairs with typescript.md red lines.
+  触发：`API type sync` · `do not hand-write API types` · `OpenAPI codegen` · `GraphQL codegen`
+
+- **`zsk:css-bem`** *[standard · optional]*
+  Use when writing CSS / Less / Sass / CSS Modules / Tailwind in a frontend module — CSS scheme detection (Less/Sass/CSS Modules/Tailwind/native), BEM naming (Block__Element--Modifier), nesting discipline (≤3 layers), token usage rules (no hardcoded color/spacing), scope isolation, responsive breakpoints, and !important prohibition.
+  触发：`CSS scheme detection` · `BEM naming` · `Less nesting` · `design token`
+
+- **`zsk:i18n`** *[standard · optional]*
+  Use when implementing i18n in a frontend module — unified entry (i18n.t with mandatory fallback), key namespace structure (namespace.module.leaf_key), three-language sync rule (commit-atomic), ICU MessageFormat for plural/select, Intl.* for date/number/currency, RTL declaration, React Trans component for JSX interpolation. Replaces standards/i18n for frontend scope.
+  触发：`i18n implementation` · `key namespace` · `fallback baseline` · `ICU plural`
+
+- **`zsk:performance-web`** *[standard · optional]*
+  Use when optimizing a React / Web frontend for Core Web Vitals — CWV thresholds (LCP/INP/CLS/TTFB/TTI), React memoization discipline (when to memo vs not), virtualization for lists ≥ 200, lazy loading via React.lazy + Suspense + IntersectionObserver, bundle splitting + tree-shaking, image srcset + loading="lazy", debounce/throttle, re-render diagnosis with React DevTools Profiler. Implementation layer; budget framework in system/nfr-baseline + frontend/nfr-web.
+  触发：`Core Web Vitals` · `LCP INP CLS` · `React memo` · `virtual scrolling`
+
+- **`zsk:react-components`** *[standard · optional]*
+  Use when designing React component APIs — layering (UI/logic separation via hooks), composition vs configuration (compound components over flat-prop explosion), granularity (5-question checklist), controlled vs uncontrolled boundary, Props API design. React-specific implementation of generic component discipline.
+  触发：`React component design` · `compound components` · `component granularity` · `controlled uncontrolled`
+
+- **`zsk:react-naming`** *[standard · optional]*
+  Use when naming React components, files, folders, variables, booleans, event handlers, event props, hooks, TS types/interfaces, constants, and i18n keys — the complete naming convention table for a React + TypeScript codebase. Principles transfer to Vue/Svelte with syntax adjustments.
+  触发：`React naming` · `component file naming` · `event handler naming` · `boolean naming`
+
+- **`zsk:security-web`** *[standard · optional]*
+  Use when addressing Web frontend security — XSS (React default escape + dangerouslySetInnerHTML red line + DOMPurify exception), URL protocol whitelist, Storage red lines (no sensitive data in Local/SessionStorage), CSRF token integration, console log scrubbing for production, CSP meta/header consumption, SRI for third-party scripts, clickjacking (frame-ancestors awareness), postMessage origin checks. Frontend UI is the convenience defense; backend is final.
+  触发：`dangerouslySetInnerHTML` · `XSS React` · `DOMPurify` · `LocalStorage sensitive`
+
+- **`zsk:testing-web`** *[standard · optional]*
+  Use when setting up or writing frontend tests for a React codebase — the full toolchain (Jest/Vitest + React Testing Library + renderHook + user-event + MSW + Playwright + Chromatic + jest-axe), test structure (AAA/GWT), mock strategy (MSW for HTTP, manual for modules), coverage thresholds (new code / global), and the component test template. Implementation layer; cross-stack principles live in quality/testing-pyramid.
+  触发：`Jest Vitest` · `React Testing Library` · `MSW mock service worker` · `Playwright`
+
+- **`zsk:typescript`** *[standard · optional]*
+  Use when writing TypeScript in a frontend codebase — 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.
+  触发：`TypeScript red lines` · `no any` · `strict mode` · `noUncheckedIndexedAccess`
+
+### `quality/` — Quality · 跨栈质量原则（5）
+
+- **`zsk:a11y-principles`** *[standard · optional]*
+  Use when thinking about accessibility 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.
+  触发：`accessibility principles` · `WCAG AA` · `POUR` · `keyboard matrix`
+
+- **`zsk:code-hygiene`** *[standard · optional]*
+  Use when writing code in any language — comment policy (WHY not WHAT), import ordering principle, formatter discipline, generic forbidden patterns (TODO comments, commented-out code, signature-like comments). Stack-specific rules (TypeScript red lines, React naming) are in frontend/*.
+  触发：`code hygiene` · `comment policy` · `import order` · `WHY not WHAT`
+
+- **`zsk:release`** *[standard · optional]*
+  Use when shipping a version — SemVer numbering, Keep a Changelog, Conventional Changelog auto-generation, environment promotion (dev→test→pre→prod), feature flag lifecycle, rollback strategy, hotfix process, canary monitoring. Works across language stacks; tool names are stack-specific examples.
+  触发：`SemVer` · `changelog` · `conventional changelog` · `hotfix`
+
+- **`zsk:security-owasp`** *[standard · optional]*
+  Use when addressing cross-stack security concerns — OWASP Top 10 overview, CVE response SLAs, dependency license whitelist, supply chain hygiene, common lint red lines (eval/dynamic execution), and the "frontend UI is not the final defense" principle. Web-specific XSS/CSRF/Storage red lines are in frontend/security-web.md.
+  触发：`OWASP Top 10` · `CVE response` · `license whitelist` · `supply chain security`
+
+- **`zsk:testing-pyramid`** *[standard · optional]*
+  Use when designing test strategy or writing tests in any language — the test pyramid ratio (unit 70 / integration 20 / e2e 10), AAA/GWT structure, coverage targets, and the three hard principles (evidence before assertion, Red-Green-Refactor, bug confidence questioning). Stack-specific tooling (Jest/RTL/MSW/Playwright) is in frontend/testing-web.md.
+  触发：`test pyramid` · `TDD discipline` · `test coverage target` · `AAA GWT structure`
+
+### `design-handoff/` — Design Handoff · 设计交付方法论（2）
+
+- **`zsk:figma-to-code`** *[optional]*
+  Use when reading a Figma design node via MCP and producing production-grade code — the 7-step workflow (locate → extract structure → extract annotations → naming conversion → layout decoding → states → tokens), plus the 4-dimension "100% fidelity" verification (visual / interaction / semantic / responsive). CSS/BEM specifics live in zsk:css-bem.
+  触发：`figma to code` · `100 percent fidelity` · `node naming conversion` · `design annotations`
+
+- **`zsk:ue-mcp`** *[optional]*
+  Use when the module has Figma/design input and you need to capture Design Source (URL/node-id), MCP readout status, module-specific UE deviations from system baselines, and implementation mapping. Produces docs/{module}/ue-mcp.md + structured description.md snapshot in design-assets. Only records deviations, not duplicated baseline rules.
+  触发：`UE MCP context` · `figma snapshot` · `design source reference` · `module UE deviation`
+
+### `system/` — System · 工程宪法级资源（5）
+
+- **`zsk:adr`** *[optional]*
+  Use when recording a cross-module, long-lived architectural decision that has alternatives worth weighing — with context, decision, rationale, alternatives considered, and consequences. Produces docs/system/adrs/ADR-NNNN-{slug}.md. Not for single-module implementation choices.
+  触发：`architecture decision record` · `ADR template` · `MADR` · `cross-module decision`
+
+- **`zsk:architecture`** *[optional]*
+  Use when documenting the project's overall system architecture — C4 context diagram, tech stack baseline, module boundaries, routing, auth flow, data flow (request/state/contract), deployment topology, related ADRs. Frontend micro-frontend topology is an optional add-on section.
+  触发：`system architecture` · `C4 model` · `tech stack baseline` · `module boundaries`
+
+- **`zsk:glossary`** *[optional]*
+  Use when bootstrapping or maintaining the project's Ubiquitous Language — the single source for business terms, domain entities, state names, technical terms, and acronyms. Eliminates same-concept-different-names confusion across modules and backend contracts.
+  触发：`glossary` · `ubiquitous language` · `DDD terms` · `business term`
+
+- **`zsk:nfr-baseline`** *[optional]*
+  Use when establishing or inheriting the project's non-functional requirements baseline — the 7-category framework (performance / a11y / security / i18n / compatibility / observability / reliability) and the deviation-declaration discipline. Web-specific values (CWV thresholds, WCAG AA, browser matrix, 三语) live in frontend/nfr-web.md.
+  触发：`NFR baseline` · `non functional requirements` · `quality attributes` · `ISO 25010`
+
+- **`zsk:project-constraints-template`** *[optional]*
+  Use when bootstrapping a new project to capture import origins, forbidden libraries/patterns, required wrappers, naming conventions, quality gates, branch/release conventions in one SYSTEM-SPEC chapter. The project-side constitutional constraint table, complementary to project-config.yaml (mechanical values).
+  触发：`project constraints` · `SYSTEM-SPEC` · `import origins` · `forbidden packages`
+
+### `meta/` — Meta · 元信息（1）
+
+- **`zsk:philosophy`** *[meta · optional]*
+  Use when you need to understand the design rationale of the zsk skill set (LLM Wiki × Superpowers × GSD × project-adaptation synthesis), or when explaining why zsk is organized the way it is to a new contributor.
+  触发：`zsk philosophy` · `why is zsk organized this way` · `design rationale` · `LLM wiki vs superpowers`

package/bundles.yaml

@@ -0,0 +1,104 @@
+# @captain_z/zsk-skills · installation bundles
+#
+# Flat-list model: every bundle explicitly lists the skills it installs.
+# No extends/inheritance — see ARCHITECTURE.md §5 for rationale.
+
+bundles:
+  sdlc-only:
+    label: 纯 SDLC 流程骨架
+    hint: 7 阶段 + 3 变更工作流，不涉及技术栈
+    skills:
+      # stages (7)
+      - zsk:proposal
+      - zsk:spec
+      - zsk:design
+      - zsk:coding
+      - zsk:reviewing
+      - zsk:verify
+      - zsk:archive
+      # workflows (3)
+      - zsk:feature
+      - zsk:bugfix
+      - zsk:refactor
+
+  frontend-project:
+    label: 前端项目（推荐）
+    hint: SDLC + 前端领域 + 质量规范
+    skills:
+      # SDLC 10
+      - zsk:proposal
+      - zsk:spec
+      - zsk:design
+      - zsk:coding
+      - zsk:reviewing
+      - zsk:verify
+      - zsk:archive
+      - zsk:feature
+      - zsk:bugfix
+      - zsk:refactor
+      # Frontend 16 (5 SDLC overlays + 11 standards)
+      - zsk:spec-frontend
+      - zsk:design-frontend
+      - zsk:review-frontend
+      - zsk:dor-dod-frontend
+      - zsk:feature-tasks-frontend
+      - zsk:react-components
+      - zsk:react-naming
+      - zsk:typescript
+      - zsk:css-bem
+      - zsk:i18n
+      - zsk:a11y-web
+      - zsk:performance-web
+      - zsk:security-web
+      - zsk:testing-web
+      - zsk:api-contract-ts
+      - zsk:nfr-web
+      # Quality 3
+      - zsk:testing-pyramid
+      - zsk:security-owasp
+      - zsk:a11y-principles
+
+  frontend-with-design-handoff:
+    label: 前端 + 设计交付（Figma）
+    hint: frontend-project 之上再加 Figma 交付方法论
+    skills:
+      # SDLC 10
+      - zsk:proposal
+      - zsk:spec
+      - zsk:design
+      - zsk:coding
+      - zsk:reviewing
+      - zsk:verify
+      - zsk:archive
+      - zsk:feature
+      - zsk:bugfix
+      - zsk:refactor
+      # Frontend 16
+      - zsk:spec-frontend
+      - zsk:design-frontend
+      - zsk:review-frontend
+      - zsk:dor-dod-frontend
+      - zsk:feature-tasks-frontend
+      - zsk:react-components
+      - zsk:react-naming
+      - zsk:typescript
+      - zsk:css-bem
+      - zsk:i18n
+      - zsk:a11y-web
+      - zsk:performance-web
+      - zsk:security-web
+      - zsk:testing-web
+      - zsk:api-contract-ts
+      - zsk:nfr-web
+      # Quality 3
+      - zsk:testing-pyramid
+      - zsk:security-owasp
+      - zsk:a11y-principles
+      # Design-handoff 2
+      - zsk:figma-to-code
+      - zsk:ue-mcp
+
+  custom:
+    label: 自选
+    hint: 通过 zsk add 交互多选每颗 skill
+    skills: []

package/design-handoff/figma-to-code/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: zsk:figma-to-code
+description: Figma design node → production code via MCP — 7-step workflow
+  (locate → extract structure → extract annotations → naming conversion → layout
+  decoding → states → tokens), plus the 4-dimension "100% fidelity" verification
+  (visual / interaction / semantic / responsive). CSS/BEM specifics live in
+  zsk:css-bem.
+category: resource
+domain: design-handoff
+tier: optional
+related:
+  - ../ue-mcp/SKILL.md
+  - ../../frontend/css-bem/SKILL.md
+  - ../../frontend/a11y-web/SKILL.md
+  - ../../frontend/react-components/SKILL.md
+triggers:
+  - figma to code
+  - 100 percent fidelity
+  - node naming conversion
+  - design annotations
+  - auto layout to flex
+  - MCP design tokens
+---
+
+# Figma → Code 工作流规范
+
+> **目标**：以最少的主观猜测、最高的还原度，从 Figma 设计稿产出生产级代码
+> **适用**：有视觉 / 交互设计输入的模块
+> **CSS 实现细节**：BEM / Less 嵌套 / token 引用见 [`frontend/css-bem`](../../frontend/css-bem/SKILL.md)（本文件只讲方法论）
+
+## 核心挑战
+
+1. **Figma 节点名不规范**（`Frame 123` / `Rectangle 45` / `矩形 28`）
+2. **布局属性散落**（auto-layout / constraints / 绝对定位混合）
+3. **状态和变体分散**（Variants / frames / 命名暗示多源混杂）
+4. **设计 token 未统一**（硬编码色值与变量并存）
+5. **设计批注容易被忽略**（画面上看不到的关键交互 / UX / a11y / 边界信息）
+6. **"100% 还原"没有客观标准**，必须先定义可验收维度
+
+## 工作流（7 步）
+
+```text
+1. 定位目标  →  2. 提取结构  →  3. 提取批注  →  4. 命名转换  →  5. 布局解码
+                                                                         ↓
+                      7. Token 提取  ←  6. 状态与变体识别
+```
+
+### Step 1：定位 + 对齐目标
+
+**Tools**：`mcp__figma-mcp-go__get_pages` / `navigate_to_page` / `get_selection` / `get_node`
+
+- 获取 Figma URL 与 `node-id`（见 `FIGMA-INDEX.md`）
+- 明确"我要还原的节点"
+- 多变体 / 多页面 → 在 `description.md` 列出并标注范围
+
+### Step 2：提取结构（节点层级）
+
+**Tools**：`get_metadata` / `get_nodes_info`
+
+- 获取节点树 + 每节点类型 / 尺寸 / 内容
+- 记录到 `description.md` 的"节点层级"章节
+- 同步做节点命名转换（Step 4）
+
+### Step 3：提取设计批注（Annotations）
+
+**Tool**：`mcp__figma-mcp-go__get_annotations`
+
+> 🔑 **批注是 Figma 画面之外的关键信息源**。不提取会出现"视觉对了但行为错了"。
+
+常见批注类别：
+
+| 类别 | 示例 |
+| --- | --- |
+| 交互 | "输入 500ms 防抖" / "hover 延迟 0.2s" |
+| 视觉 | "hover 颜色必须为 brand/soft" / "0.2s ease-out 过渡" |
+| UX 边界 | "文字 > 20 字 ellipsis + title" / "列表 > 100 项虚拟滚动" |
+| a11y | "必须支持 Enter/Space 触发" / "选中需 aria-selected" |
+| 空 / 错误态 | "空态文案：暂无数据" / "加载失败显示重试按钮" |
+| 性能 | "首屏只渲染前 50 项" |
+| 待确认 | "TODO: 这里和 XX 对齐后补" |
+
+#### 执行要点
+
+1. 调用 `get_annotations`
+2. MCP 未返回时**回退手工扫描**：画布文字框 / 标签 / 箭头 / Sticky Notes / Inspector Panel 的 Annotations
+3. 所有批注记录到 `description.md`，**每条必须有落实追踪**
+
+#### 批注表（必入 description.md）
+
+| 批注位置 | 类别 | 内容 | 责任 | 已落实 |
+| --- | --- | --- | --- | --- |
+| search-input | 交互 | 输入 500ms 防抖 | 前端 | [ ] |
+| node-item | a11y | 必须支持 Enter/Space | 实现 + 测试 | [ ] |
+| long-name | 边界 | > 20 字符 ellipsis + title | 前端 | [ ] |
+
+**原则**：每条批注必有**责任归属** + **已落实标记**（未落实的进入 `tasks.md`）
+
+### Step 4：节点命名转换（关键！）
+
+Figma 原名往往不规范，必须转换为 **语义化 + 可搜索 + 与代码对齐** 的命名。
+
+#### 命名维度（必填映射表）
+
+| 维度 | 目的 | 示例 |
+| --- | --- | --- |
+| Figma 原名 | 溯源 | `Frame 123` |
+| 语义角色 | CSS 命名基础 | `search-input` |
+| 组件名 | JSX 定位 | `FeatureTreeSearch` |
+| CSS class | 样式落地 | `.feature-tree__search` |
+| 状态修饰符 | 变体 | `.feature-tree__node--selected` |
+
+#### 命名转换原则
+
+1. **语义化，不视觉化**（✅ `.feature-tree__node` / ❌ `.blue-box`）
+2. **BEM 约定**（Block / Element / Modifier — 默认推荐，详见 [`frontend/css-bem`](../../frontend/css-bem/SKILL.md)）
+3. **与组件命名对齐**（组件 `FeatureTree` → Block class `.feature-tree`）
+4. **稳定且可搜索**（Figma 改名不影响代码；跨文件 grep 能定位）
+5. **识别语义的依据**：位置 / 结构、Variants / States、内容、命名暗示
+
+### Step 5：布局解码（Auto-layout → CSS）
+
+Figma Auto-layout 到 CSS Flexbox / Grid 的映射：
+
+| Figma | CSS |
+| --- | --- |
+| Auto-layout Horizontal | `display: flex; flex-direction: row` |
+| Auto-layout Vertical | `display: flex; flex-direction: column` |
+| Auto-layout gap | `gap` |
+| Auto-layout padding | `padding` |
+| Hug contents | `width: fit-content` |
+| Fill container | `flex: 1` |
+| Absolute positioning | `position: absolute`（最后手段，优先 flex） |
+
+**原则**：固定间距 / 尺寸 → 必须转成 design token（Step 7）；绝对定位是**最后手段**。
+
+### Step 6：状态与变体识别
+
+**Tools**：`get_nodes_info` + `save_screenshots`
+
+Figma Variants → 组件状态：
+
+- 每个 variant 对应一个状态（default / hover / focus / focus-visible / selected / disabled / error / empty / loading）
+- 记录每 variant 与 default 的**差异**（不重复描述全部）
+- 每个 variant 单独截图保存到 `screenshot-{state}.png`
+
+#### 状态矩阵模板
+
+| 状态 | 触发条件 | 与 default 差异 | 截图 | a11y 属性 |
+| --- | --- | --- | --- | --- |
+| default | — | — | screenshot-default.png | — |
+| hover | 鼠标悬浮 | bg 变浅 | screenshot-hover.png | — |
+| focus-visible | 键盘 Tab 聚焦 | outline 2px brand | screenshot-focus.png | — |
+| selected | 点击选中 | bg / text 变色 | screenshot-selected.png | `aria-selected="true"` |
+| disabled | 禁用 | opacity 0.4 | screenshot-disabled.png | `aria-disabled="true"` |
+
+### Step 7：Token 提取
+
+**Tools**：`get_variable_defs` / `export_tokens`
+
+从 Figma 变量定义导出：
+- **颜色**（背景 / 文字 / 边框 / 品牌色）
+- **字体**（family / size / weight / line-height）
+- **圆角 / 阴影 / 边框**
+- **间距**（padding / gap / margin）
+
+映射到代码：
+1. **优先使用项目 UI 库 token**（`{{config.stack.ui_lib}}` 已覆盖的）
+2. UI 库未覆盖时，写入模块内样式变量或 CSS custom property
+3. **禁止硬编码色值 / 间距散落**
+
+## 100% 还原判定（四维度）
+
+"100% 还原" 不是模糊概念，而是**四维度**客观验收：
+
+### 视觉维度
+
+- [ ] 布局尺寸一致（±1px 容差）
+- [ ] 色值精确（按 token 对照）
+- [ ] 字体 / 行高 / 字重一致
+- [ ] 圆角 / 阴影 / 边框一致
+- [ ] 所有状态视觉一致
+
+**验证**：截图对照 + 像素差异工具
+
+### 交互维度
+
+- [ ] Figma Prototype 所有交互可复现
+- [ ] 动效时长 / 缓动曲线一致
+- [ ] 反馈态（loading / empty / error）存在且正确
+- [ ] `prefers-reduced-motion` 下有降级
+
+**验证**：录屏对照 + 自动化交互测试
+
+### 语义维度
+
+- [ ] WCAG 2.1 AA 达标（见 [`quality/a11y-principles`](../../quality/a11y-principles/SKILL.md) + [`frontend/a11y-web`](../../frontend/a11y-web/SKILL.md)）
+- [ ] 键盘操作矩阵完整
+- [ ] 读屏抽检通过
+- [ ] 对比度达标
+
+**验证**：axe-core + 手工键盘 / 读屏测试
+
+### 响应式维度
+
+- [ ] 断点切换行为一致
+- [ ] 极端尺寸不破坏布局
+- [ ] 浏览器缩放 200% 不断字不截断
+
+**验证**：断点截图对照 + 手工测试
+
+**任一维度不达标 → 不视为"100% 还原"**
+
+## MCP 工具调用推荐顺序
+
+```text
+1. get_pages                       → 定位页面
+2. navigate_to_page                → 切到目标
+3. get_selection / get_node        → 锚定 node-id
+4. get_metadata                    → 结构元数据
+5. get_nodes_info                  → 详细尺寸 / 变量
+6. get_annotations                 → 批注（**关键**）
+7. get_variable_defs               → token
+8. scan_text_nodes                 → i18n 抽取
+9. save_screenshots                → 状态截图归档
+10. [人工] 生成 description.md
+11. [人工] 命名转换映射表
+```
+
+**批注兜底**：`get_annotations` 返回空 → 手工扫描画布。
+
+## 产物清单（必交付）
+
+- [ ] `{{config.paths.design_assets}}/{module}/{snapshot}/description.md`
+- [ ] `screenshot-*.png`（每状态一张）
+- [ ] `docs/{module}/ue-mcp.md`（引用 description.md）
+- [ ] 组件代码 + 样式（遵循 [`frontend/css-bem`](../../frontend/css-bem/SKILL.md)）
+- [ ] i18n 三语文案（若适用，含批注中文案）
+- [ ] 单元测试（覆盖状态矩阵每一项）
+- [ ] **批注落实追踪**
+- [ ] 视觉对照证据（pixel diff / 并排截图）
+
+## 常见陷阱
+
+| 陷阱 | 应对 |
+| --- | --- |
+| 用 Figma 原名直接作为 class | 转换为语义 BEM |
+| 硬编码色值 | 用 token |
+| 把每个 variant 当独立组件 | 用组件 state 表达变体 |
+| 忽略 auto-layout 语义 | 映射到 flex |
+| **忽略设计批注** | **必调 `get_annotations`；MCP 空必手工扫描** |
+| **批注只看不落实** | **批注表含"已落实"列 + 未落实进 tasks.md** |
+| 跳过 a11y | a11y 是 Figma 之外的硬要求，必补 |
+| 状态 variants 过多 | 只保留**独立状态**，内容差异不单独 variant |
+
+## 质量门禁
+
+- [ ] 节点命名映射表完整
+- [ ] Token 映射表完整（无硬编码）
+- [ ] 状态矩阵含 diff + 截图 + a11y 属性
+- [ ] **设计批注表完整**（含类别 / 责任 / 已落实列）
+- [ ] **批注已全部落实或关联 tasks.md**
+- [ ] BEM 命名一致（见 `frontend/css-bem`）
+- [ ] 布局用 flex / grid，绝对定位有理由
+- [ ] 四维度 100% 还原清单全绿
+- [ ] description.md 与代码交叉一致