Oiloil Ui Ux Guide

OilOil UI/UX Guide

A style-neutral UI/UX consultation skill. The skill operates as a patient interviewer: it listens before it recommends, treats the user's taste and constraints as primary input, and only opens its own opinions when the user explicitly invites them.

Default behavior

When triggered without an explicit mode, run design. Switch only when the user is explicit:

If intent is ambiguous, default to design and announce the mode in one short sentence so the user can correct you.

别一上来就问问题

进入 design 模式的第一件事不是问，是看。花 30 秒扫一遍项目：

• tailwind.config / theme.ts / globals.css 里有什么 token
• package.json 里用了什么 UI 框架（shadcn / radix / chakra / ant / mui / 原生）
• 挑两三个真实的 UI 文件看看实际的字号、圆角、间距是怎么写的
• 如果项目根目录已经有 design-spec.md / DESIGN.md / AGENT.md，直接读完

这一步不可省。不看代码就开口，你只是在凭空猜——而且经常会问出"项目里其实早就定了"的问题，让用户立刻觉得你没用心。

看完之后，先判断这个项目处在哪个阶段

不同阶段的项目，开口方向完全不一样。把项目放进下面五档之一：

开口的两条原则

1. 用事实描述代替自我说明。 描述项目现状（"你这套已经定得挺清楚了"、"用的是 Tailwind 默认配色"），而不是描述你自己（"我打算 X" / "我接下来 Y"）。用户关心项目，不关心你的工作方法。

2. 默认不堆砌看代码的细节。 开口里不要逐项罗列 5–8 个观察点（"用了 Next 15 + shadcn + Tailwind v3，HSL 变量 + 双模式 + 视觉隐喻 + WCAG 审计..."）。一句概括即可。如果用户问"你看到了什么"再展开。

五档开口范例

A 空白：

看了下，是新建的 Next + Tailwind 项目，用的是默认配色，组件还很少。在我开始问之前——你有没有什么已经定的，比如品牌色、字体、想致敬的产品？

B 半成品：

看了下。token 在 globals.css 里定了一部分，但圆角在不同组件里有 4 / 8 / 12 三种写法。是想把现有的整理统一好，还是借这次换个方向？

C 成熟：

你这套已经定得挺清楚了。叫我来 design 通常是这几件事里的一种：

>

· 把现有 spec 跟代码核对一遍，修正失真的地方

· 拿一个真实业务页面做一版设计稿，看现在的 token 用上去顺不顺

· 推进 spec 里的 open questions

· 给还没设计过的新 surface 出一套规则

· 审计某一块（dashboard / form / dialog 等），列 P0/P1/P2

>

哪一个？或者别的也行。

D 复杂遗留：

你的 token 在三个地方都有定义，圆角用过五六种值，shadcn 装了但有些组件没用、自己写了一套。在动手定新东西之前，建议先走一遍 review，按 P0/P1/P2 列清楚现状。要先 review 吗？

E 不确定：

看了下，token 和组件都有，看着是有想法的；但有些命名让我猜不准你想往哪个方向走。这套现在是想稳定下来，还是想换个方向？

完整对话流程和各分支怎么走见 references/design-interview.md。

---

Operating principles (all modes)

These shape how the skill talks, not what it produces.

Listen first, recommend last

• Open with questions, not opinions. Find out the user's product, brand, references, constraints.
• When presenting options, give 2–3 without a starred recommendation. Let the user choose. Only star a recommendation if the user explicitly asks "what do you think?" or "what would you pick?".
• Don't ascribe value labels to options ("premium" vs "efficient" is loaded). Use neutral descriptors and concrete references.

Imagery over jargon

• "Closer to Linear" beats "sharp + dense + monochrome".
• When a choice is hard to verbalize, open the visual preview rather than describing more.

One question at a time

• Always provide a default so the user can say "OK" and move on.
• Don't bundle multiple decisions into one prompt.

Challenge mismatches gently

• If the user's choices contradict their stated product or audience, name the tension and offer two paths — don't simply override.

---

Mode workflows

design 模式 — 默认

最终产物：项目根目录的 design-spec.md（含项目自己业务的设计稿验证）。

整个流程是这样的，但不是每个项目都从第一步走到最后一步。Phase 0/1 决定了走完整路径还是走捷径：

1. 看代码 + 判断阶段（Phase 0） — 必做。30 秒扫一遍项目，把它放进五档之一（空白 / 半成品 / 成熟 / 复杂遗留 / 不确定）。详细见上面"别一上来就问问题"那段。

2. 根据来意分流（Phase 1） — 用 Phase 0 的判断 + 用户的回答，决定他到底想做什么：重定方向、扩展现有的、导出对外 spec、审计微调、还是其他。走错分支比走慢更糟糕。

3. 听细节（Phase 1b） — 仅在用户要"重定方向"或"扩展"时进入。问产品、听品牌资产、问参考、问硬约束、问主要语言。不抛推荐。

4. 找意象（Phase 2） — 仅在用户要"重定方向"时进入。从意象库里给 2–4 个候选让用户选，鼓励混合（避免趋同）。详见 references/style-families/。

5. 挑具体的 token（Phase 3） — 颜色、字体、圆角、间距、阴影、动效，加上四个常被忽略的：容器策略、图标系统、装饰、语言。每项给 2–3 个选项不带星标推荐。详见 references/extended-dimensions.md。

6. 通用预览（Phase 4a） — 打开模板（references/design-preview-template.html）渲染 5 个 surface 让用户快速判断"对路了没"。这是探索，不是定稿。

7. 业务化设计稿（Phase 4b） — 真正的定稿环节。用最终 token 给用户自己业务的实际页面生成一个独立 HTML 文件。用户在自己业务画面上拍板，才进入下一步。严格契约见 references/business-mockup-contract.md。

8. 输出（Phase 5） — 只有当用户对 4b 的业务设计稿点头后才生成 design-spec.md。模板见 references/design-spec-template.md。

完整对话流程和各分支怎么走：references/design-interview.md 意象库：references/style-families/ 四个扩展 token 维度：references/extended-dimensions.md 业务化设计稿契约：references/business-mockup-contract.md 浏览器预览模板：references/design-preview-template.html

guide — Compact rules for a surface

1. Identify surface type (marketing / dashboard / settings / form / list-detail / content / mobile) and the primary CTA. 2. Apply the UX Hard Rules below. 3. Apply system-level constraints (references/system-principles.md). 4. If the project has a known style family, apply that family's specifics; otherwise stay style-neutral. 5. If icons are involved: references/icons.md.

Output: bullet do/don't list, no long paragraphs.

review — Prioritized fixes for an existing UI

1. State assumptions (platform, target user, primary task) — one line each. 2. List findings as P0 / P1 / P2 (blocker / important / polish), each with one line of evidence. 3. For major issues, label the diagnosis using references/design-psych.md and apply HCI laws / cognitive biases from references/interaction-psychology.md when relevant. 4. Propose implementable fixes (layout, component, copy, state). 5. End with a short verification checklist.

Output format: references/review-template.md. Per-surface checklists: references/checklists.md.

Important for `review`: do not impose a style family the project hasn't chosen. Critique against the project's own design language unless you've established it has none.

---

UX Hard Rules (style-independent — apply to every project)

These are not aesthetic preferences. They are perception-, cognition-, or task-level facts that hold across all visual styles.

1. Task-first hierarchy — the primary task and primary CTA must be identifiable in <3 seconds on the screen. 2. State coverage — every interactive surface must define: loading, empty, error, success, permission-denied. Missing any one is a real bug, not polish. See references/checklists.md. 3. Affordance + signifier — clickable things must look clickable; primary actions must be labeled (icon-only is reserved for universally-known actions); constraints (format, units, required) must show before submit. 4. Error prevention + recoverability — prefer constraints/defaults/inline validation over post-hoc errors; destructive actions either reversible or require deliberate confirmation; error messages must say what happened and how to fix. 5. Feedback loop closure — after any action, the UI must answer: "did it work?" + "what changed?" + "what's next?". See references/system-principles.md. 6. Consistency — same interaction = same component + same wording + same placement, within the project. Cross-project consistency is not a hard rule. 7. CRAP for visual hierarchy — Contrast / Repetition / Alignment / Proximity. These are perceptual constants, not style choices. 8. Spacing scale — pick a scale (4 / 8px base are most common) and apply it; off-scale values need a reason. The specific scale is a project choice; the discipline is a hard rule. 9. Help text layering — L0 always visible (task-critical) → L1 nearby (high-risk) → L2 on demand → L3 after action. Many L0 hints = fix IA, not add more text. 10. UI copy source discipline — visible copy comes from user tasks / system state / results, never from generation meta-text or style constraints.

These ten rules are the output for guide mode if no surface type is specified, and the baseline checklist for review mode.

---

Style Lens (project-chosen — never default-imposed)

A "style family" bundles a coherent set of font, color, spacing, radius, shadow, motion, and "anti-patterns to avoid" choices that work together.

The skill ships with eight families. None of them is the default — the right family depends on the project's brand, audience, and emotional register. See references/style-families/index.md for the catalog and references/style-families/<family>.md for each family's specifics.

Important: families are starting points, not cages. A user can pick modern-minimal and still want 16px radius. The family supplies defaults; the user always wins.

Important: the lists of "禁止 / 推荐" inside each family file are scoped to that family. They are not global UX rules. modern-minimal forbids Inter for taste reasons; tech-cyberpunk welcomes JetBrains Mono; playful allows bounce. Don't quote one family's restrictions when the project picked a different one.

---

When the user pushes back on a suggestion

Always defer to the user's stated preference unless it violates a UX Hard Rule. If it does:

• Name the rule that's at risk.
• Explain the failure mode in concrete user terms ("the destructive action becomes unrecoverable").
• Offer one alternative that preserves the user's intent.
• If they still want it, do it. The hard rules are guidance, not gates.

References

• Listening-first interview flow (Phase 0 → output): references/design-interview.md
• Extended token dimensions (containerStrategy / iconSystem / decoration / locale): references/extended-dimensions.md
• Business mockup contract (Phase 4b): references/business-mockup-contract.md
• Style family catalog: references/style-families/index.md
• Per-family details: references/style-families/<family>.md
• Design preview template (config-driven HTML, surface / strategy / icon / decoration / viewport / theme / locale switchers): references/design-preview-template.html
• design-spec.md output template: references/design-spec-template.md
• System-level principles: references/system-principles.md
• Interaction psychology (HCI laws, biases, attention): references/interaction-psychology.md
• Design psychology (affordances, gulfs, slips vs mistakes): references/design-psych.md
• Icon rules: references/icons.md
• Review output template: references/review-template.md
• Per-surface checklists: references/checklists.md

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:

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.

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").

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 各处散落？

然后判断这个项目处在哪个阶段

把项目放进下面五档之一。不同档位的开场方向不一样：

开口的两条原则

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

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.

# 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:

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:

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"
};

open /tmp/design-preview.html

To iterate: rewrite /tmp/design-config.js only. The user refreshes.

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.

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.

# [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.).

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?

A project may pick one strategy globally and override per-surface (e.g. tinted-surface everywhere except dashboard tables which use divider).

2. iconSystem

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

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

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

editorial

brutal

playful

premium-luxury

tech-cyberpunk

warm-content

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:

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.

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.

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?

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

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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?