188 lines
8.7 KiB
Markdown
188 lines
8.7 KiB
Markdown
# oiloil-ui-ux-guide
|
||
|
||
一套 **风格中性** 的 UI/UX 咨询 Skill。它不是一个"特定审美的助手"，而是一个 **耐心的访谈者**：
|
||
|
||
- 不预设你的产品该长什么样
|
||
- 不强加单一风格的字体 / 色彩 / 圆角偏好
|
||
- 先听你的产品、品牌、参考、约束，再给选项
|
||
- 给出的选项是平等并列的，不带"推荐星标"——除非你主动问"你觉得呢"
|
||
|
||
## 适用场景
|
||
|
||
- **新项目**：通过对话定下设计系统（颜色 / 字体 / 圆角 / 间距 / 阴影 / 动效），生成 `design-spec.md`
|
||
- **已有项目**：评审现有 UI，按 `P0 / P1 / P2` 给修复清单
|
||
- **单一面型**：给一种页面类型（dashboard / form / 长文等）的"该做 / 不该做"规则
|
||
|
||
## 三种模式（默认 `design`）
|
||
|
||
未指定模式时进入 `design`。其他模式需要显式触发。
|
||
|
||
| 模式 | 用途 | 默认？ |
|
||
|---|---|---|
|
||
| `design` | 通过对话定制项目专属的 design spec，最终在项目根目录生成 `design-spec.md` | 默认 |
|
||
| `guide` | 给定页面类型，输出"该做 / 不该做"规则 | 显式触发 |
|
||
| `review` | 评审现有界面，输出 `P0 / P1 / P2` 修复清单 | 显式触发 |
|
||
|
||
**Skill 不会被轻量问题触发**——"这两个蓝色哪个好看"这种问题它会直接答，不会启动整套对话流程。
|
||
|
||
## 核心范式：UX Hard Rules vs Style Lens
|
||
|
||
旧版本把"现代极简"风格的 token 偏好当成全局硬规则（禁止 Inter、禁止纯黑、禁止圆角 >12px、强制 OKLCH 等）。这不通用——同样的规则用在儿童产品、奢侈品、游戏、品牌强烈的项目上反而是限制。
|
||
|
||
新版本把规则严格分成两层：
|
||
|
||
### UX Hard Rules（10 条，跨风格不可妥协）
|
||
|
||
任务优先 / 状态闭环 / Affordance / 错误预防 / 反馈闭环 / 一致性 / CRAP / 间距规整 / 提示分层 L0–L3 / UI 文案纪律——这些是感知与认知层面的事实，不是审美。
|
||
|
||
### Style Lens（8 个风格家族，项目自选）
|
||
|
||
| Family | 一句话 | 参考 |
|
||
|---|---|---|
|
||
| `modern-minimal` | 留白 + 排版 + 克制色彩 + 锐利网格 | Linear, Vercel, Notion |
|
||
| `editorial` | 长文友好、衬线标题、宽松版心 | Medium, Substack, NYT |
|
||
| `brutal` | 原始、等宽、硬阴影、刻意粗糙 | 独立 maker 站点、Vercel brutal templates |
|
||
| `playful` | 大圆角、饱和色、弹性动效、插画 | Duolingo, MailChimp, Notion 早期 |
|
||
| `premium-luxury` | 优雅衬线、留白即价值、缓慢动效 | Aesop, Hermès, Apple Music |
|
||
| `tech-cyberpunk` | 暗色优先、霓虹强调、等宽密集 | GitHub dark, Vercel docs, Cursor |
|
||
| `warm-content` | 暖色中性、舒适阅读、柔软表面 | Are.na, Notion light, Craft |
|
||
| `brand-driven` | 所有 token 来自现有品牌资产 | 项目自身的 brand book |
|
||
|
||
每个家族都有自己的字体推荐 / 色彩倾向 / 圆角范围 / 动效语汇 / 反 AI 缺陷。**这些规则是家族内部的，不会跨家族适用**——`modern-minimal` 不喜欢 Inter，`tech-cyberpunk` 拥抱 Geist Mono，`playful` 允许 bounce。Skill 不会用一个家族的规则去批评另一个家族的项目。
|
||
|
||
## `design` 模式的对话节奏
|
||
|
||
```
|
||
Phase 0 Scan code (silent, 强制)
|
||
↓
|
||
Phase 1 Listen — 开放式提问，不抛推荐
|
||
↓
|
||
Phase 2 Style family — 用户已说清就确认，否则展示 2–4 个并列家族
|
||
↓
|
||
Phase 3 Visual choices — 每个 token 给 2–3 个选项，无星标
|
||
↓
|
||
Phase 4 Full preview — 在 dashboard / marketing / content / form / pricing 多个面型上预览，可切 dark mode + viewport
|
||
↓
|
||
Phase 5 Output design-spec.md
|
||
```
|
||
|
||
**硬性前置**：进入 `design` 之后，Skill 会先静默扫一遍代码（Tailwind / theme / CSS 变量 / UI 框架 / 关键 UI 文件），形成对现有 design tokens 一致性的事实判断（不是好坏判决），再以一段总结开口。**不会在没看代码的情况下问任何问题**。
|
||
|
||
完整流程见 `skills/oiloil-ui-ux-guide/references/design-interview.md`。
|
||
|
||
## 可视化预览模板
|
||
|
||
`references/design-preview-template.html` 是一个 **风格中性的静态预览模板**——它的外壳（chrome）刻意保持灰白色调，不抢戏。每次迭代只重写 JSON config，用户刷新浏览器即可。
|
||
|
||
模板支持：
|
||
|
||
- **Compare 模式** — 多个候选 token 集并排展示，**渲染同一个真实面型**（dashboard / marketing / content / form / pricing），方便横向对比
|
||
- **Full 模式** — 完整设计系统应用到上述 5 个面型上，带 **viewport 切换**（desktop / tablet / mobile）和 **dark mode 切换**
|
||
|
||
## 跨工具支持（Codex / Claude Code / Cursor / Windsurf）
|
||
|
||
- `AGENTS.md` 作为跨工具共享指令入口
|
||
- `CLAUDE.md`、`.cursor/rules/*.mdc` 桥接到 `AGENTS.md`
|
||
- `skills/oiloil-ui-ux-guide/SKILL.md` 是 Skill 行为的真实定义
|
||
|
||
## 安装
|
||
|
||
### 用 `skills` CLI 一键安装到多个 Agent
|
||
|
||
```bash
|
||
npx skills add oil-oil/ui-ux-guide --list
|
||
npx skills add oil-oil/ui-ux-guide -a codex -a claude-code -a cursor -a windsurf
|
||
# 全局
|
||
npx skills add oil-oil/ui-ux-guide -g -a codex -a claude-code -a cursor -a windsurf
|
||
```
|
||
|
||
### 手动复制
|
||
|
||
```bash
|
||
git clone https://github.com/oil-oil/ui-ux-guide ~/.codex/skills/oiloil-ui-ux-guide
|
||
```
|
||
|
||
## 触发方式
|
||
|
||
两种方式：
|
||
|
||
1. 显式点名 — `请使用 $oiloil-ui-ux-guide 帮我把这个项目的设计规范定下来。`
|
||
2. 描述任务 — "帮我定一套这个项目的颜色和字体" / "评审这个仪表盘" / "给我表单页的 UX 规则"
|
||
|
||
只描述任务、没指定模式时，Skill 默认进入 `design`。轻量问题（"这个按钮颜色对吗"）不会触发完整流程。
|
||
|
||
## 推荐提示词模板
|
||
|
||
### `design`（默认 — 定制项目设计规范）
|
||
|
||
```text
|
||
请使用 $oiloil-ui-ux-guide 帮我把这个项目的设计规范定下来。
|
||
背景：[一句话产品 / 目标用户]
|
||
要求：先扫一遍现有的 design tokens 再开始问我；
|
||
我希望你听完我的回答再给选项，不要一上来就推荐风格。
|
||
最终输出 design-spec.md 到项目根目录。
|
||
```
|
||
|
||
### `review`（评审现有界面）
|
||
|
||
```text
|
||
请使用 $oiloil-ui-ux-guide 的 review 模式。
|
||
背景：Web 管理后台，目标用户为首次完成配置的新用户。
|
||
请输出 P0/P1/P2 问题清单 + 每个问题的可执行修复 + 验收检查点。
|
||
注意：不要按某种风格家族评判我们 — 我们目前还没定型。
|
||
```
|
||
|
||
### `guide`（先出规则）
|
||
|
||
```text
|
||
请使用 $oiloil-ui-ux-guide 的 guide 模式。
|
||
页面类型：B 端长表单（8 个字段）。
|
||
请输出该做 / 不该做规则，覆盖：CTA 层级、状态、affordance、错误预防、提示分层、间距。
|
||
要求：纯要点，不要长段落。
|
||
```
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
.
|
||
├── AGENTS.md # 跨工具共享指令
|
||
├── CLAUDE.md # Claude Code 入口
|
||
├── .cursor/rules/oiloil-ui-ux-guide.mdc # Cursor 桥接
|
||
├── agents/openai.yaml # Codex Skill 元信息
|
||
├── index.html # Skill 介绍页
|
||
└── skills/oiloil-ui-ux-guide/
|
||
├── SKILL.md # 主规则
|
||
├── evals/evals.json # 测试用例 (8 个)
|
||
└── references/
|
||
├── design-interview.md # design 模式完整流程
|
||
├── design-preview-template.html # 浏览器预览模板
|
||
├── design-spec-template.md # design-spec.md 输出模板
|
||
├── system-principles.md # 系统级原则
|
||
├── interaction-psychology.md # HCI 定律 / 认知偏差
|
||
├── design-psych.md # 设计心理学诊断词汇
|
||
├── icons.md # 图标规则
|
||
├── review-template.md # 评审输出模板
|
||
├── checklists.md # 各面型清单
|
||
└── style-families/ # 8 个风格家族
|
||
├── index.md
|
||
├── modern-minimal.md
|
||
├── editorial.md
|
||
├── brutal.md
|
||
├── playful.md
|
||
├── premium-luxury.md
|
||
├── tech-cyberpunk.md
|
||
├── warm-content.md
|
||
└── brand-driven.md
|
||
```
|
||
|
||
## 参考文档
|
||
|
||
- skills CLI（跨 Agent 分发）：<https://github.com/vercel-labs/skills>
|
||
- Claude Code 记忆机制（`CLAUDE.md`）：<https://docs.anthropic.com/en/docs/claude-code/memory>
|
||
- Cursor 规则与 `AGENTS.md`：<https://docs.cursor.com/context/rules-for-ai>
|
||
- Windsurf `AGENTS.md` 支持：<https://docs.windsurf.com/windsurf/cascade/memories>
|
||
|
||
## 许可证
|
||
|
||
Apache License 2.0，详见 `LICENSE.txt`。
|