Section Builder

This skill provides patterns and guidelines for building website sections that are visually stunning, highly functional, and optimized for conversions.

When to Use This Skill

• Creating any website section (hero, features, pricing, etc.)
• Implementing custom section designs from inspiration
• Building responsive section layouts
• Adding animations and interactions to sections

Core Principles

1. Section Anatomy

Every section should have:

<section className="relative py-section-md overflow-hidden">
  {/* Optional: Background layer */}
  <div className="absolute inset-0 -z-10">
    {/* Gradients, patterns, images */}
  </div>

  {/* Container */}
  <div className="container mx-auto px-4">
    {/* Section header (optional) */}
    <div className="text-center max-w-3xl mx-auto mb-12">
      <span className="text-sm font-medium text-primary">Label</span>
      <h2 className="text-3xl md:text-4xl font-bold mt-2">Headline</h2>
      <p className="text-muted-foreground mt-4">Supporting text</p>
    </div>

    {/* Section content */}
    <div className="grid ...">
      {/* Content */}
    </div>
  </div>
</section>

2. Hero Section Patterns

Pattern A: Split Hero (Image + Text)

<section className="min-h-[90vh] flex items-center">
  <div className="container grid lg:grid-cols-2 gap-12 items-center">
    <div className="space-y-6">
      <Badge>New Feature</Badge>
      <h1 className="text-4xl md:text-5xl lg:text-6xl font-bold tracking-tight">
        Compelling headline that <span className="text-primary">captures attention</span>
      </h1>
      <p className="text-xl text-muted-foreground max-w-lg">
        Supporting description that explains the value proposition clearly.
      </p>
      <div className="flex flex-wrap gap-4">
        <Button size="lg">Primary CTA</Button>
        <Button size="lg" variant="outline">Secondary CTA</Button>
      </div>
    </div>
    <div className="relative">
      <Image src="..." alt="..." className="rounded-2xl shadow-2xl" />
    </div>
  </div>
</section>

Pattern B: Centered Hero

<section className="min-h-[90vh] flex items-center justify-center text-center">
  <div className="container max-w-4xl space-y-8">
    <Badge className="mx-auto">Announcement</Badge>
    <h1 className="text-5xl md:text-6xl lg:text-7xl font-bold">
      Bold statement headline
    </h1>
    <p className="text-xl text-muted-foreground max-w-2xl mx-auto">
      Description text that provides context and builds interest.
    </p>
    <div className="flex justify-center gap-4">
      <Button size="lg">Get Started</Button>
    </div>
  </div>
</section>

Pattern C: Video/Media Hero

<section className="relative min-h-screen flex items-center">
  <video
    autoPlay
    muted
    loop
    className="absolute inset-0 w-full h-full object-cover"
  >
    <source src="..." type="video/mp4" />
  </video>
  <div className="absolute inset-0 bg-black/50" />
  <div className="relative container text-white text-center">
    {/* Content */}
  </div>
</section>

3. Feature Section Patterns

Grid Layout:

<section className="py-section-lg">
  <div className="container">
    <div className="text-center max-w-2xl mx-auto mb-16">
      <h2>Features</h2>
      <p>Description</p>
    </div>
    <div className="grid md:grid-cols-2 lg:grid-cols-3 gap-8">
      {features.map((feature) => (
        <div key={feature.id} className="p-6 rounded-2xl border bg-card">
          <div className="w-12 h-12 rounded-lg bg-primary/10 flex items-center justify-center mb-4">
            <feature.icon className="w-6 h-6 text-primary" />
          </div>
          <h3 className="text-xl font-semibold mb-2">{feature.title}</h3>
          <p className="text-muted-foreground">{feature.description}</p>
        </div>
      ))}
    </div>
  </div>
</section>

Bento Grid:

<div className="grid grid-cols-4 grid-rows-3 gap-4">
  <div className="col-span-2 row-span-2 bg-card rounded-2xl p-8">
    {/* Large feature */}
  </div>
  <div className="col-span-2 bg-card rounded-2xl p-6">
    {/* Medium feature */}
  </div>
  <div className="bg-card rounded-2xl p-6">
    {/* Small feature */}
  </div>
  <div className="bg-card rounded-2xl p-6">
    {/* Small feature */}
  </div>
</div>

4. Testimonial Patterns

Carousel:

<section className="py-section-lg bg-muted/50">
  <div className="container">
    <Carousel>
      {testimonials.map((t) => (
        <Card key={t.id} className="p-8">
          <div className="flex gap-1 mb-4">
            {[...Array(5)].map((_, i) => (
              <Star key={i} className="w-5 h-5 fill-yellow-400 text-yellow-400" />
            ))}
          </div>
          <blockquote className="text-lg mb-6">"{t.quote}"</blockquote>
          <div className="flex items-center gap-4">
            <Avatar src={t.avatar} />
            <div>
              <p className="font-semibold">{t.name}</p>
              <p className="text-sm text-muted-foreground">{t.role}</p>
            </div>
          </div>
        </Card>
      ))}
    </Carousel>
  </div>
</section>

Grid with Masonry:

<div className="columns-1 md:columns-2 lg:columns-3 gap-4 space-y-4">
  {testimonials.map((t) => (
    <Card key={t.id} className="break-inside-avoid">
      {/* Testimonial content */}
    </Card>
  ))}
</div>

5. Pricing Section

<section className="py-section-lg">
  <div className="container">
    <div className="text-center mb-12">
      <h2>Simple, transparent pricing</h2>
      <div className="flex justify-center gap-2 mt-4">
        <Button variant={billing === 'monthly' ? 'default' : 'outline'}>
          Monthly
        </Button>
        <Button variant={billing === 'yearly' ? 'default' : 'outline'}>
          Yearly (Save 20%)
        </Button>
      </div>
    </div>

    <div className="grid md:grid-cols-3 gap-8 max-w-5xl mx-auto">
      {plans.map((plan) => (
        <Card
          key={plan.id}
          className={cn(
            "p-8",
            plan.popular && "border-primary shadow-lg scale-105"
          )}
        >
          {plan.popular && (
            <Badge className="absolute -top-3 left-1/2 -translate-x-1/2">
              Most Popular
            </Badge>
          )}
          <h3 className="text-xl font-bold">{plan.name}</h3>
          <p className="text-muted-foreground mt-2">{plan.description}</p>
          <div className="my-6">
            <span className="text-4xl font-bold">${plan.price}</span>
            <span className="text-muted-foreground">/month</span>
          </div>
          <ul className="space-y-3 mb-8">
            {plan.features.map((f) => (
              <li key={f} className="flex items-center gap-2">
                <Check className="w-5 h-5 text-green-500" />
                <span>{f}</span>
              </li>
            ))}
          </ul>
          <Button className="w-full" variant={plan.popular ? 'default' : 'outline'}>
            Get Started
          </Button>
        </Card>
      ))}
    </div>
  </div>
</section>

6. CTA Section

Simple CTA:

<section className="py-section-lg bg-primary text-primary-foreground">
  <div className="container text-center">
    <h2 className="text-3xl md:text-4xl font-bold mb-4">
      Ready to get started?
    </h2>
    <p className="text-primary-foreground/80 max-w-xl mx-auto mb-8">
      Join thousands of satisfied customers today.
    </p>
    <div className="flex justify-center gap-4">
      <Button size="lg" variant="secondary">
        Start Free Trial
      </Button>
    </div>
  </div>
</section>

7. Responsive Patterns

Mobile-First Grid:

/* Stack on mobile, side-by-side on larger screens */
.responsive-grid {
  display: grid;
  grid-template-columns: 1fr;
  gap: 2rem;
}

@media (min-width: 768px) {
  .responsive-grid {
    grid-template-columns: repeat(2, 1fr);
  }
}

@media (min-width: 1024px) {
  .responsive-grid {
    grid-template-columns: repeat(3, 1fr);
  }
}

Tailwind Responsive:

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">

8. Visual Enhancements

Gradient Backgrounds:

{/* Mesh gradient */}
<div className="absolute inset-0 -z-10">
  <div className="absolute top-0 -left-4 w-72 h-72 bg-purple-300 rounded-full mix-blend-multiply filter blur-xl opacity-70 animate-blob" />
  <div className="absolute top-0 -right-4 w-72 h-72 bg-yellow-300 rounded-full mix-blend-multiply filter blur-xl opacity-70 animate-blob animation-delay-2000" />
  <div className="absolute -bottom-8 left-20 w-72 h-72 bg-pink-300 rounded-full mix-blend-multiply filter blur-xl opacity-70 animate-blob animation-delay-4000" />
</div>

Noise Texture:

.noise-bg::before {
  content: "";
  position: absolute;
  inset: 0;
  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)'/%3E%3C/svg%3E");
  opacity: 0.03;
  pointer-events: none;
}

---

⚠️ Visual Quality Requirements (KRITISCH)

This section defines mandatory visual standards. Sections that don't meet these requirements will FAIL the Design Excellence check.

BANNED Patterns (Auto-Fail)

These patterns result in automatic Design Excellence failure:

Pattern	Why It's Bad	Example
Plain white backgrounds	No atmosphere, generic	<section className="bg-white">
Generic fonts as display	Looks like AI output	font-family: Inter, Arial, sans-serif
Cramped spacing	Unprofessional	py-8, py-12 on sections
Equal card grids	Cookie-cutter look	grid-cols-3 with identical cards
Generic blue buttons	No brand identity	bg-blue-600
Untreated images	Stock photo look	<Image className="rounded-lg">

❌ BAD: Generic Section (DO NOT DO THIS)

// ❌ FAIL - This will fail Design Excellence
<section className="py-12 bg-white">
  <div className="container mx-auto text-center">
    <h2 className="text-2xl font-semibold">Our Features</h2>
    <p className="text-gray-600">Check out what we offer</p>
    <div className="grid grid-cols-3 gap-4 mt-8">
      <div className="p-4 border rounded-lg">
        <h3 className="font-medium">Feature 1</h3>
        <p className="text-sm text-gray-500">Description text</p>
      </div>
      {/* More identical cards */}
    </div>
  </div>
</section>

Why this fails:

• py-12 - Too cramped, minimum is py-24
• bg-white - Plain, no atmosphere
• text-2xl - Not dramatic enough for headline
• font-semibold - Generic weight
• grid-cols-3 gap-4 - Cookie-cutter grid
• No background treatment
• No visual hierarchy
• No distinctive elements

✅ GOOD: Distinctive Section (DO THIS)

// ✅ PASS - This meets Design Excellence standards
<section className="py-32 lg:py-48 relative overflow-hidden">
  {/* Background treatment - atmosphere */}
  <div className="absolute inset-0 bg-gradient-to-br from-primary/5 via-background to-accent/5" />
  <div className="absolute top-20 -right-20 w-96 h-96 bg-primary/10 rounded-full blur-3xl" />

  <Container>
    {/* Section header with dramatic typography */}
    <motion.div
      initial={{ opacity: 0, y: 20 }}
      whileInView={{ opacity: 1, y: 0 }}
      viewport={{ once: true }}
      className="max-w-3xl mb-20"
    >
      <span className="text-sm font-medium text-primary tracking-wider uppercase">
        Why Choose Us
      </span>
      <h2 className="font-display text-4xl md:text-5xl lg:text-6xl font-bold mt-4 tracking-tight">
        Features that set us <span className="text-primary">apart</span>
      </h2>
      <p className="text-lg md:text-xl text-muted-foreground mt-6 max-w-2xl">
        Description with proper hierarchy and breathing room.
      </p>
    </motion.div>

    {/* Asymmetric grid with varied cards */}
    <div className="grid md:grid-cols-2 lg:grid-cols-3 gap-8">
      {features.map((feature, i) => (
        <motion.div
          key={feature.id}
          initial={{ opacity: 0, y: 20 }}
          whileInView={{ opacity: 1, y: 0 }}
          viewport={{ once: true }}
          transition={{ delay: i * 0.1 }}
          className="group relative"
        >
          {/* Card with hover effect */}
          <div className="relative p-8 rounded-2xl bg-card/50 backdrop-blur-sm border-0 shadow-lg transition-all duration-300 group-hover:shadow-xl group-hover:-translate-y-1">
            {/* Gradient border on hover */}
            <div className="absolute -inset-0.5 bg-gradient-to-r from-primary/20 to-accent/20 rounded-2xl opacity-0 group-hover:opacity-100 blur transition" />

            <div className="relative">
              <div className="w-14 h-14 rounded-xl bg-primary/10 flex items-center justify-center mb-6">
                <feature.icon className="w-7 h-7 text-primary" />
              </div>
              <h3 className="text-xl font-bold mb-3">{feature.title}</h3>
              <p className="text-muted-foreground leading-relaxed">{feature.description}</p>
            </div>
          </div>
        </motion.div>
      ))}
    </div>
  </Container>
</section>

Why this passes:

• py-32 lg:py-48 - Generous whitespace
• Gradient background with blur shapes - atmosphere
• text-5xl lg:text-6xl - Dramatic headline
• font-display - Distinctive font
• Staggered animations
• Card hover effects with gradient border
• Backdrop blur and shadow depth
• Visual hierarchy (label → headline → description → features)

Required Visual Elements

Every section MUST have at least 3 of these:

Element	Implementation
Background treatment	Gradient, blur shapes, pattern, or distinctive solid color
Dramatic typography	text-4xl minimum for headlines, distinctive font
Generous spacing	py-24 minimum, prefer py-32 or more
Visual hierarchy	Clear label → heading → body → content flow
Animation	Entrance animations with stagger
Hover states	Interactive feedback on cards/buttons
Depth	Shadows, blur, overlapping elements
Image treatment	Shadow, blur glow, overlay, or masking

Typography Scale

Element	Mobile	Desktop	Notes
Section Label	text-sm	text-sm	Uppercase, tracking-wider, text-primary
Section Headline	text-3xl	text-5xl/6xl	font-display, font-bold, tracking-tight
Section Description	text-base	text-lg/xl	text-muted-foreground, max-w constraint
Card Title	text-lg	text-xl	font-bold
Card Description	text-sm	text-base	text-muted-foreground

Spacing Scale

Element	Value	Tailwind
Section padding (min)	96px	py-24
Section padding (preferred)	128px	py-32
Section padding (dramatic)	192px	py-48
Content gap	32-64px	gap-8 to gap-16
Card padding	32px	p-8
Element spacing	16-24px	space-y-4 to space-y-6

---

Quality Checklist

Visual Quality (Design Excellence):

• Background has atmosphere (not plain white/gray)
• Typography is dramatic (4xl+ headlines, distinctive font)
• Spacing is generous (py-24+ on sections)
• Has 3+ distinctive visual elements
• No banned patterns present

Technical Quality:

• Section has clear visual hierarchy
• Content is readable at all breakpoints
• Proper spacing between elements
• CTAs are prominent and action-oriented
• Images are optimized and have alt text
• Animations enhance, not distract
• Accessible color contrast
• Mobile-first responsive design

---

📦 shadcnblocks Integration

Dieser Abschnitt beschreibt den Workflow für die Nutzung von shadcnblocks als Layout-Template.

Workflow

1. Download Component (exakter Befehl aus page-shapes):

   pnpm dlx shadcn add @shadcnblocks/feature-grid-2
   

2. Custom Styles entfernen (siehe Checkliste unten)

3. Design System anwenden (Design Tokens verwenden)

4. Container centern (IMMER mx-auto max-w-7xl)

5. Playwright Screenshot + AI-Analyse gegen Style-Bild

Setup-Anforderungen

components.json Registry:

{
  "registries": {
    "@shadcnblocks": {
      "url": "https://shadcnblocks.com/r/{name}",
      "headers": {
        "Authorization": "Bearer ${SHADCNBLOCKS_API_KEY}"
      }
    }
  }
}

Environment Variable:

export SHADCNBLOCKS_API_KEY=your_api_key_here

---

🔄 Custom Styles Entfernen - Checkliste

Bei JEDER shadcnblocks-Component müssen diese Styles entfernt/ersetzt werden:

Entfernen	Ersetzen mit
text-3xl, text-4xl etc. auf h1/h2	font-display text-4xl aus Design Tokens
text-gray-600, text-slate-500	text-muted-foreground
bg-white, bg-gray-50	bg-background, bg-muted
text-blue-600, text-indigo-500	text-primary
font-semibold, font-medium	Design Token Weights
py-12, py-16	Minimum py-24, bevorzugt py-32
gap-4, gap-6	Minimum gap-8
rounded-lg	rounded-xl oder rounded-2xl
Inline style={}	Tailwind Classes
max-w-6xl, max-w-5xl	max-w-7xl (Standard Container)

Container Centering (PFLICHT)

Alle Container MÜSSEN zentriert sein:

// ✅ RICHTIG
<div className="container mx-auto max-w-7xl px-4">

// ❌ FALSCH
<div className="max-w-6xl">
<div className="container">  // ohne mx-auto

---

📊 Layout-Empfehlungslogik

Statt Fragen zu stellen, gibt der Workflow Empfehlungen basierend auf Content-Menge:

Features/Services

Anzahl Items	Empfohlenes Layout
3-4	Horizontal Row oder 2x2 Grid
5-6	Grid 3x2 oder 2x3
7-9	Grid 3x3
10-12	Grid 4x3 oder 3x4
13+	Grid 4x4 oder Bento mit Pagination

Responsive Breakpoints:

• Desktop (lg): Max 4 Spalten
• Tablet (md): Max 3 Spalten
• Mobile: Max 2 Spalten

Team

Anzahl Members	Empfohlenes Layout
1-2	Side-by-side oder Featured
3-4	Grid 2x2 oder 4x1 Row
5-6	Featured Lead + Grid 4x1 darunter
7+	Grid 4x2 oder Carousel

Testimonials

Anzahl	Empfohlenes Layout
1	Single Quote, zentriert, gross
2-3	3-Column Grid
4+	Carousel oder Masonry

Pricing

Anzahl Plans	Empfohlenes Layout
2	Side-by-side, einer highlighted
3	3-Column, mittlerer highlighted
4+	Carousel oder Comparison Table

Beispiel-Output (Shape-Pages Phase 1)

════════════════════════════════════════════════════════════════
                    PAGE OVERVIEW: HOME
════════════════════════════════════════════════════════════════

┌───────────────────────────────────────────────────────────────┐
│ 1. HERO                                                       │
│ Split-Layout mit Text links, grossem Bild rechts.             │
│ Volle Viewport-Höhe, sofort sichtbarer CTA.                   │
└───────────────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────────────┐
│ 2. SERVICES (12 Items)                                        │
│ Grid mit Icon-Cards. 4 Spalten Desktop, 2 Mobile.             │
│ Jede Card: Icon + Titel + kurze Beschreibung.                 │
└───────────────────────────────────────────────────────────────┘

... weitere Sections ...

════════════════════════════════════════════════════════════════

---

🎯 Playwright Screenshot + AI-Analyse

Nach jeder Section-Implementation:

1. Screenshot erstellen:

   mcp__playwright__browser_navigate → URL
   mcp__playwright__browser_take_screenshot → fullPage: false, element spezifisch
   

2. AI-Analyse gegen Style-Bild:

   • Layout-Vergleich: Stimmt Grid/Spalten?
   • Spacing-Vergleich: Ähnliche Abstände?
   • Proportionen: Cards/Elemente ähnlich gross?
   • Typografie: Headlines/Body ähnliche Hierarchie?

3. Feedback geben:

   ✓ Layout passt (4x3 Grid wie im Bild)
   ✗ Cards zu eng → gap-8 auf gap-12 erhöhen
   ✗ Headlines zu klein → text-3xl auf text-4xl
   

4. Iterieren bis Match

Wichtig bei Style-Bild Analyse

• Das Bild zeigt den GEWÜNSCHTEN Style, nicht die exakte Anzahl Items
• Beispiel: Bild zeigt 6 Cards → Du implementierst trotzdem für 12 wenn das der Content ist
• Nur Layout, Spacing, Proportionen übernehmen - NICHT die Farben/Fonts (die kommen aus Design Tokens)