@bovinphang/frontend-craft 2.6.0 → 2.7.0

package/skills/relations.json

@@ -25,7 +25,7 @@
       "fec-security-review",
       "fec-route-protection",
       "fec-form-handling",
-      "fec-typescript-type-safety",
+      "fec-typescript-project-standard",
       "fec-source-driven-development"
     ],
     "boundaryWorkflows": [
@@ -41,6 +41,26 @@
       "realtime"
     ]
   },
+  "fec-backend-requirements-handoff": {
+    "relatedSkills": [
+      "fec-api-integration",
+      "fec-doc-sync",
+      "fec-source-driven-development",
+      "fec-testing-strategy",
+      "fec-route-protection"
+    ],
+    "boundaryWorkflows": [
+      "Use API integration when the contract shape, typed client, auth refresh, error mapping, upload, or realtime implementation is being designed.",
+      "Use documentation sync when backend decisions change public docs, API notes, route docs, or env/config documentation.",
+      "Use route protection when the handoff centers on auth redirects, RBAC, permission routes, or middleware behavior."
+    ],
+    "capabilityTags": [
+      "backend-requirements",
+      "handoff",
+      "api-collaboration",
+      "data-needs"
+    ]
+  },
   "fec-browser-storage": {
     "relatedSkills": [
       "fec-security-review",
@@ -85,7 +105,7 @@
       "fec-e2e-testing",
       "fec-validation-fix",
       "fec-performance-optimization",
-      "fec-typescript-type-safety",
+      "fec-typescript-project-standard",
       "fec-state-management",
       "fec-source-driven-development",
       "fec-dependency-upgrade",
@@ -174,6 +194,27 @@
       "migration"
     ]
   },
+  "fec-drawio-studio": {
+    "relatedSkills": [
+      "fec-image-generation",
+      "fec-canvas-threejs",
+      "fec-svg-animation",
+      "fec-ui-design",
+      "fec-source-driven-development"
+    ],
+    "boundaryWorkflows": [
+      "Use image generation for raster-first posters, visual concepts, product images, and PNG QA beyond editable technical diagrams.",
+      "Use Canvas/Three.js when the diagram becomes an interactive runtime visualization, simulation, game scene, shader, or 3D renderer.",
+      "Use SVG animation for motion-specific vector micro-interactions; use drawio studio for static or editable technical SVG exports."
+    ],
+    "capabilityTags": [
+      "drawio",
+      "editable-diagram",
+      "autolayout",
+      "shape-search",
+      "code-structure-map"
+    ]
+  },
   "fec-e2e-testing": {
     "relatedSkills": [
       "fec-testing-strategy",
@@ -210,6 +251,30 @@
       "accessibility"
     ]
   },
+  "fec-image-generation": {
+    "relatedSkills": [
+      "fec-ui-design",
+      "fec-implement-from-design",
+      "fec-canvas-threejs",
+      "fec-svg-animation",
+      "fec-responsive-layout",
+      "fec-accessibility-check",
+      "fec-web-video-presentation"
+    ],
+    "boundaryWorkflows": [
+      "Use UI design for product-specific visual direction, brand tone, hierarchy, and visual QA of generated assets.",
+      "Use implementation-from-design when a Figma, Sketch, MasterGo, Pixso, screenshot, or other external design source is authoritative.",
+      "Use Canvas/Three.js or SVG animation workflows when the generated visual becomes an interactive renderer, shader, or motion asset rather than a static image."
+    ],
+    "capabilityTags": [
+      "image-generation",
+      "image-editing",
+      "diagram-generation",
+      "png-qa",
+      "visual-assets",
+      "autofix"
+    ]
+  },
   "fec-legacy-to-modern-migration": {
     "relatedSkills": [
       "fec-legacy-web-standard",
@@ -356,7 +421,7 @@
   },
   "fec-react-project-standard": {
     "relatedSkills": [
-      "fec-typescript-type-safety",
+      "fec-typescript-project-standard",
       "fec-state-management",
       "fec-tailwind-design-system",
       "fec-responsive-layout",
@@ -530,26 +595,6 @@
       "workflow"
     ]
   },
-  "fec-typescript-type-safety": {
-    "relatedSkills": [
-      "fec-code-review",
-      "fec-api-integration",
-      "fec-react-project-standard",
-      "fec-vue3-project-standard",
-      "fec-form-handling"
-    ],
-    "boundaryWorkflows": [
-      "Use a general code review workflow when the task spans architecture, rendering, styles, tests, and maintainability beyond type contracts.",
-      "Use an API integration workflow for runtime API client boundaries, auth refresh, uploads, realtime behavior, and error mapping.",
-      "Use framework project workflows when type decisions are part of broader React, Vue, Next.js, or Nuxt module architecture."
-    ],
-    "capabilityTags": [
-      "typescript",
-      "type-safety",
-      "type-modeling",
-      "dto"
-    ]
-  },
   "fec-testing-strategy": {
     "relatedSkills": [
       "fec-component-testing",
@@ -570,14 +615,39 @@
       "quality-gate"
     ]
   },
+  "fec-typescript-project-standard": {
+    "relatedSkills": [
+      "fec-code-review",
+      "fec-api-integration",
+      "fec-react-project-standard",
+      "fec-vue3-project-standard",
+      "fec-vite-project-standard",
+      "fec-monorepo-project-standard",
+      "fec-validation-fix"
+    ],
+    "boundaryWorkflows": [
+      "Use framework project workflows for component architecture, routing, state ownership, and framework-specific module boundaries.",
+      "Use API integration when runtime API clients, auth refresh, uploads, realtime behavior, or error mapping go beyond TypeScript type contracts.",
+      "Use validation fix when the task is to repair concrete lint, typecheck, test, build, or CI failures after TypeScript changes."
+    ],
+    "capabilityTags": [
+      "typescript",
+      "project-standard",
+      "type-safety",
+      "tsconfig",
+      "declarations"
+    ]
+  },
   "fec-ui-design": {
     "relatedSkills": [
+      "fec-image-generation",
       "fec-implement-from-design",
       "fec-accessibility-check",
       "fec-code-review",
       "fec-tailwind-design-system",
       "fec-responsive-layout",
-      "fec-storybook-component-doc"
+      "fec-storybook-component-doc",
+      "fec-web-video-presentation"
     ],
     "boundaryWorkflows": [
       "Use an implementation-from-design workflow when an external design file is the source of truth.",
@@ -620,7 +690,7 @@
   },
   "fec-vue3-project-standard": {
     "relatedSkills": [
-      "fec-typescript-type-safety",
+      "fec-typescript-project-standard",
       "fec-state-management",
       "fec-tailwind-design-system",
       "fec-responsive-layout",
@@ -644,6 +714,27 @@
       "fec-architecture"
     ]
   },
+  "fec-web-video-presentation": {
+    "relatedSkills": [
+      "fec-ui-design",
+      "fec-image-generation",
+      "fec-motion-interaction",
+      "fec-responsive-layout",
+      "fec-accessibility-check"
+    ],
+    "boundaryWorkflows": [
+      "Use a UI design workflow for product-specific visual direction, asset strategy, anti-generic design, and visual QA of scenes.",
+      "Use image generation when the presentation needs custom raster assets, diagrams, storyboard frames, or generated visual references.",
+      "Use motion and responsive layout workflows when scene transitions, reduced-motion behavior, viewport scaling, or recording stability need deeper treatment."
+    ],
+    "capabilityTags": [
+      "web-video",
+      "presentation",
+      "recording",
+      "script-outline",
+      "step-driven-stage"
+    ]
+  },
   "fec-web-workers": {
     "relatedSkills": [
       "fec-canvas-threejs",

package/templates/shared/rules/fec-ci-cd.md

@@ -1,128 +1,40 @@
 # CI/CD 规则
 
-本文件约定持续集成与部署流水线的结构与行为。
+本文件约定持续集成与部署流水线的常驻结构与门禁。具体 GitHub Actions、GitLab CI、云平台或 monorepo pipeline 写法，应按项目现有 CI 模板实现，不在本规则中复制长 YAML。
 
 ## 流水线阶段
 
 建议顺序：
 
-1. **安装依赖** — `npm ci` 或 `pnpm install --frozen-lockfile`
-2. **Lint** — ESLint、Stylelint
-3. **类型检查** — `tsc --noEmit`
-4. **单元测试** — Jest / Vitest
-5. **构建** — `npm run build` 或 `pnpm build`
-6. **包体/性能预算**（可选）— size-limit、Lighthouse CI、bundle analyzer
-7. **依赖与供应链检查**（可选）— audit、license、lockfile diff、依赖升级验证
-8. **E2E 测试**（可选）— Playwright / Cypress
-9. **部署** — 构建产物上传或触发部署服务
+1. **安装依赖**：使用锁文件安装，例如 `npm ci` 或 `pnpm install --frozen-lockfile`。
+2. **Lint / Format 检查**：ESLint、Stylelint、Prettier check 或项目等价命令。
+3. **类型检查**：`tsc --noEmit` 或项目 typecheck 脚本。
+4. **单元 / 组件测试**：Jest、Vitest、Testing Library、Vue Test Utils 等。
+5. **构建**：项目生产构建命令。
+6. **专项质量门禁**：包体、Lighthouse、依赖安全、license、a11y、视觉回归、E2E，按风险启用。
+7. **部署**：仅在前序门禁通过后上传产物或触发部署。
 
-任一阶段失败则中止后续步骤。
-
-## GitHub Actions 示例
-
-```yaml
-name: CI
-
-on:
-  push:
-    branches: [main, develop]
-  pull_request:
-    branches: [main, develop]
-
-jobs:
-  ci:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: pnpm/action-setup@v2
-        with:
-          version: 8
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'pnpm'
-
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm run lint
-      - run: pnpm run typecheck
-      - run: pnpm run test
-      - run: pnpm run build
-
-      - name: Upload build
-        if: success() && github.ref == 'refs/heads/main'
-        uses: actions/upload-artifact@v4
-        with:
-          name: dist
-          path: dist/
-```
-
-## GitLab CI 示例
-
-```yaml
-stages:
-  - install
-  - lint
-  - test
-  - build
-  - deploy
-
-variables:
-  PNPM_VERSION: "8"
-
-install:
-  stage: install
-  script:
-    - corepack enable pnpm
-    - pnpm install --frozen-lockfile
-  cache:
-    key: ${CI_COMMIT_REF_SLUG}
-    paths:
-      - node_modules/
-      - .pnpm-store/
-
-lint:
-  stage: lint
-  script:
-    - pnpm run lint
-    - pnpm run typecheck
-  needs: [install]
-
-test:
-  stage: test
-  script:
-    - pnpm run test
-  needs: [install]
-
-build:
-  stage: build
-  script:
-    - pnpm run build
-  artifacts:
-    paths:
-      - dist/
-  needs: [lint, test]
-```
+任一必需阶段失败都应中止后续步骤。
 
 ## 环境变量与密钥
 
-- 敏感信息使用 CI 平台的 Secrets，不写入仓库
-- 构建时注入 `VITE_*` / `NEXT_PUBLIC_*` 等前端环境变量
-- E2E 的 baseURL、测试账号等从 Secrets 读取
-- 只允许公开前缀的环境变量进入客户端 bundle；服务端密钥不得使用 `VITE_*` / `NEXT_PUBLIC_*`
+- 敏感信息使用 CI 平台 Secrets，不写入仓库、日志或构建产物。
+- 只允许公开前缀的环境变量进入客户端 bundle，例如 `VITE_*`、`NEXT_PUBLIC_*` 等；服务端密钥不得使用公开前缀。
+- E2E 的 baseURL、测试账号、第三方 token 等从 Secrets 或受控测试环境读取。
+- CI 日志要避免打印完整环境变量、请求 header、token 或私密配置。
 
 ## 产物与证据
 
-- 上传测试报告、覆盖率、E2E trace、截图、构建产物和性能预算结果。
+- 上传或保留测试报告、覆盖率、E2E trace、截图、构建产物、包体报告和性能预算结果。
 - CI 失败时保留足够日志定位根因，不只返回“命令失败”。
-- 发布前确认版本、变更说明、迁移事项和回滚路径。
+- 发布前确认版本、变更说明、迁移事项、回滚路径和影响范围。
 - 依赖升级 PR 保留 lockfile diff、关键包版本、release notes 摘要和验证矩阵。
 - Monorepo affected 快速验证可以用于 PR 反馈，但 release 或主干合并前应保留全量验证入口。
 
 ## 强约束
 
-- 使用锁文件（`package-lock.json`、`pnpm-lock.yaml`），禁止 `npm install` 无锁安装
-- 构建产物不提交到仓库，由 CI 生成并上传
-- 部署前必须通过 lint、typecheck、test、build
-- 不跳过失败门禁直接部署，除非有明确风险接受和回滚方案
+- 使用并提交锁文件，禁止无锁安装。
+- 构建产物不提交到源码仓库，由 CI 生成并上传。
+- 部署前必须通过项目定义的 lint、typecheck、test、build。
+- 不跳过失败门禁直接部署，除非有明确风险接受、审批记录和回滚方案。
+- CI 配置应复用项目已有命令，不在流水线里发明与本地不同的替代命令。

package/templates/shared/rules/fec-design-system.md

@@ -1,248 +1,72 @@
 # 设计系统规则
 
-凡是任务涉及 UI 实现、设计稿转代码、样式、设计 Token 或组件复用时，都应用本文件。
+凡是任务涉及 UI 实现、设计稿转代码、样式、设计 Token 或组件复用时，都应用本文件。本文只保留项目常驻设计约束；产品化设计方向、设计系统生成、页面级 override、UI QA 细节交给 `fec-ui-design`；Tailwind token、variant、dark mode 和 class 治理交给 `fec-tailwind-design-system`；响应式布局交给 `fec-responsive-layout`。
 
 ## 核心优先级
 
-按以下顺序优先处理：
-
-1. 复用已有组件
-2. 在已有组件上扩展
-3. 创建新的叶子组件
-4. 只有在理由非常充分时，才创建新的共享基础组件
+1. 复用已有组件。
+2. 在已有组件上扩展。
+3. 创建新的叶子组件。
+4. 只有在理由充分、边界清晰且会被复用时，才创建新的共享基础组件。
 
 ## 产品化设计方向
 
-开始 UI 实现前，先明确界面语气：
-
-- 工具型页面、SaaS 后台、CRM、运营台：优先安静、密集、可扫描，首屏直接呈现核心工作区
-- 品牌页、作品集、发布页：可以更有表现力，但 H1 应是品牌/产品/对象/品类，说明文案放在副标题
-- 可视化、游戏、创作工具：可以使用更强视觉资产和动效，但必须保持交互可控、状态清晰
-- 每个重要界面都应有一个贴合业务的视觉锚点：真实媒体、数据形态、行业材质、字体性格、空间组织或交互节奏
-- 大胆设计必须服务场景；高频工具重效率和稳定，展示型页面重主体识别和记忆点
+- 工具型页面、SaaS 后台、CRM、运营台：优先安静、密集、可扫描，首屏直接呈现核心工作区。
+- 品牌页、作品集、发布页：可以更有表现力，但 H1 应是品牌、产品、对象或品类，说明文案放在副标题。
+- 可视化、游戏、创作工具：可以使用更强视觉资产和动效，但必须保持交互可控、状态清晰。
+- 每个重要界面都应有贴合业务的视觉锚点，例如真实媒体、数据形态、行业材质、字体性格、空间组织或交互节奏。
+- 大胆设计必须服务场景；高频工具重效率和稳定，展示型页面重主体识别和记忆点。
 
 避免：
 
-- 把日常高频工具做成营销落地页
-- 默认使用紫色渐变、装饰光斑、堆叠卡片或空泛 hero
-- 使用无语境默认字体、平均分布的弱对比配色、模板化双栏 hero 或重复圆角卡片作为通用答案
-- 页面区块大面积卡片化，尤其是卡片套卡片
-- 用可见说明文字解释常见控件本该表达的功能
-- 让整个界面只由一个色相的深浅变化组成
+- 把日常高频工具做成营销落地页。
+- 默认使用紫色渐变、装饰光斑、堆叠卡片、空泛 hero 或无语境默认字体。
+- 页面区块大面积卡片化，尤其是卡片套卡片。
+- 用可见说明文字解释常见控件本该表达的功能。
+- 让整个界面只由一个色相的深浅变化组成。
 
-### 视觉语言基线
+## 设计稿转代码规则
 
-- 字体：优先复用项目字体体系；新建方向时，标题和正文应形成性格与可读性的分工
-- 色彩：区分主色、强调色、状态色和中性色，关键动作与风险状态不能只靠透明度表达
-- 动效：只为入场、层级展开、状态确认、错误反馈和重点引导编排节奏，并尊重 `prefers-reduced-motion`
-- 空间：根据任务选择高密度、留白、非对称、分栏、画布式或编辑器式布局，不套用固定卡片模板
-- 质感：背景、纹理、阴影和透明度应解释层级或语境，不作为无内容装饰
+- 有设计上下文时，先通过 MCP 或截图/标注读取事实来源，不靠猜测决定布局、间距、字体、颜色或状态。
+- 设计稿中的颜色、间距、圆角、阴影和字体应映射到现有 token、CSS 变量、主题变量或组件 variant。
+- 创建新组件前先检查现有组件库和业务组件，优先复用。
+- 默认验证 mobile(375px)、tablet(768px)、desktop(1440px)。
+- 像素还原要求以项目约定为准；没有约定时，核心结构、间距、字体、状态和交互优先于机械追求截图重合。
+- 复杂设计任务实现前先给出简短实现计划，说明复用组件、新建组件、可能改动文件、响应式策略和 token 映射。
 
-### 设计系统生成与覆盖
+## 设计 Token 与样式
 
-- 项目缺少设计方向时，可先生成轻量设计系统建议，再根据真实业务、组件库和数据校正
-- `design-system/<project>/MASTER.md` 记录跨页面共享的产品类型、视觉语言、token 方向、动效、图表和 QA 规则
-- `design-system/<project>/pages/<page>.md` 只记录页面差异：首屏结构、组件密度、图表选择、状态覆盖和局部 token 调整
-- 构建页面或检查 UI 时，先读取页面 override，再读取 Master；页面规则不能复制全量 Master
-- 产品类型推理要落到界面决策：行业风险、用户频率、数据密度、触摸/鼠标场景、图表任务和转化路径
-- 交付前 QA 至少覆盖可访问性、交互反馈、布局溢出、字体色彩、动效降级、表单、导航和图表可读性
+- 优先使用已有 design token、CSS 变量或主题变量；不要硬编码颜色、圆角、间距、阴影和字体取值。
+- 缺少所需 token 时要明确指出，并集中补齐或记录，不在多个组件里散落字面量。
+- Tailwind 项目中，token 应通过语义化 `theme.extend`、CSS 变量或组件 variant 承接；不要把 `blue-600`、`rounded-xl` 等具体值复制成事实标准。
+- 组件 variant 应区分语义 tone、尺寸 size、密度 density 和状态 state；不要让一个字符串参数同时承载多种业务含义。
+- 动态 Tailwind class 必须可被构建扫描识别；复杂映射使用显式对象、variant 工具或 safelist。
+- 优先使用局部、受控的样式，不做大范围全局覆盖；与项目现有 CSS Modules、Tailwind、组件库或样式体系保持一致。
 
-## 设计稿转代码规则
+## 界面质感基线
 
-当存在设计上下文时：
-
-- 先通过 MCP 读取设计上下文（Figma / MasterGo / Pixso / 墨刀 / Sketch，摹客则使用截图/标注）
-- 设计稿中的颜色/间距 token 必须从 design token 文件中引用
-- 如果已有设计上下文，不要靠猜测来决定布局、间距、字体、颜色或状态
-- 在创建新组件前，先检查现有组件，优先复用现有组件库中的组件
-- 响应式断点: mobile(375px) / tablet(768px) / desktop(1440px)
-- 像素还原精度要求: ≥ 95%
-- 在改文件前先给出简短实现计划
-
-始终要考虑：
-
-- loading 状态
-- empty 状态
-- error 状态
-- disabled 状态
-- hover 状态
-- focus 状态
-- 在相关场景下的 selected 状态
-- 响应式行为
-
-## 设计 Token 规则
-
-- 优先使用已有 design token、CSS 变量或主题变量
-- 当已有 Token 可用时，不要硬编码颜色、圆角、间距、阴影和字体取值
-- 如果缺少所需 Token，要明确指出，不要悄悄到处硬编码
-- Token 使用方式要与周边模块保持一致
-- Tailwind 项目中，token 应通过语义化 `theme.extend`、CSS 变量或组件 variant 承接；不要把 `blue-600`、`rounded-xl` 等具体值复制成事实标准
-- 组件 variant 应区分语义 tone、尺寸 size、密度 density 和状态 state；不要让一个字符串参数承载多种业务含义
-- 动态 Tailwind class 必须可被构建扫描识别；复杂映射使用显式对象、variant 工具或 safelist
-
-## 样式规则
-
-- 优先使用局部、受控的样式，而不是大范围全局覆盖
-- 保持当前断点下的响应式行为
-- 与项目现有样式体系保持一致
-- 检查 hover、active、focus、disabled、selected 等状态
-- 除非没有合适 Token 或刻度值，否则不要使用 magic number
-
-### 界面质感基线
-
-- 嵌套圆角保持光学关系：外层圆角约等于内层圆角 + 间距
-- 图标按钮、箭头、播放三角等非对称图形按视觉中心微调
-- 小控件命中区域至少 40x40px，空间允许时优先 44x44px
-- 标题和短文本可用 `text-wrap: balance`，短中正文可用 `text-wrap: pretty`
-- 计数器、价格、时间、表格数字使用 `font-variant-numeric: tabular-nums`
-- 图片在浅/深色背景上边缘不清时，使用中性 alpha 内描边，不使用品牌色描边
-- 动效只声明实际变化属性，禁止 `transition: all` 和 `will-change: all`
-- 进入/退出动效要克制，并尊重 `prefers-reduced-motion`
+- 嵌套圆角保持光学关系：外层圆角约等于内层圆角 + 间距。
+- 图标按钮、箭头、播放三角等非对称图形按视觉中心微调。
+- 小控件命中区域至少 40x40px，空间允许时优先 44x44px。
+- 标题和短文本可用 `text-wrap: balance`，短中正文可用 `text-wrap: pretty`。
+- 计数器、价格、时间、表格数字使用 `font-variant-numeric: tabular-nums`。
+- 动效只声明实际变化属性，禁止 `transition: all` 和 `will-change: all`，并尊重 `prefers-reduced-motion`。
 
 ## 暗色模式
 
-提供与系统主题同步的手动切换能力，减少视觉疲劳并满足可访问性要求。
-
-### CSS 变量方案
-
-```css
-:root {
-  --color-bg-primary: #ffffff;
-  --color-bg-secondary: #f5f5f5;
-  --color-text-primary: #1a1a1a;
-  --color-text-secondary: #666666;
-  --color-border: #e0e0e0;
-}
-
-[data-theme="dark"] {
-  --color-bg-primary: #1a1a1a;
-  --color-bg-secondary: #2a2a2a;
-  --color-text-primary: #f0f0f0;
-  --color-text-secondary: #a0a0a0;
-  --color-border: #404040;
-}
-
-body {
-  background-color: var(--color-bg-primary);
-  color: var(--color-text-primary);
-}
-```
-
-### Tailwind 方案
-
-```js
-// tailwind.config.js
-module.exports = {
-  darkMode: "class", // 通过 .dark 类控制，而非 prefers-color-scheme
-};
-```
-
-```html
-<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
-  <!-- 内容 -->
-</div>
-```
-
-### 主题切换 Hook
-
-```tsx
-import { useState, useEffect } from "react";
-
-function useTheme() {
-  const [theme, setTheme] = useState<"light" | "dark">("light");
-
-  useEffect(() => {
-    // 1. 优先读取用户保存的偏好
-    const saved = localStorage.getItem("theme") as "light" | "dark" | null;
-    if (saved) {
-      setTheme(saved);
-      return;
-    }
-    // 2. 回退到系统偏好
-    const prefersDark = window.matchMedia(
-      "(prefers-color-scheme: dark)",
-    ).matches;
-    setTheme(prefersDark ? "dark" : "light");
-  }, []);
-
-  useEffect(() => {
-    const root = document.documentElement;
-    if (theme === "dark") {
-      root.classList.add("dark");
-      root.setAttribute("data-theme", "dark");
-    } else {
-      root.classList.remove("dark");
-      root.setAttribute("data-theme", "light");
-    }
-    localStorage.setItem("theme", theme);
-  }, [theme]);
-
-  const toggle = () => setTheme((t) => (t === "light" ? "dark" : "light"));
-
-  return { theme, toggle };
-}
-```
-
-### FOUC 防护（主题闪烁）
-
-在 `<head>` 中同步执行主题初始化脚本（阻塞渲染），避免首次加载时出现错误的主题色：
-
-```html
-<head>
-  <script>
-    // 同步执行 — 在 body 渲染前确定主题
-    (function () {
-      const theme =
-        localStorage.getItem("theme") ||
-        (window.matchMedia("(prefers-color-scheme: dark)").matches
-          ? "dark"
-          : "light");
-      if (theme === "dark") {
-        document.documentElement.classList.add("dark");
-        document.documentElement.setAttribute("data-theme", "dark");
-      }
-    })();
-  </script>
-</head>
-```
-
-### 暗色模式注意事项
-
-- **图片**: 亮色图片在暗色模式下刺眼，使用 `filter: brightness(0.8)` 降低亮度
-- **阴影**: 暗色模式下阴影不明显，改用 `box-shadow: 0 0 15px rgba(255,255,255,0.05)` 或边框替代
-- **颜色对比度**: 确保暗色模式下文本与背景的对比度 ≥ 4.5:1（WCAG AA）
-- **表单控件**: 输入框、下拉框、开关等原生控件在暗色模式下需要自定义样式
-- **第三方组件**: 检查 UI 组件库是否支持暗色模式，必要时用 CSS 变量覆盖
-- **Tailwind 组件**: 暗色模式下需复核 focus、disabled、selected、invalid、skeleton、chart 和阴影层级，不只补 `dark:` 背景色
-
----
+- 项目级暗色模式只选择一种主策略：CSS 变量、根节点 class、`data-theme` 或组件库主题。
+- 支持手动切换主题时，要在首屏绘制前初始化用户偏好，避免主题闪烁；实现细节交给 Tailwind / design-system skill reference。
+- 亮色与暗色都要复核 disabled、focus、selected、invalid、skeleton、chart、表单控件、第三方组件和阴影层级。
+- 不只靠降低透明度表达 disabled，不只补背景色而忽略文本、边框、图表和焦点状态。
 
 ## 可访问性基线
 
-优先使用语义化 HTML。
-
-确保：
-
-- 表单控件具备标签
-- 纯图标按钮具有可访问名称
-- 菜单、标签页、对话框和自定义控件支持键盘操作
-- 焦点样式可见
-- 编辑页面时标题层级正确
-- 真实表格数据使用正确表格语义
-
-## UI 任务的输出要求
-
-对于较复杂的设计类任务，开始时先给出：
-
-- 复用的组件
-- 新建的组件
-- 可能改动的文件
-- 响应式策略
-- Token 映射或样式策略
+- 优先使用语义化 HTML。
+- 表单控件具备标签，纯图标按钮具备可访问名称。
+- 菜单、标签页、对话框和自定义控件支持键盘操作。
+- 焦点样式可见，标题层级正确，真实表格数据使用表格语义。
+- 颜色对比度、触摸目标、reduced-motion 和错误提示不能被视觉 polish 破坏。
 
-实现完成后，需要说明：
+## UI 任务输出
 
-- 复用了什么
-- 新建了什么
-- 与设计稿有哪些偏差
-- 缺少哪些 Token、资源或交互细节
+实现完成后说明复用了什么、新建了什么、与设计稿或项目 token 的偏差、缺少哪些资源或交互细节。复杂 UI 还应说明状态覆盖、响应式验证和剩余设计风险。