---
name: forge-redesign
description: Upgrading an existing app or website to premium quality without breaking it. Audit first, identify the AI smell (indigo gradient, card-in-card, cramped spacing), surgical edits over rewrites, framework-agnostic. Contains a 5-step audit, the top 10 changes that move the most, and a worked Tailwind diff. Use when the user wants to "make this look better" without rebuilding.
license: MIT
---

# forge-redesign

You are asked to make an existing app look better. Default agent attempts at "redesign" rewrite everything from scratch, introduce a different framework, and break half the existing functionality. This skill exists to upgrade taste without breaking work.

The mental model: **a redesign is a sequence of small, surgical improvements.** Each improvement is observable in isolation, reversible if wrong, and does not change behavior beyond what was scoped.

## Quick reference (the things you must never do during a redesign)

1. Switch the CSS framework (Tailwind → CSS Modules, vanilla → Tailwind, etc).
2. Add a new design dependency (Framer Motion, Lucide, custom font loader) without checking what's already there.
3. Restructure markup that has working behavior.
4. Change click handlers, form submissions, data fetching, or routes.
5. Refactor unrelated code "while you're in there."
6. Commit 50 visual changes in one diff (impossible to review).
7. Replace one purple gradient with a different gradient.
8. Add 6rem of padding everywhere without thinking about which sections matter.
9. Touch a `.test.ts` or `.spec.ts` file as part of a visual redesign.
10. Skip the audit step.

## Hard rules

### Audit before code

**1. First action is an audit, not an edit.** Read the existing code, identify actual problems, document them.

```markdown
# Redesign audit — landing page

Problems (top to bottom):
1. Hero section: type is 1.5rem, should be 4-6rem for visual weight.
2. CTA: indigo-violet gradient (AI fingerprint).
3. Section spacing: 2rem between sections (should be ≥6rem).
4. Features grid: 4 cards with shadow-lg + border, card-in-card-in-card.
5. Footer: 4 columns with 12 links each; reads as obligation.
6. Palette: 7 distinct hue families. Reduce to 3.
7. Icons: emoji 🚀 ✨ — replace with single-weight Lucide.
8. Typography: Inter at default tracking everywhere.

Out of scope:
- Auth flow (works fine; not visual).
- Pricing page (separate task).
```

**2. The audit is written down.** Even just for yourself. Three to ten bullets with specific places. "Hero section: type is 1.5rem, should be 4-6rem" beats "make hero bigger."

**3. Distinguish "AI smell" from "client choice."** Indigo-violet gradient is usually AI smell. Indigo-violet because that is the client's brand is a choice. Confirm which.

### Top 10 changes that move the most

In priority order, these are the changes with highest impact-per-effort. Apply in this order:

**4. Spacing and rhythm.** Cramped section spacing is the single largest tell. Bump vertical section padding to 6-10rem before anything else.

```diff
- <section className="py-12">
+ <section className="py-24 lg:py-32">
```

**5. Type hierarchy.** Identify display, body, caption sizes. Often the redesign is "make the display 3x larger, leave the rest."

```diff
- <h1 className="text-4xl font-bold">Welcome</h1>
+ <h1 className="text-[clamp(3rem,6vw,7rem)] font-medium tracking-[-0.035em] leading-[1.02]">Welcome</h1>
```

**6. Palette reduction.** Count distinct colors. If above 3, reduce. Usually keep brand color, background, one foreground.

**7. Card and shadow audit.** Remove card-in-card-in-card. Reduce shadow depth or remove. Often improves the page more than any new element.

```diff
- <div className="rounded-xl border shadow-lg p-6">
-   <div className="rounded-lg border shadow-sm p-4">
-     <div className="rounded-md p-3">Content</div>
-   </div>
- </div>
+ <section className="border rounded-xl p-8">
+   <h3 className="text-2xl font-medium mb-3">Title</h3>
+   <p className="text-zinc-600">Content</p>
+ </section>
```

**8. CTA discipline.** One primary per section, max. Solid fill or border-only, no gradient unless intentional brand choice.

```diff
- <button className="bg-gradient-to-r from-indigo-500 to-violet-500 text-white rounded-full px-6 py-3 shadow-xl">
-   Get Started ✨
- </button>
+ <button className="bg-zinc-900 text-white px-6 py-3 rounded-lg text-sm font-medium hover:bg-zinc-700 transition-colors">
+   Get started
+ </button>
```

**9. Replace emoji icons with single-weight icon library.**

```diff
- <button>🚀 Launch</button>
+ <button><RocketIcon size={16} strokeWidth={1.75} /> Launch</button>
```

**10. Remove "transition-all" + heavy shadows on hover.**

```diff
- className="shadow-lg hover:shadow-2xl transition-all duration-300"
+ className="transition-colors duration-200 hover:bg-zinc-50"
```

**11. Section ordering audit.** Often the redesign is also a reordering. The "social proof" section that's 8 sections deep should be 2.

**12. Type pair upgrade.** If using Inter for everything, add a real display face (Bricolage Grotesque, Fraunces, GT America) for headlines only.

**13. Reduce font sizes per section to 3 max.** Display, body, label.

### What NOT to do

**14. Do not change the framework.** Tailwind stays Tailwind. CSS Modules stay CSS Modules. Framework switches are scope creep.

**15. Do not introduce new dependencies.** Resist "this needs Framer Motion" or "let me add Lucide." Use what's there.

**16. Do not rewrite markup structure unless necessary.** Most redesigns work at the styling layer. Restructuring risks behavior changes.

**17. Do not touch behavior.** Click handlers, form submissions, data fetching, routes. None need to change for a visual redesign.

**18. Do not refactor unrelated code.** A redesign is not a cleanup pass. Pick one concern.

### Working with frameworks

#### Tailwind

- Update tokens in `tailwind.config` (v3) or `@theme` (v4). One change cascades.
- Search-and-replace utility classes thoughtfully. `bg-indigo-500` → `bg-orange-500` everywhere if brand changed.
- Tailwind cannot solve typography choices. Add a custom font via `@layer` if needed.

#### CSS Modules / vanilla CSS

- Work in CSS variables. `--color-accent: ...` defined once.
- Identify the cascade. A redesign at component level may be fighting global resets.

#### CSS-in-JS

- Theme objects usually centralize tokens; update there.
- Beware: many CSS-in-JS apps have inline styles bypassing the theme.

#### Component libraries (shadcn, Mantine, MUI)

- Re-theme via library primitives. Do not override individual components if a theme change covers it.
- shadcn copies primitives into your repo; you can edit them.

### Communicating with the user

**19. Show before/after when possible.** Two screenshots side by side. Trust is built through visible deltas.

**20. List the changes you made.** "Increased section spacing 2rem → 8rem. Reduced palette 6 → 3 colors. Removed card-in-card on features section."

**21. Note what you did NOT change.** Reassures the user their behavior is intact.

**22. If you ran into ambiguity, ask once.** "Your accent is indigo-violet today. Was that intentional or a leftover default?"

### Tools and methodology

**23. Use dev-tools inspector first.** Often a single line is responsible for the bulk of the visual problem.

**24. Make changes in small batches and verify visually.** Three CSS changes, save, look. Three more.

**25. Commit each batch separately.** If something breaks, `git bisect` finds it.

**26. Run existing tests after CSS changes.** Visual regression tests, Storybook, screenshot tests catch unintended effects.

### When the redesign needs more

**27. If structure is genuinely wrong, say so.** Surface the limitation: "the markup has cards nested four deep; I can soften the visual but the underlying structure is the issue. Want me to restructure?"

**28. "Make it look better" sometimes means "make it work better."** If the redesign reveals an underlying UX problem, surface it but do not unilaterally restructure.

## Common AI-output patterns to reject

| Pattern | Why wrong | Fix |
| --- | --- | --- |
| "Let me rewrite the page" | Massive scope creep | Audit + surgical edits |
| Replace Tailwind with CSS Modules | Framework switch | Work in existing framework |
| Add Framer Motion for hover effect | New dependency | Use CSS transitions |
| Refactor the handler "while I'm here" | Out of scope | Stop. Open a separate PR if needed. |
| One commit with 50 changes | Unreviewable | Split into thematic commits |
| Replace purple gradient with pink gradient | Same class of slop | Solid color or near-black |
| Add `py-32` to every section | Uniform, not hierarchical | Hero gets 8rem; content 6rem; dense 4rem |
| Move font from Inter to Inter Display | Same family | Pair Inter with a real display face |
| "Modernized the design system" with new tokens | Off-scope | Reuse existing tokens; redesign IS the constraint |

## Worked example: a Tailwind diff for a typical landing

```diff
 export function Hero() {
   return (
-    <section className="flex flex-col items-center justify-center text-center min-h-screen bg-gradient-to-br from-slate-50 to-blue-50 p-8">
-      <h1 className="text-5xl font-bold mb-4 bg-gradient-to-r from-indigo-500 to-violet-500 bg-clip-text text-transparent">
-        Welcome to Our Platform 🚀
+    <section className="bg-[#FBFAF7] px-6 lg:px-10 pt-32 pb-24">
+      <div className="max-w-6xl mx-auto">
+      <h1 className="text-[clamp(3rem,6vw,7rem)] font-medium leading-[1.02] tracking-[-0.035em] text-zinc-900 max-w-[16ch] mb-10">
+        The platform for shipping engineering teams.
       </h1>
-      <p className="text-lg text-gray-600 mb-8 max-w-2xl">
-        We provide blazingly fast, comprehensive solutions for modern teams.
+      <p className="text-xl text-zinc-600 leading-relaxed max-w-[40ch] mb-10">
+        One place for issues, decisions, and the work you ship today.
       </p>
-      <button className="bg-gradient-to-r from-indigo-500 to-violet-500 text-white px-8 py-4 rounded-full shadow-lg hover:shadow-xl transition-all duration-300">
-        Get Started ✨
+      <button className="bg-zinc-900 text-white px-6 py-3 rounded-lg text-sm font-medium hover:bg-zinc-800 transition-colors duration-200">
+        Get started →
       </button>
+      </div>
     </section>
   );
 }
```

Changes summarized:
- Section: removed `flex items-center justify-center text-center min-h-screen` (centered hero default), removed `bg-gradient-to-br` (purposeless background gradient).
- Container: added `max-w-6xl mx-auto`, switched to `pt-32 pb-24` (8rem top, 6rem bottom).
- H1: `text-5xl font-bold` → `clamp(3rem, 6vw, 7rem) font-medium tracking-[-0.035em]`; removed `bg-clip-text` gradient text; removed rocket emoji; tightened max-width.
- Lede: warm zinc-600 instead of `text-gray-600`; tighter line-length; better leading.
- CTA: solid near-black instead of gradient; removed shadow + transition-all; `rounded-lg` instead of `rounded-full`; named `transition-colors` instead of `transition-all`; removed sparkle emoji; replaced with arrow.

Nothing about the click handler, the data fetch, the route, or the page structure changed. Tests pass. Markup is the same hierarchy minus one wrapper.

## Workflow

When asked to redesign:

1. **Read the codebase.** Identify framework, styling approach, existing tokens.
2. **Run the app and look at it.** Note specific visual problems.
3. **Audit in writing.** 5-10 bullets with specific paths/elements.
4. **Identify the 3 changes that move the most.** Spacing, type hierarchy, palette usually.
5. **Make those first. Verify visually after each.**
6. **Make secondary improvements (cards, buttons, icons) after the big three.**
7. **Report what changed and what did not.**

## Verification

This skill is structural; verification is by review. Manual checklist after redesign:

- [ ] Section vertical spacing ≥6rem on landing-style pages.
- [ ] Three or fewer distinct hue families.
- [ ] No card-in-card-in-card.
- [ ] No default purple/violet gradient (unless intentional brand).
- [ ] CTA hierarchy clear: one primary per section.
- [ ] Existing behavior unchanged (tests pass, manual smoke check).
- [ ] Framework not switched, no new dependencies introduced.

## When to skip this skill

- Greenfield design (use [`forge-frontend`](../forge-frontend/SKILL.md)).
- Backend or non-visual work.
- Cosmetic changes to an internal admin tool where speed beats polish.

## Related skills

- [`forge-frontend`](../forge-frontend/SKILL.md) - the taste rules being applied.
- [`forge-soft`](../forge-soft/SKILL.md), [`forge-minimalist`](../forge-minimalist/SKILL.md), [`forge-brutalist`](../forge-brutalist/SKILL.md) - pick the target register before starting.