whiteport-design-studio 0.1.0

package/src/data/agent-guides/saga/trigger-mapping.md

@@ -0,0 +1,403 @@
+# Saga's Trigger Mapping Guide
+
+**When to load:** During Phase 2 (Trigger Mapping) or when analyzing user psychology
+
+---
+
+## Core Principle
+
+**Connect business goals to user psychology through Trigger Mapping.**
+
+Discover not just WHO your users are, but WHY they act and WHAT triggers their decisions.
+
+---
+
+## What is Trigger Mapping?
+
+**Trigger Mapping is WDS's adaptation of Impact/Effect Mapping** that focuses on user psychology.
+
+**Key differences from generic Impact Mapping:**
+- ✅ Removes solutions from the map (solutions designed *against* map, not *on* it)
+- ✅ Adds negative driving forces (fears, frustrations) alongside positive ones
+- ✅ Focuses on smaller, targeted maps (3-4 user groups max)
+- ✅ Integrates explicit prioritization for driving forces
+
+**Result:** Longer shelf life, deeper psychology, clearer focus.
+
+---
+
+## The Trigger Map Structure
+
+**Visual Flow (Left to Right):**
+
+```
+Business Goals → Product/Solution → Target Groups → Usage Goals
+(Vision +          (What you're      (Who uses it)    (Positive Drivers)
+ SMART              building)                          (Negative Drivers)
+ Objectives)
+```
+
+**Four-Layer Architecture:**
+
+1. **Business Goals** (Left)
+   - Vision statement(s) - inspirational direction
+   - SMART objectives - measurable targets
+   - Multiple goals can feed into the product
+
+2. **Product/Solution** (Center)
+   - Product name and description
+   - What the product does
+   - Central hub connecting goals to users
+
+3. **Target Groups** (Middle-Right)
+   - Prioritized personas (Primary 👥, Secondary 👤, etc.)
+   - Connected to the product
+   - Detailed psychological profiles
+
+4. **Usage Goals** (Right)
+   - **Positive Drivers** (✅ green) - What they want to achieve
+   - **Negative Drivers** (❌ red) - What they want to avoid
+   - Separated into distinct groups per target group
+   - Both types are equally important for design decisions
+
+---
+
+## Business Goals Layer
+
+### Vision Goals (Directional)
+**"Where are we going?"**
+
+- Build the most trusted proposal platform
+- Become the industry standard for consultants
+- Revolutionize how professionals communicate value
+
+**Characteristics:**
+- Inspirational, not measurable
+- Provides direction and purpose
+- Guides strategic decisions
+
+---
+
+### SMART Goals (Measurable)
+**"How do we know we're making progress?"**
+
+- 1,000 registered users in 12 months
+- 500 premium signups in 18 months  
+- $50K MRR by end of year 2
+- 80% activation rate (signup → first proposal)
+
+**Characteristics:**
+- Specific, Measurable, Achievable, Relevant, Time-bound
+- Can be tracked objectively
+- Tied to business success
+
+---
+
+## Target Groups Layer
+
+**Connect each target group to specific business goals they serve.**
+
+### Example
+```
+Business Goal: 1,000 registered users
+    ↓
+Target Groups:
+├── Independent consultants (high volume)
+├── Small consulting firms (medium volume)
+└── Freelance designers (adjacent market)
+```
+
+**Why connect:** Shows which users matter most for which goals.
+
+---
+
+## Detailed Personas
+
+**Go beyond demographics → psychological depth**
+
+### Wrong (Shallow)
+> "Sarah, 35, consultant, lives in London"
+
+**Why bad:** Doesn't help design decisions
+
+---
+
+### Right (Deep)
+> **Harriet the Hairdresser**
+> 
+> Owns a salon, 15 years experience, ambitious. Wants to be seen as the "queen of beauty" in her town - not just another hairdresser, but THE expert everyone comes to. Fears falling behind competitors who have better online presence. Frustrated by not knowing how to market herself effectively. In her salon context, she's confident. In the digital marketing context, she feels like a beginner.
+
+**Why better:** You can design for her psychology
+
+---
+
+## Usage Goals vs User Goals
+
+**Critical distinction:**
+
+### User Goals (Life Context)
+What they want in general life:
+- Be a successful consultant
+- Provide for family
+- Be respected in industry
+
+---
+
+### Usage Goals (Product Context)
+What they want when using your product:
+- Feel prepared for client meeting
+- Look professional to prospects
+- Save time on formatting
+
+**Design for usage goals, informed by user goals.**
+
+---
+
+## Context-Dependent Goals
+
+**The Dubai Golf Course Example:**
+
+A golfer using a booking form has specific **usage goals** in that moment:
+- Book a tee time quickly
+- See availability clearly
+- Feel confident about the booking
+
+What they do at the resort restaurant later is a **different context** with different usage goals. Don't conflate them!
+
+**The Harriet Example:**
+
+When booking beauty product supplier:
+- **Active goal:** "Compare prices efficiently"
+- **Not active:** "Feel like queen of beauty" (that's in salon context)
+
+When marketing her salon online:
+- **Active goal:** "Feel like queen of beauty"
+- **Not active:** "Compare supplier prices" (different context)
+
+**Design for the active goals in THIS usage context.**
+
+---
+
+## Driving Forces (The Psychology)
+
+### Positive Driving Forces (Wishes/Desires)
+**What pulls them forward?**
+
+- Want to feel prepared
+- Want to look professional
+- Want to impress clients
+- Want to save time
+- Want to be seen as expert
+
+**Trigger these** through your design and content.
+
+---
+
+### Negative Driving Forces (Fears/Frustrations)
+**What pushes them away from current state?**
+
+- Fear looking unprofessional
+- Fear losing clients to competitors
+- Frustrated by wasted time on formatting
+- Anxious about making mistakes
+- Worried about missing deadlines
+
+**Address these** through reassurance and solutions.
+
+---
+
+### The Power of Both
+
+**Same goal, different messaging:**
+
+- Positive framing: "Feel confident and prepared"
+- Negative framing: "Stop worrying about embarrassing mistakes"
+
+Both are valid! Often negative triggers action faster (pain > pleasure).
+
+---
+
+## Feature Impact Analysis
+
+**Once map is complete, prioritize driving forces:**
+
+### Scoring System (1-5 scale)
+- **Frequency:** How often does this trigger matter?
+- **Intensity:** How strongly do they feel this?
+- **Fit:** How well can our solution address this?
+
+**Example:**
+```
+"Want to look professional to clients"
+├── Frequency: 5 (every proposal)
+├── Intensity: 5 (critical to business)
+├── Fit: 5 (we solve this directly)
+└── Score: 15/15 (HIGH PRIORITY)
+
+"Want to collaborate with team members"
+├── Frequency: 2 (solo consultants rarely need this)
+├── Intensity: 3 (nice to have)
+├── Fit: 3 (requires complex features)
+└── Score: 8/15 (LOWER PRIORITY)
+```
+
+**Use scores to prioritize features and design decisions.**
+
+---
+
+## Customer Awareness Integration
+
+**Every scenario should move users through awareness stages:**
+
+```
+Trigger Map shows:
+└── User + Driving Forces
+
+Scenario adds:
+├── Starting Awareness: Problem Aware (knows proposals are weak)
+└── Target Awareness: Product Aware (knows our solution helps)
+```
+
+**Example:**
+- **Start:** "I know my proposals lose clients" (Problem Aware)
+- **Through scenario:** Experience our solution working
+- **End:** "This tool makes my proposals professional" (Product Aware)
+
+---
+
+## Common Trigger Mapping Mistakes
+
+### ❌ Too Many Target Groups
+"Let's map 10 different user types..."
+
+**Why bad:** Dilutes focus, overwhelming, unused
+
+**Instead:** 3-4 groups max, deeply understood
+
+---
+
+### ❌ Shallow Personas
+"John, 32, works in consulting..."
+
+**Why bad:** Doesn't inform design
+
+**Instead:** Deep psychology, usage context, active goals
+
+---
+
+### ❌ Only Positive Forces
+"Users want to save time and be efficient..."
+
+**Why bad:** Missing powerful negative triggers
+
+**Instead:** Positive AND negative (fears drive action!)
+
+---
+
+### ❌ Solutions on the Map
+"They need a template library and e-signature..."
+
+**Why bad:** Locks in solutions too early, map ages quickly
+
+**Instead:** Map psychology, design solutions against it
+
+---
+
+### ❌ Generic Goals
+"Want a better experience..."
+
+**Why bad:** Too vague to design for
+
+**Instead:** Specific, contextual: "Want to feel prepared before client meeting"
+
+---
+
+## Trigger Map → VTC Connection
+
+**VTC is extracted from Trigger Map:**
+
+```
+Trigger Map (Comprehensive):
+├── 3 business goals
+├── 4 target groups
+├── 12 detailed personas
+└── 40+ driving forces
+
+VTC (Focused):
+├── 1 business goal
+├── 1 user/persona
+├── 1 solution context
+└── 3-5 key driving forces
+```
+
+**VTC is the "working copy" for a specific design task.**
+
+---
+
+## Visual Mermaid Diagrams
+
+**Create visual trigger maps using Mermaid syntax:**
+
+```mermaid
+graph TD
+    BG1[1000 Users] --> TG1[Independent Consultants]
+    BG1 --> TG2[Small Firms]
+    
+    TG1 --> P1[Harriet - Solo Consultant]
+    
+    P1 --> DF1[+ Feel professional]
+    P1 --> DF2[+ Save time]
+    P1 --> DF3[- Fear losing clients]
+    P1 --> DF4[- Frustrated by formatting]
+```
+
+**See:** `../../workflows/2-trigger-mapping/mermaid-diagram/`
+
+---
+
+## Workshop Process
+
+**Trigger Mapping is collaborative:**
+
+1. **Define business goals** (Vision + SMART)
+2. **Identify target groups** (connect to goals)
+3. **Create personas** (psychological depth)
+4. **Discover driving forces** (positive + negative)
+5. **Prioritize forces** (Feature Impact Analysis)
+6. **Generate visual map** (Mermaid diagram)
+7. **Document findings** (structured markdown)
+
+**See:** `../../workflows/2-trigger-mapping/workshops/`
+
+---
+
+## When to Update Trigger Map
+
+**Trigger Maps evolve:**
+
+- ✅ New user research reveals different psychology
+- ✅ Business goals change
+- ✅ New target groups emerge
+- ✅ Priorities shift based on data
+
+**Process:**
+1. Create new version (v2)
+2. Document what changed and why
+3. Update any VTCs derived from map
+4. Keep old version for reference
+
+---
+
+## Related Resources
+
+- **Phase 2 Workflow:** `../../workflows/2-trigger-mapping/`
+- **Impact/Effect Mapping Model:** `../../docs/models/impact-effect-mapping.md`
+- **VTC Guide:** `../../docs/method/value-trigger-chain-guide.md`
+- **Customer Awareness Cycle:** `../../docs/models/customer-awareness-cycle.md`
+- **Feature Impact Analysis:** Prioritization method based on Impact Mapping
+
+---
+
+*Trigger Mapping connects business goals to user psychology. It's the strategic foundation that makes design purposeful.*
+
+

package/src/data/design-system/component-boundaries.md

@@ -0,0 +1,318 @@
+# Component Boundaries
+
+**Purpose:** Guidelines for determining what constitutes a component.
+
+**Referenced by:** Design system router, assessment flow
+
+---
+
+## The Core Question
+
+**"Is this one component or multiple components?"**
+
+This is the most common design system challenge.
+
+---
+
+## Guiding Principles
+
+### Principle 1: Single Responsibility
+
+**A component should do one thing well.**
+
+✅ **Good:** Button component triggers actions
+❌ **Bad:** Button component that also handles forms, navigation, and modals
+
+### Principle 2: Reusability
+
+**A component should be reusable across contexts.**
+
+✅ **Good:** Input Field used in login, signup, profile forms
+❌ **Bad:** Login-Specific Input Field that only works on login page
+
+### Principle 3: Independence
+
+**A component should work independently.**
+
+✅ **Good:** Card component that can contain any content
+❌ **Bad:** Card component that requires specific parent container
+
+---
+
+## Common Boundary Questions
+
+### Q1: Icon in Button
+
+**Question:** Is the icon part of the button or separate?
+
+**Answer:** Depends on usage:
+
+**Part of Button (Variant):**
+
+```yaml
+Button Component:
+  variants:
+    - with-icon-left
+    - with-icon-right
+    - icon-only
+```
+
+**When:** Icon is always the same type (e.g., always arrow for navigation)
+
+**Separate Components:**
+
+```yaml
+Button Component: (text only)
+Icon Component: (standalone)
+Composition: Button + Icon
+```
+
+**When:** Icons vary widely, button can exist without icon
+
+**Recommendation:** Start with variant, split if complexity grows.
+
+---
+
+### Q2: Label with Input
+
+**Question:** Is the label part of the input or separate?
+
+**Answer:** Usually part of Input Field component:
+
+```yaml
+Input Field Component:
+  includes:
+    - Label
+    - Input element
+    - Helper text
+    - Error message
+```
+
+**Reason:** These always appear together in forms, form a semantic unit.
+
+---
+
+### Q3: Card with Button
+
+**Question:** Is the button part of the card?
+
+**Answer:** Usually separate:
+
+```yaml
+Card Component: (container)
+Button Component: (action)
+Composition: Card contains Button
+```
+
+**Reason:** Card is a container, button is an action. Different purposes.
+
+---
+
+### Q4: Navigation Bar Items
+
+**Question:** Is each nav item a component?
+
+**Answer:** Depends on complexity:
+
+**Simple (Single Component):**
+
+```yaml
+Navigation Bar Component:
+  includes: All nav items as configuration
+```
+
+**Complex (Composition):**
+
+```yaml
+Navigation Bar: (container)
+Navigation Item: (individual item)
+Composition: Nav Bar contains Nav Items
+```
+
+**Threshold:** If nav items have complex individual behavior, split them.
+
+---
+
+## Decision Framework
+
+### Step 1: Ask These Questions
+
+1. **Can it exist independently?**
+   - Yes → Probably separate component
+   - No → Probably part of parent
+
+2. **Does it have its own states/behaviors?**
+   - Yes → Probably separate component
+   - No → Probably part of parent
+
+3. **Is it reused in different contexts?**
+   - Yes → Definitely separate component
+   - No → Could be part of parent
+
+4. **Does it have a clear single purpose?**
+   - Yes → Good component candidate
+   - No → Might need to split further
+
+### Step 2: Consider Complexity
+
+**Low Complexity:** Keep together
+
+- Icon in button
+- Label with input
+- Simple list items
+
+**High Complexity:** Split apart
+
+- Complex nested structures
+- Independent behaviors
+- Different lifecycle
+
+### Step 3: Think About Maintenance
+
+**Together:**
+
+- ✅ Easier to keep consistent
+- ❌ Component becomes complex
+
+**Apart:**
+
+- ✅ Simpler components
+- ❌ More components to manage
+
+---
+
+## Composition Patterns
+
+### Pattern 1: Container + Content
+
+**Container provides structure, content is flexible.**
+
+```yaml
+Card Component: (container)
+  - Can contain: text, images, buttons, etc.
+  - Provides: padding, border, shadow
+```
+
+### Pattern 2: Compound Component
+
+**Multiple parts that work together.**
+
+```yaml
+Accordion Component:
+  - Accordion Container
+  - Accordion Item
+  - Accordion Header
+  - Accordion Content
+```
+
+### Pattern 3: Atomic Component
+
+**Single, indivisible unit.**
+
+```yaml
+Button Component:
+  - Cannot be broken down further
+  - Self-contained
+```
+
+---
+
+## Red Flags
+
+### Too Many Variants
+
+**Warning:** Component has 10+ variants
+
+**Problem:** Probably multiple components disguised as variants
+
+**Solution:** Split into separate components based on purpose
+
+### Conditional Complexity
+
+**Warning:** Component has many "if this, then that" rules
+
+**Problem:** Component doing too many things
+
+**Solution:** Split into simpler, focused components
+
+### Context-Specific Behavior
+
+**Warning:** Component behaves differently in different contexts
+
+**Problem:** Not truly reusable
+
+**Solution:** Create context-specific components or use composition
+
+---
+
+## Examples
+
+### Example 1: Button
+
+**One Component:**
+
+```yaml
+Button:
+  variants: primary, secondary, ghost
+  states: default, hover, active, disabled, loading
+```
+
+**Reason:** All variants serve same purpose (trigger action), share behavior
+
+### Example 2: Input Types
+
+**Multiple Components:**
+
+```yaml
+Text Input: (text entry)
+Select Dropdown: (choose from list)
+Checkbox: (toggle option)
+Radio: (choose one)
+```
+
+**Reason:** Different purposes, different behaviors, different HTML elements
+
+### Example 3: Modal
+
+**Compound Component:**
+
+```yaml
+Modal: (overlay + container)
+Modal Header: (title + close button)
+Modal Body: (content area)
+Modal Footer: (actions)
+```
+
+**Reason:** Complex structure, but parts always used together
+
+---
+
+## When in Doubt
+
+**Start simple:**
+
+1. Create as single component
+2. Add variants as needed
+3. Split when complexity becomes painful
+
+**It's easier to split later than merge later.**
+
+---
+
+## Company Customization
+
+Companies can define their own boundary rules:
+
+```markdown
+# Acme Corp Component Boundaries
+
+**Rule 1:** Icons are always separate components
+**Rule 2:** Form fields include labels (never separate)
+**Rule 3:** Cards never include actions (composition only)
+```
+
+**Consistency within a company matters more than universal rules.**
+
+---
+
+**Use this guide when the design system router detects similarity and you need to decide: same component, variant, or new component?**