# web-ui Style Studio 使用指南

这份文档说明 `style-studio/` 的几种主要用法：网页 Studio、命令行、HTTP API、MCP server、Agent Skill，以及如何把 `DESIGN.md` 交给 AI 生成 HTML 或图像。

`style-studio` 的核心链路是：

```text
需求描述 / 手动选择 -> seed -> design DNA -> DESIGN.md / PAGE.md / IMPLEMENTATION.md / STARTER.html -> AI 或应用代码
```

## 1. 核心概念

### Seed

Seed 是一套视觉方向的最短引用，例如：

```text
swiss.v3m2d6.azure.geist
```

它编码了：

- `swiss`：genre，风格流派
- `v3`：visual variance，视觉/布局变化度
- `m2`：motion intensity，动效强度
- `d6`：visual density，信息密度
- `azure`：palette，色板
- `geist`：typeface，字体

当你想保存、复现、分享某个风格时，用 seed 最方便。

### Design DNA

Resolver 会把 seed 展开成完整的 design DNA，包括：

- 语义色阶
- 字体角色
- 间距节奏
- 形状、圆角、边框、阴影规则
- 动效规则
- 布局方向
- WCAG 对比度检查

### DESIGN.md

`DESIGN.md` 是给对话式 AI 和 coding agent 使用的主要产物。它包含：

- YAML front matter，机器可读 token
- 给人和 agent 读的设计说明
- Do's and Don'ts
- `AI HTML/CSS Implementation Contract`
- `AI Image Generation Contract`

默认导出英文版 `DESIGN.md`。如果需要中文说明，可以导出 `DESIGN.zh.md`。

### Tailwind Theme

Tailwind 导出会把 design DNA 转成 Tailwind v4 `@theme`。适合让 AI 或开发者写 Tailwind 页面时避免回到默认的 `indigo/slate/rounded-lg` 风格。

### React Tokens

React 导出会生成 typed tokens module 和 `ThemeStyle` 注入器。适合 React 组件代码直接读取颜色、间距、字体、圆角等 token。

## 2. 网页 Studio

适合场景：你想可视化挑风格、调参数、看预览，并把同一组生成参数交给 Codex。

### 启动

```sh
cd /path/to/Mac-A-web-ui/style-studio
npm run dev
```

打开：

```text
http://localhost:4173
```

### 使用步骤

1. 选择 `GENRE`，例如 Swiss、Brutalist、Terminal、Editorial、Glass、Linear、Stripe、WorkBuddy。
2. 调整三个旋钮：
   - `变体`：视觉/布局变化度
   - `动效`：动效强度
   - `密度`：信息密度
3. 选择色板。
4. 选择字体。
5. 在右侧嵌入预览中查看生成效果。
6. 在预览下方选择页面类型和合同语言，填写真实业务 brief。
7. 分别查看或下载 V2 四件套：`DESIGN.md`、`PAGE.md`、`IMPLEMENTATION.md`、`STARTER.html`。
8. 点击“复制给 Codex”，把四件套、参数和 brief 一次写入剪贴板。
9. 需要框架 token 时，仍可导出 Tailwind theme 或 React tokens。

复制 seed 后，网页会提示这段 seed 应该怎么给 Codex 使用。推荐做法是把 seed 和明确指令一起发给 Codex：

```text
请使用以下四件套实现页面。DESIGN.md 管视觉身份，PAGE.md 管结构，
IMPLEMENTATION.md 管编码与验收；必须修改 STARTER.html，不要从空白文件开始。
```

### 什么时候用网页 Studio

当人需要浏览不同方向、比较风格、选中一个方向交给 AI 时，用网页 Studio 最直观。

<a id="cli"></a>
## 3. 命令行用法

适合场景：不打开网页，直接用脚本生成 seed、`DESIGN.md`、Tailwind theme 或 React tokens。

### 安装统一 CLI

```sh
cd /path/to/Mac-A-web-ui/style-studio
npm link
```

安装后可以在任意目录运行 `style-studio`。不想建立全局链接时，也可以把下面命令中的 `style-studio` 替换为 `node cli/style-studio.mjs`。

### 解析一个 seed

```sh
style-studio resolve swiss.v3m2d6.azure.geist
```

它会输出解析后的 DNA 摘要和 WCAG 检查结果；加 `--json` 可得到结构化结果。

### 一次导出 V2 四件套

```sh
style-studio bundle \
  --seed swiss.v3m2d6.azure.geist \
  --page detail \
  --lang zh \
  --brief-file ./brief.md \
  --out ./design-context \
  --zip
```

短 brief 可以改用 `--brief "客户档案详情页"`。输出目录包含四件套、`CODEX_PROMPT.md`、`README.md` 和带版本信息的 `manifest.json`。

### 根据需求生成多个不撞脸方向

```sh
style-studio recommend "a fintech dashboard" --count 3
```

它会返回 3 个经过距离度量筛选的 style seed，尽量避免生成结果撞脸。

目前这个“多样性引擎”没有调用大模型。它是本地规则脚本：先按 brief 命中 genre 的 intent/tags，再按色相、明暗、字体、密度、变体、动效、材质、圆角等特征计算“撞脸距离”，最后挑出互相差异更大的候选。

如果用户没有给 seed，Codex/agent 应该先走这一步，而不是凭感觉选一个“现代简洁风”。推荐规则：

1. 用户给了 seed：直接使用 seed。
2. 用户给了明确风格词：使用对应 genre 的 anchor seed。
3. 用户只给业务需求：先运行 `diversity.mjs "<brief>" 3`，给出 2-3 个候选和选择理由。
4. 用户不想选：默认使用第一个候选。
5. 品牌官网、客户交付页面、视觉探索类任务：优先让用户从候选中选。
6. 内部工具、后台、dashboard：可以默认选更稳的 `swiss` / `github` / `vercel` / `linear` 类方向。

### 导出英文 DESIGN.md

```sh
node resolver/emit-designmd.mjs swiss.v3m2d6.azure.geist > DESIGN.md
```

### 导出中文 DESIGN.zh.md

```sh
node resolver/emit-designmd.mjs swiss.v3m2d6.azure.geist --lang zh > DESIGN.zh.md
```

### V2：拆分视觉身份、页面构图和实现合同

当前九种完整策展风格 `swiss`、`brut`、`term`、`edit`、`github`、`notion`、`vercel`、`linear`、`workbuddy` 均推荐使用 v2：

```sh
node resolver/emit-designmd-v2.mjs swiss.v3m2d6.azure.geist --lang zh > DESIGN.md
node resolver/emit-pagemd.mjs swiss.v3m2d6.azure.geist --page landing --lang zh > PAGE.md
node resolver/emit-implementation.mjs swiss.v3m2d6.azure.geist --page landing --lang zh > IMPLEMENTATION.md
node resolver/emit-starter-html.mjs swiss.v3m2d6.azure.geist --page landing --lang zh > STARTER.html
```

- `DESIGN.md`：稳定视觉身份、语义 token、组件状态、风格 grammar
- `PAGE.md`：所选页面类型的区域职责、比例、首屏层级、移动端重排和构图 family
- `IMPLEMENTATION.md`：只负责代码生成，不混入生图 contract
- `STARTER.html`：由 resolver 确定性生成的语义骨架、完整 CSS 变量和移动端重排兜底

给 AI 时同时提供四份文件和真实内容 brief，并明确要求“修改 STARTER.html，不要从空白重写”。不要让 AI 用框架默认色、默认圆角或通用页面模板覆盖这些文件。

#### 模型选择

- 推荐使用 **GPT-5.5 / Codex**。这是 v2 唯一正式支持并执行完整回归的生成模型。
- Kimi K2.6 可用于兼容性尝试，但可能遗漏内容账本中的业务事实。
- Qwen 可用于研究或低成本草稿，但必须经过静态门禁、浏览器截图和人工视觉复核。

这里的“正式支持”只描述 AI 对四件套的执行稳定性，不限制 `DESIGN.md`、`PAGE.md`、`IMPLEMENTATION.md` 和 `STARTER.html` 的文件格式；其他模型仍然可以读取这些文件，但结果不作一致性保证。

`--page` 目前支持 1 种通用兜底和 8 种专用页面结构：

| 值 | 主要用途 | 常见页面 |
|---|---|---|
| `general` | 无法归入现有专用类型时，根据 brief 确定唯一主任务并保守组织页面 | 混合业务页、尚未建立专用 recipe 的页面 |
| `landing` | 介绍产品并推动一次转化 | 产品页、活动页、服务介绍 |
| `dashboard` | 监控状态并执行日常任务 | 数据看板、项目总览、运营后台 |
| `list` | 搜索、筛选和比较一组对象 | 表格、资源管理、搜索结果、客户列表 |
| `detail` | 理解并操作单个对象 | 客户档案、订单详情、项目详情 |
| `form` | 录入、校验和提交信息 | 创建、编辑、设置、分步表单 |
| `workbench` | 围绕主工作面进行编辑或审核 | 编辑器、审核台、标注台、生成工具 |
| `article` | 连续阅读和理解长内容 | 文档、教程、博客、知识库文章 |
| `auth` | 完成身份相关任务 | 登录、注册、验证、找回密码 |

选择标准是“页面的首要任务”，不是视觉外观。例如带几个指标的客户列表仍应选 `list`，而不是 `dashboard`；带侧栏的文章仍应选 `article`。`general` 不是“自动选最好看的布局”，只是在现有专用类型都不匹配时，根据 brief 建立一个主内容流和一个主操作。

### 导出 Tailwind theme

```sh
node resolver/emit-tailwind.mjs swiss.v3m2d6.azure.geist > theme.css
```

### 导出 React tokens

```sh
node resolver/emit-react.mjs swiss.v3m2d6.azure.geist > tokens.tsx
```

## 4. 把 DESIGN.md 给 AI 使用

适合对象：ChatGPT、Claude、Gemini、Codex、Cursor、Claude Code 等对话式 AI 或 coding agent。

### 生成单文件 HTML/CSS

推荐给 AI 的材料：

```text
1. 页面需求
2. DESIGN.md
3. 明确指令：生成单文件 HTML/CSS，并遵守 AI HTML/CSS Implementation Contract
```

示例指令：

```text
请使用这份 DESIGN.md 作为唯一设计系统，生成一个单页 HTML/CSS 界面。严格遵守 AI HTML/CSS Implementation Contract。YAML tokens 是事实来源。不要引入设计系统外的颜色、字体、间距、圆角、阴影、渐变或装饰效果。
```

如果目标是单文件 HTML，通常只给 `DESIGN.md` 就够了。不需要同时给 Tailwind 或 React tokens，除非目标技术栈明确使用它们。

### 生成 Tailwind 页面

推荐给 AI 的材料：

```text
1. 页面需求
2. DESIGN.md
3. Tailwind @theme 导出
4. 明确指令：只能使用 theme 驱动的 utilities
```

告诉 AI 优先使用这些由 DNA 生成的工具类：

```text
bg-accent-700
text-neutral-1000
bg-pagebg
rounded-ui
p-section
gap-inter
font-display
text-hero
shadow-btn
```

避免直接使用 Tailwind 默认倾向，例如 `bg-indigo-600`、`text-slate-500`、`rounded-lg`，除非这些值确实来自当前 DNA。

### 生成 React 组件

推荐给 AI 的材料：

```text
1. 组件需求
2. DESIGN.md
3. React tokens 导出
4. 明确指令：样式值必须从 tokens 读取
```

适合场景：AI 正在写 React 组件，需要在代码里读取 typed token object，而不是随手写 inline value。

### 生图 / 视觉方向图

推荐给 AI 或生图模型的材料：

```text
1. 图像需求
2. DESIGN.md
3. 明确指令：遵守 AI Image Generation Contract
```

示例指令：

```text
请把这份 DESIGN.md 作为 UI 图像的视觉方向。遵守 AI Image Generation Contract。保持色板、密度、形状语言、材质风格和 genre 识别度。不要生成通用 SaaS/AI 官网风格。
```

注意：Image contract 不是要求生图模型实现 CSS，而是把 design DNA 转成视觉方向约束。

## 5. DESIGN.md 是否应该同时包含两个 Contract

以下内容描述的是 v1 兼容导出。v2 已经把 HTML 实现合同拆到 `IMPLEMENTATION.md`，生图合同不再默认进入代码生成上下文。

默认 `DESIGN.md` 会同时包含：

- `AI HTML/CSS Implementation Contract`
- `AI Image Generation Contract`

这样做是刻意的。两个 section 标题很清楚：

- 代码生成任务看 HTML/CSS contract。
- 生图或视觉探索任务看 Image Generation contract。

当你想要一份能跨代码生成和视觉生成复用的设计系统文档时，使用完整 `DESIGN.md` 最方便。

后续可以继续扩展更细的导出：

- `DESIGN.html.md`
- `DESIGN.image.md`

目前默认保留完整文档。

<a id="api"></a>
## 6. HTTP API

适合场景：其他应用、脚本、根目录 HTML 微调器，或任何外部工具需要调用 style engine。

### 启动

```sh
cd /path/to/Mac-A-web-ui/style-studio
npm run dev
```

### 接口

```text
GET  /api/health
GET  /api/v2/meta
GET  /api/openapi.json
GET  /api/v2/skill.zip
GET  /api/registry
GET  /api/styles
GET  /api/resolve?seed=swiss.v3m2d6.azure.geist
POST /api/diversify
POST /api/v2/bundle
GET  /api/export/designmd?seed=swiss.v3m2d6.azure.geist
GET  /api/export/designmd?seed=swiss.v3m2d6.azure.geist&lang=zh
GET  /api/export/tailwind?seed=swiss.v3m2d6.azure.geist
GET  /api/export/react?seed=swiss.v3m2d6.azure.geist
GET  /api/short?seed=swiss.v3m2d6.azure.geist
GET  /api/v2/resolve?seed=swiss.v3m2d6.azure.geist&pageType=landing
GET  /api/v2/export/designmd?seed=swiss.v3m2d6.azure.geist&lang=zh
GET  /api/v2/export/pagemd?seed=swiss.v3m2d6.azure.geist&pageType=landing&lang=zh
GET  /api/v2/export/implementation?seed=swiss.v3m2d6.azure.geist&pageType=landing&lang=zh
GET  /api/v2/export/starter?seed=swiss.v3m2d6.azure.geist&pageType=landing&lang=zh
POST /api/v2/bundle.zip
```

V2 的 `pageType` 可替换为：`general`、`landing`、`dashboard`、`list`、`detail`、`form`、`workbench`、`article`、`auth`。优先使用后八种专用类型，无法合理归类时再使用 `general`。

### 示例

```sh
curl -sS 'http://127.0.0.1:4173/api/export/designmd?seed=swiss.v3m2d6.azure.geist&lang=zh'
```

```sh
curl -sS -X POST http://127.0.0.1:4173/api/diversify \
  -H 'Content-Type: application/json' \
  -d '{"brief":"a fintech dashboard","n":3}'
```

一次取得完整 V2 bundle：

```sh
curl -sS -X POST http://127.0.0.1:4173/api/v2/bundle \
  -H 'Content-Type: application/json' \
  -d '{"seed":"swiss.v3m2d6.azure.geist","pageType":"detail","brief":"客户档案详情页","language":"zh"}'
```

下载可移植 ZIP：

```sh
curl -sS -X POST http://127.0.0.1:4173/api/v2/bundle.zip \
  -H 'Content-Type: application/json' \
  -d '{"seed":"swiss.v3m2d6.azure.geist","pageType":"detail","brief":"客户档案详情页","language":"zh"}' \
  -o style-context.zip
```

完整 OpenAPI 文档位于 `http://127.0.0.1:4173/api/openapi.json`。部署时可通过 `HOST`、`PORT`、`CORS_ORIGIN` 和 `MAX_BODY_BYTES` 配置监听地址、跨域来源与请求体上限。

后续可以用这层 API 把 Style Studio 接到根目录的 AI HTML 可视化微调器里。

<a id="mcp"></a>
## 7. MCP Server

适合场景：让 agent 把 style engine 当作实时工具调用，而不是手动复制 CLI 输出。

### 入口

```text
/path/to/Mac-A-web-ui/style-studio/mcp/server.mjs
```

### 注册到 Codex

```sh
codex mcp add web-ui-style -- \
  node /path/to/Mac-A-web-ui/style-studio/mcp/server.mjs
```

注册后重新打开任务即可使用。MCP 使用 stdio，不需要额外开放端口。

### 工具列表

- `list_styles`
- `recommend_styles`
- `build_style_context`
- `diversify`（兼容旧调用）
- `resolve_seed`
- `emit_design_md`
- `emit_tailwind_theme`
- `emit_react`
- `short_code`
- `build_design_bundle`（兼容旧调用）

`emit_design_md` 支持：

```json
{
  "seed": "swiss.v3m2d6.azure.geist",
  "lang": "zh"
}
```

推荐 MCP 流程：

1. Agent 收到用户 brief。
2. 调用 `recommend_styles` 生成多个不同方向。
3. 展示选项，让用户或 agent 选一个 seed。
4. 调用 `build_style_context`，传入同一组 `seed`、`pageType`、`brief`、`language`。
5. Agent 修改返回的 `STARTER.html`，并按另外三份合同实现和验收。

<a id="skill"></a>
## 8. Agent Skill

适合场景：你希望 agent 长期具备这套风格生成能力，而不是每次临时解释。

Skill 目录：

```text
/path/to/Mac-A-web-ui/style-studio/skills/web-ui-style/
```

这个 skill 内部包含一份 resolver scripts 副本，因此可以作为自包含能力包使用。

### 安装到 Codex

先启动 Studio，然后下载并解压到个人 Skill 目录：

```sh
curl -sS http://127.0.0.1:4173/api/v2/skill.zip -o web-ui-style.skill.zip
unzip web-ui-style.skill.zip -d ~/.codex/skills
```

重新打开任务后，可显式调用：

```text
$web-ui-style 使用 seed swiss.v3m2d6.azure.geist，按 list 页面配方和中文合同，
为客户管理业务生成并实现完整四件套。
```

未提供 seed 时，Skill 会先按 brief 生成三个差异化候选，不会凭“现代简洁”之类的模糊判断直接选风格。

### 修改引擎后同步 Skill

如果你改了：

```text
resolver/
linter/
```

需要同步 skill 副本：

```sh
cd /path/to/Mac-A-web-ui/style-studio
./sync-skill.sh
```

### Skill 工作流

1. 明确 `seed`、`pageType`、`language`、`brief`；缺 seed 时先生成多个风格选项。
2. 选择一个 seed，或让用户选择。
3. 用 `scripts/export-bundle.mjs` 一次生成完整四件套。
4. 修改 `STARTER.html` 实现页面，不从空白文件重写。
5. 在 1440 × 1000 和 390 × 844 下完成静态、响应式和视觉检查。

## 9. 官方组件库：装真包

`style-studio` 里有两类系统：

- **Tier B**：由本项目生成。链路是 `seed -> DNA -> DESIGN.md / Tailwind / React tokens`。
- **官方组件库**：已有官方组件库。链路是 `install official package -> use official components/tokens`。

官方组件库不应该生成一套“看起来像某品牌”的 token。它应该直接安装并使用官方包，这样保真度最高，也更省事。

网页里点击“官方组件库”卡片会弹出安装命令，例如：

```sh
npm i @fluentui/react-components
```

给 Codex 的推荐指令：

```text
安装并使用这个官方组件库。请直接使用它的官方组件、主题和文档模式搭页面，不要手写一套仿制 token，也不要用普通 HTML/CSS 模仿这个设计系统。
```

什么时候用官方组件库：

- 用户明确说要 Material、Fluent、Ant Design、Primer、Carbon、Polaris 等官方体系。
- 项目已经在用某个组件库。
- 企业后台或机构产品要求组件一致性高于视觉新鲜感。
- 目标是生产落地，不是探索一个全新视觉方向。

什么时候用 Tier B：

- 用户想要更有差异化的视觉方向。
- 需要给 AI 一个轻量、可分享、可变体化的风格 seed。
- 不想被某个官方组件库锁死。
- 想要多个“不撞脸”的风格候选。

## 10. 和根目录 HTML 微调器的关系

这个仓库现在有两个一等能力：

- 根目录：AI HTML 可视化微调器
- `style-studio/`：风格引擎和 Studio

推荐组合方式：

```text
Style Studio 决定设计系统。
根目录 HTML 微调器调整具体生成页面。
```

示例流程：

1. 用 Style Studio 选择一个 seed。
2. 导出 `DESIGN.md`。
3. 把页面需求和 `DESIGN.md` 给 AI。
4. 让 AI 生成 HTML。
5. 在根目录 HTML 微调器里打开生成的 HTML。
6. 可视化微调文字、图片、间距、顺序、样式细节。
7. 导出最终 HTML。

后续可以把根目录编辑器接到 Style Studio API，实现“选择 seed -> 直接应用到已有 HTML 页面”。

## 11. 开发检查

改代码后运行：

```sh
cd /path/to/Mac-A-web-ui/style-studio
npm run check
```

检查内容包括：

- API server 语法
- MCP server 语法
- 默认 seed 解析
- 所有 Tier B seed 解析和 WCAG audit
- 英文 `DESIGN.md`
- 中文 `DESIGN.zh.md`
- Tailwind 导出
- React 导出
- diversify 输出唯一性和距离矩阵