chore: initial monorepo scaffold + WDS Phase 1+2 artifacts
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user