内容
# 网页风格指南
[](./README.en.md)
[](./README.ko.md)
[](./README.ja.md)
**前端团队和 AI 编程代理的实用设计参考和实施交接文档。**
网页风格指南连接了设计工作的三个部分，这些部分通常分散在不同的资源中：
选择视觉方向，应用用户体验（UX）和视觉原则，将结果转化为实施就绪的提示。
[实时网站](https://webstylebook.com) ·
[设计指南](https://webstylebook.com/pages/ux-principles) ·
[提示生成器](https://webstylebook.com/pages/prompt-workflow) ·
[网页风格指南 MCP](https://github.com/seungdori/web-stylebook-mcp)
## 你可以做的事情
### 探索方向
- 浏览 32 种基础样式和 16 种经过精心组合的融合样式。
- 打开完整的 React 渲染示例，而不是仅凭缩略图判断方向。
- 在提交视觉语言之前并排比较两个样式。
### 使用共享的设计语言
- 将 23 个用户体验原则转化为设计问题、应用指南、注意事项和可观察的检查。
- 审查 21 个视觉设计原则，包括层次结构、间距、排版、颜色、深度、图像和状态。
- 用实时示例解释 20 个常见的 UI 组件术语。
### 从参考到实施
- 测试颜色对比度并导出 CSS 或 JSON 设计令牌。
- 通过实时预览和实施提示探索 29 种运动模式。
- 生成 AI 就绪的设计交接文档，保持样式、令牌、运动、组件基础和质量保证约束的连接。
- 通过独立的 MCP 包向编码代理公开相同的规范目录。
## 目录概览
| 参考 | 数量 | 目的 |
| --- | ---: | --- |
| 基础样式 | 32 | 完整的视觉方向 |
| 融合样式 | 16 | 针对特定目的的两种设计语言组合 |
| 用户体验原则 | 23 | 行为、心理学、交互和验证 |
| 视觉设计原则 | 21 | 层次结构、构图、工艺和状态覆盖 |
| 组件术语 | 20 | 共享的 UI 词汇和示例 |
| 运动模式 | 29 | 可搜索的实时预览和提示语言 |
| 语言 | 3 | 英语、韩语和日语路由 |
## 信息架构
网站将知识与交互工具分开：
| 设计指南 | 工具 |
| --- | --- |
| [用户体验原则](https://webstylebook.com/pages/ux-principles) | [样式比较](https://webstylebook.com/pages/compare) |
| [视觉设计原则](https://webstylebook.com/pages/design-principles) | [颜色系统](https://webstylebook.com/pages/color-system) |
| [组件词典](https://webstylebook.com/pages/component-glossary) | [动画实验室](https://webstylebook.com/pages/animation-lab) |
| | [提示提示](https://webstylebook.com/pages/prompt-tips) |
`设计指南`页面是独立的、深度链接的参考资料，具有共享的兄弟导航。
`工具`是用于比较、测试、预览和生成输出的工作空间。
## AI 交接和 MCP
[提示生成器](https://webstylebook.com/pages/prompt-workflow) 生成用于 AI 辅助前端工作的结构化工作流。
代理还可以获取 [`/agent-handoff.json`](https://webstylebook.com/agent-handoff.json) 以读取使用指南、样式目录、反模式、验证检查清单、构建提示和自我审计提示，而无需执行客户端 JavaScript。
独立的 [`web-stylebook-mcp`](https://github.com/seungdori/web-stylebook-mcp) 包提供来自同一规范目录的确定性只读设计智能：
- 具有原因和被拒绝的替代方案的产品适合度样式选择；
- 按结果、表面和阶段划分的用户体验和视觉原则规划；
- 屏幕层次结构、状态覆盖和设计令牌组成；
- 针对通用或无法访问的界面选择的警告。
```json
{
"mcpServers": {
"web-stylebook": {
"command": "npx",
"args": ["-y", "web-stylebook-mcp@latest"]
}
}
}
```
## 开发
```bash
npm install
npm run dev
```
该网站使用 React、TypeScript 和 Vite 构建。它在 `dist/` 中生成静态输出；规范 URL、本地化路由、hreflang 链接、站点地图、SEO 元数据和代理交接文档均从类型化源数据生成。
## 验证
```bash
npm run typecheck
npm run lint
npm run i18n:check
npm run test
npm run mcp:catalog
npm run mcp:catalog:check
npm run mcp:catalog:validate
npm run build
```
使用以下命令预览生产输出：
```bash
python3 -m http.server 4173 -d dist
```
## 源代码映射
- `src/data/styles.ts` — 样式卡片、提示配置文件、调色板和元数据。
- `src/ported/pages/*.tsx` — 所有 48 个样式页面的 React 源代码。
- `src/ported/portedStylePages.css` — 页面特定的视觉主题和交互。
- `src/catalog/principles.ts` — 规范的用户体验原则目录。
- `src/catalog/designPrinciples.ts` — 规范的视觉设计原则目录。
- `src/catalog/components.ts` — 规范的组件词汇。
- `src/pages/animation-lab/catalog.ts` — 运动模式目录。
- `src/data/routes.ts` — 路由、本地化元数据、规范 URL 和 hreflang 数据。
- `scripts/generate-static-pages.mjs` — 静态 HTML 和旧版 `.html` 兼容别名。
- `scripts/generate-agent-handoff.mjs` — 完整的机器可读 AI 交接文档。
- `public/previews/*.html` — 存档的保真度参考，不是生产渲染源。
英语路由不带前缀。韩语和日语路由使用 `/ko/` 和 `/ja/`。规范导航使用无扩展名的 URL，而旧版 `.html` 别名仍可用于兼容性。
## 许可证
[CC BY-NC 4.0](./LICENSE)
用户体验原则领域指南是独立编写的，并将 [Laws of UX](https://lawsofux.com)（CC BY-NC-ND 4.0）作为索引参考。Laws of UX 的文字、插图和页面布局不包含在内。
独立编写的用户体验和视觉设计目录也通过 [`web-stylebook-mcp`](https://github.com/seungdori/web-stylebook-mcp) 以 MIT 许可证分发。
