@captain_z/zsk-skills 0.1.0

package/frontend/css-bem/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: zsk:css-bem
+description: Frontend CSS / Less / Sass / CSS Modules / Tailwind discipline —
+  scheme detection, BEM naming (Block__Element--Modifier), nesting depth (≤3
+  layers), token usage rules (no hardcoded color/spacing), scope isolation,
+  responsive breakpoints, and !important prohibition.
+category: standard
+domain: frontend
+tier: optional
+related:
+  - ../react-naming/SKILL.md
+  - ../../design-handoff/figma-to-code/SKILL.md
+triggers:
+  - CSS scheme detection
+  - BEM naming
+  - Less nesting
+  - design token
+  - style scope
+  - no important
+  - responsive breakpoints
+---
+
+# CSS / BEM · 样式纪律
+
+> **范围**：CSS / Less / Sass / CSS Modules / Tailwind / CSS-in-JS 场景下的样式纪律
+> **前置**：**写样式前必须先检测项目 CSS 方案**，严格跟随，不混用
+
+## 1. 方案检测（第一条纪律）
+
+### 检测表
+
+| 线索 | 判定方案 |
+| --- | --- |
+| `package.json` 含 `less` + `.less` 文件 | **Less** |
+| `package.json` 含 `sass` / `.scss` | **Sass / SCSS** |
+| 存在 `*.module.css` / `*.module.less` | **CSS Modules** |
+| `tailwind.config.*` 存在 + JSX 类名以 `tw-` 或 utility 为主 | **Tailwind** |
+| `package.json` 含 `styled-components` / `@emotion/*` | **CSS-in-JS** |
+| 仅 `.css` 无预处理 | **原生 CSS** |
+| `vanilla-extract.config.*` / `.css.ts` | **Vanilla Extract** |
+
+### 检测结果记录
+
+项目选型填入 `SYSTEM-SPEC.md` 的"样式方案"条目。本 skill 的示例默认 **Less + BEM**，其他方案等价替换语法。
+
+### 禁用
+
+- ❌ Less 项目里写 Sass `@mixin` / `@include`
+- ❌ Tailwind 项目里又额外写一套 BEM 类
+- ❌ CSS Modules 项目里手写全局 class（除非显式 `:global()`）
+- ❌ 同文件混用 CSS-in-JS 与外部样式表
+
+## 2. BEM 命名（Block · Element · Modifier）
+
+### 结构
+
+```
+.block                { ... }   // 块
+.block__element       { ... }   // 元素
+.block--modifier      { ... }   // 块修饰符
+.block__element--mod  { ... }   // 元素修饰符
+```
+
+### 命名规则
+
+- Block / Element / Modifier 每段用小写 + `-` 连接（`user-card`、`feature-tree__node-title`）
+- 不嵌套 Element（`block__el1__el2` 是错误 — 改为 `block__el2` 或重新设计 block）
+- Modifier 表达状态 / 变体（`--primary`、`--is-active`、`--size-large`）
+
+### 示例
+
+```html
+<div class="user-card user-card--selected">
+  <img class="user-card__avatar" />
+  <div class="user-card__body">
+    <h3 class="user-card__name">Alice</h3>
+    <span class="user-card__name user-card__name--muted">alice@x.com</span>
+  </div>
+</div>
+```
+
+```less
+.user-card {
+  display: flex;
+  padding: @spacing-md;
+
+  &--selected {
+    background: @color-primary-bg;
+  }
+
+  &__avatar {
+    width: 40px; height: 40px;
+  }
+
+  &__name {
+    font-weight: 500;
+
+    &--muted {
+      color: @color-text-muted;
+      font-weight: 400;
+    }
+  }
+}
+```
+
+## 3. 嵌套纪律（Less / Sass）
+
+### 硬上限：**≤ 3 层**
+
+```less
+// ✅ 3 层以内
+.user-card {
+  &__body {
+    &__title { ... }
+  }
+}
+
+// ❌ 4 层以上 — 重新设计
+.user-card {
+  .layout {
+    .row {
+      .col {
+        .title { ... }
+      }
+    }
+  }
+}
+```
+
+### 禁用
+
+- ❌ 层层嵌套复刻 DOM 结构（选择器脆弱 + 权重过高）
+- ❌ 用 `& > div > span` 这类**位置依赖**选择器
+- ❌ 用标签选择器（`div` / `span`）做样式载体 — 加 BEM 类
+
+## 4. 设计 token 纪律
+
+### 硬规则：禁止硬编码以下值
+
+| 值 | 来源 |
+| --- | --- |
+| 颜色 | `@color-*` / `var(--color-*)` / 设计 token 文件 |
+| 间距 | `@spacing-*` / token |
+| 字号 / 行高 | `@font-size-*` / `@line-height-*` |
+| 圆角 | `@border-radius-*` |
+| 阴影 | `@shadow-*` |
+| 动效时长 | `@motion-duration-*` |
+| z-index | `@z-index-*`（避免层级混乱） |
+
+### 允许硬编码
+
+- 一次性数值（`width: 1px` 分隔线、`margin: 0` 清零）
+- 组件内私有几何（`flex-basis: 280px` 的栅格列宽 — 写注释说明来源）
+
+### token 来源
+
+- 设计系统（Ant Design / Tailwind / 自研）→ 引入 token 文件
+- Figma → 见 [`design-handoff/figma-to-code`](../../design-handoff/figma-to-code/SKILL.md) 的 token 映射
+
+## 5. 作用域隔离
+
+### CSS Modules（推荐）
+
+```less
+// UserCard.module.less
+.card { ... }
+.body { ... }
+
+// UserCard.tsx
+import s from './UserCard.module.less';
+<div className={s.card}><div className={s.body}/></div>
+```
+
+类名自动哈希化，天然隔离。
+
+### 全局样式的使用原则
+
+- 仅用于：重置 (reset.css) / 主题 token (vars.less) / 字体 (fonts.css)
+- 业务模块**不允许**写全局 class
+
+### BEM + Less 的隔离
+
+即使不用 CSS Modules，BEM 的 block 前缀已提供命名空间（`.user-card__*` 唯一）。
+
+## 6. !important 禁用
+
+### 禁用
+
+- ❌ 业务代码使用 `!important`
+- ❌ 用 `!important` 覆盖第三方组件库（改用组件库提供的 theme 机制 / token）
+
+### 允许（罕见）
+
+- 第三方不可改的样式覆盖（必须在该行上方注释说明"此处覆盖 XX 库默认样式，因为 YY"）
+- 即使允许也必须集中到一个 `overrides.less` 文件
+
+## 7. 响应式断点
+
+断点**统一从 token 引**，不散落在各模块：
+
+```less
+// tokens/breakpoints.less
+@bp-xs: 480px;
+@bp-sm: 768px;
+@bp-md: 1024px;
+@bp-lg: 1280px;
+@bp-xl: 1536px;
+
+// 使用
+.layout {
+  display: block;
+
+  @media (min-width: @bp-md) {
+    display: grid;
+  }
+}
+```
+
+### 策略
+
+- **Mobile-first**：默认写移动端样式，`min-width` 向上叠加
+- **避免 `max-width` 向下覆盖**（除非必要）
+- **不允许组件内自定义断点**（违反统一性）
+
+## 8. 跨方案语法速查
+
+| 能力 | Less | Sass | CSS Modules | Tailwind | CSS-in-JS |
+| --- | --- | --- | --- | --- | --- |
+| 变量 | `@var` | `$var` | CSS 自定义属性 `var(--x)` | 配置 `theme.colors` | JS 对象 |
+| 嵌套 | `&` | `&` | `&`（需 PostCSS 插件）| 无（平铺 utility） | 模板字符串嵌套 |
+| mixin | `.mixin()` | `@mixin` + `@include` | 组合 `composes` | `@apply` | 函数 |
+| 条件 | `when` guard | `@if` | JS 侧 | JSX 侧 | JS 侧 |
+| 作用域 | BEM 前缀 | BEM 前缀 | 自动哈希 | 全局 utility | 自动作用域 |
+
+无论方案，**命名纪律（BEM 精神：block · element · modifier）、token 纪律、嵌套限制**都适用。
+
+## 9. 组件样式目录
+
+```
+UserCard/
+├── index.tsx
+├── UserCard.module.less   // 样式文件贴组件目录
+├── styles.less            // 若不用 CSS Modules
+└── ...
+```
+
+- 每个组件一个样式文件（不跨组件共享样式文件）
+- 公用片段（`.truncate` / `.visually-hidden`）抽到 `utilities.less`
+
+## 反模式（禁止）
+
+- ❌ 硬编码颜色 / 间距 / 字号（应用 token）
+- ❌ `!important` 绕过样式冲突
+- ❌ 4 层以上嵌套
+- ❌ 标签选择器 + 位置选择器堆叠（`.x > div:nth-child(3)`）
+- ❌ BEM Element 嵌套（`block__el1__el2`）
+- ❌ 全局写业务样式
+- ❌ 断点散落在模块
+
+## 质量门禁
+
+- [ ] 项目 CSS 方案已在 `SYSTEM-SPEC.md` 声明
+- [ ] 新增 / 修改样式符合 BEM
+- [ ] 嵌套 ≤ 3 层
+- [ ] 无硬编码 color / spacing / font-size / radius（或有 ADR 豁免）
+- [ ] 无 `!important`（或集中在 overrides 文件 + 注释）
+- [ ] 断点引自 token
+- [ ] stylelint 零 error

package/frontend/design-frontend/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: zsk:design-frontend
+description: 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.
+category: stage
+domain: frontend
+tier: optional
+stage: 3
+variants:
+  - feature
+  - bugfix
+  - refactor
+related:
+  - ../../sdlc/design/SKILL.md
+  - ../spec-frontend/SKILL.md
+  - ../performance-web/SKILL.md
+  - ../nfr-web/SKILL.md
+  - ../react-components/SKILL.md
+  - ../../design-handoff/figma-to-code/SKILL.md
+triggers:
+  - frontend design
+  - Props implementation mapping
+  - UE state to structure
+  - Figma to implementation
+  - frontend performance budget
+  - ErrorBoundary placement
+  - Core Web Vitals budget
+---
+
+# Stage 3: Design · Frontend 补丁
+
+> **用途**：当模块是**前端组件 / 页面**时，在 [`zsk:design`](../../sdlc/design/SKILL.md) 通用骨架上追加的实现映射
+> **范围**：Props 映射、UE 状态 → 结构、Figma → 实现、性能预算 (CWV)、ErrorBoundary
+
+## 追加章节
+
+### A. Props / 状态 / 事件实现映射
+
+Spec 的每个公开 Props 必须说明：
+- 由哪个文件消费
+- 是否进入内部 state
+- 是否触发 service 调用
+- 是否影响样式或视觉状态
+
+```md
+## Props / 状态 / 事件实现映射
+
+| 契约项 | 落点文件 | 内部状态 / 副作用 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `index.tsx` | 归一化后进 state | 通过 useMemo 派生扁平树 |
+| `selectedId` | `index.tsx` | 受控 + 内部回显 | 外部未传时用内部 state |
+| `onSelect` | `{module}View.tsx` | 事件上报 | 透传 node 数据 |
+```
+
+### B. UE 状态映射到结构
+
+Spec 的每个 UE 状态必须说明**由哪个容器 / class / 分支渲染**：
+
+```md
+## UE 状态映射
+
+| 状态 | 实现方式 | 落点文件 |
+| --- | --- | --- |
+| `loading` | `<Skeleton>` 或 `<Spinner>` | `index.tsx` 顶部条件渲染 |
+| `empty` | `<EmptyState>` 组件 | `components/EmptyState.tsx` |
+| `error` | `<ErrorFallback>` 或 toast | `index.tsx` + ErrorBoundary |
+| `hover` | `.{module}__node:hover` | `styles.less` |
+| `focus-visible` | `.{module}__node:focus-visible` | `styles.less` |
+| `selected` | `.{module}__node--selected` | `styles.less` + className 逻辑 |
+```
+
+### C. Figma / UE / MCP 到实现映射
+
+```md
+## Figma → 实现映射
+
+| Figma 节点 / 区域 | 文件 / 样式 | 说明 |
+| --- | --- | --- |
+| search-input frame | `components/Search.tsx` + `.{module}__search` | 500ms 防抖（批注要求） |
+| node-list frame | `components/NodeList.tsx` + `.{module}__list` | 虚拟滚动 |
+```
+
+**原则**：引用 `docs/{module}/ue-mcp.md` 的命名映射表（[`zsk:figma-to-code`](../../design-handoff/figma-to-code/SKILL.md) Step 4 产物），不重复。
+
+### D. 性能预算（Core Web Vitals）
+
+继承 [`frontend/nfr-web`](../nfr-web/SKILL.md) 的系统基线，模块级可加严：
+
+```md
+## 性能预算
+
+| 指标 | 系统基线 | 本模块 | 测量方式 | 超限处理 |
+| --- | --- | --- | --- | --- |
+| LCP（首屏） | < 2.5s | < 2.0s | Lighthouse CI | 有 ADR 豁免 |
+| INP | < 200ms | < 100ms | Web Vitals |  |
+| CLS | < 0.1 | < 0.05 | Web Vitals |  |
+| 单 chunk（gzip） | < 500KB | < 300KB | Bundle Analyzer |  |
+| 首屏请求数 | ≤ 6 | ≤ 4 | Network tab |  |
+```
+
+详细策略见 [`frontend/performance-web`](../performance-web/SKILL.md)。
+
+### E. ErrorBoundary 位置
+
+- 模块入口必须包 `ErrorBoundary`（见 [`frontend/react-components`](../react-components/SKILL.md)）
+- 错误边界只捕获 render 期错误；async 错误用 try/catch + 显式 UI
+- 降级 UI 必须可交互（至少"重试"/"返回"）
+
+```md
+## ErrorBoundary 设计
+
+- 位置：`index.tsx` 外层包裹
+- 降级 UI：`components/ErrorFallback.tsx`
+- 上报：接入 `{{config.stack.error_reporter}}`
+- 重试机制：降级 UI 含"重试"按钮，reset state
+```
+
+### F. 观测性接入（前端补丁）
+
+| 事件 | 位置 | 上报字段 |
+| --- | --- | --- |
+| `{module}_view` | `index.tsx` useEffect | userId / moduleId |
+| `{module}_select` | `onSelect` 回调 | userId / nodeId |
+| `{module}_search` | Search onChange 防抖后 | userId / query |
+| `{module}_error` | ErrorBoundary | userId / err.message / componentStack |
+
+埋点基线见 [`system/nfr-baseline`](../../system/nfr-baseline/SKILL.md) 的第 6 类。
+
+## Frontend Feature design 完整结构
+
+1. 模块映射 _(zsk:design)_
+2. 当前实现 _(zsk:design)_
+3. 架构决策 ADR _(zsk:design)_
+4. 上下文 / 时序图 _(zsk:design)_
+5. 文件职责与分层 _(zsk:design)_
+6. 目录架构 _(zsk:design)_
+7. FR 实现映射 _(zsk:design)_
+8. NFR 实现映射 _(zsk:design)_
+9. **Props / 状态 / 事件映射**（本文件 A）
+10. **UE 状态映射**（本文件 B）
+11. **Figma → 实现映射**（本文件 C）
+12. API / 数据流 _(zsk:design)_
+13. 错误处理与降级 + **ErrorBoundary**（本文件 E）
+14. 回滚与迁移 _(zsk:design)_
+15. **观测性接入**（本文件 F）
+16. **性能预算 CWV**（本文件 D）
+17. 安全考虑 _(zsk:design)_
+18. 测试方案 _(zsk:design)_
+19. 风险与权衡 _(zsk:design)_
+20. 变更文件清单 _(zsk:design)_
+
+## 质量门禁（前端补丁）
+
+- [ ] Props / UE 状态全部映射到文件
+- [ ] Figma → 实现映射表与 `ue-mcp.md` 一致
+- [ ] 性能预算量化（LCP / INP / CLS / bundle）
+- [ ] ErrorBoundary 位置明确 + 降级 UI 可交互
+- [ ] 观测性埋点已声明
+- [ ] 未新增 Spec 未声明的行为
+
+> 通用 design 门禁（ADR / C4 图 / FR 落点）见 [`zsk:design`](../../sdlc/design/SKILL.md)

package/frontend/dor-dod-frontend/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: zsk:dor-dod-frontend
+description: 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.
+category: resource
+domain: frontend
+tier: optional
+variants:
+  - feature
+  - bugfix
+  - refactor
+related:
+  - ../../sdlc/dor-dod/SKILL.md
+  - ../spec-frontend/SKILL.md
+  - ../design-frontend/SKILL.md
+  - ../nfr-web/SKILL.md
+  - ../a11y-web/SKILL.md
+  - ../i18n/SKILL.md
+  - ../../design-handoff/ue-mcp/SKILL.md
+triggers:
+  - frontend DoR DoD
+  - frontend definition of ready done
+  - UE matrix gate
+  - visual regression gate
+  - three language sync gate
+---
+
+# DoR & DoD · Frontend 补丁
+
+> **用途**：在 [`zsk:dor-dod`](../../sdlc/dor-dod/SKILL.md) 通用清单上追加的前端专属条款
+> **范围**：UE 状态矩阵、ue-mcp.md、视觉回归、i18n 三语、a11y、NFR-Web
+
+## DoR（前端补丁）— 启动前门禁
+
+### Feature 专用（前端）
+
+- [ ] `{{config.paths.api_contracts}}` 已对齐后端（后端契约目录）
+- [ ] `ue-mcp.md` 已登记（有 Figma 输入时）或明确"无设计交付"降级
+- [ ] **UE 状态矩阵覆盖**：loading / empty / error / hover / focus / focus-visible / selected（必填）+ 组件特有状态
+- [ ] **Props / Event Contract** 在 [`zsk:spec-frontend`](../spec-frontend/SKILL.md) A 节完整
+- [ ] **受控 / 非受控边界**已声明
+- [ ] **Frontend NFR 六类**（性能 / a11y / 安全 / i18n / 兼容性 / 可观测性）全覆盖（见 [`frontend/nfr-web`](../nfr-web/SKILL.md)）
+- [ ] 三语（`{{config.i18n.languages}}`）清单已明确
+
+### Bugfix 专用（前端）
+
+- [ ] MCVE 可在浏览器复现（录屏 / 步骤）
+- [ ] 受影响契约项（FR / NFR / AC 编号）已列出
+- [ ] 是否涉及 visual / a11y / i18n 受影响已评估
+
+### Refactor 专用（前端）
+
+- [ ] 视觉基线已留档（截图 / Chromatic snapshots）
+- [ ] 性能基线已留档（Lighthouse / Bundle size）
+- [ ] 对外契约（Props / Events / API）保留清单完整
+
+---
+
+## DoD（前端补丁）— 关闭前门禁
+
+### 通用（前端）
+
+- [ ] **视觉回归**对照完成或差异已记录（截图 / Chromatic diff）
+- [ ] **i18n 三语同步验证**（在同一 commit；语言清单 `{{config.i18n.languages}}`）
+- [ ] **a11y 核对**（键盘 / aria / 焦点；axe-core 零 critical）
+- [ ] **NFR 六类全部有证据**：
+  - 性能（Lighthouse 报告）
+  - a11y（axe 报告）
+  - 安全（依赖扫描报告）
+  - i18n（三语 diff 截图）
+  - 兼容性（浏览器矩阵截图）
+  - 可观测性（埋点样本）
+
+### Feature 专用（前端）
+
+- [ ] 所有 UE 状态（loading / empty / error / hover / focus-visible / selected / disabled）视觉 + 行为均已验证
+- [ ] 包体积增量 < 10%（或有 ADR 豁免）
+- [ ] Core Web Vitals 达标：LCP / INP / CLS（见 [`frontend/nfr-web`](../nfr-web/SKILL.md)）
+
+### Bugfix 专用（前端）
+
+- [ ] 原浏览器复现步骤 → 不再复现（截图 / 录屏对照 before/after）
+- [ ] 相邻 UE 状态未回归（hover → selected 等邻项）
+- [ ] a11y / i18n / 性能路径未受影响（若相关）
+
+### Refactor 专用（前端）
+
+- [ ] **视觉回归零差异**（硬门禁）
+- [ ] Lighthouse 评分不回退
+- [ ] **包体积变化 ≤ ±2%**（硬门禁）
+- [ ] 对外 Props / Events / API 清单零变化（有对照表）
+
+---
+
+## Exit Criteria（前端补丁）
+
+前端模块在 `zsk:dor-dod` 的通用出口条件基础上，各阶段出口还要满足：
+
+| 阶段 | 前端专项 |
+| --- | --- |
+| spec → design | UE 状态矩阵 + Props Contract + NFR 六类已定 |
+| design → coding | Props / UE / Figma 映射表完整；性能预算量化 |
+| coding → reviewing | 三语 i18n 同 commit + axe-core 零 critical + 视觉对照存在 |
+| verify → archive | 视觉回归对照归档 + CWV 达标证据 + 浏览器矩阵截图 |
+
+## 反模式（前端专属）
+
+- ❌ "等代码出来再截图"（视觉基线必须先有）
+- ❌ "先中文后补 i18n"（i18n 必须同 commit）
+- ❌ "UE 状态实现了再写矩阵"（Spec 阶段必须已定矩阵）
+- ❌ "性能预算后面看情况"（Design 阶段必须量化）
+- ❌ "a11y 最后统一过一遍"（一开始就满足，不留技术债）