Imported from gandazgul/runwield (.agents/skills/visual-redesign/SKILL.md). Install upstream with npx skills add gandazgul/runwield --skill visual-redesign. Copyright stays with the author.

Visual Redesign: Surgical Aesthetic Upgrade

This skill fires when the user provides existing React/HTML/CSS code and asks to make it look better, upgrade the design, improve the aesthetics, make it premium, give it an Awwwards feel, or any variation of "this works but looks terrible." The user's code is FUNCTIONAL — it has working state, API calls, event handlers, and business logic. Your job is to upgrade the visual layer without breaking any of it. You are a surgeon, not a demolition crew. Cut precisely. Leave the patient alive.

The Sacred Rule — Read First

JavaScript logic is sacred. You do not touch it. Ever.

This is the non-negotiable, unbreakable rule that governs every line of this skill:

SACRED (never modify):
  ├── useState / useReducer declarations and updates
  ├── useEffect / useCallback / useMemo bodies
  ├── API calls (fetch, axios, SWR, React Query)
  ├── Event handler LOGIC (what happens onClick, not how the button looks)
  ├── Conditional rendering logic (ternaries, && chains, if blocks)
  ├── Router/navigation logic
  ├── Form validation logic
  ├── Context providers and consumers
  ├── Custom hook implementations
  ├── Data transformations (map, filter, reduce on data)
  ├── Error handling (try/catch, error boundaries)
  ├── Prop drilling / prop interfaces
  └── Third-party library integration logic

SLOP (upgrade aggressively):
  ├── className strings and CSS classes
  ├── Inline styles (style={{...}})
  ├── CSS/SCSS files
  ├── Tailwind utility classes
  ├── Bootstrap classes
  ├── Color values (hex, rgb, hsl)
  ├── Font families and sizes
  ├── Spacing values (padding, margin, gap)
  ├── Border-radius values
  ├── Shadow values
  ├── Transition/animation declarations
  ├── z-index values
  ├── Layout structure (flex/grid configuration)
  └── Wrapper div nesting (for layout, NOT for conditional logic)

⚠ Drift Warning: The #1 way AI "breaks the app" is by restructuring JSX to look cleaner and accidentally removing a conditional wrapper, moving a key prop, changing a ref assignment, or reordering children that depend on DOM position. NEVER restructure JSX for aesthetic reasons if the existing structure works. Add CSS to the existing structure. Do not reshape the structure to fit your CSS preferences.

→ The Gray Zone

Some elements are both logic and style. Handle them with extreme care:

Element	Sacred or Slop?	Rule
`className={isActive ? 'active' : ''}`	Both — logic is sacred, class names are slop	Keep the ternary. Change only the class name values: `className={isActive ? 'nav-link--active' : 'nav-link'}`
`style={{ display: isOpen ? 'block' : 'none' }}`	Sacred — this is conditional visibility logic	Do NOT replace with CSS classes. The inline style is driven by state. Leave it. Add your styles alongside it
`{items.map((item) => <Card key={item.id} ... />)}`	Sacred — the map, key, and data flow are logic	Style the Card component's internals. Do not change the map structure or key assignment
`ref={containerRef}`	Sacred — ref assignments drive JS behavior	Never remove, move, or rename refs
`aria-*` attributes	Sacred — accessibility attributes are functional	Never remove. You may add missing ones
`data-*` attributes	Probably sacred — often used by JS/tests	Never remove unless confirmed unused
`id` attributes	Probably sacred — may be used by JS selectors	Never change unless confirmed unused
`onClick={() => setOpen(!open)}`	Sacred — the handler is logic	Style the element. Do not touch the handler
`<div>` that wraps conditional content	Sacred — the div may exist for rendering reasons	Do not remove "unnecessary" wrapper divs unless you've confirmed they're purely presentational

The Golden Rule of the Gray Zone: If you're unsure whether something is logic or style, leave it alone and add your styles alongside it. A slightly less elegant CSS solution that doesn't break the app is infinitely better than an elegant refactor that introduces bugs.

The Pipeline

┌──────────────────────────────────────────────────────────────────────────┐
│                                                                          │
│   CODE IN ──→ Phase 1: Audit                                            │
│                 (read every file, classify Sacred vs Slop,              │
│                  identify the aesthetic crimes)                          │
│                                                                          │
│             ──→ Phase 2: Extraction                                     │
│                  (extract current design decisions across               │
│                   7 layers, build the Slop Sheet)                       │
│                                                                          │
│             ──→ Phase 3: Prescription                                   │
│                  (define target aesthetic, map every                    │
│                   slop item to its gold replacement)                    │
│                                                                          │
│             ──→ Phase 4: Surgery                                        │
│                  (execute replacements layer by layer:                  │
│                   tokens → typography → color → spacing →              │
│                   components → atmosphere → motion)                     │
│                                                                          │
│             ──→ Phase 5: Post-Op                                        │
│                  (verify nothing broke, visual diff,                    │
│                   responsive check, motion check)                       │
│                                                                          │
│   Each phase has a ✓ Quality Gate. Failing a gate blocks the next.     │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

Phase 1: Audit

Before changing a single character, read the entire codebase. Understand what exists. Classify everything.

→ Read every file and fill the Audit Table

File	Type	Sacred elements	Slop elements	Risk level
`App.tsx`	Root component	Router setup, providers, global state	Root className, global wrapper styles	Low
`Header.tsx`	UI component	Nav state (mobile menu toggle), auth state	All className strings, inline styles, layout	Medium
`Hero.tsx`	UI component	CTA click handlers, any analytics calls	Typography, colors, spacing, images, layout	Low
`Features.tsx`	UI component	Data arrays, map iterations	Card styles, grid layout, icons	Low
`Dashboard.tsx`	Complex component	All state, effects, API calls, data transforms	Table styles, card styles, chart wrapper styles	High
`Form.tsx`	Complex component	Validation, submission, error handling, refs	Input styles, button styles, layout	High
`index.css`	Stylesheet	None (but may contain critical resets)	Everything	Low

Risk levels:

Low — Mostly presentational. Safe to restyle aggressively.
Medium — Mix of logic and presentation. Restyle carefully, test after.
High — Heavy logic intertwined with presentation. Touch only CSS classes and styles. Test every change.

→ Identify the Aesthetic Crimes

Walk through the UI and catalog every visual problem. Be specific — "looks bad" is not a diagnosis.

Crime	Where	Severity	Example
Generic font stack	Global/body	Critical	`font-family: Arial, sans-serif` or browser default
Default shadows	Cards, buttons	Major	`box-shadow: 0 2px 4px rgba(0,0,0,0.1)` — the Bootstrap default
Pure black text on pure white	Everywhere	Major	`color: #000; background: #fff` — zero warmth, harsh contrast
Inconsistent spacing	Between sections	Major	`margin-top: 20px` on one section, `margin-top: 50px` on the next
Bootstrap blue accent	Buttons, links	Critical	`#0d6efd` — the single most recognizable "I didn't design this" signal
Generic border-radius	Cards, buttons	Moderate	`border-radius: 4px` everywhere — no radius language
No entry animations	Page load	Moderate	Elements just appear — static, lifeless mount
No hover states	Buttons, cards, links	Major	Interactive elements give zero feedback
Cramped padding	Cards, sections	Major	`padding: 16px` on a card that needs `32px` to breathe
No atmosphere	Backgrounds	Moderate	Flat `background: white` or `background: #f5f5f5` — no depth
Mixed radius languages	Across components	Moderate	Buttons are `rounded-full` but cards are `rounded-sm` with no logic
Body font as heading font	H1-H3	Critical	Inter/Roboto/Arial at `font-size: 24px` pretending to be a display heading
No visual hierarchy	Content sections	Major	Everything the same size, weight, and color
No whitespace system	Layout	Major	Random `mt-4`, `mt-6`, `mt-3` with no pattern

→ Output the Audit Summary

State in 3-5 lines what you found:

"Audit Summary: React SPA with 8 components. Router, auth state, and 3 API calls are sacred — all in Dashboard.tsx and Header.tsx. The visual layer is Bootstrap 5 defaults across the board: #0d6efd blue accent, default shadows, Arial font stack, 4px radius on everything, no hover states, no entry animations, cramped 16px padding on cards, pure black-on-white text. No design system — spacing and colors are ad-hoc per component. Estimated crimes: 14 critical, 23 major. Risk: Medium overall, High on Dashboard.tsx (complex state + table rendering)."

✓ Quality Gate: Audit

Before moving to Phase 2, confirm:

Every file has been read and classified in the Audit Table
Sacred elements are identified in every file
Risk levels are assigned per file
Aesthetic crimes are cataloged with specific examples
Audit Summary is written
You understand which files are High risk (heavy JS logic)
You have NOT modified any code yet

Phase 2: Extraction

Extract the current design decisions across 7 layers. This creates the "before" snapshot — the Slop Sheet.

→ Layer 1: Tokens (Colors, Fonts, Spacing Scale)

Token	Current value (Slop)	Source
Primary background	`#ffffff` or `white`	index.css / inline
Secondary background	`#f5f5f5` or `#f8f9fa`	Bootstrap gray-100
Primary text	`#000000` or `#212529`	Bootstrap default
Secondary text	`#6c757d`	Bootstrap gray-600
Accent/primary action	`#0d6efd`	Bootstrap primary
Accent hover	`#0b5ed7`	Bootstrap primary hover
Danger/error	`#dc3545`	Bootstrap danger
Success	`#198754`	Bootstrap success
Border color	`#dee2e6`	Bootstrap gray-300
Font display	`system-ui` or `Arial`	Browser default
Font body	Same as display	No differentiation
Font mono	None	Missing
Spacing base	No system (ad-hoc)	Random px values
Radius default	`4px` or `0.375rem`	Bootstrap default

→ Layer 2: Typography

Element	Current spec (Slop)
H1	`font-size: 2rem; font-weight: bold; font-family: inherit`
H2	`font-size: 1.5rem; font-weight: bold`
H3	`font-size: 1.25rem; font-weight: bold`
Body	`font-size: 1rem; line-height: 1.5`
Small/caption	`font-size: 0.875rem`
Button text	`font-size: 1rem; font-weight: 400`
Letter-spacing	None set (browser default: normal)
Line-height on headings	1.2 (Bootstrap default — too loose for display)
Text wrapping	No `text-wrap: balance` on headings
Max-width on body text	None (text runs edge to edge)

→ Layer 3: Spacing

Measurement	Current value (Slop)
Section padding	Inconsistent: `py-3`, `py-4`, `py-5`, random px values
Card padding	`p-3` (12px) or `p-4` (16px) — cramped
Grid gap	`gap-3` (12px) or `gap-4` (16px) — tight
Heading → body gap	`mb-2` or `mb-3` — too tight
Body → CTA gap	`mt-3` — too tight
Nav height	`py-2` (short and cramped) or default Bootstrap nav height
Component spacing	No consistent system — every component different

→ Layer 4: Color Usage

Usage	Current value (Slop)	Problem
Background	Pure `#fff` or `#f8f9fa`	Flat, cold, no warmth
Text	Pure `#000` or `#212529`	Harsh, no refinement
Accent	Bootstrap `#0d6efd`	Screams "undesigned"
Borders	`#dee2e6`	Generic gray
Shadows	`rgba(0,0,0,0.1)`	Default, undifferentiated
Hover states	Slightly darker shade	No personality
Active states	Even darker shade	Mechanical, not physical
Error	Bootstrap `#dc3545`	Generic red

→ Layer 5: Components

Component	Current state (Slop)
Buttons	Bootstrap `.btn.btn-primary` — `#0d6efd`, `4px` radius, generic padding, no hover physics
Cards	`.card` — `1px solid #dee2e6`, `4px` radius, default shadow or no shadow, cramped padding
Inputs	Bootstrap form controls — `#dee2e6` border, no focus glow, no float labels
Navigation	Bootstrap navbar — busy, cramped, default styling
Tables	Bootstrap `.table` — zebra stripes, cramped rows, no refinement
Modals	Bootstrap modal — generic overlay, no entry animation
Badges/pills	Bootstrap `.badge` — small, cramped, primary blue
Dropdowns	Bootstrap dropdown — generic shadow, no animation

→ Layer 6: Atmosphere

Property	Current state (Slop)
Background texture	None — flat solid color
Ambient glow/gradient	None — completely flat
Grain/noise	None
Frosted glass	None
Depth system	Default Bootstrap shadow or none
Visual warmth	Zero — cold and clinical

→ Layer 7: Motion

Property	Current state (Slop)
Page entry	None — static mount, everything appears instantly
Scroll reveals	None — everything visible immediately
Hover transitions	`transition: all 0.15s ease-in-out` (Bootstrap default) or none
Page transitions	None — instant swap
Micro-interactions	None
Loading states	Spinner or "Loading..." text
Easing curves	`ease-in-out` CSS keyword or none

✓ Quality Gate: Extraction

Before moving to Phase 3, confirm:

All 7 extraction layers are filled in with actual values from the codebase
Values are specific (exact hex codes, exact rem/px values), not vague
You can see the gap between current state and target quality
You have NOT modified any code yet

Phase 3: Prescription

For every slop item extracted in Phase 2, prescribe the gold replacement. This is the transformation map — the surgical plan.

→ Token Prescription

/* PRESCRIPTION: Design tokens — Slop → Gold
   WHY: Tokens are the foundation. Changing these first
   means every component that references them upgrades
   automatically. This is the highest-leverage change. */

:root {
    /* ── Colors ────────────────────────────────────── */

    /* Background: #ffffff → warm off-white
       WHY: Pure white is harsh and clinical. Off-white
       with a warm undertone feels premium and intentional.
       The difference is subtle but the eye registers it
       as "designed" vs "default." */
    --color-bg: #FAFAF9; /* was: #ffffff */
    --color-surface: #FFFFFF; /* was: #f8f9fa — cards sit ON the bg */
    --color-surface-2: #F5F4F2; /* was: none — for alternating sections */

    /* Text: #000000 → warm near-black
       WHY: Pure black on warm off-white creates a jarring
       temperature clash. Near-black (#1a1a1a) matches the
       warmth of the background and reduces eye strain. */
    --color-text: #1A1A1A; /* was: #000000 or #212529 */
    --color-text-2: #6B7280; /* was: #6c757d — muted, for secondary */
    --color-text-3: #9CA3AF; /* was: none — for captions, placeholders */

    /* Accent: #0d6efd → considered, non-Bootstrap hue
       WHY: Bootstrap blue is the single loudest "I didn't
       design this" signal on the web. ANY other considered
       hue immediately elevates the design. Pick based on
       brand context from the user's brief. */
    --color-accent: #____; /* MUST be chosen based on brand context */
    --color-accent-hover: #____; /* 10-15% darker or more saturated */

    /* Borders and shadows: warm, not gray
       WHY: Cool gray borders (#dee2e6) clash with warm
       backgrounds. Use warm gray or very low-opacity black. */
    --color-border: rgba(0, 0, 0, 0.08); /* was: #dee2e6 */
    --color-shadow: rgba(0, 0, 0, 0.04); /* was: rgba(0,0,0,0.1) */

    /* ── Typography ────────────────────────────────── */

    /* Display font: Arial → a real display font
       WHY: Arial/system-ui as a heading font is the
       typographic equivalent of serving fine dining
       on paper plates. Display fonts have optical
       refinements for large sizes that body fonts lack. */
    --font-display: 'Outfit', system-ui, sans-serif; /* was: Arial/system-ui */
    --font-body: 'Inter', system-ui, sans-serif; /* was: same as display */
    --font-mono: 'JetBrains Mono', monospace; /* was: none */

    /* ── Spacing ───────────────────────────────────── */

    /* Section spacing: random values → consistent scale
       WHY: A spacing system creates rhythm. Random spacing
       creates visual noise — the eye detects inconsistency
       even when the brain can't articulate it. */
    --space-section: clamp(5rem, 10vw, 8rem); /* was: random py values */
    --space-element: 1.5rem; /* was: 0.75rem–1rem */
    --space-component: 2rem; /* was: 1rem–1.5rem */

    /* ── Radius ────────────────────────────────────── */

    /* Radius: 4px everywhere → considered radius language
       WHY: A design system commits to a radius language.
       Pick ONE and apply consistently. */
    --radius-sm: 8px; /* was: 4px (Bootstrap) — inputs, badges */
    --radius-md: 12px; /* was: 4px — cards, containers */
    --radius-lg: 16px; /* was: 4px — modals, large cards */
    --radius-full: 9999px; /* was: 50% — pills, avatars */

    /* ── Easing ────────────────────────────────────── */

    /* Easing: ease-in-out → custom curves
       WHY: CSS keyword easings are the typographic
       equivalent of Comic Sans. Zero character,
       zero intentionality. Custom curves give
       every animation a deliberate feel. */
    --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
    --ease-snap: cubic-bezier(0.22, 1, 0.36, 1);
    --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
}

→ Typography Prescription

/* PRESCRIPTION: Typography scale — Slop → Gold
   WHY: The heading is the first thing the eye hits.
   A display font with tight tracking and compressed
   line-height immediately signals "designed." The body
   font stays readable with comfortable line-height. */

/* Import the fonts — add to the top of your CSS or <head> */
@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap');

h1,
h2,
h3,
h4 {
    font-family: var(--font-display);
    letter-spacing: -0.03em; /* was: normal (too loose at display size) */
    line-height: 1.1; /* was: 1.2 (Bootstrap) — tighten */
    text-wrap: balance; /* prevents ugly orphan lines */
    color: var(--color-text);
}

h1 {
    font-size: clamp(2.25rem, 5vw, 3.75rem); /* was: 2rem fixed */
    font-weight: 700;
    letter-spacing: -0.04em;
    line-height: 1.05;
}

h2 {
    font-size: clamp(1.75rem, 3.5vw, 2.75rem); /* was: 1.5rem fixed */
    font-weight: 600;
}

h3 {
    font-size: clamp(1.25rem, 2vw, 1.5rem); /* was: 1.25rem fixed */
    font-weight: 600;
}

body,
p,
span,
li {
    font-family: var(--font-body);
    font-size: clamp(0.9375rem, 1.1vw, 1.0625rem); /* was: 1rem fixed */
    line-height: 1.65; /* was: 1.5 — slightly more generous */
    color: var(--color-text);
}

/* Body text max-width — prevent wall-to-wall text */
p {
    max-width: 65ch; /* was: none — text ran edge to edge */
}

/* Muted secondary text */
.text-muted,
.text-secondary {
    color: var(--color-text-2) !important; /* override Bootstrap's gray */
}

/* Eyebrow / label style — add where appropriate */
.eyebrow {
    font-family: var(--font-mono);
    font-size: 0.75rem;
    font-weight: 500;
    letter-spacing: 0.12em;
    text-transform: uppercase;
    color: var(--color-text-3);
}

→ Component Prescription

/* PRESCRIPTION: Button — Bootstrap → Premium
   WHY: The button is the most interactive element on the page.
   Its hover feel communicates the entire quality level of the site.
   A snappy cubic-bezier with a physical lift-and-shadow creates
   a tactile impression that Bootstrap's default cannot achieve. */

/* Strip Bootstrap button defaults */
.btn {
    font-family: var(--font-body);
    font-size: 0.875rem;
    font-weight: 600;
    letter-spacing: 0.02em;
    padding: 0.75rem 1.75rem; /* was: py-2 px-3 — cramped */
    border-radius: var(--radius-full); /* was: 4px — now pill */
    border: none;
    cursor: pointer;
    transition:
        transform 0.4s var(--ease-snap),
        box-shadow 0.4s var(--ease-snap),
        background-color 0.3s var(--ease-out);
}

.btn:hover {
    transform: translateY(-2px);
    box-shadow: 0 4px 16px var(--color-shadow);
}

.btn:active {
    transform: translateY(0) scale(0.98);
    transition-duration: 0.1s;
}

/* Primary button */
.btn-primary {
    background: var(--color-accent);
    color: #ffffff;
    border: none;
    box-shadow: 0 1px 3px var(--color-shadow);
}

.btn-primary:hover {
    background: var(--color-accent-hover);
}

/* Ghost / outline button */
.btn-outline-primary,
.btn-secondary,
.btn-outline-secondary {
    background: transparent;
    color: var(--color-text);
    border: 1px solid var(--color-border);
}

.btn-outline-primary:hover,
.btn-outline-secondary:hover {
    border-color: var(--color-text);
    background: rgba(0, 0, 0, 0.02);
}

/* PRESCRIPTION: Card — Bootstrap → Premium */
.card {
    background: var(--color-surface);
    border: 1px solid var(--color-border);
    border-radius: var(--radius-md); /* was: 4px */
    padding: var(--space-component); /* was: 1rem — cramped */
    box-shadow: none; /* was: default Bootstrap shadow */
    transition:
        transform 0.4s var(--ease-snap),
        box-shadow 0.4s var(--ease-snap),
        border-color 0.3s var(--ease-snap);
}

.card:hover {
    transform: translateY(-4px);
    box-shadow:
        0 8px 24px rgba(0, 0, 0, 0.04),
        0 2px 8px rgba(0, 0, 0, 0.02);
    border-color: rgba(0, 0, 0, 0.12);
}

/* Reset Bootstrap card internals */
.card-body {
    padding: 0; /* parent .card already has padding */
}

.card-title {
    font-family: var(--font-display);
    font-size: 1.125rem;
    font-weight: 600;
    letter-spacing: -0.01em;
    margin-bottom: var(--space-element);
}

/* PRESCRIPTION: Input — Bootstrap → Premium */
.form-control,
input[type="text"],
input[type="email"],
input[type="password"],
textarea,
select {
    font-family: var(--font-body);
    font-size: 0.9375rem;
    padding: 0.75rem 1rem; /* was: py-1.5 px-3 — cramped */
    border: 1px solid var(--color-border);
    border-radius: var(--radius-sm);
    background: var(--color-surface);
    color: var(--color-text);
    transition:
        border-color 0.3s var(--ease-snap),
        box-shadow 0.3s var(--ease-snap);
}

.form-control:focus,
input:focus,
textarea:focus,
select:focus {
    outline: none;
    border-color: var(--color-accent);
    box-shadow: 0 0 0 3px rgba(var(--color-accent-rgb), 0.15);
}

/* PRESCRIPTION: Navigation — Bootstrap → Premium */
.navbar,
nav {
    backdrop-filter: blur(16px) saturate(180%);
    -webkit-backdrop-filter: blur(16px) saturate(180%);
    background: rgba(250, 250, 249, 0.85); /* semi-transparent for frost */
    border-bottom: 1px solid var(--color-border);
    padding: 0 clamp(1.5rem, 5vw, 5rem);
    height: 64px;
    display: flex;
    align-items: center;
}

.nav-link,
.navbar-nav .nav-link {
    font-family: var(--font-body);
    font-size: 0.875rem;
    font-weight: 500;
    color: var(--color-text-2);
    transition: color 0.3s var(--ease-snap);
    position: relative;
}

.nav-link:hover {
    color: var(--color-text);
}

/* Sliding underline on nav links */
.nav-link::after {
    content: '';
    position: absolute;
    bottom: -2px;
    left: 0;
    width: 100%;
    height: 1.5px;
    background: var(--color-text);
    transform: scaleX(0);
    transform-origin: right;
    transition: transform 0.3s var(--ease-snap);
}

.nav-link:hover::after {
    transform: scaleX(1);
    transform-origin: left;
}

/* PRESCRIPTION: Table — Bootstrap → Premium */
.table,
table {
    border-collapse: separate;
    border-spacing: 0;
    width: 100%;
}

.table th,
table th {
    font-family: var(--font-mono);
    font-size: 0.6875rem;
    font-weight: 500;
    letter-spacing: 0.1em;
    text-transform: uppercase;
    color: var(--color-text-3);
    padding: 0.75rem 1rem;
    border-bottom: 1px solid var(--color-border);
    text-align: left;
}

.table td,
table td {
    font-size: 0.9375rem;
    padding: 1rem;
    border-bottom: 1px solid rgba(0, 0, 0, 0.04);
    color: var(--color-text);
}

.table tbody tr:hover,
table tbody tr:hover {
    background: rgba(0, 0, 0, 0.015);
}

/* Kill Bootstrap zebra striping — it looks cheap */
.table-striped > tbody > tr:nth-of-type(odd) {
    background-color: transparent;
}

→ Atmosphere Prescription

/* PRESCRIPTION: Atmosphere — Flat → Alive
   WHY: Flat backgrounds feel like nothing. A subtle
   radial gradient, grain texture, or warm tint gives
   the background depth without adding visual elements. */

/* Subtle warm radial on the body */
body {
    background:
        radial-gradient(ellipse at 30% 0%, rgba(250, 235, 215, 0.2) 0%, transparent 50%),
        var(--color-bg);
}

/* Noise grain overlay — felt, not seen */
body::after {
    content: '';
    position: fixed;
    inset: 0;
    pointer-events: none;
    z-index: 9999;
    opacity: 0.025;
    background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='1'/%3E%3C/svg%3E");
}

/* Section dividers — subtle border instead of hard lines */
section + section {
    border-top: 1px solid var(--color-border);
}

/* Alternating section backgrounds for rhythm */
section:nth-child(even) {
    background-color: var(--color-surface-2);
}

→ Motion Prescription

/* PRESCRIPTION: Motion — Static → Alive
   WHY: Every element that appears without animation
   feels like the page is broken. A staggered fade-up
   with deblur signals that the page loaded intentionally. */

/* Entry animation keyframe */
@keyframes enter-up {
    from {
        opacity: 0;
        transform: translateY(24px);
        filter: blur(6px);
    }
    to {
        opacity: 1;
        transform: translateY(0);
        filter: blur(0);
    }
}

/* Apply to major elements — use inline style for stagger:
   <h1 class="enter-up" style="--stagger: 0ms">
   <p class="enter-up" style="--stagger: 120ms">
   <button class="enter-up" style="--stagger: 240ms"> */
.enter-up {
    animation: enter-up 0.7s var(--ease-out) both;
    animation-delay: var(--stagger, 0ms);
}

/* Scroll reveal — elements below the fold */
[data-reveal] {
    opacity: 0;
    transform: translateY(30px);
    transition:
        opacity 0.8s var(--ease-out),
        transform 0.8s var(--ease-out);
}

[data-reveal].is-visible {
    opacity: 1;
    transform: translateY(0);
}

/* Universal interactive transition — replaces Bootstrap's
   transition: all 0.15s ease-in-out on EVERY interactive element */
a,
button,
[role="button"],
input,
select,
textarea,
.card,
.nav-link,
.badge {
    transition: all 0.3s var(--ease-snap);
}

/* Respect reduced motion */
@media (prefers-reduced-motion: reduce) {
    .enter-up {
        animation: none;
        opacity: 1;
        transform: none;
        filter: none;
    }

    [data-reveal] {
        opacity: 1;
        transform: none;
        transition: none;
    }

    *,
    *::before,
    *::after {
        animation-duration: 0.01ms !important;
        transition-duration: 0.01ms !important;
    }
}

→ Scroll Reveal JavaScript (Non-Destructive)

/* PRESCRIPTION: Scroll reveal — add as a separate script
   WHY: This script observes [data-reveal] elements and
   adds .is-visible when they enter the viewport. It does
   NOT modify any existing JS — it's a new, separate file
   that runs independently.

   Add to the end of the page or import in main entry. */

class ScrollReveal {
    constructor() {
        if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) return;

        this.observer = new IntersectionObserver(
            (entries) => {
                entries.forEach((entry) => {
                    if (entry.isIntersecting) {
                        entry.target.classList.add("is-visible");
                        this.observer.unobserve(entry.target);
                    }
                });
            },
            { threshold: 0.15, rootMargin: "-50px 0px" },
        );

        document.querySelectorAll("[data-reveal]").forEach((el) => {
            this.observer.observe(el);
        });
    }
}

// Initialize after DOM ready
if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", () => new ScrollReveal());
} else {
    new ScrollReveal();
}

✓ Quality Gate: Prescription

Before moving to Phase 4, confirm:

Every slop item from Phase 2 has a gold replacement prescribed
Token prescriptions are internally consistent (warm bg + warm text, not mixed temperatures)
The accent color is chosen based on the user's brand context (not another generic blue)
Typography prescription uses a display font for headings and a body font for body
Component prescriptions maintain the same DOM structure (class changes only)
Atmosphere additions are subtle (opacity < 0.05 for grain, < 0.3 for gradients)
Motion additions are non-destructive (new CSS classes and a new script, no existing JS modified)
The accent color #____ placeholder is filled with an actual hex value

Phase 4: Surgery

Execute the prescriptions. This is the operating room. Follow the exact order below — each layer builds on the previous one.

→ Surgical Order

Layer 1: Tokens     (CSS custom properties — the foundation)
Layer 2: Typography (font imports + heading/body styles)
Layer 3: Color      (replace all Bootstrap/generic color values)
Layer 4: Spacing    (padding, margins, gaps — breathing room)
Layer 5: Components (buttons, cards, inputs, nav, tables)
Layer 6: Atmosphere (grain, glow, section alternation)
Layer 7: Motion     (entry animations, hover states, scroll reveals)

→ Surgical Rules

Rule	Why
One layer at a time	If you change tokens, typography, AND components simultaneously and something breaks, you cannot isolate the cause
Test after each layer	Run the app. Does it still work? Do all routes load? Do forms submit? Do API calls return? If yes, proceed to the next layer
CSS overrides, not replacements	Add a new stylesheet (e.g., `gold.css`) that overrides the existing styles. Do NOT delete the existing CSS files until the override is confirmed working
className changes are surgical	If replacing Bootstrap classes with custom ones, search the entire codebase for each class before removing it. A class used in JS logic (`document.querySelector('.btn-primary')`) is sacred
Never rewrite JSX structure	You may add/change `className` props and `style` props. You may NOT reorder children, remove wrapper divs, change component hierarchy, or modify props that aren't purely visual
New files > modified files	Prefer creating `gold.css` and importing it AFTER existing stylesheets (for override priority) over editing the existing stylesheets directly. This makes rollback trivial

→ The Override Strategy

The safest approach is a single new stylesheet loaded AFTER all existing stylesheets:

/* gold.css — loaded LAST in the cascade
   WHY: By loading after Bootstrap/existing CSS, our rules
   override the defaults without deleting any existing code.
   If something breaks, the user can remove this one import
   to revert entirely. This is the safest surgery method.

   Import in main entry file:
   import './gold.css'  // AFTER all other CSS imports */

This file contains ALL prescriptions from Phase 3 — tokens, typography, components, atmosphere, motion — in one file that can be added or removed as a single unit.

⚠ Drift Warning: The temptation is to "clean up" the existing CSS by deleting Bootstrap imports or removing old stylesheets. Do NOT do this until the user has confirmed the gold override is working. The old CSS is a safety net. Remove it only after the patient is confirmed stable.

→ High-Risk File Surgery (Dashboard, Forms, Complex Components)

For files marked High risk in the Audit Table:

Read the entire file first — understand every state variable, effect, and handler
Map every className and style prop — note which ones are referenced in JS logic
Change ONLY className string values — the attribute stays, only the value changes
Never touch inline styles that reference state — style={{ display: isOpen ? 'block' : 'none' }} is sacred
Test immediately after changes — run the app, trigger every state change, submit every form, verify every API call

/* EXAMPLE: Safe className surgery on a complex component

   BEFORE (Bootstrap):
   <div className={`card ${isSelected ? 'border-primary' : ''}`}>

   AFTER (Gold):
   <div className={`card ${isSelected ? 'card--selected' : ''}`}>

   The ternary logic is IDENTICAL. Only the class name value changed.
   Then in gold.css:
   .card--selected {
     border-color: var(--color-accent);
     box-shadow: 0 0 0 2px rgba(var(--color-accent-rgb), 0.2);
   }
*/

→ Adding data-reveal Attributes (Non-Destructive)

To add scroll reveal animations, add data-reveal attributes to existing JSX elements. This is safe because data-* attributes do not affect React's rendering logic:

/* BEFORE: */
<section className="features">
  <h2>Features</h2>
  {features.map(f => <FeatureCard key={f.id} {...f} />)}
</section>

/* AFTER — added data-reveal, nothing else changed: */
<section className="features" data-reveal>
  <h2>Features</h2>
  {features.map(f => <FeatureCard key={f.id} {...f} />)}
</section>

/* The data-reveal attribute is inert until the ScrollReveal
   script observes it. It does not interfere with React's
   reconciliation, event handling, or state management. */

→ Adding Entry Animation Classes (Non-Destructive)

/* BEFORE: */
<h1 className="hero-heading">Build faster.</h1>
<p className="hero-subtext">The platform for modern teams.</p>
<button className="btn btn-primary" onClick={handleSignup}>Get Started</button>

/* AFTER — added enter-up class and stagger variable: */
<h1 className="hero-heading enter-up" style={{ '--stagger': '0ms' } as React.CSSProperties}>Build faster.</h1>
<p className="hero-subtext enter-up" style={{ '--stagger': '120ms' } as React.CSSProperties}>The platform for modern teams.</p>
<button className="btn btn-primary enter-up" style={{ '--stagger': '240ms' } as React.CSSProperties} onClick={handleSignup}>Get Started</button>

/* onClick handler is UNTOUCHED. Only className and style were added.
   The style prop uses a CSS custom property for stagger delay.
   In TypeScript, cast as React.CSSProperties to avoid type errors. */

✓ Quality Gate: Surgery

After all 7 layers are applied, confirm:

The app runs without errors (console is clean)
All routes load correctly
All forms submit and validate correctly
All API calls return data and render correctly
All state changes work (toggles, modals, dropdowns, selections)
All event handlers fire correctly (clicks, submits, keypresses)
No ref errors or "cannot read property of undefined" errors
The new CSS imports load AFTER existing stylesheets
The gold.css file can be removed to fully revert

Phase 5: Post-Op

Verify the surgery was successful. Walk through every check. Any FAIL requires diagnosis and correction.

Functionality Check (Sacred Integrity)

Check	PASS/FAIL
All pages/routes load without error
All forms submit correctly
All API calls return and render data
All state toggles work (open/close, show/hide, select/deselect)
All event handlers fire (onClick, onSubmit, onChange, onKeyDown)
Authentication flow works (login, logout, protected routes)
No console errors
No TypeScript errors (if TS project)
No broken refs or undefined property errors
All conditional rendering works (loading states, error states, empty states)

⚠ If ANY functionality check fails, REVERT the last surgery layer and diagnose. Do NOT proceed to visual checks until all functionality passes.

Visual Upgrade Check

Check	PASS/FAIL
No Bootstrap blue (#0d6efd) visible anywhere
No pure black (#000) text on pure white (#fff) backgrounds
Heading font is a display font (not Arial/system-ui)
Heading letter-spacing is negative (tight, not loose)
Heading line-height is compressed (< 1.15)
Body text has comfortable max-width (not edge-to-edge)
Cards have generous padding (not cramped 16px)
Buttons are pill-shaped or use the prescribed radius
Buttons have hover lift + shadow expansion
Buttons have active press feedback
Nav has frosted glass treatment
Color palette is warm and consistent (no cold grays mixed with warm tones)
Shadows are subtle and warm (not default Bootstrap)
Border-radius is consistent across same component types

Atmosphere Check

Check	PASS/FAIL
Background has subtle warmth (not flat white/gray)
Grain overlay is present and subtle (felt, not seen)
Section alternation creates rhythm (not all same background)
No flat, dead-feeling sections remain

Motion Check

Check	PASS/FAIL
Hero elements animate in on page load (staggered fade-up-deblur)
Scroll reveals trigger on below-fold sections
All buttons have hover transitions (not instant state change)
All cards have hover lift
Nav links have animated underlines
Input focus has border glow transition
No animation uses CSS keyword easing (ease, ease-in, ease-out, ease-in-out)
`prefers-reduced-motion` is respected (no motion on reduce)

Responsive Check

Check	PASS/FAIL
Layout works at 1440px (desktop)
Layout works at 768px (tablet)
Layout works at 375px (mobile)
No horizontal overflow at any viewport
Touch targets minimum 44px on mobile
Heading doesn't wrap beyond 3 lines at any viewport
Cards stack properly on mobile (single column)

Rollback Check

Check	PASS/FAIL
Removing gold.css import reverts ALL visual changes cleanly
No existing CSS files were deleted (they're intact as fallback)
No JSX structural changes were made (only className and data-* additions)
The user can accept or reject the entire upgrade as one unit

The Slop Catalog — Common Patterns and Their Cures

Quick-reference for the most common aesthetic crimes. Look up the pattern, apply the cure.

Slop Pattern	The Crime	The Cure
`font-family: Arial, Helvetica, sans-serif`	Body font as display font	Import Outfit/Satoshi/Cabinet Grotesk for headings
`color: #000; background: #fff`	Pure black-on-white	`color: #1a1a1a; background: #FAFAF9`
`background: #0d6efd`	Bootstrap primary blue	Choose a brand-appropriate accent color
`box-shadow: 0 2px 4px rgba(0,0,0,0.1)`	Generic default shadow	`box-shadow: 0 1px 3px rgba(0,0,0,0.04)` at rest, expand on hover
`border-radius: 4px`	Bootstrap default radius	Commit to a radius language: 8/12/16/9999
`border: 1px solid #dee2e6`	Cool gray border	`border: 1px solid rgba(0,0,0,0.08)` — warm, subtle
`transition: all 0.15s ease-in-out`	Bootstrap default transition	`transition: all 0.3s cubic-bezier(0.22, 1, 0.36, 1)`
`padding: 1rem` on a card	Cramped card padding	`padding: 2rem` minimum — cards need to breathe
`margin-bottom: 0.5rem` heading→body	Cramped heading gap	`margin-bottom: 1.5rem` — let the heading land
`gap: 1rem` in a card grid	Tight grid gap	`gap: 1.5rem` minimum — cards need separation
No `:hover` on buttons	Dead, unresponsive buttons	`translateY(-2px) + shadow expansion + custom easing`
No `:hover` on cards	Static, lifeless cards	`translateY(-4px) + shadow expansion + border glow`
No entry animation	Instant static mount	Staggered fade-up-deblur on above-fold elements
`h1 { font-size: 2rem }`	Undersized heading	`font-size: clamp(2.25rem, 5vw, 3.75rem)`
`line-height: 1.2` on headings	Too loose for display	`line-height: 1.05` — tight, architectural
No letter-spacing on headings	Loose, amateur tracking	`letter-spacing: -0.03em` — tighten
`py-3` section padding	Cramped sections	`py-20 md:py-32` — sections are chapters, not paragraphs
Zebra-striped tables	2010 Bootstrap energy	Kill stripes, add subtle hover row highlight
`.badge { font-size: 0.75em }`	Tiny, cramped badges	`padding: 0.25rem 0.75rem; font-size: 0.75rem; border-radius: 9999px`
No `::placeholder` styling on inputs	Default gray placeholder	`color: var(--color-text-3); opacity: 0.7`

Edge Cases

When the code uses CSS-in-JS (styled-components, Emotion)

Apply token prescriptions as a CSS custom property layer (:root variables)
Override styled-component styles via a global createGlobalStyle that references the tokens
For component-level overrides, add a gold-overrides.ts file with styled-component overrides
Never modify the existing styled-component definitions inline — create override wrappers

When the code uses Tailwind CSS

Override Tailwind's theme in tailwind.config.js with the gold tokens (colors, fonts, radii, shadows)
Use @layer utilities for atmosphere and motion additions
Replace Tailwind color classes systematically: text-gray-900 → text-[#1a1a1a] or define custom colors in config
Replace shadow-sm / shadow-md → custom shadow values in config
Replace rounded / rounded-md → custom radii in config
This is the safest approach for Tailwind because it changes the design system at the config level, not in every component file

When the code uses Material UI / Chakra / Ant Design

Override the theme provider configuration — these libraries are designed for theme customization
Focus on the theme object: colors, typography, spacing, radii, shadows
Add component-level sx overrides or styled() wrappers for atmosphere and motion
Never fight the component library's structure — work within its theming system

When the code is vanilla HTML/CSS (no framework)

Add gold.css as the LAST stylesheet in the <head>
Use CSS specificity to override existing styles without editing them
If existing styles use !important, your overrides may need !important too (unfortunate but necessary)
Add the ScrollReveal script as a <script> before </body>

When the user says "just make the hero look good"

Do NOT upgrade the entire site. Apply the pipeline to the hero section only:

Audit the hero component
Extract its current design decisions
Prescribe the gold replacements for that section
Execute surgery on that section's CSS
Verify nothing else broke

Respect the user's scope. Upgrading more than asked wastes time and introduces risk.

The Core Principles

The patient must survive. A beautiful app that no longer functions is worse than an ugly app that works. Test after every surgery layer. Functionality always trumps aesthetics.

CSS overrides, never JS rewrites. Your tools are className changes, new CSS files, and data-attributes. You do not rewrite component logic, refactor state management, or restructure JSX hierarchies. If a visual upgrade requires changing JS logic, find a CSS-only alternative.

The gold.css is a single unit. One file, loaded last, that contains the entire visual upgrade. The user can add it (upgrade) or remove it (revert) with a single import. This is the surgical philosophy: clean entry, clean exit.

Warmth over neutrality. Every premium design uses warm tones — off-white backgrounds, warm near-black text, warm gray borders. Cold neutrals (pure gray, pure white, pure black) feel clinical and undesigned. The fastest single upgrade is replacing the color temperature.

Spacing is the secret. The single change that has the most dramatic impact is increasing spacing — section padding, card padding, heading gaps, grid gaps. Cramped spacing is the hallmark of amateur design. Generous spacing is the hallmark of premium design. When in doubt, add more space.

Display fonts separate amateurs from professionals. Swapping the heading font from Arial/system-ui to a proper display font (Outfit, Satoshi, Cabinet Grotesk, Clash Display) is the highest-impact single change. Everything else builds on this foundation.

About