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>
2026-05-27 14:34:20 +00:00
commit 17c08e6392
3631 changed files with 855518 additions and 0 deletions
--- a/.agents/skills/wds-4-ux-design/data/modular-architecture/01-core-concepts/complexity-detection.md
+++ b/.agents/skills/wds-4-ux-design/data/modular-architecture/01-core-concepts/complexity-detection.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
--- a/.agents/skills/wds-4-ux-design/data/modular-architecture/01-core-concepts/content-placement-rules.md
+++ b/.agents/skills/wds-4-ux-design/data/modular-architecture/01-core-concepts/content-placement-rules.md
@@ -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)
--- a/.agents/skills/wds-4-ux-design/data/modular-architecture/01-core-concepts/three-tier-overview.md
+++ b/.agents/skills/wds-4-ux-design/data/modular-architecture/01-core-concepts/three-tier-overview.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?