@captain_z/zsk-skills 0.1.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -91
- package/bundles.yaml +2 -2
- package/design-handoff/figma-to-code/SKILL.md +7 -7
- package/frontend/nfr-web/SKILL.md +1 -1
- package/frontend/review-frontend/SKILL.md +1 -1
- package/frontend/{css-bem → styling-system}/SKILL.md +14 -8
- package/package.json +1 -1
- package/sdlc/coding/SKILL.md +125 -114
- package/sdlc/design/SKILL.md +144 -201
- package/sdlc/spec/SKILL.md +167 -125
- package/sdlc/verify/SKILL.md +103 -120
- package/design-handoff/.gitkeep +0 -0
- package/frontend/.gitkeep +0 -0
- package/meta/.gitkeep +0 -0
- package/quality/.gitkeep +0 -0
- package/sdlc/.gitkeep +0 -0
- package/system/.gitkeep +0 -0
package/README.md
CHANGED
|
@@ -4,26 +4,26 @@ ZNorth Standard Kit 的内容包：**46 颗原子 skill**，按领域分簇组
|
|
|
4
4
|
|
|
5
5
|
## 合规审查（ARCHITECTURE §4.4 硬指标）
|
|
6
6
|
|
|
7
|
-
| 检查项
|
|
8
|
-
|
|
|
9
|
-
| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 46/46 | 结构化 lint 通过
|
|
10
|
-
| `name` 以 `zsk:` 前缀，扁平 slug
|
|
11
|
-
| `description` 以 `Use when…` 开头（trigger-optimized）
|
|
12
|
-
| `category` / `domain` / `tier` 枚举值合法
|
|
13
|
-
| `triggers` 数组非空
|
|
14
|
-
| 无硬编码项目名 / 技术栈（统一 `{{config.*}}` 占位符）
|
|
15
|
-
| `related:` 相对路径合法（build 已重写）
|
|
16
|
-
| 单文件 ≤ 300 行
|
|
7
|
+
| 检查项 | 结果 | 说明 |
|
|
8
|
+
| ---------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
|
|
9
|
+
| frontmatter 完整（`name` / `description` / `category` / `domain` / `tier` / `triggers`） | ✓ 46/46 | 结构化 lint 通过 |
|
|
10
|
+
| `name` 以 `zsk:` 前缀，扁平 slug | ✓ 46/46 | 命名空间统一 |
|
|
11
|
+
| `description` 以 `Use when…` 开头（trigger-optimized） | ✓ 46/46 | 触发匹配句式 |
|
|
12
|
+
| `category` / `domain` / `tier` 枚举值合法 | ✓ 46/46 | stage/workflow/standard/resource/meta · core/optional |
|
|
13
|
+
| `triggers` 数组非空 | ✓ 46/46 | 每颗至少 4 个关键词 |
|
|
14
|
+
| 无硬编码项目名 / 技术栈（统一 `{{config.*}}` 占位符） | ✓ | harness-neutral |
|
|
15
|
+
| `related:` 相对路径合法（build 已重写） | ✓ | 无孤儿引用 |
|
|
16
|
+
| 单文件 ≤ 300 行 | ⚠ 41/46 | 5 个 frontend skill 超标（见技术债） |
|
|
17
17
|
|
|
18
18
|
**技术债**（不阻塞 CI，`tools/lint-frontmatter.ts` 当前降级 warn）：
|
|
19
19
|
|
|
20
|
-
| 文件
|
|
21
|
-
|
|
|
22
|
-
| `frontend/a11y-web/SKILL.md`
|
|
23
|
-
| `frontend/testing-web/SKILL.md`
|
|
24
|
-
| `frontend/nfr-web/SKILL.md`
|
|
25
|
-
| `frontend/security-web/SKILL.md`
|
|
26
|
-
| `frontend/performance-web/SKILL.md` | 305
|
|
20
|
+
| 文件 | 行数 |
|
|
21
|
+
| ----------------------------------- | ---- |
|
|
22
|
+
| `frontend/a11y-web/SKILL.md` | 370 |
|
|
23
|
+
| `frontend/testing-web/SKILL.md` | 351 |
|
|
24
|
+
| `frontend/nfr-web/SKILL.md` | 352 |
|
|
25
|
+
| `frontend/security-web/SKILL.md` | 311 |
|
|
26
|
+
| `frontend/performance-web/SKILL.md` | 305 |
|
|
27
27
|
|
|
28
28
|
清理手法见 `memory/project_tech_debts_lint_frontmatter.md`；完成后把 `max-lines` 从 `warn` 升回 `error`。
|
|
29
29
|
|
|
@@ -37,227 +37,239 @@ zsk skill 是 LLM **按需自动触发**的资产：
|
|
|
37
37
|
4. **手动触发**（可选）：会话中显式说 "用 `zsk:spec`"、"走 `zsk:feature` 工作流"，LLM 直接载入指定 skill
|
|
38
38
|
|
|
39
39
|
**典型消费路径**（production，安装后）：
|
|
40
|
+
|
|
40
41
|
- `~/.claude/skills/<domain>/<slug>/SKILL.md` — Claude Code
|
|
41
42
|
- `~/.codex/skills/<domain>/<slug>/SKILL.md` — Codex
|
|
42
43
|
- `@captain_z/zsk-skills/<domain>/<slug>/SKILL.md` — 通过 npm 读
|
|
43
44
|
|
|
44
45
|
## 领域总览
|
|
45
46
|
|
|
46
|
-
| 领域
|
|
47
|
-
|
|
|
48
|
-
| `sdlc/`
|
|
49
|
-
| `frontend/`
|
|
50
|
-
| `quality/`
|
|
51
|
-
| `design-handoff/` | 2
|
|
52
|
-
| `system/`
|
|
53
|
-
| `meta/`
|
|
54
|
-
| **总计**
|
|
47
|
+
| 领域 | skill 数 | 职责 |
|
|
48
|
+
| ----------------- | -------- | ------------------------------------------ |
|
|
49
|
+
| `sdlc/` | 17 | 7 阶段 SDLC + 3 变更工作流 + task 执行框架 |
|
|
50
|
+
| `frontend/` | 16 | React + Web 层实现规范 |
|
|
51
|
+
| `quality/` | 5 | 跨栈质量原则 |
|
|
52
|
+
| `design-handoff/` | 2 | 设计交付方法论 |
|
|
53
|
+
| `system/` | 5 | 工程宪法级资源 |
|
|
54
|
+
| `meta/` | 1 | 元信息 |
|
|
55
|
+
| **总计** | **46** | |
|
|
55
56
|
|
|
56
57
|
## 安装套件（bundles.yaml）
|
|
57
58
|
|
|
58
|
-
| name
|
|
59
|
-
|
|
|
60
|
-
| `sdlc-only`
|
|
61
|
-
| `frontend-project`（推荐）
|
|
62
|
-
| `frontend-with-design-handoff` | 31
|
|
63
|
-
| `custom`
|
|
59
|
+
| name | skills | 场景 |
|
|
60
|
+
| ------------------------------ | ------ | --------------------------------------------- |
|
|
61
|
+
| `sdlc-only` | 10 | 纯流程骨架（7 阶段 + 3 工作流），不涉及技术栈 |
|
|
62
|
+
| `frontend-project`（推荐） | 29 | SDLC 10 + Frontend 16 + Quality 3 |
|
|
63
|
+
| `frontend-with-design-handoff` | 31 | frontend-project + Figma 交付 2 |
|
|
64
|
+
| `custom` | 交互 | 通过 `zsk add` 任意多选 |
|
|
65
|
+
|
|
66
|
+
<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 46 skills -->
|
|
67
|
+
|
|
68
|
+
<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 46 skills -->
|
|
69
|
+
|
|
70
|
+
<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 46 skills -->
|
|
71
|
+
|
|
72
|
+
<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 46 skills -->
|
|
73
|
+
|
|
74
|
+
<!-- Auto-generated by tools/catalog.ts — do not edit manually. Total: 46 skills -->
|
|
64
75
|
|
|
65
76
|
## Skill 清单（按领域）
|
|
66
77
|
|
|
67
78
|
> 内容由 `tools/catalog.ts` 从各 SKILL.md frontmatter 生成。重生成：`pnpm catalog`。
|
|
68
79
|
|
|
69
|
-
### `sdlc/` — SDLC · 7 阶段 + 3 变更工作流 + task
|
|
80
|
+
### `sdlc/` — SDLC · 7 阶段 + 3 变更工作流 + task 框架 (17)
|
|
70
81
|
|
|
71
82
|
- **`zsk:proposal`** *[stage 1 · stage · core]*
|
|
72
|
-
|
|
83
|
+
New-change framing (feature / bugfix / refactor) before spec work — why, success criteria, out-of-scope boundary, alternatives considered, and risks. Always the first stage of the 7-stage SDLC.
|
|
73
84
|
触发：`new feature proposal` · `bug report` · `refactor trigger` · `SMART goals`
|
|
74
85
|
|
|
75
86
|
- **`zsk:spec`** *[stage 2 · stage · core]*
|
|
76
|
-
|
|
77
|
-
触发：`writing spec` · `
|
|
87
|
+
Behavioral contract writing after proposal approval — scope, numbered functional and non-functional requirements, scenarios, acceptance criteria, edge cases, and impact boundaries. Stage 2 of the 7-stage SDLC.
|
|
88
|
+
触发：`writing spec` · `behavior contract` · `acceptance criteria` · `numbered requirements`
|
|
78
89
|
|
|
79
90
|
- **`zsk:design`** *[stage 3 · stage · core]*
|
|
80
|
-
|
|
81
|
-
触发：`technical design` · `
|
|
91
|
+
Solution design after spec freeze — current-state scan, architectural decisions, implementation mapping, delivery slices, risks, rollback, and observability. Stage 3 of the 7-stage SDLC.
|
|
92
|
+
触发：`technical design` · `solution design` · `architecture decision` · `current state scan`
|
|
82
93
|
|
|
83
94
|
- **`zsk:coding`** *[stage 4 · stage · core]*
|
|
84
|
-
|
|
85
|
-
触发：`implementing design` · `
|
|
95
|
+
Implementation execution after design freeze — smallest viable change, task-by-task delivery, test-first where risk is high, continuous evidence capture, and local quality gates before review. Stage 4 of the 7-stage SDLC.
|
|
96
|
+
触发：`implementing design` · `task by task delivery` · `local quality gates` · `smallest viable change`
|
|
86
97
|
|
|
87
98
|
- **`zsk:reviewing`** *[stage 5 · stage · core]*
|
|
88
|
-
|
|
99
|
+
PR 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.
|
|
89
100
|
触发：`code review` · `PR review` · `conventional comments` · `receiving feedback`
|
|
90
101
|
|
|
91
102
|
- **`zsk:verify`** *[stage 6 · stage · core]*
|
|
92
|
-
|
|
93
|
-
触发：`acceptance verification` · `
|
|
103
|
+
Acceptance verification before merge — independent contract check, FR/NFR coverage, AC evidence, gate records, and verdict with reproducible proof. Stage 6 of the 7-stage SDLC.
|
|
104
|
+
触发：`acceptance verification` · `evidence before assertion` · `FR coverage matrix` · `AC evidence`
|
|
94
105
|
|
|
95
106
|
- **`zsk:archive`** *[stage 7 · stage · core]*
|
|
96
|
-
|
|
107
|
+
Iteration closing / archive — 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.
|
|
97
108
|
触发：`archive iteration` · `postmortem` · `changelog` · `ADR flush`
|
|
98
109
|
|
|
99
110
|
- **`zsk:bugfix-tasks`** *[core]*
|
|
100
|
-
|
|
111
|
+
Bugfix task template with TDD enforcement — 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.
|
|
101
112
|
触发：`bugfix task template` · `TDD bug fix` · `red green regression` · `bug confidence questions`
|
|
102
113
|
|
|
103
114
|
- **`zsk:dor-dod`** *[core]*
|
|
104
|
-
|
|
115
|
+
DoR/DoD gates between SDLC stages — generic DoR/DoD for all change types; frontend-specific rows (UE matrix / ue-mcp / 三语 i18n / 视觉回归 / axe) are in frontend:dor-dod-frontend.
|
|
105
116
|
触发：`definition of ready` · `definition of done` · `DoR DoD` · `task gate`
|
|
106
117
|
|
|
107
118
|
- **`zsk:refactor-tasks`** *[core]*
|
|
108
|
-
|
|
119
|
+
Refactor task template (characterization + small-step atomic) — 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.
|
|
109
120
|
触发：`refactor task template` · `characterization baseline` · `Fowler techniques` · `Parallel Change tasks`
|
|
110
121
|
|
|
111
122
|
- **`zsk:task`** *[core]*
|
|
112
|
-
|
|
123
|
+
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.
|
|
113
124
|
触发：`task framework` · `task execution overview` · `cross-stage tasks` · `which task template`
|
|
114
125
|
|
|
115
126
|
- **`zsk:task-evidence`** *[core]*
|
|
116
|
-
|
|
127
|
+
Task verification evidence discipline — 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.
|
|
117
128
|
触发：`FR coverage matrix` · `AC verification` · `validation record` · `evidence links`
|
|
118
129
|
|
|
119
130
|
- **`zsk:task-structure`** *[core]*
|
|
120
|
-
|
|
131
|
+
tasks.md authoring discipline — 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.
|
|
121
132
|
触发：`task granularity` · `task estimation` · `T-shirt sizing` · `story points`
|
|
122
133
|
|
|
123
134
|
- **`zsk:task-tracking`** *[core]*
|
|
124
|
-
|
|
135
|
+
Task execution 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).
|
|
125
136
|
触发：`task dependency graph` · `blocker log` · `milestones` · `task state flow`
|
|
126
137
|
|
|
127
138
|
- **`zsk:bugfix`** *[workflow · core]*
|
|
128
|
-
|
|
139
|
+
Bugfix end-to-end orchestration — triage → reproduce → RCA (5 Whys with confidence questions) → TDD fix (red first) → regression coverage → postmortem (P0/P1 mandatory). Enforces Superpowers' bug confidence questioning discipline.
|
|
129
140
|
触发：`bug fix workflow` · `fix defect` · `RCA` · `5 whys`
|
|
130
141
|
|
|
131
142
|
- **`zsk:feature`** *[workflow · core]*
|
|
132
|
-
|
|
143
|
+
Feature end-to-end orchestration across 7 SDLC stages — brainstorming → writing-plans → plan-eng-review → executing-plans+TDD → requesting/receiving-code-review → verification-before-completion → finishing-a-development-branch.
|
|
133
144
|
触发：`new feature workflow` · `feature end to end` · `start feature` · `feature stages`
|
|
134
145
|
|
|
135
146
|
- **`zsk:refactor`** *[workflow · core]*
|
|
136
|
-
|
|
147
|
+
Behavior-preserving refactor discipline — 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 is not a refactor).
|
|
137
148
|
触发：`refactor workflow` · `Fowler refactoring` · `characterization test` · `Parallel Change`
|
|
138
149
|
|
|
139
|
-
### `frontend/` — Frontend · React + Web
|
|
150
|
+
### `frontend/` — Frontend · React + Web 层实现规范 (16)
|
|
140
151
|
|
|
141
152
|
- **`zsk:spec-frontend`** *[stage 2 · stage · optional]*
|
|
142
|
-
|
|
153
|
+
Frontend component/page spec.md authoring — 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.
|
|
143
154
|
触发：`frontend spec` · `Component Public Contract` · `Props Event Contract` · `UE state matrix`
|
|
144
155
|
|
|
145
156
|
- **`zsk:design-frontend`** *[stage 3 · stage · optional]*
|
|
146
|
-
|
|
157
|
+
Frontend module design.md authoring — 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.
|
|
147
158
|
触发：`frontend design` · `Props implementation mapping` · `UE state to structure` · `Figma to implementation`
|
|
148
159
|
|
|
149
160
|
- **`zsk:review-frontend`** *[stage 5 · stage · optional]*
|
|
150
|
-
|
|
161
|
+
Frontend PR code review — 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.
|
|
151
162
|
触发：`frontend code review` · `React review checklist` · `TypeScript red lines` · `hooks review`
|
|
152
163
|
|
|
153
164
|
- **`zsk:dor-dod-frontend`** *[optional]*
|
|
154
|
-
|
|
165
|
+
Frontend-specific DoR/DoD for SDLC stage transitions — frontend-specific 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.
|
|
155
166
|
触发：`frontend DoR DoD` · `frontend definition of ready done` · `UE matrix gate` · `visual regression gate`
|
|
156
167
|
|
|
157
168
|
- **`zsk:feature-tasks-frontend`** *[optional]*
|
|
158
|
-
|
|
169
|
+
Frontend component/page feature task template — 7-category mandatory (事实源对齐 / Props 契约 / UE-MCP 刷新 / UE 状态 / 测试 / 视觉回归 / 质量门禁). Enforces TDD-first, contract-driven, evidence-before-assertion.
|
|
159
170
|
触发：`frontend feature tasks` · `component tasks template` · `7 category tasks` · `Props UE state visual regression`
|
|
160
171
|
|
|
161
172
|
- **`zsk:nfr-web`** *[optional]*
|
|
162
|
-
|
|
173
|
+
Web-side NFR thresholds for the 7-category 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.
|
|
163
174
|
触发：`Web NFR` · `CWV thresholds` · `WCAG AA rules` · `browser matrix`
|
|
164
175
|
|
|
165
176
|
- **`zsk:a11y-web`** *[standard · optional]*
|
|
166
|
-
|
|
177
|
+
React/JSX accessibility implementation — 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.
|
|
167
178
|
触发：`jsx a11y` · `focus trap` · `Modal accessibility` · `axe-core`
|
|
168
179
|
|
|
169
180
|
- **`zsk:api-contract-ts`** *[standard · optional]*
|
|
170
|
-
|
|
181
|
+
TypeScript frontend × backend API contract — 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.
|
|
171
182
|
触发：`API type sync` · `do not hand-write API types` · `OpenAPI codegen` · `GraphQL codegen`
|
|
172
183
|
|
|
173
|
-
- **`zsk:css-bem`** *[standard · optional]*
|
|
174
|
-
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.
|
|
175
|
-
触发：`CSS scheme detection` · `BEM naming` · `Less nesting` · `design token`
|
|
176
|
-
|
|
177
184
|
- **`zsk:i18n`** *[standard · optional]*
|
|
178
|
-
|
|
185
|
+
Frontend module i18n implementation — 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.
|
|
179
186
|
触发：`i18n implementation` · `key namespace` · `fallback baseline` · `ICU plural`
|
|
180
187
|
|
|
181
188
|
- **`zsk:performance-web`** *[standard · optional]*
|
|
182
|
-
|
|
189
|
+
React / Web frontend performance 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.
|
|
183
190
|
触发：`Core Web Vitals` · `LCP INP CLS` · `React memo` · `virtual scrolling`
|
|
184
191
|
|
|
185
192
|
- **`zsk:react-components`** *[standard · optional]*
|
|
186
|
-
|
|
193
|
+
React component API design — 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.
|
|
187
194
|
触发：`React component design` · `compound components` · `component granularity` · `controlled uncontrolled`
|
|
188
195
|
|
|
189
196
|
- **`zsk:react-naming`** *[standard · optional]*
|
|
190
|
-
|
|
197
|
+
React + TypeScript naming conventions — components, files, folders, variables, booleans, event handlers, event props, hooks, TS types/interfaces, constants, and i18n keys. Principles transfer to Vue/Svelte with syntax adjustments.
|
|
191
198
|
触发：`React naming` · `component file naming` · `event handler naming` · `boolean naming`
|
|
192
199
|
|
|
193
200
|
- **`zsk:security-web`** *[standard · optional]*
|
|
194
|
-
|
|
201
|
+
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.
|
|
195
202
|
触发：`dangerouslySetInnerHTML` · `XSS React` · `DOMPurify` · `LocalStorage sensitive`
|
|
196
203
|
|
|
204
|
+
- **`zsk:styling-system`** *[standard · optional]*
|
|
205
|
+
Frontend styling system discipline — scheme detection, naming conventions, nesting depth (≤3 layers), token usage rules (no hardcoded color/spacing), scope isolation, responsive breakpoints, and !important prohibition across Less / Sass / CSS Modules / Tailwind / CSS-in-JS.
|
|
206
|
+
触发：`CSS scheme detection` · `BEM naming` · `Less nesting` · `design token`
|
|
207
|
+
|
|
197
208
|
- **`zsk:testing-web`** *[standard · optional]*
|
|
198
|
-
|
|
209
|
+
Frontend tests for React codebases — 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.
|
|
199
210
|
触发：`Jest Vitest` · `React Testing Library` · `MSW mock service worker` · `Playwright`
|
|
200
211
|
|
|
201
212
|
- **`zsk:typescript`** *[standard · optional]*
|
|
202
|
-
|
|
213
|
+
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.
|
|
203
214
|
触发：`TypeScript red lines` · `no any` · `strict mode` · `noUncheckedIndexedAccess`
|
|
204
215
|
|
|
205
|
-
### `quality/` — Quality ·
|
|
216
|
+
### `quality/` — Quality · 跨栈质量原则 (5)
|
|
206
217
|
|
|
207
218
|
- **`zsk:a11y-principles`** *[standard · optional]*
|
|
208
|
-
|
|
219
|
+
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.
|
|
209
220
|
触发：`accessibility principles` · `WCAG AA` · `POUR` · `keyboard matrix`
|
|
210
221
|
|
|
211
222
|
- **`zsk:code-hygiene`** *[standard · optional]*
|
|
212
|
-
|
|
223
|
+
Code hygiene for 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/*.
|
|
213
224
|
触发：`code hygiene` · `comment policy` · `import order` · `WHY not WHAT`
|
|
214
225
|
|
|
215
226
|
- **`zsk:release`** *[standard · optional]*
|
|
216
|
-
|
|
227
|
+
Version release discipline — 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.
|
|
217
228
|
触发：`SemVer` · `changelog` · `conventional changelog` · `hotfix`
|
|
218
229
|
|
|
219
230
|
- **`zsk:security-owasp`** *[standard · optional]*
|
|
220
|
-
|
|
231
|
+
Cross-stack security discipline — 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.
|
|
221
232
|
触发：`OWASP Top 10` · `CVE response` · `license whitelist` · `supply chain security`
|
|
222
233
|
|
|
223
234
|
- **`zsk:testing-pyramid`** *[standard · optional]*
|
|
224
|
-
|
|
235
|
+
Cross-language test strategy & discipline — 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.
|
|
225
236
|
触发：`test pyramid` · `TDD discipline` · `test coverage target` · `AAA GWT structure`
|
|
226
237
|
|
|
227
|
-
### `design-handoff/` — Design Handoff ·
|
|
238
|
+
### `design-handoff/` — Design Handoff · 设计交付方法论 (2)
|
|
228
239
|
|
|
229
240
|
- **`zsk:figma-to-code`** *[optional]*
|
|
230
|
-
|
|
241
|
+
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). Styling specifics live in zsk:styling-system.
|
|
231
242
|
触发：`figma to code` · `100 percent fidelity` · `node naming conversion` · `design annotations`
|
|
232
243
|
|
|
233
244
|
- **`zsk:ue-mcp`** *[optional]*
|
|
234
|
-
|
|
245
|
+
Design Source capture & MCP readout for modules with Figma/design input — 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.
|
|
235
246
|
触发：`UE MCP context` · `figma snapshot` · `design source reference` · `module UE deviation`
|
|
236
247
|
|
|
237
|
-
### `system/` — System ·
|
|
248
|
+
### `system/` — System · 工程宪法级资源 (5)
|
|
238
249
|
|
|
239
250
|
- **`zsk:adr`** *[optional]*
|
|
240
|
-
|
|
251
|
+
Cross-module long-lived architectural decision record — context, decision, rationale, alternatives considered, and consequences. Produces docs/system/adrs/ADR-NNNN-{slug}.md. Not for single-module implementation choices.
|
|
241
252
|
触发：`architecture decision record` · `ADR template` · `MADR` · `cross-module decision`
|
|
242
253
|
|
|
243
254
|
- **`zsk:architecture`** *[optional]*
|
|
244
|
-
|
|
255
|
+
Project system architecture documentation — 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.
|
|
245
256
|
触发：`system architecture` · `C4 model` · `tech stack baseline` · `module boundaries`
|
|
246
257
|
|
|
247
258
|
- **`zsk:glossary`** *[optional]*
|
|
248
|
-
|
|
259
|
+
Project Ubiquitous Language maintenance — single source for business terms, domain entities, state names, technical terms, and acronyms. Eliminates same-concept-different-names confusion across modules and backend contracts.
|
|
249
260
|
触发：`glossary` · `ubiquitous language` · `DDD terms` · `business term`
|
|
250
261
|
|
|
251
262
|
- **`zsk:nfr-baseline`** *[optional]*
|
|
252
|
-
|
|
263
|
+
Project NFR baseline (inherited or established) — 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.
|
|
253
264
|
触发：`NFR baseline` · `non functional requirements` · `quality attributes` · `ISO 25010`
|
|
254
265
|
|
|
255
266
|
- **`zsk:project-constraints-template`** *[optional]*
|
|
256
|
-
|
|
267
|
+
Project constraints template for new-project bootstrap — captures 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).
|
|
257
268
|
触发：`project constraints` · `SYSTEM-SPEC` · `import origins` · `forbidden packages`
|
|
258
269
|
|
|
259
|
-
### `meta/` — Meta ·
|
|
270
|
+
### `meta/` — Meta · 元信息 (1)
|
|
260
271
|
|
|
261
272
|
- **`zsk:philosophy`** *[meta · optional]*
|
|
262
|
-
|
|
273
|
+
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.
|
|
263
274
|
触发：`zsk philosophy` · `why is zsk organized this way` · `design rationale` · `LLM wiki vs superpowers`
|
|
275
|
+
|
package/bundles.yaml
CHANGED
|
@@ -45,7 +45,7 @@ bundles:
|
|
|
45
45
|
- zsk:react-components
|
|
46
46
|
- zsk:react-naming
|
|
47
47
|
- zsk:typescript
|
|
48
|
-
- zsk:
|
|
48
|
+
- zsk:styling-system
|
|
49
49
|
- zsk:i18n
|
|
50
50
|
- zsk:a11y-web
|
|
51
51
|
- zsk:performance-web
|
|
@@ -82,7 +82,7 @@ bundles:
|
|
|
82
82
|
- zsk:react-components
|
|
83
83
|
- zsk:react-naming
|
|
84
84
|
- zsk:typescript
|
|
85
|
-
- zsk:
|
|
85
|
+
- zsk:styling-system
|
|
86
86
|
- zsk:i18n
|
|
87
87
|
- zsk:a11y-web
|
|
88
88
|
- zsk:performance-web
|
|
@@ -3,14 +3,14 @@ name: zsk:figma-to-code
|
|
|
3
3
|
description: Figma design node → production code via MCP — 7-step workflow
|
|
4
4
|
(locate → extract structure → extract annotations → naming conversion → layout
|
|
5
5
|
decoding → states → tokens), plus the 4-dimension "100% fidelity" verification
|
|
6
|
-
(visual / interaction / semantic / responsive).
|
|
7
|
-
zsk:
|
|
6
|
+
(visual / interaction / semantic / responsive). Styling specifics live in
|
|
7
|
+
zsk:styling-system.
|
|
8
8
|
category: resource
|
|
9
9
|
domain: design-handoff
|
|
10
10
|
tier: optional
|
|
11
11
|
related:
|
|
12
12
|
- ../ue-mcp/SKILL.md
|
|
13
|
-
- ../../frontend/
|
|
13
|
+
- ../../frontend/styling-system/SKILL.md
|
|
14
14
|
- ../../frontend/a11y-web/SKILL.md
|
|
15
15
|
- ../../frontend/react-components/SKILL.md
|
|
16
16
|
triggers:
|
|
@@ -26,7 +26,7 @@ triggers:
|
|
|
26
26
|
|
|
27
27
|
> **目标**：以最少的主观猜测、最高的还原度，从 Figma 设计稿产出生产级代码
|
|
28
28
|
> **适用**：有视觉 / 交互设计输入的模块
|
|
29
|
-
>
|
|
29
|
+
> **样式实现细节**：命名、Less 嵌套、token 与断点纪律见 [`frontend/styling-system`](../../frontend/styling-system/SKILL.md)（本文件只讲方法论）
|
|
30
30
|
|
|
31
31
|
## 核心挑战
|
|
32
32
|
|
|
@@ -112,7 +112,7 @@ Figma 原名往往不规范，必须转换为 **语义化 + 可搜索 + 与代
|
|
|
112
112
|
#### 命名转换原则
|
|
113
113
|
|
|
114
114
|
1. **语义化，不视觉化**（✅ `.feature-tree__node` / ❌ `.blue-box`）
|
|
115
|
-
2.
|
|
115
|
+
2. **样式命名约定**（BEM 为默认推荐，详见 [`frontend/styling-system`](../../frontend/styling-system/SKILL.md)）
|
|
116
116
|
3. **与组件命名对齐**（组件 `FeatureTree` → Block class `.feature-tree`）
|
|
117
117
|
4. **稳定且可搜索**（Figma 改名不影响代码；跨文件 grep 能定位）
|
|
118
118
|
5. **识别语义的依据**：位置 / 结构、Variants / States、内容、命名暗示
|
|
@@ -233,7 +233,7 @@ Figma Variants → 组件状态：
|
|
|
233
233
|
- [ ] `{{config.paths.design_assets}}/{module}/{snapshot}/description.md`
|
|
234
234
|
- [ ] `screenshot-*.png`（每状态一张）
|
|
235
235
|
- [ ] `docs/{module}/ue-mcp.md`（引用 description.md）
|
|
236
|
-
- [ ] 组件代码 + 样式（遵循 [`frontend/
|
|
236
|
+
- [ ] 组件代码 + 样式（遵循 [`frontend/styling-system`](../../frontend/styling-system/SKILL.md)）
|
|
237
237
|
- [ ] i18n 三语文案（若适用，含批注中文案）
|
|
238
238
|
- [ ] 单元测试（覆盖状态矩阵每一项）
|
|
239
239
|
- [ ] **批注落实追踪**
|
|
@@ -259,7 +259,7 @@ Figma Variants → 组件状态：
|
|
|
259
259
|
- [ ] 状态矩阵含 diff + 截图 + a11y 属性
|
|
260
260
|
- [ ] **设计批注表完整**（含类别 / 责任 / 已落实列）
|
|
261
261
|
- [ ] **批注已全部落实或关联 tasks.md**
|
|
262
|
-
- [ ]
|
|
262
|
+
- [ ] 样式命名一致（见 `frontend/styling-system`）
|
|
263
263
|
- [ ] 布局用 flex / grid，绝对定位有理由
|
|
264
264
|
- [ ] 四维度 100% 还原清单全绿
|
|
265
265
|
- [ ] description.md 与代码交叉一致
|
|
@@ -161,7 +161,7 @@ triggers:
|
|
|
161
161
|
|
|
162
162
|
**浏览器矩阵**（默认基线）：Chrome / Edge / Safari / Firefox 桌面端最近 2 个大版本；iOS Safari / Android Chrome 最近 2 个大版本；**IE 11 不支持**。在 `package.json` 配 `browserslist` 对齐（`last 2 <browser> versions` + `not dead`）。
|
|
163
163
|
|
|
164
|
-
**响应式断点**（引自 token，详见 [`
|
|
164
|
+
**响应式断点**（引自 token，详见 [`styling-system`](../styling-system/SKILL.md) 第 7 节）：
|
|
165
165
|
|
|
166
166
|
| 断点 | ≤ px | 说明 |
|
|
167
167
|
| --- | ---: | --- |
|
|
@@ -112,7 +112,7 @@ triggers:
|
|
|
112
112
|
|
|
113
113
|
### 代码风格（前端）
|
|
114
114
|
- [ ] 命名符合 [`frontend/react-naming`](../react-naming/SKILL.md)
|
|
115
|
-
- [ ]
|
|
115
|
+
- [ ] 样式遵循 [`frontend/styling-system`](../styling-system/SKILL.md)（命名稳定 / 无 `!important` / 无深度嵌套）
|
|
116
116
|
- [ ] 无过度注释 WHAT（见 [`quality/code-hygiene`](../../quality/code-hygiene/SKILL.md)）
|
|
117
117
|
- [ ] 没有未被调用的新抽象（YAGNI）
|
|
118
118
|
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: zsk:
|
|
3
|
-
description: Frontend
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
name: zsk:styling-system
|
|
3
|
+
description: Frontend styling system discipline — scheme detection, naming
|
|
4
|
+
conventions, nesting depth (≤3 layers), token usage rules (no hardcoded
|
|
5
|
+
color/spacing), scope isolation, responsive breakpoints, and !important
|
|
6
|
+
prohibition across Less / Sass / CSS Modules / Tailwind / CSS-in-JS.
|
|
7
7
|
category: standard
|
|
8
8
|
domain: frontend
|
|
9
9
|
tier: optional
|
|
@@ -20,7 +20,7 @@ triggers:
|
|
|
20
20
|
- responsive breakpoints
|
|
21
21
|
---
|
|
22
22
|
|
|
23
|
-
#
|
|
23
|
+
# Styling System · 样式体系纪律
|
|
24
24
|
|
|
25
25
|
> **范围**：CSS / Less / Sass / CSS Modules / Tailwind / CSS-in-JS 场景下的样式纪律
|
|
26
26
|
> **前置**：**写样式前必须先检测项目 CSS 方案**，严格跟随，不混用
|
|
@@ -50,9 +50,9 @@ triggers:
|
|
|
50
50
|
- ❌ CSS Modules 项目里手写全局 class（除非显式 `:global()`）
|
|
51
51
|
- ❌ 同文件混用 CSS-in-JS 与外部样式表
|
|
52
52
|
|
|
53
|
-
## 2. BEM
|
|
53
|
+
## 2. 命名与结构纪律（默认示例：BEM）
|
|
54
54
|
|
|
55
|
-
###
|
|
55
|
+
### 默认结构
|
|
56
56
|
|
|
57
57
|
```
|
|
58
58
|
.block { ... } // 块
|
|
@@ -67,6 +67,12 @@ triggers:
|
|
|
67
67
|
- 不嵌套 Element（`block__el1__el2` 是错误 — 改为 `block__el2` 或重新设计 block）
|
|
68
68
|
- Modifier 表达状态 / 变体（`--primary`、`--is-active`、`--size-large`）
|
|
69
69
|
|
|
70
|
+
### 说明
|
|
71
|
+
|
|
72
|
+
- **BEM 不是唯一合法方案**，但在 Less / Sass / 全局样式表场景下仍然是默认推荐
|
|
73
|
+
- 如果项目已明确采用 CSS Modules、Tailwind、CSS-in-JS 或 Vanilla Extract，就遵循宿主方案的命名与组织方式，不强行套一层 BEM
|
|
74
|
+
- 本 skill 关心的是**命名稳定、作用域清晰、层级可控**，不是要求所有项目都写成同一种 class 语法
|
|
75
|
+
|
|
70
76
|
### 示例
|
|
71
77
|
|
|
72
78
|
```html
|