git:20260329.57c628c to git:20260329.7d1210e

---

name: page-architecture

description: >

Information architecture and content planning for websites — page structure, section definitions,

content hierarchy, text content, and mock data strategy. Use when planning what pages a website

---

# 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

```markdown

# 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