whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/agentic-development/steps-c/3-logical-view-breakdown.md

@@ -0,0 +1,197 @@
+# Phase 3: Logical View Selection & Section Breakdown
+
+**Purpose**: Select a logical view to build and break it into implementable sections
+
+**Note**: This creates the work plan, but NOT the story files yet (those are created just-in-time)
+
+---
+
+## When to Use This Phase
+
+- ✅ Logical view mapping complete (Phase 2)
+- ✅ User has selected which logical view to build
+
+---
+
+## Step 1: Confirm Logical View Selection
+
+**User says**: "Let's build [Logical View Name]" or selects from list
+
+**Your response**:
+> "**Building Logical View: [View Name]**
+>
+> This view is used by: [List scenario steps]
+>
+> Let me analyze all specifications for this view..."
+
+---
+
+## Step 2: Gather All Specifications
+
+**Actions**:
+
+1. **Read all scenario step specs** that use this logical view
+2. **Extract all Object IDs** across all states
+3. **Identify unique objects** vs **state-specific objects**
+4. **Note functional requirements** from all specs
+
+**Your response**:
+> "**Objects identified across all states:**
+>
+> **Shared across all states** ([N] objects):
+> - [Object ID] [Description]
+> - [Object ID] [Description]
+> ...
+>
+> **State-specific** ([N] objects):
+> - [Object ID] [Description] (only in [state])
+> - [Object ID] [Description] (only in [state])
+> ...
+>
+> **Total**: [N] unique objects
+>
+> **Does this match your expectations?** (Y/N)"
+
+---
+
+## Step 3: User Confirms Objects
+
+**Wait for response**
+
+**If user says "N"**:
+- Ask what's missing or should be removed
+- Update object list
+- Re-present
+
+**If user says "Y"**: Continue to section breakdown
+
+---
+
+## Step 4: Propose Section Breakdown
+
+**Actions**:
+
+1. **Group objects logically** into 4-8 sections
+2. **Consider all states** when grouping
+3. **Estimate time** per section
+
+**Your response**:
+> "**Proposed Section Breakdown:**
+>
+> **Section 1: [Section Name]** (~X min)
+> - Objects: [Object IDs]
+> - States covered: [All / Specific states]
+>
+> **Section 2: [Section Name]** (~X min)
+> - Objects: [Object IDs]
+> - States covered: [All / Specific states]
+>
+> **Section 3: [Section Name]** (~X min)
+> - Objects: [Object IDs]
+> - States covered: [All / Specific states]
+>
+> ...
+>
+> **Total**: [N] sections, ~[X] hours
+>
+> **Approve this breakdown?** (Y/N)"
+
+---
+
+## Step 5: User Reviews Section Breakdown
+
+**Wait for response**
+
+**If user says "N"**:
+- Ask what needs adjustment
+- Revise section breakdown
+- Re-present
+
+---
+
+## Step 6: Create Work File
+
+**When user approves**:
+
+**Actions**:
+
+Create `work/[View-Name]-Work.yaml` with:
+
+```yaml
+logical_view: "[View Name]"
+html_file: "[file-name].html"
+scenario_steps:
+  - step: "1.5"
+    state: "Creator only"
+  - step: "1.7"
+    state: "With dog"
+  - step: "1.9"
+    state: "With dog + member"
+
+sections:
+  - id: 1
+    name: "[Section Name]"
+    objects:
+      - "[object-id]"
+      - "[object-id]"
+    states: "all"
+    estimated_time: "X min"
+    status: "pending"
+    
+  - id: 2
+    name: "[Section Name]"
+    objects:
+      - "[object-id]"
+    states: "1.7, 1.9 only"
+    estimated_time: "X min"
+    status: "pending"
+
+total_sections: N
+total_estimated_time: "X hours"
+created: "[date]"
+status: "ready_to_build"
+```
+
+**Your response**:
+> "✅ Work File created: `work/[View-Name]-Work.yaml`
+>
+> **Build plan complete!**
+>
+> **Next**: We'll build section-by-section. For each section:
+> 1. Create focused story file
+> 2. Implement section
+> 3. You test & approve
+> 4. Move to next section
+>
+> **Ready to start Section 1?** (Y)"
+
+---
+
+## Next Phase
+
+**Go to**: `4-section-story-and-implementation.md` when user says "Y"
+
+---
+
+## 📝 **Example: Dog Family Overview**
+
+**Section Breakdown:**
+
+**Section 1: Header & Family Info** (~15 min)
+- Objects: `family-picture`, `family-dropdown`, `family-description`, `edit-btn`
+- States: All states
+
+**Section 2: Dogs Section** (~20 min)
+- Objects: `dogs-section-header`, `dog-card`, `add-dog-btn`, `dog-menu`
+- States: Empty (1.5), With dog (1.7, 1.9)
+
+**Section 3: Members Section** (~20 min)
+- Objects: `members-section-header`, `member-card`, `add-member-btn`, `pending-badge`
+- States: Creator only (1.5, 1.7), With pending member (1.9)
+
+**Section 4: Bottom Navigation** (~10 min)
+- Objects: `bottom-nav`, `nav-items` × 5
+- States: All states
+
+**Total**: 4 sections, ~65 min
+

package/src/workflows/4-ux-design/agentic-development/steps-c/4a-announce-and-gather.md

@@ -0,0 +1,69 @@
+# Phase 4a: Announce Section & Gather Requirements
+
+**Purpose**: Announce which section we're building and gather all requirements from specifications
+
+**Task**: Prepare to create the story file by collecting all necessary information
+
+---
+
+## When to Use This Phase
+
+- ✅ Work file created (Phase 3 complete)
+- ✅ Ready to build next section
+- ✅ Previous section approved (or this is Section 1)
+
+---
+
+## Step 1: Announce Section
+
+**Your response**:
+> "**━━━ Section [N] of [Total]: [Section Name] ━━━**
+>
+> **What I'll build**:
+> - [Feature 1]
+> - [Feature 2]
+> - [Feature 3]
+>
+> **Objects**: [List Object IDs]
+> **States**: [Which states this section covers]
+> **Estimated time**: ~[X] min
+>
+> Let me gather all requirements from the specifications..."
+
+---
+
+## Step 2: Read Relevant Specifications
+
+**Actions**:
+
+1. Open work file: `work/[View]-Work.yaml`
+2. Find Section [N] details
+3. Read all scenario step specifications that need this section
+4. For each spec, extract:
+   - Object IDs for this section
+   - Object descriptions (type, label, behavior)
+   - State-specific behavior
+   - Functional requirements
+   - Design references
+
+---
+
+## Step 3: Gather Requirements Summary
+
+**Your response**:
+> "**Requirements gathered for Section [N]:**
+>
+> **Objects to implement**: [N]
+> **Specifications referenced**: [List steps]
+> **States to handle**: [List states]
+> **Functions needed**: [N]
+> **Design tokens**: [Colors, spacing, etc.]
+>
+> Ready to create the story file..."
+
+---
+
+## Next Phase
+
+**Go to**: `4b-create-story-file.md`
+

package/src/workflows/4-ux-design/agentic-development/steps-c/4b-create-story-file.md

@@ -0,0 +1,144 @@
+# Phase 4b: Create Story File
+
+**Purpose**: Create the focused story file for this section with all implementation details
+
+**Task**: Use story template to create complete, clear instructions for implementation
+
+---
+
+## When to Use This Phase
+
+- ✅ Requirements gathered (Phase 4a complete)
+
+---
+
+## Step 1: Create Story File
+
+**Actions**:
+
+Create `stories/[View].[N]-[section-name].md` using this structure:
+
+```markdown
+# [View Name] - Section [N]: [Section Name]
+
+**Status**: 🔨 In Progress
+**Estimated Time**: ~X min
+**Created**: [Date]
+
+## Purpose
+
+[Why this section exists, what it accomplishes]
+
+## Specifications Reference
+
+**Source specs**:
+- [Step] [Step Name] - [Relevant sections]
+- [Step] [Step Name] - [Relevant sections]
+
+## Objects in This Section
+
+### [Object ID]
+- **Type**: [Button / Input / Card / etc.]
+- **Label/Content**: [Text or description]
+- **Behavior**: [What it does]
+- **States**: [Which states show/hide/modify this]
+- **Spec reference**: [Step].[Section]
+
+[... repeat for each object]
+
+## HTML Structure to Build
+
+```html
+<div data-object-id="section-container" class="[tailwind-classes]">
+  <!-- Section content -->
+</div>
+```
+
+## Tailwind Classes to Use
+
+**Container**: `[classes]`
+**Elements**: `[classes]`
+**States**: `[classes for different states]`
+
+## JavaScript Requirements
+
+**Functions needed**:
+```javascript
+function [functionName]() {
+  // [What it does]
+}
+```
+
+**State handling**:
+```javascript
+if (state === '[state-name]') {
+  // Show/hide/modify elements
+}
+```
+
+## Demo Data Requirements
+
+**Data needed**: `data/demo-data.json` → `[path.to.data]`
+
+## Acceptance Criteria
+
+- [ ] All objects visible and positioned correctly
+- [ ] All Object IDs present
+- [ ] Responsive at 375px
+- [ ] State handling works
+- [ ] Console shows logs
+- [ ] Matches spec
+
+## Test Instructions
+
+1. Open `[View].html`
+2. [Action] → Expected: [Result]
+3. [Action] → Expected: [Result]
+4. Console shows: "[Expected log]"
+5. Test at 375px
+
+## Notes
+
+[Important considerations for implementation]
+```
+
+---
+
+## Step 2: Present Story to User
+
+**Your response**:
+> "✅ Story file created: `stories/[View].[N]-[section-name].md`
+>
+> **Summary**:
+> - Objects: [N] objects defined
+> - Functions: [N] JavaScript functions needed
+> - States: [List which states this section handles]
+> - Estimated time: ~[X] min
+>
+> This story has everything needed to implement this section correctly.
+>
+> **Would you like to**:
+> - Review the story first? (I'll show you the key parts)
+> - Trust the plan and start implementing? (faster)
+>
+> **Your choice?** (review/implement)"
+
+---
+
+## Step 3: Handle User Response
+
+**If user says "review"**:
+- Show key sections of the story file
+- Answer any questions
+- Make adjustments if needed
+- Ask: "Ready to implement now? (Y)"
+
+**If user says "implement"** or "Y":
+> "Perfect! Moving to implementation..."
+
+---
+
+## Next Phase
+
+**Go to**: `4c-implement-section.md`
+

package/src/workflows/4-ux-design/agentic-development/steps-c/4c-implement-section.md

@@ -0,0 +1,113 @@
+# Phase 4c: Implement Section
+
+**Purpose**: Implement the section following the story file precisely
+
+**Task**: Linear code generation - AI's strength!
+
+---
+
+## When to Use This Phase
+
+- ✅ Story file created (Phase 4b complete)
+- ✅ User approved story (or chose to proceed)
+
+---
+
+## Step 1: Begin Implementation
+
+**Your response**:
+> "📝 **Implementing Section [N]: [Section Name]**
+>
+> Following the story file instructions..."
+
+---
+
+## Step 2: Create or Update HTML File
+
+**Actions**:
+
+**For Section 1 ONLY**: 
+- Create new HTML file from `templates/page-template.html`
+- Name it: `[View].html`
+- Place in prototype root folder
+
+**For Sections 2+**:
+- Open existing `[View].html` file
+- Find insertion point (after previous section or before placeholder)
+
+---
+
+## Step 3: Add HTML Structure
+
+**Follow story file precisely**:
+
+1. Add HTML structure with Tailwind classes from story
+2. Add all Object IDs on interactive elements
+3. Add state-specific classes/attributes
+4. Add placeholder content where specified
+
+**Console logging**:
+```
+📝 Implementing Section [N]: [Section Name]
+✅ Added HTML structure
+✅ Added object: [object-id]
+✅ Added object: [object-id]
+```
+
+---
+
+## Step 4: Add JavaScript
+
+**If section needs JavaScript**:
+
+1. Add functions specified in story file
+2. Add event listeners for interactive elements
+3. Add state handling logic
+4. Add console logging for debugging
+5. Load demo data from `data/demo-data.json`
+
+**Console logging**:
+```
+✅ Added JavaScript function: [function-name]
+✅ Added state handling for: [states]
+```
+
+---
+
+## Step 5: Add Placeholder for Remaining Sections
+
+**If more sections remain**:
+
+Add at the bottom of the HTML:
+
+```html
+<!-- 🚧 Coming Next: Section [N+1] -->
+<div class="p-8 text-center text-gray-400 border-2 border-dashed border-gray-300 rounded-lg">
+  <p class="text-lg">🚧 Section [N+1]: [Section Name]</p>
+  <p class="text-sm">Coming next in development...</p>
+</div>
+```
+
+---
+
+## Step 6: Final Check
+
+**Before presenting to user, verify**:
+- [ ] All Object IDs from story file are present
+- [ ] Tailwind classes match story file
+- [ ] JavaScript functions implemented
+- [ ] Console logging added
+- [ ] Code is clean and readable
+- [ ] No syntax errors
+
+**Console logging**:
+```
+✅ Section [N] implementation complete!
+```
+
+---
+
+## Next Phase
+
+**Go to**: `4d-present-for-testing.md`
+

package/src/workflows/4-ux-design/agentic-development/steps-c/4d-present-for-testing.md

@@ -0,0 +1,68 @@
+# Phase 4d: Present Section for Testing
+
+**Purpose**: Present the implemented section to user with clear test instructions
+
+**Task**: Help user test the section effectively
+
+---
+
+## When to Use This Phase
+
+- ✅ Section implemented (Phase 4c complete)
+
+---
+
+## Step 1: Present Implementation
+
+**Your response**:
+> "✅ **Section [N] Implemented!**
+>
+> **What's new**:
+> - ✅ [Feature 1] (Object ID: `[id]`)
+> - ✅ [Feature 2] (Object ID: `[id]`)
+> - ✅ [Feature 3] (Object ID: `[id]`)
+>
+> **Files updated**:
+> - `[View].html` ([N] new objects added)
+> - Story file documents this section"
+
+---
+
+## Step 2: Provide Test Instructions
+
+**Your response**:
+> "**Test Instructions**:
+>
+> 1. **Open** `[View].html` in browser
+> 2. **Action**: [Specific action] → You should see: [Expected result]
+> 3. **Action**: [Specific action] → You should see: [Expected result]
+> 4. **Check console** → Should show: "[Expected log message]"
+> 5. **Test mobile**: Resize to 375px → Check: [Responsive behavior]"
+
+**If section handles states**:
+> "**State testing**:
+> - [Action to trigger State 1] → Expected: [Result]
+> - [Action to trigger State 2] → Expected: [Result]"
+
+**Your response**:
+> "**Working as expected? Any issues or improvements?**"
+
+---
+
+## Step 3: Wait for User Feedback
+
+**User will respond with one of**:
+- ✅ "Looks good!" / "Approved" / "Y" / "Perfect!"
+- ⚠️ Issue: "The button doesn't..." / "I see a problem with..."
+- 💡 Improvement: "Could we make it..." / "What if we..."
+
+---
+
+## Next Phase
+
+**If user approves**: Go to `4g-section-approved.md`
+
+**If user reports issue**: Go to `4e-handle-issue.md`
+
+**If user suggests improvement**: Go to `4f-handle-improvement.md`
+

package/src/workflows/4-ux-design/agentic-development/steps-c/4e-handle-issue.md

@@ -0,0 +1,85 @@
+# Phase 4e: Handle Issue
+
+**Purpose**: Fix reported issues in the section
+
+**Task**: Identify, fix, document, and re-test
+
+---
+
+## When to Use This Phase
+
+- ✅ User reported an issue with the implemented section
+
+---
+
+## Step 1: Acknowledge Issue
+
+**Your response**:
+> "I see the issue with [specific problem].
+>
+> **Analysis**: [Why it's happening]
+> **Fix**: [What needs to change]
+>
+> Let me fix that now..."
+
+---
+
+## Step 2: Fix the Issue
+
+**Actions**:
+
+1. Identify the root cause
+2. Make the specific fix in the code
+3. Test the fix mentally (does it solve the problem?)
+4. Keep the fix focused and local
+
+**Console logging**:
+```
+🔧 Fixing issue: [description]
+✅ Fixed: [what was changed]
+```
+
+---
+
+## Step 3: Update Story File with Learning
+
+**Add to story file** `stories/[View].[N]-[section-name].md`:
+
+```markdown
+## Changes Made
+
+**[Date]**: Fixed [issue]
+- **Problem**: [What was wrong]
+- **Root cause**: [Why it happened]
+- **Solution**: [What was changed]
+- **Code change**: [Specific change made]
+- **Learned**: [What to do differently next time]
+```
+
+---
+
+## Step 4: Re-present for Testing
+
+**Your response**:
+> "✅ **Issue fixed!**
+>
+> **What changed**:
+> - [Specific change made]
+>
+> **Why it works now**:
+> - [Explanation of fix]
+>
+> Please test again:
+> 1. [Specific test for the fix]
+> 2. [General retest]
+>
+> **Working correctly now?**"
+
+---
+
+## Next Phase
+
+**Loop**: Go back to `4d-present-for-testing.md` (user tests again)
+
+**Note**: This may loop multiple times until issue is resolved
+