web-design

Web design

Generated UI fails in predictable ways: the same fonts, the same violet gradient, cards inside cards, a centred hero with three icon tiles, decoration standing in for a point of view. This skill replaces defaults with decisions, then checks the rendered result.

<skill-dir> below means this skill's own folder. Run its scripts from the project root so output lands in the project, not in the installed skill.

1. Load or create the design context

Look for DESIGN.md (also docs/DESIGN.md, BRAND.md). If it exists, read it before touching UI; its tokens and rules win over your taste. If it does not exist and the work is more than a small fix, create one from the template by reading the code: real tokens from the CSS/Tailwind config, real fonts, real components. Mark anything you inferred as inferred.

Update DESIGN.md when a session makes a durable decision (a new token, a rejected direction and why). This is how the next session avoids regressing to defaults.

2. Decide the direction

Name the mode first. It sets how much boldness the surface earns:

• Persuade (landing, pricing, launch pages): the design is the product; commit to a point of view.
• Operate (app UI, dashboards, settings, forms): precision and restraint; familiar patterns earn their place; brand lives in details.
• Read (docs, articles, changelogs): structure for comprehension, then make reading pleasant.
• Experience (portfolios, showcases, games): the work leads; the interface recedes.

Refining or redesigning? Refining keeps the current identity, copy and behaviour and improves within it. Redesigning keeps the product's facts and function but replaces the look entirely. Never split the difference by polishing a look you mean to discard.

Then plan in two passes before writing code.

Pass one, the plan:

• Job: who is here, what they need first, the next action.
• Palette: four to six named hex values, with where the accent is allowed.
• Type: faces and their roles, the scale, numerals.
• Layout: a sentence and a rough ASCII wireframe; alignment stated.
• The one bold thing: the single memorable element. Everything around it stays quiet.

Pass two, the generic test: would you have produced this plan for any similar brief? Check it against the current AI-default looks, which change over time. Cream background with a serif display and a terracotta accent, near-black with one acid accent, and broadsheet hairlines are today's clusters, as purple gradients were last year's. If a part of the plan matches a default the brief did not ask for, replace it and write down what you changed and why. The brief's own words always win, including when it asks for one of these looks.

Choose from the subject's world: its materials, places, artefacts and vocabulary. A dog walker's site and an analyst's dashboard should not be able to swap palettes.

When the user gives references, study them properly: reference study pulls computed styles from the live sites so you borrow relationships (scale, rhythm, density), not surface decoration.

3. Build in the product's system

• Use existing tokens, primitives and components. Add a token before adding a one-off value.
• Real content only: real names, long names, real numbers, empty data. Never lorem ipsum, never invented metrics to fill a layout.
• Design the states with the screen: loading, empty, error, success, disabled, overflow. An empty state that looks broken is a bug.
• Hide what has nothing to say. Zero rows, zero balances and empty charts become an honest empty state or disappear; no walls of zeros.
• Headers are labels. A subtitle that re-explains the header gets deleted.
• Mobile is its own layout: reorder by priority, use horizontal snap rails where desktop uses grids, dvh/svh not 100vh, inputs at 16px or larger, tap targets 44px.

Hold the line on the craft floor while building, not as a final pass. For any animation or transition, read motion first: one orchestrated moment, a small timing system, interruption-safe, reduced motion handled, and watched as a filmstrip.

4. Look at it

node <skill-dir>/scripts/shoot.mjs http://localhost:3000/page --full          # 390 + 1440, light + dark
node <skill-dir>/scripts/shoot.mjs http://localhost:3000/page --widths 320,390,768,1440 --themes light
node <skill-dir>/scripts/shoot.mjs http://localhost:3000/page --click '[aria-controls=menu]' --widths 390

Open every screenshot and actually read it. Then go through, in this order:

1. First read: squint. Is the most important thing the most prominent? Can you tell what this is and what to do in three seconds?
2. Broken: overflow, clipped text, overlapping layers, stranded words, invisible focus, dark mode contrast. shoot.mjs flags several of these; check its output.
3. Hierarchy and rhythm: more space above a heading than below it; consistent gaps within groups, larger between groups; one primary action per view.
4. Generic: run deslop's scan or check anti-patterns. Would a stranger guess this product from a screenshot with the logo removed?
5. Craft: alignment to the pixel at 2x, optical balance of icons and text, tabular numbers in columns.

Fix the worst problem, re-shoot, repeat. Compare against references at the same width and state. Two or three full loops is normal for new work.

5. Finish

Report the screens and states you inspected (widths, themes), the decisions you made, and anything not inspected (authenticated states you could not reach, real data you did not have). Commit DESIGN.md changes with the UI.

Rules

• The user's brief and DESIGN.md beat this skill. If the brand is purple gradients, it is purple gradients.
• No new UI library, icon set or font for a local change.
• Do not invent social proof, testimonials, logos, user counts or "trusted by".
• Do not fake liveness: no pulsing "Live" dots, tickers or activity unless backed by real data at that cadence ("Updates every 10s" when that is true).
• Never collapse distinct states (submitted, accepted, confirmed) into one success tick.