内容
<div align="center">
# 网页样式手册
**AI 编码代理的设计智能**。不再使用相同的英雄加三张卡片。
您的代理获得评分设计**合约** —— 方向、UI 状态计划、令牌 —— 然后从证据中编写代码。
[](https://www.npmjs.com/package/web-stylebook-mcp)
[](https://www.npmjs.com/package/web-stylebook-mcp)
[](./LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
**中文** · [한국어](./README.ko.md)
</div>
---
编码代理默认使用相同的通用 UI，因为它们无法**决定**它应该是什么样子 —— 所以它们会退回到英雄 + 3 张卡片 + 渐变。`web-stylebook-mcp` 是一个模型上下文协议服务器，它为代理提供**设计合约** —— 评分的视觉方向、UI 状态计划和设计令牌 —— 从与 [webstylebook.com](https://webstylebook.com) 相同的精选目录中获取。它返回**证据，而不是代码**。您的代理仍然会编写代码 —— 现在它知道要构建什么。
无需 API 密钥。无需模型调用。无需网络。无需文件系统访问。**确定性，只读，完全本地**。
## 没有它 / 有它
| | 没有 `web-stylebook-mcp` | 有 `web-stylebook-mcp` |
|---|---|---|
| **方向** | 猜测一种样式，坚持下去 | 评分候选项 + 原因代码 + 被拒绝的内容及原因 |
| **UI 状态** | 仅限快乐路径；空 / 错误 / 加载状态后来添加 | 必要 / 推荐 / 领域状态提前规划，按表面划分 |
| **令牌** | 手选的十六进制颜色，对比度很少检查 | 基于角色的令牌，带有 WCAG 对比度警告 |
| **结果** | 通用 AI UI | 可防御的设计合约，代理从中构建 |
## 观察它的决策
> *"高密度监控仪表盘，用于 SRE，整天都在通话中。保持冷静，技术性。避免赛博朋克风格。"*
```jsonc
// → recommend_design_direction （输入）
{
"productDescription": "高密度监控仪表盘，用于 SRE，整天都在通话中",
"productType": "operational-saas",
"tone": ["calm", "technical"],
"density": "high",
"usageFrequency": "daily",
"avoid": ["cyberpunk"]
}
```
```jsonc
// ← 结果
{
"confidence": "high",
"candidates": [ // 全部绑定在 0.91 — 排序不是有意义的
{ "style": "notion-style", "score": 0.91 },
{ "style": "platform-core", "score": 0.91 },
{ "style": "quiet-utility", "score": 0.91 },
{ "style": "runtime-signal", "score": 0.91 }
],
"rejected": [
{ "style": "cyberpunk-glitch", "reasons": ["EXPLICITLY_AVOIDED", "DAILY_USE_OVERSTIMULATION"] },
{ "style": "aurora-gradient", "reasons": ["PRODUCT_NOT_IDEAL", "DAILY_USE_OVERSTIMULATION"] }
],
"pairing": "macos-liquid-glass + notion-style (quieter forms / nav)",
"guidance": "将候选项视为评分证据；根据产品上下文进行选择。4 个候选项绑定在一起 — 排序不是有意义的；使用区分度。"
}
```
注意它**不做**的事情：它不假装只有一个赢家。四个方向绑定在 0.91，拒绝的内容带有原因代码，指南告诉模型做出最终决定。这种诚实是关键 —— 服务器提供证据，代理决定。
然后将选定的方向转化为实际的令牌：
```jsonc
// → compose_design_tokens(style: "notion-style", format: "css-variables", theme: "light")
// 0 个 WCAG 对比度警告
:root {
--color-canvas: #ffffff;
--color-text: #37352f;
--color-accent: #2383e2;
--color-border: #d3d3d1;
/* … 基于角色的颜色、类型、间距、半径、运动、密度 */
}
```
一次请求 —— 代理选择了一个方向，查看了被拒绝的内容及原因，并获得了通过 WCAG 的令牌，而无需生成一行代码。
## 代理用它构建的内容
一个不同的简报 —— *"一个用于 **Throughline** 的营销登陆页面，这是一个 B2B SaaS，用于将分散的客户反馈（支持票据、销售电话、应用评论、Slack）转化为一个优先的路线图。"* 没有布局，没有英雄，没有样式被指定。遵循配套技能，代理从**产品核心思想**开始编写，而不是依赖于一个库存英雄：右侧一半是一个定制的图表，展示了产品的实际机制 —— 反馈来源汇聚成一个自动排名的路线图 —— 而不是一个装饰性的卡片，您可以将其粘贴到任何其他网站上。
<div align="center">
<img src="https://raw.githubusercontent.com/seungdori/web-stylebook-mcp/master/docs/example-throughline-hero.png" alt="AI 代理使用 web-stylebook-mcp 组成的登陆页面英雄 —— 一个定制的反馈到路线图的可视化，而不是一个通用的英雄" width="840">
</div>
<div align="center"><sub>由 AI 代理组成，遵循配套技能 —— 提示描述了产品和堆栈，没有布局信息。</sub></div>
## 它是如何工作的
```mermaid
flowchart LR
A[AI 编码代理] -->|产品、基调、<br/>密度、使用情况| B(web-stylebook-mcp)
B --> C{捆绑目录<br/>只读 · 离线}
C --> D[recommend_design_direction]
C --> E[compare_design_directions]
C --> F[get_ui_state_plan]
C --> G[compose_design_tokens]
D & E & F & G -->|设计合约<br/>评分 · 原因代码 · 令牌| A
A -->|从证据中<br/>编写代码| H[您的 UI]
```
代理描述产品；服务器评分其精选目录并返回结构化的证据。不会生成代码，也不会离开您的机器。
## 安装
需要 **Node ≥ 20**.
<details open>
<summary><b>Codex CLI · IDE 扩展</b></summary>
使用 Codex CLI：
```bash
codex mcp add web-stylebook -- npx -y web-stylebook-mcp@latest
```
或将其添加到 `~/.codex/config.toml`。您也可以在受信任的存储库中使用基于项目的 `.codex/config.toml`:
```toml
[mcp_servers.web-stylebook]
command = "npx"
args = ["-y", "web-stylebook-mcp@latest"]
```
在编辑配置后重启 Codex 或打开新会话。在 Codex TUI 中运行 `/mcp` 以确认服务器已激活。
</details>
<details>
<summary><b>Claude Code</b></summary>
```bash
claude mcp add web-stylebook -- npx -y web-stylebook-mcp@latest
```
</details>
<details>
<summary><b>Cursor · Windsurf · 通用 MCP 客户端</b></summary>
将以下内容添加到您的 MCP 配置中：
```json
{
"mcpServers": {
"web-stylebook": {
"command": "npx",
"args": ["-y", "web-stylebook-mcp@latest"]
}
}
}
```
</details>
<details>
<summary><b>Claude 桌面版</b></summary>
将相同的块添加到您的 `claude_desktop_config.json` 中，然后重启：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"web-stylebook": {
"command": "npx",
"args": ["-y", "web-stylebook-mcp@latest"]
}
}
}
```
</details>
## 工具
| 工具 | 您获得的内容 | 诚实的部分 |
|------|--------------|-----------------|
| **`recommend_design_direction`** | 评分样式候选项，带有原因代码，**被拒绝**样式及*原因*，次要配对，置信度 | 模型做出最终选择 —— 这是证据提供者 |
| **`compare_design_directions`** | 2–4 个方向按产品适应性、重复使用性、密度、信任度、独特性、易用性风险、运动、维护性进行比较 | 不会宣布单一获胜者 |
| **`get_ui_state_plan`** | 必要 / 推荐 / 领域 UI 状态，用于表面（数据表、表单、结账、聊天、开发者控制台）—— 触发器、必须显示、必须隐藏、易用性和运动 | 涵盖代理遗忘的状态：空、错误、加载、边缘 |
| **`compose_design_tokens`** | 基于角色的令牌（颜色、类型、间距、半径、运动、密度）作为 `json` / `css-variables` / `tailwind` / `typescript`，适用于浅色 / 深色 / 两者 | 发出 WCAG 对比度警告，而不是隐藏它们 |
**目录：** 48 种样式 · 20 个组件 · 5 个表面 · 57 个 UI 状态配方 · 29 个运动配置文件 · 14 个产品原型。
## 本地化输出
每个工具都接受一个可选的 `locale`。原因代码、指南和标签以请求的语言返回：
```text
"zh" | "en" | "ko" | "ja" // 简体中文 · 英语 · 한국어 · 日本語
```
## 资源
通过 MCP 资源直接浏览目录：
```
webstylebook://manifest
webstylebook://styles · /styles/{id}
webstylebook://motion · /motion/{id}
webstylebook://components · /components/{id}
webstylebook://states/surfaces · /states/{surface} · /states/{surface}/{state}
webstylebook://products · /products/{id}
webstylebook://policies/anti-patterns · /policies/verification
```
## 提示
适用于常见工作流的现成 MCP 提示：
`design-product` · `design-screen` · `complete-ui-states` · `redesign-with-style` · `audit-design-direction`
## CLI
```bash
web-stylebook-mcp # 通过 stdio 运行服务器（默认）
web-stylebook-mcp --version
web-stylebook-mcp --catalog-info
web-stylebook-mcp --validate-catalog
```
## 配套技能
配套技能位于 [`skill/`](./skill) 目录中，以便您的代理在合适的时候调用这些工具，并正确使用结果（组合，不要重新着色；提供多个候选项；赢得信任，不要伪造；落地可重复使用的组件）：
**Codex**
- 将 `skill/web-stylebook-design/` 复制或链接到 Codex 技能位置，例如
`.agents/skills/web-stylebook-design/` 在您的存储库中，或 `~/.agents/skills/web-stylebook-design/`
用于您的用户配置文件。
- 如果您不想安装技能，请将 `skill/AGENTS.md` 复制到您的项目的 `AGENTS.md` 中。
**Claude Code 和其他代理**
- 将您的代理技能目录指向 `skill/web-stylebook-design/`，**或**
- 将 `skill/CLAUDE.md` 复制到您的项目的 `CLAUDE.md` 或等效规则文件中。
## 隐私和安全
| 属性 | |
|----------|---|
| API 密钥 | 无 |
| 模型调用 | 无 |
| 网络访问 | 无 — 完全离线工作 |
| 项目 / 文件系统访问 | 无 |
| 行为 | 确定性，只读 |
服务器从包中捆绑的目录快照中读取。不会发送任何内容；相同的输入始终产生相同的合约。
## 兼容性
- **Node:** ≥ 20
- **传输:** stdio（模型上下文协议）
- **客户端：** Codex CLI / IDE 扩展，Claude Code，Claude 桌面版，Cursor，Windsurf 和任何 MCP 兼容的客户端
## 许可证
[MIT](./LICENSE) — 涵盖**代码**和捆绑的目录快照（可用于商业用途）。
> [webstylebook.com](https://webstylebook.com) 网站的许可证为 CC BY-NC。相同的所有者为此包中捆绑的目录快照授予 MIT 许可证。
