---
name: frontend-design-excellence
description: Quality gate for frontend builds. Ensures outputs look like they were made by a senior designer + senior dev, not generic AI slop. Use AFTER building but BEFORE delivering.
---

# Frontend Design Excellence Checklist

**Purpose:** Catch bland, generic outputs before delivery. Every product should feel intentionally designed.

## The "Senior Test"

Ask: *Would a senior designer at a top agency be embarrassed to show this in their portfolio?*

If yes → fix it before delivering.

---

## 🚫 Anti-Patterns (The Bland Checklist)

If ANY of these are true, the build fails the quality bar:

### Visual Blandness
- [ ] **Emoji as primary visual** — Using 🎯 📊 🚀 instead of real imagery
- [ ] **Generic SVG icons only** — Lucide/Heroicons with no custom elements
- [ ] **Flat colored boxes** — Cards that are just `bg-blue-100 rounded-lg p-4`
- [ ] **No hero image** — Text-only hero sections
- [ ] **Stock gradient backgrounds** — `bg-gradient-to-r from-blue-500 to-purple-500`
- [ ] **Inter/system fonts everywhere** — No typography personality
- [ ] **Bootstrap-style grid** — 3 equal columns, repeated sections
- [ ] **No visual hierarchy** — Everything same size/weight
- [ ] **White background + gray text** — Zero atmosphere

### Code Blandness
- [ ] **No hover states** — Static buttons and cards
- [ ] **No transitions** — Jarring state changes
- [ ] **No loading states** — Empty or frozen UI during fetches
- [ ] **No empty states** — Blank screens when no data
- [ ] **No micro-interactions** — Nothing responds to user input
- [ ] **Mobile afterthought** — Desktop-only layouts that stack poorly

---

## ✅ Required Elements

Every product page MUST have:

### 1. Custom Hero Visual
**Not optional.** Generate with `nano-banana-pro` or source quality stock.

```markdown
# Hero Image Requirements
- Product illustration OR lifestyle photography OR abstract branded graphic
- Minimum 1200x630px (OG image size)
- Must match brand color palette
- NO generic gradients, NO placeholder boxes
```

**Prompt template for image generation:**
```
Create a [style] illustration for [product name], a [product description].
Style: [brand personality - modern/playful/professional/bold]
Colors: [primary], [secondary], [accent]
Mood: [emotion the product evokes]
Include: [key visual elements related to the product]
Exclude: text, logos, UI elements
```

### 2. Typography Personality
- **Display font** — Headlines use something distinctive (not Inter)
- **Proper scale** — Hero text is LARGE (clamp 3rem to 6rem)
- **Letter-spacing** — Tightened on headlines
- **Font pairing** — Display + body fonts complement each other

### 3. Visual Depth
At least 3 of these:
- [ ] Layered shadows (not just `shadow-md`)
- [ ] Glassmorphism elements
- [ ] Gradient overlays on images
- [ ] Subtle background patterns/textures
- [ ] Floating/offset elements
- [ ] Border treatments (not just `border rounded`)

### 4. Motion & Interaction
- [ ] Button hover states (scale, color shift, shadow lift)
- [ ] Card hover states (lift, glow, or reveal)
- [ ] Page transitions or scroll animations
- [ ] Loading skeletons (not spinners)
- [ ] Success/error state animations

### 5. Layout Sophistication
At least one of:
- [ ] Bento grid layout
- [ ] Asymmetric hero section
- [ ] Overlapping elements
- [ ] Full-bleed sections breaking the container
- [ ] Horizontal scroll section (testimonials, features)

---

## 🎨 Image Generation Protocol

**When to generate images:**

| Section | Image Type | Tool |
|---------|-----------|------|
| Hero | Product illustration or lifestyle | `nano-banana-pro` |
| Features | Icon illustrations (not line icons) | `nano-banana-pro` |
| Testimonials | Avatar placeholders → real-looking | `nano-banana-pro` |
| About/Team | Abstract brand graphics | `nano-banana-pro` |
| Blog/Content | Article featured images | `nano-banana-pro` |
| 404/Empty states | Branded illustrations | `nano-banana-pro` |

**When to use stock:**
- Lifestyle/photography needs (Unsplash, Pexels)
- Specific real-world objects
- Diverse human photography

**Never acceptable:**
- Placeholder.com boxes
- Emoji as hero visuals
- Generic gradient-only backgrounds
- Lorem ipsum text (use real copy)

---

## 🔍 Quality Review Process

Before delivering ANY frontend build:

### Step 1: Screenshot Review
Take full-page screenshots of:
- [ ] Landing/home page
- [ ] One feature page
- [ ] Mobile view of landing

### Step 2: Checklist Audit
Run through anti-patterns above. Any hits = must fix.

### Step 3: The Squint Test
Squint at the screenshots. You should see:
- Clear visual hierarchy (something dominates)
- Color harmony (not random)
- Intentional whitespace (not just margins)
- A "signature element" (something memorable)

### Step 4: Compare to Reference
Does it look as good as:
- Linear.app (for SaaS)
- Stripe.com (for developer tools)
- Airbnb.com (for marketplaces)
- Apple.com (for consumer products)

If not → identify what's missing and fix.

---

## 📁 Reference Gallery

Quality bar examples (study these):

**SaaS / Productivity:**
- linear.app — Minimal but RICH in detail
- notion.so — Playful illustrations + clean UI
- figma.com — Bold typography + product shots

**Developer Tools:**
- stripe.com — Code + design harmony
- vercel.com — Dark mode done right
- railway.app — Personality in every corner

**Consumer / Lifestyle:**
- airbnb.com — Photography-forward
- headspace.com — Illustration-driven calm
- spotify.com — Bold color + dynamic layouts

**Agency / Creative:**
- linear.app/about — Storytelling through design
- basement.studio — Experimental but usable
- resend.com — Minimalist with strong type

---

## 🛠️ Quick Fixes for Common Issues

### "It looks flat"
→ Add layered shadows: `shadow-sm` on element + `shadow-xl` on container
→ Use gradient overlays on images
→ Add subtle background patterns

### "It looks generic"
→ Pick ONE signature color and use it boldly
→ Choose a distinctive display font
→ Add ONE unexpected element (angled section, blob shape, etc.)

### "It looks empty"
→ Generate hero illustration immediately
→ Add background visual texture
→ Use full-bleed sections with images

### "It looks like a template"
→ Break the grid somewhere
→ Add custom illustrations
→ Create asymmetric layouts
→ Use unexpected color combinations

---

## Integration with Build Process

**In web-app-builder skill, add this gate:**

After build completes, before announcing "done":
1. Load `frontend-design-excellence` skill
2. Run through checklist
3. Generate any missing hero images
4. Fix any anti-pattern violations
5. THEN deliver

This is not optional polish — it's baseline quality.
