Vibecode Website Upgrade Playbook

---
name: vibecode-upgrade
description: "A step-by-step playbook to upgrade vibecode websites from functional to polished, consistent products by auditing styles, unifying components, and building a design system."
metadata:
  tags: "visual-design, frontend-audit, ui-polish, design-system, component-unification, vibecode, web-polish"
  source: "https://skilldb.dev/skills/web-polish-skills/vibecode-upgrade"
  pack: "web-polish-skills"
  category: "Visual Arts & Design"
---

# Vibecode Website Upgrade Playbook

## When to use this skill
Use when the user says things like:
- "How do I upgrade a vibecode website to be polished?"
- "I need a playbook to unify a vibecode site's UI."
- "Show me an audit process for vibecode site polish."
- "Provide design-system steps for vibecode upgrades."
- "What is a phased upgrade plan for vibecode websites?"


You are a senior frontend engineer who takes vibecoded websites — sites built through AI
prompts, rapid prototyping, or incremental feature-by-feature development — and transforms
them from functional prototypes into polished, consistent, professional products. You don't
redesign. You systematize, unify, and polish what's already there.

## Why Vibecoded Sites Need This

AI-generated code produces components in isolation. Each prompt creates a locally-correct
solution that doesn't know about the other components on the site. The result:

- **5 button styles** because each was generated by a different prompt
- **12 shades of gray** because each component picked its own
- **Modals that don't match** because the settings modal was built months after the delete confirmation
- **No loading states** because "show a spinner" wasn't in the original prompt
- **Broken mobile** because the AI optimized for the viewport it was shown
- **No design system** because there was never a design phase — just feature requests

This playbook fixes all of it in a systematic, non-destructive way.

## The Upgrade Process

### Phase 0: Don't Break Anything (30 minutes)

Before touching code:

1. **Screenshot every page** at desktop and mobile widths. These are your before photos.
2. **Run the app locally** and click through every feature. Note anything that's broken.
3. **Check for tests.** If they exist, run them. They're your safety net.
4. **Create a branch.** All upgrade work happens on a branch, not main.

### Phase 1: Audit (1-2 hours)

Use the `ui-audit` skill to systematically catalog every inconsistency:

1. **Extract all color values.** Group duplicates. Count unique values.
2. **Extract all font sizes.** Count how many exist vs. how many should (6-8).
3. **Extract all spacing values.** Check if they follow a scale or are random.
4. **Inventory every component type** (buttons, inputs, cards, modals, etc.).
5. **Document every missing state** (loading, empty, error, hover, focus, disabled).

The output is a prioritized list of everything that needs fixing.

### Phase 2: Design Tokens (1-2 hours)

Use the `design-token-extraction` skill to establish the foundation:

1. **Consolidate colors** to a single neutral scale + one primary + semantic states.
2. **Establish a type scale** of 6-8 sizes with consistent weights and line heights.
3. **Define a spacing scale** based on an 8px grid.
4. **Set border radius, shadow, and transition tokens.**
5. **Create a CSS variables file** (or Tailwind config) with all tokens.
6. **Build a migration map** from old values to new tokens.

### Phase 3: Typography Cleanup (1 hour)

Use the `typography-cleanup` skill:

1. **Replace all font-size values** with scale tokens.
2. **Consolidate font families** to 1-2.
3. **Standardize weights** to 3 (normal, medium, semibold).
4. **Fix heading hierarchy** so h1 > h2 > h3 is visually clear.

### Phase 4: Color Unification (1 hour)

Use the `color-system-repair` skill:

1. **Replace all hardcoded colors** with token references.
2. **Consolidate near-duplicate grays** to one neutral scale.
3. **Verify contrast** on all text/background combinations.
4. **Fix semantic color usage** (error = red, success = green, consistent everywhere).

### Phase 5: Component Unification (2-4 hours)

Use the `component-unification` skill — this is the biggest phase:

**Order of operations (most impactful first):**

1. **Buttons.** Unify all button styles into one `<Button>` component with variants.
2. **Form inputs.** Make all text inputs, selects, textareas share one design language.
3. **Cards.** Same radius, shadow, padding, border everywhere.
4. **Modals/Dialogs.** One component with consistent overlay, animation, close behavior.
5. **Alerts/Toasts.** Consistent success/error/warning/info styling.
6. **Navigation.** One header, one footer, one sidebar, used everywhere.
7. **Tables.** Consistent header, row, hover, responsive behavior.
8. **Everything else.** Badges, avatars, tooltips, tabs, accordions, pagination.

For each component:
- Pick the best existing version
- Parameterize it into a proper shared component
- Replace every instance across the codebase
- Delete the old implementations

### Phase 6: Form System (1-2 hours)

Use the `form-elements` skill:

1. **Match all input heights** so they align in rows.
2. **Unify focus rings** across all form elements.
3. **Create a FormField wrapper** for consistent label + input + error layout.
4. **Fix the file upload** so it matches the site's button/input styling.
5. **Add proper validation UI** to every form.

### Phase 7: Responsive Repair (1-2 hours)

Use the `responsive-repair` skill:

1. **Test at 375px, 768px, 1024px, 1280px.**
2. **Fix overflow** — no horizontal scrollbars at any width.
3. **Fix grids** — collapse columns on mobile.
4. **Fix navigation** — add mobile menu if missing.
5. **Fix modals** — full-width on mobile.
6. **Fix tables** — horizontal scroll or card view on mobile.
7. **Fix typography** — scale down headings for mobile.
8. **Fix touch targets** — minimum 44px tap size.

### Phase 8: Visual Polish (1-2 hours)

Use the `visual-polish` skill:

1. **Add transitions** to every state change (150-200ms).
2. **Add hover states** to every interactive element.
3. **Add focus rings** to every focusable element.
4. **Add loading states** — skeletons for content, spinners for buttons.
5. **Add empty states** — no blank white spaces.
6. **Add error states** — every form and API call handles errors visually.
7. **Smooth scrolling, scroll margins, scrollbar styling.**
8. **Micro-interactions** — copy feedback, save confirmations, count animations.

### Phase 9: Dark Mode (Optional, 1-2 hours)

Use the `dark-mode-retrofit` skill if dark mode is desired:

1. **Convert all colors to CSS variables** (done in Phase 2).
2. **Create dark theme variable set.**
3. **Add theme toggle with persistence.**
4. **Verify every component in dark mode.**
5. **Handle images, code blocks, embeds.**
6. **Prevent white flash on page load.**

### Phase 10: Final Verification (1 hour)

1. **Compare before/after screenshots.** The site should look the same but better.
2. **Run Lighthouse audit.** Performance, accessibility, best practices, SEO.
3. **Test every page at every breakpoint.**
4. **Test every interactive element** (buttons, forms, modals, navigation).
5. **Test in multiple browsers** (Chrome, Firefox, Safari, Edge).
6. **Run existing tests.** Nothing should break.

## The Deliverables

After the upgrade, the codebase has:

```
components/
  ui/              # 15-25 shared, parameterized components
    Button.tsx
    Input.tsx
    Select.tsx
    Textarea.tsx
    Checkbox.tsx
    Toggle.tsx
    Card.tsx
    Dialog.tsx
    Alert.tsx
    Toast.tsx
    Badge.tsx
    Avatar.tsx
    Skeleton.tsx
    EmptyState.tsx
    FileUpload.tsx
    Tooltip.tsx
    Dropdown.tsx
    Tabs.tsx
    Table.tsx
    FormField.tsx
    ...

  layout/           # Shared layout components
    Header.tsx
    Footer.tsx
    Sidebar.tsx
    Container.tsx

styles/
  tokens.css        # All design tokens (or tailwind.config.js)
  globals.css       # Reset, base styles, transitions
```

Every component uses tokens. Every page uses shared components.
Every interactive element has hover, focus, disabled, and loading states.
Typography follows a clean scale. Colors are minimal and purposeful.
Mobile works. Dark mode works (if included).

## Time Estimates by Site Size

| Site Size | Pages | Components | Estimated Time |
|-----------|-------|------------|---------------|
| Small     | 3-5   | 10-15     | 4-8 hours     |
| Medium    | 6-15  | 15-30     | 8-16 hours    |
| Large     | 15+   | 30+       | 16-40 hours   |

## Principles

1. **Don't redesign.** The goal is consistency and polish, not a new look.
2. **Work incrementally.** Each phase leaves the site in a working, improved state.
3. **One component at a time.** Don't try to unify everything simultaneously.
4. **Visual diff after every change.** Catch regressions immediately.
5. **Delete old code.** After replacing an inline button with the shared component, delete the old inline styles.
6. **Resist scope creep.** This is a polish pass, not a feature sprint.