pretty-ui

pretty-ui 是做什么的？

AI 构建的屏幕看起来千篇一律，因为没人做出任何选择。模型会用所见的最常见答案填补每一个空白，结果就是页面可以属于任何产品。

pretty-ui 按照设计师的顺序解决这个问题：选择方向，将其记录下来，然后在所有地方应用它并检查结果。 选择由人来做，从他们能看到真实选项中进行，而不是由代理独自决定。

运行流程

按顺序执行以下步骤。告知用户你当前处于哪一步。

1. 阅读项目

• 找出正在构建的内容：一个用于阅读和滚动的页面（落地页、营销网站、作品集）、一个人们在其中工作的 Web 应用屏幕（仪表盘、设置、收件箱），或一个移动应用。
• 找出技术栈：纯 HTML、Tailwind、shadcn/ui、React、Vue、Svelte、React Native、SwiftUI、Compose 或 Flutter。在该技术栈内工作。切勿迁移它。
• 寻找现有的视觉系统：DESIGN.md、AGENTS.md 或 CLAUDE.md 中的设计说明、Tailwind 或 shadcn 主题变量、品牌指南、Logo。如果品牌已有颜色和字体，请保留它们。 步骤 3 中的方向将在此品牌内部改变布局、字阶、密度和强调色，而不是改变品牌本身。
• 收集真实内容：产品名称、其功能、目标用户、真实数字、真实截图。占位内容会让每个设计看起来都千篇一律。

2. 审计（仅在已有 UI 时执行）

阅读 references/tells.md。对渲染 UI 的文件运行检查器：

node <skill>/scripts/check.mjs <文件或文件夹>

按严重性分组，列出找到的问题给用户，并附带文件和行号。添加任何检查器无法通过阅读代码看到的问题：三个相同的卡片、所有内容居中、没有清晰焦点、占位符内容。如果屏幕已经设计得很好，请说明，并建议两到三个小型改进，而不是重新设计。

3. 提供三种方向

阅读 references/systems.md。其中列出了 24 个完整的设计系统，12 个用于 Web，12 个用于移动应用，每个都有公开的 DESIGN.md。

1. 选择三个有意不同的系统：例如一个浅色且编辑风格、一个深色且密集、一个柔和且友好。匹配平台（Web 或应用）和产品的世界。绝不提供同一个外观的三种变体。
2. 从其 URL 获取每个系统的 DESIGN.md。
3. 使用相同的真实内容，构建相同的关键屏幕的每个方向版本，作为独立的 HTML 文件：
   • pretty-ui/directions/a-<slug>.html、b-<slug>.html、c-<slug>.html
   • Web 页面为 1440×900，移动屏幕为 390×844。内联 CSS、Google Fonts 链接，无外部图片。
4. 使其易于比较：
   • 如果 Codex Design 画布工具可用（例如 create_canvas 和 add_node），将三个文件放在一个画布上并排显示并打开。
   • 否则运行 node <skill>/scripts/compare.mjs pretty-ui/directions/*.html --out pretty-ui/directions/index.html 并告诉用户打开该文件。
5. 要求用户选择一个，或组合部分内容（“A 的字体加上 C 的颜色”）。如果他们让你决定，选择最符合产品的一个，并用一句话说明原因。

当品牌固定时，三种方向使用品牌的颜色和字体，而在布局、比例和密度上有所不同。

4. 写入系统

• 将选定的系统保存为项目根目录下的 DESIGN.md。保持其格式：YAML 前置元数据包含令牌，然后是概述、颜色、排版、布局、形状、组件以及应做与不应做事项。
• 将用户要求的任何更改（品牌颜色、不同的标题字体）应用到该文件中，而不仅仅是应用到代码。
• 向 AGENTS.md（如果项目有，也向 CLAUDE.md）添加一行：对每个屏幕遵循 DESIGN.md：颜色、类型、间距、圆角和组件。 Codex 会自动读取 AGENTS.md，但不会读取 DESIGN.md。
• 对于 shadcn 或 Tailwind 项目，将令牌映射到主题变量（--background、--primary、--radius 等）。每个系统页面都链接了一个准备好的 shadcn 主题：npx shadcn@latest add https://codexdesign.io/r/<slug>.json。

5. 逐轮应用

像设计师的红线审阅一样，一次一层地处理整个屏幕。除非用户另有要求，否则保留功能、内容和章节顺序。

1. 令牌。 将硬编码的颜色、大小和圆角替换为系统的令牌。
2. 排版。 最多两个字体家族。使用系统的字阶。确保屏幕上最重要的一行文字明显最大。数字使用表格数字以对齐。
3. 间距和布局。 使用系统的一个间距单位及其倍数。将所有内容对齐到网格或屏幕内边距。紧密关联的内容组合在一起，不同组之间留出充足间距。
4. 颜色。 中性色承载屏幕。主要颜色出现在用户操作的位置，每个视图大约一次。图表按顺序使用系统的图表颜色。
5. 组件。 按钮、输入框、卡片、列表和导航遵循系统的“组件”部分。使用真实图标（Lucide、Phosphor、SF Symbols、Material Symbols），绝不要使用 emoji 作为图标。
6. 文案。 来自产品的简洁、具体的词语。删减填充词（“无缝”、“解锁”、“赋能”）。标题说明该事物是什么或做什么。
7. 细节。 悬停、聚焦和按下状态；空态、加载态和错误态；文本对比度至少为 4.5:1。
8. 动效。 仅用于解释某些内容：状态变化、屏幕之间的过渡。不要在每个部分都做淡入效果，不要使用脉冲装饰。

对于移动应用，还请阅读 references/app.md。

6. 检查

• 对更改后的文件再次运行检查器，修复所有错误和尽可能多的合理警告。
• 查看结果。如果 Playwright 或浏览器工具可用，请截取 1440 和 390 宽度（或应用的设备尺寸）的截图，并修复看起来不正确的内容：无焦点、空间拥挤、文字换行不佳、对比度低。
• 对于重新设计，编写一个用户可以分享的“前后对比”页面：

node <skill>/scripts/compare.mjs before.html after.html --labels "Before,After" --out pretty-ui/before-after.html

7. 报告

简要告知用户：选择的方向及其原因、更改的文件、检查器前后的发现，以及任何仍需他们决定的事项（真实照片、Logo、只有他们能写的文案）。

始终适用的规则

• 在确定一种方案前展示选项。切勿默默选择样式。
• 保留用户的品牌、内容和技术栈。
• 每个产品一个设计系统，写入 DESIGN.md，并在所有地方遵循。
• 除非用户明确要求，否则不要使用紫色或紫罗兰色渐变、渐变文字、玻璃态面板、发光阴影、emoji 图标、每个标题上方的药丸徽章，或成排的相同图标卡片。
• 不要用一种陈词滥调替换另一种。奶油色搭配衬线字体和赤陶色强调色，或近黑色搭配一种酸性绿色强调色，是新的默认；仅在产品世界需要时才使用它们。
• 去掉装饰就完成了一半工作。用真实内容填充空间，为重要的内容使用更大的字体，以及一个取自产品本身的令人难忘的元素。

文件

• references/systems.md：24 个设计系统，包含平台、风格和 DESIGN.md 的 URL。
• references/tells.md：什么让 UI 看起来像 AI 制作的，以及应如何做。
• references/app.md：针对 iOS、Android 和跨平台应用屏幕的规则。
• scripts/check.mjs：用于在 HTML、CSS、JSX、TSX、Vue 和 Svelte 文件中检查 AI 痕迹的静态检查器。需要 Node 18+，无依赖。
• scripts/compare.mjs：编写一个 HTML 页面，并排显示多个屏幕，用于选择方向或展示前后对比。