---

name: enhance-web-ui description: > Polish an existing page's hierarchy, spacing, type, and visual personality. Use when "make this page polished/premium", "less crowded", or "better visual hierarchy". Readability → enhance-readability. Flow/IA → enhance-web-ux. license: MIT

Surface router: /uiux. You are here: enhance-web-ui. Native iOS/Android (SwiftUI / Compose, no web layer) is out of scope — use Apple HIG / Material directly.

Enhance Page UI

Degree of freedom: MIXED. Composition and tier judgment [HIGH freedom]; live read, DOM rects, three-viewport verify [LOW freedom — run exactly].

Turn an existing screen into a composed interface: calmer hierarchy, smarter content placement, expressive but purposeful motion, and artful transitions that support comprehension. This is not a "add more chips/cards/shadows" skill. It rearranges, subtracts, and stages information before adding decoration.

Vague-but-visceral user feedback ("clunky", "atrocious", "wasted space", "incoherent height") almost always points to a Hidden Failure Mode from §X below — start there, not at the surface decoration the user named.

If browser automation is used, first follow the protocol-browser-anti-stall skill when present.

How to reason

1. Recon — primitives, tokens, real data contracts
2. Rank — primary / secondary / metadata / actions / ambient
3. Compose — subtract → group → pin → stage before decorating
4. Verify — 1440/1024/800 + two squints + rect uniformity

Worked example

Recon: learning app (tier A); stat tiles share a Tooltip wrapper; "0/10 today" appears three times. Rank: primary is the next lesson CTA; the count is metadata, not a third headline. Compose: patch Tooltip to block w-full; drop two duplicate counts; no extra chips. Verify: tile widths match; category squint shows distinct hues; CTA still one brand-color target.

Self-critique before reporting

• Compose first — decoration was not the first edit
• Real data — no mocked status/count; primitive patched if the bug repeats
• Three viewports — no wrapped CTAs; dead slots collapse when empty
• Right owner — flow/IA → enhance-web-ux; breakpoints-only → audit-responsive

---

Rules

Compose before decorating. Fix hierarchy, grouping, alignment, and rhythm before adding gradients, motion, blur, masks, or shadows.

Replace clutter with structure. Do not stack more badges, labels, cards, dividers, or helper text onto a crowded surface. Move secondary information to a quieter region, a footer band, a hover/focus reveal, a drawer, or a progressive disclosure layer.

Make hierarchy visible at a squint. A user should know the focal element, supporting content, metadata, and actions before reading every word.

Motion must explain. Animate only feedback, state change, spatial relationship, affordance, or attention. No looping sparkle unless it carries status or brand tone and respects reduced motion.

Use the local design system. Reuse existing primitives, tokens, radius, spacing, typography, animation helpers, and dark/light surfaces. Extend a local primitive before inventing a one-off.

Never ship mock, dead, or rogue UI. Enhancements must be wired to the product's real data contracts, backend/API state, database schema, or existing domain helpers. If the UI needs better visual feedback, first look for the real status, timestamp, count, owner, error, progress, permission, or lifecycle data that should drive it. If that data does not exist but is necessary for a solid user experience, propose or implement the smallest backend/schema/API extension instead of faking the state in the component.

Respect density by viewport. Desktop can hold layered metadata. Tablet needs tighter grouping. Narrow screens need progressive disclosure and no wrapping CTAs.

Extended rules — tune saturation to product domain; audit conditional slots for dead-state; scan for information duplication within one viewport; patch the primitive, not the site; calm chrome before you decorate content; one brand-color element per visual zone; active ≠ heavier layout: references/live-read.md §Extended rules.

Named defaults to avoid when restyling. Without direction the model reaches for the same few styles: Inter / Roboto, pill-shaped buttons on every control, monospace or "01 / 02 / 03" section labels, a cream / off-white canvas, purple gradients, three equal cards, an italic accent word in headlines. Use the repo's own type, radius, and palette tokens instead; if a first pass lands on one of these, name it in the write-up and replace it.

---

Workflow Checklist

Copy and track:

UI ENHANCE /<route-or-component>
- [ ] 0. DOMAIN: product class -> colour-tier + density-tier (see Domain Colour Tier)
- [ ] 1. RECON: route, component tree, data fields, tokens, primitives, wrappers
- [ ] 2. CONTENT RANK: primary, secondary, metadata, actions, ambient
- [ ] 3. LIVE READ: 1440 / 1024 / 800 screenshots + DOM rect measurements
- [ ] 4. PAIN MAP: crowding, dead space, weak hierarchy, dup info, wrapper collapse,
 conditional-slot zero-state, monochromatic surfaces, hard cuts, bland motion
- [ ] 5. COMPOSITION PLAN: move, group, pin, crop, reveal, fade, animate
- [ ] 6. IMPLEMENT: primitive-level fixes first, smallest site-level diffs after
- [ ] 7. VERIFY: three viewports + DOM uniformity + squint-for-colour-distinction
 + reduced motion + dark/light if supported
- [ ] 8. WRITE-UP: before pain -> design principle -> after behavior

---

Step 1 - Recon: Learn the Existing Visual System [HIGH freedom]

Read the route/component in full. Then inspect:

• Layout primitives: Card, Section, Drawer, Tabs, Badge, Button, Tooltip, grid/list helpers.
• Styling system: Tailwind config, CSS variables, design tokens, theme context, animation utilities, existing radii/shadows.
• Data shape: all fields available, especially metadata currently shoved into titles or hidden in modals.
• Data source: API endpoints, loaders/actions, database schema, cache keys, backend status enums, validation errors, permissions, and lifecycle events that can make the UI's feedback real instead of decorative.
• Existing comments: search for "DO NOT", "avoid", "deprecated", "design", "layout", "spacing", "motion", "overflow".

Output a tiny component map:

<Page>
|-- Header - title, context, primary action
|-- Body/Grid/List - main content
|-- Detail/Drawer - progressive disclosure
`-- Footer/Chrome - metadata, controls, scroll status

Also list every wrapper / layout primitive in the chain from grid cell down to the rendered child: Tooltip, Trigger, Popover, Slot, AnimatedDiv, Tippy, motion.div, etc. Note the default display, width, and flex-shrink of each. This is where wrapper-collapse bugs hide and where the primitive-first patch in step 6 is decided.

---

Step 1.5 - Domain Colour & Density Tier [HIGH freedom]

Before touching any colour, name the product class. The same /8 tint that reads "premium and restrained" on a finance dashboard reads "monochromatic and dead" on a learning app. Pick a tier, then apply it consistently — never blend tiers in one product.

Tier	Examples	Surface bg tint	Accent fill	Categorical hue use	Source
A — Vibrant / Gamified	Duolingo, Drops, Habitica, Strava, kids/learning, fitness, casual gaming	/15–/25 gradient + ring /30–/40	solid token (bg-success, bg-cta), white-on-solid text	every meaningful category gets a distinct hue (success/error/streak/xp/info/premium) — colour is the gamification	Duolingo design system; Figma 2026 trend report
B — Expressive Consumer	Spotify, Notion playful surfaces, Robinhood onboarding, content/lifestyle apps	/10–/18 gradient + ring /20–/28	semi-solid (bg-cta/85)	3–5 semantic hues, decorative palette restrained	Spotify, Notion
C — Productive / Pro Tools	Linear, GitHub, Vercel, Figma chrome, design tools	/6–/12 tint + ring /15	one accent + 4 semantic states	accent reserved for primary action; semantic states only for status	Linear, Radix
D — Restrained / Data-Dense	Stripe dashboard, AWS console, observability/finance/admin/healthcare	mostly neutral surfaces; /4–/8 only on status pills	one accent for CTA; semantic states 4-slot (success/warn/error/info)	colour reserved for data signal; chrome stays achromatic — NN/g 60-30-10	Stripe, ColorArchive SaaS dashboards

How to detect tier (do this before designing):

1. Read the product's marketing copy, README, or onboarding — words like play, streak, level, fun, journey, daily, habit, master → tier A or B; workspace, dashboard, report, audit, query, pipeline → tier C or D.
2. Look at the existing primary CTA: solid saturated colour with chunky shadow → A; solid muted → B/C; outline or ghost dominates → D.
3. Look at semantic state tokens (success, warning, error, info, plus app-specific xp, streak, premium, ai, tone-1..6). More than 5 semantic hues with brand meaning → tier A. Just the basic 4 → tier C/D.

Tier mismatch is the top hidden cause of "monochromatic" feedback on consumer apps. A tier-A product with tier-D /8 tints will look washed-out and AI-generated even though every token is technically "correct".

---

Step 2 - Content Rank Before Layout [HIGH freedom]

Classify every visible element:

Rank	Meaning	Default Treatment
Primary	What the page is about	largest scale, strongest contrast, best space
Secondary	Helps interpret primary	near primary, smaller, grouped
Metadata	Dates, counts, stats, status	pinned footer/rail/table column, not title stack
Actions	What user can do	close to target, stable hit area, no wrap
Ambient	Brand, mood, decorative signal	background, mask, low contrast, removable

Rules:

• If everything is primary, nothing is primary.
• If metadata crowds the headline, move it to a bottom band, side rail, table column, tooltip, or detail drawer.
• If an action wraps, abbreviate progressively or icon+tooltip it.
• If a grid has dead space, adjust span, dense placement, aspect ratio, or content anchoring before adding more content.

---

Step 3 - Live Read [LOW freedom — run exactly]

Inspect the page at:

1440 x 900 desktop composition
1024 x 700 tablet / split-screen stress
800 x 700 narrow desktop / large mobile stress

For each viewport, note:

• First focal point.
• What feels crowded.
• What feels empty or unbalanced.
• Which labels wrap or truncate.
• Whether scroll edges are hard cuts or softly communicated.
• Whether hover/focus states explain interactivity.
• Console/runtime errors.

Use the squint test: mentally blur the screenshot. The page should still reveal its main regions through scale, contrast, grouping, and whitespace.

Then run the four sub-passes:

• 3a Two squint passes — hierarchy ("where is my eye pulled first?") and category ("can I tell related items apart by colour/shape alone?"); tier A/B tiles must blur to distinct hues, tier D to near-uniform.
• 3b DOM uniformity gate — query rects of repeated elements; a width span > 1px under a shared grid-cols-N parent is wrapper collapse. Fix at the wrapper.
• 3c Conditional-slot zero-state pass — render each optional slot with its smallest realistic content; a kept min-h / aspect-ratio floor is a dead slot.
• 3d Information-duplication scan — list every datum that appears more than once per fold; keep one canonical home. Rect script, wrapper-collapse causes, and the fold-scan example: references/live-read.md §Step 3.

---

Step 4 - Composition Moves [HIGH freedom]

Prefer these moves, in order:

1. Subtract: remove repeated hints, duplicate labels, low-value icons, noisy chrome, and "just in case" metadata.
2. Group: use proximity and common region to make related pieces read as one unit. Increase spacing between groups; decrease spacing inside groups.
3. Pin: move stats, code metadata, timestamps, or progress to a card footer, side rail, bottom band, sticky summary, or column.
4. Stage: reveal secondary content through hover, focus, tabs, accordions, drawers, details panels, or "show more" only when it helps.
5. Rebalance: change card spans, grid density, aspect ratio, order, or alignment so important items get room and empty space feels intentional.
6. Soften: replace hard clipping with fades, masks, scroll shadows, curtains, sticky gradients, or viewport-aware edge treatments.
7. Animate: add microinteractions only after the static composition works.

---

Hidden Failure Modes (the difficult-to-spot ones)

These are the "user said it but you missed it on first pass" patterns. When feedback is vague-but-visceral ("clunky", "atrocious", "wasted space", "incoherent height", "feels AI-generated"), walk this list before you touch decoration. Each entry has a detection probe (what to look for) and a fix shape (the smallest move that resolves it). Generic across stacks.

Walk H1–H16 with their detection probes and fix shapes: H1 active-state mass mismatch, H2 chrome tautology on root routes, H3 card-on-card chrome, H4 brand-color competition, H5 library-injected inline width, H6 wasted/squeezed column pair, H7 hover-only affordance, H8 hit-area baked into chrome, H9 stale data-priority, H10 missing aria-current, H11 motion that fights motion, H12 slot reserving space for absent content, H13 wrapper-collapsed tiles, H14 duplication per fold, H15 monochromatic surface, H16 left-anchored stack. Full catalogue, Pattern Library, Primitive-First Patch Rule, motion and implementation rules, plan template, and sanity checks: references/details.md.

Further reading

• Extended rules and Step 3 sub-passes (squints, DOM uniformity, zero-state, duplication)
• Hidden Failure Modes H1–H16, Pattern Library, Primitive-First Patch Rule, templates, sanity checks