sar/.claude/skills/wds-4-ux-design/data/modular-architecture/02-workflows/page-specification-workflow.md

Page Specification Workflow

Step-by-step iterative decomposition from sketch to specs

---

Overview

The agent guides you through specifying a page from top to bottom, one section at a time. You control the level of detail at each step.

---

The Workflow

Step 1: Identify All Sections

Agent analyzes sketch and outputs:

📋 Page Sections Detected:

1. Navigation Header
2. Hero Section
3. Calendar Component
4. Leaderboard Component
5. Footer

Does this match your sketch? Any sections missing or incorrectly identified?

You respond:

• Confirm sections
• Add missing sections
• Rename sections
• Reorder sections

---

Step 2: Section Purpose

For each section, agent asks:

📍 Section: Navigation Header

What is the purpose of this section?
- User navigation?
- Branding?
- User account access?
- Search functionality?

You respond:

"User navigation and branding. Shows logo, main menu, and user profile."

Agent captures:

## Navigation Header

**Purpose:** User navigation and branding
**Contains:** Logo, main menu, user profile

---

Step 3: List Objects in Section

Agent outputs:

🔍 Objects in Navigation Header:

1. Logo (image)
2. Main Menu (navigation)
3. User Profile (dropdown)

Shall I specify each object, or is this section simple enough to keep schematic?

You choose:

• Option A: "Specify each object" → Go deeper
• Option B: "Keep schematic" → Move to next section

---

Step 4: Decompose Containers

If object is a container, agent asks:

📦 Main Menu (Container)

What components does this contain?
1. Home link
2. Calendar link
3. Leaderboard link
4. Settings link

Are these simple links, or do any need detailed specs?

You respond:

"Simple links, no detail needed"

Agent captures:

### Main Menu

- Home link
- Calendar link
- Leaderboard link
- Settings link

---

Step 5: Specify Atomic Components

When reaching smallest parts:

🔬 User Profile (Dropdown)

This looks complex (multiple states, interactions).

Should I:
A) Create detailed Component + Feature files (3-tier)
B) Keep simple specification in Page file
C) Skip for now, mark as TODO

You choose based on complexity:

• Simple: Keep in Page file
• Complex: Decompose to 3 files
• Later: Mark TODO

---

Example: TaskFlow Calendar Page

Full Workflow

Step 1: Sections

Agent: "I see 5 sections: Header, Week Overview, Leaderboard, Calendar, Footer"
You: "Correct!"

Step 2: Section Purposes

Agent: "What's the purpose of Week Overview?"
You: "Shows current week number and 7-day status circles"

Step 3: Week Overview Objects

Agent: "Objects detected:
1. Week number label (text)
2. 7 day circles (repeated component)

Specify each or keep schematic?"
You: "Specify the day circles, they have states"

Step 4: Day Circle Component

Agent: "Day circles look complex (3 states: empty, booked, completed).
Should I create Component + Feature files?"
You: "Yes, decompose it"

Step 5: Calendar Section

Agent: "Calendar has 6 walk states, countdown timers, business rules.
This is highly complex. Should I:
- Create 3-tier decomposition
- Reference your storyboard (App-Main-Booking-States.jpg)"
You: "Yes, decompose and reference storyboard"

---

Designer Control Points

At each step, you decide:

Detail Level

• Schematic: Just list components, no details
• Moderate: Basic specs (size, position, content)
• Detailed: Full 3-tier decomposition

When to Stop

• Good enough: "This is clear, move on"
• Need detail: "Let's specify this fully"
• Later: "Mark as TODO, we'll come back"

Feedback Loop

Agent: "Here's what I captured for Navigation Header..."
You: "Actually, the logo should be clickable and link to home"
Agent: "Updated! Logo is now a link component."

---

Output Structure

Schematic Page Spec

Pages/02-calendar-page.md

## Navigation Header

**Purpose:** User navigation and branding

- Logo (clickable, links to home)
- Main menu (4 links)
- User profile dropdown

## Calendar Section

**Purpose:** Book and manage dog walks
**Component:** → walk-slot-card.component.md
**Feature:** → walk-booking-logic.feature.md
**Storyboard:** → Features/Storyboards/walk-states.jpg

Detailed Page Spec

Pages/02-calendar-page.md

## Navigation Header

**Purpose:** User navigation and branding
**Position:** Top, full-width, fixed
**Height:** 64px

### Logo

**Component:** → logo.component.md
**Position:** Left, 16px padding
**Size:** 40x40px
**Action:** Click → Navigate to home

### Main Menu

**Component:** → nav-menu.component.md
**Position:** Center
**Items:** Home, Calendar, Leaderboard, Settings

### User Profile

**Component:** → user-dropdown.component.md
**Feature:** → user-menu-logic.feature.md
**Position:** Right, 16px padding

---

Benefits

✅ Iterative: Specify what you need, when you need it ✅ Flexible: Control detail level per section ✅ Collaborative: Agent asks, you decide ✅ Efficient: Don't over-specify simple sections ✅ Complete: Nothing gets missed ✅ Aligned: Feedback loop at every step

---

When to Use

Use this workflow when:

• Starting a new page specification
• Converting a sketch to structured specs
• Unsure how detailed to be
• Want guided decomposition

Skip this workflow when:

• Page is extremely simple (1-2 sections)
• You already know the structure
• Rapid prototyping (schematic only)

---

Next Steps

• Complexity Detection - When to decompose components
• Complexity Router Workflow - How to decompose complex components