page-specification-workflow.md 5.7 KB
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