UI craft
Two things keep AI-built UI from feeling production-level:
- It looks generated. The same corner roundness, grays, fonts and card grids appear whatever the brand.
- It isn't finished. Toasts pile up, sheets don't drag, menus break with the keyboard, and the empty, error and phone states were never built.
This skill fixes both with three things that live in each project, and six standards that live here.
| In the project | What it is |
|---|---|
DESIGN.md | The brand-applied UI guide: the project's values, assets, components as they look here, "Never" list, deviations from the standards by rule ID, decisions. |
| Master UI page | One live page built from the project's real CSS showing every token, every component in every state (pinnable), forms, tables, overlays and every motion with replay. Later work copies from it. |
| Tokens | One CSS file of custom properties. Everything else uses them. |
| In this skill | Read when |
|---|---|
standards/S1-direction.md | Establishing a direction: brand discovery, tokens, colour, type, motion, assets, CSS architecture, the AI look |
standards/S2-layout-and-words.md | Laying out a page or app shell, writing any UI text |
standards/S3-components.md | Building any component (29 covered, each with required states) |
standards/S4-interaction-and-motion.md | Keyboard, focus, overlays, gestures, animation, progress |
standards/S5-access-and-resilience.md | Accessibility, worst-case data, phones, desktop apps, themes and plugins |
standards/S6-proof.md | Before calling anything done |
specs/ | Hand-building a toast, drawer, command menu, dialog or popover, or animated number |
appendix/ | Depth and sources: the full directions shelf, research, library picks |
standards/README.md | How rule IDs work |
Rules have IDs like S3.23.2. Cite them in plans, reviews, commits and reports.
Pick the mode first
| The user asked to… | Mode | What happens |
|---|---|---|
| "Establish the direction", "set up the UI", or a new project | Establish | Steps 1–2 in full. The user approves the master UI page before any screen is built. |
| Build or change UI | Build | Steps 1–4. If there's no master UI page yet, offer Establish first; it's quicker than retrofitting. |
| Polish existing UI that has no guide | Retrofit | Extract the tokens already in the code. Write DESIGN.md from them, marking the thesis and direction inferred. Build the master UI page from an inventory of the real components (step 7). Don't redesign. Then steps 3–4 on what you touch. |
| Review, audit, "make sure it looks good" | Review | Skip guide creation and say so. Judge against DESIGN.md, or the code's tokens and any approved design. Run S6. Report numbered findings citing rule IDs, with before-and-after evidence. Change nothing until approved. |
Say which mode you're in, in one line, before starting.
Styling default: plain CSS with custom properties and @layer (templates/foundation.css). Use CSS modules or scoped styles where the framework has them. Use Tailwind only when the project already uses it. Never add Tailwind, CSS-in-JS or a component kit just to build a screen.
Step 1: Find the direction, or establish one
Find every guide: find . -maxdepth 4 -name DESIGN.md -not -path '*/node_modules/*'. Also check CLAUDE.md/AGENTS.md for a pointer.
- Check the checkout is current. Run
git status -sbandgit rev-list --count HEAD..origin/HEAD. If the branch is far behind, read the guide and code from the default branch or a fresh worktree. An old checkout can carry a retired brand. - More than one guide: don't add another. Extend the one that covers this surface and say at the top which surfaces each governs. If two conflict, ask the user which wins.
- Found: read
DESIGN.mdfully. It overrides the standards wherever it records a deviation. If a master UI page exists, build from it: copy its markup and classes, don't re-derive them.
Establishing a direction (S1 in full):
- Discover the current brand. Read the brand guide and any token or manifest files. Run
uv run --with playwright python scripts/brand-scan.py <home> <a typical inner page>on the live site. It reports colours actually used, fonts, radius and shadow habits, existing tokens, logo and favicon, and the voice of headings and buttons. Look at its screenshots. Note where the live site drifts from the guide. - Shortlist 2–3 directions from S1 (full shelf in
appendix/directions.md) that fit the existing brand. Say why in one line each. A direction must fit the brand, not replace it. - Let the user choose. Follow any steer they gave. In an unattended run, pick one and write "Picked by the agent, not yet confirmed" in
DESIGN.md§1. - Choose assets (S1.8): one icon set, fonts and an imagery style, with licences.
- Write
DESIGN.mdfromtemplates/DESIGN.md. Discovery, thesis, tokens with measured contrast, assets and "Never" are mandatory. Mark proposed values that the brand guide doesn't cover as needing approval. If the brand deliberately uses something on the AI-look list, mark it with<!-- ai-look-ok: ... -->and record what keeps it on-brand. - Put the tokens in one CSS file, starting from
templates/foundation.css. - Build the master UI page from
templates/ui-standards.html, with the project's tokens and assets. In an existing project, inventory the real components first: list the component files and the page files, and the classes each page uses. The page's core is a "Components in use" section, one specimen per real component, built from its real markup, CSS and copy. Under each: source file, pages that use it, states, and drift found. Template components the project doesn't use go in a collapsed "Available, not used yet" section at the end. While choosing, keep the 2–3 candidates in its direction switcher. Delete the losers once one is chosen. Write component states as:is(:hover, .is-hover)so the page can pin them. - Get approval: show the page live plus screenshots at 375 and 1280.
- Append, never overwrite, to the project's
CLAUDE.md/AGENTS.md:Before building or changing UI, read DESIGN.md and build from the master UI page.Use>>or an edit, never>.
Keep the generated guide and master page in the project so later sessions can use them directly.
Step 2: Build from the page and the standards
- Copy approved pieces from the master UI page. A component that isn't on the page gets added there first, in every state, then used.
- For each component, read its S3 entry. If it's a solved problem, install the library S3 names or hand-build to its spec in
specs/. Never improvise toasts, drawers, command menus, dialogs or comboboxes. - Use only tokens. No raw hex, no one-off radius, shadow or duration.
- Build every state as you go: empty, loading, error, busy (S3).
- Use real-looking content. Placeholder text hides layout problems.
- Write the words to S2: buttons are verbs that name the result, errors say what to do next.
Step 3: Prove it (S6)
Run S6 and end with its report table. Key tools:
scripts/ai-look-scan.sh <src>, or--changedfor only the files you touched. It flags AI tells and raw colours, and honours the project'sai-look-oklist. Never copy files into a temporary folder to scan them.uv run --with playwright python scripts/shoot.py <urls>. It takes screenshots and flags console errors, broken requests, sideways scroll and small targets. It handles logins (--storage-state,--cookie,--http-auth-env,--password-url), clicks (--click), banners (--hide) and desktop apps (--desktop). Don't write your own screenshot script unless this one can't reach the screen, and say why if so. Then open and look at the screenshots.vendor/emil-skills/skills/break-ui/SKILL.mdfor worst-case data.- After several agents fix things in parallel, run one fresh, independent review of the whole surface.
Don't call UI done until S6 passes, or the remaining items are listed as known gaps.
Step 4: Keep the direction alive
When the user corrects the look or feel, run vendor/emil-skills/skills/learn-taste/SKILL.md. It writes the correction into DESIGN.md as a rule with its reason. Update the master UI page in the same change. The same correction should never be needed twice.
Other tools in vendor/emil-skills/skills/
Emil Kowalski's design-engineering skills (MIT, pinned in vendor/emil-skills/PINNED_COMMIT):
| Skill | Use it for |
|---|---|
emil-design-eng | A full polish review |
review-animations | A strict motion review |
animate | Building any non-trivial animation |
gestures | Anything dragged or flicked |
mobile-native | Making a web app feel native on phones |
prototype | Live variants with a switcher |
find-animation-opportunities | Finding where motion should go |
remove-animations | Finding where motion shouldn't go |
choreograph | Several things moving together |
animation-performance | Animation that drops frames |
pick-ui-library | His curated library picks |