phase-design 设计阶段技能（融合版）

name: phase-design
description: 将PRD文档转化为标准化设计方案，输出三种格式（MD/JSON/YAML）供下游使用

技能定位

本技能负责设计阶段，将需求文档（PRD）转化为结构化的设计方案，采用分层架构（L4布局层 + L5模块层），输出三种独立格式供下游消费。

上游输入：
- phase-requirement 输出的 PRD 文档.md
- 或用户直接提供的系统需求描述

下游输出：
- 设计方案.md（详细设计描述）
- 设计方案.json（DSL JSON数据结构）
- 设计参数.yaml（SPEC YAML参数配置）

分层架构

本技能采用 L4 + L5 两层架构：

┌─────────────────────────────────────────────────────────┐
│                     L4-Layouts-designer                  │
│                   布局层 - 页面级设计                      │
├─────────────────────────────────────────────────────────┤
│  • 7种标准布局模式（LayoutPage-1~7）                      │
│  • 20种页面类型规范                                       │
│  • 组件令牌系统（component_tokens.md）                    │
│  • 栅格系统与响应式设计                                    │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                    L5-Module-designer                    │
│                   模块层 - 区域级设计                      │
├─────────────────────────────────────────────────────────┤
│  • BEM命名规范                                           │
│  • 四层容器结构（Page→Section→Block→Element）            │
│  • 模块HTML模板库（module-templates.md）                 │
│  • 字段描述规范                                          │
└─────────────────────────────────────────────────────────┘

工作流程

Step 1: 提取需求

输入来源：
1. PRD 文档（含页面清单、模块字段、操作交互）
2. 用户直接提供的系统需求

提取要素：
- 系统类型（CRM/OA/ERP等）
- 页面清单
- 功能模块与字段
- 操作交互需求

Step 2: 选择布局（L4）

7种标准布局：

页面类型映射：

Step 3: 规划模块结构（L5）

BEM命名规范：

Block（模块）         → .user-module
Block__Element（元素） → .user-module__header
Block--Modifier（修饰）→ .user-module--collapsed

四层容器结构：

Page（页面层）
  └── Section（区域层）
        └── Block（模块层）
              └── Element（组件层）

标准区域划分：
1. 头部区域（Header Section）：页面标题、面包屑、全局操作
2. 筛选区域（Filter Section）：搜索、筛选条件、批量操作
3. 内容区域（Content Section）：数据表格、卡片列表、详情信息
4. 操作区域（Action Section）：分页、底部按钮、悬浮操作

Step 4: 选择组件

组件令牌系统：位于 L4-Layouts-designer/references/component_tokens.md

令牌格式：[类别]::[组件]::[变体]

组件令牌与BEM的关系：
- 组件令牌描述「是什么」组件（语义层面）
- BEM命名描述「在哪里」放置（位置层面）
- 解耦原则：令牌不强制绑定特定BEM容器，可灵活放置

Step 5: 生成三种输出

输出1：设计方案.md
- 详细的设计描述文档
- 按区域划分的设计详情
- 人类可读的设计说明

输出2：设计方案.json
- DSL JSON数据结构
- 机器可解析的设计数据
- 供自动化工具使用

输出3：设计参数.yaml
- SPEC YAML参数配置
- 设计系统Token值
- 供前端工程化使用

Python引擎使用（保守模式）

保留Python引擎仅用于辅助查询，精简后的命令：

核心原则

1. 组件令牌与BEM解耦

• 令牌描述组件语义，不绑定特定容器
• BEM描述布局位置，灵活容纳各种令牌
• 映射表提供参考，不限制实际使用

2. 三种输出职责分明

• MD → 人类可读的设计文档
• JSON → 机器可解析的数据结构
• YAML → 工程化的参数配置

3. 分层设计清晰

• L4 负责页面级布局规划
• L5 负责区域级模块设计
• 各层职责单一，边界清晰

4. Python引擎保守使用

• 仅用于快速查询和辅助决策
• 不用于生成SPEC或验证逻辑
• LLM承担主要的分析和生成工作

知识库结构

phase-design/
├── SKILL.md                          # 本文件（主入口）
├── design_engine.py                  # Python引擎（精简版）
│
├── L4-Layouts-designer/              # 布局层
│   ├── skill.md                      # L4技能定义
│   └── references/
│       ├── 00-page-layouts.md       # 7种标准布局
│       ├── 01-dashboard.md          # Dashboard规范
│       ├── 02-list-table.md         # 列表页规范
│       ├── ...                      # 其他页面类型
│       ├── component_tokens.md      # 组件令牌系统（来自M版）
│       └── layout-grid.md           # 栅格系统
│
├── L5-Module-designer/               # 模块层
│   ├── skill.md                      # L5技能定义
│   └── references/
│       ├── bem-naming.md            # BEM命名规范
│       ├── module-structure.md      # 四层容器结构
│       ├── module-templates.md      # 模块HTML模板库（新增）
│       └── module-best-practices.md # 最佳实践
│
└── templates/                        # 输出模板
    ├── design-output-template.md    # MD输出模板
    ├── dsl-json-template.json       # JSON输出模板
    └── spec-yaml-template.yaml      # YAML输出模板

使用示例

场景1：来自PRD文档

输入：PRD文档.md（含页面清单、模块字段）

↓

Step 1: 提取页面清单
- 客户列表页
- 客户详情页  
- 商机看板

Step 2: L4选择布局
- 系统类型：CRM
- 推荐布局：LayoutPage-2（侧边栏+顶栏+内容区）
- 页面类型：列表页(02) + 详情页(10) + Dashboard(01)

Step 3: L5规划模块
- 头部区域：页面标题 + 面包屑
- 筛选区域：搜索框 + 筛选条件 + 新建按钮
- 内容区域：数据表格（客户列表）
- 操作区域：分页器

Step 4: 选择组件令牌
- `GEN::Button::primary` → 新建客户按钮
- `ENT::Input::search` → 搜索框
- `DISP::Table::selection` → 客户列表表格

Step 5: 生成三种输出
- 设计方案.md（按区域划分）
- 设计方案.json（DSL结构）
- 设计参数.yaml（SPEC参数）

场景2：用户直接需求

输入："做一个简单的客户管理系统"

↓

Step 1: 快速推断需求
- 系统类型：CRM
- 核心页面：客户列表、客户详情、Dashboard

后续步骤同上...

输出规范

MD输出规范

按以下结构组织（详见 templates/design-output-template.md）：

# [页面名称] 设计方案

## 页面信息
## 页面描述
## 整体页面布局结构
## 区域详细设计（按区域划分）
### 区域1: [区域名称]
### 区域2: [区域名称]
...
## 组件令牌汇总
## 设计规范

JSON输出规范

DSL JSON结构（详见 templates/dsl-json-template.json）：

{
  "version": "1.0",
  "pages": [{
    "id": "",
    "layout": "",
    "sections": [{
      "id": "",
      "components": []
    }]
  }]
}

YAML输出规范

SPEC YAML参数（详见 templates/spec-yaml-template.yaml）：

Global:
  layout: ""
  theme: {}
Regions: []
Modules: []

注意事项

1. L3模式层暂不关联：当前版本暂不引用L3的模式知识库，专注于L4+L5的落地实现
2. L6页面层已取消：不再维护独立的L6页面知识库，页面规范整合到L4
3. 令牌与BEM解耦：组件令牌描述语义，BEM描述位置，两者独立
4. 三种输出分开：MD/JSON/YAML三种格式独立输出，不融合