feat：移除了弹窗，服务器添加sls
This commit is contained in:
187
.agents/skills/oiloil-ui-ux-guide/README.md
Normal file
187
.agents/skills/oiloil-ui-ux-guide/README.md
Normal file
@ -0,0 +1,187 @@
|
||||
# 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`。
|
||||
220
.agents/skills/oiloil-ui-ux-guide/SKILL.md
Normal file
220
.agents/skills/oiloil-ui-ux-guide/SKILL.md
Normal file
@ -0,0 +1,220 @@
|
||||
---
|
||||
name: oiloil-ui-ux-guide
|
||||
description: Run a structured UI/UX consultation to either (a) co-design a project-specific design system and emit `design-spec.md`, (b) review an existing UI with prioritized fixes, or (c) emit compact do/don't rules for a surface. Triggers when the user wants to define / build / refine a design system or design tokens, asks for a design spec, asks for a full UI review of a screen / mockup / PR, or wants design rules for a surface type. Do NOT trigger for narrow one-off questions ("is this color OK?", "should this button be larger?") — answer those directly without invoking the consultation flow.
|
||||
---
|
||||
|
||||
# OilOil UI/UX Guide
|
||||
|
||||
A style-neutral UI/UX consultation skill. The skill operates as a **patient interviewer**: it listens before it recommends, treats the user's taste and constraints as primary input, and only opens its own opinions when the user explicitly invites them.
|
||||
|
||||
## Default behavior
|
||||
|
||||
When triggered without an explicit mode, run `design`. Switch only when the user is explicit:
|
||||
|
||||
| User intent | Mode |
|
||||
|---|---|
|
||||
| Define / refine the design system itself; "let's pick colors and fonts" | `design` (default) |
|
||||
| "Give me rules for a settings page" / "what's the do/don't list for a dashboard" | `guide` |
|
||||
| "Review this screen" / pasted screenshot with no other instruction | `review` |
|
||||
|
||||
If intent is ambiguous, default to `design` and announce the mode in one short sentence so the user can correct you.
|
||||
|
||||
## 别一上来就问问题
|
||||
|
||||
进入 `design` 模式的第一件事不是问，是看。花 30 秒扫一遍项目：
|
||||
|
||||
- `tailwind.config` / `theme.ts` / `globals.css` 里有什么 token
|
||||
- `package.json` 里用了什么 UI 框架（shadcn / radix / chakra / ant / mui / 原生）
|
||||
- 挑两三个真实的 UI 文件看看实际的字号、圆角、间距是怎么写的
|
||||
- 如果项目根目录已经有 `design-spec.md` / `DESIGN.md` / `AGENT.md`，**直接读完**
|
||||
|
||||
这一步不可省。不看代码就开口，你只是在凭空猜——而且经常会问出"项目里其实早就定了"的问题，让用户立刻觉得你没用心。
|
||||
|
||||
## 看完之后，先判断这个项目处在哪个阶段
|
||||
|
||||
不同阶段的项目，开口方向完全不一样。把项目放进下面五档之一：
|
||||
|
||||
| 档 | 信号 | 开口走向 |
|
||||
|---|---|---|
|
||||
| **A. 空白** | Tailwind 默认配色，无自定义 token，没几个真组件 | 走完整流程：找意象 → 选 token → 业务设计稿 → 输出 spec |
|
||||
| **B. 半成品** | 有 token 但分散，组件风格不统一，圆角 4/8/16 散落 | 整理已有 + 补全，先问哪些是"想保留的决定"哪些是"凑合用的" |
|
||||
| **C. 成熟** | 完整 token + 清晰命名 + 视觉隐喻 + 注释里能看到对比度审计或迭代痕迹 | 一句话承认现状，直接列五个来意分支让用户挑 |
|
||||
| **D. 复杂遗留** | 多套 token 并存、新旧风格混用、看不出主线 | 建议先走 `review` 模式做审计，再讨论要不要重构 |
|
||||
| **E. 不确定** | 扫完心里没底 | 描述看到的，问用户这套是想稳定还是想换方向 |
|
||||
|
||||
## 开口的两条原则
|
||||
|
||||
**1. 用事实描述代替自我说明。** 描述项目现状（"你这套已经定得挺清楚了"、"用的是 Tailwind 默认配色"），而不是描述你自己（"我打算 X" / "我接下来 Y"）。用户关心项目，不关心你的工作方法。
|
||||
|
||||
**2. 默认不堆砌看代码的细节。** 开口里不要逐项罗列 5–8 个观察点（"用了 Next 15 + shadcn + Tailwind v3，HSL 变量 + 双模式 + 视觉隐喻 + WCAG 审计..."）。一句概括即可。如果用户问"你看到了什么"再展开。
|
||||
|
||||
### 五档开口范例
|
||||
|
||||
**A 空白**：
|
||||
> 看了下，是新建的 Next + Tailwind 项目，用的是默认配色，组件还很少。在我开始问之前——你有没有什么已经定的，比如品牌色、字体、想致敬的产品？
|
||||
|
||||
**B 半成品**：
|
||||
> 看了下。token 在 globals.css 里定了一部分，但圆角在不同组件里有 4 / 8 / 12 三种写法。是想把现有的整理统一好，还是借这次换个方向？
|
||||
|
||||
**C 成熟**：
|
||||
> 你这套已经定得挺清楚了。叫我来 design 通常是这几件事里的一种：
|
||||
>
|
||||
> · 把现有 spec 跟代码核对一遍，修正失真的地方
|
||||
> · 拿一个真实业务页面做一版设计稿，看现在的 token 用上去顺不顺
|
||||
> · 推进 spec 里的 open questions
|
||||
> · 给还没设计过的新 surface 出一套规则
|
||||
> · 审计某一块（dashboard / form / dialog 等），列 P0/P1/P2
|
||||
>
|
||||
> 哪一个？或者别的也行。
|
||||
|
||||
**D 复杂遗留**：
|
||||
> 你的 token 在三个地方都有定义，圆角用过五六种值，shadcn 装了但有些组件没用、自己写了一套。在动手定新东西之前，建议先走一遍 review，按 P0/P1/P2 列清楚现状。要先 review 吗？
|
||||
|
||||
**E 不确定**：
|
||||
> 看了下，token 和组件都有，看着是有想法的；但有些命名让我猜不准你想往哪个方向走。这套现在是想稳定下来，还是想换个方向？
|
||||
|
||||
完整对话流程和各分支怎么走见 `references/design-interview.md`。
|
||||
|
||||
---
|
||||
|
||||
## Operating principles (all modes)
|
||||
|
||||
These shape *how* the skill talks, not *what* it produces.
|
||||
|
||||
### Listen first, recommend last
|
||||
- Open with questions, not opinions. Find out the user's product, brand, references, constraints.
|
||||
- When presenting options, give 2–3 **without** a starred recommendation. Let the user choose. Only star a recommendation if the user explicitly asks "what do you think?" or "what would you pick?".
|
||||
- Don't ascribe value labels to options ("premium" vs "efficient" is loaded). Use neutral descriptors and concrete references.
|
||||
|
||||
### Imagery over jargon
|
||||
- "Closer to Linear" beats "sharp + dense + monochrome".
|
||||
- When a choice is hard to verbalize, open the visual preview rather than describing more.
|
||||
|
||||
### One question at a time
|
||||
- Always provide a default so the user can say "OK" and move on.
|
||||
- Don't bundle multiple decisions into one prompt.
|
||||
|
||||
### Challenge mismatches *gently*
|
||||
- If the user's choices contradict their stated product or audience, name the tension and offer two paths — don't simply override.
|
||||
|
||||
---
|
||||
|
||||
## Mode workflows
|
||||
|
||||
### `design` 模式 — 默认
|
||||
|
||||
最终产物：项目根目录的 `design-spec.md`（含项目自己业务的设计稿验证）。
|
||||
|
||||
整个流程是这样的，但**不是每个项目都从第一步走到最后一步**。Phase 0/1 决定了走完整路径还是走捷径：
|
||||
|
||||
1. **看代码 + 判断阶段（Phase 0）** — 必做。30 秒扫一遍项目，把它放进五档之一（空白 / 半成品 / 成熟 / 复杂遗留 / 不确定）。详细见上面"别一上来就问问题"那段。
|
||||
|
||||
2. **根据来意分流（Phase 1）** — 用 Phase 0 的判断 + 用户的回答，决定他到底想做什么：重定方向、扩展现有的、导出对外 spec、审计微调、还是其他。**走错分支比走慢更糟糕**。
|
||||
|
||||
3. **听细节（Phase 1b）** — 仅在用户要"重定方向"或"扩展"时进入。问产品、听品牌资产、问参考、问硬约束、问主要语言。**不抛推荐**。
|
||||
|
||||
4. **找意象（Phase 2）** — 仅在用户要"重定方向"时进入。从意象库里给 2–4 个候选让用户选，鼓励混合（避免趋同）。详见 `references/style-families/`。
|
||||
|
||||
5. **挑具体的 token（Phase 3）** — 颜色、字体、圆角、间距、阴影、动效，加上四个常被忽略的：容器策略、图标系统、装饰、语言。每项给 2–3 个选项不带星标推荐。详见 `references/extended-dimensions.md`。
|
||||
|
||||
6. **通用预览（Phase 4a）** — 打开模板（`references/design-preview-template.html`）渲染 5 个 surface 让用户快速判断"对路了没"。这是**探索**，不是定稿。
|
||||
|
||||
7. **业务化设计稿（Phase 4b）** — **真正的定稿环节**。用最终 token 给用户**自己业务的实际页面**生成一个独立 HTML 文件。用户在自己业务画面上拍板，才进入下一步。严格契约见 `references/business-mockup-contract.md`。
|
||||
|
||||
8. **输出（Phase 5）** — 只有当用户对 4b 的业务设计稿点头后才生成 `design-spec.md`。模板见 `references/design-spec-template.md`。
|
||||
|
||||
完整对话流程和各分支怎么走：`references/design-interview.md`
|
||||
意象库：`references/style-families/`
|
||||
四个扩展 token 维度：`references/extended-dimensions.md`
|
||||
业务化设计稿契约：`references/business-mockup-contract.md`
|
||||
浏览器预览模板：`references/design-preview-template.html`
|
||||
|
||||
### `guide` — Compact rules for a surface
|
||||
|
||||
1. Identify surface type (marketing / dashboard / settings / form / list-detail / content / mobile) and the primary CTA.
|
||||
2. Apply the **UX Hard Rules** below.
|
||||
3. Apply system-level constraints (`references/system-principles.md`).
|
||||
4. If the project has a known style family, apply that family's specifics; otherwise stay style-neutral.
|
||||
5. If icons are involved: `references/icons.md`.
|
||||
|
||||
Output: bullet do/don't list, no long paragraphs.
|
||||
|
||||
### `review` — Prioritized fixes for an existing UI
|
||||
|
||||
1. State assumptions (platform, target user, primary task) — one line each.
|
||||
2. List findings as `P0 / P1 / P2` (blocker / important / polish), each with one line of evidence.
|
||||
3. For major issues, label the diagnosis using `references/design-psych.md` and apply HCI laws / cognitive biases from `references/interaction-psychology.md` when relevant.
|
||||
4. Propose implementable fixes (layout, component, copy, state).
|
||||
5. End with a short verification checklist.
|
||||
|
||||
Output format: `references/review-template.md`. Per-surface checklists: `references/checklists.md`.
|
||||
|
||||
**Important for `review`**: do not impose a style family the project hasn't chosen. Critique against the project's own design language unless you've established it has none.
|
||||
|
||||
---
|
||||
|
||||
## UX Hard Rules (style-independent — apply to every project)
|
||||
|
||||
These are not aesthetic preferences. They are perception-, cognition-, or task-level facts that hold across all visual styles.
|
||||
|
||||
1. **Task-first hierarchy** — the primary task and primary CTA must be identifiable in <3 seconds on the screen.
|
||||
2. **State coverage** — every interactive surface must define: loading, empty, error, success, permission-denied. Missing any one is a real bug, not polish. See `references/checklists.md`.
|
||||
3. **Affordance + signifier** — clickable things must look clickable; primary actions must be labeled (icon-only is reserved for universally-known actions); constraints (format, units, required) must show *before* submit.
|
||||
4. **Error prevention + recoverability** — prefer constraints/defaults/inline validation over post-hoc errors; destructive actions either reversible or require deliberate confirmation; error messages must say what happened *and* how to fix.
|
||||
5. **Feedback loop closure** — after any action, the UI must answer: "did it work?" + "what changed?" + "what's next?". See `references/system-principles.md`.
|
||||
6. **Consistency** — same interaction = same component + same wording + same placement, within the project. Cross-project consistency is *not* a hard rule.
|
||||
7. **CRAP for visual hierarchy** — Contrast / Repetition / Alignment / Proximity. These are perceptual constants, not style choices.
|
||||
8. **Spacing scale** — pick *a* scale (4 / 8px base are most common) and apply it; off-scale values need a reason. The specific scale is a project choice; the discipline is a hard rule.
|
||||
9. **Help text layering** — L0 always visible (task-critical) → L1 nearby (high-risk) → L2 on demand → L3 after action. Many L0 hints = fix IA, not add more text.
|
||||
10. **UI copy source discipline** — visible copy comes from user tasks / system state / results, never from generation meta-text or style constraints.
|
||||
|
||||
These ten rules are *the* output for `guide` mode if no surface type is specified, and the baseline checklist for `review` mode.
|
||||
|
||||
---
|
||||
|
||||
## Style Lens (project-chosen — never default-imposed)
|
||||
|
||||
A "style family" bundles a coherent set of font, color, spacing, radius, shadow, motion, and "anti-patterns to avoid" choices that work together.
|
||||
|
||||
The skill ships with eight families. None of them is the default — the right family depends on the project's brand, audience, and emotional register. See `references/style-families/index.md` for the catalog and `references/style-families/<family>.md` for each family's specifics.
|
||||
|
||||
| Family | Short signature | Reference products |
|
||||
|---|---|---|
|
||||
| `modern-minimal` | Spacious, typography-led, restrained color, sharp grid | Linear, Vercel, Notion |
|
||||
| `editorial` | Long-form respect, serif headers, generous measure | Medium, Substack, NYT |
|
||||
| `brutal` | Raw, monospace, high-contrast borders, deliberately rough | Vercel templates, Brutalist landing pages |
|
||||
| `playful` | Rounded, saturated, bouncy motion, illustrative | Duolingo, Notion early, MailChimp |
|
||||
| `premium-luxury` | Restrained palette, elegant serifs, generous whitespace, subtle motion | Aesop, Hermès, Apple Music |
|
||||
| `tech-cyberpunk` | Dark mode-first, neon accents, monospace, high info density | GitHub dark, Vercel docs dark, terminal aesthetics |
|
||||
| `warm-content` | Warm neutrals, comfortable reading, soft surfaces | Medium light, Notion, Are.na |
|
||||
| `brand-driven` | All tokens derived from an existing brand (logo, brand book) | Custom; the project *is* the source |
|
||||
|
||||
**Important**: families are starting points, not cages. A user can pick `modern-minimal` and still want 16px radius. The family supplies defaults; the user always wins.
|
||||
|
||||
**Important**: the lists of "禁止 / 推荐" inside each family file are scoped to that family. They are not global UX rules. `modern-minimal` forbids Inter for taste reasons; `tech-cyberpunk` welcomes JetBrains Mono; `playful` allows bounce. Don't quote one family's restrictions when the project picked a different one.
|
||||
|
||||
---
|
||||
|
||||
## When the user pushes back on a suggestion
|
||||
|
||||
Always defer to the user's stated preference *unless* it violates a UX Hard Rule. If it does:
|
||||
- Name the rule that's at risk.
|
||||
- Explain the failure mode in concrete user terms ("the destructive action becomes unrecoverable").
|
||||
- Offer one alternative that preserves the user's intent.
|
||||
- If they still want it, do it. The hard rules are guidance, not gates.
|
||||
|
||||
## References
|
||||
|
||||
- Listening-first interview flow (Phase 0 → output): `references/design-interview.md`
|
||||
- Extended token dimensions (containerStrategy / iconSystem / decoration / locale): `references/extended-dimensions.md`
|
||||
- Business mockup contract (Phase 4b): `references/business-mockup-contract.md`
|
||||
- Style family catalog: `references/style-families/index.md`
|
||||
- Per-family details: `references/style-families/<family>.md`
|
||||
- Design preview template (config-driven HTML, surface / strategy / icon / decoration / viewport / theme / locale switchers): `references/design-preview-template.html`
|
||||
- `design-spec.md` output template: `references/design-spec-template.md`
|
||||
- System-level principles: `references/system-principles.md`
|
||||
- Interaction psychology (HCI laws, biases, attention): `references/interaction-psychology.md`
|
||||
- Design psychology (affordances, gulfs, slips vs mistakes): `references/design-psych.md`
|
||||
- Icon rules: `references/icons.md`
|
||||
- Review output template: `references/review-template.md`
|
||||
- Per-surface checklists: `references/checklists.md`
|
||||
171
.agents/skills/oiloil-ui-ux-guide/evals/evals.json
Normal file
171
.agents/skills/oiloil-ui-ux-guide/evals/evals.json
Normal file
@ -0,0 +1,171 @@
|
||||
{
|
||||
"skill_name": "oiloil-ui-ux-guide",
|
||||
"notes": "Test set covers: (a) patient-interviewer behavior, (b) cross-project-type generality, (c) style-family neutrality, (d) overtrigger avoidance, (e) extended-dimensions modeling (container strategy, icon system, decoration, locale), (f) Phase 4b business mockup as gating artifact. Run with the skill loaded; assertions check behavioral properties, not exact wording.",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "design-from-scratch-no-style-leak",
|
||||
"prompt": "I'm starting a new internal tool for our finance team. They use it 6 hours a day to reconcile invoices. I want to define the design system before I write any UI code. Help me get a design-spec.md.",
|
||||
"files": [],
|
||||
"expected_output": "Skill enters design mode, runs Phase 0 (codebase scan even though greenfield), then opens with listening questions about product/audience/references/constraints. Does NOT impose modern-minimal or any style family upfront. Does NOT recommend Plus Jakarta Sans or ban Inter. Eventually produces design-spec.md.",
|
||||
"assertions": [
|
||||
{"text": "Performs codebase scan before asking any design question", "kind": "behavior"},
|
||||
{"text": "First user-facing question is open (e.g. 'what does this do' / 'who uses it' / 'any references') — not a recommendation", "kind": "behavior"},
|
||||
{"text": "Does not impose 'modern-minimal' or any specific style family without the user choosing it", "kind": "behavior"},
|
||||
{"text": "Does not include '禁止 Inter' / 'no Inter' style hard-bans as global rules", "kind": "behavior"},
|
||||
{"text": "When presenting style family options, presents them as neutral siblings (no starred recommendation) unless user asks for opinion", "kind": "behavior"},
|
||||
{"text": "Final output is a design-spec.md file in the project root, containing color/type/spacing/radius/shadow sections", "kind": "artifact"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"name": "design-with-existing-brand",
|
||||
"prompt": "We already have a brand book — primary color is #d62828, headings use Söhne Breit, body uses Söhne. I need a design-spec.md that incorporates these and fills in everything else. Project is the marketing site for a luxury hotel group.",
|
||||
"files": [],
|
||||
"expected_output": "Skill recognizes this is brand-driven (Phase 1 inputs already provided), skips redundant questions, locks brand color and fonts as fixed inputs, and treats the rest as derivable. Picks a style direction compatible with luxury hospitality (likely premium-luxury family).",
|
||||
"assertions": [
|
||||
{"text": "Treats #d62828 as fixed primary, does not propose alternatives", "kind": "behavior"},
|
||||
{"text": "Treats Söhne Breit / Söhne as fixed fonts", "kind": "behavior"},
|
||||
{"text": "Does not ask the user to pick a primary color or heading font", "kind": "behavior"},
|
||||
{"text": "Notes premium-luxury or brand-driven family in the spec, with hospitality-appropriate spacing/motion", "kind": "behavior"},
|
||||
{"text": "design-spec.md contains the user's brand inputs verbatim and derives hover/subtle from primary", "kind": "artifact"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"name": "design-children-education-app",
|
||||
"prompt": "I'm building a math practice app for kids age 6–10. Needs to feel encouraging, not clinical. Help me set up the design system.",
|
||||
"files": [],
|
||||
"expected_output": "Skill should NOT default to modern-minimal (which is wrong for this audience). Should surface playful (or warm-content) as the candidate family. Should allow bouncy motion, rounded radius (16+ px), saturated colors — opposite of the original SKILL.md's bans.",
|
||||
"assertions": [
|
||||
{"text": "Does not propose modern-minimal or tech-cyberpunk as starting families", "kind": "behavior"},
|
||||
{"text": "Surfaces playful and/or warm-content as candidate families", "kind": "behavior"},
|
||||
{"text": "Allows bouncy motion vocabulary if user picks playful family", "kind": "behavior"},
|
||||
{"text": "Allows large radius (16px+) without flagging as anti-pattern", "kind": "behavior"},
|
||||
{"text": "Color palette skews saturated/warm, not muted/cool", "kind": "behavior"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"name": "review-mode-existing-ui",
|
||||
"prompt": "Please review this dashboard screenshot. Project is an analytics tool for marketing teams; users are non-technical. Output P0/P1/P2.",
|
||||
"files": ["test-fixtures/dashboard-screenshot.png"],
|
||||
"expected_output": "Skill enters review mode, states assumptions, lists findings as P0/P1/P2 with one-line evidence each, proposes implementable fixes, ends with a short verification checklist. Does NOT critique against modern-minimal style if the project's own style is different.",
|
||||
"assertions": [
|
||||
{"text": "States assumptions about platform, user, primary task before findings", "kind": "behavior"},
|
||||
{"text": "Findings are organized as P0/P1/P2 with evidence per item", "kind": "behavior"},
|
||||
{"text": "Each finding includes a concrete implementable fix (not just 'improve hierarchy')", "kind": "behavior"},
|
||||
{"text": "Does not impose modern-minimal taste rules unless the project clearly is in that family", "kind": "behavior"},
|
||||
{"text": "Ends with a verification checklist", "kind": "behavior"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"name": "guide-mode-form-rules",
|
||||
"prompt": "Give me the do/don't rules for designing a long signup form (8 fields). Use guide mode.",
|
||||
"files": [],
|
||||
"expected_output": "Skill enters guide mode, identifies surface as form, returns compact bullet rules covering: primary CTA hierarchy, state coverage, affordance, error prevention, help text layering, spacing. No long paragraphs. No style-family-specific rules unless one was named.",
|
||||
"assertions": [
|
||||
{"text": "Output is bullet-formatted, no long paragraphs", "kind": "behavior"},
|
||||
{"text": "Covers all UX Hard Rules relevant to forms (CTA hierarchy, states, affordance, error prevention, help layering)", "kind": "behavior"},
|
||||
{"text": "Does not include color/font/radius prescriptions unless user named a style family", "kind": "behavior"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"name": "no-overtrigger-narrow-question",
|
||||
"prompt": "Should this button be #2563eb or #3b82f6? Both look fine to me.",
|
||||
"files": [],
|
||||
"expected_output": "Skill should NOT enter the full design consultation. Should answer the narrow question directly: trade-off between the two values, recommendation if user wants one (or refuse to pick if both genuinely fit), in 2–3 sentences max. Does not run codebase scan, does not ask about brand/references/constraints.",
|
||||
"assertions": [
|
||||
{"text": "Does NOT trigger the design mode consultation flow", "kind": "behavior"},
|
||||
{"text": "Does NOT run a codebase scan before answering", "kind": "behavior"},
|
||||
{"text": "Answers in <= 5 sentences", "kind": "behavior"},
|
||||
{"text": "Does not ask the user open questions about product/audience/references", "kind": "behavior"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 7,
|
||||
"name": "user-pushes-back-honored",
|
||||
"prompt": "[After Phase 2 of design mode, user has picked modern-minimal family and is in Phase 3] I want 20px border radius for buttons. I know that's bigger than your default — go with it.",
|
||||
"files": [],
|
||||
"expected_output": "Skill takes the user's preference. Does NOT lecture about modern-minimal preferring 4–8px. Does NOT try to talk them back. May offer one inline note ('that pushes the design toward playful — happy to update the family tag if you want') but only as info, not as resistance.",
|
||||
"assertions": [
|
||||
{"text": "Sets radius to 20px without resistance", "kind": "behavior"},
|
||||
{"text": "Does not lecture the user about modern-minimal conventions", "kind": "behavior"},
|
||||
{"text": "If commenting, does so in <= 1 short sentence and does not block the change", "kind": "behavior"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 8,
|
||||
"name": "ux-hard-rule-pushback",
|
||||
"prompt": "[In design mode, user says] We don't need an error state for the form — users will just see if their submission worked when the page reloads.",
|
||||
"files": [],
|
||||
"expected_output": "This violates a UX Hard Rule (state coverage / feedback loop closure). Skill should name the rule, explain the failure mode in concrete user terms, offer one alternative, and defer if the user still insists.",
|
||||
"assertions": [
|
||||
{"text": "Names the UX Hard Rule being violated (state coverage / feedback loop)", "kind": "behavior"},
|
||||
{"text": "Explains the failure in user terms, not abstract 'this is bad practice'", "kind": "behavior"},
|
||||
{"text": "Offers one concrete alternative", "kind": "behavior"},
|
||||
{"text": "If the user insists, defers (does not block)", "kind": "behavior"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 9,
|
||||
"name": "design-cn-locale-business-mockup",
|
||||
"prompt": "我在做一个广告投放计划管理后台，团队是国内电商运营，每天用 6+ 小时。希望整个产品语言是中文。帮我把设计规范定下来。",
|
||||
"files": [],
|
||||
"expected_output": "Skill should run Phase 0, listen, pick a family with the user, but critically: in Phase 3 the typography options must include CJK-capable fonts (Noto Sans SC, Source Han Sans, PingFang fallback) — not Latin-only options. In Phase 4b, generate a business mockup whose copy is 100% Chinese, with realistic ad-campaign domain language (投放计划/审核中/暂停/预算 etc), not English placeholders. Mockup body line-height >= 1.7 for CJK comfort.",
|
||||
"assertions": [
|
||||
{"text": "Phase 3 typography candidates include CJK-capable fonts (Noto Sans SC / Source Han Sans / PingFang / similar)", "kind": "behavior"},
|
||||
{"text": "Does not propose Latin-only fonts (Plus Jakarta Sans / Geist / DM Sans alone) without CJK fallback", "kind": "behavior"},
|
||||
{"text": "Phase 4b business mockup is generated to /tmp/business-mockup-N.html", "kind": "artifact"},
|
||||
{"text": "All visible copy in the mockup is Chinese, with domain-appropriate vocabulary (投放计划 / 审核 / 暂停 / 预算 / etc)", "kind": "artifact"},
|
||||
{"text": "Mockup uses realistic Chinese names and demo data (not 'John Doe' / 'Acme Corp')", "kind": "artifact"},
|
||||
{"text": "Mockup CSS sets body line-height >= 1.6 for CJK readability", "kind": "artifact"},
|
||||
{"text": "Skill does NOT lock design-spec.md until user has approved the business mockup", "kind": "behavior"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 10,
|
||||
"name": "container-strategy-tinted-surface",
|
||||
"prompt": "[In design mode Phase 3, user says] I don't want borders around our cards — I want them to feel like soft tinted blocks instead. The brand is warm and friendly.",
|
||||
"files": [],
|
||||
"expected_output": "Skill recognizes this as a containerStrategy = tinted-surface preference. Confirms and updates the spec. The Phase 4a preview and Phase 4b mockup MUST render containers with offset surface color (no border, no shadow), proving the model can express this dimension.",
|
||||
"assertions": [
|
||||
{"text": "Skill identifies the user's request as a containerStrategy decision (uses the term or equivalent)", "kind": "behavior"},
|
||||
{"text": "Sets containerStrategy = tinted-surface in the working spec", "kind": "behavior"},
|
||||
{"text": "Phase 4a preview renders cards with no border, surface color offset from page bg", "kind": "artifact"},
|
||||
{"text": "Phase 4b business mockup CSS does not contain `border: 1px solid` on card-like containers", "kind": "artifact"},
|
||||
{"text": "Phase 4b business mockup uses surface color offset for container separation", "kind": "artifact"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 11,
|
||||
"name": "decoration-marketing-vs-dashboard-split",
|
||||
"prompt": "[In design mode Phase 3, after picking playful family for a kids' learning app] For the marketing site I want it lively — gradients, illustrations, the whole thing. But the actual app dashboard for parents should stay calm and focused. Can the design system express that?",
|
||||
"files": [],
|
||||
"expected_output": "Skill confirms decoration is a per-surface dimension, not global. Sets decoration policy: marketing = expressive gradients + illustration motifs, dashboard = none. design-spec.md section 7c shows the per-surface table. Phase 4b business mockup renders the dashboard surface CLEAN (no gradient, no illustration), proving the model honors per-surface policy.",
|
||||
"assertions": [
|
||||
{"text": "Skill confirms decoration can be set per-surface (does not force one global policy)", "kind": "behavior"},
|
||||
{"text": "design-spec.md section 7c contains a per-surface table with marketing and dashboard rows", "kind": "artifact"},
|
||||
{"text": "Marketing row shows expressive gradients + illustration motifs", "kind": "artifact"},
|
||||
{"text": "Dashboard row shows decoration.gradients = none and decoration.motifs = none (or data-viz only)", "kind": "artifact"},
|
||||
{"text": "Phase 4b dashboard mockup contains no gradient backgrounds or decorative illustrations", "kind": "artifact"}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 12,
|
||||
"name": "phase-4b-gating-not-skipped",
|
||||
"prompt": "[After Phase 4a, user says] OK, the preview looks roughly fine. Just write the design-spec.md and we'll iterate later.",
|
||||
"files": [],
|
||||
"expected_output": "Skill should NOT immediately jump to Phase 5. It should explain Phase 4b's role (the business mockup is the gating artifact — it surfaces issues the generic preview can't), offer to generate the mockup, and only skip to Phase 5 if the user explicitly insists. If user insists on skipping, the spec must note the deviation ('Validated against generic preview only; business mockup skipped per user request').",
|
||||
"assertions": [
|
||||
{"text": "Does NOT immediately generate design-spec.md after Phase 4a", "kind": "behavior"},
|
||||
{"text": "Briefly explains why Phase 4b matters (one short paragraph max)", "kind": "behavior"},
|
||||
{"text": "Offers to generate the business mockup with one focused question (which surface to mock)", "kind": "behavior"},
|
||||
{"text": "If user insists on skipping, design-spec.md contains a note about Phase 4b being skipped", "kind": "artifact"},
|
||||
{"text": "Does not lecture or block — defers to user's choice after one ask", "kind": "behavior"}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -0,0 +1,149 @@
|
||||
# Business Mockup Contract (Phase 4b)
|
||||
|
||||
## What this is
|
||||
|
||||
In Phase 4b of the `design` flow, the skill generates a **standalone HTML file** that renders the project's actual core surface using the chosen tokens. This file is the user's **final review artifact** before the spec is locked. The user looks at *their own product*, with *their own copy*, in *their own language*, rendered in the candidate design system, and decides whether to ship the spec or iterate.
|
||||
|
||||
This file is *not* the same as `design-preview-template.html`:
|
||||
|
||||
| | `design-preview-template.html` | business mockup |
|
||||
|---|---|---|
|
||||
| Purpose | Quick try-on during exploration | Final ship/iterate decision |
|
||||
| Content | Generic surfaces (dashboard / marketing / form / ...) | The user's actual product surface |
|
||||
| Copy | Generic placeholder ("Active users 2,847") | User's domain copy ("待审核投放计划 12 条") |
|
||||
| Language | English placeholder | Project's primary locale |
|
||||
| Iteration | Rewrite JSON config; refresh | Regenerate the HTML when tokens change |
|
||||
| Lifetime | Disposable | Disposable (but kept around per iteration for comparison) |
|
||||
|
||||
## Where it lives
|
||||
|
||||
`/tmp/business-mockup-<n>.html` where `<n>` increments per iteration. Keeping previous iterations lets the user compare side-by-side.
|
||||
|
||||
## The contract — what the generated file MUST satisfy
|
||||
|
||||
### 1. Single self-contained file
|
||||
|
||||
- One `.html` file. No external assets except Google Fonts CDN.
|
||||
- All CSS inline in `<style>`.
|
||||
- All icons inline as SVG (or via a single CDN sprite link if the icon set has one).
|
||||
- All images either omitted or inline as data URIs / placeholder SVG.
|
||||
|
||||
### 2. Token application contract
|
||||
|
||||
**Every visual decision in the file must be traceable to a token.** No ad-hoc values. Concretely:
|
||||
|
||||
- All colors come from `--color-*` CSS variables defined at the top of the `<style>` block.
|
||||
- All fonts come from `--font-*` variables and a single `@import` at the top of `<style>`.
|
||||
- All radii come from `--radius-*`.
|
||||
- All spacing values come from the project's spacing scale (4 / 8 / 12 / 16 / 24 / 32 / 48 — or whatever scale was chosen). Off-scale spacing is forbidden in the mockup; if you find yourself wanting `padding: 13px;` you've left the contract.
|
||||
- All shadows come from `--shadow-*` (or are absent if `containerStrategy` is `border` / `divider` / `none`).
|
||||
- All motion (hover transitions etc.) follows the chosen motion vocabulary — `minimal` ≈ no transitions or 100ms; `subtle` ≈ 200ms ease; `expressive` ≈ 300ms+ with custom easing.
|
||||
|
||||
### 3. `containerStrategy` honored
|
||||
|
||||
The generated file must implement the chosen container strategy globally:
|
||||
|
||||
- `border` — `border: 1px solid var(--color-border)` on cards / panels / list-rows. No `box-shadow` for separation.
|
||||
- `tinted-surface` — cards use `background: var(--color-surface)` against page `background: var(--color-bg)`, where surface is offset (lighter on light themes, lighter on dark themes by ~3-5% lightness). No border, no shadow.
|
||||
- `elevation` — `box-shadow: var(--shadow-md)` on cards. No border. Page bg and surface can be the same color.
|
||||
- `divider` — no enclosing borders. Sections separated by `border-bottom: 1px solid var(--color-border)`.
|
||||
- `none` — pure spacing. No borders, no shadows. Section separation by margin only.
|
||||
|
||||
A mixed implementation (some cards use border, some use elevation) is a contract violation unless the spec explicitly defined per-surface overrides.
|
||||
|
||||
### 4. `iconSystem` honored
|
||||
|
||||
- Use only icons from the chosen `iconSystem.set`.
|
||||
- Apply the chosen `weight` (e.g. `phosphor` `bold`).
|
||||
- Apply the chosen `treatment`:
|
||||
- `monochrome` — single fill, usually `currentColor`.
|
||||
- `two-tone` — primary + secondary fill (use `--color-primary` + `--color-text-muted` or per-icon two-tone if the set ships with it).
|
||||
- `brand-tinted` — `--color-primary` at 0.6-0.8 alpha.
|
||||
- Don't mix icon sets within the file. If you need an icon the set doesn't have, use the closest match or omit.
|
||||
|
||||
### 5. `decoration` honored
|
||||
|
||||
If the spec sets `decoration.gradients = "expressive"`, the mockup *should* use multiple gradients (hero bg, accent buttons, decorative shapes). If `none`, the mockup *must* not use gradients anywhere.
|
||||
|
||||
If `decoration.textures = "noise"`, apply a noise overlay via SVG filter or data-URI background-image. If `none`, no texture.
|
||||
|
||||
If `decoration.motifs = "illustration"`, include 1-2 inline SVG illustrations or geometric figures appropriate to the family. If `none`, no decorative imagery.
|
||||
|
||||
### 6. `locale` honored
|
||||
|
||||
- All visible copy in `locale.primary`.
|
||||
- Demo data should look real for that locale: Chinese names for `zh-CN` users (王小明), Japanese for `ja` (田中太郎), realistic numbers / currency formatting (¥ for JP, ¥ or 元 for CN).
|
||||
- Body line-height >=1.7 for CJK locales, 1.5 for Latin.
|
||||
- Heading letter-spacing 0 for CJK, may be -0.01em to -0.02em for Latin display sizes.
|
||||
|
||||
### 7. Real business surface, not generic
|
||||
|
||||
This is the most important requirement. The mockup must show **the user's actual product**, derived from what they said in Phase 1.
|
||||
|
||||
If the user said "广告投放计划管理后台":
|
||||
- The mockup is a list of 投放计划 with state (审核中 / 投放中 / 已暂停 / 已结束), not "Active users 2,847".
|
||||
- Real-feeling demo data: "618 大促主推 - 美妆护肤" "黑五前置 - 数码周边".
|
||||
|
||||
If the user said "病历归档":
|
||||
- The mockup shows patient records with diagnostic codes, dates, attending physician.
|
||||
- Not "User", "Owner", "Status" — but "患者", "主治医生", "归档状态".
|
||||
|
||||
If the user said "亲子任务卡片":
|
||||
- The mockup shows task cards with cute icons / illustrations, completion stickers, parent/child role split.
|
||||
- Not "Project", "Owner" — but "今天的任务", "完成 ✓", with appropriately playful copy and visuals.
|
||||
|
||||
The skill picks one or two **core pages** for the mockup, not a full app. Picking the right page matters: choose the user's primary daily-use surface, not the rarely-visited settings page.
|
||||
|
||||
### 8. Two-page minimum, three-page maximum
|
||||
|
||||
- Page 1: the primary daily-use surface (list / dashboard / main canvas).
|
||||
- Page 2 (optional): a key flow surface (detail view / form / confirmation).
|
||||
- Page 3 (optional): if the project has a marketing surface as part of the design system, include a small marketing block; otherwise skip.
|
||||
|
||||
Pages live in the same file as `<section>` blocks separated by visual gap and a small in-page nav (or vertical scroll).
|
||||
|
||||
### 9. No fake interactivity
|
||||
|
||||
The mockup is a static visual. No working JS. Buttons don't navigate. Forms don't submit. Nav links are inert. This keeps the file simple and the focus on visual decisions.
|
||||
|
||||
### 10. Header annotation
|
||||
|
||||
At the top of the mockup, render a small fixed banner:
|
||||
|
||||
```
|
||||
[Project Name] · business mockup · iteration N
|
||||
[family] · [containerStrategy] · [iconSystem.set] · [locale.primary]
|
||||
```
|
||||
|
||||
So the user always knows which version they're looking at. Style the banner discretely (high contrast against bg, but small — 12-13px, top-right corner).
|
||||
|
||||
---
|
||||
|
||||
## How to generate the file
|
||||
|
||||
This is the workflow, not output:
|
||||
|
||||
1. **Re-read the user's Phase 1 inputs** — what does the product do, who uses it, what surfaces matter.
|
||||
2. **Pick 1-2 core surfaces** based on (1). If unclear, ask the user one focused question: "Of all the screens in this product, which one would you say users spend the most time on?".
|
||||
3. **Draft a content outline first** — what real entities go on each surface, what real fields, what real states. Don't start writing HTML yet.
|
||||
4. **Write the HTML** following the contract. Use the spec's chosen tokens.
|
||||
5. **Save to `/tmp/business-mockup-<n>.html`** and tell the user where it is.
|
||||
6. **Open it for the user** (`open /tmp/business-mockup-<n>.html` on macOS).
|
||||
7. **Ask one open question**: "How does it feel? Anything you'd want to change before we lock the spec?"
|
||||
8. **Iterate** — if the user wants changes, decide whether they're token changes (re-run Phase 3 to update tokens, then regenerate) or content/copy changes (regenerate with same tokens).
|
||||
|
||||
## When to skip Phase 4b
|
||||
|
||||
- The user explicitly says "skip the business mockup, just write the spec" → honor it.
|
||||
- The project is not a single product but a multi-product design system (no single business surface) → use the static template only.
|
||||
- The user is reviewing for a hypothetical / not-yet-defined product → ask whether to invent a plausible business or stay generic.
|
||||
|
||||
## Why the contract matters
|
||||
|
||||
Without it, the AI tends to:
|
||||
|
||||
- Generate prettier-than-real demo content that doesn't stress the tokens (everything fits because the AI made the data fit).
|
||||
- Sneak in off-scale spacing because "it looks better here" — at which point the spec is no longer trusted.
|
||||
- Use a different icon set than agreed for "variety", which is the worst possible thing for a system review.
|
||||
|
||||
The contract makes the mockup *useful as evidence* — what the user sees in the mockup is what they get if they apply the spec faithfully. If the mockup looks bad and the contract was honored, the spec is wrong; iterate the spec, not the mockup.
|
||||
111
.agents/skills/oiloil-ui-ux-guide/references/checklists.md
Normal file
111
.agents/skills/oiloil-ui-ux-guide/references/checklists.md
Normal file
@ -0,0 +1,111 @@
|
||||
# Expanded Checklists (Load Only When Needed)
|
||||
|
||||
Use these checklists when the task needs more detail than the SKILL.md minimal principles.
|
||||
|
||||
## Universal states
|
||||
|
||||
- Loading:
|
||||
- Avoid layout jumps (skeleton/placeholder with stable height)
|
||||
- Prevent double-submit; show progress when waiting is noticeable
|
||||
- Empty:
|
||||
- Explain what “empty” means
|
||||
- Provide a next step (create/import/change filters)
|
||||
- Error:
|
||||
- Message: what happened + why (if safe) + what to do
|
||||
- Preserve user input where possible
|
||||
- Success:
|
||||
- Confirm outcome + provide next action (view, undo, share)
|
||||
- Permission:
|
||||
- Explain why access is blocked + where to request access
|
||||
|
||||
## Affordance (示能性) & signifiers (指示符)
|
||||
|
||||
- Primary actions look like actions:
|
||||
- Use a real primary button; label with a verb (avoid OK/Done).
|
||||
- Icon-only is reserved for universally-known actions (search/close/more/settings).
|
||||
- Links look like links:
|
||||
- Ensure a clear link signifier (underline or strong hover/contrast), not color-only subtlety.
|
||||
- Clickable surfaces communicate clickability:
|
||||
- Web: for custom clickable surfaces (non-`button`/`a`), use `cursor: pointer` and a visible focus style.
|
||||
- Card/list rows that open should have hover + chevron/affordance cue (or a clear “View” action).
|
||||
- Do not make plain body text behave like a button.
|
||||
- Controls match outcomes (mapping):
|
||||
- Place controls near what they affect; keep directionality intuitive.
|
||||
- Group controls with the content they control (filters above list; section actions in section header).
|
||||
|
||||
## Lists (table / cards)
|
||||
|
||||
- Scannability:
|
||||
- One primary column/field; secondary details visually muted
|
||||
- Consistent row height and alignment; avoid jagged columns
|
||||
- Controls:
|
||||
- Search/filter/sort appear before the list, not after
|
||||
- Selected filters are visible and removable
|
||||
- Row actions:
|
||||
- Keep high-frequency actions visible
|
||||
- Hide long-tail actions under a “more” menu (but not the primary action)
|
||||
|
||||
## Detail pages
|
||||
|
||||
- Clear page title that matches the object
|
||||
- Key facts near the top; secondary info below or collapsed
|
||||
- Actions grouped by intent (primary, secondary, destructive)
|
||||
- Related items and history: grouped and titled (avoid endless scroll dumps)
|
||||
|
||||
## Forms (create/edit/config)
|
||||
|
||||
- Reduce thinking:
|
||||
- Use defaults and reasonable prefill
|
||||
- Use presets when choices are complex
|
||||
- Prevent errors:
|
||||
- Inline validation; format hints before submit
|
||||
- Don’t require users to memorize constraints
|
||||
- Layout:
|
||||
- Group fields by meaning; use headings (not just spacing)
|
||||
- Keep labels consistent (position + style) across the product
|
||||
- Submission:
|
||||
- One primary submit action
|
||||
- Disabled state and clear error placement
|
||||
|
||||
## Settings / Preferences
|
||||
|
||||
- Group by mental model (account, security, notifications, integrations, appearance)
|
||||
- For each setting: clear label + short value explanation only if needed
|
||||
- Destructive actions separated and clearly labeled; never hide them among benign toggles
|
||||
|
||||
## Motion (animation) review checklist (modern, clean, creator-friendly)
|
||||
|
||||
- Purpose:
|
||||
- Each animation explains hierarchy (panel/overlay) or state change (feedback). If not, remove or downgrade.
|
||||
- Vocabulary:
|
||||
- Prefer fade; then small translate+fade; allow tiny scale+fade for overlays. Avoid “showy” motion.
|
||||
- Canvas stability:
|
||||
- Keep the work surface stable (canvas/editor area). Move panels/overlays, not the core content.
|
||||
- Responsiveness:
|
||||
- Interaction feedback (hover/pressed) feels immediate; UI never makes users wait for animation to proceed.
|
||||
- Consistency:
|
||||
- Same component type uses the same motion pattern across the product.
|
||||
- Enter/exit feel related (no random directions or mixed styles).
|
||||
- Stability:
|
||||
- No layout shift/jank during loading or transitions; use skeleton/placeholder to preserve layout.
|
||||
- Red flags (avoid):
|
||||
- Continuous decorative motion (breathing backgrounds, floating cards).
|
||||
- Large bouncy/elastic overshoot that steals attention.
|
||||
- Big page-level transitions for routine navigation.
|
||||
|
||||
## Dashboards
|
||||
|
||||
- Decide the “story”: what decision should the user make here?
|
||||
- Keep top KPI set small; avoid wall-of-numbers
|
||||
- Make time range and filters obvious and persistent
|
||||
- Provide drill-down paths (click-through) for every key metric
|
||||
|
||||
## Copy rules (minimal style)
|
||||
|
||||
- Prefer short labels over helper paragraphs.
|
||||
- Use helper text only when it:
|
||||
- prevents an error
|
||||
- clarifies a non-obvious term
|
||||
- explains consequences (especially destructive actions)
|
||||
- builds trust (privacy, payment, external side effects)
|
||||
- Replace vague verbs ("Do", "OK") with concrete actions ("Create", "Save", "Publish").
|
||||
396
.agents/skills/oiloil-ui-ux-guide/references/design-interview.md
Normal file
396
.agents/skills/oiloil-ui-ux-guide/references/design-interview.md
Normal file
@ -0,0 +1,396 @@
|
||||
# Design Interview Flow (Listening-First)
|
||||
|
||||
## Your role: patient interviewer
|
||||
|
||||
You are not an opinionated consultant. You are a patient interviewer whose job is to understand the user's product, brand, taste, and constraints **before** introducing any design opinion.
|
||||
|
||||
Behavioral rules:
|
||||
|
||||
- **Listen first.** Ask open questions. Don't open with recommendations.
|
||||
- **No starred recommendations.** When you present 2–3 options, present them as neutral siblings. Star a recommendation only if the user explicitly asks "what do you think?" / "which would you pick?".
|
||||
- **No loaded labels.** "Premium" vs "efficient" steers the answer. Use neutral descriptors and concrete references ("closer to Linear" / "closer to Medium").
|
||||
- **One question at a time.** Always include a default so the user can say "OK" and move on.
|
||||
- **Imagery over jargon.** When verbalization is hard, open the visual preview.
|
||||
- **Defer.** When the user states a preference, take it. Only push back when it violates a UX Hard Rule (see SKILL.md).
|
||||
|
||||
The arc of the interview:
|
||||
|
||||
```
|
||||
Phase 0 Scan code (silent)
|
||||
↓
|
||||
Phase 1 Listen — open questions, no recommendations
|
||||
↓
|
||||
Phase 2 Style family — confirm if user already named one, else show neutral options
|
||||
↓
|
||||
Phase 3 Visual choices — present options drawn from chosen family, no stars
|
||||
(covers: color · type · radius · spacing · shadow · motion
|
||||
· containerStrategy · iconSystem · decoration · locale)
|
||||
↓
|
||||
Phase 4a Generic preview — render tokens on the static template's 5 surfaces
|
||||
↓
|
||||
Phase 4b Business mockup — generate a standalone HTML of the user's actual product,
|
||||
in their language, applying the full token set. ← Final review evidence.
|
||||
↓
|
||||
Phase 5 Output design-spec.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: 先看代码（必做，安静地做）
|
||||
|
||||
不管用户多急，**这一步不可省**。30 秒能避免后面问出几个项目里已经定下来的问题——那种"哦我已经选过 Inter 了"的尴尬反馈，是 skill 失败感的最大来源。
|
||||
|
||||
### 扫什么
|
||||
|
||||
```
|
||||
- tailwind.config.{js,ts,mjs,cjs}
|
||||
- **/theme.{js,ts,css}
|
||||
- **/tokens.{js,ts,json,css}
|
||||
- **/variables.css, **/globals.css, **/index.css, **/app.css
|
||||
- **/design-system/**, **/design-tokens/**, **/styles/**
|
||||
- package.json → 看 UI 框架（shadcn / radix / chakra / antd / mui / naive-ui / daisyui...）
|
||||
- 项目根目录的 design-spec.md / DESIGN.md / AGENT.md / README.md 里有没有提设计
|
||||
- 挑 2–3 个真实的 UI 文件（按 src/components 或 app 目录下），看实际用法
|
||||
```
|
||||
|
||||
### 看的是事实，不是判断
|
||||
|
||||
总结里只放观察到的事实，不要立刻评价好坏：
|
||||
|
||||
- 定义了哪些 token（颜色 / 字号 / 圆角 / 间距 / 阴影分层）？
|
||||
- 用了什么框架 / 组件库？
|
||||
- 有没有视觉上的隐喻或主题（"Quiet Studio"、"Cockpit" 这种从命名能看出的世界观）？
|
||||
- 注释里有没有迭代痕迹？（"WCAG-tightened"、"bumped from X to Y"、"removed because..." 这种一看就是认真做过的人写的）
|
||||
- 圆角 / 间距是否一致？还是 4/8/16/20 各处散落？
|
||||
|
||||
### 然后判断这个项目处在哪个阶段
|
||||
|
||||
把项目放进下面五档之一。不同档位的开场方向不一样：
|
||||
|
||||
| 档 | 信号 | 后续走向 |
|
||||
|---|---|---|
|
||||
| **A. 空白** | Tailwind 默认配色，无自定义 token，没几个真组件 | 走完整的"找意象 → 选 token → 出业务设计稿"流程 |
|
||||
| **B. 半成品** | 有些 token 但分散，组件风格不一致，圆角散落 | 整理已有的 + 补全 |
|
||||
| **C. 成熟** | 完整 token + 一致命名 + 视觉隐喻 + 注释里能看到对比度审计 | 一句话承认现状，直接列五个来意分支让用户挑（见 Phase 1） |
|
||||
| **D. 复杂遗留** | 多套 token 并存、新旧混用、看不出主线 | 先走 `review` 模式做审计 |
|
||||
| **E. 不确定** | 扫完心里没底 | 描述看到的，问用户这套是想稳定还是想换方向 |
|
||||
|
||||
### 开口的两条原则
|
||||
|
||||
1. **用事实描述代替自我说明**。说项目是什么状态（"你这套已经定得挺清楚了"、"用的是 Tailwind 默认配色"），不说你打算怎么做（"我打算..."、"我接下来..."）。
|
||||
2. **默认不堆砌看代码的细节**。开口里不逐项罗列 5–8 个观察点。一句概括即可，用户问"看到了什么"再展开。
|
||||
|
||||
### 五档开口范例
|
||||
|
||||
**A 空白**：
|
||||
> 看了下，是新建的 Next + Tailwind 项目，用的是默认配色，组件还很少。在我开始问之前——你有没有什么已经定的，比如品牌色、字体、想致敬的产品？
|
||||
|
||||
**B 半成品**：
|
||||
> 看了下。token 在 globals.css 里定了一部分，但圆角在不同组件里有 4 / 8 / 12 三种写法。是想把现有的整理统一好，还是借这次换个方向？
|
||||
|
||||
**C 成熟**：
|
||||
> 你这套已经定得挺清楚了。叫我来 design 通常是这几件事里的一种：
|
||||
>
|
||||
> · 把现有 spec 跟代码核对一遍，修正失真的地方
|
||||
> · 拿一个真实业务页面做一版设计稿，看现在的 token 用上去顺不顺
|
||||
> · 推进 spec 里的 open questions
|
||||
> · 给还没设计过的新 surface 出一套规则
|
||||
> · 审计某一块（dashboard / form / dialog 等），列 P0/P1/P2
|
||||
>
|
||||
> 哪一个？或者别的也行。
|
||||
|
||||
**D 复杂遗留**：
|
||||
> 你的 token 在三个地方都有定义，圆角用过五六种值，shadcn 装了但有些组件没用、自己写了一套。在动手定新东西之前，建议先走一遍 review，按 P0/P1/P2 列清楚现状。要先 review 吗？
|
||||
|
||||
**E 不确定**：
|
||||
> 看了下，token 和组件都有，看着是有想法的；但有些命名让我猜不准你想往哪个方向走。这套现在是想稳定下来，还是想换个方向？
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: 根据来意分流
|
||||
|
||||
Phase 0 之后，用户的回答会把对话引向不同分支。**不要把所有项目都按 A 类的"找意象 → 选 token → 出 spec"硬走一遍**——那是只对 A 和 B 适用的剧本。
|
||||
|
||||
### 来意 1: 重定方向（换意象）
|
||||
信号：用户说"换个感觉"、"现在的太工程感了想温暖一点"、"不要 Linear 了想做个像 Notion 的"。
|
||||
做法：完整走 Phase 1b（听）→ Phase 2（找意象）→ Phase 3（选 token）→ Phase 4ab（预览 + 业务设计稿）→ Phase 5（输出）。**但要带着旧 spec 一起讨论**——明确告诉用户哪些旧 token 你打算保留、哪些打算换。
|
||||
|
||||
### 来意 2: 扩展现有体系
|
||||
信号：用户说"我们要新加一个 marketing landing"、"还没有空状态 / 错误页的设计"、"想把移动端补完"。
|
||||
做法：跳过 Phase 2（意象已经定了，沿用）。直接 Phase 3 在已有 token 上设计新 surface，Phase 4ab 渲染新增 surface 的预览和业务稿，Phase 5 把新增内容**追加**进 spec（不要覆盖）。
|
||||
|
||||
### 来意 3: 导出对外 spec
|
||||
信号：用户说"团队里默契是有的，但要给外包/新人一份独立的 spec"、"想沉淀文档"。
|
||||
做法：跳过 Phase 1b–4，直接做"翻译沉淀"：把项目里已有的 token + 隐喻 + 签名细节，按 `references/design-spec-template.md` 整理成完整 spec.html + spec.md。这一步做的是**记录**，不是发明。完成后让用户校对。
|
||||
|
||||
### 来意 4: 审计 + 微调
|
||||
信号：用户说"我觉得 dark 模式 muted 还是不够亮"、"sheet shadow 太重了"、"找你来挑刺"。
|
||||
做法：直接切到 `review` 模式。按 P0/P1/P2 出修复清单，可执行的代码片段附上。不走完整 design 流程。
|
||||
|
||||
### 来意 5: 其他
|
||||
用户说的不在上面。
|
||||
做法：复述你听到的，问"这是属于上面哪种，还是有别的"。**不要硬塞进上面四类**。
|
||||
|
||||
---
|
||||
|
||||
## Phase 1b: Listen（适用于来意 1 和 2）
|
||||
|
||||
The goal is to understand the project well enough to propose options later. Ask in this order, one question at a time, and keep follow-ups light. Skip any question whose answer was already given in Phase 0 or by the user upfront.
|
||||
|
||||
### Q1.1 — Product
|
||||
|
||||
> "In one sentence, what does this product do, and who is the primary user?"
|
||||
|
||||
Don't categorize them yet. Don't say "so this is a SaaS B2B dashboard, I recommend...". Just absorb.
|
||||
|
||||
### Q1.2 — Existing brand
|
||||
|
||||
> "Do you have any brand assets that are already fixed — a logo, brand color, brand fonts, a brand book?"
|
||||
|
||||
If yes → ask for the file or hex codes. These become non-negotiable inputs.
|
||||
If no → log "from scratch" and continue.
|
||||
|
||||
### Q1.3 — References (taste anchor)
|
||||
|
||||
> "Name 1–3 products whose UI you find pleasant to use, or whose look you'd be happy to be compared to. They don't need to be in your industry."
|
||||
|
||||
This is the single most useful question in the interview. References are concrete, low-effort to give, and reveal taste better than abstract adjectives.
|
||||
|
||||
If the user can't think of any → ask the inverse: "Any product whose look you actively dislike?"
|
||||
|
||||
If still nothing → **open the style-family compare preview** (`design-preview-template.html` in compare mode) showing 3–4 family samples and ask which is closest. This is the "show, don't ask" fallback.
|
||||
|
||||
### Q1.4 — Hard constraints
|
||||
|
||||
> "Anything I should know about — accessibility requirements, dark mode, mobile-first, internationalization, dense data tables, anything else that constrains the design?"
|
||||
|
||||
Common constraints to watch for:
|
||||
- WCAG AA/AAA → narrows color contrast options
|
||||
- Dark mode required → some palettes work better than others
|
||||
- High info density → spacious doesn't fit
|
||||
- Multilingual including CJK → font choice narrows
|
||||
- Embedded/iframe → can't dictate global background
|
||||
|
||||
### Q1.5 — Emotional register (only if user is engaged)
|
||||
|
||||
If the user is giving rich answers, ask one optional question:
|
||||
|
||||
> "When someone uses this product for the first time, what should they feel?"
|
||||
|
||||
Examples of useful answers: "in control", "respected", "curious", "calm", "fast", "in the right place". Translate these into style-family hints later — but don't over-extract. If the answer is "I dunno, just clean", leave it.
|
||||
|
||||
**Do not** ask the 5-axis spectrum questions (Shape / Density / Tone / Weight / Color) at this stage. Those decisions are downstream of the style family.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Style family
|
||||
|
||||
If the user already named a clear direction in Phase 1 (named references that all live in the same family, or said "I want it like Linear" outright) → confirm and move on:
|
||||
|
||||
> "Sounds like you're in the **modern-minimal** family — Linear, Vercel, Notion all live there. I'll start from those defaults; we can adjust anything you don't like. Sound right?"
|
||||
|
||||
If the user did not name a direction → present 2–4 family options as **neutral siblings**, no stars, no value labels. Use the compare preview to show them visually.
|
||||
|
||||
How to pick which 2–4 families to show:
|
||||
- Use Phase 1 references as the primary signal (group references by family).
|
||||
- Use Phase 1 emotional register as a secondary signal.
|
||||
- Drop families that are clearly inappropriate (don't show `tech-cyberpunk` for a children's app).
|
||||
|
||||
**Script template:**
|
||||
|
||||
> "I'll show you 3 directions on the same content so you can see them side by side. None of them is 'the right answer' — pick whichever feels closest, and we can adjust details inside it."
|
||||
|
||||
After the user picks a family, load that family's defaults from `style-families/<family>.md` as the starting point for Phase 3.
|
||||
|
||||
If the user picks none / says "show me more" → load 3 different families and re-present.
|
||||
|
||||
If the user wants to combine families ("the spacing of A but the colors of B") → that's fine. Honor it. Note the combination in the eventual `design-spec.md`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Visual choices
|
||||
|
||||
For each unknown token, present 2–3 options drawn from the chosen family. **No starred recommendations.** Open the compare preview if the user hesitates.
|
||||
|
||||
Token-by-token order (skip whatever Phase 0 / Phase 1 already fixed):
|
||||
|
||||
1. **Color palette** — primary + how to derive neutrals (tinted vs true gray) + semantic (success/warning/error/info).
|
||||
2. **Typography** — heading font, body font, optional mono font. The chosen family supplies a shortlist appropriate to that family. **If `locale.primary` is CJK or non-Latin, the shortlist must include locale-capable fonts** — Latin-only Plus Jakarta Sans on a Chinese product is a non-starter.
|
||||
3. **Radius scale** — sm / md / lg.
|
||||
4. **Spacing density** — compact / balanced / spacious.
|
||||
5. **Shadow / elevation** — flat / subtle / pronounced.
|
||||
6. **Motion vocabulary** — minimal / subtle / expressive.
|
||||
7. **Container strategy** — `border` / `tinted-surface` / `elevation` / `divider` / `none`. This is a real visual decision that distinguishes families. Don't skip. See `extended-dimensions.md`.
|
||||
8. **Icon system** — set + weight + treatment. See `extended-dimensions.md`.
|
||||
9. **Decoration policy** — gradients / textures / motifs, **per-surface** (e.g. marketing may go expressive while dashboard stays clean).
|
||||
10. **Locale** — primary + secondary supported locales. If not gathered in Phase 1, ask now. Affects font shortlist and Phase 4b mockup language.
|
||||
|
||||
For each: ask "Any preference, or want to see the options?" Default to opening the preview if the user has no preference — visual choice is faster than verbal.
|
||||
|
||||
When the user picks something off-family (e.g. picked `modern-minimal` but wants 16px radius, or picked `playful` but wants `containerStrategy: border`) → take it. Don't try to talk them back into the family default. Note the deviation in `design-spec.md` so the next contributor knows it's intentional.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4a: Generic preview & quick iteration
|
||||
|
||||
Open the full-mode static preview rendering the chosen tokens on **multiple surfaces** so the user can pressure-test token decisions without committing to business content yet.
|
||||
|
||||
Default surfaces in the preview (template supports a switcher):
|
||||
|
||||
- Dashboard (nav + stats + table + actions)
|
||||
- Marketing landing (hero + features + CTA band)
|
||||
- Content article (long-form text + figure + pull quote)
|
||||
- Form / settings (inputs + groups + submit)
|
||||
- Pricing (3-tier card layout)
|
||||
|
||||
The preview also has switchers for **container strategy**, **icon set**, **decoration**, **viewport** (desktop / tablet / mobile), **dark / light theme**, and **locale** (zh-CN / en / ja).
|
||||
|
||||
### Refinement questions (open, not leading)
|
||||
|
||||
Ask up to 3 of these per round, never more:
|
||||
|
||||
> "Anything feel off?"
|
||||
> "Is there a specific surface you want to pressure-test?"
|
||||
> "Anything you'd want darker / lighter / tighter / looser?"
|
||||
|
||||
Iterate by rewriting `/tmp/design-config.js` only — the user refreshes the browser. Don't regenerate the template HTML each time.
|
||||
|
||||
Phase 4a is for *exploration*, not for *final review*. Don't try to lock the spec here. When the tokens feel "roughly right" — even if a few details still bug the user — move to Phase 4b. The business mockup will surface issues this generic preview can't.
|
||||
|
||||
Stop Phase 4a when the user says "looks roughly right" or after 3 rounds of refinement, whichever comes first. If after 3 rounds the user still feels lost → the chosen family was probably wrong; offer to re-run Phase 2.
|
||||
|
||||
## Phase 4b: Business mockup (the real definition step)
|
||||
|
||||
This is the most important phase. The skill generates a **standalone HTML file** that renders the user's *actual product surface*, in *their language*, applying *every chosen token including containerStrategy / iconSystem / decoration*.
|
||||
|
||||
The user looks at *their own product*, makes the final ship/iterate decision, and only then does the spec get locked.
|
||||
|
||||
### Before generating, decide what to render
|
||||
|
||||
Re-read the user's Phase 1 inputs. The mockup needs:
|
||||
|
||||
1. **One or two core surfaces** — the user's primary daily-use page(s). Not settings, not the about page. If unclear, ask one focused question:
|
||||
> "Of all the screens in your product, which one would you say users spend the most time on? That's what I'll mock up first."
|
||||
2. **Realistic copy in `locale.primary`** — actual domain language ("待审核投放计划 12 条", not "Active campaigns 12"). Realistic demo data.
|
||||
3. **Real entity names and field names** — if it's a CRM, "客户名称 / 跟进阶段 / 下次联系时间", not "User / Status / Date".
|
||||
|
||||
If the user described an industry vertical (medical / advertising / education), use vocabulary native to that vertical. If unsure, ask.
|
||||
|
||||
### Generating the file
|
||||
|
||||
Generate to `/tmp/business-mockup-<n>.html` where `n` is the iteration number. Keep prior iterations on disk so the user can compare.
|
||||
|
||||
Follow `references/business-mockup-contract.md` strictly. The contract is non-negotiable; if you find yourself wanting to violate it ("I'll just use a different icon for this one place"), stop — the violation is signal that something in the spec is wrong. Iterate the spec, not the mockup.
|
||||
|
||||
### Open the file and ask
|
||||
|
||||
```bash
|
||||
open /tmp/business-mockup-1.html
|
||||
```
|
||||
|
||||
Then ask one question — open, not leading:
|
||||
|
||||
> "How does it feel? Anything you'd want to change before we lock the spec?"
|
||||
|
||||
### Iteration loop
|
||||
|
||||
Two kinds of feedback:
|
||||
|
||||
- **Token feedback** ("the cards are too tight", "the green is too lime") → re-run Phase 3 to adjust the relevant token, then regenerate the mockup as iteration `n+1`. Keep the previous file so the user can compare.
|
||||
- **Content / copy feedback** ("this isn't really what our list looks like", "we don't have a 'pause' state") → regenerate with the same tokens but better content. This is also a signal that you got the business surface wrong; revisit Phase 1 mentally before regenerating.
|
||||
|
||||
3 iterations is a usual maximum. If after 3 the user still isn't ready to lock, the issue is probably structural (wrong family, wrong primary surface choice) — name it and offer to back up to the relevant earlier phase.
|
||||
|
||||
### When the user is satisfied
|
||||
|
||||
Move to Phase 5. Do not lock the spec until the user has explicitly said the business mockup feels right. The mockup is the gating artifact.
|
||||
|
||||
### When to skip Phase 4b
|
||||
|
||||
- User explicitly says "skip the mockup, just write the spec".
|
||||
- The project is a multi-product design system, not a single product (no single business surface to mock).
|
||||
- The project is hypothetical and the user isn't ready to invent demo content.
|
||||
|
||||
In any of these, note it in `design-spec.md` so future contributors know the spec was not validated against a real surface.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Output
|
||||
|
||||
**Precondition**: Phase 4b's business mockup has been generated and the user has explicitly said it feels right. (Skip this precondition only if Phase 4b was deliberately skipped — and note that fact in the spec.)
|
||||
|
||||
Generate `design-spec.md` in the project root using `references/design-spec-template.md` as the structure. Make sure the spec includes:
|
||||
|
||||
- All sections from the template, including the new sections for **container strategy** (7a), **icon system** (7b), and **decoration policy** (7c).
|
||||
- The chosen `locale` in section 1.
|
||||
- Any deviations from the chosen style family's defaults, with one-line reasoning ("we picked 16px radius despite modern-minimal's 8px default because the brand wanted a softer feel").
|
||||
- Reference back to the business mockup: a small note at the bottom saying "Validated against `business-mockup-N.html` (latest iteration)".
|
||||
|
||||
Tell the user where the file was written and offer one follow-up:
|
||||
|
||||
> "Written to `design-spec.md`. Want me to also (a) generate a starter `tokens.css` / `tailwind.config` extension based on these tokens, or (b) review one specific page now using `review` mode against this spec?"
|
||||
|
||||
---
|
||||
|
||||
## Template usage (token-efficient)
|
||||
|
||||
The preview template HTML is static. Iterate by rewriting only the JSON config.
|
||||
|
||||
```bash
|
||||
# First time only — copy the template out of the skill
|
||||
cp <skill-path>/references/design-preview-template.html /tmp/design-preview.html
|
||||
```
|
||||
|
||||
**Compare mode** — for picking a style family or comparing 2–3 token sets:
|
||||
|
||||
```js
|
||||
window.__DESIGN_CONFIG__ = {
|
||||
mode: "compare",
|
||||
title: "Three directions on the same content",
|
||||
subtitle: "Pick whichever feels closest. Nothing is final.",
|
||||
options: [
|
||||
{
|
||||
label: "A",
|
||||
family: "modern-minimal",
|
||||
subtitle: "Linear / Vercel / Notion",
|
||||
colors: { primary: "...", primaryHover: "...", primarySubtle: "...",
|
||||
bg: "...", surface: "...", border: "...",
|
||||
text: "...", textSecondary: "...", textMuted: "...",
|
||||
success: "...", warning: "...", error: "...", info: "..." },
|
||||
fonts: { heading: "...", body: "..." },
|
||||
radius: { sm: "4px", md: "8px" }
|
||||
},
|
||||
{ label: "B", family: "...", subtitle: "...", colors: {...}, fonts: {...}, radius: {...} },
|
||||
{ label: "C", family: "...", subtitle: "...", colors: {...}, fonts: {...}, radius: {...} }
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
**Full mode** — for showing the full system on multiple surfaces:
|
||||
|
||||
```js
|
||||
window.__DESIGN_CONFIG__ = {
|
||||
mode: "full",
|
||||
name: "ProjectName",
|
||||
family: "modern-minimal",
|
||||
surfaces: ["dashboard", "marketing", "content", "form", "pricing"],
|
||||
defaultSurface: "dashboard",
|
||||
darkMode: false, // user can toggle in UI
|
||||
colors: { primary, primaryHover, primarySubtle, secondary,
|
||||
bg, surface, border, text, textSecondary, textMuted,
|
||||
success, warning, error, info,
|
||||
// optional dark mode overrides
|
||||
dark: { bg, surface, border, text, ... } },
|
||||
fonts: { heading: "...", body: "...", mono: "..." },
|
||||
radius: { sm, md, lg },
|
||||
shadows: { sm, md, lg },
|
||||
spacing: "compact" | "balanced" | "spacious",
|
||||
motion: "minimal" | "subtle" | "expressive"
|
||||
};
|
||||
```
|
||||
|
||||
```bash
|
||||
open /tmp/design-preview.html
|
||||
```
|
||||
|
||||
To iterate: rewrite `/tmp/design-config.js` only. The user refreshes.
|
||||
File diff suppressed because it is too large
Load Diff
97
.agents/skills/oiloil-ui-ux-guide/references/design-psych.md
Normal file
97
.agents/skills/oiloil-ui-ux-guide/references/design-psych.md
Normal file
@ -0,0 +1,97 @@
|
||||
# Design Psychology (inspired by *The Design of Everyday Things*)
|
||||
|
||||
Keep this as a compact reference. Use it when explaining *why* a design is confusing and how to fix it.
|
||||
This is a paraphrased summary, not a verbatim excerpt.
|
||||
|
||||
## Affordances (示能性 / 可供性)
|
||||
|
||||
- An affordance is what an object *allows* a person to do.
|
||||
- In UI, you mostly manage **perceived affordances**: what people *think* they can do.
|
||||
|
||||
Practical rule:
|
||||
- If an action is important, it must be discoverable without hover, tooltips, or prior training.
|
||||
|
||||
## Signifiers (指示符)
|
||||
|
||||
- Signifiers are the cues that indicate possible actions.
|
||||
|
||||
Examples in UI:
|
||||
- Button shape, link styling, icons + labels, hover/focus states, cursor changes, microcopy.
|
||||
|
||||
Practical rule:
|
||||
- Use the smallest signifier that removes ambiguity. Default to labels for non-obvious actions.
|
||||
|
||||
## Mapping (映射) / Natural mapping
|
||||
|
||||
- Mapping is the relationship between controls and their effects.
|
||||
- Natural mapping means the layout/relationship mirrors the real-world mental model.
|
||||
|
||||
Practical rules:
|
||||
- Put controls near what they control.
|
||||
- Use spatial grouping to show what belongs together.
|
||||
- For multi-part objects, align actions with the part they affect (per-item actions next to the item).
|
||||
|
||||
## Constraints (约束)
|
||||
|
||||
- Constraints limit possible actions, preventing errors and reducing thinking.
|
||||
|
||||
Types you can use in UI:
|
||||
- Physical constraints (not literal in UI, but you can simulate via disabled states)
|
||||
- Logical constraints (only valid combinations are allowed)
|
||||
- Semantic constraints (meaning-based limits)
|
||||
- Cultural constraints (conventions users expect)
|
||||
|
||||
Practical rules:
|
||||
- Prefer constraints + defaults over warnings.
|
||||
- If you must block an action, explain the requirement and provide a path to satisfy it.
|
||||
|
||||
## Conceptual model (概念模型)
|
||||
|
||||
- Users form an internal model of how the system works.
|
||||
- Your UI should make the correct model obvious.
|
||||
|
||||
Practical rules:
|
||||
- Use consistent nouns/labels for objects.
|
||||
- Use consistent verbs for actions.
|
||||
- Show cause-effect clearly (do X -> see Y change).
|
||||
|
||||
## Feedback (反馈)
|
||||
|
||||
- Feedback tells people what happened after an action.
|
||||
|
||||
Practical rules:
|
||||
- Always provide immediate feedback for interaction (press/hover/loading).
|
||||
- If an operation takes time, show progress or a clear waiting state.
|
||||
- After success/failure, clearly state the outcome and the next step.
|
||||
|
||||
## Gulfs of execution & evaluation (执行鸿沟 / 评估鸿沟)
|
||||
|
||||
- Execution gulf: user can’t figure out how to do what they want.
|
||||
- Evaluation gulf: user can’t tell what happened or what state the system is in.
|
||||
|
||||
Practical diagnostic:
|
||||
- If users hesitate before acting: reduce execution gulf (clear CTA, clearer signifiers, simpler choices).
|
||||
- If users repeat actions / rage-click: reduce evaluation gulf (loading, disabled, progress, clearer results).
|
||||
|
||||
## Slips vs mistakes (失误 vs 错误)
|
||||
|
||||
- Slip: the goal is correct, the action execution goes wrong (fat-finger, wrong click).
|
||||
- Mistake: the mental model/goal is wrong (user thinks it works differently).
|
||||
|
||||
Practical rules:
|
||||
- Slips: add undo, confirmations for destructive actions, safer hit targets, better spacing.
|
||||
- Mistakes: fix labeling, mapping, and conceptual model; add just-enough explanation.
|
||||
|
||||
## Knowledge in the world vs in the head (外部知识 vs 头脑知识)
|
||||
|
||||
- Good design puts knowledge in the world: visible options, clear labels, previews, examples.
|
||||
|
||||
Practical rule:
|
||||
- Don’t force users to remember constraints. Surface them at the point of decision.
|
||||
|
||||
## Modes (模式) and mode errors
|
||||
|
||||
- Modes mean the same action produces different results depending on state.
|
||||
|
||||
Practical rule:
|
||||
- Avoid modes; if unavoidable, make mode state extremely visible and easy to exit.
|
||||
@ -0,0 +1,173 @@
|
||||
# `design-spec.md` Output Template
|
||||
|
||||
Use this structure when generating the final `design-spec.md` in the user's project root. Fill every section with concrete values, not placeholders.
|
||||
|
||||
```markdown
|
||||
# [Project Name] Design Specification
|
||||
|
||||
> Generated from a `design` consultation with `oiloil-ui-ux-guide`.
|
||||
> Style family: `<family>` (or `brand-driven`).
|
||||
|
||||
## 1. Design direction
|
||||
|
||||
- **Product**: [one sentence — what it does, who uses it]
|
||||
- **Style family**: `<family>`. [If hybrid, e.g. "modern-minimal layout, editorial typography", say so.]
|
||||
- **References**: [products the user named in Phase 1]
|
||||
- **Tone**: [3 descriptors the user landed on, or N/A]
|
||||
- **Hard constraints**: [accessibility, dark mode, mobile-first, i18n, etc.]
|
||||
- **Locale**: primary `[zh-CN | en | ja | ...]`, secondary `[…]`
|
||||
|
||||
## 2. Color
|
||||
|
||||
### Brand
|
||||
- `--color-primary`: `#xxxxxx` — usage notes
|
||||
- `--color-primary-hover`: `#xxxxxx`
|
||||
- `--color-primary-subtle`: `#xxxxxx` (background tint, ~5–10% alpha or +90% lightness)
|
||||
- `--color-secondary`: `#xxxxxx` (omit if not used)
|
||||
|
||||
### Neutrals (tinted toward [hue or "true gray"])
|
||||
- `--color-bg`: `#xxxxxx`
|
||||
- `--color-surface`: `#xxxxxx`
|
||||
- `--color-border`: `#xxxxxx`
|
||||
- `--color-text`: `#xxxxxx`
|
||||
- `--color-text-secondary`: `#xxxxxx`
|
||||
- `--color-text-muted`: `#xxxxxx`
|
||||
|
||||
### Semantic
|
||||
- `--color-success`: `#xxxxxx`
|
||||
- `--color-warning`: `#xxxxxx`
|
||||
- `--color-error`: `#xxxxxx`
|
||||
- `--color-info`: `#xxxxxx`
|
||||
|
||||
### Dark mode (if shipping)
|
||||
- Override block for the above neutrals + any color that needs adjustment.
|
||||
|
||||
## 3. Typography
|
||||
|
||||
| Role | Font | Weights | Source |
|
||||
|---|---|---|---|
|
||||
| Heading | [name] | [list] | [Google Fonts / Adobe / self-host] |
|
||||
| Body | [name] | [list] | [source] |
|
||||
| Mono | [name] | [list] | [source] |
|
||||
|
||||
### Type scale (px)
|
||||
12 / 14 / 16 / 18 / 20 / 24 / 32 / 40 / 48 / 64 — *or whatever scale the project chose*
|
||||
|
||||
### Body measure
|
||||
- Target: [60–75 chars per line for editorial, 50–65 for app body]
|
||||
- Line-height: [1.4 for UI, 1.6+ for long-form]
|
||||
|
||||
## 4. Spacing
|
||||
|
||||
- Base unit: `4px` *(or `8px` if applicable)*
|
||||
- Allowed scale: `4 / 8 / 12 / 16 / 24 / 32 / 48 / 64`
|
||||
- Density: `compact` | `balanced` | `spacious`
|
||||
- Off-scale spacing requires justification in code comments.
|
||||
|
||||
## 5. Radius
|
||||
|
||||
- `--radius-sm`: `Xpx`
|
||||
- `--radius-md`: `Xpx`
|
||||
- `--radius-lg`: `Xpx`
|
||||
- `--radius-full`: `9999px` (chips, avatars only)
|
||||
|
||||
## 6. Elevation / shadow
|
||||
|
||||
- `--shadow-sm`: `[box-shadow value]`
|
||||
- `--shadow-md`: `[box-shadow value]`
|
||||
- `--shadow-lg`: `[box-shadow value]`
|
||||
- Or note "flat — use borders only" if family is shadow-less.
|
||||
|
||||
## 7. Motion
|
||||
|
||||
- Vocabulary: `minimal` | `subtle` | `expressive`
|
||||
- Default duration: `Xms` for micro, `Xms` for state change, `Xms` for overlays
|
||||
- Easing: `[curve]`
|
||||
- Allowed motion patterns: [list — e.g. fade, translate+fade, scale+fade for overlays]
|
||||
- Forbidden (in this project): [list — e.g. bounce, parallax]
|
||||
|
||||
## 7a. Container strategy
|
||||
|
||||
How container boundaries are expressed in this project. See `references/extended-dimensions.md` for definitions.
|
||||
|
||||
- **Strategy**: `border` | `tinted-surface` | `elevation` | `divider` | `none`
|
||||
- **Per-surface overrides** (if any):
|
||||
- dashboard: `[strategy]`
|
||||
- marketing: `[strategy]`
|
||||
- form / settings: `[strategy]`
|
||||
- long-form content: `[strategy]`
|
||||
- Notes on implementation specifics — e.g. for `tinted-surface`: surface is `[hex]` against bg `[hex]` (a `[X]%` lightness offset). For `elevation`: `--shadow-md` is the default container shadow, `--shadow-lg` for modals only.
|
||||
|
||||
## 7b. Icon system
|
||||
|
||||
- **Set**: `lucide` | `phosphor` | `heroicons` | `carbon` | `tabler` | `material` | `brand-custom`
|
||||
- **Weight**: `thin` | `regular` | `bold` | `filled` (set-dependent)
|
||||
- **Treatment**: `monochrome` | `two-tone` | `brand-tinted`
|
||||
- **Sizes**: `16 / 20 / 24 px` baseline; `32 / 48 px` for empty states
|
||||
- **Primary use color**: `currentColor` (inherits text) | `--color-primary` | `--color-text-muted`
|
||||
- **Mixing**: do not mix sets within this project. If a needed icon is missing in the set, [decision: substitute closest / commission custom / omit].
|
||||
|
||||
## 7c. Decoration
|
||||
|
||||
Per-surface decoration policy. Each surface specifies what's allowed; surfaces not listed default to `none / none / none`.
|
||||
|
||||
| Surface | Gradients | Textures | Motifs |
|
||||
|---|---|---|---|
|
||||
| Marketing hero | `none / subtle / expressive` | `none / noise / dot-grid / paper / scan-lines` | `none / geometric / illustration / photography / data-viz` |
|
||||
| Dashboard | … | … | … |
|
||||
| Form / settings | … | … | … |
|
||||
| Long-form content | … | … | … |
|
||||
|
||||
Notes:
|
||||
- For `gradients = subtle`: max 1 per page, and only on [hero bg / accent button / card highlight].
|
||||
- For `textures`: implementation note (SVG noise filter, CSS background pattern, image asset).
|
||||
- For `motifs = illustration`: which library / style. For `photography`: cropping rules, treatment.
|
||||
|
||||
## 8. Component conventions
|
||||
|
||||
### Buttons
|
||||
- Primary: `[background, text color, padding, radius]`
|
||||
- Secondary: `[…]`
|
||||
- Ghost: `[…]`
|
||||
- Destructive: `[…]`
|
||||
- Sizes: `sm / md / lg` with concrete pixel values
|
||||
|
||||
### Inputs
|
||||
- Default state, focus ring, error state, disabled state — concrete values
|
||||
|
||||
### Cards
|
||||
- When to use cards (only for actually-grouped content)
|
||||
- Padding, radius, border vs shadow choice
|
||||
|
||||
### Icons
|
||||
- See section 7b above. (Section 8 only documents per-component icon usage exceptions, if any.)
|
||||
|
||||
## 9. Surfaces (templates)
|
||||
|
||||
For each surface the project actually has, define how the tokens apply:
|
||||
|
||||
- **Dashboard**: [layout grid, card vs whitespace, density]
|
||||
- **Marketing landing**: [hero treatment, section rhythm]
|
||||
- **Form / settings**: [grouping, label position, validation timing]
|
||||
- **Long-form content**: [measure, figure treatment, pull-quote style] (if applicable)
|
||||
|
||||
## 10. Anti-patterns for this project
|
||||
|
||||
Specific things to avoid in *this* project, drawn from the chosen style family. Be concrete:
|
||||
|
||||
- e.g. "No 3-column equal-grid landing pages with stock photos."
|
||||
- e.g. "Cards never nested. If you need to group inside a card, use spacing or a divider."
|
||||
- e.g. "Body copy never on saturated brand background."
|
||||
|
||||
## 11. Open questions
|
||||
|
||||
If any decision was deferred during the consultation, list it here so the next contributor knows it's open, not omitted.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes for the AI generating this spec
|
||||
|
||||
- Fill every value. If a section doesn't apply, write "N/A — [reason]" rather than removing the section.
|
||||
- Keep the file < 500 lines. If a section is bloating, extract to a sibling file (e.g. `design-spec-components.md`).
|
||||
- After writing the file, tell the user the path and offer one follow-up (generate `tokens.css`, run `review` mode against an existing page, etc.).
|
||||
@ -0,0 +1,207 @@
|
||||
# Extended Token Dimensions
|
||||
|
||||
The original token model (`color` / `font` / `radius` / `spacing` / `shadow` / `motion`) is enough to describe a *sterile* design system. To capture the things that actually distinguish style families from each other in real product UI, the spec also tracks four additional dimensions:
|
||||
|
||||
1. `containerStrategy` — how container boundaries are expressed
|
||||
2. `iconSystem` — which icon set, weight, and treatment
|
||||
3. `decoration` — gradients, textures, motifs (mostly for marketing and hero surfaces)
|
||||
4. `locale` — primary language + secondary supported languages
|
||||
|
||||
Each of these is a real visual decision. Skipping them is the reason the original preview template made `modern-minimal` and `warm-content` look identical when rendered.
|
||||
|
||||
---
|
||||
|
||||
## 1. `containerStrategy`
|
||||
|
||||
How do containers (cards, panels, list rows, sections) visually separate from each other?
|
||||
|
||||
| Value | What it means | Implications |
|
||||
|---|---|---|
|
||||
| `border` | 1px borders around containers, often with a slight surface tint | The default of most SaaS UI. Reads as "designed system". |
|
||||
| `tinted-surface` | Container surface color is offset from page bg (lighter or darker), no border | iOS 14+ Health, many fintech apps. Feels softer, more depth. |
|
||||
| `elevation` | No border. Soft shadow does the work. | Material, macOS. Reads as physical, "objects on a desk". |
|
||||
| `divider` | Containers don't have visible boundaries; horizontal/vertical dividers separate sections within | Editorial, list-heavy interfaces. Quiet. |
|
||||
| `none` | Pure spacing and typography do the grouping work | Brutalist, manifesto pages, `premium-luxury` heroes. |
|
||||
|
||||
A project may pick one strategy globally and override per-surface (e.g. `tinted-surface` everywhere except dashboard tables which use `divider`).
|
||||
|
||||
## 2. `iconSystem`
|
||||
|
||||
```yaml
|
||||
iconSystem:
|
||||
set: lucide | phosphor | heroicons | carbon | tabler | material | brand-custom
|
||||
weight: thin | regular | bold | filled # set-dependent
|
||||
treatment: monochrome | two-tone | brand-tinted
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `lucide` — the modern default; clean, monoline, regular weight. Works in almost any family.
|
||||
- `phosphor` — has 6 weights; great for `playful` (bold/filled) and `editorial` (thin/regular).
|
||||
- `heroicons` — Tailwind ecosystem; outline + solid. Solid is heavier; pick on purpose.
|
||||
- `carbon` — IBM design system. Reads enterprise.
|
||||
- `tabler` — close to lucide visually but with more variety. Good for dense `tech-cyberpunk` UI.
|
||||
- `material` — Google. Carries Material's voice; usually only correct for Android-leaning products.
|
||||
- `brand-custom` — when the brand has a proprietary set; default for established brands.
|
||||
|
||||
The `treatment` matters more than people think:
|
||||
- `monochrome` — single color (usually text color or muted), recedes.
|
||||
- `two-tone` — accent + neutral, draws attention. Often `playful` / `warm-content`.
|
||||
- `brand-tinted` — uses primary at a lower alpha. Works in `modern-minimal` and `tech-cyberpunk`.
|
||||
|
||||
## 3. `decoration`
|
||||
|
||||
```yaml
|
||||
decoration:
|
||||
gradients: none | subtle | expressive
|
||||
textures: none | noise | dot-grid | paper | scan-lines
|
||||
motifs: none | geometric | illustration | photography | data-viz
|
||||
```
|
||||
|
||||
Definitions:
|
||||
|
||||
- `gradients`
|
||||
- `none` — no decorative gradients. Solid color blocks only.
|
||||
- `subtle` — at most one gradient per page (typically hero background or a single accent button).
|
||||
- `expressive` — gradients are part of the visual language (multiple per page, animated where appropriate).
|
||||
- `textures`
|
||||
- `noise` — film grain / noise overlay; widely used in `playful` and `brutal`.
|
||||
- `dot-grid` — engineering / blueprint feel; common in `tech-cyberpunk`.
|
||||
- `paper` — warm canvas texture; `warm-content`, `editorial`, `premium-luxury`.
|
||||
- `scan-lines` — CRT / terminal aesthetic; only `tech-cyberpunk` and very deliberate brutalism.
|
||||
- `motifs` — what's the secondary visual language alongside copy?
|
||||
- `geometric` — abstract shapes (circles, blobs, strokes) used as decoration.
|
||||
- `illustration` — characters / scenes; in family for `playful` and `warm-content`.
|
||||
- `photography` — used heavily in `premium-luxury`, `editorial`, `warm-content`.
|
||||
- `data-viz` — charts / sparklines as decoration; `tech-cyberpunk`, `modern-minimal` SaaS.
|
||||
|
||||
Decoration is **per-surface**: marketing pages may go `expressive + illustration`, while the dashboard stays `none / none / data-viz`.
|
||||
|
||||
## 4. `locale`
|
||||
|
||||
```yaml
|
||||
locale:
|
||||
primary: zh-CN | zh-TW | en | ja | ko | ...
|
||||
secondary: [list of supported locales]
|
||||
```
|
||||
|
||||
Why this is a token decision, not a runtime concern:
|
||||
|
||||
- **Font shortlist depends on language.** Plus Jakarta Sans is great for Latin; for `zh-CN` you need a CJK-capable font (Noto Sans SC, Source Han Sans, PingFang fallback). For `ja` add Noto Sans JP / Hiragino. The skill should propose locale-appropriate fonts in Phase 3, not generic Latin-only candidates.
|
||||
- **Line-height and font-size baselines differ.** CJK body needs larger line-height (1.7+) to be comfortable; Latin can do 1.5. Hard-coding 1.5 leaves CJK text feeling cramped.
|
||||
- **Letter-spacing.** Negative letter-spacing on display headings looks great in Latin and bad in CJK.
|
||||
- **Demo content.** A user looking at an English `Active users 2,847` dashboard cannot judge how their actual Chinese product will feel. The preview must render in the project's primary language.
|
||||
|
||||
When `secondary` is non-empty, the chosen body font must support all listed scripts (or the spec must define a font fallback stack).
|
||||
|
||||
---
|
||||
|
||||
## Per-family defaults
|
||||
|
||||
Each style family has a default *starting point* across the four extended dimensions. The user can always override.
|
||||
|
||||
### `modern-minimal`
|
||||
| Dim | Default | Compatible alternatives |
|
||||
|---|---|---|
|
||||
| containerStrategy | `border` | `tinted-surface`, `divider` |
|
||||
| iconSystem | `lucide` regular monochrome | `tabler`, `heroicons` |
|
||||
| decoration.gradients | `none` | `subtle` (hero only) |
|
||||
| decoration.textures | `none` | `dot-grid` (engineering brand) |
|
||||
| decoration.motifs | `data-viz` (dashboard) / `geometric` (marketing) | — |
|
||||
| locale | as project | — |
|
||||
|
||||
### `editorial`
|
||||
| Dim | Default | Compatible alternatives |
|
||||
|---|---|---|
|
||||
| containerStrategy | `divider` or `none` | `border` (only for code blocks / sidebars) |
|
||||
| iconSystem | `phosphor` thin or regular monochrome | `lucide` |
|
||||
| decoration.gradients | `none` | — |
|
||||
| decoration.textures | `paper` | `none` |
|
||||
| decoration.motifs | `photography` | `illustration` (for cover art) |
|
||||
| locale | as project; serif body fonts must support locale | — |
|
||||
|
||||
### `brutal`
|
||||
| Dim | Default | Compatible alternatives |
|
||||
|---|---|---|
|
||||
| containerStrategy | `border` (thick, 2-4px) | `none` |
|
||||
| iconSystem | `brand-custom` ASCII / Unicode glyphs | `tabler` bold, system emoji ironically |
|
||||
| decoration.gradients | `none` (use color blocks) | — |
|
||||
| decoration.textures | `noise` or `paper` | `scan-lines` |
|
||||
| decoration.motifs | `geometric` (raw shapes) | — |
|
||||
| locale | locale-agnostic; mono fonts must support locale | — |
|
||||
|
||||
### `playful`
|
||||
| Dim | Default | Compatible alternatives |
|
||||
|---|---|---|
|
||||
| containerStrategy | `tinted-surface` or `elevation` | `border` (thin, soft color) |
|
||||
| iconSystem | `phosphor` bold or filled, `two-tone` | `heroicons` solid |
|
||||
| decoration.gradients | `expressive` | `subtle` |
|
||||
| decoration.textures | `noise` | `paper` |
|
||||
| decoration.motifs | `illustration` | `geometric` |
|
||||
| locale | leans toward rounded fonts in any locale (Nunito ZH, Noto Sans Rounded, etc.) | — |
|
||||
|
||||
### `premium-luxury`
|
||||
| Dim | Default | Compatible alternatives |
|
||||
|---|---|---|
|
||||
| containerStrategy | `none` or `divider` | — |
|
||||
| iconSystem | optional; `phosphor` thin monochrome if used; `brand-custom` preferred | — |
|
||||
| decoration.gradients | `none` | `subtle` (very dark/very light) |
|
||||
| decoration.textures | `paper` or `none` | metallic foil (rare) |
|
||||
| decoration.motifs | `photography` (full-bleed editorial) | `none` |
|
||||
| locale | serif body; for CJK, prefer Source Han Serif / Songti family | — |
|
||||
|
||||
### `tech-cyberpunk`
|
||||
| Dim | Default | Compatible alternatives |
|
||||
|---|---|---|
|
||||
| containerStrategy | `tinted-surface` (dark) | `elevation` (with glow not shadow) |
|
||||
| iconSystem | `tabler` or `carbon` monochrome | `lucide` |
|
||||
| decoration.gradients | `subtle` (mesh / neon glow) | `expressive` (deliberate, neon) |
|
||||
| decoration.textures | `dot-grid` or `scan-lines` | `noise` (film-grain) |
|
||||
| decoration.motifs | `data-viz` | `geometric` (terminal glyphs) |
|
||||
| locale | mono fonts must support locale; for CJK: JetBrains Mono + Noto Sans Mono CJK | — |
|
||||
|
||||
### `warm-content`
|
||||
| Dim | Default | Compatible alternatives |
|
||||
|---|---|---|
|
||||
| containerStrategy | `tinted-surface` | `border` (warm gray, very low contrast) |
|
||||
| iconSystem | `phosphor` regular `two-tone` | `lucide` |
|
||||
| decoration.gradients | `none` | — |
|
||||
| decoration.textures | `paper` | `none` |
|
||||
| decoration.motifs | `illustration` | `photography` |
|
||||
| locale | warm serif body; CJK: Source Han Serif / Noto Serif CJK | — |
|
||||
|
||||
### `brand-driven`
|
||||
All four dimensions derive from brand assets:
|
||||
- `containerStrategy` — read from existing brand UI; if brand has cards-with-shadows, use `elevation`; if brand never uses borders, use `none`. Look at the brand site's UI patterns.
|
||||
- `iconSystem` — `brand-custom` if the brand has a set; otherwise pick a neutral one (`lucide`) and document the choice.
|
||||
- `decoration` — extract from brand collateral. If brand uses noise overlay everywhere, use `noise`. If brand never uses gradients, set `none`.
|
||||
- `locale` — primary = brand's primary market language. Secondary = whatever the brand publishes in.
|
||||
|
||||
If the brand has not made these decisions explicitly, **the consultant's job is to make them and write them into `design-spec.md` so the brand book is extended, not replaced**.
|
||||
|
||||
---
|
||||
|
||||
## How these dimensions feed into the preview template
|
||||
|
||||
When `design-config.js` is written for the preview template:
|
||||
|
||||
```js
|
||||
window.__DESIGN_CONFIG__ = {
|
||||
mode: "full",
|
||||
// ... existing fields ...
|
||||
containerStrategy: "tinted-surface",
|
||||
iconSystem: { set: "phosphor", weight: "regular", treatment: "two-tone" },
|
||||
decoration: {
|
||||
gradients: "subtle",
|
||||
textures: "paper",
|
||||
motifs: "illustration"
|
||||
},
|
||||
locale: { primary: "zh-CN", secondary: [] }
|
||||
};
|
||||
```
|
||||
|
||||
The template (Commit 2) provides switchers for each so the user can A/B inside one config without rewriting it.
|
||||
|
||||
## How these dimensions feed into the business mockup
|
||||
|
||||
The Phase 4b business mockup MUST honor every one of these dimensions. See `references/business-mockup-contract.md`.
|
||||
41
.agents/skills/oiloil-ui-ux-guide/references/icons.md
Normal file
41
.agents/skills/oiloil-ui-ux-guide/references/icons.md
Normal file
@ -0,0 +1,41 @@
|
||||
# Icons (No Emoji, Modern Minimal)
|
||||
|
||||
## Hard rules
|
||||
|
||||
- Do not use emoji as icons (or decoration).
|
||||
- Use one icon family across the product. Do not mix outlined/filled/3D/emoji styles.
|
||||
- Prefer obvious meanings over clever metaphors. If an icon can be misunderstood, add a text label.
|
||||
|
||||
## “Intuitive + refined” checklist
|
||||
|
||||
- **Style consistency**: same stroke weight (outline) or same fill style (filled).
|
||||
- **Sizes**: standardize on 16/20/24 (or your system sizes); avoid random sizes per screen.
|
||||
- **Optical alignment**: align visually (icon bounding boxes lie; nudge when needed).
|
||||
- **Touch targets**: icon buttons still need adequate hit area; do not shrink interactive area to the glyph.
|
||||
- **Labels**: primary actions should be text or text+icon; icon-only is reserved for universally-known actions.
|
||||
- **Tooltips**: tooltips are support, not the primary way to understand an action.
|
||||
|
||||
## Prefer text over icons when
|
||||
|
||||
- The action is uncommon in your product.
|
||||
- The icon is domain-specific (users won’t share the same mental model).
|
||||
- The action is destructive or high-stakes (use explicit wording).
|
||||
|
||||
## Suggested icon sets (pick one; do not mix)
|
||||
|
||||
- Lucide / Feather-style outline icons (web-friendly)
|
||||
- Material Symbols (outlined or rounded; pick one)
|
||||
- SF Symbols (Apple platforms)
|
||||
|
||||
## Common mappings (use cautiously)
|
||||
|
||||
- Search: magnifier
|
||||
- Filter: funnel
|
||||
- Settings: gear
|
||||
- More actions: kebab (vertical three dots)
|
||||
- Close: x
|
||||
- Back: left arrow
|
||||
- Info: i in circle (use sparingly; don’t turn UI into a tooltip museum)
|
||||
|
||||
If an icon is not instantly clear, prefer a short label instead of inventing a new icon metaphor.
|
||||
|
||||
@ -0,0 +1,164 @@
|
||||
# Interaction Psychology (HCI Laws, Cognitive Biases, Flow)
|
||||
|
||||
Compact reference for review and design guidance.
|
||||
Complements `design-psych.md` (Norman's conceptual model) with empirically-grounded laws and biases that directly inform design decisions.
|
||||
|
||||
## A) Classic HCI Laws
|
||||
|
||||
### Fitts's Law (费茨定律)
|
||||
|
||||
- Core idea: the time to reach a target is a function of target size and distance.
|
||||
- Larger and closer targets are faster and easier to hit.
|
||||
|
||||
Practical rules:
|
||||
- Primary CTA: make it the largest interactive element in its section and place it near the user's visual focus.
|
||||
- Destructive actions: keep them small and spatially separated from the primary CTA to prevent slips.
|
||||
- Touch targets: minimum 44×44 CSS px (web) / 48×48 dp (mobile); don't shrink hit area to the glyph.
|
||||
- Edges and corners of the viewport are effectively infinite-size targets (screen edge stops the cursor) — use them for key navigation (e.g., fixed top nav, bottom tab bar).
|
||||
|
||||
Review question: Is the primary action button large enough and close to the user's focus? Are destructive actions physically separated from routine actions?
|
||||
|
||||
### Hick's Law (希克定律)
|
||||
|
||||
- Core idea: decision time increases logarithmically with the number of choices.
|
||||
- More options → slower decisions → higher abandonment.
|
||||
|
||||
Practical rules:
|
||||
- Limit visible choices: if a list/menu exceeds ~7 items, add grouping, search, or filtering.
|
||||
- Use smart defaults to eliminate decisions entirely (the best choice is no choice).
|
||||
- Progressive disclosure: show basic options first, reveal advanced options on demand.
|
||||
- Avoid "paradox of choice" in onboarding: guide users through a recommended path instead of presenting all features at once.
|
||||
|
||||
Review question: Is the user facing too many options at once? Can grouping, search, or defaults reduce the decision burden?
|
||||
|
||||
### Miller's Law (米勒定律)
|
||||
|
||||
- Core idea: working memory holds roughly 7 ± 2 items.
|
||||
- Exceeding this limit causes cognitive overload and errors.
|
||||
|
||||
Practical rules:
|
||||
- Navigation / tab bars: keep to ≤ 7 top-level items; use grouping or "more" for the rest.
|
||||
- Long forms: chunk fields into labeled groups (≤ 5–7 fields per group).
|
||||
- Information display: break long lists into scannable sections with headings.
|
||||
- Don't force users to remember information across screens — carry context forward.
|
||||
|
||||
Review question: Does a single screen require the user to hold more than 7 independent pieces of information in mind?
|
||||
|
||||
---
|
||||
|
||||
## B) Cognitive Biases in UI Design
|
||||
|
||||
### Anchoring Effect (锚定效应)
|
||||
|
||||
- Users are influenced by the first piece of information they see.
|
||||
- The first number, option, or example sets a reference point for all subsequent judgments.
|
||||
|
||||
Practical rules:
|
||||
- Pricing pages: show the recommended plan first (or in the center); it becomes the anchor.
|
||||
- Form defaults: the pre-filled value becomes the user's baseline — choose it carefully.
|
||||
- Progress indicators: showing "step 2 of 3" anchors the user's effort expectation.
|
||||
|
||||
### Default Effect (默认效应)
|
||||
|
||||
- Users disproportionately stick with the default option.
|
||||
- Defaults are the most powerful design decision you can make.
|
||||
|
||||
Practical rules:
|
||||
- Set defaults to the safest and most common choice.
|
||||
- Never use defaults to trick users into unfavorable choices (dark pattern).
|
||||
- When there is no safe default, force an explicit choice instead of pre-selecting.
|
||||
|
||||
### Peak-End Rule (峰终定律)
|
||||
|
||||
- Users judge an experience primarily by its most intense moment and its ending.
|
||||
- A painful middle is forgiven if the peak and end are positive.
|
||||
|
||||
Practical rules:
|
||||
- Invest in the completion/success screen — it's the last impression.
|
||||
- Error recovery experience matters more than error prevention messaging for overall satisfaction.
|
||||
- Celebrate meaningful milestones (first project created, first successful deploy).
|
||||
|
||||
### Loss Aversion (损失厌恶)
|
||||
|
||||
- The pain of losing something is ~2× stronger than the pleasure of gaining the same thing.
|
||||
- Users are more motivated to avoid loss than to achieve gain.
|
||||
|
||||
Practical rules:
|
||||
- Destructive actions: frame confirmation around what will be lost ("You will lose 12 files"), not just the action ("Confirm delete").
|
||||
- Trial expiration: "Your data will be deleted in 3 days" is more motivating than "Upgrade to keep your data."
|
||||
- Unsaved changes: warn clearly before navigation away; show exactly what will be lost.
|
||||
|
||||
### Inattentional Blindness (注意力盲区)
|
||||
|
||||
- When focused on a task, users fail to notice information outside their attention focus.
|
||||
- Important alerts placed far from the user's current focus are effectively invisible.
|
||||
|
||||
Practical rules:
|
||||
- Place critical feedback near the user's point of action (inline validation, not page-top banners).
|
||||
- Don't rely on peripheral notifications for urgent information during focused tasks.
|
||||
- If you must interrupt, use the user's current focus area (inline message or modal), not a distant toast.
|
||||
|
||||
---
|
||||
|
||||
## C) Interaction Flow & Rhythm
|
||||
|
||||
### Interruption Cost (中断成本)
|
||||
|
||||
- Every interruption (modal, page redirect, loading spinner) has a cognitive recovery cost.
|
||||
- Users need time to re-orient after each interruption, and some never return.
|
||||
|
||||
Practical rules:
|
||||
- Prefer inline interactions over modals; prefer modals over page redirects.
|
||||
- If a sub-task can be completed in the current context, don't navigate away.
|
||||
- Batch confirmations: one confirmation for a batch operation, not one per item.
|
||||
|
||||
Review question: How many page jumps or modal interruptions does it take to complete the primary task?
|
||||
|
||||
### Action Momentum (操作动量)
|
||||
|
||||
- Users build rhythm during sequential operations; design should sustain, not break, this rhythm.
|
||||
- Unexpected pauses or confirmations in the middle of a flow feel jarring.
|
||||
|
||||
Practical rules:
|
||||
- In batch/sequential workflows, don't require confirmation at every step.
|
||||
- Tab order between form fields should follow the natural reading/input sequence.
|
||||
- Auto-advance where appropriate (e.g., after selecting from a dropdown, focus moves to the next field).
|
||||
|
||||
### Reversibility Principle (可逆性原则)
|
||||
|
||||
- Users explore more confidently when they know actions can be undone.
|
||||
- Irreversibility creates hesitation and anxiety.
|
||||
|
||||
Practical rules:
|
||||
- Provide undo for common actions (delete, move, edit).
|
||||
- Non-destructive actions should not require confirmation dialogs — let users act and undo.
|
||||
- For truly irreversible actions, make the consequences explicit and require deliberate confirmation (e.g., type the name to confirm).
|
||||
|
||||
---
|
||||
|
||||
## D) Attention Economy
|
||||
|
||||
### Visual Weight Budget (视觉权重预算)
|
||||
|
||||
- A page has a finite attention budget. Emphasizing too many things = emphasizing nothing.
|
||||
- Every bold element, bright color, or large size competes for the same limited attention.
|
||||
|
||||
Practical rules:
|
||||
- One visual focal point per screen section (the primary CTA or key metric).
|
||||
- Secondary information: reduce contrast, size, or weight to create clear hierarchy.
|
||||
- If everything looks important, re-evaluate: what is the ONE thing the user should do or notice here?
|
||||
|
||||
Review question: Close your eyes, then open them — is the first thing you see the most important thing on the page?
|
||||
|
||||
### Scanning Patterns (扫描模式)
|
||||
|
||||
- Users don't read; they scan. Common patterns: F-shape (content pages) and Z-shape (landing pages).
|
||||
- Key information must be on the scanning path or it will be missed.
|
||||
|
||||
Practical rules:
|
||||
- Place critical information at the top-left and in headings (F-pattern entry points).
|
||||
- In data tables, put the most important column on the far left.
|
||||
- Use visual anchors (bold text, icons, color) to create "scan stops" at key information.
|
||||
- Front-load sentences and labels: put the differentiating word first ("Save draft" vs "Draft — save").
|
||||
|
||||
Review question: If the user spends only 3 seconds scanning, can they extract the most critical information?
|
||||
@ -0,0 +1,60 @@
|
||||
# Review Output Template (Concise)
|
||||
|
||||
Use this template for `review` outputs. Keep each bullet short and implementable.
|
||||
|
||||
## Context
|
||||
|
||||
- Surface: (web/app) + page type (list/detail/form/dashboard/settings)
|
||||
- Primary user task:
|
||||
- Primary CTA:
|
||||
- Constraints/assumptions:
|
||||
|
||||
## Diagnosis (pick one per major issue)
|
||||
|
||||
- Execution gulf (执行鸿沟): user can’t find *how* to do it (entry/signifier/IA/choices)
|
||||
- Evaluation gulf (评估鸿沟): user can’t tell *what happened* (state/feedback/results)
|
||||
|
||||
- Slip (失误): goal is correct, execution goes wrong (misclick, fat-finger, wrong target)
|
||||
- Mistake (错误): mental model is wrong (labels/mapping/conceptual model misleads)
|
||||
|
||||
## Findings (prioritized)
|
||||
|
||||
### P0 (blocker)
|
||||
|
||||
- Problem:
|
||||
- Evidence:
|
||||
- Diagnosis: execution gulf / evaluation gulf; slip / mistake
|
||||
- Why it hurts:
|
||||
- Fix (specific, implementable):
|
||||
- Acceptance check:
|
||||
|
||||
### P1 (important)
|
||||
|
||||
- Problem:
|
||||
- Evidence:
|
||||
- Diagnosis: execution gulf / evaluation gulf; slip / mistake
|
||||
- Fix:
|
||||
- Acceptance check:
|
||||
|
||||
### P2 (polish)
|
||||
|
||||
- Problem:
|
||||
- Diagnosis: execution gulf / evaluation gulf (optional)
|
||||
- Fix:
|
||||
|
||||
## Quick wins (optional)
|
||||
|
||||
- 3 small changes that noticeably improve clarity or polish.
|
||||
|
||||
## Checklist to verify (copy/paste)
|
||||
|
||||
- Task clarity: primary CTA obvious and singular
|
||||
- IA: groups and headings match mental model
|
||||
- Feedback: loading/empty/error/success states present and helpful
|
||||
- Consistency: components and wording stable across screens
|
||||
- Affordance: clickable elements look clickable; icon-only is rare
|
||||
- Errors: prevention + recovery + actionable messages
|
||||
- Cognitive load: defaults and progressive disclosure reduce thinking
|
||||
- CRAP: hierarchy, alignment, spacing, grouping feel intentional
|
||||
- Modern minimal: restrained color, spacious layout, minimal copy
|
||||
- Icons: no emoji; consistent set; labels where ambiguity exists
|
||||
@ -0,0 +1,71 @@
|
||||
# Style Family: brand-driven
|
||||
|
||||
**Signature**: Tokens derived from existing brand assets. The project's brand is the source, not a style family.
|
||||
**Reference products**: Custom — anything where the brand book exists and dictates visual choices.
|
||||
**Best for**: established companies with brand guidelines, agency work, B2B with strict CI/CD (corporate identity), products that ship across brand-owned surfaces (web + email + print).
|
||||
|
||||
## How this family is different
|
||||
|
||||
The other 7 families ship with token defaults. `brand-driven` has none — by definition, the brand supplies them. This file is a *framework* for extracting tokens from brand assets, not a token set.
|
||||
|
||||
## Inputs you need from the user
|
||||
|
||||
In Phase 1, ask explicitly:
|
||||
|
||||
1. **Logo** — vector file (SVG / AI / Figma) preferred, otherwise highest-res PNG.
|
||||
2. **Brand color(s)** — hex codes for primary, optional secondary, semantic colors if defined.
|
||||
3. **Brand fonts** — font names + weights + license info (Adobe Fonts, self-hosted, Google Fonts). If proprietary, ask about web fallback.
|
||||
4. **Brand book / style guide** — PDF or web link if one exists.
|
||||
5. **Voice / tone notes** — affects copy, but also informs density/motion choices.
|
||||
|
||||
If the user doesn't have all of these → either
|
||||
- (a) start from what they have and treat the rest as open in Phase 2 (use neutral defaults), or
|
||||
- (b) flag that the project might *not* be brand-driven and re-run Phase 2 with a real style family.
|
||||
|
||||
## Token derivation rules
|
||||
|
||||
When you do have brand assets:
|
||||
|
||||
### Color
|
||||
- Primary = brand primary, exactly as specified.
|
||||
- Hover / active = derived using OKLCH or HSL lightness shift (typically -8% to -12% lightness for hover, -16% to -20% for active).
|
||||
- Subtle (background tint) = primary at 5–10% alpha or +90% lightness.
|
||||
- Neutrals = tinted toward the brand primary's hue (not pure gray) unless the brand book specifies.
|
||||
- Semantic (success/warning/error/info) = the brand book's versions if defined; otherwise stay close to web defaults but tinted toward the brand temperature.
|
||||
|
||||
### Typography
|
||||
- Headings = brand display font.
|
||||
- Body = brand body font, or a free fallback if licensing prevents web use. Always provide system-font fallback stack.
|
||||
- Mono = the brand's mono if specified, otherwise a neutral choice that doesn't fight the brand.
|
||||
|
||||
### Spacing / radius / shadow
|
||||
- The brand book usually does *not* specify these for the web. Pick defaults that match the brand's emotional register:
|
||||
- Sharp brand → sharp radius (2–4px), flat shadow.
|
||||
- Friendly brand → generous radius (12–16px), soft shadow.
|
||||
- Premium brand → 0–2px radius, no shadow, lots of whitespace.
|
||||
|
||||
### Motion
|
||||
- If brand book mentions motion principles, follow them.
|
||||
- If not, choose motion vocabulary based on brand tone — premium = slow, playful = bouncy, technical = snappy.
|
||||
|
||||
## Cross-surface consistency
|
||||
|
||||
Brand-driven projects often appear on:
|
||||
- Web app
|
||||
- Marketing site
|
||||
- Email
|
||||
- Print collateral
|
||||
- Mobile app
|
||||
|
||||
When generating `design-spec.md` for brand-driven, include a **cross-surface notes** section that flags what should stay consistent and what should adapt (e.g. body font might be system on email, web on app).
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- Treating the brand color as decoration rather than the primary signal.
|
||||
- Auto-generating a 9-tier color scale without checking if the brand has its own scale.
|
||||
- Replacing the brand fonts with "what looks more modern" on the web. The brand's font is the brand's voice; if you don't like it, talk to the user, don't override.
|
||||
- Ignoring CJK / multi-script considerations when the brand operates internationally.
|
||||
|
||||
## Notes
|
||||
|
||||
About 30–40% of real-world projects are brand-driven and the consultant's job is largely to *extract and codify* what already exists, not to invent. If the user keeps saying "we already use X for that", the project is probably brand-driven and you should switch families.
|
||||
@ -0,0 +1,56 @@
|
||||
# Style Family: brutal
|
||||
|
||||
**Signature**: Raw, monospace, high-contrast borders, deliberately rough, system-font fallbacks visible.
|
||||
**Reference products**: Many indie maker landing pages, Vercel templates (brutalist variants), Bauhaus-revival sites, Cobalt.tools.
|
||||
**Best for**: indie projects, designer portfolios, statement marketing, hacker culture products.
|
||||
|
||||
## Token defaults
|
||||
|
||||
### Color
|
||||
- **Primary**: high-saturation block colors — pure red, pure yellow, pure blue, pure black.
|
||||
- **Background**: unapologetic — pure white `#ffffff` or pure black `#000000`. The "no pure black" rule from `modern-minimal` does not apply here; pure black is the point.
|
||||
- **Borders**: thick (2–4px), pure black, on every container. Borders carry the visual weight that elsewhere is carried by shadows.
|
||||
|
||||
### Typography
|
||||
- **Heading**: monospace, system font, or quirky display — JetBrains Mono, Space Mono, IBM Plex Mono, Departure Mono, Times New Roman (deliberate retro).
|
||||
- **Body**: monospace or system serif. Geometric sans-serif is *out of family*.
|
||||
- **Weights**: extreme contrast — 400 vs 800, no in-between.
|
||||
|
||||
### Radius
|
||||
- **0 px**. Sharp corners always. This is the family's most non-negotiable trait.
|
||||
|
||||
### Spacing
|
||||
- 8px base. Scale: 8 / 16 / 24 / 40 / 64.
|
||||
- Spacing is uneven on purpose — asymmetric layouts are encouraged.
|
||||
|
||||
### Shadow
|
||||
- **Hard shadows only**. `box-shadow: 4px 4px 0 0 #000;` (no blur). No soft elevation.
|
||||
|
||||
### Motion
|
||||
- Snappy or none. No easing curves. Linear or step transitions. Hover states can be aggressive (color invert, hard offset).
|
||||
|
||||
## Anti-patterns *within this family*
|
||||
|
||||
- Soft shadows.
|
||||
- Rounded corners.
|
||||
- Pastels.
|
||||
- "Design system polish" — uniform spacing, perfect alignment, careful hierarchy. Brutal embraces friction.
|
||||
- Fade animations.
|
||||
- Lucide / Phosphor icons. Use ASCII characters, emoji as ironic decoration, or system Unicode glyphs.
|
||||
|
||||
## Typical surfaces
|
||||
|
||||
This family does well on:
|
||||
- Single-page indie landing
|
||||
- Developer tool marketing
|
||||
- Manifesto / values pages
|
||||
- Designer portfolios
|
||||
|
||||
This family does poorly on:
|
||||
- Anything where users spend more than ~10 minutes per session — the friction wears
|
||||
- Enterprise / regulated industries
|
||||
- Consumer apps with broad demographic reach
|
||||
|
||||
## Notes
|
||||
|
||||
Brutal is a statement, not a default. If the user picked it without realizing what it implies (no rounded corners, no soft shadows, no neat alignment), pause and double-check before generating tokens.
|
||||
@ -0,0 +1,58 @@
|
||||
# Style Family: editorial
|
||||
|
||||
**Signature**: Long-form respect, serif headers, generous measure, hierarchy through scale.
|
||||
**Reference products**: Medium, Substack, NYT, The Verge, Stratechery.
|
||||
**Best for**: blogs, content platforms, documentation that's read end-to-end, knowledge bases, news.
|
||||
|
||||
## Token defaults
|
||||
|
||||
### Color
|
||||
- **Primary**: deep ink, restrained accent (often a deep red, navy, or forest green).
|
||||
- **Background**: warm off-white or cream, not pure white. Common range `#fafaf7` to `#f5f1ea`.
|
||||
- **Text**: high-contrast near-black with slight warm cast.
|
||||
- **Avoid in this family**: bright saturated brand colors competing with text; cool tech blue.
|
||||
|
||||
### Typography
|
||||
- **Heading**: serif — Source Serif, Lora, Tiempos, GT Sectra, Newsreader, Playfair (display only).
|
||||
- **Body**: serif preferred for body too (the whole point) — Source Serif, Lora, Spectral, IBM Plex Serif. Sans-serif body is acceptable but loses the family's voice.
|
||||
- **Mono**: only if code samples appear.
|
||||
- **Measure**: 60–75 characters per line for body. This is a hard rule in this family.
|
||||
|
||||
### Radius
|
||||
- Minimal. **0 / 2 / 4 px**. Curves dilute the editorial feel.
|
||||
|
||||
### Spacing
|
||||
- 4px base, but the *visible* spacing is generous: 24 / 32 / 48 / 64.
|
||||
- Density: spacious. Compact does not belong here.
|
||||
|
||||
### Shadow
|
||||
- Flat. Borders if needed. No elevation.
|
||||
|
||||
### Motion
|
||||
- Minimal. Fade only. Scrolling does the work.
|
||||
|
||||
## Anti-patterns *within this family*
|
||||
|
||||
- Sans-serif headings that scream "SaaS landing page".
|
||||
- Cards everywhere. The body of an article is *not* a card.
|
||||
- Saturated CTA buttons in the middle of body copy. Use inline text links; reserve buttons for end-of-article actions.
|
||||
- Sidebars full of widgets. Editorial respects the reader's attention.
|
||||
- Auto-playing video / hero animations.
|
||||
- Narrow body measure (under 50 chars) or absurdly wide (over 90 chars).
|
||||
|
||||
## Typical surfaces
|
||||
|
||||
This family does well on:
|
||||
- Article pages
|
||||
- Author archives
|
||||
- Documentation
|
||||
- About / values pages
|
||||
|
||||
This family does poorly on:
|
||||
- Dashboards (no place for serif body in dense data)
|
||||
- Forms (serifs at small input sizes look off)
|
||||
- Mobile-first apps (the family relies on desktop measure)
|
||||
|
||||
## Notes
|
||||
|
||||
Editorial done well *almost feels like nothing* — the design recedes and lets the writing carry. If you find yourself adding decoration, you've left the family.
|
||||
@ -0,0 +1,39 @@
|
||||
# Style Family Catalog
|
||||
|
||||
A "style family" is a coherent bundle of font / color / spacing / radius / shadow / motion choices that work together emotionally and functionally. Style families are **starting points** — the user can override anything inside a chosen family.
|
||||
|
||||
**These families are project-chosen, never default-imposed.** If you start a `design` session and impose `modern-minimal` without the user asking, you are doing it wrong.
|
||||
|
||||
## How to use this catalog
|
||||
|
||||
1. In Phase 1 of the interview, listen to the user's references and constraints.
|
||||
2. In Phase 2, present 2–4 candidate families based on those signals.
|
||||
3. Once the user picks one, load `<family>.md` for the specifics — that file becomes the starting token set for Phase 3.
|
||||
4. Each family file contains its own "anti-patterns to avoid" — those are scoped to that family, not global UX rules. Do not quote one family's restrictions when a different family was chosen.
|
||||
|
||||
## Catalog
|
||||
|
||||
| Family | One-line signature | Reference products | Best for |
|
||||
|---|---|---|---|
|
||||
| [`modern-minimal`](./modern-minimal.md) | Spacious, typography-led, restrained color, sharp grid | Linear, Vercel, Notion | Dev tools, SaaS, startup landing |
|
||||
| [`editorial`](./editorial.md) | Long-form respect, serif headers, generous measure | Medium, Substack, NYT | Blogs, content platforms, knowledge bases |
|
||||
| [`brutal`](./brutal.md) | Raw, monospace, high-contrast borders, deliberately rough | Vercel templates, brutalist landing pages | Indie projects, designer tools, statement marketing |
|
||||
| [`playful`](./playful.md) | Rounded, saturated, bouncy motion, illustrative | Duolingo, MailChimp, early Notion | Education, consumer apps, onboarding-heavy |
|
||||
| [`premium-luxury`](./premium-luxury.md) | Restrained palette, elegant serifs, generous whitespace, subtle motion | Aesop, Hermès, Apple Music | Hospitality, fashion, high-ticket SaaS |
|
||||
| [`tech-cyberpunk`](./tech-cyberpunk.md) | Dark-first, monospace, neon accents, high info density | GitHub dark, Vercel docs dark, terminal aesthetics | Dev infra, security, AI tooling, data dashboards |
|
||||
| [`warm-content`](./warm-content.md) | Warm neutrals, comfortable reading, soft surfaces | Are.na, Notion light, Craft | Personal sites, journals, community tools |
|
||||
| [`brand-driven`](./brand-driven.md) | All tokens derived from existing brand assets | Custom; the project is the source | Established brands, agency work, B2B with brand guidelines |
|
||||
|
||||
## When to combine
|
||||
|
||||
Users often want hybrids. Common pairs:
|
||||
|
||||
- `modern-minimal` color + `editorial` typography → corporate blog
|
||||
- `tech-cyberpunk` colors + `modern-minimal` layout → developer dashboard
|
||||
- `premium-luxury` typography + `warm-content` surfaces → boutique e-commerce
|
||||
|
||||
Honor the combination. Note it explicitly in `design-spec.md` so future contributors know which family supplies which dimension.
|
||||
|
||||
## When none fits
|
||||
|
||||
If the user's references span 3+ unrelated families and they can't pick one, the project is probably **brand-driven** by default — start from their brand assets (logo, brand color) and let everything else follow. Use `brand-driven.md` as the framework.
|
||||
@ -0,0 +1,58 @@
|
||||
# Style Family: modern-minimal
|
||||
|
||||
**Signature**: Spacious, typography-led, restrained color, sharp grid.
|
||||
**Reference products**: Linear, Vercel, Notion, Stripe, Plaid.
|
||||
**Best for**: dev tools, SaaS dashboards, startup landing pages, internal enterprise.
|
||||
|
||||
## Token defaults
|
||||
|
||||
### Color
|
||||
- **Primary**: a single saturated accent (often blue / teal / violet). Used sparingly.
|
||||
- **Neutrals**: tinted toward the brand color (e.g. brand `#0066cc` → text `#1a2a3a` rather than `#333`). True grays look sterile in this family.
|
||||
- **Avoid in this family**: pure black `#000`, pure white `#fff` for large surfaces, generic indigo `#6366f1`, purple-to-blue gradients (Stripe-cliché unless deliberate).
|
||||
|
||||
### Typography
|
||||
- **Heading**: geometric sans — Plus Jakarta Sans, Geist, Manrope, Outfit, DM Sans, Inter (Inter is fine here, the "ban" is a taste preference, not a UX rule).
|
||||
- **Body**: same family or a paired humanist sans.
|
||||
- **Mono**: JetBrains Mono, Geist Mono, IBM Plex Mono.
|
||||
|
||||
### Radius
|
||||
- Sharp side: **4 / 8 / 12 px**. Pills only on chips/badges, not on primary buttons.
|
||||
|
||||
### Spacing
|
||||
- 4px base, scale 4 / 8 / 12 / 16 / 24 / 32 / 48.
|
||||
- Density: balanced or spacious. Compact is uncommon in this family.
|
||||
|
||||
### Shadow
|
||||
- Flat by default. Subtle (1–2px tinted shadow) for elevated surfaces.
|
||||
|
||||
### Motion
|
||||
- Minimal. Fade and small translate+fade for state changes. Scale+fade only for overlays. **Avoid bounce.**
|
||||
|
||||
## Anti-patterns *within this family*
|
||||
|
||||
These are the things that pull a project out of `modern-minimal`. If the user explicitly wants them, that's fine — but they're stylistically inconsistent with the family.
|
||||
|
||||
- All content wrapped in cards with borders + shadow. Use whitespace + typography for hierarchy instead.
|
||||
- Card-in-card nesting.
|
||||
- 3-column equal-grid landing pages with stock-photo headers.
|
||||
- Decorative gradients on every section. Limit to one per page.
|
||||
- Emoji as section icons. Use Lucide / Phosphor / Heroicons.
|
||||
- Pure-grey-on-tinted-background body text. Add brand tint to neutrals.
|
||||
|
||||
## Typical surfaces
|
||||
|
||||
This family does well on:
|
||||
- Dashboard with sidebar nav + content
|
||||
- Settings forms
|
||||
- API documentation
|
||||
- Marketing landing for B2B SaaS
|
||||
|
||||
This family does poorly on:
|
||||
- Children / education products (too cold)
|
||||
- Long-form reading (sans body fights long passages — consider `editorial` for blog routes)
|
||||
- Brand-driven luxury (too utilitarian)
|
||||
|
||||
## Notes
|
||||
|
||||
The "Modern Minimal" defaults the original SKILL.md treated as universal *belong here* and only here. If the project picked a different family, those defaults do not apply.
|
||||
@ -0,0 +1,62 @@
|
||||
# Style Family: playful
|
||||
|
||||
**Signature**: Rounded, saturated, bouncy motion, illustrative, friendly.
|
||||
**Reference products**: Duolingo, MailChimp, Slack early, Notion early, Headspace.
|
||||
**Best for**: education, consumer apps with onboarding, kids products, gamification, habit/lifestyle apps.
|
||||
|
||||
## Token defaults
|
||||
|
||||
### Color
|
||||
- **Primary**: saturated and friendly — coral, teal, sunny yellow, grass green. Avoid muted enterprise blues.
|
||||
- **Palette**: 2–3 accent colors are encouraged (the "single primary" rule from other families is relaxed).
|
||||
- **Background**: warm off-white or soft tinted background; pure white feels sterile here.
|
||||
- **Avoid in this family**: cool grays, navy/charcoal, monochrome palettes.
|
||||
|
||||
### Typography
|
||||
- **Heading**: friendly humanist sans or rounded sans — Nunito, Quicksand, Poppins, Fraunces (soft serif), Inter Display (rounded variant).
|
||||
- **Body**: rounded humanist sans — Nunito, DM Sans, Manrope, Open Sans (yes, even this one).
|
||||
- **Weight**: medium-to-bold for headings (600+). Light weights look fragile.
|
||||
|
||||
### Radius
|
||||
- **Generous**: 12 / 16 / 24 px. Pills and full-rounded buttons are common and *correct* here.
|
||||
|
||||
### Spacing
|
||||
- 4px base, scale 4 / 8 / 16 / 24 / 32 / 48.
|
||||
- Density: balanced. Generous touch targets (mobile-friendly).
|
||||
|
||||
### Shadow
|
||||
- **Soft and tinted**: shadows often inherit a hint of the surface or primary color, not pure black.
|
||||
- Multiple elevation tiers welcome.
|
||||
|
||||
### Motion
|
||||
- **Bounce is encouraged.** Spring physics, elastic easing, micro-celebrations on success.
|
||||
- Lottie illustrations are in family.
|
||||
- Empty states and 404 pages are opportunities for character, not minimalism.
|
||||
|
||||
## Anti-patterns *within this family*
|
||||
|
||||
- Sharp corners (0–4px) on primary surfaces.
|
||||
- Pure black or pure gray text on white. Use a slightly warm dark color.
|
||||
- Geometric sans like Geist or Inter as body — too cold.
|
||||
- Flat illustrations with no character.
|
||||
- Skipping the empty state — playful family thrives on personality in edge cases.
|
||||
- Rigid grid alignment with no asymmetry.
|
||||
|
||||
## Typical surfaces
|
||||
|
||||
This family does well on:
|
||||
- Onboarding flows
|
||||
- Consumer mobile apps
|
||||
- Education products
|
||||
- Streak / progress / gamification surfaces
|
||||
- Marketing for B2C
|
||||
|
||||
This family does poorly on:
|
||||
- B2B dashboards used 8 hours a day (the personality wears)
|
||||
- High-stakes interfaces (medical, financial trades)
|
||||
- Enterprise procurement processes
|
||||
- Long-form reading (rounded body fonts fatigue)
|
||||
|
||||
## Notes
|
||||
|
||||
There's a cliff between "friendly" and "infantilizing". For adult-targeted products in serious domains (finance, healthcare), `playful` is usually the wrong family — but `warm-content` may give the same warmth without the gamification feel.
|
||||
@ -0,0 +1,61 @@
|
||||
# Style Family: premium-luxury
|
||||
|
||||
**Signature**: Restrained palette, elegant serifs, generous whitespace, subtle motion, products treated like objects.
|
||||
**Reference products**: Aesop, Hermès, Apple Music, Apple Newsroom, Linear (when in marketing mode), Loro Piana.
|
||||
**Best for**: hospitality, fashion / beauty, high-ticket SaaS marketing, art galleries, boutique e-commerce.
|
||||
|
||||
## Token defaults
|
||||
|
||||
### Color
|
||||
- **Primary**: muted, often *not* a vivid color — deep brown, ink black, forest, oxblood, brass.
|
||||
- **Background**: warm off-white, cream, sand, or pure white treated with intent.
|
||||
- **Accents**: minimal. A single underline color, a metallic touch.
|
||||
- **Avoid in this family**: saturated brand blues, neon accents, gradient backgrounds.
|
||||
|
||||
### Typography
|
||||
- **Heading**: elegant serif or contrasted display — GT Sectra, Tiempos, Newsreader, Söhne Breit, Canela, EB Garamond.
|
||||
- **Body**: serif or refined sans — Söhne, Söhne Lebenslauf, Aktiv Grotesk, Inter at low weights, Tiempos Text.
|
||||
- **Sizing**: large display headlines (5–8rem on landing). Body stays at 16–18px.
|
||||
- **Letterspacing**: slight negative tracking on display headings (-0.02 to -0.04em).
|
||||
|
||||
### Radius
|
||||
- **0 / 2 px**. Curves cheapen this family. Buttons rectangular. Cards rectangular.
|
||||
|
||||
### Spacing
|
||||
- 8px base, scale 8 / 16 / 24 / 40 / 64 / 96.
|
||||
- Density: very spacious. Whitespace is the signal of value.
|
||||
|
||||
### Shadow
|
||||
- None or extremely subtle (1px hairline borders preferred over shadow).
|
||||
|
||||
### Motion
|
||||
- **Slow and intentional**. 400–800ms easings. Fade with slight upward movement on scroll.
|
||||
- No bounces. No celebrations. Confident and quiet.
|
||||
|
||||
## Anti-patterns *within this family*
|
||||
|
||||
- Rounded buttons / pills.
|
||||
- Saturated CTA color competing with content.
|
||||
- "Get started for free" CTA copy. Premium copy is more reserved — "Discover", "Begin", or just the product name.
|
||||
- Multi-column dense layouts. One column, one focus.
|
||||
- Stock photography. Either custom or none.
|
||||
- Trustpilot badges, social proof bars, "as seen in" logo strips. (These belong in other families.)
|
||||
- Sale stickers, urgency timers, comparison tables.
|
||||
|
||||
## Typical surfaces
|
||||
|
||||
This family does well on:
|
||||
- Brand homepages
|
||||
- Product detail pages (single SKU treatment)
|
||||
- About / heritage / craft pages
|
||||
- Editorial-style product stories
|
||||
|
||||
This family does poorly on:
|
||||
- Functional dashboards (the spacious style wastes screen)
|
||||
- Settings panels (reads as cold and unhelpful)
|
||||
- Forms with many fields (whitespace amplifies tedium)
|
||||
- Mobile checkout (vertical sprawl)
|
||||
|
||||
## Notes
|
||||
|
||||
Premium is largely about *what you remove*. If the page feels busy, it's wrong. The most common failure mode is treating premium as "modern-minimal but with a serif" — the spacing, sizing, and motion are all different.
|
||||
@ -0,0 +1,64 @@
|
||||
# Style Family: tech-cyberpunk
|
||||
|
||||
**Signature**: Dark-first, monospace, neon accents, high info density, terminal/IDE aesthetics.
|
||||
**Reference products**: GitHub dark, Vercel docs dark, Cursor, Warp, Raycast, terminal apps, Cyberpunk 2077 menus.
|
||||
**Best for**: developer infrastructure, security tools, AI tooling, observability dashboards, command-palette apps.
|
||||
|
||||
## Token defaults
|
||||
|
||||
### Color
|
||||
- **Background**: dark by default — `#0a0a0b` to `#18181b` range. Pure black `#000` is acceptable.
|
||||
- **Primary accent**: neon-leaning — electric blue `#3b82f6`, lime `#84cc16`, magenta `#d946ef`, cyan `#06b6d4`.
|
||||
- **Text**: off-white with slight cool cast (`#e4e4e7`), not pure white.
|
||||
- **Borders**: low-opacity white (`rgba(255,255,255,0.08–0.12)`) — barely visible structural lines.
|
||||
- **Light mode**: optional and secondary. Many products in this family don't ship light mode; if they do, it's clearly not the headline experience.
|
||||
|
||||
### Typography
|
||||
- **Heading**: geometric sans, mono, or hybrid — Inter, Geist, Space Grotesk, JetBrains Mono.
|
||||
- **Body**: same as heading or paired sans.
|
||||
- **Mono**: critical and prominent — JetBrains Mono, Geist Mono, Berkeley Mono, IBM Plex Mono. Used for code, IDs, command shortcuts, status text.
|
||||
- **Mono in chrome**: keyboard hints `⌘K`, status badges, version numbers all live in mono.
|
||||
|
||||
### Radius
|
||||
- **2 / 4 / 6 px**. Sharp but not aggressively so. 8px+ feels too soft for the family.
|
||||
|
||||
### Spacing
|
||||
- 4px base, scale 4 / 8 / 12 / 16 / 24.
|
||||
- Density: **compact**. The family thrives on info density. Spacious wastes the dark canvas.
|
||||
|
||||
### Shadow
|
||||
- Often replaced by glow / inner shadow. Outer shadows on dark mode read as halos.
|
||||
- Subtle inner shadow on inputs to imply depth.
|
||||
|
||||
### Motion
|
||||
- Snappy (100–200ms). No bounce. State changes are crisp on/off.
|
||||
- Selection / focus uses a glow ring or thin colored border.
|
||||
|
||||
## Anti-patterns *within this family*
|
||||
|
||||
- Light gray text on dark background (`#888` on `#000` fails contrast and looks generic). Use cool off-whites.
|
||||
- Rounded pill buttons.
|
||||
- Soft pastel illustrations.
|
||||
- Stock-photo hero images.
|
||||
- Whitespace as the design (this family is the opposite of `premium-luxury`).
|
||||
- Avoiding monospace entirely. Mono is the family's voice.
|
||||
- Toast notifications with bouncy entry.
|
||||
|
||||
## Typical surfaces
|
||||
|
||||
This family does well on:
|
||||
- Developer dashboards (deployments, logs, traces)
|
||||
- Command palettes
|
||||
- Code editors and IDE-adjacent surfaces
|
||||
- Observability and security tooling
|
||||
- Terminal-inspired marketing pages
|
||||
|
||||
This family does poorly on:
|
||||
- Marketing aimed at non-developer buyers (CFO, HR)
|
||||
- Long-form reading
|
||||
- Children / education
|
||||
- Anything that needs to feel approachable to non-technical users
|
||||
|
||||
## Notes
|
||||
|
||||
The "AI tooling" wave (2024–) has made this family overused — every dev tool now ships with the same dark + neon accent + mono look. If the project is in this family, lean on a *specific* mono / accent combo that's not literal copies of GitHub or Vercel.
|
||||
@ -0,0 +1,62 @@
|
||||
# Style Family: warm-content
|
||||
|
||||
**Signature**: Warm neutrals, comfortable reading, soft surfaces, low-pressure feel.
|
||||
**Reference products**: Are.na, Notion light, Craft, Day One journal, Bear, Readwise.
|
||||
**Best for**: personal sites, journaling apps, community tools, knowledge gardens, indie productivity.
|
||||
|
||||
## Token defaults
|
||||
|
||||
### Color
|
||||
- **Background**: warm off-white — `#faf8f3` to `#f0ece2`. Cream, parchment, sand.
|
||||
- **Primary**: soft and earthy — terracotta, dusty teal, deep moss, muted plum. Saturated tech colors don't belong.
|
||||
- **Text**: warm dark — `#2d2a26`, `#3d3a35`. Pure black reads as clinical here.
|
||||
- **Borders**: barely-there warm gray, often replaced by shadow or just spacing.
|
||||
|
||||
### Typography
|
||||
- **Heading**: serif or warm humanist sans — Tiempos, Spectral, Sentinel, Söhne, Inter Display, GT Alpina.
|
||||
- **Body**: serif or rounded humanist — Sentinel, Spectral, Söhne, Tiempos Text, Mulish.
|
||||
- **Mono**: warm if used — Berkeley Mono, IBM Plex Mono.
|
||||
|
||||
### Radius
|
||||
- **6 / 10 / 16 px**. Soft enough to feel human, not so much it feels childish.
|
||||
|
||||
### Spacing
|
||||
- 4px base, scale 4 / 8 / 12 / 16 / 24 / 32.
|
||||
- Density: balanced or spacious. Never compact.
|
||||
|
||||
### Shadow
|
||||
- Soft and warm-tinted (`rgba(45, 42, 38, 0.06)`), not cold black shadows.
|
||||
- Multiple elevation tiers OK but kept subtle.
|
||||
|
||||
### Motion
|
||||
- Gentle. 200–400ms with ease-out curves. No snap, no bounce.
|
||||
- Reveal animations on scroll are in family if subtle.
|
||||
|
||||
## Anti-patterns *within this family*
|
||||
|
||||
- Pure white backgrounds.
|
||||
- Cool blue / cyan / neon palettes.
|
||||
- Tech-style monospace as the heading font.
|
||||
- Aggressive CTA colors (red, electric orange).
|
||||
- Dense data tables.
|
||||
- "Power user" keyboard shortcut UI as a primary surface.
|
||||
|
||||
## Typical surfaces
|
||||
|
||||
This family does well on:
|
||||
- Personal blogs
|
||||
- Note-taking apps
|
||||
- Reading apps
|
||||
- Journaling and reflection tools
|
||||
- Community / forum surfaces
|
||||
- Indie maker about pages
|
||||
|
||||
This family does poorly on:
|
||||
- Enterprise dashboards
|
||||
- High-frequency transactional UIs
|
||||
- Anything where speed/efficiency must dominate feel
|
||||
- Cold-tech marketing
|
||||
|
||||
## Notes
|
||||
|
||||
`warm-content` is what `editorial` becomes when the product is interactive (you make notes, organize, save) rather than purely consumed (you read). The two share serif typography and generous spacing but `warm-content` allows more UI affordance — buttons, inputs, lists.
|
||||
@ -0,0 +1,79 @@
|
||||
# System-Level Guiding Principles
|
||||
|
||||
Use these as first-order constraints before choosing specific components or page patterns.
|
||||
|
||||
## Concept constancy
|
||||
- Definition: The same business concept keeps the same name, meaning, and interaction semantics across the system.
|
||||
- Review question: If a user learns this concept in one place, can they transfer that understanding everywhere else?
|
||||
|
||||
## Primary task focus
|
||||
- Definition: Each screen has one dominant objective with the highest visual and interaction priority.
|
||||
- Review question: Can users identify the most important action within 3 seconds?
|
||||
|
||||
## UI copy source discipline (for product development)
|
||||
- Definition: visible UI copy should come from business content, not from implementation constraints or generation instructions.
|
||||
- Preferred copy sources:
|
||||
- User task: what the user is trying to do.
|
||||
- System state: what is happening now (loading, empty, error, success, permission).
|
||||
- Result + next step: what changed and what users can do next.
|
||||
- Risk/trust context: only when it prevents mistakes or improves confidence.
|
||||
- Internal-only sources (do not render directly in product UI by default):
|
||||
- Visual/style constraints (e.g., "minimal", "black-and-white", "modern").
|
||||
- Technical constraints and implementation notes.
|
||||
- Prompt instructions, review rubrics, and generation meta text.
|
||||
- User-facing copy framing heuristic (general, not title-specific):
|
||||
- Applies to any prominent UI copy: titles, section headers, callouts, badges, CTA labels, and empty states.
|
||||
- Prefer user-outcome framing: describe the user's goal and the result they get.
|
||||
- Avoid self-referential/process framing for end-user product UI (e.g., "to showcase", "this page demonstrates", "showing the skill's value").
|
||||
- Exception: if the surface is explicitly a demo/tutorial/spec page for builders, self-referential/process copy can be acceptable when it improves understanding.
|
||||
|
||||
## State perceptibility (high-level, cross-system)
|
||||
- Problem: users make errors when an important internal state is not perceivable (mode, scope, selection, unsaved changes, environment, permission).
|
||||
- Principle: make state visible using the lowest-noise signal that reliably changes behavior.
|
||||
- Preferred signals (in order):
|
||||
- Structural change: the layout/components clearly switch (read -> edit; list -> selection; view -> compare).
|
||||
- Control state: the control that changes behavior shows its state (tabs, toggles, segmented controls).
|
||||
- Inline signifiers: local cues near the affected area (selection count, scope chip, disabled reason).
|
||||
- Post-action feedback: clear results + next step (reduces evaluation gulf).
|
||||
- Only if needed: persistent banners/labels for high-risk, sticky modes.
|
||||
- Avoid: redundant "status labels" that restate what the structure already makes obvious (they add noise but not clarity).
|
||||
- Practical workflow:
|
||||
- First build a content model (task/state/result/risk).
|
||||
- Then apply visual constraints through layout, hierarchy, and component styling.
|
||||
- Run a final copy pass: if a sentence does not help task completion, state understanding, or trust, move it to internal notes.
|
||||
- Review question: is each visible sentence useful for end users, or only useful for builders/reviewers?
|
||||
|
||||
## Help text layering (avoid "hint sprawl")
|
||||
- Problem this prevents: dumping all tips onto the UI feels "safe", but it destroys hierarchy and increases scanning cost.
|
||||
- Placement heuristic:
|
||||
- L0 (Always visible): only information needed to complete the task correctly.
|
||||
- L1 (Nearby): short guidance for high-risk / high-ambiguity inputs.
|
||||
- L2 (On demand): examples, advanced details, "learn more".
|
||||
- L3 (After action): result, error, recovery, and next step.
|
||||
- Copy budget heuristic:
|
||||
- Prefer one clear helper line over multiple repetitive hints.
|
||||
- If a page needs many persistent hints, improve IA or defaults first.
|
||||
|
||||
## Feedback loop closure
|
||||
- Definition: Every user action must complete a full loop: received, in progress, result, and clear next step.
|
||||
- Review question: At any moment, can users tell what the system is doing and what they should do next?
|
||||
|
||||
## Prevention first + recoverability
|
||||
- Definition: Reduce error probability before submission, and provide recovery paths for high-risk outcomes.
|
||||
- Review question: Is the path designed to be easy to do right and safe to recover when wrong?
|
||||
|
||||
## Progressive complexity
|
||||
- Definition: Show minimum-required controls by default; reveal advanced capability only when context requires it.
|
||||
- Review question: Can novices complete the core task quickly without limiting expert throughput?
|
||||
|
||||
## Action perceptibility (affordance + signifiers)
|
||||
- Definition: Interactive targets and likely outcomes are perceivable from structure and visual cues, without guesswork.
|
||||
- Review question: Without reading help text, can users predict what is actionable and what will happen?
|
||||
|
||||
## Cognitive load budget
|
||||
- Definition: Limit new rules, terms, and interaction modes per screen; prioritize reuse over novelty.
|
||||
- Review question: As information grows, does comprehension cost stay stable?
|
||||
|
||||
## Evolution with semantic continuity
|
||||
- Definition: Introduce new components/patterns only when existing ones cannot solve the problem, and keep semantic compatibility.
|
||||
- Review question: Is this necessary innovation or avoidable interaction drift?
|
||||
Reference in New Issue
Block a user