initial commit

_bmad/wds/workflows/0-project-setup/steps/step-01-welcome.md

@@ -0,0 +1,183 @@
+---
+name: 'step-01-welcome'
+description: 'Welcome user to WDS introduce methodology and determine project type and alignment needs'
+
+# File References
+nextStepFile: './step-02-structure.md'
+workflowFile: '../workflow.md'
+---
+
+# Step 1: Welcome & Orientation
+
+## STEP GOAL:
+
+Welcome the user to WDS, introduce the methodology and agents, determine if this is a greenfield or brownfield project, and assess if stakeholder alignment is needed.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are the Project Setup facilitator, onboarding users to WDS methodology
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring WDS methodology expertise, user brings their project knowledge
+- ✅ Maintain a welcoming and informative tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on WDS introduction, project type, and alignment assessment
+- 🚫 FORBIDDEN to skip the project type determination or assume it
+- 💬 Approach: Present information clearly, let user choose their path
+- 📋 Routing decisions here determine the entire workflow path
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Introduce WDS, determine project type, assess alignment needs
+- 💾 Record project type (greenfield/brownfield) and alignment decision
+- 📖 Present WDS overview including phases and agents
+- 🚫 Do not skip project type or alignment questions
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Fresh start - no prior project context
+- Focus: Orientation, project type, alignment needs
+- Limits: Do not configure project details yet (that is step 02)
+- Dependencies: None - this is the entry point
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Present WDS Introduction
+
+**Welcome to Whiteport Design Studio (WDS)**
+
+WDS is a **design methodology** that helps you create great digital products through structured workflows.
+
+---
+
+**What WDS Does**
+
+**For NEW products** (Greenfield):
+- Phase 1: Define your vision (Project Brief)
+- Phase 2: Understand your users (Trigger Mapping)
+- Phase 3: Specify features (PRD Platform)
+- Phase 4: Design the experience (UX Design) + Hand off to developers
+- Phase 5: Build with agentic development + Validate quality
+- Phase 6: Build consistency (Design System)
+- Phase 7: Launch & Go Live
+
+**For EXISTING products** (Brownfield):
+- Phase 8: Strategic improvements (Kaizen approach)
+- Limited Brief (document what exists)
+- Focused improvements (not complete redesigns)
+- Continuous iteration cycles
+
+---
+
+**What WDS is NOT**
+
+- Not a code framework
+- Not a UI library
+- Not a one-size-fits-all template
+
+WDS is a **thinking framework** with templates to guide your design decisions.
+
+---
+
+**The Agents**
+
+Three specialized agents help you:
+
+| Agent | Domain | Specialty |
+|-------|--------|-----------|
+| **Saga** | Strategy | Project Briefs, user research, requirements |
+| **Freya** | Design | UX/UI, wireframes, specifications, prototypes, product evolution |
+
+You are currently working with one of these agents.
+
+### 2. Ask Project Type
+
+**What type of project is this?**
+
+Understanding your starting point ensures you follow the right workflow.
+
+**[A] NEW Product (Greenfield)** - Building from scratch -> Phase 1
+**[B] EXISTING Product (Brownfield)** - Improving what exists -> Phase 8
+**[C] NOT SURE** - We will analyze together
+
+**Your choice (A, B, or C):**
+
+### 3. Ask Alignment Requirement
+
+**Do you need stakeholder approval before starting?**
+
+**[A] No - Ready to start** -> Continue to project configuration
+**[B] Yes - Need to pitch/create agreement** -> Route to Alignment & Signoff workflow
+
+**Your choice (A or B):**
+
+### 4. Handle Routing
+
+Based on user responses:
+
+**If alignment = [B] Need to pitch:**
+1. Route to: `{project-root}/_bmad/wds/workflows/0-alignment-signoff/workflow.md`
+2. After alignment complete -> Return here for project configuration
+
+**If alignment = [A] Ready to start:**
+
+**If [A] NEW Product:** Continue to `step-02-structure.md` then Phase 1
+**If [B] EXISTING Product:** Continue to `step-02-structure.md` then Phase 8
+**If [C] NOT SURE:** Scan project, recommend path, then continue
+
+### 5. Completion Output
+
+Project type confirmed: [Greenfield/Brownfield]
+Next: Set up your project structure.
+
+### 6. Present MENU OPTIONS
+
+Display: "**Select an Option:** [C] Continue to Step 2: Configuration & Structure"
+
+#### Menu Handling Logic:
+- IF C: Load, read entire file, then execute {nextStepFile}
+- IF M: Return to {workflowFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can chat or ask questions - always respond and then redisplay menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the project type is confirmed and alignment decision is made will you then load and read fully `{nextStepFile}` to execute and begin the next step.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+- User understands WDS methodology at a high level
+- Project type (greenfield/brownfield) is determined
+- Alignment needs are assessed and routed correctly
+- User feels oriented and confident about the path ahead
+
+### ❌ SYSTEM FAILURE:
+- Skipping project type determination
+- Assuming greenfield or brownfield without asking
+- Not assessing alignment needs
+- Routing to wrong workflow path
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+---
+
+_Phase 0: Project Setup - Step 01: Welcome & Orientation_

_bmad/wds/workflows/0-project-setup/steps/step-02-structure.md

@@ -0,0 +1,225 @@
+---
+name: 'step-02-structure'
+description: 'Configure project settings create folder structure and generate project outline'
+
+# File References
+workflowFile: '../workflow.md'
+activityWorkflowFile: '../workflow.md'
+---
+
+# Step 2: Project Configuration & Structure
+
+## STEP GOAL:
+
+Configure all project settings (name, complexity, tech stack, component library, brief level, strategic analysis, working relationship), create the folder structure, and generate the project outline.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are the Project Setup facilitator, configuring the WDS project
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring WDS methodology expertise, user brings their project knowledge
+- ✅ Maintain a helpful and efficient tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on gathering project configuration and creating structure
+- 🚫 FORBIDDEN to skip configuration questions or assume answers
+- 💬 Approach: Ask each configuration question, respect user choices
+- 📋 Configuration determines the entire project workflow path
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Gather all configuration settings and create project structure
+- 💾 Save project outline to `{{root_folder}}/_progress/wds-project-outline.yaml`
+- 📖 Follow the configuration sequence exactly
+- 🚫 Do not skip questions or assume defaults without offering choice
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Project type (greenfield/brownfield) from step 0.1
+- Focus: Project configuration and structure creation
+- Limits: Configuration only - do not begin Phase 1 work
+- Dependencies: step-01-welcome must be completed
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Project Name
+
+**What is your project name?**
+
+### 2. What Are You Building?
+
+**What type of product is this?**
+
+[A] **Landing Page** - Single page, marketing focused -> Simplified workflow, minimal phases
+[B] **Website** - Multiple pages, content focused -> Standard workflow, most phases
+[C] **Web Application** - Complex features, user interactions -> Full workflow, all phases
+[D] **Mobile App** - iOS/Android application -> Full workflow + platform considerations
+
+Store as `product_complexity`: A=simple, B=standard, C=complex, D=complex+mobile
+
+### 3. Tech Stack (Optional)
+
+**Tech stack?** [A] React/Next [B] Vue/Nuxt [C] WordPress [D] HTML [E] Other [F] Skip
+
+Store as `tech_stack` (or null if F)
+
+### 4. Component Library (Optional)
+
+**Component library?**
+
+[A] **shadcn/ui** -> Skip Phase 5
+[B] **Tailwind only** -> Phase 5 optional
+[C] **Material UI** -> Skip Phase 5
+[D] **Custom** -> Phase 5 recommended
+[E] **Skip** - Decide later
+
+Store as `component_library`. If A/C -> `skip_design_system: true`
+
+### 5. Root Folder Name
+
+**Where should design process files live?**
+
+[A] **design-process** (Recommended)
+[B] **docs**
+[C] **Custom name**
+
+Store as `root_folder`: A=design-process, B=docs, C=custom
+
+### 6. Existing Materials (Optional Context)
+
+**Do you have any existing materials for this project?**
+
+[A] **Yes** - I have some materials to share
+[B] **No** - Starting fresh
+
+If Yes: Review materials, store in outline under `existing_materials`
+If No: Store `existing_materials.has_materials: false`
+
+### 7. Brief Level
+
+**Greenfield**: Always use Complete Brief (`brief_level: complete`)
+
+**Brownfield**: Ask how thorough the Project Brief should be:
+[A] **Complete** - Full strategic documentation
+[B] **Simplified** (Recommended) - Document what exists + what to change
+
+Store as `brief_level`: complete | simplified
+
+### 8. Strategic Analysis Level (Greenfield only)
+
+**How deep should the user/market analysis go?** (Only ask if greenfield AND not simple)
+
+[A] **Full Trigger Map** (Recommended for complex) -> Phase 2 enabled
+[B] **Simplified** -> Strategic context in Phase 1, skip Phase 2
+[C] **Skip** (Not recommended) -> Skip Phase 2
+
+Store as `strategic_analysis`: full | simplified | skip
+
+### 9. Working Relationship Context
+
+**What are the stakes of this project?**
+
+[A] **Personal/Hobby** -> Encouragement-focused, minimal documentation
+[B] **Small Business Investment** -> Balanced rationale, professional
+[C] **Departmental/Organizational** -> Comprehensive justification, evidence-based
+[D] **Enterprise/High Stakes** -> Rigorous documentation, proof for every point
+
+**How involved do you want to be?**
+[A] Highly collaborative [B] Balanced [C] Autonomous execution
+
+**What is your role?**
+[A] Client/Stakeholder [B] Product Owner [C] Design Partner [D] Project Manager [E] Other
+
+**How should I present recommendations?**
+[A] Suggest options [B] Recommend with rationale [C] Direct guidance
+
+If stakes C/D: Ask about stakeholders and political sensitivities.
+
+Store all as `project_context` and `working_relationship` in outline.
+
+### 10. Create Structure & Outline
+
+**Check existing:** Look for `{{root_folder}}/` and outline file
+**If exists:** Ask to keep or reset
+
+**Create folder structure:**
+1. Create root folder: `{{root_folder}}/`
+2. Create progress folder: `{{root_folder}}/_progress/`
+3. Create agent experiences folder: `{{root_folder}}/_progress/agent-experiences/`
+4. Create phase folders (greenfield vs brownfield)
+5. Create D-Design-System subfolders
+6. Install folder guide files from templates
+
+**Generate `{{root_folder}}/_progress/wds-project-outline.yaml`** with all configuration values.
+
+**Fill in `00-design-log.md`** with initial Phase 0 entry.
+
+### 11. Summary & Next Steps
+
+**Project configured!** Display summary table of all settings.
+
+**Greenfield routing:**
+[A] Start Phase 1 now
+[B] Hand off to Saga (specialist)
+
+**Brownfield routing:**
+[A] Create Limited Brief now
+[B] Scan my codebase first
+[C] I know what to improve - go
+
+### 12. Routing
+
+**Greenfield:** [A] -> Phase 1 workflow, [B] -> Hand off to Saga
+**Brownfield:** [A] -> Limited Brief, [B] -> Scan codebase, [C] -> Phase 8
+
+### 13. Present MENU OPTIONS
+
+Display: "**Select an Option:** [M] Return to Activity Menu"
+
+#### Menu Handling Logic:
+- IF M: Return to {workflowFile} or {activityWorkflowFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- User can chat or ask questions - always respond and then redisplay menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the project is fully configured and structure is created will you present the return to Activity Menu option.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+- All configuration questions are answered
+- Project outline YAML is generated correctly
+- Folder structure is created
+- Correct routing to next phase based on project type and configuration
+- User understands what comes next
+
+### ❌ SYSTEM FAILURE:
+- Skipping configuration questions
+- Assuming defaults without offering choice
+- Not creating folder structure
+- Not generating project outline YAML
+- Routing to wrong phase
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+---
+
+_Phase 0: Project Setup - Step 02: Configuration & Structure_

_bmad/wds/workflows/0-project-setup/templates/folder-guides/00-design-log.template.md

@@ -0,0 +1,59 @@
+# Design Log
+
+**Project:** {{project_name}}
+**Started:** {{date}}
+**Method:** Whiteport Design Studio (WDS)
+
+---
+
+## Backlog
+
+> Business-value items. Add links to detail files if needed.
+
+- [ ] Complete product brief — Phase 1
+- [ ] Define trigger map — Phase 2
+- [ ] Create user scenarios — Phase 3
+
+---
+
+## Current
+
+| Task | Started | Agent |
+|------|---------|-------|
+| — | — | — |
+
+**Rules:** Mark what you start. Complete it when done (move to Log). One task at a time per agent.
+
+---
+
+## Design Loop Status
+
+> Per-page design progress. Updated by agents at every design transition.
+
+| Scenario | Step | Page | Status | Updated |
+|----------|------|------|--------|---------|
+
+**Status values:** `discussed` → `wireframed` → `specified` → `explored` → `building` → `built` → `approved` | `removed`
+
+**How to use:**
+- **Append a row** when a page reaches a new status (do not overwrite — latest row per page is current status)
+- **Read on startup** to see where the project stands and what to suggest next
+
+---
+
+## Log
+
+### {{date}} — Project initialized (Phase 0)
+- Type: {{greenfield/brownfield}}
+- Complexity: {{product_complexity}}
+- Tech stack: {{tech_stack}}
+
+---
+
+## About This Folder
+
+- **This file** — Single source of truth for project progress
+- **agent-experiences/** — Compressed insights from design discussions (dated files)
+- **wds-project-outline.yaml** — Project configuration from Phase 0 setup
+
+**Do not modify `wds-project-outline.yaml`** — it is the source of truth for project configuration.

_bmad/wds/workflows/0-project-setup/templates/folder-guides/00-design-system.template.md

@@ -0,0 +1,251 @@
+# Design System: {{project_name}}
+
+> Components, tokens, and patterns that grow from actual usage — not upfront planning.
+
+**Created:** {{date}}
+**Phase:** 7 — Design System (optional)
+**Agent:** Freya (Designer)
+
+---
+
+## What Belongs Here
+
+The Design System captures reusable patterns that emerge during UX Design (Phase 4). It is not designed upfront — it crystallizes from real page specifications.
+
+**What goes here:**
+- **Design Tokens** — Colors, spacing, typography, shadows
+- **Components** — Buttons, inputs, cards, navigation elements
+- **Patterns** — Layouts, form structures, content blocks
+- **Visual Design** — Mood boards, design concepts, color and typography explorations
+- **Assets** — Logos, icons, images, graphics
+
+**What does NOT go here:**
+- Page-specific content (that lives in `C-UX-Scenarios/`)
+- Business logic or API specs (that's BMM territory)
+- Aspirational components nobody uses yet
+
+**When to skip this phase:**
+- Using shadcn/ui or Material UI → the library IS your design system
+- Simple sites with Tailwind → tokens in `tailwind.config` are enough
+
+**Learn more:**
+- WDS Course Module 12: Functional Components — Patterns Emerge
+- WDS Course Module 13: Design System
+
+---
+
+## Folder Structure
+
+```
+D-Design-System/
+├── 00-design-system.md          ← This file (hub + guide)
+├── 01-Visual-Design/            [Early design exploration]
+│   ├── mood-boards/             [Visual inspiration, style exploration]
+│   ├── design-concepts/         [NanoBanana outputs, design explorations]
+│   ├── color-exploration/       [Color palette experiments]
+│   └── typography-tests/        [Font pairing and hierarchy tests]
+├── 02-Assets/                   [Final production assets]
+│   ├── logos/                   [Brand logos and variations]
+│   ├── icons/                   [Icon sets]
+│   ├── images/                  [Photography, illustrations]
+│   └── graphics/                [Custom graphics and elements]
+└── components/                  [Emerges during Phase 4]
+    ├── interactive/             [Buttons, toggles, tabs]
+    ├── form/                    [Inputs, selects, checkboxes]
+    ├── layout/                  [Containers, grids, sections]
+    ├── content/                 [Cards, lists, media blocks]
+    ├── feedback/                [Alerts, toasts, progress]
+    └── navigation/              [Menus, breadcrumbs, links]
+```
+
+**01-Visual-Design/** is used early — before or during scenarios — for exploring visual direction. Mood boards, color palettes, typography tests, and AI-generated design concepts live here.
+
+**02-Assets/** holds final, production-ready assets. Logos, icons, images, and graphics that are referenced from page specifications.
+
+**components/** grows organically during Phase 4 as patterns emerge across page specifications.
+
+---
+
+## For Agents
+
+**Workflow:** `_bmad/wds/workflows/7-design-system/workflow.md`
+**Agent trigger:** `DS` (Freya)
+**Router:** `_bmad/wds/workflows/7-design-system/design-system-router.md`
+**Templates:** `_bmad/wds/workflows/7-design-system/templates/`
+**Guide:** `_bmad/wds/data/agent-guides/freya/design-system.md`
+
+**Before creating any component:**
+1. Check if it already exists in the chosen component library
+2. Look at actual usage in `C-UX-Scenarios/` page specs — extract, don't invent
+3. Load the component template from the workflow templates folder
+
+**File naming:** Number all documents with a two-digit prefix: `01-design-tokens.md`, `02-button.md`, etc. Update the sections below as each file is created.
+
+**Harm:** Designing an abstract component library before any pages exist. Components without real usage are decoration. They waste time and create maintenance burden for patterns nobody needs.
+
+**Help:** Extracting patterns from real page specs. When three pages use similar card layouts, that's a component. The design system documents what emerged, making future pages faster and more consistent.
+
+---
+
+## Spacing Scale
+
+> **Bring your own or use ours.** If your project already has a design system with a spacing scale (Tailwind, Material, Carbon, your own tokens), use that. Map your token names below so page specs reference them consistently. If you don't have one yet, WDS provides a default 9-token scale to get started.
+
+### Option A: Use your existing design system
+
+Replace the table below with your system's spacing tokens. Any naming convention works — numbered (`spacing-4`), t-shirt (`sm`/`md`/`lg`), or your own. The only rule: page specs reference token names, never raw pixel values.
+
+### Option B: WDS default scale
+
+Nine tokens, symmetric around `space-md` (the baseline). Freya will propose pixel values during the first design session.
+
+`space-md` is to spacing what `text-md` is to typography — the default you reach for first. It's the gap between paragraphs, between form fields, between list items. Everything else is relative to it: `space-sm` is tighter, `space-lg` is more generous.
+
+| Token | Value | Use |
+|-------|-------|-----|
+| space-3xs | — | Hairline gaps (icon-to-label, inline elements) |
+| space-2xs | — | Minimal spacing (badge padding, tight lists) |
+| space-xs | — | Tight spacing (within compact groups) |
+| space-sm | — | Small gaps (between related elements) |
+| **space-md** | — | **Default element spacing (the baseline)** |
+| space-lg | — | Comfortable spacing (card padding, form fields) |
+| space-xl | — | Section padding |
+| space-2xl | — | Section gaps |
+| space-3xl | — | Page-level breathing room |
+
+### Optical adjustments
+
+Sometimes the math is right but the eye says it's wrong. A circular image leaves white corners, a light element on a light background looks more spaced than it is. When this happens, use token math — not raw pixels:
+
+```
+space-lg - space-3xs    → "standard spacing, pulled in by a hairline"
+space-xl + space-2xs    → "section padding, nudged out slightly"
+```
+
+In page specs, always annotate why:
+
+| Padding top | **space-lg - space-3xs** (optical: circular image adds perceived whitespace) |
+
+**Rules:**
+- Adjustments always use token math: `base ± correction`
+- Always annotate the reason — future readers need to know this wasn't a mistake
+- If adjusting by more than one step, the base token is probably wrong — reconsider
+
+In CSS: `calc(var(--space-lg) - var(--space-3xs))`
+
+<!--
+  space-md is typically 16px (on an 8px grid) or 12px (on a 4px grid) — the most common
+  default spacing on the web. Same ballpark as body text size, which is not a coincidence.
+
+  The pixel values are yours to define. Common starting points:
+  2/4/8/12/16/24/32/48/64 (8px grid) or 4/6/12/16/24/32/48/72.
+  You can adjust later — specs stay valid because they reference names, not numbers.
+-->
+
+---
+
+## Type Scale
+
+> **Bring your own or use ours.** Same principle as spacing — if your project has a type system, map it here. If not, use the WDS default.
+
+The type scale controls **visual size** — how big text looks. This is separate from semantic level (H1, H2, p) which controls **document structure**. An H2 in a sidebar might be `text-sm`. A tagline might be a `<p>` at `text-2xl`. The semantic level is for accessibility and SEO; the type token is for visual hierarchy.
+
+Headings can have different typefaces, weights, and styles on different pages. A landing page H1 might be a serif display font at `text-3xl` italic. An admin page H1 might be clean sans-serif at `text-lg` medium. Each page spec declares its own typographic treatment — the type scale provides the shared sizing vocabulary.
+
+### Option A: Use your existing type system
+
+Replace the table below with your system's type tokens.
+
+### Option B: WDS default scale
+
+Nine tokens, symmetric around `text-md` (body text). Freya will propose sizes during the first design session.
+
+| Token | Value | Use |
+|-------|-------|-----|
+| text-3xs | — | Fine print, legal text |
+| text-2xs | — | Metadata, timestamps |
+| text-xs | — | Captions, helper text |
+| text-sm | — | Labels, secondary text |
+| text-md | — | Body text (the baseline) |
+| text-lg | — | Emphasis, lead paragraphs |
+| text-xl | — | Subheadings |
+| text-2xl | — | Section titles, display text |
+| text-3xl | — | Hero headings, page titles |
+
+<!--
+  text-md (body text) is typically 16px or 14px — the most common baseline on the web.
+  Common starting points: 11/12/13/14/16/18/20/24/32 or 10/11/12/14/16/18/22/30/40.
+  Line heights should align to your spacing grid for vertical rhythm.
+-->
+
+---
+
+## Tokens
+
+_Additional design tokens (colors, shadows, borders) will be documented here as they emerge from page specifications._
+
+---
+
+## Patterns
+
+<!--
+  Patterns are organized BY the spacing, not by object pairs.
+  Each spacing value/composition accumulates a list of where it's used.
+
+  When the designer says "more space here", the agent fixes it, reflects
+  what it learned, and adds the situation to the relevant pattern below.
+
+  The agent does NOT ask "why?" — it observes and reflects:
+  "Got it — large image above a card row needs extra room. I'll remember that."
+
+  EXTRACTION RULES — objects vs spacing:
+  - Objects: first use stays in the page spec. Second use → extract here.
+  - Spacing: first use → immediately extract here. No waiting.
+  Spacing is relational — a decision about two object types is universal from day one.
+
+  CONTEXT RULE: Entries are context-free by default (universal).
+  Add context only when the same object pair needs DIFFERENT spacing
+  in different situations. When that happens, BOTH entries get context
+  so you can tell them apart. Before the first violation, keep it clean.
+-->
+
+Spacing objects are first-class — they have IDs in page specs (e.g., `hem-v-space-xl`) and live here organized by value. Each spacing value accumulates the situations where it's used. The list grows from real design decisions.
+
+_Patterns will be documented here as spacing objects recur across pages._
+
+<!--
+  Example format (delete when real patterns emerge):
+
+  ### space-sm
+  | Above | Below | Why |
+  |-------|-------|-----|
+  | Heading | Subheading | Tight pair — always read together |
+  | Icon | Label (inside button) | Compact inline group |
+
+  ### space-lg
+  | Above | Below | Why |
+  |-------|-------|-----|
+  | Card | Card (grid gap) | Comfortable breathing room |
+  | Image | Caption | Standard image-to-text |
+
+  ### space-zero
+  | Above | Below | Why |
+  |-------|-------|-----|
+  | Header | Service menu | One continuous nav unit |
+  | Icon bar | Section below | Flush — belongs to the section above |
+
+  ### v-separator-2xl
+  | Above | Below | Why |
+  |-------|-------|-----|
+  | About preview | Trust cards | Gray line, equal space above/below |
+-->
+
+---
+
+## Components
+
+_Components will be documented here as patterns emerge across scenarios._
+
+---
+
+_Created using Whiteport Design Studio (WDS) methodology_

_bmad/wds/workflows/0-project-setup/templates/folder-guides/00-product-brief.template.md

@@ -0,0 +1,59 @@
+# Product Brief: {{project_name}}
+
+> The strategic foundation — why this product exists, who it serves, and what success looks like.
+
+**Created:** {{date}}
+**Phase:** 1 — Product Brief
+**Agent:** Saga (Analyst)
+
+---
+
+## What Belongs Here
+
+The Product Brief answers five strategic questions:
+
+1. **Why** does this product exist? (Vision & business goals)
+2. **Who** is it for? (Target users and their context)
+3. **What** does it need to do? (Core capabilities)
+4. **How** will we know it works? (Success metrics)
+5. **What** are the constraints? (Platform requirements, tech stack)
+
+Everything downstream — trigger maps, scenarios, page specs, design system — traces back to decisions made here. This is the North Star.
+
+**Learn more:**
+- WDS Course Module 04: Product Brief — Your Strategic Foundation
+- WDS Course Module 05: Platform Requirements
+
+---
+
+## For Agents
+
+**Workflow:** `_bmad/wds/workflows/1-project-brief/workflow.md`
+**Agent trigger:** `PB` (Saga)
+**Templates:** `_bmad/wds/workflows/1-project-brief/templates/`
+
+**Before writing anything in this folder:**
+1. Load the workflow and follow its steps
+2. Use Dialog mode for discovery — ask questions, don't assume
+3. Read existing materials if the user has them (check `wds-project-outline.yaml`)
+
+**File naming:** Number all documents with a two-digit prefix: `01-product-brief.md`, `02-content-language.md`, etc. Platform Requirements is always last — it summarizes technical decisions that emerge from the strategic documents above. Update the Documents table below as each file is created.
+
+**Harm:** Producing a brief from assumptions instead of conversation. A brief that doesn't reflect the user's actual goals forces every later phase to build on a wrong foundation.
+
+**Help:** Asking the right questions, listening deeply, and documenting what the user actually said. A good brief makes every later decision easier.
+
+---
+
+## Documents
+
+_This section will be updated as documents are created during Phase 1._
+
+| # | Document | Status |
+|---|----------|--------|
+| 01 | Product Brief | Not started |
+| 02 | Platform Requirements | Not started |
+
+---
+
+_Created using Whiteport Design Studio (WDS) methodology_

_bmad/wds/workflows/0-project-setup/templates/folder-guides/00-trigger-map.template.md

@@ -0,0 +1,66 @@
+# Trigger Map: {{project_name}}
+
+> Connect business goals to user psychology — understand why people act, not just what they do.
+
+**Created:** {{date}}
+**Phase:** 2 — Trigger Mapping
+**Agent:** Saga (Analyst)
+
+---
+
+## What Belongs Here
+
+The Trigger Map reveals the human forces behind product decisions through five workshops:
+
+1. **Business Goals** — What the business needs to achieve
+2. **Target Groups** — Who the users are (with alliterative persona names)
+3. **Driving Forces** — What motivates and frightens each persona (positive + negative)
+4. **Prioritization** — Which forces matter most (scored by frequency, intensity, fit)
+5. **Feature Impact** — How product features address the highest-priority forces
+
+This folder feeds directly into Phase 4 (UX Scenarios). Every page spec should trace back to a driving force documented here.
+
+**Learn more:**
+- WDS Course Module 06: Trigger Mapping — Connect Business Goals to User Psychology
+- WDS Course Module 06, Lessons 4–8: The Five Workshops
+
+---
+
+## For Agents
+
+**Workflow:** `_bmad/wds/workflows/2-trigger-mapping/workflow.md`
+**Agent trigger:** `TM` (Saga)
+**Templates:** `_bmad/wds/workflows/2-trigger-mapping/templates/`
+
+**Before writing anything in this folder:**
+1. Read the Product Brief in `A-Product-Brief/` — trigger mapping builds on it
+2. Load the workflow and follow the five workshop sequence
+3. Use Dialog mode — personas emerge from conversation, not invention
+
+**File naming:** Number all documents with a two-digit prefix: `01-business-goals.md`, `02-lars-the-loyal.md`, etc. One file per persona. Update the Documents table below as each file is created.
+
+**Harm:** Inventing personas without discovery. Fabricated driving forces produce scenarios that solve imaginary problems. The user pays to correct work that should never have been written.
+
+**Help:** Uncovering real psychology through conversation. When driving forces are authentic, every downstream design decision has a clear "why."
+
+---
+
+## Documents
+
+_This section will be updated as documents are created during Phase 2._
+
+| # | Document | Purpose | Status |
+|---|----------|---------|--------|
+| 01 | Business Goals | Vision, objectives, metrics | Not started |
+| 02+ | Persona files | One per target group | Not started |
+| — | Feature Impact Analysis | Forces × features scoring | Not started |
+
+---
+
+## Trigger Map Visualization
+
+_A mermaid diagram connecting goals → platform → personas → forces will be added here during Phase 2._
+
+---
+
+_Created using Whiteport Design Studio (WDS) methodology_

_bmad/wds/workflows/0-project-setup/templates/folder-guides/00-ux-scenarios.template.md

@@ -0,0 +1,85 @@
+# UX Scenarios: {{project_name}}
+
+> Design experiences, not screens — every page serves a user with a goal and an emotion.
+
+**Created:** {{date}}
+**Phase:** 3 (Scenario Outline) + Phase 4 (UX Design)
+**Agents:** Saga (Scenario Outline), Freya (Page Specifications)
+
+---
+
+## What Belongs Here
+
+Scenarios organize the product into meaningful user journeys. Each scenario groups related pages. Each page gets a full specification that a developer can build from.
+
+**Folder structure per scenario:**
+```
+C-UX-Scenarios/
+├── 00-ux-scenarios.md          ← This file (scenario guide + page index)
+├── 01-scenario-name/
+│   ├── 1.1-page-name/
+│   │   ├── 1.1-page-name.md   ← Page specification
+│   │   └── Sketches/           ← Wireframes and concepts
+│   ├── 1.2-page-name/
+│   │   ├── 1.2-page-name.md
+│   │   └── Sketches/
+│   └── ...
+├── 02-scenario-name/
+│   └── ...
+├── Components/                  ← Shared component specs
+└── Features/
+    └── Storyboards/             ← Multi-step interaction flows
+```
+
+**Learn more:**
+- WDS Course Module 08: Outline Scenarios — Design Experiences Not Screens
+- WDS Course Module 09: Conceptual Sketching
+- WDS Course Module 10: Storyboarding
+- WDS Course Module 11: Conceptual Specifications
+- WDS Course Tutorial 08: From Trigger Map to Scenarios
+
+---
+
+## For Agents
+
+### Scenario Outline (Saga)
+**Workflow:** `_bmad/wds/workflows/3-scenarios/workflow.md`
+**Agent trigger:** `SC` (Saga)
+
+### Page Specifications (Freya)
+**Workflow:** `_bmad/wds/workflows/4-ux-design/workflow.md`
+**Agent trigger:** `UX` (Freya)
+**Page template:** `_bmad/wds/workflows/4-ux-design/templates/page-specification.template.md`
+**Scenario template:** `_bmad/wds/workflows/4-ux-design/templates/scenario-overview.template.md`
+**Quality guide:** `_bmad/wds/data/agent-guides/freya/specification-quality.md`
+**Object types:** `_bmad/wds/workflows/4-ux-design/object-types/`
+
+### Specification Audit (Freya)
+**Workflow:** `_bmad/wds/workflows/4-ux-design/specification-audit-workflow.md`
+**Agent trigger:** `SA` (Freya)
+
+**Before writing any page specification:**
+1. Read `B-Trigger-Map/` — know the personas and their driving forces
+2. Read the page specification template — use it as your scaffold, not memory
+3. Discuss the page purpose with the user before filling in details
+4. Each page folder needs a `Sketches/` subfolder for wireframes
+
+**Harm:** Producing page specs from memory of what the template "roughly" contains. Plausible-looking specs that use wrong structure break the pipeline — developers can't trust them, audits can't validate them, and the user must correct what should have been right.
+
+**Help:** Reading the actual template into context, discussing page purpose with the user, then filling the template with specific content. Specs that follow the template work across projects, pass audits, and give developers confidence.
+
+---
+
+## Scenarios
+
+_This section will be updated as scenarios are outlined during Phase 3._
+
+---
+
+## Page Index
+
+_This section will be updated as page specifications are created during Phase 4._
+
+---
+
+_Created using Whiteport Design Studio (WDS) methodology_

_bmad/wds/workflows/0-project-setup/workflow.md

@@ -0,0 +1,105 @@
+---
+name: project-setup
+description: Project onboarding - determine project type, complexity, tech stack, and route to correct phase
+web_bundle: true
+---
+
+# Phase 0: Project Setup
+
+**The starting point for every WDS project.**
+
+
+## Purpose
+
+Phase 0 ensures you start on the right path. Before diving into design work, we need to understand:
+
+1. **What is WDS?** - So you know what you're getting
+2. **What type of project?** - New product vs existing product
+3. **How complex?** - Landing page vs web application
+4. **What tech?** - Framework and component library choices
+5. **What's the right workflow?** - Route to the correct phase with right config
+
+---
+
+## Why This Matters
+
+**The #1 mistake**: Starting Phase 1 with an existing codebase.
+
+- **Phase 1-7** = Building something NEW (Greenfield)
+- **Phase 8** = Improving something EXISTING (Brownfield, Product Evolution)
+
+Wrong path = wasted work. Phase 0 prevents this.
+
+---
+
+## The Flow
+
+```
+Phase 0: Project Setup
+    │
+    ├─→ Step 01: Welcome
+    │       ├─→ "What is WDS?" (quick intro)
+    │       └─→ "Greenfield or Brownfield?"
+    │
+    └─→ Step 02: Configuration
+            ├─→ Project name
+            ├─→ Product complexity (landing/website/app)
+            ├─→ Tech stack (optional)
+            ├─→ Component library (optional)
+            ├─→ Brief level (complete/simplified)
+            ├─→ Strategic analysis (full/simplified/skip)
+            ├─→ Create folder structure
+            └─→ Generate project outline
+                    │
+                    ├─→ Greenfield → Phase 1 (→ Phase 2 if full analysis)
+                    └─→ Brownfield → Phase 8
+```
+
+---
+
+## Steps
+
+| Step | Name | Purpose |
+|------|------|---------|
+| 01 | [Welcome & Orientation](steps/step-01-welcome.md) | Introduce WDS, determine greenfield vs brownfield |
+| 02 | [Configuration & Structure](steps/step-02-structure.md) | Configure project, create folders, generate outline |
+
+---
+
+## Entry Point
+
+**Start here**: `steps/step-01-welcome.md`
+
+---
+
+## When to Use Phase 0
+
+- First time using WDS
+- Starting a new project
+- Joining an existing project
+- Unsure which workflow to use
+
+---
+
+## When to Skip Phase 0
+
+- Project outline already exists (`.wds-project-outline.yaml`)
+- You know exactly which phase you need
+- Continuing work on established WDS project
+
+---
+
+**Phase 0 takes 3-5 minutes. It saves hours of wrong-path work.**
+
+---
+
+## Configuration Options
+
+| Option | Values | Impact |
+|--------|--------|--------|
+| Project Type | greenfield / brownfield | Determines Phase 1-7 (greenfield) vs Phase 8 (brownfield) |
+| Complexity | simple / standard / complex | Which phases are enabled |
+| Tech Stack | react / vue / wordpress / etc. | Delivery format guidance |
+| Component Library | shadcn / tailwind / custom | Skip or enable Phase 5 |
+| Brief Level | complete / simplified | Depth of Phase 1 |
+| Strategic Analysis | full / simplified / skip | Full Trigger Map or simplified in brief |