@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/enhance-web-ui/SKILL.md

@@ -0,0 +1,473 @@
+---
+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.
+
+> **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.
+
+> **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.
+
+### 3a - Two squint passes, not one
+
+Run the squint test twice — both passes are necessary, and the second is
+the one most enhancers skip:
+
+| Pass | Question | Failure looks like |
+|------|----------|--------------------|
+| **Hierarchy squint** | "Where is my eye pulled first?" | Several elements equally loud → primary not chosen |
+| **Category squint** | "Can I tell related items apart by colour/shape alone, without reading?" | All tiles same neutral grey → user must read every label = NN/g #6 violation |
+
+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:
+
+```js
+// 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](references/details.md)