whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/templates/scenario-overview.template.md

@@ -0,0 +1,159 @@
+# {scenario-number}-{scenario-name}
+
+**Project:** {project-name}  
+**Created:** {date}  
+**Method:** Whiteport Design Studio (WDS)
+
+---
+
+## Scenario Overview
+
+**User Journey:** {High-level description of what users accomplish in this scenario}
+
+**Entry Point:** {Where users begin this scenario}  
+**Success Exit:** {Where users end after successful completion}  
+**Alternative Exits:** {Other possible endpoints - errors, cancellations, etc.}
+
+**Target Personas:** {Which personas from Trigger Map use this scenario}
+
+---
+
+## Pages in This Scenario
+
+| Page # | Page Name   | Status           | Purpose         |
+| ------ | ----------- | ---------------- | --------------- |
+| {n}.1  | {page-name} | {draft/complete} | {Brief purpose} |
+| {n}.2  | {page-name} | {draft/complete} | {Brief purpose} |
+| {n}.3  | {page-name} | {draft/complete} | {Brief purpose} |
+
+---
+
+## User Flow
+
+```mermaid
+flowchart TD
+    A[{Entry Point}] --> B[{Page n.1}]
+    B --> C[{Page n.2}]
+    C --> D{{Decision Point?}}
+    D -->|Yes| E[{Page n.3}]
+    D -->|No| F[{Alternative Path}]
+    E --> G[{Success Exit}]
+    F --> G
+```
+
+---
+
+## Scenario Steps
+
+### Step 1: {Step Name}
+
+**Page:** {n.1-Page-Name}  
+**User Action:** {What the user does}  
+**System Response:** {How the system responds}  
+**Success Criteria:** {What defines success for this step}
+
+### Step 2: {Step Name}
+
+**Page:** {n.2-Page-Name}  
+**User Action:** {What the user does}  
+**System Response:** {How the system responds}  
+**Success Criteria:** {What defines success for this step}
+
+{Repeat for all steps}
+
+---
+
+## Trigger Map Connections
+
+### Positive Drivers Addressed
+
+From Trigger Map analysis, this scenario serves these user goals:
+
+- ✅ {Positive goal from Trigger Map}
+- ✅ {Positive goal from Trigger Map}
+
+### Negative Drivers Avoided
+
+This scenario helps users avoid:
+
+- ❌ {Negative outcome from Trigger Map}
+- ❌ {Negative outcome from Trigger Map}
+
+---
+
+## Success Metrics
+
+**Primary Metric:** {Main measure of scenario success}
+
+**Secondary Metrics:**
+
+- {Metric 1}
+- {Metric 2}
+
+**User Satisfaction Indicators:**
+
+- {What indicates good user experience}
+
+---
+
+## Edge Cases & Error Handling
+
+| Edge Case               | How Handled         | Page(s) Affected  |
+| ----------------------- | ------------------- | ----------------- |
+| {edge-case-description} | {handling-approach} | {page-references} |
+
+---
+
+## Technical Requirements
+
+### Data Flow
+
+```
+{Entry} → [Fetch Data] → {Display} → [User Action] → [Validate] → [API Call] → {Success}
+```
+
+### API Endpoints Used
+
+| Endpoint        | Page(s)     | Purpose        |
+| --------------- | ----------- | -------------- |
+| {endpoint-path} | {page-refs} | {what-it-does} |
+
+### State Management
+
+{How state is managed across pages in this scenario}
+
+---
+
+## Design Assets
+
+**Scenario Folder:** `C-Scenarios/{scenario-number}-{scenario-name}/`
+
+**Page Specifications:**
+
+- {n}.1-{page-name}/{page-name}.md
+- {n}.2-{page-name}/{page-name}.md
+- {n}.3-{page-name}/{page-name}.md
+
+**Prototypes:**
+
+- {n}.1-{page-name}/Prototype/
+- {n}.2-{page-name}/Prototype/
+- {n}.3-{page-name}/Prototype/
+
+---
+
+## Development Notes
+
+{Any scenario-level technical considerations, performance requirements, security notes, etc.}
+
+---
+
+## Revision History
+
+| Date   | Changes                  | Author   |
+| ------ | ------------------------ | -------- |
+| {date} | Initial scenario created | {author} |
+
+---
+
+_Created using Whiteport Design Studio (WDS) methodology_

package/src/workflows/4-ux-design/templates/storyboard-specification.template.md

@@ -0,0 +1,94 @@
+# Storyboard Extension
+
+**Use when:** Page has multiple sketches (multi-step flows, state changes, transitions)
+
+**Base:** Start with [page-specification.template.md](page-specification.template.md)
+
+---
+
+## What Changes
+
+### 1. Add State Flow Overview (before Page Sections)
+
+After Reference Materials, add:
+
+```markdown
+## State Flow Overview
+
+{Brief description of states}
+
+![Overview](Sketches/{page-number}-{page-name}-Overview.jpg)
+
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│  STATE 1    │───▶│  STATE 2    │───▶│  STATE 3    │
+└─────────────┘    └─────────────┘    └─────────────┘
+
+| State | Name | Visual | Entry | Actions |
+|-------|------|--------|-------|---------|
+| **1** | {name} | {color/icon} | {trigger} | {actions} |
+| **2** | {name} | {color/icon} | {trigger} | {actions} |
+```
+
+---
+
+### 2. State 1 = Normal Page Specification
+
+Document State 1 using the standard page spec structure:
+- Page Sections
+- Objects with OBJECT IDs
+- Groups with nested objects
+
+This is the **baseline** that other states reference.
+
+---
+
+### 3. States 2+ = Differences Only
+
+After State 1, add for each additional state:
+
+```markdown
+# State 2: {State Name} — Differences from State 1
+
+![State 2](Sketches/{page-number}-{page-name}-2-{state-name}.jpg)
+
+> **The Story:** {User experience narrative}
+
+| Property | Value |
+|----------|-------|
+| Purpose | {what this state does} |
+| Entry | {trigger from previous state} |
+| Previous | State 1 |
+| Next | State 3 / {options} |
+
+### Changes from State 1
+
+| OBJECT ID | Change | Details |
+|-----------|--------|---------|
+| `{existing-id}` | Modified | {what changed} |
+| `{existing-id}` | Hidden | {why hidden} |
+| `{new-id}` | Added | {new element} |
+
+### State 2 Elements
+
+{Only document NEW objects not in State 1}
+
+#### {New Object}
+
+**OBJECT ID:** `{page-name}-{new-object}`
+
+| Property | Value |
+|----------|-------|
+| Component | [{Component}]({path}) |
+| Translation Key | `{key}` |
+| SE | "{text}" |
+| EN | "{text}" |
+```
+
+---
+
+## Key Principles
+
+1. **State 1 is baseline** — fully documented
+2. **States 2+ show only changes** — reuse OBJECT IDs
+3. **Same IDs across states** — `booking-detail-header` stays the same, just describe what changed
+4. **New elements get new IDs** — only in the state they first appear

package/src/workflows/4-ux-design/ux-design-guide.md

@@ -0,0 +1,223 @@
+# Phase 4: UX Design Workflow
+
+**Freya's domain - From sketch to specification**
+
+---
+
+## Overview
+
+Phase 4 transforms sketches and ideas into detailed, developer-ready page specifications with multi-language support.
+
+---
+
+## Workflow Steps
+
+| Step                  | File                           | Purpose                                   |
+| --------------------- | ------------------------------ | ----------------------------------------- |
+| **Init**              | `step-01-init.md`              | Welcome, load context, initialize session |
+| **Define Scenario**   | `step-02-define-scenario.md`   | Plan user journey and pages               |
+| **Design Page**       | `step-03-design-page.md`       | Orchestrate 4A-4E substeps per page       |
+| **Complete Scenario** | `step-04-complete-scenario.md` | Finalize and summarize scenario           |
+| **Next Steps**        | `step-05-next-steps.md`        | Continue or exit workflow                 |
+
+---
+
+## Substeps (4A-4E)
+
+### 4A: Exploration
+
+**File:** `substeps/4a-exploration.md`
+
+- Think through user journey
+- Clarify context and goals
+
+### 4B: Sketch Analysis
+
+**File:** `substeps/4b-sketch-analysis.md`
+
+- **Section-first approach:** AI reads entire sketch, identifies all sections
+- User confirms structure
+- Section-by-section AI interpretation
+- User refinement dialog
+
+### 4C: Specification (Micro-steps 01-08)
+
+**Files:** `substeps/4c-01-page-basics.md` through `4c-08-generate-spec.md`
+
+1. **Page Basics** - Name, purpose, route
+2. **Layout** - Structure, grid, responsive
+3. **Components** - Identify objects, route to object-type instructions
+4. **Content** - Text, images, media with translations
+5. **Interactions** - Behaviors, events, state changes
+6. **States** - Loading, error, empty, success
+7. **Validation** - Rules, messages, error handling
+8. **Generate Spec** - Complete page specification
+
+### 4D: Prototype
+
+**File:** `substeps/4d-prototype.md`
+
+- Generate interactive HTML prototype
+- Uses Design System if enabled
+- **Visual refinement option:** Extract to Figma via MCP server if design system incomplete
+- Iterative refinement: Prototype → Figma → Design System → Re-render
+- See: `workflows/5-design-system/figma-integration/prototype-to-figma-workflow.md`
+
+### 4E: PRD Update
+
+**File:** `substeps/4e-prd-update.md`
+
+- Extract functional requirements
+- Update Product Requirements Document
+
+---
+
+## Object Type Instructions
+
+**Location:** `object-types/`
+
+Each object type has a dedicated instruction file:
+
+| File               | Purpose                                              |
+| ------------------ | ---------------------------------------------------- |
+| `object-router.md` | Detects object types, routes to appropriate file     |
+| `button.md`        | Button specification                                 |
+| `text-input.md`    | Input field specification                            |
+| `link.md`          | Link/anchor specification                            |
+| `heading-text.md`  | Text element specification with purpose-based naming |
+| `image.md`         | Image specification                                  |
+
+**Key Features:**
+
+- Purpose-based naming (function over content)
+- Grouped translations (coherent language blocks)
+- Design System integration (use existing, create new, or page-specific)
+- Text placeholder analysis (line thickness → font weight, spacing → font size)
+
+---
+
+## Templates
+
+**Location:** `templates/`
+
+| File                             | Purpose                          |
+| -------------------------------- | -------------------------------- |
+| `page-specification.template.md` | Complete page spec output format |
+| `scenario-overview.template.md`  | Scenario summary format          |
+
+---
+
+## Documentation
+
+| File                                | Purpose                                                  |
+| ----------------------------------- | -------------------------------------------------------- |
+| `ARCHITECTURE.md`                   | Complete workflow architecture overview                  |
+| `WDS-SPECIFICATION-PATTERN.md`      | **Standard specification format** (Dog Week as example)  |
+| `TRANSLATION-ORGANIZATION-GUIDE.md` | Purpose-based text organization and grouped translations |
+| `SKETCH-TEXT-ANALYSIS-GUIDE.md`     | How to interpret text markers in sketches                |
+| `SKETCH-TEXT-QUICK-REFERENCE.md`    | Quick reference for text analysis                        |
+| `SKETCH-TEXT-STRATEGY.md`           | When to use actual text vs. line markers                 |
+| `PROACTIVE-TRANSLATION-WORKFLOW.md` | How agent suggests translations                          |
+| `ROUTER-FLOW-DIAGRAM.md`            | Visual flow of object routing with examples              |
+
+---
+
+## Key Patterns
+
+### 1. Section-First Workflow
+
+- AI reads entire sketch → identifies sections
+- User confirms structure
+- Section-by-section interpretation
+- User refines details
+- Batch generation of specs
+
+### 2. Purpose-Based Naming
+
+- Name text by **function**, not content
+- `hero-headline` not `welcome-message`
+- `form-error` not `invalid-email-text`
+
+### 3. Grouped Translations
+
+```markdown
+#### Primary Headline
+
+**Content**:
+
+- EN: "Welcome to Dog Week"
+- SE: "Välkommen till Hundveckan"
+```
+
+### 4. Design System Integration
+
+For each object:
+
+1. Use existing component
+2. Create new component (mark for Phase 5)
+3. Page-specific only
+
+### 5. Text Marker Analysis
+
+- **2 lines together** = 1 line of text
+- **Line thickness** = font weight (thick = bold)
+- **Spacing between pairs** = font size
+- **Line count** = number of text lines
+
+---
+
+## Multi-Language Support
+
+**Configuration:** Set in `workflow-init`
+
+- **Specification Language**: Language for writing specs (EN, SE, etc.)
+- **Product Languages**: Languages the product supports (array)
+
+**All text objects include translations for every product language.**
+
+See: `LANGUAGE-CONFIGURATION-GUIDE.md` in workflows folder
+
+---
+
+## Example: Dog Week Start Page
+
+The complete Dog Week Start Page specification demonstrates the pattern in action.
+
+**See:** `WDS-SPECIFICATION-PATTERN.md`
+
+---
+
+## v6 Best Practices
+
+✅ **Goal-based instructions** - Trust the agent to interpret
+✅ **Micro-file design** - Small, focused instruction files
+✅ **Just-in-time loading** - Only current step in memory
+✅ **State tracking** - Progress in output file frontmatter
+✅ **Show don't tell** - Examples over explanations
+
+---
+
+## Output Structure
+
+```
+docs/
+  C-Scenarios/
+    {scenario-name}/
+      00-{scenario-name}-overview.md
+      01-{page-name}.md
+      02-{page-name}.md
+      ...
+```
+
+Each page spec includes:
+
+- Page metadata and purpose
+- All sections with objects
+- Complete multi-language content
+- Component references (if Design System enabled)
+- Interaction behaviors
+- States and validation rules
+
+---
+
+**Phase 4 Status:** ✅ **COMPLETE** (December 6, 2025)

package/src/workflows/4-ux-design/workflow-new.yaml

@@ -0,0 +1,18 @@
+---
+name: UX Design Workflow
+description: Transform ideas into detailed visual specifications through scenario-driven design using step-file architecture
+main_config: "{project-root}/{bmad_folder}/wds/config.yaml"
+web_bundle: true
+---
+# Workflow configuration for UX Design process
+# This workflow handles the complete UX design phase from concept to implementation
+
+phases:
+  - phase_1_project_brief
+  - phase_2_trigger_mapping
+  - phase_3_prd_platform
+  - phase_4_ux_design
+  - phase_5_design_system
+  - phase_6_design_deliveries
+  - phase_7_testing
+  - phase_8_ongoing_development

package/src/workflows/4-ux-design/workflow.md

@@ -0,0 +1,61 @@
+---
+name: UX Design Workflow
+description: Transform ideas into detailed visual specifications through scenario-driven design
+main_config: '{project-root}/{bmad_folder}/wds/config.yaml'
+web_bundle: true
+---
+
+# UX Design Workflow
+
+**Goal:** Create development-ready specifications through scenario-driven design with Freya the WDS Designer.
+
+**Your Role:** You are Freya, a creative and thoughtful UX designer collaborating with the user. This is a partnership - you bring design expertise and systematic thinking, while the user brings product vision and domain knowledge. Work together as equals.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self-contained instruction file that is part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in scenario tracking file
+- **Goal-Based Trust**: Trust the agent to achieve the goal, provide guidance not procedures
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: Only proceed to next step when user explicitly chooses to continue
+5. **SAVE STATE**: Update scenario tracking before loading next step
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update scenario tracking when completing steps
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from {main_config} and resolve:
+
+- `project_name`, `output_folder`, `user_name`
+- `communication_language`, `document_output_language`
+- `date` as system-generated current datetime
+
+### 2. First Step Execution
+
+Load, read the full file and then execute `steps/step-01-init.md` to begin the workflow.

package/src/workflows/4-ux-design/workflow.yaml

@@ -0,0 +1,18 @@
+---
+name: UX Design Workflow
+description: Transform ideas into detailed visual specifications through scenario-driven design using step-file architecture
+main_config: "{project-root}/{bmad_folder}/wds/config.yaml"
+web_bundle: true
+---
+# Workflow configuration for UX Design process
+# This workflow handles the complete UX design phase from concept to implementation
+
+phases:
+  - phase_1_project_brief
+  - phase_2_trigger_mapping
+  - phase_3_prd_platform
+  - phase_4_ux_design
+  - phase_5_design_system
+  - phase_6_design_deliveries
+  - phase_7_testing
+  - phase_8_ongoing_development