whiteport-design-studio 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2025 BMad Code, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+TRADEMARK NOTICE:
+
+BMad™ , BMAD-CORE™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.
+WDS and the Whiteport Design System are trademarks of Whiteport Collective.
+The use of any of these trademarks in this software does not grant any rights to use the trademarks for any other purpose.

package/README.md

@@ -0,0 +1,196 @@
+# Whiteport Design Studio (WDS) 🎨
+
+**Strategic design methodology for creating products users love**
+
+## What You Can Accomplish with WDS
+
+As a designer using WDS, you'll be able to:
+
+🎯 **Create strategic designs** - Connect every design decision to business goals and user psychology  
+📋 **Produce complete specifications** - Generate developer-ready page specs with all details defined  
+✨ **Explore with AI image generation** - Use NanoBanana/Eira to generate design concepts and establish visual identity  
+🎨 **Design with Figma** - Open your prototype in Figma, refine the design, export it back to update the design system and generate new code  
+🤖 **Leverage AI agents** - Work with Saga, Idunn, and Freya to accelerate your workflow  
+📦 **Deliver with confidence** - Hand off complete, tested prototypes with clear documentation  
+
+### What You Need to Learn
+
+To get the most out of WDS, you'll need to understand:
+
+1. **The WDS workflow** - How phases connect and when to use each one
+2. **Agent collaboration** - Working with Saga, Idunn, and Freya to accomplish tasks
+3. **Tool integration** - Using Figma MCP, NanoBanana, and other design tools
+
+� **Start learning:** [docs/learn-wds/](docs/learn-wds/) - Interactive courses and tutorials
+
+---
+
+## Module Structure
+
+```
+wds/
+├── _module-installer/          # Installation configuration
+├── agents/                     # WDS specialized agents (Norse Pantheon)
+│   ├── saga-analyst.agent.yaml # Saga-Analyst - Business & Product Analyst
+│   ├── idunn-pm.agent.yaml     # Idunn-WDS-PM - Product Manager
+│   └── freya-ux.agent.yaml    # Freya-WDS-Designer - UX/UI Designer
+├── workflows/                  # Phase-selectable design workflows
+├── data/                       # Standards, frameworks, presentations
+│   └── presentations/          # Agent introduction presentations
+├── docs/                       # Module documentation
+│   ├── method/                 # Methodology deep-dives
+│   └── images/                 # Diagrams and visuals
+├── examples/                   # Real-world usage examples
+│   └── dog-week-patterns/      # Patterns from Dog Week project
+├── reference/                  # Templates and checklists
+│   ├── templates/              # Document templates
+│   └── checklists/             # Phase completion checklists
+├── teams/                      # Team configurations
+└── README.md                   # This file (only README in module)
+```
+
+## 📁 Output Structure
+
+WDS creates a clean, alphabetized folder structure in your project's `docs/` folder:
+
+| Folder             | Phase | Purpose                                      | Timing              |
+| ------------------ | ----- | -------------------------------------------- | ------------------- |
+| `A-Product-Brief/` | 1     | Strategic foundation & vision                | Start here          |
+| `B-Trigger-Map/`   | 2     | User psychology & business goals             | After Phase 1       |
+| `C-Scenarios/`     | 4     | UX specifications (HOW it works)             | After Phase 2       |
+| `D-Design-System/` | 5     | Visual identity & components (HOW it looks)  | **Anytime** 🎨      |
+| `D-PRD/`           | 3     | Technical requirements (optional)            | Before development  |
+| `E-UI-Roadmap/`    | 6     | Development handoff                          | After Phase 4       |
+
+## 🎯 Design Phases
+
+### Core Workflow
+
+**Phase 1: Product Exploration** → `A-Product-Brief/`  
+Define vision, positioning, and success criteria
+
+**Phase 2: User Research** → `B-Trigger-Map/`  
+Connect business goals to user psychology and triggers
+
+**Phase 4: UX Design** → `C-Scenarios/`  
+**HOW it works** - Functionality, interactions, content structure
+
+**Phase 5: Visual Design** → `D-Design-System/`  
+**HOW it looks** - Tie UX to brand, create visual system  
+⚡ **Can start anytime** - Brand identity is independent of product!
+
+### Optional Phases
+
+**Phase 3: Requirements** → `D-PRD/` (for technical products)  
+**Phase 6: Dev Integration** → `E-UI-Roadmap/` (handoff to development)
+
+---
+
+## 💡 Key Concepts
+
+### UX vs Visual Design
+
+```
+Phase 4 (UX Design)
+├─ Defines HOW it works
+├─ Functionality & interactions
+├─ Content structure & hierarchy
+└─ Question: "What does this do?"
+
+Phase 5 (Visual Design)
+├─ Defines HOW it looks and feels
+├─ Brand expression & visual language
+├─ Design tokens & system
+└─ Question: "How does this feel like our brand?"
+```
+
+### Brand Independence
+
+**Visual design is NOT tied to product timing!**
+
+- ✅ Before product work (brand-first approach)
+- ✅ Parallel to strategy (simultaneous development)
+- ✅ After strategy (informed by insights)
+
+**Output location:** `D-Design-System/01-Visual-Design/`
+
+## Agents - The Norse Pantheon 🏔️
+
+| Agent                   | File                      | Role                       | Norse Meaning                       |
+| ----------------------- | ------------------------- | -------------------------- | ----------------------------------- |
+| **Saga the Analyst**    | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom         |
+| **Idunn the PM**        | `idunn-pm.agent.yaml`     | Product Manager            | Goddess of renewal & youth          |
+| **Freya the Designer** | `freya-ux.agent.yaml`    | UX/UI Designer             | Goddess of beauty, magic & strategy |
+
+## 🛠️ Tools & Integration
+
+### Visual Design Tools
+
+- **Figma MCP** - Automated bidirectional sync with Object IDs
+- **NanoBanana/Eira** - AI-powered image generation for brand exploration
+- **html.to.design** - Import HTML prototypes into Figma
+
+### Workflow Tools
+
+- **Excalidraw** - Sketch analysis and wireframing
+- **Git** - Version control and collaboration
+- **Cursor/Windsurf** - AI-powered IDE integration
+
+📖 **Full tools guide:** [docs/tools/wds-tools-guide.md](docs/tools/wds-tools-guide.md)
+
+---
+
+## 📋 Conventions
+
+- **One README rule** - Only this README.md; all other docs use `xxx-guide.md` naming
+- **Alphabetized output** - A-B-C-D-E folder prefix for clean organization
+- **Design focus** - No development artifacts (handled by BMM)
+- **Phase-selectable** - Choose phases based on project needs
+- **Tool-agnostic** - Works with any design/development tools
+
+## 🚀 Getting Started
+
+### 1. Sideload Agents (Manual Installation)
+
+Since the installer isn't working, manually copy agents:
+
+```bash
+# Copy agent files to your IDE's agent folder
+cp src/modules/wds/agents/*.yaml <your-ide-agent-folder>/
+```
+
+### 2. Activate an Agent
+
+In your IDE, activate one of the WDS agents:
+- **Saga** - Business & Product Analyst
+- **Idunn** - Product Manager  
+- **Freya** - UX/UI Designer
+
+### 3. Initialize Workflow
+
+```
+*workflow-init
+```
+
+The agent will guide you through project setup and phase selection.
+
+📖 **Detailed setup guide:** [docs/how-to/installation/install-bmad.md](../../docs/how-to/installation/install-bmad.md)
+
+## 🔗 Integration with BMM
+
+WDS design artifacts feed directly into BMad Method (BMM) development workflows:
+
+```
+WDS Design System → E-UI-Roadmap/ → BMM Architecture & Stories → Development
+```
+
+**Handoff includes:**
+- Component specifications with Object IDs
+- Design tokens (colors, typography, spacing)
+- Interactive HTML prototypes
+- User flow documentation
+- Acceptance criteria
+
+---
+
+<sub>Part of the BMad ecosystem • Contributed by Whiteport Collective</sub>

package/docs/getting-started/MANUAL-INIT-GUIDE.md

@@ -0,0 +1,251 @@
+# Manual WDS Initialization
+
+**Set up WDS in your project without NPX - 3 simple steps**
+
+---
+
+## Overview
+
+This guide walks you through manually initializing WDS in your project by copying the necessary files and folder structure.
+
+**Time:** 5 minutes  
+**Difficulty:** Beginner
+
+---
+
+## Prerequisites
+
+- A project repository (GitHub, GitLab, local Git repo)
+- Basic familiarity with file structure
+- Code editor (VS Code/Cursor recommended)
+
+---
+
+## Step 1: Copy WDS Module to Your Project
+
+### Option A: Clone and Copy
+
+```bash
+# Clone WDS repository (temporary location)
+git clone https://github.com/whiteport-collective/whiteport-design-studio.git temp-wds
+
+# Copy the WDS module to your project
+cp -r temp-wds/src/modules/wds your-project/.cursor/rules/wds
+
+# Remove temporary clone
+rm -rf temp-wds
+```
+
+### Option B: Download and Copy
+
+1. Download WDS from [GitHub](https://github.com/whiteport-collective/whiteport-design-studio)
+2. Extract the archive
+3. Copy `src/modules/wds` to `your-project/.cursor/rules/wds`
+
+---
+
+## Step 2: Verify Folder Structure
+
+After copying, your project should have this structure:
+
+```
+your-project/
+├── .cursor/
+│   └── rules/
+│       └── wds/
+│           ├── agents/
+│           │   ├── freya-ux.agent.yaml
+│           │   ├── idunn-pm.agent.yaml
+│           │   └── saga-analyst.agent.yaml
+│           ├── workflows/
+│           │   ├── 1-project-brief/
+│           │   ├── 2-trigger-mapping/
+│           │   ├── 3-prd-platform/
+│           │   ├── 4-ux-design/
+│           │   └── 00-system/
+│           ├── getting-started/
+│           └── WDS-WORKFLOWS-GUIDE.md
+└── [your project files]
+```
+
+---
+
+## Step 3: Activate WDS Agent
+
+### In Cursor AI
+
+1. **Open your project** in Cursor
+2. **Start a new chat** with the AI
+3. **Reference the WDS agent** you want to use:
+
+```
+@wds/agents/freya-ux    - For UX Design & Prototyping
+@wds/agents/idunn-pm     - For Product Management & Analysis
+@wds/agents/saga-analyst - For Scenario Analysis
+```
+
+### Example Activation
+
+```
+You: @wds/agents/freya-ux
+
+Agent: 🎨 **Freya - UX Designer**
+
+I'm ready to help you design user experiences!
+
+What would you like to work on?
+- Create interactive prototypes
+- Design scenarios
+- Sketch to specification
+- UX research and analysis
+```
+
+---
+
+## Step 4: Start Your First Workflow
+
+Choose a workflow to start:
+
+### 🎯 **Trigger Map** (Recommended First Step)
+```
+@wds/workflows/trigger-map
+```
+*Understand your users' pain points and triggers*
+
+### 📋 **Product Brief**
+```
+@wds/workflows/product-brief
+```
+*Define your product vision and goals*
+
+### 🎨 **Agentic Development**
+```
+@wds/workflows/agentic-development
+```
+*Build clickable prototypes for testing*
+
+### 📊 **Scenario Analysis**
+```
+@wds/workflows/scenario-init
+```
+*Define and analyze user scenarios*
+
+---
+
+## Verification Checklist
+
+✅ WDS folder exists in `.cursor/rules/wds/`  
+✅ Agent files are present in `agents/` folder  
+✅ Workflows folder contains all 5 workflow directories  
+✅ Can reference `@wds/agents/` in Cursor chat  
+✅ Agent responds when referenced  
+
+---
+
+## Quick Reference
+
+### Agent Launchers
+
+| Agent | Purpose | Reference |
+|-------|---------|-----------|
+| **Freya** | UX Design & Prototyping | `@wds/agents/freya-ux` |
+| **Idunn** | Product Management | `@wds/agents/idunn-pm` |
+| **Saga** | Scenario Analysis | `@wds/agents/saga-analyst` |
+
+### Key Workflows
+
+| Workflow | Purpose | Reference |
+|----------|---------|-----------|
+| **Trigger Map** | User pain points | `@wds/workflows/trigger-map` |
+| **Product Brief** | Product vision | `@wds/workflows/product-brief` |
+| **Prototypes** | Interactive demos | `@wds/workflows/agentic-development` |
+| **Scenario Init** | User journeys | `@wds/workflows/scenario-init` |
+
+---
+
+## Troubleshooting
+
+### ❌ "Can't find @wds/agents/freya-ux"
+
+**Solution:** Check that the folder structure matches Step 2. The path should be:
+```
+.cursor/rules/wds/agents/freya-ux.agent.yaml
+```
+
+### ❌ "Agent doesn't respond"
+
+**Solution:** 
+1. Restart Cursor
+2. Try referencing the agent again with a clear question:
+   ```
+   @wds/agents/freya-ux Can you help me create a prototype?
+   ```
+
+### ❌ "Workflow not found"
+
+**Solution:** Verify all workflow folders are present:
+```
+.cursor/rules/wds/workflows/1-project-brief/
+.cursor/rules/wds/workflows/2-trigger-mapping/
+.cursor/rules/wds/workflows/3-prd-platform/
+.cursor/rules/wds/workflows/4-ux-design/
+.cursor/rules/wds/workflows/00-system/
+```
+
+---
+
+## What's Next?
+
+### 🎓 **Learn WDS Concepts**
+[Course](../course/00-course-overview.md) - Deep dive into WDS methodology
+
+### 🚀 **Start Your First Project**
+[Quick Start](quick-start.md) - 5-minute walkthrough
+
+### 📚 **Explore All Workflows**
+[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md) - Complete workflow documentation
+
+### 🤝 **Join the Community**
+[Discord](https://discord.gg/whiteport) - Get help and share experiences
+
+---
+
+## Optional: Create Project Docs Folder
+
+For a complete setup, create a `docs/` folder in your project:
+
+```bash
+mkdir -p docs/{A-Strategy,B-Requirements,C-Scenarios,D-Prototypes,E-Deliveries}
+```
+
+This gives you a structured place to store all WDS outputs.
+
+---
+
+## Manual vs NPX Installation
+
+| Method | Pros | Cons |
+|--------|------|------|
+| **Manual** | • No dependencies<br>• Full control<br>• Works offline | • Manual updates<br>• Must copy files |
+| **NPX** | • Automatic updates<br>• One command<br>• Always latest | • Requires Node.js<br>• Internet needed |
+
+Both methods give you the **exact same WDS experience**!
+
+---
+
+## Summary
+
+You've successfully initialized WDS manually! 🎉
+
+**You can now:**
+✅ Reference WDS agents in Cursor  
+✅ Run WDS workflows  
+✅ Create conceptual specifications  
+✅ Build interactive prototypes  
+
+**Next:** Try the [Quick Start Guide](quick-start.md) to create your first Trigger Map!
+
+---
+
+[← Back to Getting Started](installation.md) | [Next: Quick Start →](quick-start.md)
+

package/docs/getting-started/about-wds.md

@@ -0,0 +1,86 @@
+# About WDS
+
+**What is Whiteport Design Studio?**
+
+---
+
+## Overview
+
+**Whiteport Design Studio (WDS)** is a design methodology that makes designers indispensable in the AI era.
+
+**The paradigm shift:**
+
+- The design becomes the specification
+- The specification becomes the product
+- The code is just the printout
+
+---
+
+## Who Created It?
+
+**Mårten Angner** - UX designer and founder of Whiteport, a design and development agency in Sweden.
+
+After years of working with AI tools, Mårten observed that traditional design handoffs were breaking down. Designers would create mockups, hand them off to developers, and watch their intent get lost in translation.
+
+WDS solves this by preserving design thinking through AI-ready specifications.
+
+---
+
+## Why It Exists
+
+**The problem:** AI can generate code perfectly, but only if you can clearly define what you want. Unclear specifications lead to AI hallucinations and failed projects.
+
+**The solution:** WDS teaches designers to create conceptual specifications that capture intent, not just appearance.
+
+**The result:** Designers become 5x more productive while maintaining creative control.
+
+---
+
+## How It Works
+
+WDS provides:
+
+- A systematic workflow from product brief to AI-ready specifications
+- Conceptual specifications (WHAT + WHY + WHAT NOT TO DO)
+- AI agents specifically tailored for design work
+- Integration with BMad Method for seamless design-to-development handoff
+
+---
+
+## Free and Open-Source
+
+WDS is completely free and open-source:
+
+- No cost barriers or subscriptions
+- AI agents included
+- Community-driven development
+- Plugin module for BMad Method
+
+**Mission:** Give designers everywhere the tools to thrive in the AI era.
+
+---
+
+## Real-World Proof
+
+**Dog Week project:**
+
+- Traditional approach: 26 weeks, mediocre result
+- WDS approach: 5 weeks, exceptional result
+- **5x speed increase with better quality**
+
+---
+
+## What's Next?
+
+Now that you understand what WDS is, let's get it installed:
+
+**[Continue to Installation →](installation.md)**
+
+Or return to the overview:
+
+**[← Back to Getting Started Overview](getting-started-overview.md)**
+
+---
+
+**Created by Mårten Angner and the Whiteport team**  
+**Free and open-source for designers everywhere**

package/docs/getting-started/agent-activation/activation/step-01-load-agent-definition.md

@@ -0,0 +1,28 @@
+# Step 1: Load Agent Definition
+
+**Purpose**: Embody the agent persona before proceeding
+
+---
+
+## Instruction
+
+Read and fully embody the persona from your agent definition file.
+
+**Your agent definition file**:
+- Saga: `src/modules/wds/agents/saga-analyst.agent.yaml`
+- Freya: `src/modules/wds/agents/freya-ux.agent.yaml`
+- Idunn: `src/modules/wds/agents/idunn-pm.agent.yaml`
+- Mimir: `src/modules/wds/MIMIR-WDS-ORCHESTRATOR.md` (orchestrator file)
+
+**What to do**:
+1. Read the entire agent definition file
+2. Understand your identity, role, and communication style
+3. Embody the persona fully
+
+---
+
+## Next Step
+
+After loading your agent definition, proceed to:
+→ `step-02-check-conversations.md`
+

package/docs/getting-started/agent-activation/activation/step-02-check-conversations.md

@@ -0,0 +1,43 @@
+# Step 2: Check for Active Conversations
+
+**Purpose**: Discover if there are conversations waiting to be resumed
+
+---
+
+## Instruction
+
+Check if there are active conversations to resume.
+
+**Reference**: `src/modules/wds/workflows/project-analysis/conversation-persistence/check-conversations.md`
+
+**What to do**:
+1. Check `docs/.conversations/` folder for files with `status: active`
+2. Filter by relevance (topic, recency, agent)
+3. If conversations found, present options to user
+4. If no conversations found, proceed to next step
+
+---
+
+## Decision Point
+
+**If active conversations found**:
+
+Present options to user:
+- "I see there's an active conversation about [topic] from [time]. Should I pick up from there, or start fresh?"
+
+**If user wants to resume**:
+- Load the conversation file
+- Update status to `picked-up`
+- Continue from where conversation left off
+- **STOP** - Don't proceed to next activation steps
+
+**If user wants to start fresh OR no conversations found**:
+- Continue to next step
+
+---
+
+## Next Step
+
+If no conversations found OR user wants to start fresh:
+→ `step-03-check-activation-context.md`
+

package/docs/getting-started/agent-activation/activation/step-03-check-activation-context.md

@@ -0,0 +1,42 @@
+# Step 3: Check Activation Context
+
+**Purpose**: Determine if this is a handoff or standard activation
+
+---
+
+## Instruction
+
+Check conversation history to see if another agent just handed over with a specific task.
+
+**Reference**: `src/modules/wds/workflows/project-analysis/context-aware-activation.md`
+
+**What to look for**:
+- "Let me hand over to [Your Name]"
+- "User wants to work on: [Task]"
+- "[Previous Agent] specializes in..."
+- "Current Project Status:" already shown
+
+---
+
+## Decision Point
+
+**If handoff context detected**:
+- This is a handoff from another agent
+- User already saw project analysis
+- Proceed to handoff path
+
+**If no handoff context**:
+- This is a standard activation
+- User hasn't seen project analysis yet
+- Proceed to standard path
+
+---
+
+## Next Step
+
+**If handoff detected**:
+→ `step-04-handoff-presentation.md`
+
+**If standard activation**:
+→ `step-04-standard-presentation.md`
+

package/docs/getting-started/agent-activation/activation/step-04-handoff-presentation.md

@@ -0,0 +1,30 @@
+# Step 4: Show Presentation (Handoff Path)
+
+**Purpose**: Introduce yourself when receiving a handoff
+
+---
+
+## Instruction
+
+Show your full presentation even though this is a handoff.
+
+**Why**: Human connection is important, even in handoffs
+
+**Your presentation file**:
+- Saga: `src/modules/wds/data/presentations/saga-presentation.md`
+- Freya: `src/modules/wds/data/presentations/freya-presentation.md`
+- Idunn: `src/modules/wds/data/presentations/idunn-presentation.md`
+- Mimir: `src/modules/wds/agents/presentations/mimir-presentation.md`
+
+**What to do**:
+1. Load and show your full presentation
+2. Include personality, expertise, and philosophy
+3. Then proceed to acknowledge the specific task
+
+---
+
+## Next Step
+
+After showing presentation:
+→ `step-05-handoff-acknowledge.md`
+