Enhance Web UI

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

Critical 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.

Tune saturation to product domain. A consumer learning, kids, fitness, or gamified app needs a vibrant, semantic palette where each colour carries meaning (Duolingo: green=correct, red=hearts, orange=streak). A B2B/SaaS/finance dashboard needs restrained colour reserved for status only (NN/g 60–30–10, Stripe-style). Faint /5–/10 tints on a playful consumer surface read as monochromatic and dead. Pick a saturation tier for the product first, then apply it consistently — see Domain Colour Tier below.

Audit conditional slots for dead-state. Any optional region — media, aside, eyebrow, footerSlot, cover, illustration, secondaryCTA — must be tested with sparse / zero-state content. A slot that reserves min-h: 160px for a rich illustration becomes a giant empty card when the only content is "0%". Make the slot conditional on content (drop the wrapper when empty) or collapse the floor (min-h-0 on mobile), never reserve space for absent content.

Scan for information duplication within one viewport. The same number, word, date, or status appearing twice in the same fold means one of them is wasted ink. Eyebrow shows "0/10 today" + inline pill shows "0/10 today" + footer bar shows "0/10 today" → keep the most actionable copy and delete the rest. Duplicates fragment attention (NN/g #8) and signal that the content rank in step 2 was skipped.

Patch the primitive, not the site. If a layout/colour/wrap bug repeats, fix it where the wrapper, helper, or token lives — not at the consumer. A single Tooltip defaulting to inline-flex will silently shrink every w-full child across the app; one prop fix beats N per-page band-aids. See Primitive-First Patch Rule below.

Calm chrome before you decorate content. Wayfinding chrome (header, breadcrumb, tabs, dock, toolbar) should recede, not announce itself — Linear's 2025 refresh names this "structure should be felt, not seen". If chrome competes with content for visual weight, it has too much paint: strip backgrounds → borders → tints → fills, in that order, until the chrome reads as a tonal recess that frames the content. The squint test applies to chrome too: at 10 px blur, the page content should dominate; the chrome should look like a quiet frame, not a stack of buttons.

One brand-color element per visual zone. A page should have ONE brand/accent-tinted element per zone (header strip, breadcrumb row, tab row, dock, page body). If breadcrumb chips, tab badges, AND the actual primary CTA all use the brand color, the actual CTA loses scent — every brand-tinted thing claims primacy and the user's eye can't pick a target. Audit the brand budget per zone: count brand-tinted surfaces in the screenshot; if > 1 per zone (excluding the count badge / underline / status chip that carries meaning), demote the chrome ones to neutral typography. The brand color is a finite resource — spend it on the action the user is here to take.

Active ≠ heavier layout — active = different cue. When an element moves to active state, its layout dimensions must not change (no taller, no wider, no extra padding). The active signal should come from a micro-cue: text-color shift + font-weight bump (font-medium → font-semibold), an underline, an icon-wrapping pill (Material 3 NavigationBar pattern: 32×16 bg-secondaryContainer rounded-full pill wrapping the icon, NOT the whole cell), or a count-badge tint swap. Full background washes on active tabs/buttons/cells inflate perceived weight 50%+ even when the bounding box is identical; the user reads the active sibling as "weirdly big and clunky". Linear, Stripe Apps, Vercel, M3 all obey this — copy them.

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.

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:

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.

3a - Two squint passes, not one

Run the squint test twice — both passes are necessary, and the second is the one most enhancers skip:

For a Tier A/B product (see Domain Colour Tier), a 2-up or 3-up of metric tiles that all read the same hue when blurred is a bug — colour is your category signal. For a Tier D product, the same blur should show near-uniform tiles with colour reserved only for the alert row.

3b - DOM uniformity gate (catches silent wrapper collapse)

Screenshots are necessary but not sufficient. When a page has repeated elements that should be the same width / height — grid tiles, segmented control segments, table columns, sidebar nav rows, form fields — measure them. Many "weird-looking" layouts come from a wrapper higher in the tree silently collapsing children to content width.

For each repeated group, query rendered rects and assert uniformity:

// playwright-cli / Playwright / DevTools console — generic, framework-free
const rects = [...document.querySelectorAll('<your-tile-selector>')]
 .map(el => el.getBoundingClientRect());
const widths = rects.map(r => Math.round(r.width));
const heights = rects.map(r => Math.round(r.height));
const span = Math.max(...widths) - Math.min(...widths);
console.table({ widths, heights, widthSpan: span });
// span > 1px on tiles that share a `grid-cols-N` parent === wrapper-collapse bug

Common wrapper-collapse causes (generic, language/framework agnostic):

• Tooltip / Popover / Trigger primitive defaults to display: inline-flex or inline-block → child width: 100% collapses to content width.
• Grid template uses 1fr (which is minmax(auto, 1fr)) and a child has intrinsic content wider than expected → cell expands beyond 1fr. Fix: repeat(N, minmax(0, 1fr)).
• Flex child without min-width: 0 or flex: 1 1 0 → content size dictates layout instead of the flex track.
• Animation libraries (Framer Motion m.div, Reanimated, GSAP wrappers) that inject inline display: inline-block for transform performance.
• Slot patterns (<Slot>, asChild, cloneElement) where the consumer drops w-full because the inner component doesn't forward className.

Fix at the wrapper, not the leaf: see Primitive-First Patch Rule.

3c - Conditional-slot zero-state pass

For every conditional region (media, aside, cover, eyebrow, secondaryCTA, illustration, footerSlot), inspect its sparse state — render the page with the slot's smallest realistic content (empty, "0%", a single icon, one short word). If the slot still reserves its min-h / aspect-ratio / min-w floor, you have a dead-conditional slot. Move to Composition Move 4 (Stage) and either:

1. Drop the wrapper when the slot is empty ({slot && <Region>{slot}</Region>}).
2. Collapse the floor on narrow viewports (min-h-0 lg:min-h-[160px]).
3. Inline the data into the body (chip / pill next to the action).

3d - Information-duplication scan

Within every fold (one viewport-height slice top-to-bottom), search for the same number, word, date, or status appearing more than once. List duplicates explicitly:

Fold 1 of /home @ 390×844:
- "0/10 words today" ×3 (eyebrow metric, action pill, footer strip)
- "0%" ×2 (action pill, Today metric tile)
- streak count ×2 (eyebrow metric, Streak tile)

The duplication itself is the diagnosis — pick one canonical home for each datum (usually the most actionable one) and delete the others. Each delete is a hierarchy upgrade for whatever stays.

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.

H1. Active-state mass mismatch

Symptom: "Tab/button/dock cell looks weirdly big and clunky", "highlight area is huge", "heights are incoherent".

Detection: Take a screenshot. Compare bounding boxes of active vs inactive siblings (DevTools → element rect, or just eyeball). If layout dimensions match but the active one feels 1.5× heavier, the active state is using a full-cell background fill. Grep your active state for bg-* on the container element. If found AND the inactive sibling has bg-transparent, that's the bug.

Fix shape: Move the active signal to a micro-indicator wrapped inside the cell, not painted over it:

• Tab → underline + text-color + count-badge swap (Stripe / Vercel pattern).
• Bottom dock → 32×16 rounded-full pill wrapping the icon only, not the whole button (Material 3 SecondaryContainer pattern).
• Sidebar item → leading 2px brand rail + bg-muted hover only.
• Button → solid fill is fine for primary CTAs (they SHOULD be heavy); forbidden for navigation siblings (they should NOT compete).

H2. Chrome tautology on root / index routes

Symptom: "Breadcrumb is atrocious", "header is too much", "why is 'Home' shown 3 times".

Detection: On the root route (/, /dashboard, /home), count how many chrome zones display the page name or home affordance: company-as-home link, breadcrumb chip, page title H1, dock active-item label, tab name. If ≥ 2 zones say the same word for the current page, you have tautology.

Fix shape: On root routes, suppress redundant chrome — pass showContextRow={false} (or your equivalent) to the page-layout wrapper, or gate the breadcrumb on pathname !== "/". The dock indicator + page H1 + greeting copy already answer "where am I?". The breadcrumb's job is "how do I go back?" — at the root, there is no back, so the row is dead weight.

H3. Card-on-card chrome

Symptom: Active page chip "feels heavy", "looks like a button stuck on another button", a chip on a tonally-recessed row reads as one elevation too many.

Detection: Inspect the row's background (e.g. bg-muted, bg-chrome-subtle, or any tonal recess). Then inspect the chip inside that row (e.g. bg-card border). Two distinct elevations within ~6 px of each other = card-on-card.

Fix shape: The chip must adopt the row's elevation, not introduce its own. Either drop the chip's bg-* + border and let typography (font-semibold

• text-foreground) carry the active signal, OR drop the row's tonal recess and let the chip be the only painted surface. Pick one elevation per row.

H4. Brand-color competition

Symptom: "Page feels noisy even though it's clean", "I can't tell which button is the primary action", "everything looks important".

Detection: Take a desktop screenshot. Count surfaces tinted in the brand color (border, fill, ring, text) within one visual zone. Subtract: the single intended primary CTA + status chips that carry meaning. Anything left over (a brand-tinted breadcrumb chip, a brand-tinted tab background, a brand-tinted home icon border) is competition.

Fix shape: Demote the chrome surfaces to neutral (text-muted-foreground, bg-transparent, border-border/40). Reserve the brand color for: the single primary CTA per fold, real status indicators (success / progress / new), and the active-item micro-indicator (not the cell background).

Further reading

• H5. Library-injected inline width beats your CSS rule and more