docs: update all documentation and add AI tooling configs
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,71 @@
|
||||
# Modular Component Architecture
|
||||
|
||||
**Navigation hub for the three-tier specification system**
|
||||
|
||||
---
|
||||
|
||||
## Foundation (00-)
|
||||
|
||||
### [Agent-Designer Collaboration](00-foundation/agent-designer-collaboration.md)
|
||||
|
||||
How AI agents optimize designer craft without replacing designer thinking
|
||||
|
||||
---
|
||||
|
||||
## Core Concepts (01-)
|
||||
|
||||
### [Three-Tier Architecture](01-core-concepts/three-tier-overview.md)
|
||||
|
||||
Overview of Pages, Components, and Features separation
|
||||
|
||||
### [Content Placement Rules](01-core-concepts/content-placement-rules.md)
|
||||
|
||||
Decision tree for where to document content
|
||||
|
||||
### [Complexity Detection](01-core-concepts/complexity-detection.md)
|
||||
|
||||
How to identify simple vs complex components
|
||||
|
||||
---
|
||||
|
||||
## Workflows (02-)
|
||||
|
||||
### [Page Specification Workflow](02-workflows/page-specification-workflow.md)
|
||||
|
||||
Step-by-step page decomposition from sketch to specs
|
||||
|
||||
### [Complexity Router Workflow](02-workflows/complexity-router-workflow.md)
|
||||
|
||||
Guided decomposition for complex components
|
||||
|
||||
### [Storyboard Integration](02-workflows/storyboards/storyboards-guide.md)
|
||||
|
||||
Using visual storyboards for complex components
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### [Simple Component Example](examples/simple-button.md)
|
||||
|
||||
Button - single file documentation
|
||||
|
||||
### [Complex Component Example](examples/complex-calendar.md)
|
||||
|
||||
Calendar - three-tier decomposition
|
||||
|
||||
### [Search Bar Example](examples/search-bar.md)
|
||||
|
||||
Search with page-specific content
|
||||
|
||||
---
|
||||
|
||||
## Quick References (03-)
|
||||
|
||||
### [Decision Tree](03-quick-refs/decision-tree.md)
|
||||
|
||||
One-page flowchart for file placement
|
||||
|
||||
### [Benefits Summary](03-quick-refs/benefits.md)
|
||||
|
||||
Why this architecture works
|
||||
@@ -0,0 +1,488 @@
|
||||
# Agent-Designer Collaboration in UX Design
|
||||
|
||||
**How AI agents optimize designer craft without replacing designer thinking**
|
||||
|
||||
---
|
||||
|
||||
## The Partnership Model
|
||||
|
||||
**Designer:** Strategic thinking, multi-dimensional decisions, creative problem-solving
|
||||
**Agent:** Systematic execution, pattern recognition, documentation assistance
|
||||
|
||||
**Not replacement. Amplification.**
|
||||
|
||||
---
|
||||
|
||||
## What Agents CANNOT Do
|
||||
|
||||
❌ **Understand business context**
|
||||
|
||||
- Why does this business exist?
|
||||
- What are the real goals?
|
||||
- What defines success?
|
||||
|
||||
❌ **Know user needs deeply**
|
||||
|
||||
- Who are the actual users?
|
||||
- What are their mental models?
|
||||
- What contexts do they operate in?
|
||||
|
||||
❌ **Make strategic decisions**
|
||||
|
||||
- Should we build this feature?
|
||||
- Does this serve the user or just the business?
|
||||
- What's the coherent storyline?
|
||||
|
||||
❌ **Balance competing priorities**
|
||||
|
||||
- Business goals vs user needs
|
||||
- Simplicity vs functionality
|
||||
- Technical viability vs ideal experience
|
||||
|
||||
**These require human judgment, empathy, and multi-dimensional thinking.**
|
||||
|
||||
---
|
||||
|
||||
## What Agents DO Brilliantly
|
||||
|
||||
✅ **Systematic decomposition**
|
||||
|
||||
```
|
||||
Designer: "This calendar is complex"
|
||||
Agent: "I detect 6 states, time-based transitions, business rules.
|
||||
Let me guide you through decomposition:
|
||||
- Page context
|
||||
- Visual design
|
||||
- Functional logic"
|
||||
```
|
||||
|
||||
✅ **Pattern recognition**
|
||||
|
||||
```
|
||||
Designer: "I'm adding body text here"
|
||||
Agent: "I notice on Start Page, body text was 16px with 1.5 line-height.
|
||||
Should I use the same for consistency?"
|
||||
```
|
||||
|
||||
✅ **Documentation assistance**
|
||||
|
||||
```
|
||||
Designer: "The walk slot has different colors"
|
||||
Agent: "Let me capture that systematically:
|
||||
- WHITE: Empty slot
|
||||
- GRAY: Booked
|
||||
- ORANGE: Countdown active
|
||||
- BLUE: Walk in progress
|
||||
- GREEN: Completed
|
||||
- RED: Missed"
|
||||
```
|
||||
|
||||
✅ **Workflow guidance**
|
||||
|
||||
```
|
||||
Designer: "Where should I document this content?"
|
||||
Agent: "Does the content vary by page context?
|
||||
YES → Page file
|
||||
NO → Feature file"
|
||||
```
|
||||
|
||||
✅ **Cross-reference tracking**
|
||||
|
||||
```
|
||||
Designer: "I updated the button color"
|
||||
Agent: "This button appears on 5 pages. Should I update all references?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Collaboration Flow
|
||||
|
||||
### Phase 1: Designer Thinks
|
||||
|
||||
**Designer decides:**
|
||||
|
||||
- Business goals for this page
|
||||
- User needs to serve
|
||||
- Product strategy to implement
|
||||
- Experience coherence to maintain
|
||||
- Technical approach to take
|
||||
|
||||
**Agent observes, learns context.**
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Agent Guides Decomposition
|
||||
|
||||
**Agent asks systematic questions:**
|
||||
|
||||
```
|
||||
"I see this sketch. Let me identify sections:
|
||||
1. Navigation Header
|
||||
2. Hero Section
|
||||
3. Calendar Component
|
||||
4. Leaderboard
|
||||
5. Footer
|
||||
|
||||
Does this match your vision?"
|
||||
```
|
||||
|
||||
**Designer confirms, corrects, adds context:**
|
||||
|
||||
```
|
||||
"Yes, but the Calendar is the core feature.
|
||||
It needs detailed specification."
|
||||
```
|
||||
|
||||
**Agent adapts:**
|
||||
|
||||
```
|
||||
"Got it. Calendar is core. I'll guide you through detailed decomposition.
|
||||
The other sections we can keep schematic unless you need detail."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Designer Provides Creative Input
|
||||
|
||||
**Designer sketches, explains, decides:**
|
||||
|
||||
```
|
||||
"The walk slots have 6 states. I have a storyboard showing the flow.
|
||||
The colors represent different stages of the walk lifecycle.
|
||||
This needs to feel playful, not punishing."
|
||||
```
|
||||
|
||||
**Agent captures systematically:**
|
||||
|
||||
```
|
||||
"Capturing:
|
||||
- 6 visual states (storyboard reference)
|
||||
- Color-coded lifecycle
|
||||
- Tone: Playful, not punishing
|
||||
|
||||
Should I create:
|
||||
- Component file (visual design)
|
||||
- Feature file (state machine logic)
|
||||
- Storyboard reference?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Agent Ensures Consistency
|
||||
|
||||
**Agent checks patterns:**
|
||||
|
||||
```
|
||||
"I notice you're using orange for 'countdown active' state.
|
||||
On the Week Overview, orange circles also mean 'active day'.
|
||||
This is consistent. Should I document this as a design system pattern?"
|
||||
```
|
||||
|
||||
**Designer confirms or corrects:**
|
||||
|
||||
```
|
||||
"Yes! Orange = active/urgent across the app.
|
||||
Add that to the design system."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Designer Makes Final Decisions
|
||||
|
||||
**Agent presents options:**
|
||||
|
||||
```
|
||||
"For the User Profile dropdown, I can:
|
||||
A) Keep simple specification in Page file
|
||||
B) Create detailed Component + Feature files
|
||||
C) Mark as TODO for later
|
||||
|
||||
This component has 3 states and logout logic.
|
||||
What level of detail do you need?"
|
||||
```
|
||||
|
||||
**Designer decides based on priorities:**
|
||||
|
||||
```
|
||||
"Option B. User profile is important for trust.
|
||||
Let's specify it properly."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Crucial Agent Behaviors
|
||||
|
||||
### 1. Ask, Don't Assume
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```
|
||||
Agent: "I'll create a daily calendar view."
|
||||
```
|
||||
|
||||
**Right:**
|
||||
|
||||
```
|
||||
Agent: "I see a calendar. Should this be:
|
||||
- Daily view
|
||||
- Weekly view
|
||||
- Monthly view
|
||||
|
||||
What matches your users' mental model?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Provide Context, Not Just Questions
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```
|
||||
Agent: "What color should this be?"
|
||||
```
|
||||
|
||||
**Right:**
|
||||
|
||||
```
|
||||
Agent: "I notice the walk slot needs a color for 'countdown active' state.
|
||||
You've used:
|
||||
- Blue for 'in progress'
|
||||
- Green for 'completed'
|
||||
- Red for 'missed'
|
||||
|
||||
What color represents 'urgent but not started'?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Explain WHY Questions Matter
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```
|
||||
Agent: "Does content vary by page?"
|
||||
```
|
||||
|
||||
**Right:**
|
||||
|
||||
```
|
||||
Agent: "Does the hero heading change per page?
|
||||
|
||||
This matters because:
|
||||
- If YES → Document in Page file (page-specific)
|
||||
- If NO → Document in Feature file (reusable)
|
||||
|
||||
This keeps your specs maintainable."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Learn Designer Preferences
|
||||
|
||||
**After a few interactions:**
|
||||
|
||||
```
|
||||
Agent: "I notice you prefer detailed specifications for user-facing components
|
||||
but schematic specs for admin sections.
|
||||
|
||||
Should I apply this pattern to the Settings page?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Catch Inconsistencies Gently
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```
|
||||
Agent: "ERROR: This contradicts the Start Page!"
|
||||
```
|
||||
|
||||
**Right:**
|
||||
|
||||
```
|
||||
Agent: "I notice on Start Page, buttons are 48px height.
|
||||
Here you specified 44px.
|
||||
|
||||
Is this intentional (different context) or should I match for consistency?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. Ask "Why" Questions That Reveal Insights
|
||||
|
||||
**Agent notices patterns and asks for reasoning:**
|
||||
|
||||
```
|
||||
Agent: "Help me understand: The header has two buttons -
|
||||
'Book Walk' and 'Add Walk'.
|
||||
|
||||
They seem to do similar things. What's the difference?"
|
||||
```
|
||||
|
||||
**Designer's answer reveals business logic:**
|
||||
|
||||
```
|
||||
Designer: "Oh! Good catch.
|
||||
'Book Walk' = Reserve a future slot
|
||||
'Add Walk' = Log a walk that already happened
|
||||
|
||||
We need both because kids forget to book but parents
|
||||
want to track completed walks for the leaderboard."
|
||||
```
|
||||
|
||||
**Agent captures the insight:**
|
||||
|
||||
```
|
||||
Agent: "Got it! Two distinct use cases:
|
||||
- Book Walk → Future planning (proactive)
|
||||
- Add Walk → Retroactive logging (accountability)
|
||||
|
||||
Should I document this distinction in the Feature file
|
||||
so developers understand the different workflows?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**When designer says "I don't know":**
|
||||
|
||||
```
|
||||
Agent: "Why does the calendar show week numbers instead of dates?"
|
||||
|
||||
Designer: "Hmm, I'm not sure. It just felt right."
|
||||
|
||||
Agent: "Let me help you think through this. Pros and cons:
|
||||
|
||||
Week Numbers:
|
||||
✅ Matches Swedish 'Vecka 40' culture
|
||||
✅ Simpler visual (less clutter)
|
||||
✅ Focuses on rhythm, not specific dates
|
||||
❌ Users might need to check what week it is
|
||||
❌ Less familiar to non-Swedish users
|
||||
|
||||
Specific Dates:
|
||||
✅ Immediately clear what day it is
|
||||
✅ Universal understanding
|
||||
❌ More visual clutter
|
||||
❌ Doesn't match Swedish planning culture
|
||||
|
||||
Given your target users are Swedish families,
|
||||
which approach serves them better?"
|
||||
```
|
||||
|
||||
**Designer thinks through it:**
|
||||
|
||||
```
|
||||
Designer: "You're right - Swedish families think in weeks.
|
||||
'Vecka 40' is how they plan. Let's keep week numbers
|
||||
but add a small date range for clarity: 'Vecka 40 (2-8 Oct)'"
|
||||
```
|
||||
|
||||
**Agent captures the decision:**
|
||||
|
||||
```
|
||||
Agent: "Perfect! Documenting:
|
||||
- Primary: Week number (Swedish mental model)
|
||||
- Secondary: Date range (clarity)
|
||||
- Rationale: Matches target user planning culture
|
||||
|
||||
This also goes in your design system as a pattern."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What This Enables
|
||||
|
||||
### Designer Benefits
|
||||
|
||||
✅ **Focus on thinking, not documentation**
|
||||
|
||||
- Agent handles systematic capture
|
||||
- Designer focuses on creative decisions
|
||||
|
||||
✅ **Maintain consistency effortlessly**
|
||||
|
||||
- Agent tracks patterns across pages
|
||||
- Designer confirms or corrects
|
||||
|
||||
✅ **Iterate faster**
|
||||
|
||||
- Agent guides structured decomposition
|
||||
- Designer doesn't get overwhelmed
|
||||
|
||||
✅ **Nothing gets missed**
|
||||
|
||||
- Agent asks systematic questions
|
||||
- Designer provides context
|
||||
|
||||
✅ **Design system integrity**
|
||||
|
||||
- Agent catches inconsistencies
|
||||
- Designer maintains coherence
|
||||
|
||||
---
|
||||
|
||||
### Project Benefits
|
||||
|
||||
✅ **Complete specifications**
|
||||
|
||||
- Nothing forgotten or assumed
|
||||
- Clear handoffs to developers
|
||||
|
||||
✅ **Maintainable documentation**
|
||||
|
||||
- Structured, not monolithic
|
||||
- Easy to update
|
||||
|
||||
✅ **Faster development**
|
||||
|
||||
- Developers have clear instructions
|
||||
- AI code generators have precise prompts
|
||||
|
||||
✅ **Better products**
|
||||
|
||||
- Designer thinking + Agent systematization
|
||||
- Strategic decisions + consistent execution
|
||||
|
||||
---
|
||||
|
||||
## The Bottom Line
|
||||
|
||||
**Agents don't replace designers.**
|
||||
|
||||
**Agents optimize designer craft by:**
|
||||
|
||||
- Handling systematic work
|
||||
- Ensuring consistency
|
||||
- Guiding structured workflows
|
||||
- Catching oversights
|
||||
- Documenting decisions
|
||||
|
||||
**This frees designers to:**
|
||||
|
||||
- Think strategically
|
||||
- Make creative decisions
|
||||
- Solve complex problems
|
||||
- Maintain coherent experiences
|
||||
- Balance competing priorities
|
||||
|
||||
**The result:**
|
||||
|
||||
- 10x faster specification
|
||||
- 10x better consistency
|
||||
- 10x more complete documentation
|
||||
- 100% designer-driven decisions
|
||||
|
||||
**Designer thinking. Agent execution. Product success.**
|
||||
|
||||
---
|
||||
|
||||
## Related Concepts
|
||||
|
||||
### Conceptual Specifications
|
||||
|
||||
How capturing WHY (not just WHAT) makes AI implementation correct
|
||||
|
||||
---
|
||||
|
||||
[← Back to Guide](00-MODULAR-ARCHITECTURE-GUIDE.md)
|
||||
@@ -0,0 +1,123 @@
|
||||
# Complexity Detection
|
||||
|
||||
**How to identify simple vs complex components**
|
||||
|
||||
---
|
||||
|
||||
## Simple Component Indicators
|
||||
|
||||
- ✅ Single state (no variations)
|
||||
- ✅ No user interaction (static display)
|
||||
- ✅ No data dependencies
|
||||
- ✅ No business logic
|
||||
|
||||
**Examples:**
|
||||
|
||||
- Static text
|
||||
- Image
|
||||
- Basic button (just click → navigate)
|
||||
|
||||
**Action:** Document in Page file only
|
||||
|
||||
---
|
||||
|
||||
## Complex Component Indicators
|
||||
|
||||
- ⚠️ Multiple states (3+ states)
|
||||
- ⚠️ Time-based changes (countdowns, timers)
|
||||
- ⚠️ Multi-step interactions (workflows)
|
||||
- ⚠️ Business rules (validation, permissions)
|
||||
- ⚠️ Data synchronization (updates other components)
|
||||
- ⚠️ State machines (defined transition paths)
|
||||
|
||||
**Examples:**
|
||||
|
||||
- Calendar widget (6 states)
|
||||
- Search with autocomplete (5+ states)
|
||||
- Multi-step form (progress tracking)
|
||||
- Booking system (state machine)
|
||||
|
||||
**Action:** Decompose into 3 files (Page, Component, Feature)
|
||||
|
||||
---
|
||||
|
||||
## Detection Examples
|
||||
|
||||
### Example 1: Simple Button
|
||||
|
||||
**Indicators:**
|
||||
|
||||
- ✅ Single interaction (click → navigate)
|
||||
- ✅ 2-3 states (default, hover, active)
|
||||
- ❌ No business logic
|
||||
- ❌ No data dependencies
|
||||
|
||||
**Result:** SIMPLE - Page file only
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Search Bar
|
||||
|
||||
**Indicators:**
|
||||
|
||||
- ⚠️ Multiple states (empty, typing, loading, results, error)
|
||||
- ⚠️ Real-time updates (debounced API calls)
|
||||
- ⚠️ Business logic (min 3 characters, max 10 results)
|
||||
- ⚠️ Data dependencies (search API)
|
||||
- ⚠️ Keyboard navigation
|
||||
|
||||
**Result:** COMPLEX - Decompose into 3 files
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Calendar Widget
|
||||
|
||||
**Indicators:**
|
||||
|
||||
- ⚠️ 6 walk states
|
||||
- ⚠️ Time-based transitions (countdown timers)
|
||||
- ⚠️ Complex business rules (per-dog blocking)
|
||||
- ⚠️ Multi-component sync (week view, leaderboard)
|
||||
- ⚠️ Real-time updates (every 1 minute)
|
||||
- ⚠️ API dependencies (4+ endpoints)
|
||||
|
||||
**Result:** HIGHLY COMPLEX - Decompose + storyboard
|
||||
|
||||
---
|
||||
|
||||
## When to Decompose
|
||||
|
||||
**Decompose when component has:**
|
||||
|
||||
- 3+ visual states
|
||||
- Business rules
|
||||
- API dependencies
|
||||
- State machine logic
|
||||
- Multi-component interactions
|
||||
|
||||
**Keep simple when component has:**
|
||||
|
||||
- 1-2 states
|
||||
- No logic
|
||||
- No data
|
||||
- Static display
|
||||
|
||||
**⚠️ Common Mistake:**
|
||||
|
||||
```markdown
|
||||
❌ Wrong: Everything in one file
|
||||
Pages/02-calendar-page.md (800 lines)
|
||||
├─ Layout + Visual design + Business logic + API endpoints
|
||||
|
||||
✅ Right: Decompose into 3 files
|
||||
Pages/02-calendar-page.md (100 lines) → Layout + page content
|
||||
Components/walk-slot-card.component.md (150 lines) → Visual design
|
||||
Features/walk-booking-logic.feature.md (200 lines) → Logic
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Complexity Router Workflow](02-complexity-router-workflow.md) - How to decompose
|
||||
- [Examples](examples/) - See real decompositions
|
||||
@@ -0,0 +1,144 @@
|
||||
# Content Placement Rules
|
||||
|
||||
**Decision tree for where to document content**
|
||||
|
||||
---
|
||||
|
||||
## The Core Question
|
||||
|
||||
```
|
||||
Does CONTENT vary by page context?
|
||||
│
|
||||
├─ YES → Page File
|
||||
│ (Hero heading, user-specific data)
|
||||
│
|
||||
└─ NO → Feature File
|
||||
(Generic button text, error messages)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Page File Content
|
||||
|
||||
**Document in Page file when:**
|
||||
|
||||
- ✅ Content changes per page
|
||||
- ✅ Data varies by user/context
|
||||
- ✅ Configuration differs by placement
|
||||
|
||||
**Examples:**
|
||||
|
||||
- Hero heading: "Welcome" (Home) vs "About Us" (About)
|
||||
- Search placeholder: "Search products..." vs "Search help..."
|
||||
- Calendar header: "Familjen Svensson: Vecka 40" (user's family)
|
||||
- API endpoint: `/api/families/:currentFamilyId/walks` (user-specific)
|
||||
|
||||
**⚠️ Common Mistake:**
|
||||
|
||||
```markdown
|
||||
❌ Wrong: Features/hero-logic.feature.md
|
||||
**Content:**
|
||||
|
||||
- Heading: "Welcome to TaskFlow" (Home page)
|
||||
- Heading: "About TaskFlow" (About page)
|
||||
|
||||
✅ Right: Put in respective Page files
|
||||
Pages/01-home-page.md → "Welcome to TaskFlow"
|
||||
Pages/02-about-page.md → "About TaskFlow"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feature File Content
|
||||
|
||||
**Document in Feature file when:**
|
||||
|
||||
- ✅ Content is the same everywhere
|
||||
- ✅ Generic validation messages
|
||||
- ✅ Standard UI text
|
||||
|
||||
**Examples:**
|
||||
|
||||
- Button text: "Submit" (always the same)
|
||||
- Error message: "Invalid email" (generic validation)
|
||||
- Loading text: "Loading..." (standard)
|
||||
- Tooltip: "Click to expand" (generic interaction)
|
||||
|
||||
**⚠️ Common Mistake:**
|
||||
|
||||
```markdown
|
||||
❌ Wrong: Pages/01-home-page.md
|
||||
**Content:**
|
||||
|
||||
- Submit button: "Submit"
|
||||
- Error message: "Invalid email"
|
||||
|
||||
✅ Right: Features/form-submit-logic.feature.md
|
||||
**Generic Content:**
|
||||
|
||||
- Submit button: "Submit"
|
||||
- Error message: "Invalid email"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component File Content
|
||||
|
||||
**Component files contain NO content:**
|
||||
|
||||
- ❌ No text
|
||||
- ❌ No images
|
||||
- ❌ No data
|
||||
- ✅ Only visual design (colors, spacing, states)
|
||||
|
||||
**Exception:** Content slots
|
||||
|
||||
```markdown
|
||||
**Content Slots:**
|
||||
|
||||
- Heading text (configurable per page)
|
||||
- Background image (configurable per page)
|
||||
```
|
||||
|
||||
**⚠️ Common Mistakes:**
|
||||
|
||||
```markdown
|
||||
❌ Wrong: Features/button-logic.feature.md
|
||||
**Visual:** Background: Blue, Height: 48px
|
||||
|
||||
✅ Right: Components/button-primary.component.md
|
||||
**Visual Specifications:** Background: Blue (#3B82F6), Height: 48px
|
||||
|
||||
---
|
||||
|
||||
❌ Wrong: Components/walk-slot-card.component.md
|
||||
**Logic:** Can't start walk if another is active
|
||||
|
||||
✅ Right: Features/walk-booking-logic.feature.md
|
||||
**Business Rules:** One active walk per dog
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
| Content Type | Page-Specific? | Where? |
|
||||
| --------------------- | -------------- | --------- |
|
||||
| Hero heading | ✅ YES | Page |
|
||||
| Hero background | ✅ YES | Page |
|
||||
| Search placeholder | ✅ YES | Page |
|
||||
| User's family name | ✅ YES | Page |
|
||||
| API with user context | ✅ YES | Page |
|
||||
| Submit button text | ❌ NO | Feature |
|
||||
| Error messages | ❌ NO | Feature |
|
||||
| Loading text | ❌ NO | Feature |
|
||||
| Tooltip text | ❌ NO | Feature |
|
||||
| Button color | ❌ Visual | Component |
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
- [Simple Button](examples/simple-button.md)
|
||||
- [Search Bar](examples/search-bar.md)
|
||||
- [Calendar Widget](examples/complex-calendar.md)
|
||||
@@ -0,0 +1,144 @@
|
||||
# Three-Tier Architecture Overview
|
||||
|
||||
**Separation of WHERE, HOW, and WHAT**
|
||||
|
||||
---
|
||||
|
||||
## The Three File Types
|
||||
|
||||
### 1. Pages/ (WHERE)
|
||||
|
||||
**Purpose:** Page-specific context and placement
|
||||
|
||||
**Contains:**
|
||||
|
||||
- Position & size
|
||||
- Page-specific content (varies by page)
|
||||
- Page-specific data (user context)
|
||||
- Component references
|
||||
- Feature references
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
Pages/02-calendar-page.md
|
||||
|
||||
- Position: Main content, full-width
|
||||
- Content: "Familjen Svensson: Vecka 40" (user's family)
|
||||
- Data: GET /api/families/:currentFamilyId/walks
|
||||
- Component: → walk-slot-card.component.md
|
||||
- Feature: → walk-booking-logic.feature.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Components/ (HOW IT LOOKS)
|
||||
|
||||
**Purpose:** Visual design specifications
|
||||
|
||||
**Contains:**
|
||||
|
||||
- Visual specs (colors, spacing, typography)
|
||||
- States (default, hover, active, loading, error)
|
||||
- Variants (sizes, types, themes)
|
||||
- Figma mapping
|
||||
- Responsive behavior
|
||||
- ❌ NO content, NO logic
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
Components/walk-slot-card.component.md
|
||||
|
||||
- 6 visual states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED)
|
||||
- Typography: 16px Medium, 12px Regular
|
||||
- Colors: Blue (#3B82F6), Orange (#FB923C), etc.
|
||||
- Storyboard reference: Features/Storyboards/walk-states.jpg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Features/ (WHAT IT DOES)
|
||||
|
||||
**Purpose:** Functional logic and business rules
|
||||
|
||||
**Contains:**
|
||||
|
||||
- User interactions
|
||||
- Business rules
|
||||
- State management
|
||||
- Generic content (same everywhere)
|
||||
- API endpoints
|
||||
- Validation rules
|
||||
- ❌ NO visual design
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
Features/walk-booking-logic.feature.md
|
||||
|
||||
- Book walk → GRAY state
|
||||
- Start walk → BLUE state
|
||||
- Business rule: One active walk per dog
|
||||
- API: POST /api/walks, PUT /api/walks/:id/start
|
||||
- Generic content: "Loading...", "Error: Failed to load"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Why Three Tiers?
|
||||
|
||||
### Before (Monolithic)
|
||||
|
||||
```
|
||||
Pages/02-calendar-page.md (800 lines)
|
||||
├─ Everything mixed together
|
||||
├─ Developer confused
|
||||
├─ Designer confused
|
||||
└─ Features get missed
|
||||
```
|
||||
|
||||
### After (Modular)
|
||||
|
||||
```
|
||||
Pages/02-calendar-page.md (100 lines)
|
||||
├─ Just placement + user context
|
||||
|
||||
Components/walk-slot-card.component.md (150 lines)
|
||||
├─ Visual design only
|
||||
└─ → Send to Figma designer
|
||||
|
||||
Features/walk-booking-logic.feature.md (200 lines)
|
||||
├─ Logic only
|
||||
└─ → Send to developer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Handoff Strategy
|
||||
|
||||
**Visual Designer** receives:
|
||||
|
||||
- `Components/` folder
|
||||
- Creates Figma components
|
||||
- Matches visual specs exactly
|
||||
|
||||
**Developer** receives:
|
||||
|
||||
- `Features/` folder
|
||||
- Implements business logic
|
||||
- Uses API endpoints specified
|
||||
|
||||
**You** maintain:
|
||||
|
||||
- `Pages/` folder
|
||||
- Track design system integrity
|
||||
- Manage page-specific content
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Content Placement Rules](01-content-placement-rules.md) - Where does content go?
|
||||
- [Complexity Detection](01-complexity-detection.md) - When to decompose?
|
||||
- [Workflow](02-complexity-router-workflow.md) - How to decompose?
|
||||
@@ -0,0 +1,70 @@
|
||||
# What Are Storyboards?
|
||||
|
||||
**Visual documentation of component functionality**
|
||||
|
||||
---
|
||||
|
||||
## Definition
|
||||
|
||||
A **storyboard** is a visual sequence showing:
|
||||
|
||||
- State transitions (empty → loading → active → completed)
|
||||
- User interactions (click, type, swipe)
|
||||
- System responses (updates, animations, feedback)
|
||||
- Time-based changes (countdowns, timers)
|
||||
|
||||
---
|
||||
|
||||
## Format
|
||||
|
||||
**Hand-drawn sketches** (recommended):
|
||||
|
||||
- Quick to create
|
||||
- Easy to iterate
|
||||
- Focus on functionality, not polish
|
||||
|
||||
**Example:** TaskFlow `task-status-states.jpg`
|
||||
|
||||
- 6 frames showing walk states
|
||||
- Numbered sequentially
|
||||
- Annotated with triggers
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Storyboards answer:
|
||||
|
||||
- "What does this look like in each state?"
|
||||
- "How do users move between states?"
|
||||
- "What triggers each transition?"
|
||||
- "What happens over time?"
|
||||
|
||||
---
|
||||
|
||||
## Why Visual?
|
||||
|
||||
**Text description:**
|
||||
|
||||
```
|
||||
When the user books a walk, the card changes to gray,
|
||||
the leaderboard updates, and the week overview changes.
|
||||
```
|
||||
|
||||
**Storyboard:**
|
||||
|
||||
```
|
||||
Frame 1: WHITE card with "Book" button
|
||||
Frame 2: User taps "Book"
|
||||
Frame 3: GRAY card, leaderboard +1, week circle gray
|
||||
```
|
||||
|
||||
Visual is **faster to understand** and **harder to misinterpret**.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [When to Use Storyboards](01-when-to-use.md)
|
||||
- [Storyboard Types](01-storyboard-types.md)
|
||||
- [Creation Guide](creation-guide.md)
|
||||
@@ -0,0 +1,68 @@
|
||||
# When to Use Storyboards
|
||||
|
||||
**Complexity indicators that require visual documentation**
|
||||
|
||||
---
|
||||
|
||||
## Create Storyboards For:
|
||||
|
||||
✅ **Components with 3+ states**
|
||||
|
||||
- Example (TaskFlow): Task status (TODO, IN_PROGRESS, BLOCKED, DONE, ARCHIVED)
|
||||
|
||||
✅ **Time-based transitions**
|
||||
|
||||
- Example (TaskFlow): Deadline reminders, auto-status updates
|
||||
|
||||
✅ **Multi-step user flows**
|
||||
|
||||
- Example (TaskFlow): Creating → Assigning → Completing a task
|
||||
|
||||
✅ **Complex interactions between components**
|
||||
|
||||
- Example (TaskFlow): Task completion updates dashboard and team notifications
|
||||
|
||||
✅ **State machines with branching paths**
|
||||
|
||||
- Example (TaskFlow): Happy path vs validation error vs timeout
|
||||
|
||||
---
|
||||
|
||||
## Don't Need Storyboards For:
|
||||
|
||||
❌ **Simple buttons**
|
||||
|
||||
- Hover and active states are obvious
|
||||
|
||||
❌ **Static content sections**
|
||||
|
||||
- No state changes to document
|
||||
|
||||
❌ **Single-state components**
|
||||
|
||||
- Nothing to show in sequence
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Need Storyboard:
|
||||
|
||||
- **TaskFlow:** Task status board (5 states, time-based reminders)
|
||||
- **Future Project:** Search with autocomplete (5 states, real-time)
|
||||
- **Future Project:** Multi-step form (progress tracking)
|
||||
- **Future Project:** Payment flow (multiple steps, error handling)
|
||||
|
||||
### Don't Need Storyboard:
|
||||
|
||||
- Submit button (2-3 states)
|
||||
- Hero image (static)
|
||||
- Text paragraph (no states)
|
||||
- Logo (no interaction)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Storyboard Types](01-storyboard-types.md)
|
||||
- [Creation Guide](creation-guide.md)
|
||||
@@ -0,0 +1,86 @@
|
||||
# Storyboard File Structure
|
||||
|
||||
**Where to store storyboards in the three-tier architecture**
|
||||
|
||||
---
|
||||
|
||||
## Storage Location
|
||||
|
||||
```
|
||||
project-root/
|
||||
├─ Pages/
|
||||
│ └─ 02-calendar-page.md
|
||||
│
|
||||
├─ Components/
|
||||
│ └─ walk-slot-card.component.md
|
||||
│
|
||||
├─ Features/
|
||||
│ ├─ walk-booking-logic.feature.md
|
||||
│ └─ Storyboards/ ← Store here
|
||||
│ ├─ walk-state-transitions.jpg
|
||||
│ ├─ booking-flow.jpg
|
||||
│ └─ calendar-sync-flow.jpg
|
||||
│
|
||||
└─ Sketches/ ← Page sketches
|
||||
└─ 02-calendar-page-sketch.jpg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Why Features/Storyboards/?
|
||||
|
||||
Storyboards document **functionality**, not visual design:
|
||||
|
||||
- State transitions (functional)
|
||||
- User interactions (functional)
|
||||
- Business logic flows (functional)
|
||||
|
||||
Therefore, they belong with **Features**, not Components.
|
||||
|
||||
---
|
||||
|
||||
## Reference Pattern
|
||||
|
||||
**From Feature File:**
|
||||
|
||||
```markdown
|
||||
Features/walk-booking-logic.feature.md
|
||||
|
||||
## Visual Storyboard
|
||||
|
||||
|
||||
```
|
||||
|
||||
**From Component File:**
|
||||
|
||||
```markdown
|
||||
Components/walk-slot-card.component.md
|
||||
|
||||
## Visual States
|
||||
|
||||
See storyboard for state transitions:
|
||||
→ Features/Storyboards/walk-state-transitions.jpg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Separation from Page Sketches
|
||||
|
||||
**Page Sketches** (Sketches/ folder):
|
||||
|
||||
- Show page layout
|
||||
- Static view of entire page
|
||||
- Used during initial design
|
||||
|
||||
**Storyboards** (Features/Storyboards/ folder):
|
||||
|
||||
- Show component behavior
|
||||
- Sequential frames showing changes
|
||||
- Used during specification
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Naming Conventions](02-naming-conventions.md)
|
||||
- [Feature File Integration](feature-file-integration.md)
|
||||
@@ -0,0 +1,155 @@
|
||||
# Complexity Router Workflow
|
||||
|
||||
**Step-by-step guided decomposition**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
When a complex component is detected, the agent guides you through 3 steps:
|
||||
|
||||
1. **WHERE** - Page context
|
||||
2. **HOW** - Visual design
|
||||
3. **WHAT** - Functional logic
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Page Context (WHERE)
|
||||
|
||||
**Agent asks:**
|
||||
|
||||
1. Which page(s) does this appear on?
|
||||
2. Where on the page?
|
||||
3. How big is it?
|
||||
4. Same component on multiple pages, or page-specific?
|
||||
5. **Does CONTENT change based on page context?**
|
||||
6. **Does DATA source change based on page context?**
|
||||
|
||||
**You answer, agent captures:**
|
||||
|
||||
- Pages list
|
||||
- Position
|
||||
- Size
|
||||
- Reusability
|
||||
- Content varies: YES/NO
|
||||
- Data source varies: YES/NO
|
||||
|
||||
**Result:** Page file specification
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Visual Design (HOW)
|
||||
|
||||
**Agent asks:**
|
||||
|
||||
1. How many visual states?
|
||||
2. Do you have a storyboard showing states?
|
||||
3. For each state:
|
||||
- What does it look like?
|
||||
- What triggers this state?
|
||||
- Can it transition to other states?
|
||||
|
||||
**You answer, agent captures:**
|
||||
|
||||
- State count
|
||||
- State definitions
|
||||
- Storyboard reference (if exists)
|
||||
- Visual specifications
|
||||
|
||||
**Result:** Component file specification
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Functional Logic (WHAT)
|
||||
|
||||
**Agent asks:**
|
||||
|
||||
1. What can users DO with this?
|
||||
2. What happens when they interact?
|
||||
3. Are there business rules?
|
||||
4. Does it need data from an API?
|
||||
5. Does it update other components?
|
||||
|
||||
**You answer, agent captures:**
|
||||
|
||||
- User actions
|
||||
- System responses
|
||||
- Business rules
|
||||
- API endpoints
|
||||
- Component sync
|
||||
|
||||
**Result:** Feature file specification
|
||||
|
||||
---
|
||||
|
||||
## Example Dialogue
|
||||
|
||||
See: [Coaching Dialogue Example](examples/coaching-dialogue.md)
|
||||
|
||||
---
|
||||
|
||||
## Output: Three Files
|
||||
|
||||
**1. Page File**
|
||||
|
||||
```markdown
|
||||
Pages/02-calendar-page.md
|
||||
|
||||
**Component:** walk-slot-card.component.md
|
||||
**Feature:** walk-booking-logic.feature.md
|
||||
|
||||
**Position:** Main content, full-width
|
||||
**Page-Specific Content:**
|
||||
|
||||
- Header: "Familjen Svensson: Vecka 40"
|
||||
- Data: GET /api/families/:currentFamilyId/walks
|
||||
```
|
||||
|
||||
**2. Component File**
|
||||
|
||||
```markdown
|
||||
Components/walk-slot-card.component.md
|
||||
|
||||
**Visual Specifications:**
|
||||
|
||||
- 6 states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED)
|
||||
- Typography, colors, spacing
|
||||
- Storyboard: Features/Storyboards/walk-states.jpg
|
||||
```
|
||||
|
||||
**3. Feature File**
|
||||
|
||||
```markdown
|
||||
Features/walk-booking-logic.feature.md
|
||||
|
||||
**User Interactions:**
|
||||
|
||||
- Book walk → GRAY state
|
||||
- Start walk → BLUE state
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- One active walk per dog
|
||||
- Can't book if slot taken
|
||||
|
||||
**API Endpoints:**
|
||||
|
||||
- POST /api/walks
|
||||
- PUT /api/walks/:id/start
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
- ✅ Clean handoffs (designer, developer, AI)
|
||||
- ✅ Nothing gets missed (all features documented)
|
||||
- ✅ Easy to maintain (update specs, not code)
|
||||
- ✅ Design system integrity (consistent patterns)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Examples](examples/) - See real decompositions
|
||||
- [Storyboards](02-storyboards/00-STORYBOARDS-GUIDE.md) - Visual documentation
|
||||
@@ -0,0 +1,312 @@
|
||||
# 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:**
|
||||
|
||||
```markdown
|
||||
## 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:**
|
||||
|
||||
```markdown
|
||||
### 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
|
||||
|
||||
```markdown
|
||||
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
|
||||
|
||||
```markdown
|
||||
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](01-complexity-detection.md) - When to decompose components
|
||||
- [Complexity Router Workflow](02-complexity-router-workflow.md) - How to decompose complex components
|
||||
@@ -0,0 +1,75 @@
|
||||
# Storyboard Integration
|
||||
|
||||
**Using visual storyboards for complex components**
|
||||
|
||||
---
|
||||
|
||||
## Core Concepts (01-)
|
||||
|
||||
### [What Are Storyboards?](01-what-are-storyboards.md)
|
||||
|
||||
Visual documentation of state transitions and flows
|
||||
|
||||
### [When to Use Storyboards](01-when-to-use.md)
|
||||
|
||||
Complexity indicators that require visual documentation
|
||||
|
||||
### [Storyboard Types](01-storyboard-types.md)
|
||||
|
||||
State transitions, interaction flows, multi-component sync
|
||||
|
||||
---
|
||||
|
||||
## Storage & Organization (02-)
|
||||
|
||||
### [File Structure](02-file-structure.md)
|
||||
|
||||
Where to store storyboards in the three-tier architecture
|
||||
|
||||
### [Naming Conventions](02-naming-conventions.md)
|
||||
|
||||
How to name storyboard files
|
||||
|
||||
---
|
||||
|
||||
## Creation Guidelines
|
||||
|
||||
### [How to Create Storyboards](creation-guide.md)
|
||||
|
||||
Hand-drawn, digital, or annotated screenshots
|
||||
|
||||
### [Annotation Best Practices](annotation-guide.md)
|
||||
|
||||
Numbering, labels, and visual indicators
|
||||
|
||||
---
|
||||
|
||||
## Integration
|
||||
|
||||
### [Referencing in Feature Files](feature-file-integration.md)
|
||||
|
||||
How to link storyboards from specifications
|
||||
|
||||
### [Referencing in Component Files](component-file-integration.md)
|
||||
|
||||
Visual state references
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### [TaskFlow Task States](examples/task-states.md)
|
||||
|
||||
6-state walk booking storyboard
|
||||
|
||||
### [Search Flow](examples/search-flow.md)
|
||||
|
||||
Multi-step interaction storyboard
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
### [Why Storyboards Work](benefits.md)
|
||||
|
||||
Developer clarity, QA testing, design consistency
|
||||
@@ -0,0 +1,128 @@
|
||||
# Benefits of Three-Tier Architecture
|
||||
|
||||
**Why this approach works**
|
||||
|
||||
---
|
||||
|
||||
## 1. Prevents Overwhelming Specs
|
||||
|
||||
**Before:**
|
||||
|
||||
- 800-line monolithic file
|
||||
- Everything mixed together
|
||||
- Hard to find anything
|
||||
|
||||
**After:**
|
||||
|
||||
- 3 focused files (100-200 lines each)
|
||||
- Clear separation
|
||||
- Easy to navigate
|
||||
|
||||
---
|
||||
|
||||
## 2. Clean Handoffs
|
||||
|
||||
**Visual Designer** receives:
|
||||
|
||||
- `Components/` folder only
|
||||
- Clear visual specifications
|
||||
- Creates Figma components
|
||||
|
||||
**Developer** receives:
|
||||
|
||||
- `Features/` folder only
|
||||
- Clear business logic
|
||||
- Implements functionality
|
||||
|
||||
**You** maintain:
|
||||
|
||||
- `Pages/` folder
|
||||
- Design system integrity
|
||||
- Page-specific content
|
||||
|
||||
---
|
||||
|
||||
## 3. Nothing Gets Missed
|
||||
|
||||
**Problem:** Prototype missing leaderboard, week view wrong
|
||||
|
||||
**Cause:** Monolithic spec, developer overwhelmed
|
||||
|
||||
**Solution:**
|
||||
|
||||
- Component file lists ALL visual elements
|
||||
- Feature file lists ALL interactions
|
||||
- Storyboard shows ALL states
|
||||
- **Nothing gets missed**
|
||||
|
||||
---
|
||||
|
||||
## 4. Easy to Update
|
||||
|
||||
**Change request:** "Add countdown timers"
|
||||
|
||||
**Before (Code):**
|
||||
|
||||
- Regenerate code
|
||||
- Previous features break
|
||||
- 2+ hours fixing
|
||||
|
||||
**After (Spec):**
|
||||
|
||||
- Update Feature file (15 minutes)
|
||||
- Regenerate with full context
|
||||
- Everything works
|
||||
|
||||
---
|
||||
|
||||
## 5. Reusability
|
||||
|
||||
**Same component, different pages:**
|
||||
|
||||
```
|
||||
Pages/02-calendar-page.md ──┐
|
||||
Pages/05-dashboard.md ──────┼→ Components/calendar-widget.component.md
|
||||
Pages/08-mobile-view.md ────┘ ↓
|
||||
Features/calendar-logic.feature.md
|
||||
```
|
||||
|
||||
Update Component or Feature once, all pages benefit.
|
||||
|
||||
---
|
||||
|
||||
## 6. Team Collaboration
|
||||
|
||||
**UX Designers** → Focus on `Components/` (Figma specs)
|
||||
**Developers** → Focus on `Features/` (logic implementation)
|
||||
**Content Writers** → Focus on `Pages/` (translations)
|
||||
**Product Managers** → Focus on `Features/` (business rules)
|
||||
|
||||
Everyone works in parallel, no conflicts.
|
||||
|
||||
---
|
||||
|
||||
## 7. Design System Integrity
|
||||
|
||||
**Page files** reference components:
|
||||
|
||||
```markdown
|
||||
**Component:** button-primary.component.md
|
||||
```
|
||||
|
||||
Ensures consistency across pages.
|
||||
|
||||
Easy to update design system globally.
|
||||
|
||||
---
|
||||
|
||||
## ROI
|
||||
|
||||
**Time saved per feature:** 2 hours
|
||||
**Over 10 features:** 20 hours
|
||||
**Over product lifecycle:** 100+ hours
|
||||
|
||||
**Quality improvement:**
|
||||
|
||||
- Zero missing features
|
||||
- Consistent design
|
||||
- Maintainable codebase
|
||||
@@ -0,0 +1,67 @@
|
||||
# Content Placement Decision Tree
|
||||
|
||||
**One-page flowchart for file placement**
|
||||
|
||||
---
|
||||
|
||||
## The Decision Tree
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Does CONTENT vary by page context? │
|
||||
│ (text, images, data source) │
|
||||
└────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌──────┴──────┐
|
||||
│ │
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────┐ ┌──────────────┐
|
||||
│ Page File │ │ Feature File │
|
||||
│ │ │ │
|
||||
│ Document: │ │ Document: │
|
||||
│ - Headings │ │ - Generic │
|
||||
│ - Text │ │ content │
|
||||
│ - Images │ │ - Default │
|
||||
│ - Data API │ │ config │
|
||||
│ - Scope │ │ │
|
||||
└─────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
**Page File (Content Varies):**
|
||||
|
||||
- ✅ Hero heading: "Welcome" (Home) vs "About" (About)
|
||||
- ✅ Search placeholder: "Search products..." vs "Search help..."
|
||||
- ✅ Calendar header: "Familjen Svensson: Vecka 40" (user's family)
|
||||
- ✅ Data API: `/api/families/:currentFamilyId/walks` (user-specific)
|
||||
|
||||
**Feature File (Content Same Everywhere):**
|
||||
|
||||
- ✅ Button text: "Submit" (always the same)
|
||||
- ✅ Error message: "Invalid email" (generic validation)
|
||||
- ✅ Tooltip: "Click to expand" (generic interaction)
|
||||
- ✅ Data API: `/api/products` (same for all users)
|
||||
|
||||
---
|
||||
|
||||
## Visual Design?
|
||||
|
||||
```
|
||||
Is this VISUAL design (colors, spacing, states)?
|
||||
│
|
||||
└─ YES → Component File
|
||||
(Colors, typography, layout, states)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Rule
|
||||
|
||||
- **Page File** = WHERE + WHAT (page-specific)
|
||||
- **Component File** = HOW IT LOOKS (visual design)
|
||||
- **Feature File** = WHAT IT DOES (functionality + generic content)
|
||||
@@ -0,0 +1,742 @@
|
||||
# Component File Structure
|
||||
|
||||
**Modular Organization for Complex Components**
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Complex components (calendars, calculators, graphs, interactive widgets) contain three distinct types of information that should be separated:
|
||||
|
||||
1. **Page Context** - Where/how component appears on specific pages
|
||||
2. **Design System** - Visual design, states, Figma specifications
|
||||
3. **Feature Logic** - Interactive behavior, business rules, data flow
|
||||
|
||||
**Current Issue:** All three are mixed in page specifications, making them hard to maintain and reuse.
|
||||
|
||||
---
|
||||
|
||||
## Proposed Structure
|
||||
|
||||
### File Organization
|
||||
|
||||
```
|
||||
project-root/
|
||||
├─ Pages/ # Page-specific context
|
||||
│ ├─ 01-start-page.md
|
||||
│ ├─ 02-calendar-page.md
|
||||
│ └─ 03-profile-page.md
|
||||
│
|
||||
├─ Components/ # Design System components
|
||||
│ ├─ navigation-bar.component.md
|
||||
│ ├─ feature-card.component.md
|
||||
│ ├─ calendar-widget.component.md
|
||||
│ └─ walk-scheduler.component.md
|
||||
│
|
||||
└─ Features/ # Interactive logic & business rules
|
||||
├─ calendar-logic.feature.md
|
||||
├─ walk-assignment.feature.md
|
||||
├─ notification-system.feature.md
|
||||
└─ user-permissions.feature.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Type Definitions
|
||||
|
||||
### 1. Page Files (`Pages/*.md`)
|
||||
|
||||
**Purpose:** Page-specific layout, component placement, and context
|
||||
|
||||
**Contains:**
|
||||
|
||||
- Page metadata (URL, scenario, purpose)
|
||||
- Layout structure (sections, grid)
|
||||
- Component instances with page-specific config
|
||||
- Content in all languages
|
||||
- Navigation flow (entry/exit points)
|
||||
|
||||
**Does NOT contain:**
|
||||
|
||||
- Component visual design (→ Components/)
|
||||
- Interactive logic (→ Features/)
|
||||
|
||||
**Example:** `02-calendar-page.md`
|
||||
|
||||
```markdown
|
||||
# 02-calendar-page
|
||||
|
||||
**Scenario:** Manage Dog Care Schedule
|
||||
**URL:** `/calendar`
|
||||
|
||||
## Layout Structure
|
||||
|
||||
### Header Section
|
||||
|
||||
- Component: `navigation-bar` (from Components/)
|
||||
- Position: Top, full-width
|
||||
|
||||
### Main Content
|
||||
|
||||
- Component: `calendar-widget` (from Components/)
|
||||
- Position: Center, 80% width
|
||||
- Configuration:
|
||||
- View: Month
|
||||
- Start Day: Monday
|
||||
- Show: Walk assignments only
|
||||
- Feature: `calendar-logic` (from Features/)
|
||||
|
||||
### Sidebar
|
||||
|
||||
- Component: `walk-scheduler` (from Components/)
|
||||
- Position: Right, 20% width
|
||||
- Feature: `walk-assignment` (from Features/)
|
||||
|
||||
## Content
|
||||
|
||||
**Page Title:**
|
||||
|
||||
- EN: "Family Dog Care Calendar"
|
||||
- SE: "Familjens Hundvårdskalender"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Component Files (`Components/*.md`)
|
||||
|
||||
**Purpose:** Visual design, states, variants, Figma specifications
|
||||
|
||||
**Contains:**
|
||||
|
||||
- Component name and purpose
|
||||
- Visual specifications (colors, spacing, typography)
|
||||
- States (default, hover, active, disabled, loading, error)
|
||||
- Variants (sizes, types, themes)
|
||||
- Figma component mapping
|
||||
- Responsive behavior
|
||||
- Accessibility requirements
|
||||
|
||||
**Does NOT contain:**
|
||||
|
||||
- Business logic (→ Features/)
|
||||
- Page-specific placement (→ Pages/)
|
||||
|
||||
**Example:** `calendar-widget.component.md`
|
||||
|
||||
```markdown
|
||||
# Calendar Widget Component
|
||||
|
||||
**Type:** Complex Interactive Component
|
||||
**Design System ID:** `calendar-widget`
|
||||
**Figma Component:** `DS/Widgets/Calendar`
|
||||
|
||||
## Purpose
|
||||
|
||||
Displays a monthly calendar view with interactive date selection and event display.
|
||||
|
||||
## Visual Specifications
|
||||
|
||||
### Layout
|
||||
|
||||
- Grid: 7 columns (days) × 5-6 rows (weeks)
|
||||
- Cell size: 48px × 48px (desktop), 40px × 40px (mobile)
|
||||
- Gap: 4px between cells
|
||||
- Padding: 16px container padding
|
||||
|
||||
### Typography
|
||||
|
||||
- Month/Year header: Large Heading (24px Bold)
|
||||
- Day labels: Caption (12px Medium)
|
||||
- Date numbers: Body Text (16px Regular)
|
||||
- Event indicators: Caption (10px Regular)
|
||||
|
||||
### Colors
|
||||
|
||||
- Background: `--color-surface`
|
||||
- Cell default: `--color-surface-elevated`
|
||||
- Cell hover: `--color-surface-hover`
|
||||
- Cell selected: `--color-primary`
|
||||
- Cell today: `--color-accent`
|
||||
- Cell disabled: `--color-surface-disabled`
|
||||
|
||||
## States
|
||||
|
||||
### Default State
|
||||
|
||||
- All dates visible
|
||||
- Current month displayed
|
||||
- Today highlighted with accent color
|
||||
- No date selected
|
||||
|
||||
### Date Selected
|
||||
|
||||
- Selected date: Primary color background
|
||||
- Date number: White text
|
||||
- Border: 2px solid primary-dark
|
||||
|
||||
### Date Hover
|
||||
|
||||
- Background: Surface-hover color
|
||||
- Cursor: Pointer
|
||||
- Transition: 150ms ease
|
||||
|
||||
### Date Disabled (Past dates)
|
||||
|
||||
- Background: Surface-disabled
|
||||
- Text: Gray-400
|
||||
- Cursor: Not-allowed
|
||||
- No hover effect
|
||||
|
||||
### Loading State
|
||||
|
||||
- Skeleton animation on date cells
|
||||
- Month/year header visible
|
||||
- Navigation disabled
|
||||
|
||||
### With Events
|
||||
|
||||
- Small dot indicator below date number
|
||||
- Dot color: Event category color
|
||||
- Max 3 dots visible per cell
|
||||
|
||||
## Variants
|
||||
|
||||
### Size Variants
|
||||
|
||||
- **Large:** 56px cells (desktop default)
|
||||
- **Medium:** 48px cells (tablet)
|
||||
- **Small:** 40px cells (mobile)
|
||||
|
||||
### View Variants
|
||||
|
||||
- **Month View:** Default, shows full month
|
||||
- **Week View:** Shows 7 days in row
|
||||
- **Day View:** Shows single day with hourly slots
|
||||
|
||||
## Figma Specifications
|
||||
|
||||
**Component Path:** `Design System > Widgets > Calendar`
|
||||
|
||||
**Variants to Create:**
|
||||
|
||||
- Size: Large / Medium / Small
|
||||
- View: Month / Week / Day
|
||||
- State: Default / Selected / Disabled / Loading
|
||||
|
||||
**Auto-layout:** Enabled
|
||||
**Constraints:** Fill container width
|
||||
|
||||
## Responsive Behavior
|
||||
|
||||
### Mobile (< 768px)
|
||||
|
||||
- Use Small variant (40px cells)
|
||||
- Stack month navigation vertically
|
||||
- Reduce padding to 12px
|
||||
|
||||
### Tablet (768px - 1024px)
|
||||
|
||||
- Use Medium variant (48px cells)
|
||||
- Horizontal month navigation
|
||||
- Standard padding (16px)
|
||||
|
||||
### Desktop (> 1024px)
|
||||
|
||||
- Use Large variant (56px cells)
|
||||
- Full navigation controls
|
||||
- Increased padding (20px)
|
||||
|
||||
## Accessibility
|
||||
|
||||
- **Keyboard Navigation:**
|
||||
- Arrow keys: Navigate between dates
|
||||
- Enter/Space: Select date
|
||||
- Tab: Move to month navigation
|
||||
- **Screen Readers:**
|
||||
- ARIA label: "Calendar, {Month} {Year}"
|
||||
- Each date: "Select {Day}, {Date} {Month}"
|
||||
- Selected date: "Selected, {Day}, {Date} {Month}"
|
||||
- **Focus Management:**
|
||||
- Visible focus ring on keyboard navigation
|
||||
- Focus trap within calendar when open
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Features:** Requires `calendar-logic.feature.md` for interaction behavior
|
||||
- **Data:** Expects events array from API
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Feature Files (`Features/*.md`)
|
||||
|
||||
**Purpose:** Interactive logic, business rules, data flow, state management
|
||||
|
||||
**Contains:**
|
||||
|
||||
- Feature name and purpose
|
||||
- User interactions and system responses
|
||||
- Business rules and validation
|
||||
- State transitions
|
||||
- Data requirements (API endpoints, data models)
|
||||
- Edge cases and error handling
|
||||
|
||||
**Does NOT contain:**
|
||||
|
||||
- Visual design (→ Components/)
|
||||
- Page layout (→ Pages/)
|
||||
|
||||
**Example:** `calendar-logic.feature.md`
|
||||
|
||||
````markdown
|
||||
# Calendar Logic Feature
|
||||
|
||||
**Feature ID:** `calendar-logic`
|
||||
**Type:** Interactive Widget Logic
|
||||
**Complexity:** High
|
||||
|
||||
## Purpose
|
||||
|
||||
Manages calendar interactions, date selection, event display, and navigation between months/weeks/days.
|
||||
|
||||
## User Interactions
|
||||
|
||||
### Interaction 1: Select Date
|
||||
|
||||
**Trigger:** User clicks on a date cell
|
||||
|
||||
**Flow:**
|
||||
|
||||
1. User clicks date cell
|
||||
2. System validates date is not disabled
|
||||
3. System updates selected date state
|
||||
4. System triggers `onDateSelect` callback with date
|
||||
5. System highlights selected date
|
||||
6. System updates related components (e.g., event list for that date)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Cannot select dates in the past (configurable)
|
||||
- Cannot select dates beyond 1 year in future (configurable)
|
||||
- Can only select one date at a time (single-select mode)
|
||||
- Can select date range (range-select mode, if enabled)
|
||||
|
||||
**Edge Cases:**
|
||||
|
||||
- Clicking already selected date: Deselects it
|
||||
- Clicking disabled date: No action, show tooltip
|
||||
- Rapid clicking: Debounce to prevent multiple selections
|
||||
|
||||
### Interaction 2: Navigate to Next Month
|
||||
|
||||
**Trigger:** User clicks "Next Month" button
|
||||
|
||||
**Flow:**
|
||||
|
||||
1. User clicks next month button
|
||||
2. System increments month by 1
|
||||
3. System fetches events for new month (if needed)
|
||||
4. System re-renders calendar with new month
|
||||
5. System clears selected date (optional, configurable)
|
||||
6. System updates month/year header
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Cannot navigate beyond max date (1 year from today)
|
||||
- Loading state shown while fetching events
|
||||
- Previous selections cleared on month change
|
||||
|
||||
### Interaction 3: View Events for Date
|
||||
|
||||
**Trigger:** User hovers over date with event indicators
|
||||
|
||||
**Flow:**
|
||||
|
||||
1. User hovers over date cell with events
|
||||
2. System shows tooltip with event summary
|
||||
3. Tooltip displays: Event count, first 2 event titles
|
||||
4. User can click to see full event list
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Tooltip appears after 300ms hover
|
||||
- Max 2 events shown in tooltip
|
||||
- "And X more" shown if > 2 events
|
||||
|
||||
## State Management
|
||||
|
||||
### Component State
|
||||
|
||||
```javascript
|
||||
{
|
||||
currentMonth: Date, // Currently displayed month
|
||||
selectedDate: Date | null, // User-selected date
|
||||
viewMode: 'month' | 'week' | 'day',
|
||||
events: Event[], // Events for current view
|
||||
loading: boolean, // Loading state
|
||||
error: string | null // Error message
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
### State Transitions
|
||||
|
||||
**Initial State:**
|
||||
|
||||
- currentMonth: Current month
|
||||
- selectedDate: null
|
||||
- viewMode: 'month'
|
||||
- events: []
|
||||
- loading: false
|
||||
- error: null
|
||||
|
||||
**On Date Select:**
|
||||
|
||||
- selectedDate: clicked date
|
||||
- Trigger callback: onDateSelect(date)
|
||||
|
||||
**On Month Change:**
|
||||
|
||||
- currentMonth: new month
|
||||
- selectedDate: null (if clearOnMonthChange = true)
|
||||
- loading: true
|
||||
- Fetch events for new month
|
||||
- loading: false
|
||||
|
||||
**On Error:**
|
||||
|
||||
- error: error message
|
||||
- loading: false
|
||||
- Show error state in UI
|
||||
|
||||
## Data Requirements
|
||||
|
||||
### API Endpoints
|
||||
|
||||
**Get Events for Month**
|
||||
|
||||
- **Method:** GET
|
||||
- **Path:** `/api/calendar/events?month={YYYY-MM}`
|
||||
- **Purpose:** Fetch all events for specified month
|
||||
- **Response:**
|
||||
```json
|
||||
{
|
||||
"events": [
|
||||
{
|
||||
"id": "evt_123",
|
||||
"date": "2024-12-15",
|
||||
"title": "Morning Walk - Max",
|
||||
"category": "walk",
|
||||
"assignedTo": "user_456"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Create Event**
|
||||
|
||||
- **Method:** POST
|
||||
- **Path:** `/api/calendar/events`
|
||||
- **Purpose:** Create new calendar event
|
||||
- **Request:**
|
||||
```json
|
||||
{
|
||||
"date": "2024-12-15",
|
||||
"title": "Morning Walk",
|
||||
"category": "walk",
|
||||
"assignedTo": "user_456"
|
||||
}
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
**Event Model:**
|
||||
|
||||
```typescript
|
||||
interface Event {
|
||||
id: string;
|
||||
date: string; // ISO date format
|
||||
title: string;
|
||||
category: 'walk' | 'feeding' | 'vet' | 'grooming';
|
||||
assignedTo: string; // User ID
|
||||
completed: boolean;
|
||||
notes?: string;
|
||||
}
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
| Rule | Validation | Error Message |
|
||||
| ------------ | ----------------------------------------- | -------------------------------------- |
|
||||
| Date in past | `date < today` | "Cannot select past dates" |
|
||||
| Date too far | `date > today + 365 days` | "Cannot select dates beyond 1 year" |
|
||||
| Event title | `title.length > 0 && title.length <= 100` | "Event title required (max 100 chars)" |
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Network Error (Failed to fetch events)
|
||||
|
||||
- **Trigger:** API request fails
|
||||
- **Action:** Show error state in calendar
|
||||
- **Message:** "Unable to load events. Please try again."
|
||||
- **Recovery:** Retry button
|
||||
|
||||
### Invalid Date Selection
|
||||
|
||||
- **Trigger:** User attempts to select disabled date
|
||||
- **Action:** Show tooltip
|
||||
- **Message:** "This date is not available"
|
||||
- **Recovery:** Select different date
|
||||
|
||||
## Configuration Options
|
||||
|
||||
```javascript
|
||||
{
|
||||
minDate: Date | null, // Earliest selectable date
|
||||
maxDate: Date | null, // Latest selectable date
|
||||
disablePastDates: boolean, // Disable dates before today
|
||||
clearOnMonthChange: boolean, // Clear selection on month change
|
||||
selectionMode: 'single' | 'range',
|
||||
showEventIndicators: boolean, // Show dots for events
|
||||
fetchEventsOnMount: boolean, // Auto-fetch on load
|
||||
onDateSelect: (date: Date) => void,
|
||||
onMonthChange: (month: Date) => void,
|
||||
onEventClick: (event: Event) => void
|
||||
}
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Component:** `calendar-widget.component.md` (visual design)
|
||||
- **Feature:** `walk-assignment.feature.md` (for creating walk events)
|
||||
- **API:** Calendar Events API
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits of This Structure
|
||||
|
||||
### 1. Separation of Concerns
|
||||
|
||||
| Concern | File Type | Example |
|
||||
|---------|-----------|---------|
|
||||
| **Where** component appears | Page | `02-calendar-page.md` |
|
||||
| **How** component looks | Component | `calendar-widget.component.md` |
|
||||
| **What** component does | Feature | `calendar-logic.feature.md` |
|
||||
|
||||
### 2. Reusability
|
||||
|
||||
**Component used on multiple pages:**
|
||||
```
|
||||
|
||||
Pages/02-calendar-page.md → Components/calendar-widget.component.md
|
||||
Pages/05-dashboard.md → Components/calendar-widget.component.md
|
||||
↓
|
||||
Features/calendar-logic.feature.md
|
||||
|
||||
```
|
||||
|
||||
**Same component, different configurations:**
|
||||
- Calendar Page: Month view, full-width
|
||||
- Dashboard: Week view, sidebar widget
|
||||
|
||||
### 3. Team Collaboration
|
||||
|
||||
| Role | Primary Files | Secondary Files |
|
||||
|------|---------------|-----------------|
|
||||
| **UX Designer** | Components/ | Pages/ (layout) |
|
||||
| **Developer** | Features/ | Components/ (implementation) |
|
||||
| **Content Writer** | Pages/ | - |
|
||||
| **Product Manager** | Features/ (rules) | Pages/ (flow) |
|
||||
|
||||
### 4. Maintainability
|
||||
|
||||
**Change visual design:**
|
||||
- Edit: `Components/calendar-widget.component.md`
|
||||
- Impact: All pages using calendar automatically updated
|
||||
|
||||
**Change business logic:**
|
||||
- Edit: `Features/calendar-logic.feature.md`
|
||||
- Impact: All instances of calendar use new logic
|
||||
|
||||
**Change page layout:**
|
||||
- Edit: `Pages/02-calendar-page.md`
|
||||
- Impact: Only that specific page
|
||||
|
||||
---
|
||||
|
||||
## File Naming Conventions
|
||||
|
||||
### Pages
|
||||
```
|
||||
|
||||
{number}-{page-name}.md
|
||||
|
||||
Examples:
|
||||
01-start-page.md
|
||||
02-calendar-page.md
|
||||
03-profile-settings.md
|
||||
|
||||
```
|
||||
|
||||
### Components
|
||||
```
|
||||
|
||||
{component-name}.component.md
|
||||
|
||||
Examples:
|
||||
navigation-bar.component.md
|
||||
feature-card.component.md
|
||||
calendar-widget.component.md
|
||||
walk-scheduler.component.md
|
||||
|
||||
```
|
||||
|
||||
### Features
|
||||
```
|
||||
|
||||
{feature-name}.feature.md
|
||||
|
||||
Examples:
|
||||
calendar-logic.feature.md
|
||||
walk-assignment.feature.md
|
||||
user-authentication.feature.md
|
||||
notification-system.feature.md
|
||||
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
## Cross-Reference System
|
||||
|
||||
### In Page Files
|
||||
|
||||
Reference components and features:
|
||||
|
||||
```markdown
|
||||
### Main Content Section
|
||||
|
||||
**Component:** `calendar-widget` (→ Components/calendar-widget.component.md)
|
||||
**Feature:** `calendar-logic` (→ Features/calendar-logic.feature.md)
|
||||
**Configuration:**
|
||||
- View: Month
|
||||
- Disable past dates: true
|
||||
````
|
||||
|
||||
### In Component Files
|
||||
|
||||
Reference required features:
|
||||
|
||||
```markdown
|
||||
## Dependencies
|
||||
|
||||
- **Feature:** `calendar-logic.feature.md` (interaction behavior)
|
||||
- **Feature:** `walk-assignment.feature.md` (event creation)
|
||||
```
|
||||
|
||||
### In Feature Files
|
||||
|
||||
Reference related components:
|
||||
|
||||
```markdown
|
||||
## Dependencies
|
||||
|
||||
- **Component:** `calendar-widget.component.md` (visual implementation)
|
||||
- **API:** Calendar Events API
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### Phase 1: Create Structure
|
||||
|
||||
1. Create `Components/` folder
|
||||
2. Create `Features/` folder
|
||||
3. Keep existing `Pages/` (or create if needed)
|
||||
|
||||
### Phase 2: Extract Components
|
||||
|
||||
1. Identify reusable components in page specs
|
||||
2. Create component files with visual design only
|
||||
3. Update page files to reference components
|
||||
|
||||
### Phase 3: Extract Features
|
||||
|
||||
1. Identify complex interactive logic
|
||||
2. Create feature files with business rules
|
||||
3. Update page and component files to reference features
|
||||
|
||||
### Phase 4: Refactor Existing Pages
|
||||
|
||||
1. Move visual specs → Components/
|
||||
2. Move logic → Features/
|
||||
3. Keep layout & content in Pages/
|
||||
|
||||
---
|
||||
|
||||
## Example: Dog Week Calendar
|
||||
|
||||
### Before (Monolithic)
|
||||
|
||||
```
|
||||
Pages/02-calendar-page.md (500 lines)
|
||||
├─ Page layout
|
||||
├─ Calendar visual design
|
||||
├─ Calendar interaction logic
|
||||
├─ Walk scheduler visual design
|
||||
├─ Walk assignment logic
|
||||
├─ Navigation bar design
|
||||
└─ All content in all languages
|
||||
```
|
||||
|
||||
### After (Modular)
|
||||
|
||||
```
|
||||
Pages/02-calendar-page.md (100 lines)
|
||||
├─ Page layout
|
||||
├─ Component references
|
||||
├─ Feature references
|
||||
└─ Content in all languages
|
||||
|
||||
Components/calendar-widget.component.md (150 lines)
|
||||
├─ Visual specifications
|
||||
├─ States & variants
|
||||
└─ Figma mapping
|
||||
|
||||
Components/walk-scheduler.component.md (100 lines)
|
||||
├─ Visual specifications
|
||||
└─ States & variants
|
||||
|
||||
Features/calendar-logic.feature.md (200 lines)
|
||||
├─ Interaction flows
|
||||
├─ Business rules
|
||||
├─ Data requirements
|
||||
└─ Error handling
|
||||
|
||||
Features/walk-assignment.feature.md (150 lines)
|
||||
├─ Assignment logic
|
||||
├─ Validation rules
|
||||
└─ API integration
|
||||
```
|
||||
|
||||
**Result:** Easier to maintain, reuse, and collaborate!
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Three-tier architecture:**
|
||||
|
||||
1. **Pages/** - Layout, placement, content (WHERE)
|
||||
2. **Components/** - Visual design, states, Figma (HOW IT LOOKS)
|
||||
3. **Features/** - Logic, rules, data (WHAT IT DOES)
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- ✅ Clear separation of concerns
|
||||
- ✅ Reusable components across pages
|
||||
- ✅ Maintainable business logic
|
||||
- ✅ Better team collaboration
|
||||
- ✅ Aligns with BMad v6 modular philosophy
|
||||
@@ -0,0 +1,552 @@
|
||||
# Content Placement Guide
|
||||
|
||||
**Where to Document Content: Page vs Component vs Feature**
|
||||
|
||||
---
|
||||
|
||||
## Quick Decision Tree
|
||||
|
||||
```
|
||||
Is this CONTENT (text, images, data)?
|
||||
│
|
||||
├─ YES → Does it vary by page context?
|
||||
│ │
|
||||
│ ├─ YES → Page File
|
||||
│ │ (e.g., "Welcome to Dog Week" on Home, "About Dog Week" on About)
|
||||
│ │
|
||||
│ └─ NO → Feature File
|
||||
│ (e.g., "Submit" button text is always the same)
|
||||
│
|
||||
└─ NO → Is this VISUAL design (colors, spacing, states)?
|
||||
│
|
||||
└─ YES → Component File
|
||||
(e.g., button is blue, 48px height, has hover state)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Three File Types
|
||||
|
||||
### 1. Page File (WHERE)
|
||||
|
||||
**Contains:**
|
||||
|
||||
- ✅ Position & size
|
||||
- ✅ **Page-specific content** (headings, text, images that change per page)
|
||||
- ✅ **Page-specific data** (API endpoints with page context)
|
||||
- ✅ Component references
|
||||
- ✅ Feature references
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
## Pages/01-home-page.md
|
||||
|
||||
### Hero Section
|
||||
|
||||
**Component:** `hero-banner.component.md`
|
||||
|
||||
**Position:** Top of page, full-width
|
||||
**Size:** 400px height (desktop), 300px (mobile)
|
||||
|
||||
**Page-Specific Content:**
|
||||
|
||||
- Heading: "Welcome to Dog Week" / "Välkommen till Dog Week"
|
||||
- Subheading: "Coordinate your family's dog walks effortlessly"
|
||||
- Background Image: `/images/hero-home-happy-dog.jpg`
|
||||
- CTA Button Text: "Get Started" / "Kom igång"
|
||||
- CTA Button Link: → `/onboarding/start`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Component File (HOW IT LOOKS)
|
||||
|
||||
**Contains:**
|
||||
|
||||
- ✅ Visual specifications (colors, spacing, typography)
|
||||
- ✅ States (default, hover, active, disabled, loading, error)
|
||||
- ✅ Variants (sizes, types, themes)
|
||||
- ✅ Figma component mapping
|
||||
- ✅ Responsive behavior
|
||||
- ✅ Accessibility
|
||||
- ❌ **NO content** (no text, no images, no data)
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
## Components/hero-banner.component.md
|
||||
|
||||
# Hero Banner Component
|
||||
|
||||
**Visual Specifications:**
|
||||
|
||||
- Height: 400px (desktop), 300px (mobile)
|
||||
- Layout: Centered text over background image
|
||||
- Background: Image with dark overlay (40% opacity)
|
||||
- Typography:
|
||||
- Heading: 48px Bold, white color
|
||||
- Subheading: 18px Regular, white color
|
||||
- CTA Button: Primary button style (blue background, white text)
|
||||
|
||||
**Content Slots:**
|
||||
|
||||
- Heading text (configurable per page)
|
||||
- Subheading text (configurable per page)
|
||||
- Background image (configurable per page)
|
||||
- CTA button text + link (configurable per page)
|
||||
|
||||
**States:**
|
||||
|
||||
- Default: Full opacity
|
||||
- Loading: Skeleton placeholder
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Feature File (WHAT IT DOES)
|
||||
|
||||
**Contains:**
|
||||
|
||||
- ✅ User interactions & system responses
|
||||
- ✅ Business rules & validation
|
||||
- ✅ State management
|
||||
- ✅ **Generic content** (content that's the same everywhere)
|
||||
- ✅ **Generic data** (API endpoints without page context)
|
||||
- ✅ Error handling
|
||||
- ✅ Configuration options
|
||||
- ❌ **NO visual design** (no colors, no spacing, no states)
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
## Features/hero-cta-logic.feature.md
|
||||
|
||||
# Hero CTA Logic Feature
|
||||
|
||||
**User Interactions:**
|
||||
|
||||
### Click CTA Button
|
||||
|
||||
1. User clicks CTA button
|
||||
2. System validates user session
|
||||
3. If logged in → Navigate to destination
|
||||
4. If not logged in → Show login modal first
|
||||
|
||||
**Generic Content:**
|
||||
|
||||
- Loading text: "Loading..." / "Laddar..."
|
||||
- Error message: "Something went wrong" / "Något gick fel"
|
||||
|
||||
**API Endpoints:**
|
||||
|
||||
- GET /api/user/session (check if logged in)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- CTA disabled during loading
|
||||
- CTA shows loading spinner when clicked
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content Placement Examples
|
||||
|
||||
### Example 1: Hero Section
|
||||
|
||||
**Scenario:** Hero banner appears on multiple pages with different content
|
||||
|
||||
**Page File (Home):**
|
||||
|
||||
```markdown
|
||||
**Page-Specific Content:**
|
||||
|
||||
- Heading: "Welcome to Dog Week"
|
||||
- Subheading: "Coordinate your family's dog walks"
|
||||
- Background Image: `/images/hero-home.jpg`
|
||||
- CTA Text: "Get Started"
|
||||
- CTA Link: `/onboarding/start`
|
||||
```
|
||||
|
||||
**Page File (About):**
|
||||
|
||||
```markdown
|
||||
**Page-Specific Content:**
|
||||
|
||||
- Heading: "About Dog Week"
|
||||
- Subheading: "Our mission to simplify dog care"
|
||||
- Background Image: `/images/hero-about.jpg`
|
||||
- CTA Text: "Contact Us"
|
||||
- CTA Link: `/contact`
|
||||
```
|
||||
|
||||
**Component File:**
|
||||
|
||||
```markdown
|
||||
**Visual Specifications:**
|
||||
|
||||
- Height: 400px
|
||||
- Typography: 48px Bold heading, 18px Regular subheading
|
||||
- Layout: Centered text over image
|
||||
|
||||
**Content Slots:**
|
||||
|
||||
- Heading (configurable)
|
||||
- Subheading (configurable)
|
||||
- Background image (configurable)
|
||||
- CTA button (configurable)
|
||||
```
|
||||
|
||||
**Feature File:**
|
||||
|
||||
```markdown
|
||||
**Generic Content:**
|
||||
|
||||
- Loading text: "Loading..."
|
||||
|
||||
**Interactions:**
|
||||
|
||||
- Click CTA → Navigate to link
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Search Bar
|
||||
|
||||
**Scenario:** Search bar appears on Product page and Help page with different scopes
|
||||
|
||||
**Page File (Product Catalog):**
|
||||
|
||||
```markdown
|
||||
**Page-Specific Content:**
|
||||
|
||||
- Placeholder: "Search products..." / "Sök produkter..."
|
||||
|
||||
**Page-Specific Data:**
|
||||
|
||||
- API Endpoint: GET /api/products/search?q=:query
|
||||
- Scope: Products only
|
||||
- Result Display: Product cards grid
|
||||
```
|
||||
|
||||
**Page File (Help Center):**
|
||||
|
||||
```markdown
|
||||
**Page-Specific Content:**
|
||||
|
||||
- Placeholder: "Search help articles..." / "Sök hjälpartiklar..."
|
||||
|
||||
**Page-Specific Data:**
|
||||
|
||||
- API Endpoint: GET /api/help/search?q=:query
|
||||
- Scope: Help articles only
|
||||
- Result Display: Article list
|
||||
```
|
||||
|
||||
**Component File:**
|
||||
|
||||
```markdown
|
||||
**Visual Specifications:**
|
||||
|
||||
- Height: 48px
|
||||
- Border: 1px solid gray
|
||||
- States:
|
||||
- Default: Gray border
|
||||
- Focused: Blue border
|
||||
- Loading: Spinner icon on right
|
||||
- Results: Dropdown below input
|
||||
|
||||
**Content Slots:**
|
||||
|
||||
- Placeholder text (configurable per page)
|
||||
```
|
||||
|
||||
**Feature File:**
|
||||
|
||||
```markdown
|
||||
**Generic Content:**
|
||||
|
||||
- No results message: "No results found" / "Inga resultat"
|
||||
- Error message: "Search failed" / "Sökning misslyckades"
|
||||
|
||||
**Interactions:**
|
||||
|
||||
- User types → Debounce 300ms → API call
|
||||
- Min 3 characters required
|
||||
- Max 10 results displayed
|
||||
- Keyboard navigation (arrow keys, enter, escape)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Debounce: 300ms
|
||||
- Min characters: 3
|
||||
- Max results: 10
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Calendar Widget
|
||||
|
||||
**Scenario:** Calendar appears only on Calendar page, shows current user's family data
|
||||
|
||||
**Page File (Calendar Page):**
|
||||
|
||||
```markdown
|
||||
**Page-Specific Content:**
|
||||
|
||||
- Header Format: "[Family Name]: Vecka [Week Number]"
|
||||
- SE: "Familjen Svensson: Vecka 40"
|
||||
- EN: "Svensson Family: Week 40"
|
||||
|
||||
**Page-Specific Data:**
|
||||
|
||||
- Data Source: Current user's family from session
|
||||
- API Endpoint: GET /api/families/:currentFamilyId/walks?week=:weekNumber
|
||||
- Dogs Displayed: All dogs in current user's family
|
||||
- Family Members: All members in current user's family
|
||||
|
||||
**Configuration:**
|
||||
|
||||
- Initial View: Current week, scrolled to today
|
||||
- Time Slots: 4 hardcoded (8-11, 12-13, 15-17, 18-20)
|
||||
```
|
||||
|
||||
**Component File:**
|
||||
|
||||
```markdown
|
||||
**Visual Specifications:**
|
||||
|
||||
- 6 walk states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED)
|
||||
- Week circles: 7 days with quarter segments
|
||||
- Leaderboard cards: Avatar + badge + name
|
||||
|
||||
**Content Slots:**
|
||||
|
||||
- Header text (configurable per page)
|
||||
- Time slot labels (configurable)
|
||||
```
|
||||
|
||||
**Feature File:**
|
||||
|
||||
```markdown
|
||||
**Generic Content:**
|
||||
|
||||
- Empty state: "Add a dog to start planning walks"
|
||||
- Error message: "Failed to load walks"
|
||||
- Countdown format: "32 min left" / "32 min kvar"
|
||||
- Duration format: "32 min walk" / "32 min promenad"
|
||||
|
||||
**Interactions:**
|
||||
|
||||
- Book walk → GRAY state
|
||||
- Start walk → BLUE state
|
||||
- Complete walk → GREEN state
|
||||
- Miss walk → RED state
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- One active walk per dog
|
||||
- Can't book if slot taken
|
||||
- Countdown starts at slot start time
|
||||
|
||||
**API Endpoints:**
|
||||
|
||||
- GET /api/families/:familyId/walks?week=:weekNumber
|
||||
- POST /api/walks (create booking)
|
||||
- PUT /api/walks/:walkId/start
|
||||
- PUT /api/walks/:walkId/complete
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 4: Submit Button
|
||||
|
||||
**Scenario:** Submit button appears on multiple forms, always says "Submit"
|
||||
|
||||
**Page File:**
|
||||
|
||||
```markdown
|
||||
**Position:** Bottom of form, right-aligned
|
||||
**Size:** Full-width on mobile, auto-width on desktop
|
||||
|
||||
**Component:** `button-primary.component.md`
|
||||
**Feature:** `form-submit-logic.feature.md`
|
||||
|
||||
(No page-specific content - button text is always "Submit")
|
||||
```
|
||||
|
||||
**Component File:**
|
||||
|
||||
```markdown
|
||||
**Visual Specifications:**
|
||||
|
||||
- Background: Blue (#3B82F6)
|
||||
- Text: White, 16px Medium
|
||||
- Height: 48px
|
||||
- Border Radius: 8px
|
||||
- States:
|
||||
- Default: Blue background
|
||||
- Hover: Darker blue
|
||||
- Active: Even darker blue
|
||||
- Disabled: Gray background
|
||||
- Loading: Blue background + spinner
|
||||
```
|
||||
|
||||
**Feature File:**
|
||||
|
||||
```markdown
|
||||
**Generic Content:**
|
||||
|
||||
- Button text: "Submit" / "Skicka"
|
||||
- Loading text: "Submitting..." / "Skickar..."
|
||||
- Success message: "Submitted successfully" / "Skickat"
|
||||
- Error message: "Submission failed" / "Misslyckades"
|
||||
|
||||
**Interactions:**
|
||||
|
||||
- Click → Validate form
|
||||
- If valid → Submit to API
|
||||
- If invalid → Show validation errors
|
||||
- Show loading state during submission
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
| Content Type | Page-Specific? | Where to Document |
|
||||
| ---------------------------------- | --------------------------------- | ----------------- |
|
||||
| **Hero heading** | ✅ YES (different per page) | Page File |
|
||||
| **Hero background image** | ✅ YES (different per page) | Page File |
|
||||
| **Search placeholder** | ✅ YES (different per page) | Page File |
|
||||
| **Calendar header** | ✅ YES (shows user's family name) | Page File |
|
||||
| **API endpoint with user context** | ✅ YES (varies by user/page) | Page File |
|
||||
| **Submit button text** | ❌ NO (always "Submit") | Feature File |
|
||||
| **Error messages** | ❌ NO (generic validation) | Feature File |
|
||||
| **Loading text** | ❌ NO (always "Loading...") | Feature File |
|
||||
| **Tooltip text** | ❌ NO (generic interaction) | Feature File |
|
||||
| **API endpoint (generic)** | ❌ NO (same for all users) | Feature File |
|
||||
| **Button color** | ❌ NO (visual design) | Component File |
|
||||
| **Font size** | ❌ NO (visual design) | Component File |
|
||||
| **Hover state** | ❌ NO (visual design) | Component File |
|
||||
| **Layout spacing** | ❌ NO (visual design) | Component File |
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### ❌ Mistake 1: Putting page-specific content in Feature file
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```markdown
|
||||
## Features/hero-logic.feature.md
|
||||
|
||||
**Content:**
|
||||
|
||||
- Heading: "Welcome to Dog Week" (Home page)
|
||||
- Heading: "About Dog Week" (About page)
|
||||
```
|
||||
|
||||
**Right:**
|
||||
|
||||
```markdown
|
||||
## Pages/01-home-page.md
|
||||
|
||||
**Page-Specific Content:**
|
||||
|
||||
- Heading: "Welcome to Dog Week"
|
||||
|
||||
## Pages/02-about-page.md
|
||||
|
||||
**Page-Specific Content:**
|
||||
|
||||
- Heading: "About Dog Week"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ❌ Mistake 2: Putting generic content in Page file
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```markdown
|
||||
## Pages/01-home-page.md
|
||||
|
||||
**Content:**
|
||||
|
||||
- Submit button: "Submit"
|
||||
- Error message: "Invalid email"
|
||||
```
|
||||
|
||||
**Right:**
|
||||
|
||||
```markdown
|
||||
## Features/form-submit-logic.feature.md
|
||||
|
||||
**Generic Content:**
|
||||
|
||||
- Submit button: "Submit"
|
||||
- Error message: "Invalid email"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ❌ Mistake 3: Putting visual design in Feature file
|
||||
|
||||
**Wrong:**
|
||||
|
||||
```markdown
|
||||
## Features/button-logic.feature.md
|
||||
|
||||
**Visual:**
|
||||
|
||||
- Background: Blue
|
||||
- Height: 48px
|
||||
- Hover: Darker blue
|
||||
```
|
||||
|
||||
**Right:**
|
||||
|
||||
```markdown
|
||||
## Components/button-primary.component.md
|
||||
|
||||
**Visual Specifications:**
|
||||
|
||||
- Background: Blue (#3B82F6)
|
||||
- Height: 48px
|
||||
- States:
|
||||
- Hover: Darker blue (#2563EB)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Content Placement Rule:**
|
||||
|
||||
```
|
||||
Does content vary by page context?
|
||||
├─ YES → Page File
|
||||
│ (Hero heading, search placeholder, user-specific data)
|
||||
│
|
||||
└─ NO → Feature File
|
||||
(Button text, error messages, generic tooltips)
|
||||
|
||||
Is this visual design?
|
||||
└─ YES → Component File
|
||||
(Colors, spacing, states, typography)
|
||||
```
|
||||
|
||||
**Key Principle:**
|
||||
|
||||
- **Page File** = WHERE + WHAT (page-specific)
|
||||
- **Component File** = HOW IT LOOKS (visual design)
|
||||
- **Feature File** = WHAT IT DOES (functionality + generic content)
|
||||
|
||||
**Result:**
|
||||
|
||||
- ✅ Clear separation of concerns
|
||||
- ✅ Easy to maintain and update
|
||||
- ✅ Clean handoffs to designers and developers
|
||||
- ✅ No confusion about where content belongs
|
||||
@@ -0,0 +1,301 @@
|
||||
# Cross-Page Consistency Strategy
|
||||
|
||||
**Maintaining Visual Coherence Across Project Sketches**
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Text that looks similar and serves the same role should have the same specification across all pages.**
|
||||
|
||||
This creates:
|
||||
|
||||
- ✅ Consistent user experience
|
||||
- ✅ Natural design system patterns
|
||||
- ✅ Faster specification process
|
||||
- ✅ Professional, cohesive design
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Multi-Page Projects
|
||||
|
||||
### Page 1: Start Page (Establish Baseline)
|
||||
|
||||
**First page analyzed - establish reference patterns:**
|
||||
|
||||
```
|
||||
Start Page Analysis:
|
||||
├─ Body Text: Thin lines, icon-sized spacing → 16px Regular
|
||||
├─ Button Labels: Medium lines → 16px Semibold
|
||||
├─ Page Title: Thick lines, button-height spacing → 48px Bold
|
||||
├─ Navigation: Medium lines, small spacing → 14px Medium
|
||||
└─ Caption: Thinnest lines, half-icon spacing → 12px Regular
|
||||
```
|
||||
|
||||
**These become your reference anchors for subsequent pages.**
|
||||
|
||||
---
|
||||
|
||||
### Page 2: About Page (Apply Patterns)
|
||||
|
||||
**When analyzing the About Page sketch:**
|
||||
|
||||
#### Step 1: Check Previous Pages
|
||||
|
||||
```
|
||||
Agent: "I see you've already analyzed the Start Page.
|
||||
I'll use those text styles as reference points."
|
||||
```
|
||||
|
||||
#### Step 2: Match Visual Patterns
|
||||
|
||||
```
|
||||
About Page body text:
|
||||
- Thin lines ✓
|
||||
- Icon-sized spacing ✓
|
||||
- Left-aligned ✓
|
||||
|
||||
→ Matches Start Page body text pattern
|
||||
→ Apply same spec: 16px Regular
|
||||
```
|
||||
|
||||
#### Step 3: Confirm with Designer
|
||||
|
||||
```
|
||||
Agent: "This body text looks identical to Start Page body text.
|
||||
Should I use the same specification (16px Regular)?"
|
||||
|
||||
Designer: "Yes!" or "No, make it 18px"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern Matching Rules
|
||||
|
||||
### When to Apply Same Specification
|
||||
|
||||
**Match if ALL criteria align:**
|
||||
|
||||
1. **Visual Similarity**
|
||||
- Line thickness matches (relative to other elements)
|
||||
- Spacing matches (relative to UI anchors)
|
||||
- Alignment matches
|
||||
|
||||
2. **Functional Role**
|
||||
- Serves same purpose (e.g., both are body paragraphs)
|
||||
- Same content type (e.g., both are descriptions)
|
||||
- Same hierarchy level
|
||||
|
||||
3. **Context**
|
||||
- Similar page sections (e.g., both in main content area)
|
||||
- Similar surrounding elements
|
||||
|
||||
### When to Create New Specification
|
||||
|
||||
**Create new spec if:**
|
||||
|
||||
- Visual appearance differs (thicker lines, different spacing)
|
||||
- Functional role differs (e.g., one is a quote, one is body text)
|
||||
- Designer explicitly requests different styling
|
||||
- Context requires emphasis/de-emphasis
|
||||
|
||||
---
|
||||
|
||||
## Design System Integration
|
||||
|
||||
### Automatic Pattern Building
|
||||
|
||||
As you analyze pages, WDS naturally builds design system patterns:
|
||||
|
||||
```
|
||||
Project: Dog Week
|
||||
|
||||
Text Styles Identified:
|
||||
├─ heading-xl: 48px Bold (Page titles)
|
||||
├─ heading-lg: 36px Bold (Section headings)
|
||||
├─ heading-md: 24px Semibold (Subsection headings)
|
||||
├─ body-text: 16px Regular (Paragraphs)
|
||||
├─ button-label: 16px Semibold (All buttons)
|
||||
├─ caption: 12px Regular (Helper text)
|
||||
└─ nav-item: 14px Medium (Navigation)
|
||||
|
||||
Components Identified:
|
||||
├─ Feature Card (used on Start, Features, About pages)
|
||||
├─ Navigation Bar (used on all pages)
|
||||
├─ Footer (used on all pages)
|
||||
└─ CTA Button (used on Start, Pricing pages)
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
**Without explicit design system:**
|
||||
|
||||
- Maintains consistency through pattern recognition
|
||||
- Reduces specification time (reference previous pages)
|
||||
- Creates professional, cohesive experience
|
||||
|
||||
**With explicit design system:**
|
||||
|
||||
- Automatically maps to existing components
|
||||
- Validates sketch against design system
|
||||
- Suggests design system updates when new patterns emerge
|
||||
|
||||
---
|
||||
|
||||
## Agent Behavior Examples
|
||||
|
||||
### Example 1: Exact Match
|
||||
|
||||
```
|
||||
Agent: "I'm analyzing the Contact Page body text.
|
||||
|
||||
Visual Analysis:
|
||||
- Line thickness: Thinnest (matches Start Page body text)
|
||||
- Spacing: Icon-sized (matches Start Page body text)
|
||||
- Alignment: Left (matches Start Page body text)
|
||||
|
||||
Pattern Match: Start Page body text (16px Regular)
|
||||
|
||||
Should I use the same specification?"
|
||||
|
||||
Designer: "Yes, keep it consistent."
|
||||
|
||||
Agent: "✅ Applied: 16px Regular (consistent with Start Page)"
|
||||
```
|
||||
|
||||
### Example 2: Intentional Variation
|
||||
|
||||
```
|
||||
Agent: "I'm analyzing the Testimonial Quote text.
|
||||
|
||||
Visual Analysis:
|
||||
- Line thickness: Medium (thicker than body text)
|
||||
- Spacing: Slightly larger than body text
|
||||
- Alignment: Center (different from body text)
|
||||
|
||||
This looks different from body text. Should this be:
|
||||
1. New style: 18px Medium, center-aligned (emphasis)
|
||||
2. Same as body: 16px Regular (consistency)
|
||||
|
||||
Your choice?"
|
||||
|
||||
Designer: "Option 1 - quotes should stand out."
|
||||
|
||||
Agent: "✅ Created new style: testimonial-quote (18px Medium)"
|
||||
```
|
||||
|
||||
### Example 3: Component Recognition
|
||||
|
||||
```
|
||||
Agent: "I'm analyzing the Features section on the Pricing Page.
|
||||
|
||||
Component Match Detected:
|
||||
- Layout: 3-column card grid ✓
|
||||
- Card structure: Icon + Title + Description ✓
|
||||
- Visual style: Matches Features section from Start Page ✓
|
||||
|
||||
This looks like the same 'Feature Card' component.
|
||||
Should I:
|
||||
1. Reference existing component (recommended)
|
||||
2. Create page-specific version
|
||||
|
||||
Your choice?"
|
||||
|
||||
Designer: "Option 1 - it's the same component."
|
||||
|
||||
Agent: "✅ Referenced: Feature Card component (defined on Start Page)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For Designers
|
||||
|
||||
1. **Be Consistent in Sketches**
|
||||
- Use same line thickness for same text types
|
||||
- Use same spacing patterns across pages
|
||||
- Helps AI recognize patterns automatically
|
||||
|
||||
2. **Confirm Pattern Matches**
|
||||
- When AI suggests pattern match, verify it's intentional
|
||||
- Speak up if variation is desired
|
||||
|
||||
3. **Build Design System Gradually**
|
||||
- First few pages establish patterns
|
||||
- Later pages reference patterns
|
||||
- Natural evolution into design system
|
||||
|
||||
### For AI Agents
|
||||
|
||||
1. **Always Check Previous Pages First**
|
||||
- Before analyzing text, look for established patterns
|
||||
- Show detected patterns to designer for transparency
|
||||
|
||||
2. **Ask, Don't Assume**
|
||||
- Even if visual match is strong, confirm with designer
|
||||
- Designer may have intentional variation
|
||||
|
||||
3. **Track Pattern Usage**
|
||||
- Note which pages use which patterns
|
||||
- Helps identify true design system components
|
||||
|
||||
---
|
||||
|
||||
## Implementation in WDS Workflow
|
||||
|
||||
### Step 1: Holistic Sketch Reading
|
||||
|
||||
```
|
||||
<action>
|
||||
1. Check if other pages in project have been analyzed
|
||||
2. Load established text style patterns
|
||||
3. Identify UI anchors in current sketch
|
||||
4. Use previous pages + UI elements to calibrate scale
|
||||
</action>
|
||||
```
|
||||
|
||||
### Step 2: Pattern Detection
|
||||
|
||||
```
|
||||
<action>
|
||||
For each text element in current sketch:
|
||||
1. Analyze visual properties (thickness, spacing, alignment)
|
||||
2. Compare to established patterns from previous pages
|
||||
3. If match found → suggest applying same specification
|
||||
4. If no match → analyze using UI anchors + relative measurements
|
||||
</action>
|
||||
```
|
||||
|
||||
### Step 3: Designer Confirmation
|
||||
|
||||
```
|
||||
<output>
|
||||
Text Element: Body paragraph in "About Us" section
|
||||
|
||||
Pattern Match: Start Page body text
|
||||
- Visual: Thin lines, icon-sized spacing ✓
|
||||
- Functional: Paragraph description ✓
|
||||
- Specification: 16px Regular
|
||||
|
||||
Apply same specification?
|
||||
</output>
|
||||
|
||||
<ask>
|
||||
1. Yes - Use 16px Regular (consistent)
|
||||
2. No - I want different styling
|
||||
</ask>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Cross-page consistency is achieved through:**
|
||||
|
||||
1. **Pattern Recognition** - AI identifies similar visual patterns across pages
|
||||
2. **Reference Anchors** - First pages establish baseline specifications
|
||||
3. **Designer Confirmation** - AI suggests matches, designer validates
|
||||
4. **Natural Design System** - Patterns emerge organically from consistent application
|
||||
|
||||
**Result:** Professional, cohesive multi-page designs with minimal specification overhead.
|
||||
@@ -0,0 +1,714 @@
|
||||
# Storyboard Integration Guide
|
||||
|
||||
**Using Visual Storyboards to Document Complex Component Functionality**
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Complex interactive components (calendars, booking systems, multi-step workflows) have **state transitions** and **interaction flows** that are difficult to describe in text alone.
|
||||
|
||||
**Storyboards** provide visual, sequential documentation of:
|
||||
|
||||
- State transitions (e.g., Empty → Booked → Active → Completed)
|
||||
- User interactions and system responses
|
||||
- Time-based changes (countdowns, timers)
|
||||
- Multi-step workflows
|
||||
|
||||
---
|
||||
|
||||
## Storyboard Types
|
||||
|
||||
### 1. **State Transition Storyboards**
|
||||
|
||||
**Purpose:** Show how a component changes states over time
|
||||
|
||||
**Example:** Dog Week Walk Booking States
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ State Transition Storyboard │
|
||||
│ Component: Walk Time Slot Card │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. WHITE (Empty) → User books │
|
||||
│ [Dog icon] 8-11 → [Book button] │
|
||||
│ │
|
||||
│ 2. GRAY (Booked) → Time arrives │
|
||||
│ [Dog+User] 8-11 │
|
||||
│ │
|
||||
│ 3. ORANGE (Countdown) → User starts │
|
||||
│ [Dog icon] 32 min left → [Start button] │
|
||||
│ │
|
||||
│ 4. BLUE (In Progress) → User completes │
|
||||
│ [Dog+User] Started 09:32 • 23 min ago │
|
||||
│ │
|
||||
│ 5. GREEN (Completed) → Final state │
|
||||
│ [Dog+User] 32 min walk ✓ │
|
||||
│ │
|
||||
│ Alt: RED (Missed) → Window expired │
|
||||
│ [Dog icon] No walk registered ⊖ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**File:** `Sketches/App-Main-Booking-States.jpg` (Dog Week example)
|
||||
|
||||
### 2. **Interaction Flow Storyboards**
|
||||
|
||||
**Purpose:** Show step-by-step user interactions
|
||||
|
||||
**Example:** Calendar Booking Flow
|
||||
|
||||
```
|
||||
Frame 1: User views calendar
|
||||
Frame 2: User taps "Book" button
|
||||
Frame 3: Card transitions to GRAY state
|
||||
Frame 4: Leaderboard updates (+1 point)
|
||||
Frame 5: Week overview quarter circle turns gray
|
||||
```
|
||||
|
||||
### 3. **Multi-Component Storyboards**
|
||||
|
||||
**Purpose:** Show how multiple components interact
|
||||
|
||||
**Example:** Week View + Leaderboard + Calendar Sync
|
||||
|
||||
```
|
||||
Frame 1: User clicks day circle in week overview
|
||||
Frame 2: Calendar scrolls to that day
|
||||
Frame 3: User books walk
|
||||
Frame 4: Week overview quarter circle updates
|
||||
Frame 5: Leaderboard count increments
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Modular Structure
|
||||
|
||||
### Where Storyboards Belong
|
||||
|
||||
| File Type | Contains Storyboard? | Purpose |
|
||||
| --------------- | --------------------- | ------------------------------------- |
|
||||
| **Pages/** | ❌ No | Page layout only |
|
||||
| **Components/** | ⚠️ Visual states only | Static appearance of each state |
|
||||
| **Features/** | ✅ YES | State transitions & interaction flows |
|
||||
|
||||
### Storyboard Storage
|
||||
|
||||
```
|
||||
project-root/
|
||||
├─ Pages/
|
||||
│ └─ 02-calendar-page.md
|
||||
│
|
||||
├─ Components/
|
||||
│ └─ walk-slot-card.component.md
|
||||
│
|
||||
├─ Features/
|
||||
│ ├─ walk-booking-logic.feature.md
|
||||
│ └─ Storyboards/ ← NEW FOLDER
|
||||
│ ├─ walk-state-transitions.jpg
|
||||
│ ├─ booking-flow.jpg
|
||||
│ └─ calendar-sync-flow.jpg
|
||||
│
|
||||
└─ Sketches/ ← Existing page sketches
|
||||
└─ 02-calendar-page-sketch.jpg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feature File with Storyboard Reference
|
||||
|
||||
### Example: `walk-booking-logic.feature.md`
|
||||
|
||||
```markdown
|
||||
# Walk Booking Logic Feature
|
||||
|
||||
**Feature ID:** `walk-booking-logic`
|
||||
**Type:** State Machine with Time-Based Transitions
|
||||
**Complexity:** High
|
||||
|
||||
## Purpose
|
||||
|
||||
Manages walk slot state transitions, user booking interactions, and automatic time-based state changes for the Dog Week calendar.
|
||||
|
||||
---
|
||||
|
||||
## Visual Storyboard
|
||||
|
||||
**State Transition Flow:**
|
||||
|
||||
|
||||
|
||||
**Key:** This storyboard shows all 6 walk states and the triggers that cause transitions between them.
|
||||
|
||||
---
|
||||
|
||||
## State Definitions
|
||||
|
||||
### State 1: WHITE (Empty / Available)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 1
|
||||
|
||||
**Appearance:**
|
||||
|
||||
- White background
|
||||
- Dog avatar only (no user avatar)
|
||||
- Time range: "8-11"
|
||||
- Action button: "Book" / "Boka"
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- Initial state for all unbooked slots
|
||||
- Appears when walk is unbooked
|
||||
|
||||
**Transitions:**
|
||||
|
||||
- User clicks "Book" → GRAY (Booked)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Any family member can book
|
||||
- Booking awards +1 leaderboard point
|
||||
- Updates week overview quarter circle to gray
|
||||
|
||||
---
|
||||
|
||||
### State 2: GRAY (Booked / Scheduled)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 2
|
||||
|
||||
**Appearance:**
|
||||
|
||||
- Gray background
|
||||
- Dog avatar + User avatar overlay
|
||||
- Names: "Rufus & Patrick"
|
||||
- Time range: "8-11"
|
||||
- No action button (tap card for details)
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- User books empty slot (WHITE → GRAY)
|
||||
- Walk is scheduled but time window not yet open
|
||||
|
||||
**Transitions:**
|
||||
|
||||
- Time window opens (8:00 arrives) → ORANGE (Countdown)
|
||||
- User unbooks walk → WHITE (Empty)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Shows who booked the walk
|
||||
- Tap card to view details/unbook
|
||||
- Leaderboard point already awarded
|
||||
|
||||
---
|
||||
|
||||
### State 3: ORANGE (Window Open / Countdown)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 3
|
||||
|
||||
**Appearance:**
|
||||
|
||||
- Orange background
|
||||
- Dog avatar only (user avatar removed)
|
||||
- Countdown timer: "32 min left" / "32 min kvar"
|
||||
- Warning icon: ⚠️
|
||||
- Action button: "Start" / "Starta"
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- Scheduled time arrives (8:00) → GRAY to ORANGE
|
||||
- Real-time countdown updates every minute
|
||||
|
||||
**Transitions:**
|
||||
|
||||
- User clicks "Start" → BLUE (In Progress)
|
||||
- Countdown reaches 0 (11:00) → RED (Missed)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Countdown shows time remaining in window
|
||||
- Urgency indicator (warning icon)
|
||||
- Can only start if no other walk active for this dog
|
||||
|
||||
---
|
||||
|
||||
### State 4: BLUE (In Progress / Active Walk)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 4
|
||||
|
||||
**Appearance:**
|
||||
|
||||
- Blue background
|
||||
- Dog avatar + User avatar overlay
|
||||
- Status: "Started 09:32 • 23 min ago"
|
||||
- Refresh icon: ↻
|
||||
- No action button (tap card for completion)
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- User starts walk (ORANGE → BLUE)
|
||||
- Real-time duration updates every minute
|
||||
|
||||
**Transitions:**
|
||||
|
||||
- User completes walk → GREEN (Completed)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Blocks other walks for this dog
|
||||
- Shows elapsed time since start
|
||||
- Tap card to complete walk or view progress
|
||||
|
||||
---
|
||||
|
||||
### State 5: GREEN (Completed)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 5
|
||||
|
||||
**Appearance:**
|
||||
|
||||
- Green background
|
||||
- Dog avatar + User avatar overlay
|
||||
- Duration: "32 min walk" / "32 min promenad"
|
||||
- Checkmark icon: ✓
|
||||
- No action button
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- User completes active walk (BLUE → GREEN)
|
||||
|
||||
**Transitions:**
|
||||
|
||||
- None (final successful state)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Permanent record of completed walk
|
||||
- Shows actual walk duration
|
||||
- Unblocks dog for next walk
|
||||
|
||||
---
|
||||
|
||||
### State 6: RED (Missed / Overdue)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 6
|
||||
|
||||
**Appearance:**
|
||||
|
||||
- Red background
|
||||
- Dog avatar only (no user avatar)
|
||||
- Message: "No walk registered" / "Ingen promenad registrerad"
|
||||
- Minus icon: ⊖
|
||||
- No action button
|
||||
|
||||
**Triggers:**
|
||||
|
||||
- Countdown expires without walk being started (ORANGE → RED)
|
||||
|
||||
**Transitions:**
|
||||
|
||||
- None (permanent accountability record)
|
||||
|
||||
**Business Rules:**
|
||||
|
||||
- Cannot be changed or deleted
|
||||
- Leaderboard point remains (no penalty)
|
||||
- Shows who booked but didn't complete
|
||||
|
||||
---
|
||||
|
||||
## Interaction Flows
|
||||
|
||||
### Flow 1: Successful Walk Booking & Completion
|
||||
|
||||
**Storyboard:** `Storyboards/booking-flow.jpg`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. **User views empty slot** (WHITE state)
|
||||
- Sees "Book" button
|
||||
2. **User taps "Book"**
|
||||
- System validates user is family member
|
||||
- System creates booking record
|
||||
3. **Immediate updates:**
|
||||
- Card → GRAY state
|
||||
- Leaderboard: User +1 point
|
||||
- Week overview: Quarter circle → gray
|
||||
4. **Time window opens** (8:00 arrives)
|
||||
- Card → ORANGE state
|
||||
- Countdown timer starts
|
||||
5. **User taps "Start"**
|
||||
- System validates no other active walk for dog
|
||||
- System records start time
|
||||
6. **Immediate updates:**
|
||||
- Card → BLUE state
|
||||
- Duration counter starts
|
||||
- Other walks for dog → disabled
|
||||
7. **User completes walk** (via Walk Details page)
|
||||
- System records completion time
|
||||
- System calculates duration
|
||||
8. **Immediate updates:**
|
||||
- Card → GREEN state
|
||||
- Week overview: Quarter circle → green
|
||||
- Other walks for dog → re-enabled
|
||||
|
||||
---
|
||||
|
||||
### Flow 2: Missed Walk
|
||||
|
||||
**Storyboard:** `Storyboards/missed-walk-flow.jpg`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Walk booked (GRAY state)
|
||||
2. Time window opens (ORANGE state)
|
||||
3. Countdown timer runs
|
||||
4. User doesn't start walk
|
||||
5. Countdown reaches 0 (11:00)
|
||||
6. **Automatic transition:** ORANGE → RED
|
||||
7. Permanent missed walk record created
|
||||
|
||||
---
|
||||
|
||||
### Flow 3: Multi-Component Sync
|
||||
|
||||
**Storyboard:** `Storyboards/calendar-sync-flow.jpg`
|
||||
|
||||
**Components Involved:**
|
||||
|
||||
- Week Overview (top section)
|
||||
- Leaderboard (middle section)
|
||||
- Booking Calendar (bottom section)
|
||||
|
||||
**Sync Flow:**
|
||||
|
||||
1. User books walk in calendar
|
||||
2. **Sync 1:** Week overview quarter circle updates
|
||||
3. **Sync 2:** Leaderboard count increments
|
||||
4. User starts walk
|
||||
5. **Sync 3:** Week overview quarter circle changes color
|
||||
6. User completes walk
|
||||
7. **Sync 4:** Week overview quarter circle turns green
|
||||
|
||||
---
|
||||
|
||||
## State Machine Diagram
|
||||
```
|
||||
|
||||
┌─────────────┐
|
||||
│ WHITE │
|
||||
│ (Empty) │
|
||||
└──────┬──────┘
|
||||
│ User books
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ GRAY │
|
||||
│ (Booked) │
|
||||
└──────┬──────┘
|
||||
│ Time arrives
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ ORANGE │◄──── Countdown timer
|
||||
│ (Countdown) │ updates every 1 min
|
||||
└──┬───────┬──┘
|
||||
│ │
|
||||
User starts │ │ Countdown expires
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────┐ ┌─────────┐
|
||||
│ BLUE │ │ RED │
|
||||
│(Active) │ │(Missed) │
|
||||
└────┬────┘ └─────────┘
|
||||
│ │
|
||||
User completes │ │ Permanent
|
||||
│ │ record
|
||||
▼ ▼
|
||||
┌─────────┐ [END]
|
||||
│ GREEN │
|
||||
│(Complete)│
|
||||
└─────────┘
|
||||
│
|
||||
▼
|
||||
[END]
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Storyboard Creation Guidelines
|
||||
|
||||
### When to Create Storyboards
|
||||
|
||||
Create storyboards for:
|
||||
- ✅ Components with 3+ states
|
||||
- ✅ Time-based transitions (countdowns, timers)
|
||||
- ✅ Multi-step user flows
|
||||
- ✅ Complex interactions between multiple components
|
||||
- ✅ State machines with branching paths
|
||||
|
||||
Don't need storyboards for:
|
||||
- ❌ Simple buttons (hover, active states)
|
||||
- ❌ Static content sections
|
||||
- ❌ Single-state components
|
||||
|
||||
### Storyboard Format
|
||||
|
||||
**Hand-drawn sketches** (recommended):
|
||||
- Quick to create
|
||||
- Easy to iterate
|
||||
- Focus on functionality, not polish
|
||||
- Example: Dog Week `App-Main-Booking-States.jpg`
|
||||
|
||||
**Digital wireframes:**
|
||||
- Use Figma, Sketch, or similar
|
||||
- More polished for client presentations
|
||||
- Easier to update
|
||||
|
||||
**Annotated screenshots:**
|
||||
- Use actual prototype screenshots
|
||||
- Add arrows and labels
|
||||
- Good for documenting existing systems
|
||||
|
||||
### Storyboard Numbering
|
||||
|
||||
Number frames sequentially:
|
||||
```
|
||||
|
||||
1. Initial state
|
||||
2. After user action
|
||||
3. System response
|
||||
4. Next state
|
||||
5. Alternative path
|
||||
|
||||
````
|
||||
|
||||
### Storyboard Annotations
|
||||
|
||||
Include:
|
||||
- **State names** (e.g., "ORANGE - Countdown")
|
||||
- **Trigger descriptions** (e.g., "User taps Start")
|
||||
- **Time indicators** (e.g., "After 32 minutes")
|
||||
- **Icons/symbols** for actions (→ for transitions, ⚠️ for warnings)
|
||||
|
||||
---
|
||||
|
||||
## Feature File Template with Storyboard
|
||||
|
||||
```markdown
|
||||
# {Feature Name} Feature
|
||||
|
||||
**Feature ID:** `{feature-id}`
|
||||
**Type:** {State Machine / Workflow / Calculator / etc.}
|
||||
**Complexity:** {Low / Medium / High}
|
||||
|
||||
## Purpose
|
||||
|
||||
{Brief description of what this feature does}
|
||||
|
||||
---
|
||||
|
||||
## Visual Storyboard
|
||||
|
||||
**{Storyboard Type}:**
|
||||
|
||||
|
||||
|
||||
**Key:** {Brief explanation of what the storyboard shows}
|
||||
|
||||
---
|
||||
|
||||
## State Definitions
|
||||
|
||||
{If applicable - for state machines}
|
||||
|
||||
### State 1: {State Name}
|
||||
|
||||
**Visual Reference:** Storyboard Frame {number}
|
||||
|
||||
**Appearance:**
|
||||
- {Visual description}
|
||||
|
||||
**Triggers:**
|
||||
- {What causes this state}
|
||||
|
||||
**Transitions:**
|
||||
- {What states this can transition to}
|
||||
|
||||
**Business Rules:**
|
||||
- {Rules governing this state}
|
||||
|
||||
---
|
||||
|
||||
## Interaction Flows
|
||||
|
||||
### Flow 1: {Flow Name}
|
||||
|
||||
**Storyboard:** `Storyboards/{flow-storyboard}.jpg`
|
||||
|
||||
**Steps:**
|
||||
1. {Step description}
|
||||
2. {Step description}
|
||||
3. {Step description}
|
||||
|
||||
---
|
||||
|
||||
## State Machine Diagram
|
||||
|
||||
{ASCII diagram showing state transitions}
|
||||
|
||||
---
|
||||
|
||||
## Data Requirements
|
||||
|
||||
{API endpoints, data models, etc.}
|
||||
|
||||
---
|
||||
|
||||
## Validation Rules
|
||||
|
||||
{Business rules, constraints, etc.}
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
{Error states, recovery flows, etc.}
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
## Dog Week Example: Complete Structure
|
||||
|
||||
```
|
||||
Features/
|
||||
├─ walk-booking-logic.feature.md
|
||||
│ ├─ References: Storyboards/walk-state-transitions.jpg
|
||||
│ ├─ Contains: 6 state definitions
|
||||
│ └─ Contains: State machine diagram
|
||||
│
|
||||
├─ calendar-sync.feature.md
|
||||
│ ├─ References: Storyboards/calendar-sync-flow.jpg
|
||||
│ └─ Contains: Multi-component interaction flows
|
||||
│
|
||||
└─ Storyboards/
|
||||
├─ walk-state-transitions.jpg ← Main state storyboard
|
||||
├─ booking-flow.jpg ← Successful booking flow
|
||||
├─ missed-walk-flow.jpg ← Missed walk scenario
|
||||
├─ calendar-sync-flow.jpg ← Component sync flow
|
||||
└─ week-navigation-flow.jpg ← Week navigation interactions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits of Storyboard Integration
|
||||
|
||||
### 1. Visual Clarity
|
||||
|
||||
**Before (Text only):**
|
||||
|
||||
```
|
||||
When the user books a walk, the card changes to gray,
|
||||
the leaderboard updates, and the week overview changes.
|
||||
```
|
||||
|
||||
**After (With storyboard):**
|
||||
|
||||
```
|
||||
See Storyboard Frame 2-3 for visual state transition.
|
||||
```
|
||||
|
||||
### 2. Developer Understanding
|
||||
|
||||
Developers can:
|
||||
|
||||
- See exact visual states
|
||||
- Understand transition triggers
|
||||
- Identify edge cases visually
|
||||
- Reference storyboard during implementation
|
||||
|
||||
### 3. Design Consistency
|
||||
|
||||
Designers can:
|
||||
|
||||
- Ensure all states are visually distinct
|
||||
- Verify state transitions make sense
|
||||
- Spot missing states or transitions
|
||||
- Create Figma components matching storyboard
|
||||
|
||||
### 4. QA Testing
|
||||
|
||||
QA can:
|
||||
|
||||
- Use storyboard as test script
|
||||
- Verify all states are implemented
|
||||
- Test all transition paths
|
||||
- Identify missing functionality
|
||||
|
||||
---
|
||||
|
||||
## Workflow Integration
|
||||
|
||||
### Step 1: Sketch Storyboard
|
||||
|
||||
During UX design phase:
|
||||
|
||||
1. Identify complex interactive components
|
||||
2. Sketch state transitions on paper/whiteboard
|
||||
3. Number frames sequentially
|
||||
4. Add annotations for triggers and transitions
|
||||
5. Take photo or scan
|
||||
|
||||
### Step 2: Store Storyboard
|
||||
|
||||
```
|
||||
Features/Storyboards/{component-name}-{type}.jpg
|
||||
```
|
||||
|
||||
### Step 3: Reference in Feature File
|
||||
|
||||
```markdown
|
||||
## Visual Storyboard
|
||||
|
||||
|
||||
```
|
||||
|
||||
### Step 4: Document States
|
||||
|
||||
For each frame in storyboard:
|
||||
|
||||
- Create state definition
|
||||
- Link to storyboard frame number
|
||||
- Describe triggers and transitions
|
||||
|
||||
### Step 5: Create State Machine
|
||||
|
||||
Convert storyboard to ASCII state machine diagram for quick reference
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Storyboards are essential for:**
|
||||
|
||||
- 🎯 Complex state machines (calendars, booking systems)
|
||||
- 🎯 Multi-step workflows (onboarding, checkout)
|
||||
- 🎯 Time-based interactions (countdowns, timers)
|
||||
- 🎯 Multi-component synchronization
|
||||
|
||||
**Store storyboards in:**
|
||||
|
||||
- `Features/Storyboards/` folder
|
||||
- Reference from Feature files
|
||||
- Link to specific frames in state definitions
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- ✅ Visual clarity for developers
|
||||
- ✅ Design consistency
|
||||
- ✅ QA test scripts
|
||||
- ✅ Stakeholder communication
|
||||
- ✅ Documentation that doesn't get stale
|
||||
|
||||
**Result:** Complex component functionality is documented visually and textually, making implementation and testing straightforward.
|
||||
@@ -0,0 +1,289 @@
|
||||
---
|
||||
name: Modular Component Architecture
|
||||
description: Reference guides for three-tier specification system (Pages, Components, Features)
|
||||
web_bundle: true
|
||||
---
|
||||
|
||||
# Modular Component Architecture
|
||||
|
||||
**Goal:** Understand and apply three-tier architecture for component specification
|
||||
|
||||
**Your Role:** Architecture reference for designing modular, maintainable component systems
|
||||
|
||||
---
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
This is a **guide collection** for three-tier modular architecture, not a step-by-step workflow.
|
||||
|
||||
**Three-Tier System:**
|
||||
- **Pages** - Full page layouts and compositions
|
||||
- **Components** - Reusable UI elements (simple and complex)
|
||||
- **Features** - Complex component decompositions
|
||||
|
||||
**Purpose:** Separate concerns, reduce duplication, enable modularity
|
||||
|
||||
---
|
||||
|
||||
## WHEN TO USE
|
||||
|
||||
**Use these guides when:**
|
||||
- ✅ Writing page specifications
|
||||
- ✅ Decomposing complex components
|
||||
- ✅ Deciding where to document content
|
||||
- ✅ Need to understand component complexity
|
||||
- ✅ Want to optimize agent-designer collaboration
|
||||
|
||||
**Skip these guides when:**
|
||||
- ❌ Building simple prototypes without specs
|
||||
- ❌ Already familiar with the architecture
|
||||
- ❌ Using different specification system
|
||||
|
||||
---
|
||||
|
||||
## THE FOUR SECTIONS
|
||||
|
||||
### 00. Foundation
|
||||
|
||||
**[Agent-Designer Collaboration](00-foundation/agent-designer-collaboration.md)**
|
||||
|
||||
How AI agents optimize designer craft without replacing designer thinking.
|
||||
|
||||
**Use when:** Understanding the philosophy behind modular architecture
|
||||
|
||||
**Topics:**
|
||||
- Designer maintains creative control
|
||||
- AI handles decomposition and optimization
|
||||
- Collaborative workflow patterns
|
||||
|
||||
---
|
||||
|
||||
### 01. Core Concepts
|
||||
|
||||
Three fundamental concepts of the architecture:
|
||||
|
||||
**[Three-Tier Overview](01-core-concepts/three-tier-overview.md)**
|
||||
- Overview of Pages, Components, and Features separation
|
||||
- When to use each tier
|
||||
- Benefits of separation
|
||||
|
||||
**[Content Placement Rules](01-core-concepts/content-placement-rules.md)**
|
||||
- Decision tree for where to document content
|
||||
- Simple vs complex component rules
|
||||
- Page-specific vs shared content
|
||||
|
||||
**[Complexity Detection](01-core-concepts/complexity-detection.md)**
|
||||
- How to identify simple vs complex components
|
||||
- When to decompose further
|
||||
- Complexity indicators
|
||||
|
||||
**Use when:** Learning the architecture or making placement decisions
|
||||
|
||||
---
|
||||
|
||||
### 02. Workflows
|
||||
|
||||
Practical workflows for applying the architecture:
|
||||
|
||||
**[Page Specification Workflow](02-workflows/page-specification-workflow.md)**
|
||||
- Step-by-step page decomposition from sketch to specs
|
||||
- Extracting components from page layouts
|
||||
- Handling page-specific content
|
||||
|
||||
**[Complexity Router Workflow](02-workflows/complexity-router-workflow.md)**
|
||||
- Guided decomposition for complex components
|
||||
- When to create feature folders
|
||||
- Substep breakdown patterns
|
||||
|
||||
**[Storyboards Guide](02-workflows/storyboards-guide.md)**
|
||||
- Using visual storyboards for complex components
|
||||
- State documentation
|
||||
- Interaction flows
|
||||
|
||||
**Use when:** Actively creating specifications
|
||||
|
||||
---
|
||||
|
||||
### 03. Quick References
|
||||
|
||||
Fast lookup guides for common questions:
|
||||
|
||||
**[Decision Tree](03-quick-refs/decision-tree.md)**
|
||||
- One-page flowchart for file placement
|
||||
- Quick decision making
|
||||
- Common scenarios
|
||||
|
||||
**[Benefits Summary](03-quick-refs/benefits.md)**
|
||||
- Why this architecture works
|
||||
- Advantages of three-tier system
|
||||
- Problem it solves
|
||||
|
||||
**Use when:** Need quick answers or reminders
|
||||
|
||||
---
|
||||
|
||||
## DETAILED NAVIGATION
|
||||
|
||||
For comprehensive navigation of all guides and substeps:
|
||||
|
||||
**[Modular Architecture Guide](00-MODULAR-ARCHITECTURE-GUIDE.md)**
|
||||
|
||||
This provides detailed index of all files including examples and substeps.
|
||||
|
||||
---
|
||||
|
||||
## QUICK START
|
||||
|
||||
### "Where do I document this component?"
|
||||
|
||||
Start here: [Content Placement Rules](01-core-concepts/content-placement-rules.md)
|
||||
|
||||
Then use: [Decision Tree](03-quick-refs/decision-tree.md)
|
||||
|
||||
---
|
||||
|
||||
### "How do I write a page specification?"
|
||||
|
||||
Start here: [Page Specification Workflow](02-workflows/page-specification-workflow.md)
|
||||
|
||||
Reference: [Three-Tier Overview](01-core-concepts/three-tier-overview.md)
|
||||
|
||||
---
|
||||
|
||||
### "When should I decompose a component?"
|
||||
|
||||
Start here: [Complexity Detection](01-core-concepts/complexity-detection.md)
|
||||
|
||||
Then use: [Complexity Router Workflow](02-workflows/complexity-router-workflow.md)
|
||||
|
||||
---
|
||||
|
||||
### "How do I document complex interactions?"
|
||||
|
||||
Start here: [Storyboards Guide](02-workflows/storyboards-guide.md)
|
||||
|
||||
Reference: [Complexity Router Workflow](02-workflows/complexity-router-workflow.md)
|
||||
|
||||
---
|
||||
|
||||
## INTEGRATION WITH WDS
|
||||
|
||||
### During Page Specification Phase
|
||||
|
||||
After sketching, before implementation:
|
||||
|
||||
1. Review page sketch
|
||||
2. Apply [Page Specification Workflow](02-workflows/page-specification-workflow.md)
|
||||
3. Use [Content Placement Rules](01-core-concepts/content-placement-rules.md) for each component
|
||||
4. Document simple components inline
|
||||
5. Create feature folders for complex components
|
||||
6. Use [Complexity Router](02-workflows/complexity-router-workflow.md) for decomposition
|
||||
|
||||
### During Prototype Implementation
|
||||
|
||||
When building from specs:
|
||||
|
||||
1. Read page specification
|
||||
2. Identify shared vs page-specific components
|
||||
3. Build modular component library
|
||||
4. Reference storyboards for complex interactions
|
||||
|
||||
---
|
||||
|
||||
## ARCHITECTURE BENEFITS
|
||||
|
||||
**For Designers:**
|
||||
- ✅ Reduced duplication
|
||||
- ✅ Clear decision framework
|
||||
- ✅ Maintain creative control
|
||||
- ✅ Better AI collaboration
|
||||
|
||||
**For Developers:**
|
||||
- ✅ Modular component structure
|
||||
- ✅ Clear implementation boundaries
|
||||
- ✅ Reusable components identified
|
||||
- ✅ Less ambiguity
|
||||
|
||||
**For Teams:**
|
||||
- ✅ Consistent specification format
|
||||
- ✅ Scalable architecture
|
||||
- ✅ Easier maintenance
|
||||
- ✅ Better handoff quality
|
||||
|
||||
---
|
||||
|
||||
## KEY PRINCIPLES
|
||||
|
||||
**1. Separation of Concerns**
|
||||
- Pages handle layout and composition
|
||||
- Components define reusable elements
|
||||
- Features decompose complex components
|
||||
|
||||
**2. DRY (Don't Repeat Yourself)**
|
||||
- Define once, reference everywhere
|
||||
- Shared components in component library
|
||||
- Page-specific variants documented inline
|
||||
|
||||
**3. Progressive Complexity**
|
||||
- Start simple
|
||||
- Decompose only when needed
|
||||
- Use complexity detection to guide decisions
|
||||
|
||||
**4. Designer Agency**
|
||||
- AI assists but doesn't replace designer thinking
|
||||
- Designer makes final placement decisions
|
||||
- Architecture enables, doesn't constrain
|
||||
|
||||
---
|
||||
|
||||
## TROUBLESHOOTING
|
||||
|
||||
### "I don't know if my component is complex enough to decompose"
|
||||
|
||||
Use: [Complexity Detection](01-core-concepts/complexity-detection.md)
|
||||
|
||||
Look for: Multiple states, conditional logic, nested interactions
|
||||
|
||||
### "I'm not sure where to document this content"
|
||||
|
||||
Use: [Decision Tree](03-quick-refs/decision-tree.md)
|
||||
|
||||
Ask: Is it page-specific or shared? Simple or complex?
|
||||
|
||||
### "The page specification feels too long"
|
||||
|
||||
Use: [Complexity Router Workflow](02-workflows/complexity-router-workflow.md)
|
||||
|
||||
Extract complex components to feature folders
|
||||
|
||||
---
|
||||
|
||||
## EXAMPLES
|
||||
|
||||
Throughout the guides, you'll find examples:
|
||||
|
||||
- **Simple Button** - Single file documentation
|
||||
- **Complex Calendar** - Three-tier decomposition
|
||||
- **Search Bar** - Page-specific content handling
|
||||
|
||||
These demonstrate the architecture in practice.
|
||||
|
||||
---
|
||||
|
||||
## NOTES
|
||||
|
||||
**This is architecture guidance** - not mandatory workflow steps.
|
||||
|
||||
Apply as needed based on:
|
||||
- Project complexity
|
||||
- Team size
|
||||
- Specification requirements
|
||||
- Development process
|
||||
|
||||
The architecture scales from small to large projects.
|
||||
|
||||
**Start simple, add structure when needed.**
|
||||
|
||||
---
|
||||
|
||||
_Modular Component Architecture - Clear structure, better collaboration_
|
||||
Reference in New Issue
Block a user