Page Architecture

Page Architecture

The bridge between business brief and design implementation. This skill defines WHAT goes where (information architecture) — not HOW it looks (that's frontend-aesthetics) or what style it has (that's styleguide).

Purpose

Every website starts as a blank canvas with the same question: "What pages do we need, and what goes on each page?" Page architecture answers this by translating business goals into a structured content plan. The output is a page specification document that downstream skills (frontend-aesthetics, css-architecture, animation-system) can execute against.

This skill produces:

• Site map with all pages and routes
• Section-by-section breakdown for each page
• Actual written content (headlines, body copy, CTAs)
• Media and icon requirements per section
• Mock data specifications for dynamic content
• Animation intent notes for the animation-system skill

This skill does NOT produce:

• Visual design decisions (colors, fonts, spacing) — see styleguide
• Component implementation details — see css-architecture
• Motion/animation specifics — see animation-system
• Image/media assets — see media-plugin

When NOT to Use

• User wants visual design polish → use frontend-aesthetics
• User wants a color palette or font pairing → use styleguide
• User wants CSS/component structure → use css-architecture
• User wants to generate actual images → use media-plugin/image-generation

Page Architecture Workflow

Step 1: Extract Brief Information

Pull key details from the user's brief or conversation:

• Business type — SaaS, e-commerce, portfolio, agency, restaurant, etc.
• Primary goal — Sign-ups, purchases, lead generation, information, brand awareness
• Target audience — Demographics, technical sophistication, pain points
• Key features/products — What needs to be showcased
• Tone of voice — Professional, playful, technical, luxurious, approachable
• Competitive context — What similar sites exist, how to differentiate
• Content assets available — Photos, testimonials, case studies, team bios, pricing info

Step 2: Determine Page Count and Types

Match the business type to a page template from references/page-templates.md. Adjust based on:

• Scope — MVP launch page (1-3 pages) vs. full marketing site (5-10 pages) vs. web application (many views)
• Conversion funnel — Every page should have a clear role in moving users toward the primary goal
• Content readiness — Do not plan pages the client cannot populate with real content

Step 3: Define Sections Per Page

For each page, select sections from references/section-catalog.md. Order sections following conversion funnel logic:

1. Hook — Capture attention (hero, headline)
2. Build trust — Establish credibility (social proof, logos, stats)
3. Demonstrate value — Show what you offer (features, demos, examples)
4. Prove it works — Evidence (testimonials, case studies, results)
5. Remove friction — Address objections (FAQ, guarantees, comparisons)
6. Convert — Clear call to action (CTA, pricing, sign-up)

Step 4: Write Content for Each Section

Using patterns from references/content-patterns.md, write actual content — not placeholder text. Every section needs:

• Headline — Benefit-driven, specific, 5-10 words
• Supporting copy — Expands on the headline, 15-25 words for subheadlines, scannable paragraphs for body text
• CTA text — Action-oriented with clear value proposition
• Data/lists — Feature names, pricing tiers, team bios, etc.

Step 5: Define Mock Data Requirements

For any dynamic or repeating content, specify mock data using patterns from references/mock-data.md:

• What data shape is needed (user profiles, product cards, blog posts, etc.)
• How many items to generate
• What edge cases to include
• Whether data should be static in JSX or imported from a data file

Step 6: Output the Page Specification

Produce a structured document using the template below.

Page Specification Template

# Page Architecture: [Project Name]

## Overview
- **Business type:** [type]
- **Primary goal:** [goal]
- **Target audience:** [audience]
- **Tone of voice:** [tone]
- **Page count:** [number]

## Site Map
- Home (/)
- About (/about)
- Features (/features)
- Pricing (/pricing)
- Contact (/contact)

---

## Page: Home

**Purpose:** [What this page accomplishes in the conversion funnel]
**Primary CTA:** [The single most important action on this page]

### Section 1: Hero
- **Purpose:** First impression, primary value proposition
- **Layout type:** Full-width hero with CTA
- **Content:**
  - Headline: "[actual headline text]"
  - Subheadline: "[actual subheadline]"
  - CTA primary: "[button text]" → [destination]
  - CTA secondary: "[button text]" → [destination]
- **Media needs:**
  - Hero background: [description for media-prompt-craft]
  - Logo: [shared asset]
- **Icons needed:** [list with specific icon names]
- **Mock data:** none
- **Animation intent:** [brief description for animation-system]

### Section 2: Features Grid
- **Purpose:** Showcase key features/benefits
- **Layout type:** 3-column card grid
- **Content:**
  - Section headline: "[text]"
  - Section subheadline: "[text]"
  - Card 1: { icon: "[name]", title: "[text]", description: "[text]" }
  - Card 2: { icon: "[name]", title: "[text]", description: "[text]" }
  - Card 3: { icon: "[name]", title: "[text]", description: "[text]" }
- **Media needs:** [per-card icons or illustrations]
- **Mock data:** none
- **Animation intent:** stagger reveal on scroll

### Section 3: Social Proof
- **Purpose:** Build trust with recognizable logos
- **Layout type:** Logo bar, auto-scrolling
- **Content:**
  - Section label: "Trusted by leading teams"
  - Logos: [list of 6-8 company names]
- **Media needs:** SVG logos for each company
- **Mock data:** none
- **Animation intent:** infinite horizontal scroll

### Section 4: Testimonials
- **Purpose:** Prove value through customer voices
- **Layout type:** 3-card grid with photo, quote, attribution
- **Content:**
  - Testimonial 1: { quote: "[text]", name: "[name]", title: "[title]", company: "[company]" }
  - Testimonial 2: ...
  - Testimonial 3: ...
- **Media needs:** headshot photos for each testimonial
- **Mock data:** Use faker for additional testimonials if carousel
- **Animation intent:** fade-in on scroll

### Section 5: CTA Banner
- **Purpose:** Final conversion push
- **Layout type:** Full-width banner with centered content
- **Content:**
  - Headline: "[text]"
  - Subheadline: "[text]"
  - CTA: "[button text]" → [destination]
- **Media needs:** none (gradient background)
- **Mock data:** none
- **Animation intent:** subtle background animation

### Section 6: Footer
- **Purpose:** Navigation, legal, secondary links
- **Layout type:** Multi-column footer
- **Content:**
  - Column 1 "Product": [link list]
  - Column 2 "Company": [link list]
  - Column 3 "Resources": [link list]
  - Column 4 "Legal": [link list]
  - Social links: [list]
  - Copyright: "[text]"
- **Media needs:** social media icons
- **Mock data:** none
- **Animation intent:** none

Content Writing Guidelines

Headlines That Work

Do: Write benefit-driven, specific headlines.

"Ship features 10x faster with AI-powered code review"
"Your customers deserve answers in seconds, not hours"
"The design tool that thinks like your team does"

Don't: Write vague, generic headlines.

"Welcome to Our Platform"          — says nothing
"The Best Solution for You"        — could be anything
"Innovation Meets Excellence"      — corporate buzzword soup

Subheadlines That Support

The subheadline expands on the headline with specifics. It should be 15-25 words and answer the "how" or "what" that the headline promises.

Headline: "Ship features 10x faster with AI-powered code review"
Subheadline: "Automated pull request analysis catches bugs, suggests improvements, and
approves clean code — so your team spends less time reviewing and more time building."

Body Copy That Scans

• Short paragraphs (2-3 sentences max)
• Bullet points for lists of features or benefits
• Bold key phrases for skimmers
• One idea per paragraph

CTAs That Convert

High commitment (primary):

• "Start Free Trial" — clear, low risk
• "Book a Demo" — human touch
• "Get Started for Free" — emphasizes no cost

Low commitment (secondary):

• "See How It Works" — curiosity-driven
• "View Examples" — proof-driven
• "Learn More" — minimal commitment

Avoid:

• "Submit" — robotic
• "Click Here" — meaningless
• "Sign Up" — too generic, does not communicate value

Writing Real Content, Not Filler

Every piece of text in the page specification should be project-specific. If you find yourself writing "Lorem ipsum" or "[placeholder text]", stop and write actual content based on the brief. Even for mock data scenarios, use realistic, contextually appropriate text.

Cross-References

• Section catalog with variants — references/section-catalog.md
• Page templates by business type — references/page-templates.md
• Content writing patterns and formulas — references/content-patterns.md
• Mock data generation patterns — references/mock-data.md
• Visual design and aesthetics — ../frontend-aesthetics/ (design-plugin)
• Style definitions — ../styleguide/ (design-plugin)
• Animation specifications — ../animation-system/SKILL.md
• CSS and component structure — ../css-architecture/SKILL.md
• Image generation prompts — media-plugin skills