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: 提取需求

输入来源：

PRD 文档（含页面清单、模块字段、操作交互）
用户直接提供的系统需求

提取要素：

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

Step 2: 选择布局（L4）

7种标准布局：

| 布局 | 结构 | 适用场景 | |-----|------|---------| | LayoutPage-1 | 顶栏 + 内容区 | 门户/官网 | | LayoutPage-2 | 侧边栏 + 顶栏 + 内容区 | 管理后台（OA/CRM/HRM/ERP） | | LayoutPage-3 | 左侧固定 + 右侧内容 | 文档/详情页 | | LayoutPage-4 | 多标签页 | 重型后台系统 | | LayoutPage-5 | 数据看板 | BI/数据分析 | | LayoutPage-6 | 卡片式布局 | 轻量级管理后台 | | LayoutPage-7 | 混合布局 | 复杂门户系统 |

页面类型映射：

| 系统类型 | 推荐布局 | 典型页面组合 | |---------|---------|-------------| | OA/CRM/HRM/ERP | LayoutPage-2 | Dashboard + 列表 + 详情 + 表单 | | 银行/电商门户 | LayoutPage-1 | 门户首页 + 资讯列表 + 详情 | | 数据看板 | LayoutPage-5 | 多图表Dashboard | | 重型后台 | LayoutPage-4 | 多标签页列表/详情 |

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

BEM命名规范：

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

四层容器结构：

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

标准区域划分：

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

Step 4: 选择组件

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

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

| 前缀 | 类别 | 示例 | |------|------|------| | GEN:: | General 通用 | GEN::Button::primary | | LAY:: | Layout 布局 | LAY::Grid::2col | | NAV:: | Navigation 导航 | NAV::Menu::sidebar | | ENT:: | Entry 录入 | ENT::Input::text | | DISP:: | Display 展示 | DISP::Table::selection | | FB:: | Feedback 反馈 | FB::Modal::confirm |

组件令牌与BEM的关系：

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

Step 5: 生成三种输出

输出1：设计方案.md

详细的设计描述文档
按区域划分的设计详情
人类可读的设计说明

输出2：设计方案.json

DSL JSON数据结构
机器可解析的设计数据
供自动化工具使用

输出3：设计参数.yaml

SPEC YAML参数配置
设计系统Token值
供前端工程化使用

Python引擎使用（保守模式）

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

| 命令 | 用途 | 示例 | |-----|------|------| | match_layout | 快速匹配布局 | python3 design_engine.py match_layout "CRM系统" | | get_page_layout | 获取页面布局规范 | python3 design_engine.py get_page_layout "list_table" | | read_ref | 读取参考文档 | python3 design_engine.py read_ref "00-page-layouts.md" |

核心原则

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: []

注意事项

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