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），每个阶段定义一个约束包： 目标 / 产物 / 出口条件 / 规则 / 提示词模板 / 依赖 / 常见坑 / 回退影响面。

然后提供两种消费形态：

同一份内容，两个出口。 页面端给人看的是"教程版"，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 §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 最简配置：

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

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

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

Related MCP server: io.github.bergside/typeui

2. 这不是什么

3. 核心理念

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

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

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

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

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 阶段）

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

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

阶段 2-7 的详细工程做法（以 WPF 模式为例）见 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）

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

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。

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

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

9. 当前状态与路线

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

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

10. 文档索引