whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/CONTENT-PLACEMENT-GUIDE.md

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