whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/steps/step-02-substeps/substeps-guide.md

@@ -0,0 +1,110 @@
+# Step 02 Substeps: Reusable Workshops
+
+This folder contains reusable workshop micro-instructions for scenario and page initialization.
+
+---
+
+## Structure
+
+### scenario-init/
+**Reusable scenario definition workshop** (7 micro-steps)
+
+Used to define a scenario (user flow context):
+- Core feature/experience
+- User entry point
+- Mental state at entry
+- Mutual success goals (business + user)
+- Shortest path (page sequence)
+- Scenario name
+- Create scenario folder structure
+
+**Usage:**
+- **Single page projects:** NOT USED (no scenarios)
+- **Single scenario projects:** Used ONCE (defines the one scenario)
+- **Multiple scenarios projects:** Used MULTIPLE TIMES (scenario 1, 2, 3...)
+
+After completion, automatically routes to `page-init/`.
+
+---
+
+### page-init/
+**Reusable page definition workshop** (8 micro-steps)
+
+Used to define an individual page:
+- Page context (determine scenario, page number)
+- Page name
+- Page purpose/goal
+- Entry point(s)
+- User mental state at entry
+- Desired outcome (business + user goals)
+- Page variants (if any)
+- Create page folder and initial specification document
+
+**Usage:**
+- **Single page projects:** Used MULTIPLE TIMES (separate pages or variants)
+- **Single scenario projects:** Used MULTIPLE TIMES (page 1.1, 1.2, 1.3...)
+- **Multiple scenarios projects:** Used MULTIPLE TIMES (page 1.1, 1.2, 2.1, 2.2...)
+
+The page-init workshop is the fundamental reusable building block for ALL page definitions.
+
+---
+
+## Flow
+
+### Single Page Projects
+```
+step-02-setup-scenario-structure.md
+    ↓
+page-init/ (page 1)
+    ↓
+[User can add more pages]
+    ↓
+page-init/ (page 2)
+```
+
+### Single Scenario Projects
+```
+step-02-setup-scenario-structure.md
+    ↓
+scenario-init/ (define scenario)
+    ↓
+page-init/ (page 1.1)
+    ↓
+[User can add more pages]
+    ↓
+page-init/ (page 1.2)
+```
+
+### Multiple Scenarios Projects
+```
+step-02-setup-scenario-structure.md
+    ↓
+scenario-init/ (scenario 1)
+    ↓
+page-init/ (page 1.1)
+    ↓
+[User can add more pages to scenario 1]
+    ↓
+page-init/ (page 1.2)
+    ↓
+[User can add more scenarios]
+    ↓
+scenario-init/ (scenario 2)
+    ↓
+page-init/ (page 2.1)
+```
+
+---
+
+## Key Design Principles
+
+1. **One question per file** - Prevents agent from skipping steps
+2. **Strict sequential flow** - Each step explicitly loads the next
+3. **Reusable workshops** - Can be called multiple times as project grows
+4. **Clear separation** - Scenario definition vs. page definition
+5. **Context-aware** - Workshops adapt based on project structure
+
+---
+
+**Last Updated:** 2025-12-27
+

package/src/workflows/4-ux-design/steps/step-03-design-page.md

@@ -0,0 +1,189 @@
+# Step 3: Design Page (4A-4E Process)
+
+**Progress: Step 3 of 5** - Page Design Loop
+
+## YOUR TASK
+
+Guide the user through designing one page using the 4A-4E process.
+
+---
+
+## GOAL
+
+Complete one page specification ready for development.
+
+---
+
+## CURRENT PAGE
+
+<action>Load scenario-info.yaml to determine current page</action>
+<action>Display: "Designing page {nn}.{current}: {page-name}"</action>
+
+---
+
+## THE 4A-4E DESIGN PROCESS
+
+Execute substeps in sequence for this page:
+
+### Substep 4A: Exploration (Optional)
+
+<ask>Do you need help exploring the concept before sketching?
+
+1. **Yes** - Think through the concept together
+2. **Skip** - I have sketches or know what I want
+
+Choice [1/2]:</ask>
+
+<check if="choice == 1">
+  <action>Load and execute `substeps/4a-exploration.md`</action>
+  <action>When 4A complete, return here and continue to 4B</action>
+</check>
+
+<check if="choice == 2">
+  <action>Continue to Substep 4B</action>
+</check>
+
+---
+
+### Substep 4B: Sketch Analysis
+
+<ask>Do you have sketches to analyze?
+
+1. **Yes** - I have sketches ready
+2. **Skip** - Go directly to specification
+
+Choice [1/2]:</ask>
+
+<check if="choice == 1">
+  <action>Load and execute `substeps/4b-sketch-analysis.md`</action>
+  <action>When 4B complete, return here and continue to 4C</action>
+</check>
+
+<check if="choice == 2">
+  <action>Continue to Substep 4C</action>
+</check>
+
+---
+
+### Substep 4C: Specification (Required)
+
+<output>**Time to create the complete specification.** 📝
+
+We'll go through this systematically in focused steps:
+
+1. Page basics
+2. Layout sections
+3. Components & Object IDs
+4. Content & languages
+5. Interactions
+6. States
+7. Validation & errors
+8. Generate final document
+
+This ensures nothing is missed and every detail is captured.</output>
+
+<action>Execute substeps in sequence:
+
+1. Load and execute `substeps/4c-01-page-basics.md`
+2. Load and execute `substeps/4c-02-layout-sections.md`
+3. Load and execute `substeps/4c-03-components-objects.md`
+4. Load and execute `substeps/4c-04-content-languages.md`
+5. Load and execute `substeps/4c-05-interactions.md`
+6. Load and execute `substeps/4c-06-states.md`
+7. Load and execute `substeps/4c-07-validation.md`
+8. Load and execute `substeps/4c-08-generate-spec.md`
+   </action>
+
+<action>When all 4C substeps complete, return here and continue to 4D</action>
+
+---
+
+### Substep 4D: HTML Prototype
+
+<ask>Create HTML prototype?
+
+1. **Yes** - Make it interactive
+2. **Skip** - Move to PRD update
+
+Choice [1/2]:</ask>
+
+<check if="choice == 1">
+  <action>Load and execute `substeps/4d-prototype.md`</action>
+  <action>When 4D complete, return here and continue to 4E</action>
+</check>
+
+<check if="choice == 2">
+  <action>Continue to Substep 4E</action>
+</check>
+
+---
+
+### Substep 4E: PRD Update (Required)
+
+<output>**Let's capture the requirements this page revealed.** 📋</output>
+
+<action>Load and execute `substeps/4e-prd-update.md`</action>
+<action>When 4E complete, return here</action>
+
+---
+
+## PAGE COMPLETE
+
+<output>**Page "{page-name}" is complete!** 🎉
+
+**Created:**
+
+- ✅ Specification: `C-Scenarios/{scenario}/{page}/{page}.md`
+  {{#if prototype_created}}
+- ✅ Prototype: `C-Scenarios/{scenario}/{page}/Prototype/`
+  {{/if}}
+- ✅ PRD Requirements: Added to `D-PRD/PRD.md`
+
+**Your page is development-ready!** ✨</output>
+
+---
+
+## NEXT PAGE DECISION
+
+<action>Increment current_page_index in scenario-info.yaml</action>
+<action>Check if more pages remain in scenario</action>
+
+<check if="more_pages_remaining">
+  <ask>**Next page: {next_page_name}**
+
+[C] Continue to next page
+[P] Pause - Save and continue later
+
+Choice [C/P]:</ask>
+
+  <check if="choice == C">
+    <action>Loop back to top of Step 3 with new page</action>
+  </check>
+  
+  <check if="choice == P">
+    <output>Progress saved! Resume anytime. 👍</output>
+    <action>Exit workflow</action>
+  </check>
+</check>
+
+<check if="all_pages_complete">
+  <action>Proceed to Step 4 (Complete Scenario)</action>
+  <action>Load `steps/step-04-complete-scenario.md`</action>
+</check>
+
+---
+
+## STATE MANAGEMENT
+
+After each page:
+
+- Update scenario-info.yaml with current_page_index
+- Mark page as complete in tracking
+- Save progress
+
+---
+
+## NEXT STEP
+
+- If more pages: Loop back to top of Step 3
+- If scenario complete: Load `steps/step-04-complete-scenario.md`

package/src/workflows/4-ux-design/steps/step-04-complete-scenario.md

@@ -0,0 +1,59 @@
+# Step 4: Complete Scenario
+
+**Progress: Step 4 of 5** - Scenario Complete!
+
+## YOUR TASK
+
+Celebrate completion and provide scenario summary.
+
+---
+
+## GOAL
+
+Acknowledge completion and transition to next steps.
+
+---
+
+## EXECUTION
+
+<action>Load scenario-info.yaml to get final statistics</action>
+
+<output>✅ **Scenario "{scenario_name}" complete!**
+
+**Created:**
+
+- Scenario folder: `C-Scenarios/{nn}-{scenario-name}/`
+- Page specifications: {{page_count}} pages
+  {{#if prototype_count > 0}}
+- HTML prototypes: {{prototype_count}} prototypes
+  {{/if}}
+- PRD updates: {{requirements_count}} requirements added
+
+**Each page includes:**
+
+- Complete specification with Object IDs
+- Component definitions
+- Interaction behaviors
+- State definitions
+- Multilingual content
+  {{#if prototype_count > 0}}
+- Interactive prototype
+  {{/if}}
+
+**Your specifications are development-ready!** 🎨</output>
+
+---
+
+## MENU
+
+<ask>What's next?
+
+[C] Continue to Step 5 (Next Steps)
+
+Choice [C]:</ask>
+
+---
+
+## NEXT STEP
+
+When user selects [C], load `steps/step-05-next-steps.md` for workflow completion.

package/src/workflows/4-ux-design/steps/step-05-next-steps.md

@@ -0,0 +1,76 @@
+# Step 5: Next Steps
+
+**Progress: Step 5 of 5** - Workflow Complete!
+
+## YOUR TASK
+
+Guide user to next actions after completing scenario design.
+
+---
+
+## GOAL
+
+Provide clear options for continuing work or exiting.
+
+---
+
+## EXECUTION
+
+<output>**Great design session, {user_name}!** 🎨
+
+Your specifications are saved and ready. What would you like to do next?</output>
+
+---
+
+## MENU
+
+<ask>Choose next action:
+
+1. **Design another scenario** - Continue building your UX
+2. **Phase 5: Design System** - Extract and document components (if enabled)
+3. **Phase 6: PRD Finalization** - Compile all requirements for development handoff
+4. **Review progress** - See all scenarios and completion status
+5. **Exit for now** - Save and continue later
+
+Choice [1/2/3/4/5]:</ask>
+
+---
+
+## MENU HANDLING
+
+### Choice 1: Design Another Scenario
+
+<action>Return to Step 2 (Define Scenario)</action>
+<action>Load `steps/step-02-setup-scenario-structure.md`</action>
+
+### Choice 2: Phase 5 (Design System)
+
+<output>To start Phase 5, activate Freya (WDS Designer) again and run the Design System workflow.</output>
+<action>Exit this workflow</action>
+
+### Choice 3: Phase 6 (PRD Finalization)
+
+<output>To start Phase 6, activate Idunn (WDS PM) and run the PRD Finalization workflow.</output>
+<action>Exit this workflow</action>
+
+### Choice 4: Review Progress
+
+<action>List all scenarios in C-Scenarios/</action>
+<action>Show completion status for each</action>
+<action>Count total pages designed</action>
+<action>Show PRD requirement count</action>
+<ask>Return to menu? [Y]</ask>
+<action>If Y, return to menu in this step</action>
+
+### Choice 5: Exit
+
+<output>Perfect! All your work is saved. Resume anytime by running the UX Design workflow again.
+
+See you next time! 🎨✨</output>
+<action>Exit workflow</action>
+
+---
+
+## WORKFLOW COMPLETE
+
+This is the final step. User either loops to another scenario or exits.

package/src/workflows/4-ux-design/stitch-generation/stitch-prompt.template.md

@@ -0,0 +1,174 @@
+# Stitch Prompt Template
+
+Use this template to prepare an effective Stitch prompt from a WDS specification.
+
+---
+
+## How to Use
+
+1. **Copy this template** into your Stitch dialog
+2. **Fill in each section** using your spec and design system
+3. **Remove Object IDs, translations, technical details** - Stitch doesn't need them
+4. **Keep one language only** - typically the primary language (English or Swedish)
+5. **Paste the filled template** as your Stitch prompt
+
+---
+
+## Template Structure
+
+```
+=== PROJECT CONTEXT ===
+
+App: {App name} - {One-line description}
+Target: {Target audience}
+Brand feel: {2-3 adjectives describing the feel}
+Market: {Market focus if relevant}
+
+=== DESIGN SYSTEM ===
+
+Colors:
+- Background: {color name} ({hex})
+- Primary/CTA: {color name} ({hex})
+- Text: {color name} ({hex})
+- Secondary text: {color name} ({hex})
+- Success: {hex}
+- Error: {hex}
+
+Typography:
+- Font: {font family}
+- Headlines: {weight}, {characteristics}
+- Body: {weight}, {size}
+
+Component styles:
+- Buttons: {style description - rounded, gradient, shadow, etc.}
+- Inputs: {style description - border, focus state, etc.}
+- Cards: {style description if relevant}
+
+=== SCREEN DETAILS ===
+
+Screen: {Screen name}
+Purpose: {What this screen does, one sentence}
+User context: {Where user is coming from, what they need}
+
+Layout structure:
+1. {Section 1}: {elements}
+2. {Section 2}: {elements}
+3. {Section 3}: {elements}
+
+Key elements:
+- {Element 1}: "{Actual content/text}"
+- {Element 2}: "{Actual content/text}"
+- {Element 3}: "{Actual content/text}"
+
+Key interactions:
+- Primary action: {what happens}
+- Secondary action: {what happens}
+
+=== CURRENT STATE NOTES ===
+
+{Note any elements currently using default/unstyled components}
+- {Component}: Currently ShadCN default, should match brand style
+- {Component}: Uses custom gradient button
+
+=== GENERATION INSTRUCTIONS ===
+
+Generate this screen matching:
+- Visual style of the attached reference image
+- Layout structure of the attached sketch
+- All content and elements listed above
+
+Viewport: {Mobile 390px / Desktop 1440px}
+```
+
+---
+
+## Example: Dog Week Sign-In
+
+```
+=== PROJECT CONTEXT ===
+
+App: Dog Week - Family dog walk coordination app
+Target: Swedish families (all ages from teens to grandparents)
+Brand feel: Warm, friendly, trustworthy
+Market: Sweden
+
+=== DESIGN SYSTEM ===
+
+Colors:
+- Background: Cream (#FEF3CF), gradient to #FFFBED
+- Primary/CTA: Orange (#FD6408), gradient #FD8002 to #FF2714
+- Text: Brown (#2F1A0C)
+- Secondary text: Gray (#686868)
+- Success: Green (#28C54A)
+- Error: Red (#DB0000)
+
+Typography:
+- Font: Inter
+- Headlines: Bold/Extra Bold, tight letter spacing
+- Body: Regular weight, 16px base
+
+Component styles:
+- Buttons: Rounded (8px), orange gradient for primary, subtle shadow
+- Inputs: Light background, rounded corners, brown text
+- Cards: Cream background, subtle shadow
+
+=== SCREEN DETAILS ===
+
+Screen: Sign In
+Purpose: Authenticate users with email magic link or Google SSO
+User context: Coming from Start Page, ready to access the app
+
+Layout structure:
+1. Header: Logo (left), Back button (right)
+2. Main form: Email input, magic link button, divider, Google SSO
+3. Trust section: Privacy and security messages
+4. Help links: Support links at bottom
+
+Key elements:
+- Email input label: "Email address"
+- Email placeholder: "your@email.com"
+- Helper text: "We'll send you a magic link to sign in"
+- Primary button: "Send magic link"
+- Divider text: "Or sign in with"
+- Google button: "Continue with Google"
+- Trust message 1: "Your information is secure and private"
+- Trust message 2: "We'll never spam you or share your details"
+- Trust message 3: "Safe for all family members to use"
+
+Key interactions:
+- Primary: Enter email → Send magic link → Check email
+- Secondary: Click Google → OAuth flow → Signed in
+
+=== CURRENT STATE NOTES ===
+
+- Input fields: Currently ShadCN default styling, should use cream background
+- Google button: Should match brand's rounded style with Google colors
+- Trust icons: Need checkmark or shield icons in success green
+
+=== GENERATION INSTRUCTIONS ===
+
+Generate this sign-in screen matching:
+- Visual style of the attached Start Page screenshot (warm, cream, orange CTAs)
+- Layout structure of the attached sketch
+- All content and elements listed above
+
+Viewport: Mobile 390px
+```
+
+---
+
+## Checklist Before Pasting to Stitch
+
+- [ ] Project context filled (app name, target, brand feel)
+- [ ] Design system colors accurate (from Color-Palette.md)
+- [ ] Typography correct (from Typography-System.md)
+- [ ] Component styles described (buttons, inputs)
+- [ ] Screen content in ONE language only (no translations)
+- [ ] No Object IDs included
+- [ ] No technical implementation details
+- [ ] Current state notes added (what's ShadCN default)
+- [ ] Viewport specified
+
+---
+
+_Stitch Prompt Template — Freya WDS Designer_