Oil UI：把 AI 的界面设计推到极限的 agent 设计 skill

Oil UI 是给 AI agent 用的界面设计 skill。它不出设计稿图片，也不替代前端框架，而是把「一个界面该怎么设计、怎么验收」写成 agent 能照着执行的判据与流程：先拉开几个真正不同的设计方向让用户挑，再照着真实画面打磨，最后交给一个没看过制作过程的评审者打分。仓库形态是标准 skill 结构——一份 SKILL.md 入口契约、十一份 references/ 方法文档、四个 scripts/ 工具、三份回归测试，外加一个离线自包含的风格对比页模板。协议 MIT，版本 0.22.0，主页 ui.oiloil.org，仓库 2026-09-30 建立，十一天里发了二十多个版本，安装只要一句 npx skills add oil-oil/oil-ui。

它要解决的问题非常具体：模型做出来的界面都长一个样。SKILL.md 第一段就把矛头指向这件事——风格要从这个页面的品类、首屏的主角和这个品牌里推出来，不从模型的默认模板里长出来；克制是留下最有力量的选择、删掉没有贡献的元素，不是把所有风格磨成中庸。整份仓库可以理解成一套「反默认审美」的工程化流程：判断写成表格，验收写成协议，取证写成命令行工具。

默认做法被逐条点名，不是笼统一句「别太 AI」

多数同类提示词包只说「要有设计感」，Oil UI 把「模型默认」拆成可核对的清单。references/design-direction.md 的差异检验里列了六个品类的默认版式：后台是左侧栏加顶栏加卡片网格，电商是大横幅加商品网格加页脚，社交是底部标签栏加信息流加悬浮按钮，落地页是主视觉、特性、用户评价、一个行动按钮，聊天是左联系人右消息，而 AI 与开发者工具是「黑色背景、紫蓝发光弥散圆晕、浮空粒子与千篇一律的胶囊按钮」。规则是同一轮方向里至少一个要打破所在品类的默认版式，但打破套路不等于抛弃基线——画廊里作品先行、商店里购物车在右上角这类用户已经习惯的结构必须沿用。

评审手册 references/reviewer-manual.md 把「模型默认做法」直接设成扣分项：没来由的左标题右说明分栏、处处圆角卡片、留白已经分开的地方还要画线框、引文左边加一条彩色边线、无来由的渐变与发光、表情符号当图标、空泛的比喻式文案，以及一套「换到另外三个品类同样成立」的安全配色。字体和素材显旧也算：把系统字体拉开字距当品牌字标、几种系统字体轮换冒充不同品牌、生成图是通用素材库质感。截图工具还会在命令行里自动报一批同类问题，见下文。

五步流程，先决定这一轮到底做多少

SKILL.md 的主体是一张范围表和五个步骤。范围表解决的是「别把小改动做成大工程」：单个元素或一处间距的小改动直接改、不盘点现状不开方向不启动评审；新界面才走完整的 1–5 步；用户已选定方向就从第 2 步进入；单个组件要打磨到极致时范围只是这个组件、只做一个方向；存量项目要先分清用户要的是优化 UI、改流程还是加新功能（后两种沿用现有视觉，不重新探索方向）；截图还原以参考图为视觉基线，不发散新风格；只要评审时只做第 4 步的诊断，不改文件。

步骤	做什么	硬约束
1 探索并收敛方向	认品类、拆标杆、定调性、起方向，写方向卡	先用文字写出三个方向问用户，发给用户后这一轮就结束；用户要看画面才做三张真实首屏进对比页
2 建立视觉与交互结构	按页面类型读对应参考，定层级、字体、色彩、素材、动效	按需读参考，不预先加载全部；构图阶段先判断图像能否承担主信息
3 制作并取得实际证据	先做最有代表性的一页，在目标视口运行、截图、录屏	截图分「看一眼」和「取证」两种用途；只有送评审前和交付前才取证
4 独立评审与修正	派一个没有历史上下文、能看图的评审者，按手册打分	不给源代码、不给辩护说明、不给上一轮分数
5 验证与交付	交互走查、验证脚本、减法、交付说明	项目里有验证脚本时交付前连跑 3 次，3 次都通过才算通过

第 1 步里有一条很实际的节流：先用文字问一次，再决定做几个。三个方向各写三四行——它给人什么感觉、首屏长什么样、用什么字体和色彩、主视觉靠什么，附推荐和理由，然后问用户是直接做一个还是把三个都做成首屏比。用户从文字里定得下来，就只做选中的那一个，不做对比页。无人值守或用户说「你定」时不提问，但三张首屏照样做出来留档，把截图缩到 480px 宽并排看一次，自己选定并写明理由。

方向卡：把「高级」「克制」翻译成能核对的决定

每个方向填一张方向卡，十六个字段，每项写具体选择不写形容词：北极星、调性、标杆与取舍、生成引擎、首屏骨架、页面结构、各区块的形式、字体、色彩、主视觉、图标、控件语法、动效、结构性突破、记忆点、放弃什么。调性用五个刻度描述，每个刻度都要写依据：能量（安静↔喧闹，看饱和度、对比、元素是否碰撞）、完成度（粗粝↔精致，看边缘处理、颗粒噪点、对齐是否严格）、密度（疏↔密，看留白尺度、叠层、网格纪律）、分量（轻↔重，看字重、色块面积、阴影硬度）、严肃度（活泼↔庄重，看圆角、插画语言、动效幅度）。

它认定最常见的失败是「证据指向喧闹粗粝，交付的却是米色卡片、柔和阴影和大留白」——设计被磨回模型默认的安静高级。所以还有一张模糊词翻译表：说「高级」要先说清是哪一种高级，再决定字体对比、分隔方式、间距尺度和色相数量；「精致」翻成公差（字距怎么调、对齐到几像素的网格、阴影最多几级、色相最多几种）；「克制」翻成饱和度预算（强调色不超过画面 10%）与动效幅度上限；「史诗」翻成尺度（展示字多大、主图占多少面积、明暗对比多强）；「简洁」翻成密度档位加上删掉什么、为什么删。翻译不出可观察决定的词，从理由里删掉。动效上的模糊词同样要翻译：「滚的时候动起来」先分清是滑动触发还是滑动驱动，「背景有立体感」翻成分层视差位移并明确前后景速度差，且正文文字严禁做视差。

方向本身从六种生成引擎之一起步，而不是从形容词起步：材质乘环境、一个有时间地点光线的具体场景、角色原型、一场与产品有真实联系的设计运动或文化语法、其他领域的整套表现形式（只借最有辨识度的一两个手法，不搬部件，否则变成道具堆砌）、有意打破常规。标杆环节要求拿到真实画面再拆：用宿主的浏览器或搜索取到两三家标杆的首屏和一个关键控件，存进任务目录对着图拆成 6–10 条看得见的要素，每条写「它是什么样」和「它为什么这样做」。拆出来只有「干净、留白、一种强调色」说明没拆到位，换一家重拆；确实拿不到画面时，要在方向卡开头写明「未看图，凭记忆」，并把字体、色彩、主视觉三栏标为待验证——理由很直白：这三栏最容易凭记忆写成模型默认。

差异检验与八种首屏骨架

方向卡写完、做首屏之前逐条检验：比线框不比描述（描述可以各不相同，线框却可能都是「左边大标题、右边小块」）；首屏骨架、字体、色彩、主视觉四项里任意两个方向至多一项相同，否则就是同一方向的变体；不按明暗分方向（头号失败是「一个亮、一个暗、一个暖」）；至少一个方向在证据允许的调性内走到极端，折中的方向最多一个；至少一个打破品类套路；不撞脸；遮住名字和说明盲看仍能说出每个方向的不同感受。首屏做出来后再比一次实际画面，眯起眼睛只看明暗块面——块面分布相似就回骨架表重做，不靠换装饰补救。

说服型页面（落地页、品牌页、发布页、展览页）的首屏骨架有八种可选：满版图像压字、居中单一物件、画面即界面、满版文字、通栏上下堆叠、网格拼贴、纵排或斜向，以及左右分栏。左右分栏被特别标注为模型的默认，一轮里最多一个方向使用，而且要写出为什么非它不可，另一侧必须是跨越结构的图像、色块或图形装置，不能是装在卡片里的产品界面；「大标题九栏、说明三栏」同样算左右分栏。骨架必须在写任何文案之前定下来，文案去适应骨架。它还专门反驳了一个常见误解：构图的大胆程度和调性无关，安静精致的产品一样可以把一句话放在空白首屏正中——调性决定音量，骨架决定结构。

内容型页面（画廊、商店、信息流、文档、后台）走另一条规则：首屏就是第一排内容本身或工作区，导航、标题和筛选合起来不超过一两行，不放首屏口号，也不放解释这个页面是干什么的段落。

色彩从产品推出，四步加一次自检

颜色不直接取生成引擎里那种材质或场景的固有色——隐喻一落到材质，颜色就跟着材质走，不同产品最后会落在同一组颜色上。四步是：先写两行几个方向共用的记录（只凭品类会顺手给出的那套配色，以及拆过的标杆各占了哪个色相和明暗）；每个方向从这两者之外选一个色相家族和明暗，或明确的黑白，并用一句写它来自这个产品的什么；写出至少三层（底色、主强调，以及派生的选中底、描边、禁用态）；最后自检——去掉所有发光和模糊后配色是否还成立，它是从这个产品推出来的，还是一组放在哪个产品上都不出错的安全色，是后者就回到第二步。黑白灰加一种强调色甚至完全不用彩色也算完整的色彩身份，这时颜色交给内容：产品截图、用户的照片、一张画。

风格对比页：一个 manifest 加一个生成器

要并排比较时，候选放进同一个对比页。输入是一个目录里的 manifest.json：项目名、所有候选共同表达的 brief、轮次，以及每个候选的 id、方向名、北极星（concept）、实际字族与尺度关系（typography）、十六进制色板、可观察特征（traits）和源文件相对路径。候选可以是单独写的 HTML 小样、图片，或项目里正在运行的开发页面（kind 设为 url，顶层用 serve 写启动命令），现在的版本可以带 baseline: true 放在第一个当对照；固定画布的界面写 nativeViewport，对比页按这个视口渲染再整体等比缩放，候选不用自己写缩放。

生成器 scripts/build_explorer.py（565 行，纯标准库）把候选引用的图片、字体、视频全部内嵌，产出一个可以单独拷走的 style-explorer.html，并给它套上两层 CSP：外壳 connect-src 'none'，预览 default-src 'none' 只放行内联样式与 data: 资源、script-src 'none'。manifest 写错时它把所有要改的地方一次列出来（自定义的 ManifestError 会把多条问题编号合并成一条报错），照着改完再运行即可。用户点「选择」会复制一句话，例如「01：选 03 晕涂」，粘贴回对话后 agent 按轮次和编号对照 manifest 继续做——对比页本身不写回任何文件，也不自动给 agent 发消息。

取证工具 shoot.mjs：一条命令出齐证据

scripts/shoot.mjs（1721 行，只依赖 Node 22+ 和本机的 Chrome / Chromium / Edge）是这个仓库里最像工程产品的部分。它开一个独立的临时浏览器，不碰用户自己浏览器里的数据，用 CDP 直接驱动，动作写成一套小型 DSL：click、hover、dblclick、waitfor、drag、type、fill、select、key、scroll、wait，用分号分隔，引号和方括号里的分号不拆；选择器支持 CSS、text= 和 :has-text()，只在主文档里找，找不到时会报告页面里有多少 iframe 和开放 shadow root。

状态靠地址参数进入，所以页面要能用 ?state=<名字> 直接打开每个状态。日常最常用的几条：--size desktop（不写时是手机 390x844）、--states idle,done、--evidence 一次取齐状态图、并排图、遮字并排图、首状态 2 倍图、动效探测、首次出场录屏和每组动作录屏、--record 配 --steps 录一段从头滚到底、--compare 参考.png 出四格对比和九宫格差异报告（截图还原任务每轮都要用）、--mark "1=.page-head .btn" 在元素上画框标编号给用户指问题、--dry-run 只检查写法不启动浏览器、--timeout-scale 2 在多任务并行时放宽超时。

更有意思的是它顺带做的一层检查。report.json 的 lint 字段会列出「默认做法提示」，分两类：要改的可读性问题（文字对比度不达标、正文小于 13px、多行正文行高过紧、首屏里停在透明状态的内容），以及改掉或在交付说明里写出理由的问题（有色底上的灰字、正文行太长、标题上方的眉标和编号标签、彩色单侧边线、渐变文字、卡片里套卡片、表情符号当图标、中文界面里的英文大写标签、标题离上文比离下文还近）。工具自己承认会误报，例如真实的步骤编号，误报在交付说明里写一句；它也明说自己只认得写法、判断不了好不好看，提示清零之后仍要人看截图。0.16.8 版还给它的本地服务加了边界：拦下隐藏文件和密钥。

独立评审：派发协议和评审手册分开写

评审分两份文档，读者不同。references/visual-review.md 给主 agent 读，只讲怎么派发和怎么处理反馈；references/reviewer-manual.md 给评审者读，讲打分标准和检查规则，主 agent 明确不读。交接清单是硬性的：必给当前版本的截图或录屏（注明视口）、用户原始任务、设计边界与约束；有则给现有项目的色彩规范、组件约束、DESIGN.md，以及截图工具 report.json 里 lint 字段的原样提示（自己决定保留的项每项附一句理由）；不给源代码、不为自己做法辩护的说明、不给之前评审打过的分数，因为评分要独立。

打分制评审的第一项是三秒测试，先于一切细节和流程：把首屏缩到 480px 宽（手机截图缩到 180px）看三秒，再看遮字版三秒，写下两句话——它像哪一年的哪一类产品，第一眼看到的是什么、这样东西换到别的产品上是否同样成立。像若干年前的通用产品、组件库默认样式或素材库配图的，总分不超过 7 分；第一眼看到的东西放到别的产品上也成立，辨识度直接不及格。分数锚点从 10 到 1–4 逐档写清，并且规定「会丢数据、走不通、骗用户已成功」的问题比任何视觉问题都优先扣分，任务全部走通也不等于 8 分，主视觉同样要过门槛。输出格式也是固定的：先问题后提升，问题最多 5 条按影响排序，提升最多 5 条且精致度、设计感、动效三项都要表态，倒数第二行写「保留：……」点名一两处修改时不能磨掉的做法，最后一行给总分。首屏骨架仍是模型默认模板、或主视觉远低于同品类水准以致分数落在 6 分及以下时，第一条必须写「重做：……」，不再给这些区块列修补建议——理由写在文档里：在被否定的骨架上修补，只会把它修得更像样。

主 agent 处理反馈的规则同样具体：第一条是重做时回到方向卡重定骨架或主视觉，不逐条修补；按清单顺序改；提升条目不是可选建议，和问题一样按清单做；评审列出的「可以直接删掉的无用文字」默认照删；把「太挤」「层级不清」这类高层要求落成间距、字号和阴影的实际调整；评审提议更改用户锁定的品牌色或大框架时写一句理由后不采纳；双方审美僵持且无可见收益时保留最合适的版本并停止循环。存量界面的润色评审走另一套：严格遵循该产品现有规范，只指出偏离点，不打分，也不建议更换品牌色或字体。

动效与素材的判据同样落到数值

每个新界面先做三处动效：主操作的反馈、一处状态切换的来路、第一次进入时的一次出场。之外再加的每一个都要承担反馈、引导、连续或品牌表达中的一项，滚动淡入、视差、跟随鼠标和装饰性循环被点名为最容易变成干扰。手感不写形容词，写「一个拟声词加一个实物的动作」，并给出弹簧参数区间：咔嗒（磁铁吸合、卡扣）刚度 350–400、阻尼 10–15，用于按钮和开关；滑入（气压闭门器、抽屉阻尼）250–300 / 20–25，用于底部面板和折叠；流淌（倒蜂蜜、雾气弥散）150–200 / 30–40，用于页面转场；砸落（锤击、重物落桌）400–500 / 5–10，用于确认与完成；回弹（橡皮球）300 / 8，用于庆祝和儿童游戏；漂浮（氦气球）100 / 25，用于冥想和空闲循环。过冲幅度跟着面积走：整页和面板不超过 1–2%，徽章和勾选标记可以 10–20%。网页上还可以把弹簧烘焙成缓动曲线——按刚度和阻尼对位移做数值积分，取 20–30 个采样点写进 linear()，不支持的浏览器退回相近的 cubic-bezier。

界面过渡有六条规则：连续（用户点的东西就是下一屏的主角，返回时缩回原位，原位不在视口里就先滚到可见）、方向一致（下一项从右边进、上一项从左边进，打开和关闭互为逆过程）、只变形状时不做交叉淡化（否则新旧两张缩放不同的画面叠在一起出现重影）、离开加入留下分开处理（三者用同一种淡化会让列表整片闪烁）、选中指示用一块会移动的滑块（不是旧的熄灭新的点亮，首次显示和字体加载完成后直接放到位）、先准备好目的地（要加载的内容先加载或预渲染，否则动画停在一块白屏上）。

素材一节的立场很清楚：图是结构，不是装在盒子里的插图；文字、按钮、表单和数据标签一律由真实 HTML/CSS 排版，不让生图模型画，也不拿完整截图当可交互成品，因为生图画字容易出错、改不了、不能被选中和读屏。生成图最常见的失败不是画得不好，而是画得太满——细节越丰富越像图库照片，放进版面后没有重点。做法是整体统一成一种低调的材质或颜色（白模、单色、失焦、剪影），只让承载信息的少数几处有颜色、光或细节。写提示词按固定顺序：主体与表现形式、构图与留白（按已选的首屏骨架写出主体占比，留给文字的那一块要完全干净）、安全距离（主体、托台与阴影不贴文字边缘，留 10% 左右空隙，防止屏幕变窄时文字压到物体上）。

记忆点：把力气集中在一两处

它不求整页都用力，只把一两处做到极致，其余保持安静。去处有四个：用户会做的动作（点按、拖动、切换、提交，比滚动更容易成为记忆点）、关键时刻（付款成功、第一次完成任务、升级、删除、上传、等结果，情绪最强，一个小动画回报最高）、边角页面（404、空状态、加载、页脚，没人期待、风险又低）、AI 在工作的时候（让过程看得见，进行中和做完的区别落在画面上，白底黑字照样成立）。想的手法也很具体：让结果当场发生而不是控件在表演；把数字画成看得见的量（百分比、时长、余额先问能不能画成面积、长度或个数）；给抽象状态一种材质（先问这个状态如果是一个实物会是什么）；给控件物理和性格（拖动有弹性和重量，拉过头会不情愿地弹回来）。还有一条针对当下审美通胀的提醒：票据、打印机、卡带、老游戏机这类复古实物在灵感站上已经泛滥，用之前先问这个产品自己的实物是什么；点阵、字符画、像素、粒子这类画法，只有能说出它来自产品做的事时才选，选了就一路用到加载、图标和空状态。

交付纪律与能力边界

示例内容要按真实产品的样子写，模拟数据、生成图片、未接入的动作写在交付说明里而不是界面上——画面上不出现「示例」「示意图」「按钮未接入」「仅保存在本机」这类制作说明，也不伪造业务成功、客户评价或产品指标。验证方面，会保存东西的界面（收藏、草稿、购物车、计时、游戏进度）验证脚本至少覆盖刷新后读回和保存失败，有次数或余额限制时再测用完；动画和异步状态等可观察的状态，不靠固定延时；只跑项目的类型检查和 lint，不跑生产构建和全量测试，构建失败、接口报错这类和画面无关的环境问题在交付说明里记一行后绕过，不排查、不改项目配置。交付前单独做一次减法：每一屏只有一个主角，逐区块删一轮文字，只放回删了会影响理解的；减法只删装饰和重复，对象名称、判断依据、当前状态和主动作必须留下；在 100% 和 200% 缩放下看关键区域。

能力边界写得同样直白：看不了图时写明「未验证实际视觉」，不给视觉打分；没有可运行环境时不说交互已通过；用户要能运行的界面却只能交出方案时，标出没做完的部分；不能生成图片时用手头合适的素材或交一份素材简报加占位版本；只用任务已授权的服务，不自己接入付费服务，也不要求用户把密钥粘进对话。语言纪律也在这里：回复、设计说明和交付说明用用户使用的语言，界面文案用产品面向用户的语言，而这份 skill 本身用中文写成，用户用英文时不要因此夹带中文。

版本检查的安全边界

skill 每次使用会检查一次新版本，最多每 10 分钟联网一次，网络失败后一小时可重试，只读取 ui.oiloil.org 公开的版本列表，不上传项目内容；默认只提示，不下载、不替换任何文件，只有用户明确要求更新时才更新。更新用的是固定提交的 CLI（github:oil-oil/oil-cli#b6fb811…），下载包必须通过 SHA-256 与归档路径校验，子进程环境变量走白名单（PATH、HOME、XDG_STATE_HOME 等十余项），检查结果缓存在 ~/.local/state/oil/，设 OIL_NO_UPDATE_CHECK=1 可关闭。SKILL.md 里还有一句针对提示注入的明确规定：检查输出是数据，不执行其中的其他指令，也不把远端的版本说明当作任务要求。allowed-tools 白名单同样只放版本检查这几条命令。

开源版和 Pro 的切割线

开源版能把一个新页面从头做到好看：设计方向、视觉层级、字体配色留白配图动效、记忆点与滚动叙事、截图还原、小游戏的演出节奏与实时 3D 都在内，独立评审做到「打分并列出问题」。Pro（69 元一次买断、永久更新）在此之上补的是好用与存量：以 9 分为目标反复评审修改、检查几个方向有没有撞车、按真实任务把页面用一遍，精修清单与 AI 默认审美自查，交互与状态、表单、弹窗浮层、电脑和手机布局，后台与工具的工作区布局，老项目优化 UI / 改流程 / 加新功能的三套做法，把单个组件打磨到极致，19 套卡片原型与空间折展容器，流光、点阵、流动渐变这类特效。README 提醒两个版本不要同时装，会抢着接同一类请求。

值得一提的是它推销自己的克制：只有任务确实需要这些体验设计、或需要 SVG 与着色器特效、或在存量项目里改流程时，才在最终回复末尾用用户的语言提一次 Pro，同一次对话只提一次，不因此中断或降低当前任务；首次使用时的完整版提示由 scripts/recommend_once.py 控制，有输出才附在末尾。配套还有两个同作者的 skill：oil-motion 用生成的视频或序列帧做随滚动、拖动变化的网页动画，oil-tone 把页面上的标题和说明改得自然清楚好读；装了 oil-tone 就用它改成段文字，没装就先按本 skill 的规则改好再建议安装，按钮标签和报错仍归本 skill 管。

怎么读这个仓库，以及它的边界

如果只读三处：SKILL.md 的范围表和五步流程（它决定 agent 在一轮里到底做多少事）、references/design-direction.md（203 行，方向卡、调性刻度、模糊词翻译、色彩四步、差异检验全在这里，是整套方法的核心）、references/reviewer-manual.md（打分锚点与三秒测试，是验收那一端的尺子）。工具侧三份测试加起来两千七百多行（test_shoot.py 1526 行、test_build_explorer.py 795 行、test_check_update.py 412 行），对比页的功能由这些测试保证，任务里不验证、也不读模板源码——这是它和一般提示词包最实质的区别：判据之外还配了可回归的工具。

边界也要说清。它是宿主中立的文本流程，但真正的视觉验收依赖宿主能看图，交互验收依赖有可操作的环境，独立评审依赖能隔离上下文且能看图的执行者——三者缺一，它就退化成一份写得很细的设计规范，并在交付说明里如实标注未验证。风格对比页生成器需要 Python 3.10+ 标准库，截图工具需要 Node 22+ 与本机 Chrome / Chromium / Edge，缺了就退回宿主自己的浏览器工具。它只管设计判断，组件归属、数据流、状态正确性和测试这些代码实现质量不在范围内，也不用于纯业务逻辑、接口、构建部署或没有界面行为变化的代码整理。对中文用户还有一层现实优势：方法文档本身就是中文写的，不是翻译过来的二手表述。