whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/steps/step-01-init.md

@@ -0,0 +1,116 @@
+# Step 1: Workflow Initialization
+
+**Progress: Step 1 of 5** - Next: Scenario Definition
+
+## YOUR TASK
+
+Initialize the UX Design workflow by:
+1. Loading project structure metadata from project config
+2. Understanding folder organization requirements
+3. Welcoming the user and determining what to design
+
+---
+
+## CRITICAL: LOAD PROJECT STRUCTURE
+
+**Before greeting the user**, read the project config to understand project structure:
+
+<action>
+Read `{project_root}/config.yaml` (or `{project_root}/wds-workflow-status.yaml`) and extract:
+
+- `project.structure.type` (landing_page | simple_website | web_application)
+- `project.structure.scenarios` (single | multiple)
+- `project.structure.pages` (single | multiple)
+
+Store this in memory for the entire session.
+</action>
+
+**Folder Structure Rules Based on Project Type:**
+
+- **Landing Page** (`scenarios: single`, `pages: single`):
+  - Place pages directly in `4-scenarios/`
+  - Use page variants if needed: `1.1-start-page/`, `1.1-variant-a/`, `1.1-variant-b/`
+  
+- **Simple Website** (`scenarios: single`, `pages: multiple`):
+  - Place pages directly in `4-scenarios/`
+  - Number pages sequentially: `1.1-home/`, `1.2-about/`, `1.3-contact/`
+  
+- **Web Application** (`scenarios: multiple`, `pages: multiple`):
+  - Create scenario subfolders: `4-scenarios/1-onboarding/`, `4-scenarios/2-dashboard/`
+  - Number pages within each scenario: `1.1-signup/`, `1.2-verify-email/`, `2.1-dashboard/`
+
+<reminder>
+This structure was defined during workflow-init. Follow it exactly. Do not create unnecessary subfolders.
+</reminder>
+
+---
+
+## GOAL
+
+Set up the design session and determine what scenario or page the user wants to work on.
+
+---
+
+## EXECUTION
+
+<output>Hi {user_name}! I'm Freya, and I'll help you design and specify your user experience.
+
+**UX Design** transforms ideas into detailed visual specifications. We'll work through each scenario, page by page, creating specifications so complete they eliminate guesswork during development.
+
+**The Design Journey:**
+
+**Step 2: Scenario Definition** - Define the user journey and pages
+**Step 3: Page Design** - Design each page using substeps 4A-4E:
+
+- 4A: Exploration (think through concept)
+- 4B: Sketch Analysis (analyze your sketches)
+- 4C: Specification (document everything)
+- 4D: Prototype (create interactive HTML)
+- 4E: PRD Update (extract requirements)
+  **Step 4: Complete Scenario** - Finalize and celebrate
+  **Step 5: Continue or Exit** - Next steps
+
+**Key principle:** Designs that can be logically explained without gaps are easy to develop. The specification process reveals gaps early - when they're easy to address.
+
+Ready to begin? 🎨</output>
+
+<ask>What would you like to work on?
+
+1. **New scenario** - Start exploring a new user journey
+2. **Continue existing scenario** - Work on a page you've already started
+3. **Review scenario structure** - See what scenarios exist
+
+Choice [1/2/3]:</ask>
+
+---
+
+## MENU HANDLING
+
+### Choice 1: New Scenario
+
+- Proceed to Step 2 (Scenario Structure Setup)
+- Load `steps/step-02-setup-scenario-structure.md`
+
+### Choice 2: Continue Existing
+
+- Ask which scenario/page to continue
+- Determine current status (which substep they're on)
+- Load appropriate step file based on status
+- Skip Step 2 if scenario already defined
+
+### Choice 3: Review Structure
+
+- List scenarios in `{output_folder}/C-Scenarios/`
+- Show completion status for each
+- Return to this menu
+- Do NOT proceed to next step
+
+---
+
+## NEXT STEP
+
+After user selects [1] for new scenario, load `steps/step-02-setup-scenario-structure.md` to begin scenario structure setup.
+
+If user selects [2], determine current state and load appropriate step.
+
+If user selects [3], show structure and return to this step.

package/src/workflows/4-ux-design/steps/step-02-setup-scenario-structure.md

@@ -0,0 +1,67 @@
+# Step 2: Set Up Scenario Structure
+
+**Progress: Step 2 of 5** - Next: Page Design
+
+## YOUR TASK
+
+Route to the appropriate initialization workshop based on project structure.
+
+---
+
+## CRITICAL: READ PROJECT STRUCTURE
+
+<action>
+Read `wds-workflow-status.yaml` and extract:
+- `project_structure.scenarios` (single | multiple)
+- `project_structure.pages` (single | multiple)
+
+Determine project structure type:
+- pages == "single" → SEPARATE_PAGES (individual pages/variants)
+- scenarios == "single" AND pages == "multiple" → SINGLE_FLOW (one scenario, multiple pages)
+- scenarios == "multiple" → MULTIPLE_FLOWS (multiple scenarios)
+
+Store structure_type in memory for this session.
+</action>
+
+---
+
+## ROUTING LOGIC
+
+### Separate Pages (No Scenarios)
+<check if="structure_type == SEPARATE_PAGES">
+  <output>**Project Structure:** Separate pages or variants
+
+You're creating individual pages (like landing pages, dashboards, or page variants). Let's define the first page.</output>
+  
+  <action>Skip scenario-init (no scenarios needed)</action>
+  <action>Load and execute: `step-02-substeps/page-init/step-01-page-context.md`</action>
+</check>
+
+### Single User Flow (One Scenario)
+<check if="structure_type == SINGLE_FLOW">
+  <output>**Project Structure:** Single user flow (multiple pages)
+
+You're creating one continuous user journey across multiple pages. Let's first define the scenario, then the first page.</output>
+  
+  <action>Load and execute: `step-02-substeps/scenario-init/step-01-core-feature.md`</action>
+  <output>(After scenario-init completes, it will automatically route to page-init)</output>
+</check>
+
+### Multiple User Flows (Multiple Scenarios)
+<check if="structure_type == MULTIPLE_FLOWS">
+  <output>**Project Structure:** Multiple user flows (scenarios)
+
+You're creating multiple distinct user journeys, each with their own pages. Let's define the first scenario, then its first page.</output>
+  
+  <action>Load and execute: `step-02-substeps/scenario-init/step-01-core-feature.md`</action>
+  <output>(After scenario-init completes, it will automatically route to page-init)</output>
+</check>
+
+---
+
+## CRITICAL RULES
+
+- 🛑 **NEVER** skip the routing logic
+- 📖 **ALWAYS** read the full substep file before executing
+- 🚫 **NEVER** execute multiple flows
+- ⚠️ **ONLY ONE FLOW** executes based on project structure type

package/src/workflows/4-ux-design/steps/step-02-substeps/page-init/page-init-lightweight.md

@@ -0,0 +1,355 @@
+# Page Init (Lightweight)
+
+**Purpose:** Quick page setup - establish context, create structure, ready for iteration
+
+---
+
+## CONTEXT
+
+**This workflow activates when:** User wants quick page setup without full specification yet.
+
+**Creates:** Minimal structure (name, purpose, navigation, folders) ready for iteration.
+
+**Critical:** Navigation links must be established for page comprehension.
+
+---
+
+## STEP 1: PAGE BASICS
+
+<ask>**What's the name of this page?**
+
+Examples:
+- "Start Page"
+- "Sign In"
+- "Dashboard"
+- "User Profile"
+
+Page name:</ask>
+
+<action>
+Store page_name
+Generate page_slug from page_name (lowercase, hyphenated)
+</action>
+
+---
+
+## STEP 2: PURPOSE & SITUATION
+
+<ask>**What's the PURPOSE of this page?**
+
+What should this page accomplish?
+
+Purpose:</ask>
+
+<action>Store page_purpose</action>
+
+<ask>**What's the USER'S SITUATION when they arrive?**
+
+What just happened? What are they trying to do?
+
+User situation:</ask>
+
+<action>Store user_situation</action>
+
+---
+
+## STEP 3: SCENARIO CONTEXT
+
+<action>
+**Determine scenario context:**
+- Read project structure from wds-workflow-status.yaml
+- Check existing scenarios
+- Determine page placement
+</action>
+
+<check if="multiple_scenarios_exist">
+  <ask>**Which scenario does this page belong to?**
+  
+  Existing scenarios:
+  {{#each scenario in existing_scenarios}}
+  - {{scenario.number}}: {{scenario.name}}
+  {{/each}}
+  
+  Choose scenario [number] or "new" for a new scenario:</ask>
+  
+  <action>Store scenario_number</action>
+</check>
+
+<check if="single_scenario or no_scenarios">
+  <output>This page will be in your main user flow.</output>
+  <action>Set scenario_number = 1</action>
+</check>
+
+---
+
+## STEP 4: NAVIGATION FLOW (CRITICAL!)
+
+<output>**Now let's establish navigation - this is crucial for comprehension!**</output>
+
+<action>
+**Determine page number:**
+- Count existing pages in scenario
+- Calculate next page number
+- Store page_number (e.g., "1.1", "1.2", "2.1")
+</action>
+
+<ask>**What page comes BEFORE this one?**
+
+{{#if existing_pages_in_scenario.length > 0}}
+Existing pages:
+{{#each page in existing_pages_in_scenario}}
+- {{page.number}}: {{page.name}}
+{{/each}}
+
+Type page number, or "none" if this is the first page:
+{{else}}
+This is the first page in the scenario. Type "none":
+{{/if}}
+
+Previous page:</ask>
+
+<action>Store previous_page</action>
+
+<ask>**What page comes AFTER this one?**
+
+- If you know: Type the page name (we'll create it next)
+- If unsure: Type "TBD"
+- If last page: Type "none"
+
+Next page:</ask>
+
+<action>Store next_page</action>
+
+---
+
+## STEP 5: CREATE STRUCTURE
+
+<output>**Creating page structure...**</output>
+
+<action>
+**Create folder structure:**
+
+Path: `4-scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/`
+
+Create:
+1. Page folder: `{{page_number}}-{{page_slug}}/`
+2. Sketches folder: `{{page_number}}-{{page_slug}}/sketches/`
+3. Placeholder document: `{{page_number}}-{{page_slug}}.md`
+</action>
+
+<action>
+**Generate placeholder document:**
+
+File: `4-scenarios/{{scenario_path}}/{{page_number}}-{{page_slug}}/{{page_number}}-{{page_slug}}.md`
+
+Content:
+```markdown
+{{#if previous_page != "none"}}
+← [{{previous_page}}](../{{previous_page_slug}}/{{previous_page_slug}}.md)
+{{/if}}
+{{#if next_page != "none" and next_page != "TBD"}}
+ | [{{next_page}}](../{{next_page_slug}}/{{next_page_slug}}.md) →
+{{/if}}
+{{#if next_page == "TBD"}}
+ | Next: TBD
+{{/if}}
+
+![{{page_name}}](sketches/{{page_slug}}-concept.jpg)
+
+{{#if previous_page != "none"}}
+← [{{previous_page}}](../{{previous_page_slug}}/{{previous_page_slug}}.md)
+{{/if}}
+{{#if next_page != "none" and next_page != "TBD"}}
+ | [{{next_page}}](../{{next_page_slug}}/{{next_page_slug}}.md) →
+{{/if}}
+
+# {{page_number}} {{page_name}}
+
+**User Situation:** {{user_situation}}
+
+**Page Purpose:** {{page_purpose}}
+
+---
+
+## Status
+
+⚠️ **PLACEHOLDER** - This page needs:
+- [ ] Sketch or screenshot
+- [ ] Section breakdown
+- [ ] Object specifications
+- [ ] Component links
+- [ ] Interaction definitions
+- [ ] States and variants
+
+---
+
+## Navigation Context
+
+{{#if previous_page != "none"}}
+**Previous:** {{previous_page}}
+{{else}}
+**This is the first page in the scenario**
+{{/if}}
+
+{{#if next_page == "TBD"}}
+**Next:** TBD (to be defined)
+{{else if next_page != "none"}}
+**Next:** {{next_page}}
+{{else}}
+**This is the last page in the scenario**
+{{/if}}
+
+---
+
+## Open Questions
+
+<!--
+  Auto-populate questions based on page characteristics.
+  Reference: instructions/open-questions.instructions.md
+
+  Check for:
+  - Responsive breakpoints
+  - Loading/Error/Empty states
+  - SEO (if public)
+  - Accessibility
+  - User permissions
+  - Time-sensitive behaviors
+  - Form validation
+  - Navigation/back behavior
+-->
+
+_No open questions at this time._
+
+---
+
+## Next Steps
+
+To complete this page specification:
+
+1. **Add a sketch**: Place your sketch in `sketches/` folder
+2. **Run Page Process Workshop**: Analyze your sketch
+3. **Specify sections**: Define all page sections
+4. **Specify objects**: Define all interactive elements with Object IDs
+5. **Link components**: Connect to design system components
+6. **Document states**: Define loading, error, success, empty states
+7. **Review open-questions.instructions.md**: Add relevant questions to Open Questions section
+8. **Generate prototype**: Create interactive HTML preview
+
+---
+
+{{#if previous_page != "none"}}
+**Previous Step**: ← [{{previous_page}}](../{{previous_page_slug}}/{{previous_page_slug}}.md)
+{{/if}}
+{{#if next_page != "none" and next_page != "TBD"}}
+**Next Step**: → [{{next_page}}](../{{next_page_slug}}/{{next_page_slug}}.md)
+{{/if}}
+
+---
+
+_Placeholder created using Whiteport Design Studio (WDS) methodology_
+```
+</action>
+
+---
+
+## STEP 6: UPDATE NAVIGATION
+
+<check if="previous_page != 'none'">
+  <action>
+  **Update previous page document:**
+  - Open previous page .md file
+  - Update "Next" link to point to this page
+  - Save
+  </action>
+</check>
+
+---
+
+## STEP 7: COMPLETION
+
+<output>✅ **Page initialized!**
+
+**Created:**
+- Folder: `{{page_number}}-{{page_slug}}/`
+- Document: `{{page_number}}-{{page_slug}}.md`
+- Sketches folder: `sketches/`
+
+**Page details:**
+- **Number:** {{page_number}}
+- **Name:** {{page_name}}
+- **Purpose:** {{page_purpose}}
+
+**Navigation:**
+{{#if previous_page != "none"}}
+- Previous: {{previous_page}} ✅ linked
+{{else}}
+- First page in scenario
+{{/if}}
+{{#if next_page != "none" and next_page != "TBD"}}
+- Next: {{next_page}} ✅ linked
+{{else if next_page == "TBD"}}
+- Next: TBD
+{{else}}
+- Last page in scenario
+{{/if}}
+
+---
+
+**Next steps:**
+
+1. **Add your sketch** to `sketches/` folder
+2. **Run Page Process Workshop** to analyze it
+
+Or:
+
+[A] Add sketch now and analyze
+[B] Create another page first
+[C] Back to scenario overview
+
+Choice:</output>
+
+---
+
+## ROUTING
+
+<action>
+Based on user choice:
+- [A] → workshop-page-process.md (with this page context)
+- [B] → Repeat page-init for next page
+- [C] → Return to scenario overview / main menu
+</action>
+
+---
+
+## KEY PRINCIPLES
+
+### ✅ **Navigation is Critical**
+- Appears three times (above sketch, below sketch, document bottom)
+- Links to previous/next pages
+- Creates navigable flow
+- Essential for comprehension
+
+### ✅ **Lightweight Setup**
+- Quick to create
+- No detailed specs yet
+- Just enough to get started
+- Ready for iteration
+
+### ✅ **Context Captured**
+- Name, purpose, situation
+- Scenario placement
+- Page number assigned
+- Flow established
+
+### ✅ **Open Questions Ready**
+- Section included from start
+- Reference `open-questions.instructions.md` during spec creation
+- Auto-populate based on page characteristics
+- Ensures no edge cases are missed
+
+---
+
+**Created:** December 28, 2025  
+**Purpose:** Quick page initialization with navigation  
+**Status:** Ready for WDS Presentation page
+

package/src/workflows/4-ux-design/steps/step-02-substeps/page-init/step-01-page-context.md

@@ -0,0 +1,61 @@
+# Page Init - Entry Point
+
+**Purpose:** Route user to appropriate page creation workflow
+
+---
+
+## ROUTING
+
+<action>
+**Understand from conversation context:**
+
+Check what user has said:
+- Did they mention having a sketch/wireframe/visualization?
+- Did they upload an image file?
+- Are they describing a page concept without visual?
+- Are they asking about creating/defining a page?
+
+**Route based on understanding:**
+
+IF user has sketch/visualization ready:
+  → Load and execute: `step-02-substeps/page-init/workshop-page-process.md`
+     └─> Intelligent context detection
+     └─> New page: Full analysis
+     └─> Updated page: Change detection & incremental update
+
+IF user is describing concept without visualization:
+  → Load and execute: `step-02-substeps/page-init/workshop-page-creation.md`
+     └─> Define page purpose and concept
+     └─> Choose visualization method naturally
+     └─> Create conceptual specification
+
+IF unclear what user wants:
+  → Ask natural clarifying question based on context
+     Example: "Do you have a sketch or wireframe I should look at, or should we define the page concept together?"
+</action>
+
+---
+
+## PHILOSOPHY
+
+**The page is the conceptual entity.**
+
+It has:
+- A purpose (what it accomplishes)
+- A user (who it serves)
+- Sections (what areas exist)
+- Objects (what interactions happen)
+- A place in the flow (navigation)
+
+**Visualization is how we represent the page.**
+
+Methods include:
+- Sketch (hand-drawn or digital)
+- Wireframe (tool-based)
+- ASCII layout (text-based)
+- Verbal description (discussion)
+- Reference (based on existing page)
+
+**Page first. Visualization second.**
+
+---

package/src/workflows/4-ux-design/steps/step-02-substeps/page-init/step-02-page-name.md

@@ -0,0 +1,26 @@
+# Step 2: Page Name
+
+---
+
+<ask>**What's the name of this page?**
+
+Examples:
+- Start Page / Home
+- About
+- Contact
+- Dashboard
+- User Profile
+- Checkout
+- Confirmation
+
+Page name:</ask>
+
+<action>Store page_name</action>
+<action>Generate page_slug from page_name (lowercase, hyphenated)</action>
+<template-output>page_name, page_slug</template-output>
+
+---
+
+<action>Load and execute: `step-02-substeps/page-init/step-03-page-purpose.md`</action>
+
+

package/src/workflows/4-ux-design/steps/step-02-substeps/page-init/step-03-page-purpose.md

@@ -0,0 +1,25 @@
+# Step 3: Page Purpose
+
+---
+
+<ask>**What's the purpose of this page?**
+
+What should this page accomplish?
+
+Examples:
+- Capture user's attention and explain core value
+- Collect contact information for lead generation
+- Guide user through account setup
+- Display personalized dashboard with key metrics
+- Allow user to update their profile settings
+
+Purpose:</ask>
+
+<action>Store page_purpose</action>
+<template-output>page_purpose</template-output>
+
+---
+
+<action>Load and execute: `step-02-substeps/page-init/step-04-entry-point.md`</action>
+
+

package/src/workflows/4-ux-design/steps/step-02-substeps/page-init/step-04-entry-point.md

@@ -0,0 +1,27 @@
+# Step 4: Entry Point
+
+---
+
+<ask>**Where do users arrive from?**
+
+How do users get to this page?
+
+Examples:
+- Google search (external)
+- Social media ad (external)
+- Email link (external)
+- QR code (external)
+- Navigation menu (internal)
+- Previous page in flow (internal)
+- Direct URL (bookmark)
+
+Entry point(s):</ask>
+
+<action>Store entry_point</action>
+<template-output>entry_point</template-output>
+
+---
+
+<action>Load and execute: `step-02-substeps/page-init/step-05-mental-state.md`</action>
+
+

package/src/workflows/4-ux-design/steps/step-02-substeps/page-init/step-05-mental-state.md

@@ -0,0 +1,22 @@
+# Step 5: Mental State
+
+---
+
+<ask>**What's the user's mental state when arriving?**
+
+Consider:
+- What just happened? (trigger)
+- What are they hoping for?
+- What are they worried about?
+- What questions do they have?
+
+Mental state:</ask>
+
+<action>Store mental_state</action>
+<template-output>mental_state</template-output>
+
+---
+
+<action>Load and execute: `step-02-substeps/page-init/step-06-desired-outcome.md`</action>
+
+