initial commit

_bmad/wds/workflows/4-ux-design/data/modular-architecture/03-quick-refs/benefits.md

@@ -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

_bmad/wds/workflows/4-ux-design/data/modular-architecture/03-quick-refs/decision-tree.md

@@ -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)