npm - sinapse-ai - Versions diffs - 5.0.8 → 6.0.0 - Mend

sinapse-ai 5.0.8 → 6.0.0

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.

Files changed (660) hide show

package/docs/zh/sinapse-workflows/design-system-build-quality-workflow.md DELETED Viewed

@@ -1,845 +0,0 @@
-# 设计系统构建质量流水线
-**工作流 ID:** `design-system-build-quality`
-**版本:** 1.0.0
-**类型:** 棕地
-**状态:** 生产就绪
----
-## 概览
-**设计系统构建质量流水线**是一个迁移后的设计系统工作流。它按顺序链接构建、文档、可访问性审计和 ROI 计算步骤，以确保质量并衡量交付的价值。
-### 目的
-此流水线确保在迁移或创建设计系统后:
-1. **组件正确编译** - 构建令牌和原子组件
-2. **文档完整** - 带示例和指南的模式库
-3. **可访问性已验证** - WCAG 2.1 AA 合规性
-4. **ROI 已衡量** - 经济和价值交付指标
-### 何时使用
-| 场景 | 建议 |
-|------|------|
-| 设计系统迁移后 | 强烈推荐 |
-| 发布新版本模式库 | 必需 |
-| 定期质量审计 | 推荐 (季度) |
-| 组件生产前验证 | 必需 |
-| 为利益相关者生成指标 | 根据需要 |
-### 支持的项目类型
-- `design-system`
-- `component-library`
-- `pattern-library`
-- `ui-migration`
----
-## 工作流图
-### 主流程
-```mermaid
-flowchart TD
-    subgraph INICIO["🚀 开始"]
-        A[启动: 设计系统质量流水线]
-    end
-    subgraph PHASE1["📦 阶段 1: 构建和编译"]
-        B[ux-design-expert:<br/>构建原子组件]
-        B1[编译设计令牌]
-        B2[生成原子组件]
-        B3[验证结构和命名]
-        B4[检查依赖]
-        B --> B1
-        B1 --> B2
-        B2 --> B3
-        B3 --> B4
-    end
-    subgraph DECISION1["❓ 构建决策"]
-        C{构建 OK?}
-        E[🔴 修正构建错误]
-    end
-    subgraph PHASE2["📚 阶段 2: 文档"]
-        D[ux-design-expert:<br/>生成模式库文档]
-        D1[记录 props 和变体]
-        D2[创建使用示例]
-        D3[生成样式指南]
-        D4[更新更新日志]
-        D --> D1
-        D1 --> D2
-        D2 --> D3
-        D3 --> D4
-    end
-    subgraph DECISION2["❓ 文档决策"]
-        F{文档完整?}
-        H[🔴 完成文档]
-    end
-    subgraph PHASE3["♿ 阶段 3: 质量保证"]
-        G[ux-design-expert:<br/>WCAG AA 可访问性审计]
-        G1[检查颜色对比]
-        G2[验证键盘导航]
-        G3[检查 ARIA 属性]
-        G4[用屏幕阅读器测试]
-        G5[检查焦点状态]
-        G --> G1
-        G1 --> G2
-        G2 --> G3
-        G3 --> G4
-        G4 --> G5
-    end
-    subgraph DECISION3["❓ A11y 决策"]
-        I{A11y 已批准?}
-        K[🔴 修正违规]
-    end
-    subgraph PHASE4["💰 阶段 4: ROI 分析"]
-        J[ux-design-expert:<br/>计算 ROI 和节省]
-        J1[节省的开发时间]
-        J2[减少不一致]
-        J3[功能交付速度]
-        J4[降低的维护成本]
-        J5[重用指标]
-        J --> J1
-        J1 --> J2
-        J2 --> J3
-        J3 --> J4
-        J4 --> J5
-    end
-    subgraph FIM["✅ 完成"]
-        L[流水线完成]
-        L1[📊 构建报告 + bundle]
-        L2[📖 模式库文档]
-        L3[♿ WCAG AA 报告]
-        L4[💵 ROI 仪表板]
-        L --> L1
-        L --> L2
-        L --> L3
-        L --> L4
-    end
-    A --> B
-    B4 --> C
-    C -->|是| D
-    C -->|否| E
-    E --> B
-    D4 --> F
-    F -->|是| G
-    F -->|否| H
-    H --> D
-    G5 --> I
-    I -->|是| J
-    I -->|否| K
-    K --> G
-    J5 --> L
-    style L fill:#90EE90,stroke:#228B22,stroke-width:2px
-    style A fill:#87CEEB,stroke:#4169E1,stroke-width:2px
-    style B fill:#E6E6FA,stroke:#9370DB,stroke-width:2px
-    style D fill:#E6E6FA,stroke:#9370DB,stroke-width:2px
-    style G fill:#E6E6FA,stroke:#9370DB,stroke-width:2px
-    style J fill:#E6E6FA,stroke:#9370DB,stroke-width:2px
-    style E fill:#FFB6C1,stroke:#DC143C,stroke-width:2px
-    style H fill:#FFB6C1,stroke:#DC143C,stroke-width:2px
-    style K fill:#FFB6C1,stroke:#DC143C,stroke-width:2px
-```
-### 简化视图
-```mermaid
-graph LR
-    subgraph Pipeline
-        BUILD["📦 构建"] --> DOCS["📚 文档"]
-        DOCS --> A11Y["♿ A11y"]
-        A11Y --> ROI["💰 ROI"]
-    end
-    START((开始)) --> BUILD
-    ROI --> FINISH((完成))
-    style START fill:#87CEEB
-    style FINISH fill:#90EE90
-```
-#### 依赖流
-```mermaid
-graph TD
-    subgraph Outputs["生成的工件"]
-        O1[build_report]
-        O2[compiled_tokens]
-        O3[component_bundle]
-        O4[pattern_library_docs]
-        O5[component_api_reference]
-        O6[style_guide]
-        O7[a11y_audit_report]
-        O8[violations_list]
-        O9[remediation_plan]
-        O10[roi_report]
-        O11[savings_metrics]
-        O12[adoption_dashboard]
-    end
-    BUILD[构建] --> O1 & O2 & O3
-    DOCS[文档] --> O4 & O5 & O6
-    A11Y[可访问性] --> O7 & O8 & O9
-    ROI[ROI 分析] --> O10 & O11 & O12
-    O1 -.-> DOCS
-    O4 -.-> A11Y
-    O7 -.-> ROI
-```
----
-## 详细步骤
-### 步骤 1: 构建原子组件
-| 属性 | 值 |
-|------|-----|
-| **ID** | `build` |
-| **阶段** | 1 - 构建和编译 |
-| **代理** | `ux-design-expert` (Uma) |
-| **操作** | 原子组件构建 |
-| **依赖** | 无 (初始步骤) |
-#### 描述
-执行设计系统组件的构建，编译令牌并生成原子组件。
-#### 执行的活动
-1. **编译设计令牌** - 颜色、排版、间距
-2. **生成原子组件** - 按钮、输入、卡片等。
-3. **验证文件结构和命名**
-4. **检查依赖和导入**
-#### 成功标准
-- [ ] 构建完成无错误
-- [ ] 所有令牌已编译
-- [ ] 组件正确导出
-#### 输出
-| 工件 | 描述 |
-|------|------|
-| `build_report` | 构建过程报告 |
-| `compiled_tokens` | 已编译的设计令牌 (CSS/JS) |
-| `component_bundle` | 已准备的组件 bundle |
----
-### 步骤 2: 生成文档
-| 属性 | 值 |
-|------|-----|
-| **ID** | `document` |
-| **阶段** | 2 - 文档 |
-| **代理** | `ux-design-expert` (Uma) |
-| **操作** | 生成模式库文档 |
-| **依赖** | `build` (步骤 1) |
-#### 描述
-生成模式库的完整文档，包括组件 API、示例和样式指南。
-#### 执行的活动
-1. **记录每个组件**及其 props 和变体
-2. **创建使用示例**和代码片段
-3. **生成可视样式指南**
-4. **更新组件更新日志**
-#### 成功标准
-- [ ] 所有组件都有文档
-- [ ] 代码示例有效
-- [ ] 样式指南已更新
-#### 输出
-| 工件 | 描述 |
-|------|------|
-| `pattern_library_docs` | 模式库的完整文档 |
-| `component_api_reference` | 组件 API 参考 |
-| `style_guide` | 可视样式指南 |
----
-### 步骤 3: 可访问性审计
-| 属性 | 值 |
-|------|-----|
-| **ID** | `a11y-check` |
-| **阶段** | 3 - 质量保证 |
-| **代理** | `ux-design-expert` (Uma) |
-| **操作** | 可访问性审计 (WCAG AA) |
-| **依赖** | `document` (步骤 2) |
-#### 描述
-按 WCAG 2.1 AA 执行可访问性审计，验证对比度、导航和辅助技术兼容性。
-#### 执行的活动
-1. **检查颜色对比** - 4.5:1 文本，3:1 UI
-2. **验证键盘导航**
-3. **检查 ARIA 属性和角色**
-4. **用屏幕阅读器测试**
-5. **检查焦点状态和视觉指示器**
-#### 成功标准
-- [ ] 颜色对比已批准
-- [ ] 键盘导航有效
-- [ ] ARIA 标签正确
-- [ ] 无 WCAG AA 关键违规
-#### 输出
-| 工件 | 描述 |
-|------|------|
-| `a11y_audit_report` | 完整的审计报告 |
-| `violations_list` | 发现的违规列表 |
-| `remediation_plan` | 违规修正计划 |
----
-### 步骤 4: 计算 ROI
-| 属性 | 值 |
-|------|-----|
-| **ID** | `calculate-roi` |
-| **阶段** | 4 - ROI 分析 |
-| **代理** | `ux-design-expert` (Uma) |
-| **操作** | ROI 和节省的计算 |
-| **依赖** | `a11y-check` (步骤 3) |
-#### 描述
-计算设计系统的投资回报率，衡量时间节省、不一致性减少和重用指标。
-#### 计算的指标
-1. **节省的开发时间** (小时/月)
-2. **视觉不一致降低** (%)
-3. **功能交付速度** (平均时间)
-4. **降低的维护成本** ($)
-5. **组件重用率** (%)
-#### 成功标准
-- [ ] 每月节省的开发小时数已计算
-- [ ] 组件重用百分比已衡量
-- [ ] 平均新功能时间已计算
-- [ ] 视觉 bug 的减少已量化
-#### 输出
-| 工件 | 描述 |
-|------|------|
-| `roi_report` | 完整的 ROI 报告 |
-| `savings_metrics` | 详细的节省指标 |
-| `adoption_dashboard` | 设计系统采用情况仪表板 |
----
-## 参与的代理
-### ux-design-expert (Uma)
-| 属性 | 值 |
-|------|-----|
-| **名字** | Uma |
-| **角色** | UX/UI 设计师和设计系统架构师 |
-| **图标** | 🎨 |
-| **原型** | 共鸣者 |
-#### 混合哲学
-Uma 结合了两种互补的方法:
-**Sally 的 UX 原则 (研究阶段):**
-- 以用户为中心: 基于真实需求的决策
-- 同理心发现: 深度用户研究
-- 迭代简单: 从简单开始，通过反馈优化
-- 细节的喜悦: 微交互创造难忘体验
-**Brad Frost 的系统原则 (构建和扩展阶段):**
-- 指标驱动: 数据而非观点
-- 视觉冲击疗法: 用真实数据显示混乱
-- 智能整合: 模式的算法聚类
-- ROI 集中: 计算节省，证明价值
-- 无硬编码值: 所有样式来自令牌
-- 原子设计: Atoms → Molecules → Organisms → Templates → Pages
-- WCAG AA 最低: 内置可访问性
-#### 此工作流的相关命令
-| 命令 | 描述 | 阶段 |
-|------|------|------|
-| `*build {component}` | 原子组件构建 | 4 |
-| `*document` | 生成模式库文档 | 5 |
-| `*a11y-check` | WCAG AA/AAA 审计 | 5 |
-| `*calculate-roi` | 计算 ROI 和经济 | 5 |
----
-## 执行的任务
-### 按步骤的任务映射
-| 步骤 | 任务文件 | 描述 |
-|------|---------|------|
-| 构建 | `build-component.md` | 原子组件构建 |
-| 文档 | `generate-documentation.md` | 模式库生成 |
-| A11y 审计 | `accessibility-wcag-checklist.md` | WCAG 2.1 AA 检查清单 |
-| ROI | `calculate-roi.md` | ROI 和指标计算 |
-### 任务依赖图
-```mermaid
-graph TD
-    subgraph Phase1["阶段 1: 构建"]
-        T1[build-component.md]
-    end
-    subgraph Phase2["阶段 2: 文档"]
-        T2[generate-documentation.md]
-    end
-    subgraph Phase3["阶段 3: 质量"]
-        T3[accessibility-wcag-checklist.md]
-    end
-    subgraph Phase4["阶段 4: ROI"]
-        T4[calculate-roi.md]
-    end
-    T1 --> T2 --> T3 --> T4
-```
----
-## 前置条件
-### 技术要求
-| 要求 | 描述 |
-|------|------|
-| 现有设计系统 | 组件已迁移/创建 |
-| 令牌结构 | `tokens.yaml` 或等价的已配置 |
-| 构建环境 | Node.js 18+、npm/yarn/pnpm |
-| 测试工具 | Jest、Testing Library (推荐) |
-### 项目要求
-- [ ] 设计系统迁移完成 (或创建了 v1)
-- [ ] 设计令牌已提取并组织
-- [ ] 原子组件已定义 (atoms、molecules、organisms)
-- [ ] 文件夹结构遵循原子设计
-### 团队要求
-- [ ] 原子设计方法论的知识
-- [ ] WCAG 2.1 指南的熟悉
-- [ ] 设计系统存储库的访问权限
----
-## 输入和输出
-### 流水线输入
-| 输入 | 类型 | 描述 |
-|------|------|------|
-| 设计令牌来源 | `tokens.yaml` | 颜色、排版、间距定义 |
-| 组件源文件 | `*.tsx`、`*.css` | 组件源代码 |
-| 现有文档 | `*.md` | 现有文档 (如有) |
-### 流水线输出
-#### 阶段 1: 构建和编译
-```text
-outputs/design-system/
-├── build_report.json
-├── compiled/
-│   ├── tokens.css
-│   ├── tokens.js
-│   └── tokens.d.ts
-└── bundle/
-    ├── components.js
-    └── components.d.ts
-```
-#### 阶段 2: 文档
-```text
-outputs/design-system/
-├── docs/
-│   ├── pattern-library/
-│   │   ├── index.html
-│   │   ├── atoms/
-│   │   ├── molecules/
-│   │   └── organisms/
-│   ├── api-reference/
-│   │   └── components.md
-│   └── style-guide/
-│       └── index.html
-└── changelog.md
-```
-#### 阶段 3: 质量保证
-```text
-outputs/design-system/
-├── a11y/
-│   ├── audit-report.html
-│   ├── violations.json
-│   └── remediation-plan.md
-```
-#### 阶段 4: ROI 分析
-```text
-outputs/design-system/
-├── metrics/
-│   ├── roi-report.pdf
-│   ├── savings-breakdown.json
-│   └── adoption-dashboard.html
-```
----
-## 决策点
-### 决策 1: 构建 OK?
-```mermaid
-graph TD
-    BUILD[构建完成] --> CHECK{错误?}
-    CHECK -->|是| FIX[修正错误]
-    CHECK -->|否| PROCEED[继续文档]
-    FIX --> BUILD
-```
-**通过标准:**
-- 无编译错误
-- 所有令牌有效
-- 导出有效
-**失败操作:**
-1. 审查构建日志
-2. 修正语法/导入错误
-3. 验证令牌结构
-4. 重新运行构建
----
-### 决策 2: 文档完整?
-```mermaid
-graph TD
-    DOCS[文档已生成] --> CHECK{完整?}
-    CHECK -->|是| PROCEED[继续 A11y]
-    CHECK -->|否| COMPLETE[完成文档]
-    COMPLETE --> DOCS
-```
-**通过标准:**
-- 100% 的组件已记录
-- 代码示例有效
-- 样式指南已更新
-**失败操作:**
-1. 识别无文档的组件
-2. 添加缺失的 props 和示例
-3. 更新更新日志
-4. 重新生成文档
----
-### 决策 3: 可访问性已批准?
-```mermaid
-graph TD
-    A11Y[A11y 审计] --> CHECK{已批准?}
-    CHECK -->|是| PROCEED[继续 ROI]
-    CHECK -->|否| FIX[修正违规]
-    FIX --> A11Y
-```
-**通过标准:**
-- 无关键违规 (等级 A)
-- 无严重违规 (等级 AA)
-- 100% 键盘导航功能
-**失败操作:**
-1. 审查 `violations_list`
-2. 遵循 `remediation_plan`
-3. 修正对比问题
-4. 添加缺失的 ARIA 标签
-5. 重新运行审计
----
-## 执行模式
-工作流支持三种执行模式:
-### 模式 YOLO (自主)
-| 属性 | 值 |
-|------|-----|
-| **提示** | 0-1 |
-| **交互** | 最少 |
-| **用途** | CI/CD 流水线、自动化执行 |
-```bash
-# 自主执行
-*workflow design-system-build-quality --mode yolo
-```
-### 模式 Interactive (默认)
-| 属性 | 值 |
-|------|-----|
-| **提示** | 5-10 |
-| **交互** | 决策检查点 |
-| **用途** | 正常开发、教育反馈 |
-```bash
-# 交互执行 (默认)
-*workflow design-system-build-quality
-```
-### 模式 Preflight (规划)
-| 属性 | 值 |
-|------|-----|
-| **提示** | 10-15 |
-| **交互** | 执行前的完整规划 |
-| **用途** | 首次执行、影响分析 |
-```bash
-# 带完整规划的执行
-*workflow design-system-build-quality --mode preflight
-```
----
-## 故障排查
-### 问题: 构建因令牌错误而失败
-**症状:**
-- 错误 "Token not found"
-- 颜色或间距未编译
-**解决方案:**
-```bash
-# 1. 检查令牌结构
-cat tokens.yaml
-# 2. 验证 YAML 语法
-npm run lint:tokens
-# 3. 检查交叉参考
-grep -r "var(--" src/
-```
----
-### 问题: 文档不完整
-**症状:**
-- 组件无示例
-- Props 未记录
-**解决方案:**
-```bash
-# 1. 列出无文档的组件
-*audit --check-docs
-# 2. 生成文档存根
-*document --generate-stubs
-# 3. 手动完成并重新运行
-*document
-```
----
-### 问题: 可访问性违规
-**症状:**
-- 对比失败
-- ARIA 标签缺失
-**解决方案:**
-```bash
-# 1. 审查详细报告
-cat outputs/design-system/a11y/violations.json
-# 2. 使用对比工具
-# 推荐: WebAIM 对比检查器
-# 3. 添加 ARIA 标签
-# 遵循 remediation-plan.md
-# 4. 重新运行审计
-*a11y-check
-```
----
-### 问题: ROI 计算不正确
-**症状:**
-- 指标为零
-- 历史数据缺失
-**解决方案:**
-```bash
-# 1. 检查输入数据
-cat .state.yaml
-# 2. 手动提供基准
-*calculate-roi --baseline "manual"
-# 3. 使用市场估计
-# Brad Frost 建议: 30-50% 的开发经济
-```
----
-## 切换提示
-### 构建完成后
-```
-构建组件成功完成。
-令牌已编译: {{token_count}}
-组件已生成: {{component_count}}
-继续文档...
-```
-### 文档后
-```
-模式库文档已生成。
-已记录的组件: {{documented_count}}
-已创建的示例: {{example_count}}
-启动可访问性审计...
-```
-### 可访问性审计后
-```
-WCAG AA 可访问性审计已完成。
-状态: {{pass/fail}}
-关键违规: {{critical_count}}
-次要违规: {{minor_count}}
-{{if pass}}: 继续 ROI 计算。
-{{if fail}}: 在继续前审查 remediation_plan。
-```
-### 流水线完成
-```
-质量流水线已完成!
-摘要:
-- 构建: {{build_status}}
-- 文档: {{docs_status}}
-- 可访问性: {{a11y_status}}
-- 已计算的 ROI: {{roi_value}}
-工件可在 outputs/design-system/ 获得
-```
----
-## 参考
-### 内部文档
-| 文档 | 路径 |
-|------|------|
-| 工作流定义 | `.sinapse-ai/development/workflows/design-system-build-quality.yaml` |
-| UX 设计专家代理 | `.sinapse-ai/development/agents/ux-design-expert.md` |
-| 任务: 构建组件 | `.sinapse-ai/development/tasks/build-component.md` |
-| 任务: 生成文档 | `.sinapse-ai/development/tasks/generate-documentation.md` |
-| 检查清单: WCAG A11y | `.sinapse-ai/development/checklists/accessibility-wcag-checklist.md` |
-| 任务: 计算 ROI | `.sinapse-ai/development/tasks/calculate-roi.md` |
-### 外部参考
-| 资源 | 链接 |
-|------|------|
-| 原子设计 (Brad Frost) | https://atomicdesign.bradfrost.com/ |
-| WCAG 2.1 指南 | https://www.w3.org/WAI/WCAG21/quickref/ |
-| 设计令牌 W3C | https://design-tokens.github.io/community-group/format/ |
-| WebAIM 对比检查器 | https://webaim.org/resources/contrastchecker/ |
-### 相关工作流
-| 工作流 | 描述 |
-|------|------|
-| `brownfield-migration` | 现有设计系统迁移 |
-| `greenfield-design-system` | 从零创建设计系统 |
-| `component-library-setup` | 组件库的初始设置 |
----
-## 版本历史
-| 版本 | 日期 | 作者 | 更改 |
-|------|------|------|------|
-| 1.0.0 | 2025-01-30 | Orion (SINAPSE 主机) | 工作流初始版本 |
----
-## 元数据
-```yaml
-workflow_id: design-system-build-quality
-version: 1.0.0
-type: brownfield
-author: Orion (SINAPSE Master)
-created_date: 2025-01-30
-documentation_created: 2026-02-04
-tags:
-  - design-system
-  - quality-assurance
-  - accessibility
-  - documentation
-  - roi
-  - brownfield
-```
----
-*由技术文档专家生成的文档*
-*SINAPSE-FULLSTACK 框架 v2.2*