Vibecoded websites are not bad -- they are unsystematized. Each component was generated correctly in isolation, but no single prompt ever unified them into a coherent design system. The upgrade process is not about starting over; it is about finding the best version of each element that already exists in the codebase and making everything else match it. This preserves the original intent while adding the consistency and polish that make a site feel professionally built.

## Key Points

- **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
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.
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).

Vibecode Website Upgrade Playbook

Core Philosophy

Vibecoded websites are not bad -- they are unsystematized. Each component was generated correctly in isolation, but no single prompt ever unified them into a coherent design system. The upgrade process is not about starting over; it is about finding the best version of each element that already exists in the codebase and making everything else match it. This preserves the original intent while adding the consistency and polish that make a site feel professionally built.

The upgrade must be non-destructive and incremental. Every phase should leave the site in a working, improved state. There is no "big bang" refactor where the site looks worse before it looks better. Instead, each step -- token extraction, typography cleanup, component unification -- delivers visible improvement independently. If the process stops at any phase, the site is still better than when it started.

The goal is consistency and polish, not a new look. Users who return to the site after the upgrade should feel that it got better without being able to pinpoint exactly what changed. The brand, layout, and feature set remain the same; what changes is the feeling of intentionality. Every color, spacing value, and component variant now looks like it was chosen on purpose rather than generated at random.

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

Anti-Patterns

• Big-bang refactor: Attempting to unify everything simultaneously instead of working phase by phase. This creates a period where the site looks worse than before and makes it impossible to identify which change broke something.
• Scope creep into features: Using the polish pass as an opportunity to add new features or change functionality. This is a consistency pass, not a feature sprint. Adding features introduces new untested inconsistencies.
• Skipping the screenshot phase: Starting code changes without capturing before screenshots of every page at every breakpoint. Without before photos, there is no way to verify that the upgrade preserved the original intent.
• Leaving old implementations alive: Replacing inline button styles with a shared Button component but not deleting the old inline styles. Dead code accumulates and eventually gets used again, recreating inconsistency.
• Touching the design system during migration: Changing token values or component designs while simultaneously migrating old code to use them. This makes it impossible to distinguish migration bugs from design bugs.

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.