forked from AxTps/Starlight_Lancher
feat：移除了弹窗，服务器添加sls
This commit is contained in:
@ -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