# InspireDesign

> Turn the "inspiration → UI" design methodology into a knowledge asset consumable by both humans and AI.
>
> **把"从灵感到 UI"的方法论，编码成可被人和 AI 共同消费的知识资产。**

InspireDesign 是一个**思维引导工具**。它不替你写代码，也不替你写提示词——它做的是：把一套经过验证的《从灵感到 UI 设计》的工程方法论，封装成人和 AI agent 都能消费的形态，让"有灵感但缺乏 UI 转化经验的人"能在 AI 的引导下，一步步完成从想法到可施工设计稿的转化，并无缝交给 AI 编码助手继续开发。

---

## 1. 这是什么

### 1.1 解决的问题

有灵感，但：

- 不会把想法拆解成页面和功能结构
- 不会"专业地描述"自己想要的界面，AI 看不懂
- 不知道 UI 设计过程每一步该做什么、做到什么程度算做完
- 不懂设计工具（Figma 等），也不想学

结果：灵感死在"说不出来 / 描述不清 / AI 生成的东西不是我想要的"。

### 1.2 做法

把"从灵感到 UI"的过程拆成 9 个阶段（0-8），每个阶段定义一个**约束包**：
目标 / 产物 / 出口条件 / 规则 / 提示词模板 / 依赖 / 常见坑 / 回退影响面。

然后提供两种消费形态：

| 形态 | 消费方 | 作用 |
|---|---|---|
| **页面端** | 人 | 独立浏览整套方法论；知道每个阶段该做什么；复制可用的提示词范例去和 AI 对话 |
| **MCP 服务** | AI agent | AI 调用后获得"当前阶段的完整约束"，据此引导用户：问什么、产出什么、按什么格式、什么时候停下来等人确认 |

**同一份内容，两个出口。** 页面端给人看的是"教程版"，MCP 端给 AI 的是"指令版"。

### 1.3 目标用户

- 有产品想法但非设计/前端专业的人
- 后端背景、想自己完成前端/桌面 UI 开发的开发者
- 任何希望“少用人力操作、以文本驱动 AI 开发”的个人开发者

### 1.4 快速使用

**路径 A / B 二选一（日常使用），路径 C 为可选的静态部署：**

**路径 A —— 让 AI agent 引导你（推荐）**

这是本项目的主要用途。在支持 MCP 的 AI IDE 中注册本服务后，AI 就能按 9 阶段流程引导你完成设计：

1. **注册 MCP 服务**—— 按 [docs/04-MCP服务设计.md](./docs/04-MCP服务设计.md) §6 的格式，在你的 IDE 的 MCP 配置中添加本服务
2. **安装依赖**—— 在本目录运行 `npm install`
3. **对 AI 说话**—— “用 InspireDesign 的 WPF 模式引导我做一个 xxx”
4. **按流程走**—— AI 按 §5.1 的描述：每阶段引导你回答问题 → 产出设计稿 → 等你确认 → 进下一阶段

**路径 B —— 页面端浏览，复制提示词去对话**

1. 启动页面端：`npm run web` → 自动打开 `http://localhost:4173/web/`（页面端自包含，可离线使用）
2. 从「流程全景」进入你想开始的阶段，照着「该怎么做」推进
3. 复制「提示词模板」→ 粘贴到 AI IDE 中对话；「环境清单」可整单复制，交给 AI 去检查

**路径 C —— 部署成静态站点（可选）**

页面端是零构建的静态站点（纯 HTML/CSS/原生 ESM，Mermaid 已本地内置），可直接部署到任意静态服务器：

1. 打包：`npm run build` → 产出 `dist/`（含 `web/`、`data/`、`docs/`、README）
2. 上传 `dist/` 到服务器（nginx / OSS / GitHub Pages 等），把**服务器根目录指向 `dist`**
3. 访问 `http://<域名>/web/`

注意事项：

- **必须保留目录层级**：`web/` 与 `data/` 必须同级——`web/assets/app.js` 以 `../../data/*.js` 引用同一份数据，不能只上传 `web/`
- 路由是 hash 形式（`#/overview`），**无需** SPA 回退（`try_files`）配置
- 页脚 / 关于页的 `docs/*.md`、`README.md` 链接，在 nginx 下默认会触发下载而非浏览；需要内联浏览就加 `types { text/markdown md; }`
- 单页约 5.7MB，主要是 `web/vendor/mermaid.min.js`（5.5MB）；它加载失败时页面自动降级为文字流程图
- 输出目录可用 `OUT_DIR` 覆盖：`OUT_DIR=public npm run build`（PowerShell：`$env:OUT_DIR="public"; npm run build`）

nginx 最简配置：

```nginx
server {
  listen 80;
  root /path/to/dist;   # 指向打包产物目录
  index index.html;
}
```

> 三条路径各自是怎么跑起来的（零基础说明）：见 [docs/07-文件职责说明.md](./docs/07-文件职责说明.md) §7。

不想用页面端时，所有内容也在 markdown 中：通读 [docs/](./docs/) 了解设计理念与流程全景；
工程操作细则见 [WPF-README.md](./WPF-README.md)。

---

## 2. 这不是什么

| 不是 | 说明 |
|---|---|
| 不是 IDE | 不提供编辑器、终端、文件管理 |
| 不是代码生成器 | 不直接调用大模型生成 UI 代码 |
| 不是 Figma 替代品 | 不提供图形化画布 |
| 不是流程的强制执行者 | 工具只提供约束信息；人随时可以跳步、回退、修改 |

---

## 3. 核心理念

### 3.1 设计的事实来源必须是可编辑的文本

| 载体 | 职责 |
|---|---|
| HTML + CSS | **主体**：界面布局、组件、状态 |
| SVG | 图标、需要精确矢量的图元 |
| Mermaid | 流程图、状态图、时序图（只适合"节点+边"，画不了界面布局） |
| PNG 等静态图 | 只做交付物/评审/存档，**任何时候不在图片上改设计** |
| Figma 等工具 | 与流程并存：需要多人评审时，HTML 定稿 → 导出图进 Figma 走评审 → 意见回到 HTML 改，不反向 |

一句话：**图片（PNG）只做交付物，不承担编辑职责。** 设计源是 HTML，改一行即可；图片由 HTML 派生（export-png.py），永远与设计一致。

### 3.2 角色分工：工具 / AI / 人

| 角色 | 职责 |
|---|---|
| **工具**（InspireDesign） | 信息提供者：声明该做什么、需要什么环境、怎么检查、怎么算通过 |
| **AI agent**（Qoder / Trae / Codex / Cursor…） | 执行与引导者：引导对话、检查环境、与用户确认、安装环境、运行脚本、生成产物 |
| **人** | 决策者：确认是否满意、是否安装环境、是否进入下一阶段 |

关键边界：**工具不碰系统环境、不执行操作、不替人做决定。**

### 3.3 人说了算

- 工具不参与"满意度判断"——每个阶段结束时，AI 会停下来问你"这样行吗"，你说行就行。
- 每个阶段的产物都是文本文件，**任何时候可以回退修正**：改前面的文件，重跑下游检查。
- 约束包里带"回退影响面"：告诉你"改了 tokens.css 之后，哪些文件需要复查"。

### 3.4 环境要求是声明式的

当某个阶段需要工具链（如 check-layout.js / export-png.py）时，工具会随阶段约束返回**环境要求清单**，例如：

```
{
  name: "Node.js",
  minVersion: "22.4",
  why: "check-layout.js 依赖全局 WebSocket（Node 22.4+ 默认可用）",
  check: "node --version",
  install: "https://nodejs.org 或 winget install OpenJS.NodeJS"
}
```

然后由 **AI agent** 负责：

1. 逐项运行检查命令，报告哪些缺失
2. 与用户确认是否补全
3. 执行安装命令
4. 复检通过后，继续流程

工具的职责到"声明"为止。脚本的错误信息也遵循同一原则——**写给 AI 看**：缺什么、装什么命令、装完重试，而不是一堆堆栈。

### 3.5 粗粒度、无状态

- **粗粒度**：一个核心工具 `get_stage_guidance(mode, stage)` 返回完整约束包。不拆成十几个细碎工具。
- **无状态**：工具不记住进展。约束包里带"依赖的前置产物"（如"进入本阶段前应已完成 tokens.css"），AI 据此判断当前该做什么、缺了什么先回补。
- **任意跳转**：允许 AI 在任何时候取任意阶段的约束（支持回退修正）。

---

## 4. 流程全景（0-8 阶段）

| # | 阶段 | 产物 | 出口条件（怎么算做完） |
|---|---|---|---|
| 0 | 功能蓝图（微立项） | 项目定位 + 角色 + 功能清单 + 页面清单 + Mermaid 流转图 + 独立 `flow-*.html` + 里程碑骨架 | 目标/非目标明确、页面无遗漏、主操作路径清晰、流程图可独立浏览 |
| 1 | 风格探索 | 2-3 个视觉方向 + 选定结果 | 人选定一个方向（含配色/字体/风格参数） |
| 2 | 定令牌 | `tokens.css` + `token-preview.html` | 每个颜色/间距/圆角/字号都有语义化名字；关键令牌可实时预览；后续文件 0 魔法数字 |
| 3 | 搭组件库 | `app.css` | 每个组件有全部状态：默认/hover/按下/禁用/选中/加载/错误/空 |
| 4 | 画主界面 | `fig1-*.html` | 一张图说清：信息分几区、每区放什么、主操作路径是哪一条 |
| 5 | 画规格页 | `fig2..N-*.html` | 主路径上的交互入口 + 所有非默认状态都有视觉定义 |
| 6 | 体检出图 | check-layout.js 报告 + PNG | 三类问题为 `[]`；稿子里塞过长文案撞过墙 |
| 7 | 写映射 | `wpf-mapping.md` | "找不到落点"清单为空或已确认可接受 |
| 8 | 交接开发 | 项目级提示词 + 实现顺序 | 设计资产完备，可交给 AI 编码助手逐页实现 |

每个阶段的约束包由这些字段组成：

**目标 / 产物 / 出口条件 / 规则 / 提示词模板 / 依赖 / 常见坑 / 回退影响面 / 环境要求（如有）。**

阶段 2-7 的详细工程做法（以 WPF 模式为例）见 [WPF-README.md](./WPF-README.md)。

---

## 5. 工作方式（目标形态）

### 5.1 用法 A：AI agent 接入（MCP）

AI 编码助手通过 MCP 协议调用 InspireDesign，按约束引导你走流程：

```
你：我想做一个 WPF 版的设备巡检记录工具。
AI：（调用 get_stage_guidance(mode="wpf", stage="blueprint")）
    好，我们从头开始。第一步是功能蓝图——用几个问题把你的想法结构化：
    1. 这个工具主要给谁用、解决什么问题？
    2. 你能想到的主要页面/窗口有哪些？
    3. 用户每天打开它，第一件事通常是什么？
    …（引导完成后产出页面清单 + Mermaid 流转图，并停下来等你确认）
```

关键交互约定：

- 每个阶段结束，AI 停下来等你说"行"或提修改意见
- 需要工具链时，AI 先检查环境、与你确认后安装，再继续
- 你说"想改 XX"，AI 回到对应阶段取约束，按"回退影响面"排查下游

### 5.2 用法 B：页面端独立使用

打开页面 → 选择模式（如"WPF 启发流"）→ 浏览流程全景 → 进入各阶段 → 查看"该做什么 / 怎么说 / 算做完的标准" → 复制提示词范例 → 粘贴到你的 AI IDE 中对话。

---

## 6. 模式（Mode）

同一套流程模型，针对不同前端技术架构提供有差异的指导：

| 模式 | 状态 | 差异点 |
|---|---|---|
| **WPF 启发流** | **首发，第一步实现** | 提示词术语面向 XAML + ResourceDictionary + MVVM；映射表参照 WPF 控件体系；设计稿窗口尺寸 = 目标 WPF 窗口尺寸 |
| Vue 启发流 | 后续 | 面向 Vue 3 SFC + CSS 变量 + 组件库 |
| React 启发流 | 后续 | 面向 JSX + CSS-in-JS |
| 通用启发流 | 后续 | 不限技术栈，纯方法论 |

---

## 7. 目录结构

```
InspireDesign/
├─ README.md              # 本文件：项目总览
├─ WPF-README.md          # WPF 模式工程流程（细化到工程操作，可直接复制进目标项目）
├─ mcp-server.js          # MCP 服务入口（stdio；注册方式见 docs/04 §6）
├─ data/                  # MCP 服务数据（唯一声明源）
│  ├─ stages.js           #   9 阶段完整内容（02 文档的机器可读版）
│  ├─ modes.js            #   模式定义 + WPF 字段级覆盖
│  └─ capabilities.js     #   能力包与环境要求
├─ test-mcp.js            # MCP 服务冒烟测试（npm test）
├─ package.json           # 依赖与脚本（npm install / npm start / npm test / npm run web / npm run build）
├─ check-layout.js             # 工具链：设计稿体检（溢出/越界/文字出框）
├─ export-png.py              # 工具链：HTML → PNG 出图（无头浏览器截图）
├─ token-preview-template.html # 阶段 2：令牌实时预览页模板（复制为 design/token-preview.html）
├─ mermaid-flow-template.html # 阶段 0/5：Mermaid 独立 HTML 流程图模板（阶段 5 可一页多个图）
├─ serve-web.js           # 页面端本地服务器（零依赖；npm run web）
├─ build-static.js        # 静态打包（零依赖；npm run build → dist/，用于部署）
├─ web/                   # 页面端（人看的「教程版」；零构建，复用 data/ 同一份数据）
│  ├─ index.html          #   单页骨架 + 内联 SVG 图标集
│  ├─ assets/             #   自举样式：tokens.css → app.css → 交互 app.js
│  └─ vendor/             #   离线依赖（mermaid 流程图；加载失败自动降级为文字链）
├─ docs/
│  ├─ 01-核心理念.md           # 为什么这样设计
│  ├─ 02-流程模型.md           # 9 个阶段的完整定义
│  ├─ 03-数据契约.md           # 约束包/能力包/环境要求的字段结构
│  ├─ 04-MCP服务设计.md        # MCP 工具的接口与语义
│  ├─ 05-页面端设计.md         # 页面端信息架构与交互
│  ├─ 06-设计工具链.md         # check-layout.js / export-png.py 的集成与修复记录
│  └─ 07-文件职责说明.md       # 逐文件能力说明（本节目录结构的细化补充）
└─ dist/                  # 打包产物（npm run build 生成，已 gitignore；静态部署时服务器根目录指向它）
```

> 每个文件能做什么、谁在消费、改动时注意什么，以及两条出口（页面端 / MCP 端）的运行原理，详见 [docs/07-文件职责说明.md](./docs/07-文件职责说明.md)。

---

## 8. 环境要求（使用工具链时）

| 组件 | 版本 | 用途 | 检查命令 |
|---|---|---|---|
| Node.js | 22.4+ | check-layout.js（依赖全局 WebSocket） | `node --version` |
| Python | 3.9+ | export-png.py 运行环境 | `python --version` |
| Pillow | 任意 | export-png.py 自动裁剪（可选，缺它只影响裁剪） | `python -c "import PIL"` |
| Edge 或 Chrome | 现代版本 | 无头浏览器截图（两个工具共用） | 检查常见安装路径 |

原型阶段这些环境由使用者在 AI agent 协助下检查与补全（见 §3.4）。
页面端本身只依赖浏览器（Node 仅用于启动本地服务器、静态打包与运行工具链脚本）。

---

## 9. 当前状态与路线

**当前：原型阶段。** 原则：**先固化、边用边改、不过度设计。**

| 项 | 状态 |
|---|---|
| 方法论 + WPF 工程流程（WPF-README.md） | 已有 |
| 工具链（check-layout.js / export-png.py） | 已有（原待修项已修复，见 docs/06） |
| 项目 README + 工程化文档集 | 已有（本批） |
| MCP 服务（list_modes + get_stage_guidance，含冒烟测试） | 已有 |
| 页面端（web/，零构建，复用同一份数据；`npm run web` 本地预览） | 已有 |
| 页面端静态部署（`npm run build` → dist/，可放任意静态服务器） | 已有 |
| 试用 WPF 模式第一个真实项目 | 进行中 |

演进原则：WPF 模式是第一个真实用例；先在自己的项目里试用，经验多了、足够好用了，再考虑数据外置化、更多模式、MCP 执行能力等架构优化。

---

## 10. 文档索引

| 文档 | 内容 |
|---|---|
| [WPF-README.md](./WPF-README.md) | WPF 模式的工程操作细则：目录约定、六个工程阶段、export-png.py/check-layout.js 用法、向 AI 描述界面的方法、wpf-mapping.md 生成模板、坑清单 |
| [docs/01-核心理念.md](./docs/01-核心理念.md) | 每个设计决策背后的论证 |
| [docs/02-流程模型.md](./docs/02-流程模型.md) | 9 个阶段的完整定义（目标/产物/出口条件/规则/提示词骨架/坑/回退影响面） |
| [docs/03-数据契约.md](./docs/03-数据契约.md) | 约束包、能力包、环境要求、模式的字段结构 |
| [docs/04-MCP服务设计.md](./docs/04-MCP服务设计.md) | MCP 工具清单、参数、返回示例、调用时序、执行边界 |
| [docs/05-页面端设计.md](./docs/05-页面端设计.md) | 页面信息架构、交互要点、与 MCP 端的数据共享 |
| [docs/06-设计工具链.md](./docs/06-设计工具链.md) | 两个脚本的定位、环境声明、集成方式、修复记录 |
| [docs/07-文件职责说明.md](./docs/07-文件职责说明.md) | 逐文件能力说明：每个文件能做什么、谁在消费、什么时候用、改动时注意什么 |