Oil UI: A Design Skill That Forces AI Agents to Escape Default-Template Interfaces
This Open-Source Design Skill Pushes AI's Design Capabilities to the Limit (Oil UI)
Author: oil欧哟
Many friends often use AI Agents to write web pages or build application interfaces, and they frequently run into two situations.
The first is when making a single page: if you simply tell it, "Help me make a website for a product, make it look nice," the resulting page often carries a heavy default-template feel.
Besides the early blue-purple gradients and left-right columns, current models also really like to add a small English pill label above each heading, with a gray explanatory subtitle below that carries no actual information, and then nest a small card inside a large rounded-corner card. As long as you don't give specific constraints, it falls back to this safest, most error-free style.
The second situation is that even if you barely get the first page right, once you start a new conversation to continue writing the second page, or go back and forth editing an old project, the button corner radii, spacing, and color schemes start getting messy again.
A while ago, I organized the workflow I usually use for building interfaces and open-sourced a design Skill called Oil UI. Around the same time, I also built a gallery site at ui.oiloil.org to showcase interactive works generated by different models. Later, while maintaining several multi-page projects and reviewing existing projects with user feedback, I added continuous governance for complex engineering. This article combines the ideas from previous video discussions, explaining my considerations when designing this workflow and how I use it day to day.
Four Core Design Principles
1. Don't Lock to a Style; Route by Page Type
When I first started building the design Skill, there was actually an easy approach: hardcode a preset set of colors, fonts, and card styles directly into the prompt. As long as that preset is decent, even a weaker model would produce a single page that doesn't look too bad on the first try.
But this approach has obvious problems in real business contexts. An aromatherapy lifestyle site, a desktop productivity tool homepage, a surfing weather mobile app, and a monitoring admin dashboard serve completely different use scenarios. If you force them all into the same minimal template, the pages all look identical, and many features simply can't fit.
So I set Oil UI's approach to not bind to a fixed style, but to split landing pages, content browsing pages, and admin workspaces into multiple reference guides. The AI Agent first understands what problem the current page needs to solve, then reads the corresponding rules on demand.
Because different page types often have opposite requirements. Landing pages need prominent visual focus and can afford bolder layouts; admin dashboards and workspaces value information density and operational convenience, with the focus on thinning the top bar, removing excessive thick borders and descriptive small text, and leaving only one primary visual focus per screen.
For example, the following is a multi-agent task management workspace I use daily. When building it, I didn't apply any promotional page's big titles or gradient cards. Instead, I lightened the borders and background, letting the pending tasks themselves fill the first screen:
After splitting rules by scenario, when building a landing page, it doesn't read the dashboard rules; when building a dashboard, it doesn't read the promotional page rules. This avoids stuffing irrelevant content that could confuse the AI Agent's judgment.
2. Compare Directions First, Keep the Choice with Humans
One of the most time-consuming parts of using AI for design is constantly tweaking a first draft you're not satisfied with. If the initial layout foundation is mediocre, no amount of detail adjustment later will make it look good. But if you just need to add an ordinary page to an existing project, generating three options every time is too slow.
So I split this step into two situations. For routine pages, it first gives one recommended direction based on your needs, and only after you confirm does it write code; when you're working on a new product and aren't sure about the style, or explicitly want to compare different approaches, it produces three interactive pages and puts them into a built-in local comparison page (style-explorer.html) for you to choose from.
Previously, without constraints, telling the model to "randomly generate three unique options" often resulted in three versions with similar layouts, just different light or dark backgrounds.
So I added a rule: among the generated multiple options, in the four dimensions of layout skeleton, font pairing, color, and key visual, any two options can share at most one item. For example, the following comparison page was generated for the same Orvo brief, using three different compositions and color schemes: a pushed-open light gate, an acid green background with a blue chair, and a tandem bicycle.
I also used this approach when redesigning the homepage of my tutorial site 《Oil Book》. I wanted to merge the bookshelf and recommended models into the homepage. It explored three directions side by side: the first was four columns of vertical book covers first, followed by four tool tags; the second was an open notebook with a standing bookshelf; the third compressed the models into a top row of bookmarks, leaving space for a new-book showcase.
On the comparison page, clicking the "Single" mode in the top right corner lists the current option's color values, font pairing, and feature descriptions. You can also toggle between desktop and mobile size previews. When you like a version, clicking "Select" copies the instruction, and pasting it back to the AI Agent lets it continue writing the actual code into the project.
3. Handling Existing Spec Conflicts and Drift During Revisions
A user once sent me a screenshot saying that even with Oil UI, the interfaces still looked messy: the first Dashboard page used small rounded buttons, but the second appointment page turned into capsule-shaped large rounded buttons.
I looked at his project and found those were very basic issues, caused by the project's original specs being a mess.
His repository simultaneously had DESIGN.md, AGENTS.md, README.md, and brand spec files. Each file stated different style requirements, and the CSS implementation in the code didn't match the docs. When the AI Agent (especially weaker models) wrote new features, it didn't know which document to follow, so the result naturally looked patchy.
Besides spec conflicts, when converting prototypes from the comparison page into real engineering code, and during multiple rounds of revision, AI Agents commonly showed three problems:
First, hardcoding fixed widths and heights. When writing code from a prototype, it loves to set fixed pixel dimensions for buttons or cards. On large screens it looks fine, but switching to a small screen or changing a few words distorts the button proportions. So I added a rule to prefer padding and flexbox layouts, and not mechanically copy the prototype's fixed dimensions into the project.
Second, overriding common component styles in a single page. Even when the project has already extracted a generic button component, the AI Agent often writes new styles directly in the current page, overwriting the component's original styles, making maintenance painful. The current rule requires it to go back to the original component and add variants, not override styles privately in a single page.
Third, back-and-forth revisions. When we give feedback like "it lacks focus" or "it's too crowded," it changes one place but sometimes reverts the top bar and colors that were already tuned in the previous round. Or in round 2 it deletes content because it's crowded, then in round 4 it feels too sparse and one screen can't show enough data.
To address these, I added an existing-spec reconciliation and consolidation mechanism: when taking over an old project and finding doc conflicts, first don't touch business code; list the conflicts for confirmation, then consolidate them into a single DESIGN.md of about 100 lines in the project root. Before revision, first verify confirmed parts. If three consecutive rounds give contradictory feedback, stop local tweaks, keep the color scheme, and provide two small samples with different skeletons.
After selecting the first direction for the Oil Book homepage on the comparison page, and writing the rules into the project's DESIGN.md before implementing the real Next.js code, subsequent additions like the "Blog" and "Model Recommendations" sections kept the paper background, book cover proportions, and card borders consistent across the site.
4. Split a Context-Free Sub-Agent to Review by Image
During testing, I also encountered a common situation: once the Skill files grew, the main Agent considered the task done after writing the basic layout, and requirements like scroll animations or narrow-screen margins, which were written later in the prompt, often got skipped. Asking it to self-check didn't help because it carried the context of writing the code, making it hard to spot issues.
Initially, I wrote the rule as "for complex tasks, dispatch a sub-agent (a new assistant without previous conversation history) to do a review on demand." In internal 6-group comparative tests, when letting the model decide whether to dispatch a reviewer, it didn't dispatch any in 6 out of 6 cases (0/6).
So I changed the division: the review spec is separated into its own file, which the main Agent doesn't need to read (saving context). But after completing the representative page, it must by default start a sub-agent with a blank context, sending only the desktop and mobile screenshots taken from a real browser, and asking it to find flaws and score on a 10-point scale. When Node.js and Chrome or Edge are installed locally, the screenshot script runs automatically in the background. If the environment can't take screenshots or the model doesn't support image input, it honestly states in the delivery notes that visual verification wasn't performed, rather than making up a score.
With the default-mandatory dispatch, the review dispatch rate went from 0/6 to 5/6; in 3 groups of blind tests on the same topic with identical conditions, the version with independent review won all three (3 wins, 0 losses).
But the cost must be stated clearly: with screenshot review and rework, creating a new page consumes roughly 2.3 times the original tokens and takes about 25% longer. So I didn't let deeper multi-round polishing run automatically; instead, at the end of delivery, it lists up to 3 numbered options with approximate costs, and you reply with a number if you want to continue.
Daily Usage
The Skill is essentially a local folder containing documentation and helper scripts. After installing it into your AI Agent's skills directory, you can use it directly in a new conversation without manually running scripts.
Run this command to install the free MIT-licensed version (or send the repository link https://github.com/oil-oil/oil-ui to your AI Agent to have it install; there's also a Pro version for deep overhauls of complex existing projects, just install one of them):
npx skills add oil-oil/oil-ui
1. Creating New Pages and Mixing Different Options
When creating a new page, just tell the AI Agent in everyday language what the product is, who it's for, and the main operation on that page. If the host supports image generation, it will also ask whether you want to generate a UI design image first before writing code.
To see multiple possibilities from the start, you can write:
Please use oil-ui to explore three design directions for my [product name and main purpose] that differ in fonts, colors, and layout composition. Use bold layouts, don't limit yourself to conventional centered symmetric layouts, and generate a comparison page for me to pick from.
Once you have the comparison page, besides selecting one option, you can also combine the strengths of two options.
For example, when I built the homepage for my Mac file search tool, I liked the first screen layout of the second option but also wanted the interactive search box from the first option where you could type and try it. I sent the AI Agent: "Use direction two as the base, merge direction one's interactive search box in, and after finalizing, write the rules into DESIGN.md." This saved a lot of verbal description later.
2. Organizing Old Projects and Pinpointing Elements
If your old project already has many pages and styles that aren't uniform, don't rush to change specific functional pages. First, have the AI Agent sort out the spec conflicts:
Please use oil-ui to check the project's existing design documents and style files. List the places that conflict or are inconsistent with the page code for me to confirm. Don't modify business pages at this step.
When optimizing a specific page in an existing project, it's best to state what cannot be changed first, for example:
Keep the current brand colors, logo, and left navigation bar. Use oil-ui to optimize this settings page's form hierarchy and mobile display.
If the overall page doesn't need major changes and you just want to adjust a specific button's color or spacing, name the element directly, and it will change it immediately without running the whole comparison flow.
Sometimes a page has many elements, and typing "the gray small text under the second card in the top right corner" can easily point to the wrong place. For this, I use an open-source browser plugin I made called Selector: click that element in the browser, press Command + C (Windows: Ctrl + C), and it copies the element's exact location in the code. Pasting that to the AI Agent makes the change much more accurate.
3. Model Selection and Combination
When testing and iterating on Oil UI, I generally don't use the top-tier models with inherently strong design ability. They perform well even without the Skill, so they aren't representative.
I mostly test with mid-range models that people use daily (you can check the DesignArena leaderboard for recent blind UI tests). Practical experience shows:
First, the Skill can raise the floor, but it can't change all of a model's ingrained habits. For example, some models have good visual foundations but love to add explanatory small text in corners. With Skill constraints, they become much more restrained, but occasionally it still creeps in. Other models default to packing dashboards densely; with the dashboard rules they become more organized, but sometimes local font sizes are too small and readability is mediocre.
Second, avoid using the lightest weak models for complete multi-file projects. Ultra-light small models are okay for single-page comparison draws, but in complex projects, after reading the entry file they often miss later sub-specs. For leading design work, it's recommended to use a mid-range or above model that can see images. If you want to save quota, first use a better model to finalize the representative first screen and DESIGN.md, then switch to cheaper models for subsequent routine business pages, following the spec.
Third, when pure code can't achieve the desired effect, consider the image-generation-to-reconstruction route. Image generation models have a higher creative ceiling for visuals than direct code. For high-requirement pages, you can first have an image generation tool draw the UI mock, then use my open-source draw-ui to decompose the materials and reconstruct them into code. If you also need a set of icons in the same style or scroll interaction animations, you can use the open-source oil-icon and oil-motion together.
Summary
Building Oil UI was mainly to solve the troubles I run into when writing product interfaces: don't give me a default template at the start; first put out a few genuinely different directions to pick. After picking, consolidate the rules into one place so that modifying old projects or multi-page projects doesn't get messier. Before delivery, have a sub-agent that hasn't seen the code review the screenshots as a final check.
It can't guarantee stunning designs every time after installation; the final result still depends on the model's own capability, your requirement description, and subsequent feedback. If you often use AI Agents to write frontend pages, you can install the open-source version and try it.