# WorkBuddy Guide 官网 UI 重设计方案

> 目标：把当前偏 VitePress 默认风格的文档站，升级为具有明确品牌识别度的「高级编辑型 AI 知识站」。视觉参考用户提供的荧光黄绿色像素海报，但不把整站做成复古游戏界面。

## 1. 结论先行

推荐方向：**Editorial Pixel / 编辑型像素科技感**。

- 用米白、白色和墨黑承担长文阅读与专业感。
- 用荧光黄绿色建立品牌记忆，只出现在 Hero、主要按钮、当前状态和少量强调区。
- 像素元素控制在整页视觉的 10%–15%，主要用于小图标、章节编号、装饰卡片和微动效。
- 中文标题和正文坚持现代无衬线字体；像素字体只用于英文标签、数字、状态码，不能用于长段中文。
- 保留现有 VitePress 的搜索、侧边栏、目录、深色模式、Markdown 内容和全部路由，不重做技术架构。

最终应该让人感到：**这是一本来自 AI Agent 时代的开源工作手册，而不是一个套了绿色主题的默认文档站。**

---

## 2. 对当前站点的判断

### 已有优势

- 首页的信息顺序清楚：品牌主张 → 三个价值点 → 四段阅读路线。
- 文档站核心能力完整：本地搜索、侧边栏、本页目录、上一篇/下一篇、深色模式。
- 移动端基础结构可用，现有内容和路由不需要重写。
- VitePress 默认主题适合继续扩展，没有必要换框架。

### 主要问题

- 紫色渐变、圆角卡片、点阵背景都很常见，缺少 WorkBuddy 自己的品牌特征。
- 首页 Hero 左侧信息堆叠，右侧大面积留白，没有形成一个能被截图传播的主视觉。
- 三张功能卡和四张阅读卡视觉权重接近，页面缺少强弱节奏。
- 章节页几乎是默认文档站样式，侧边栏、正文、目录之间缺少精致的层级关系。
- 圆角、渐变和阴影偏柔，和参考图的清脆像素感不一致。
- 当前像素感只存在于点阵背景，并没有变成统一的品牌语言。

---

## 3. 三个可选方向

| 方向 | 视觉特征 | 优点 | 风险 | 建议 |
| --- | --- | --- | --- | --- |
| A. 全幅像素海报 | 大面积荧光绿、超大像素字、强烈黑白对比 | 传播性最强，第一眼最像参考图 | 长文阅读容易疲劳，也容易像活动页或游戏站 | 不推荐整站采用 |
| B. 编辑型像素科技感 | 米白阅读底色、荧光绿品牌区、现代排版、像素细节 | 兼顾高级感、识别度和阅读体验 | 对留白、字体层级和素材质量要求高 | **推荐** |
| C. 暗色命令中心 | 石墨黑底、荧光绿状态、终端/控制台感 | 科技感强，适合开发者 | 不符合蓝皮书的长期阅读场景，中文密度高时压迫 | 只作为深色模式参考 |

执行时直接采用 B，不需要再混合三套风格。

---

## 4. 品牌关键词与设计原则

### 品牌关键词

**开源、可靠、行动、系统、协作、未来感、可复现。**

### 五条设计原则

1. **先像一本好读的书，再像一个有个性的科技品牌。**
2. **像素只做记忆点，不做阅读负担。**
3. **绿色负责聚焦，黑白负责秩序。**
4. **减少柔和渐变和胶囊按钮，增加清晰边界和硬朗结构。**
5. **所有装饰都要服务于章节、路径或状态，不增加无意义噪声。**

---

## 5. 视觉系统

### 5.1 色彩 Token

#### 浅色模式

| 用途 | 色值 | 使用规则 |
| --- | --- | --- |
| Brand Acid | `#D8F238` | Hero、主按钮、活动状态、大面积品牌块 |
| Brand Acid Strong | `#BCE52E` | Hover、图表强调、深色模式中的次级品牌绿 |
| Ink | `#12140F` | 标题、主要按钮、深色区域背景 |
| Paper | `#F5F7F0` | 页面主背景，轻微偏暖，不用冷白灰 |
| Surface | `#FFFFFF` | 卡片、正文、搜索框 |
| Soft Green | `#EEF6D1` | 提示框、引用、浅强调区 |
| Text Secondary | `#62675E` | 正文次级信息、描述 |
| Line | `#D9DDD2` | 分隔线、卡片边框、表格线 |
| Accessible Green | `#355E18` | 白底上的绿色文字和链接状态 |

#### 深色模式

| 用途 | 色值 |
| --- | --- |
| Background | `#0F110D` |
| Surface | `#181B15` |
| Surface Raised | `#20241C` |
| Text Primary | `#F3F5ED` |
| Text Secondary | `#AEB4A7` |
| Line | `#33392E` |
| Brand Acid | `#D8F238` |

#### 禁止事项

- 不用荧光绿作为白底小字号正文，因为对比度不足。
- 不再使用紫蓝渐变作为品牌色。
- 不用大面积绿色渐变；品牌绿尽量保持纯色和平面感。
- 同一屏最多一个大面积绿色区域。

### 5.2 字体与排版

- 中文标题：`PingFang SC / Microsoft YaHei / system-ui`，字重 700–800。
- 中文正文：系统无衬线，字重 400–500，章节正文行高 `1.8–1.9`。
- 英文与数字：优先 `Inter Tight / Inter / system-ui`。
- 像素字体：只用于 `PART 01`、`OPEN SOURCE`、`27 CHAPTERS`、编号和装饰词。可选择一款许可证清晰、支持英文和数字的像素字体，并本地托管。
- 不让像素字体承担中文 H1、导航或正文。

建议字号：

| 场景 | 桌面端 | 移动端 |
| --- | --- | --- |
| 首页 H1 | `72–88px / 0.98` | `42–50px / 1.05` |
| 首页副标题 | `20px / 1.7` | `17px / 1.7` |
| 区块标题 | `40–48px` | `30–36px` |
| 章节 H1 | `44–52px` | `34–40px` |
| 正文 | `17–18px` | `16–17px` |
| 像素标签 | `12–14px` | `11–12px` |

### 5.3 圆角、边框和阴影

- Hero 大容器：`8px`，不要夸张大圆角。
- 普通卡片：`6–8px`。
- 按钮：`4–6px`，取消胶囊形态。
- 边框：`1px` 或 `1.5px`，使用 Ink/Line 色。
- 重点卡片 Hover：使用 `4px 4px 0` 的克制硬阴影，避免柔软大模糊阴影。
- 正文图片可以保留 `8px` 圆角，但不要每一层容器都圆角。

### 5.4 像素资产规范

需要一套真实素材，不要用 emoji、文本符号、临时 CSS 图形或随手画的线性图标代替。

建议准备 6 个单色 1-bit 像素图标：

1. 工作任务 / Cursor
2. AI Agent / Buddy
3. Skill / 工具箱
4. Workflow / 节点连线
5. Team / 多角色协作
6. Book / 开源蓝皮书

资产要求：

- 黑色主体、透明背景，基于 `32×32` 或 `48×48` 网格绘制。
- 输出 4 倍 PNG 或许可证清晰的 SVG；PNG 展示时启用像素化渲染，避免模糊。
- Hero 中将图标放进白色方卡，允许 `±3deg` 的轻微旋转，模拟参考图的贴纸感。
- 额外准备一张白色小方块点缀图案，用作 Hero 边缘装饰；不要全站重复铺满。
- 图标必须语义清楚，避免骷髅、手柄、宇宙飞船等与产品无关的游戏化符号。

---

## 6. 首页结构方案

### 6.1 顶部导航

- 高度约 `64–68px`，白色/米白底，底部 1px 分隔线。
- 左侧为 WorkBuddy Guide 字标 + 小型像素书本标志。
- 中部或右侧保留：`首页 / 开始阅读 / 阅读指南 / 参与共创`。
- 搜索入口从左侧移到右侧工具区，和深色模式、GitHub 同组。
- 当前导航项不再用紫色文字，改成 Ink 字 + 下方 3px 荧光绿短线或绿色像素方块。
- 移动端只保留字标、搜索、菜单；点击区域至少 `44×44px`。

### 6.2 Hero：整站最重要的品牌画面

Hero 使用一个居中的荧光绿大色块，桌面端最大宽度约 `1280px`、高度约 `540–600px`，内容分成 7:5 两列。

左侧内容：

```text
OPEN-SOURCE · 27 CHAPTERS · 2026

从第一项任务，
到一支 AI 团队

一套以真实工作为主线的 WorkBuddy 实践路径。
先用起来，再把一次成功沉淀为可复用的工作系统。

[ 开始阅读 → ]  [ 查看阅读路线 ]
```

右侧内容：

- 3–4 张白色像素图标卡片，以错位、轻旋转方式悬浮在绿色区域内。
- 中间可以出现一个大的 `WB_` 或 `WORK / SYSTEM` 像素标签，但不要覆盖中文主标题。
- 右下角放 `27 CHAPTERS / 4 PARTS / ∞ WORKFLOWS` 三个数字信息，作为可信度和内容规模说明。

Hero 视觉要求：

- 中文主标题使用现代粗体，不用像素字体。
- 主按钮用 Ink 黑底 + 白字；次按钮用透明底 + Ink 边框。
- 不添加玻璃拟态、彩色光晕、3D 球体、人物 AI 插画。
- 首屏必须在 1440×900 下完整看到标题、CTA 和至少两张像素卡片。

### 6.3 价值条

紧接 Hero 放一条黑底静态信息带，不做无限滚动跑马灯：

`真实任务 REAL TASKS  ·  可复现 REPRODUCIBLE  ·  社区共创 OPEN SOURCE  ·  系统沉淀 WORK SYSTEM`

作用是把视觉从绿色 Hero 过渡到米白内容区，并快速传达项目差异。

### 6.4 四段阅读路线

- 保留现有四段内容，但改成更像编辑排版的 2×2 大卡片。
- 每张卡左上是像素标签 `PART 01`，右上是章节范围，如 `CH. 01–10`。
- 标题 28–32px，描述最多两行。
- 卡片底部增加一条可视化路径线，Hover 时由灰色变成荧光绿。
- PART 01 作为推荐入口，可用浅绿色底；其他卡片保持白底。
- 四张卡不要都用相同渐变。

### 6.5 按任务进入

增加一个实用型发现区，用已有章节生成 6 个入口，不增加新页面：

- 办公文档
- 文件与远程控制
- 资讯与知识管理
- 投资与专业分析
- 视频与内容增长
- Skill、多 Agent 与自动化

每个入口由像素图标、标题、2–3 个关键词组成。桌面端 3×2，移动端横向可滚动或单列。这个区块的目的不是装饰，而是帮助“带着具体任务来的读者”更快进入对应章节。

### 6.6 方法路径

用一条简洁的四步路径说明蓝皮书的方法论：

`TASK → CASE → WORKFLOW → AI TEAM`

中文解释：

1. 完成一个真实任务
2. 复盘并形成可复现案例
3. 沉淀为 Skill 和自动化工作流
4. 组合成可协作的 AI 团队

使用真实像素节点/箭头资产或许可证清晰的图标，不用临时 CSS 绘制复杂插画。

### 6.7 共创 CTA 与页脚

- 最后一个 CTA 使用 Ink 黑底，左侧大标题 `这本蓝皮书，也可以由你继续写下去。`
- 右侧两个按钮：`参与共创`、`前往 GitHub`。
- 放一个荧光绿的像素书本图标作为视觉锚点。
- 页脚保持简洁，包含项目声明、GitHub、阅读指南和版权。

---

## 7. 文档阅读页方案

文档页不需要像首页一样高饱和，目标是“安静、清晰、具有品牌细节”。

### 7.1 整体布局

- 桌面端继续使用左侧栏 + 正文 + 右侧目录三栏结构。
- 左侧栏约 `272–288px`，背景使用 Paper，右边 1px 分隔线。
- 正文最佳阅读宽度控制在 `720–780px`。
- 右侧目录约 `200px`，使用一条细竖线连接层级。

### 7.2 侧边栏

- 篇章标题使用小号像素英文标签 + 中文标题，例如 `PART 01 / 使用手册`。
- 当前章节使用 Ink 黑底、白字，并在左侧加 6px 荧光绿方块。
- Hover 只改变背景和文字，不做左右晃动。
- 章节序号使用等宽字体，正文名称保持现代中文字体。
- 折叠箭头使用现有图标库，不用文本符号。

### 7.3 正文

- H1 更大、更紧凑，标题上方增加 `CHAPTER 01` 像素标签。
- H2 前可使用 8px 荧光绿方块作为章节锚点，但不要每级标题都加装饰。
- 正文链接使用 Accessible Green，并保留下划线或明显 Hover 状态。
- 引用和提示框使用 Soft Green 背景 + Ink 左边框，不使用大面积半透明渐变。
- 图片统一边框、8px 圆角和轻阴影；有说明时使用小号图注。
- 代码块使用深色背景，顶部可以有绿色文件名/语言标签。
- 表格表头使用 Ink 黑底或浅绿色底，移动端允许横向滚动。
- 上一篇/下一篇卡片采用硬边编辑式布局，明确显示章节号和标题。

### 7.4 右侧目录

- 标题改为 `ON THIS PAGE / 本页目录`。
- 当前小节使用 Ink 粗体 + 绿色竖线。
- 二级、三级标题要有明显缩进，不只依靠字号。

### 7.5 搜索

- 保留 VitePress Local Search。
- 搜索按钮改为直角感更强的紧凑控件，显示 `⌘ K` 仅作为键盘提示。
- 搜索弹窗中的匹配关键词用浅绿色高亮，选中项用 Ink 黑底。
- 不新增远程搜索服务。

### 7.6 深色模式

- 深色模式更接近“编辑台”，而不是霓虹黑客终端。
- 正文使用暖白文字，绿色只做当前状态、链接、按钮和代码标签。
- 不添加 CRT 扫描线、发光字、闪烁光标或 Glitch 效果。

---

## 8. 动效规范

动效必须短、稳、克制。

- Hero 初次进入：标题、说明、按钮依次淡入并上移 `8–12px`，总时长不超过 `500ms`。
- 像素卡片：首次进入做一次轻微错位复位；Hover 时旋转回 `0deg` 并上移 `3px`。
- 主要按钮：Hover 时硬阴影从 `0` 增加到 `3px 3px 0`，按下时回落。
- 阅读卡片：Hover 上移 `3px`，路径线变绿。
- 当前目录状态：颜色在 `150–180ms` 内变化。
- 不使用持续漂浮、自动跑马灯、鼠标跟随、视差滚动和大面积滚动触发动画。
- 完整支持 `prefers-reduced-motion: reduce`，关闭非必要动画。

---

## 9. 响应式规则

### ≥ 1280px

- 内容最大宽度 `1280px`。
- Hero 7:5 两列，H1 72–88px。
- 四段阅读路线为 2×2。
- 任务入口为 3×2。

### 768–1279px

- Hero 6:5 或上下布局。
- 右侧像素卡片减少为 2–3 张。
- 文档页右侧目录可以隐藏，左侧栏保持。

### < 768px

- Hero 单列，左右内边距 20–24px。
- H1 42–50px，不能出现单字孤行。
- 只保留 2 张像素卡片，放在标题之后或 Hero 底部，避免遮挡文字。
- CTA 可换行，但主要按钮优先占据完整一行。
- 阅读路线改为单列；卡片高度由内容决定，不设过高最小高度。
- 文档侧边栏改为抽屉，右侧目录隐藏。
- 所有按钮和图标触控区至少 44px。

重点测试宽度：`1440 / 1024 / 768 / 390px`。

---

## 10. 无障碍与可读性底线

- 黑字/白字与背景至少满足 WCAG AA 对比度。
- 荧光绿不承担白底上的小字号正文。
- 所有交互元素必须有清晰的键盘 Focus 状态，建议使用 `3px` Ink/Acid 双层焦点环。
- 导航、章节标题和按钮不能只依靠颜色区分状态。
- 像素字体不用于长文，也不用于 14px 以下的中文。
- 图标提供 `aria-label` 或配套可见文字；纯装饰图标使用空 alt。
- 深色模式下代码、表格、链接和提示框仍要保持清晰层级。

---

## 11. 对现有项目的实施映射

### 必改文件

- `docs/index.md`
  - 重构首页信息层级和 HTML 结构。
  - 保留现有链接，补充“按任务进入”“方法路径”“共创 CTA”。

- `docs/.vitepress/theme/style.css`
  - 建立完整 Design Token。
  - 重写首页、导航、卡片、文档页、侧边栏、目录、搜索、深色模式和响应式样式。

- `docs/.vitepress/config.mts`
  - 更新 `theme-color` 为品牌绿或根据明暗模式配置。
  - 保留现有搜索、导航、侧边栏、SEO、Mermaid 和 GitHub 链接。
  - Mermaid 颜色同步为 Ink / Paper / Acid 体系。

- `docs/.vitepress/theme/index.ts`
  - 继续扩展 VitePress DefaultTheme。
  - 只有在首页结构确实需要时才注册少量 Vue 组件，不要重做整个主题。

### 建议新增

- `docs/.vitepress/theme/components/HomeHero.vue`
- `docs/.vitepress/theme/components/PixelIconCard.vue`
- `docs/.vitepress/theme/components/ReadingPathCard.vue`
- `docs/public/brand/pixel-icons/`
- `docs/public/brand/fonts/`（仅在字体许可证允许本地托管时）

组件数量保持少而精。如果 Markdown + HTML + CSS 已能满足，不要为了“组件化”拆出大量小组件。

### 明确不改

- 不迁移到 React、Next.js、Nuxt 或其他框架。
- 不改变现有章节正文和目录结构。
- 不改变已发布 URL。
- 不替换本地搜索。
- 不增加后端、登录、数据库或埋点。
- 不为了视觉效果引入重型动画库。

---

## 12. 推荐执行顺序

### Phase 1：建立基础视觉

1. 建立颜色、字体、圆角、阴影、间距 Token。
2. 更新全局背景、导航和基础按钮。
3. 同步深色模式和 Mermaid 色彩。

### Phase 2：首页重构

1. 完成绿色 Hero 和真实像素图标资产。
2. 改造价值条和四段阅读路线。
3. 添加按任务进入、方法路径和共创 CTA。
4. 验证首页所有链接。

### Phase 3：文档阅读体验

1. 改造侧边栏当前状态与篇章层级。
2. 调整正文排版、图片、表格、代码块、提示框。
3. 改造右侧目录、上一篇/下一篇和搜索弹窗。

### Phase 4：响应式与无障碍

1. 验证 1440、1024、768、390 四个宽度。
2. 验证浅色/深色模式。
3. 验证键盘导航、Focus、Reduced Motion。
4. 运行构建并修复所有警告、断链和布局溢出。

---

## 13. 验收清单

### 视觉

- [ ] 首屏一眼能识别“荧光绿 + 黑白 + 像素”品牌语言。
- [ ] 页面仍然像专业知识站，不像游戏活动页。
- [ ] 中文主标题没有使用像素字体。
- [ ] 首页只有一个大面积绿色区域。
- [ ] 像素资产清晰、不模糊、语义相关。
- [ ] 不再出现紫色品牌渐变和大量胶囊按钮。

### 体验

- [ ] 搜索、深色模式、导航、侧边栏和目录全部正常。
- [ ] 首页所有 CTA 与卡片链接正确。
- [ ] 390px 宽度无横向滚动，标题无明显孤字。
- [ ] 长文章的正文宽度和行高适合持续阅读。
- [ ] 键盘 Focus 清楚，颜色对比满足 AA。
- [ ] Reduced Motion 下无非必要动画。

### 工程

- [ ] `npm run build` 成功。
- [ ] 没有改变现有章节 URL。
- [ ] 没有引入不必要的框架或重型依赖。
- [ ] 新增字体和图标资产有清晰许可证来源。
- [ ] 浅色/深色截图均完成视觉检查。

---

## 14. 可直接交给另一个 AI 的执行提示词

```text
你是一名资深品牌设计师和前端工程师。请在当前 WorkBuddyGuide 仓库中，完成官网 UI 重设计。

先阅读：
1. docs/plans/2026-07-10-workbuddy-pixel-green-ui-design.md
2. docs/index.md
3. docs/.vitepress/config.mts
4. docs/.vitepress/theme/style.css
5. docs/.vitepress/theme/index.ts

目标：
把当前偏 VitePress 默认风格的站点，升级为“高级编辑型像素科技感”知识站。视觉语言为米白/白色 + 墨黑 + 荧光黄绿色，像素元素只占约 10%–15%。参考图中的绿色、黑白高对比、像素图标白卡和少量方块装饰可以继承，但不要把整站做成复古游戏或黑客终端。

硬性要求：
- 保留 VitePress 和现有 DefaultTheme，不迁移框架。
- 保留所有 Markdown 正文、路由、搜索、侧边栏、目录、深色模式、Mermaid、GitHub 链接。
- 重点改 docs/index.md、docs/.vitepress/theme/style.css、docs/.vitepress/config.mts；只有必要时才新增少量 Vue 组件。
- 中文标题和正文使用现代无衬线字体；像素字体只用于英文标签、数字、章节编号。
- 使用真实、许可证清晰的像素图标素材，或生成并保存清晰的像素图标资产。不要使用 emoji、文本符号、临时 CSS 图形、随手画的 SVG 代替主视觉素材。
- 不使用紫色渐变、玻璃拟态、彩色光晕、3D 球、CRT、Glitch、鼠标跟随、持续漂浮和重型动画库。
- 绿色不用于白底小字号正文；确保颜色对比、键盘 Focus 和 Reduced Motion。
- 不修改与 UI 无关的内容和功能。

实施顺序：
1. 先建立 Design Token 和全局样式。
2. 重做首页 Hero、价值条、四段阅读路线、按任务进入、方法路径、共创 CTA。
3. 优化文档侧边栏、正文、右侧目录、代码块、表格、图片、搜索和上一篇/下一篇。
4. 完成深色模式和 1440/1024/768/390px 响应式。
5. 运行 npm run build。
6. 分别检查首页与至少一个章节页的桌面端、移动端、浅色和深色截图；发现问题后继续修正，不要只以构建成功作为完成标准。

验收标准以设计文档第 13 节为准。完成后请汇报：改动文件、视觉决策、验证结果、仍存在的限制。
```

