genesis-upgrade-design

name	genesis-upgrade-design
description	Upgrade existing frontend web UI quality without changing behavior. Use when Codex is asked to redesign, polish, modernize, improve UX, make an app look premium, clean up AI-looking UI, improve responsive layout, audit visual quality, or apply targeted design upgrades to existing React, Next.js, Tailwind, CSS, HTML, dashboard, app, or website code.

Genesis Upgrade Design

Use this skill for existing frontend projects. Improve what is there; do not rewrite the product or change behavior unless the user explicitly asks.

Purpose

Upgrade existing frontend web UI quality while preserving behavior, contracts, and accessibility.

When to use

Use for visual polish, redesigns, responsive fixes, interaction states, UI audits, and anti-slop cleanup.

When NOT to use

Do not use for greenfield UI creation; use genesis-new-design instead.

Inputs required

Current UI routes, components, styling system, screenshots when available, behavior constraints, and verification commands.

Outputs required

Targeted UI improvements, before/after evidence, preserved behavior, updated tests, fixtures, contracts, and memory.

Required tests

Create or update regression tests for changed screens, interactions, validation, and visual states before implementation.

Required fixtures

Create fixtures for existing and expected UI states.

Required contract updates

Update contracts/ui/ only when the intended UI state contract changes.

Required codebase map updates

Update UI routes, frontend summary, and test matrix.

Token saving rules

Read summaries and route maps first; inspect only affected UI files and shared styling primitives.

Acceptance criteria

Behavior is preserved, UI quality improves, responsive states work, and verification passes.

Common mistakes

Rewriting instead of upgrading, changing data flow, and improving only the happy path.

Recovery workflow

If behavior changes unintentionally, restore the contract expectation, add a regression test, and narrow the UI diff.

Workflow

1. Audit before editing:

   • Inspect routes, components, styling system, theme tokens, assets, and package dependencies.
   • Identify the primary user workflows and the UI surfaces that matter most.
   • Capture or run the current UI when feasible so changes can be compared.

2. Preserve behavior:

   • Keep routing, data flow, public APIs, form semantics, state contracts, accessibility semantics, and test expectations intact.
   • Reuse existing components, utilities, variables, icons, and layout primitives.
   • Avoid broad rewrites. Make targeted changes that raise quality with the smallest safe diff.

3. Upgrade visual quality:

   • Improve typography scale, line height, copy rhythm, alignment, and scanability.
   • Normalize spacing, containers, grid tracks, button sizing, toolbar density, and responsive breakpoints.
   • Replace generic AI patterns: centered sameness, card spam, purple/blue glow defaults, placeholder content, weak empty states, and decorative clutter.
   • Add or improve loading, empty, error, hover, active, focus, and disabled states where the existing UI lacks them.
   • Use images or product visuals only when they clarify the product or user task.

4. Harden responsive and interaction details:

   • Check mobile and desktop viewports for overflow, clipping, overlap, unreadable text, and layout jumps.
   • Use stable dimensions for repeated controls and fixed-format UI.
   • Animate only transform and opacity; avoid effects that trigger layout or continuous repainting.
   • Keep keyboard focus visible and preserve accessible labels.

5. Verify and compare:

   • Run lint/typecheck/tests/build that are available for the project.
   • Start the dev server when visual validation requires it.
   • Capture screenshots after changes and inspect important states and viewports.
   • If reference screenshots or a target design are provided, compare against them before claiming completion.

Upgrade Heuristics

• Operational tools should feel quiet, dense, and work-focused.
• Marketing and brand pages should make the product, place, offer, or brand obvious in the first viewport.
• Dashboards should prioritize scanability, tabular alignment, filters, state visibility, and repeated action speed.
• Forms should use labels above inputs, helper/error text below inputs, visible focus, and inline validation.
• Navigation should clearly show current location and avoid dead links.
• Copy should be specific and plain. Avoid "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve", and "In the world of...".

Completion Bar

Do not call the upgrade complete until:

• Existing behavior is preserved.
• The changed UI renders correctly at desktop and mobile sizes.
• Core interactions have hover/active/focus states.
• No text overlap, clipped controls, broken assets, or blank primary surfaces remain.
• Verification commands have passed, or any skipped checks are reported with the reason.