diff --git a/WDS-V6-CONVERSION-ROADMAP.md b/WDS-V6-CONVERSION-ROADMAP.md index 4ae0472f..3dda319c 100644 --- a/WDS-V6-CONVERSION-ROADMAP.md +++ b/WDS-V6-CONVERSION-ROADMAP.md @@ -3,8 +3,8 @@ **Document Purpose:** Complete record of all decisions, context, and progress for converting Whiteport Design Studio to BMad Method v6 format. This document allows continuation of work if the conversation is lost. **Created:** December 2, 2025 -**Last Updated:** December 3, 2025 -**Status:** In Progress - Examples Phase +**Last Updated:** December 5, 2025 +**Status:** In Progress - Workflows Phase (Phase 4 Complete + Dog Week Pattern) --- @@ -538,8 +538,13 @@ Includes: #### Phase 3: Create Workflows | Order | Component | Location | Status | |-------|-----------|----------|--------| -| 11 | workflow-init | `workflows/0-init/` | TO CREATE | -| 12 | Phase Workflows | `workflows/1-6/` | TO CREATE | +| 11 | workflow-init | `workflows/workflow-init/` | ✅ COMPLETE | +| 12a | Phase 1 Workflow | `workflows/1-project-brief/` | ✅ COMPLETE | +| 12b | Phase 2 Workflow | `workflows/2-trigger-mapping/` | ✅ COMPLETE | +| 12c | Phase 3 Workflow | `workflows/3-prd-platform/` | ✅ COMPLETE | +| 12d | **Phase 4 Workflow** | `workflows/4-ux-design/` | ✅ **COMPLETE (Dec 4)** | +| 12e | Phase 5 Workflow | `workflows/5-design-system/` | TO CREATE | +| 12f | Phase 6 Workflow | `workflows/6-integration/` | TO CREATE | #### Phase 4: Create Agents (The Norse Pantheon) | Order | Component | File | Status | @@ -584,10 +589,19 @@ Includes: | `src/modules/wds/` | Module root | ✅ CREATED | | `src/modules/wds/README.md` | Module entry point | ✅ CREATED | | `src/modules/wds/_module-installer/` | Install config folder | EMPTY | -| `src/modules/wds/agents/` | Agents folder | EMPTY | -| `src/modules/wds/workflows/` | Workflows folder | EMPTY | +| `src/modules/wds/agents/` | Agents folder | PARTIAL (saga skeleton) | +| `src/modules/wds/workflows/` | Workflows folder | ✅ **PHASE 4 COMPLETE** | +| `src/modules/wds/workflows/workflow-init/` | Workflow initialization | ✅ COMPLETE | +| `src/modules/wds/workflows/1-project-brief/` | Phase 1 workflow | ✅ COMPLETE | +| `src/modules/wds/workflows/2-trigger-mapping/` | Phase 2 workflow | ✅ COMPLETE | +| `src/modules/wds/workflows/3-prd-platform/` | Phase 3 workflow | ✅ COMPLETE | +| `src/modules/wds/workflows/4-ux-design/` | **Phase 4 workflow** | ✅ **COMPLETE (Dec 4)** | +| `src/modules/wds/workflows/4-ux-design/substeps/` | **Phase 4 substeps (4A-4E)** | ✅ **COMPLETE (Dec 4)** | +| `src/modules/wds/workflows/4-ux-design/templates/` | **Phase 4 templates** | ✅ **COMPLETE (Dec 4)** | +| `src/modules/wds/workflows/5-design-system/` | Phase 5 workflow | TO CREATE | +| `src/modules/wds/workflows/6-integration/` | Phase 6 workflow | TO CREATE | | `src/modules/wds/data/` | Data folder | EMPTY | -| `src/modules/wds/data/presentations/` | Agent presentations | EMPTY | +| `src/modules/wds/data/presentations/` | Agent presentations | TO CREATE | | `src/modules/wds/docs/method/` | Methodology guides | ✅ COMPLETE | | `src/modules/wds/docs/images/` | Images folder | EMPTY | | `src/modules/wds/examples/` | Examples folder | EMPTY | @@ -610,27 +624,41 @@ Includes: 1. [x] Create `wds-method-guide.md` 2. [x] Create phase guide for each phase (6 files) 3. [x] Refine all phase guides with positive language, proper naming -4. [ ] Create WDS Trigger Map (meta-example for WDS itself) -5. [ ] Create conversation examples -6. [x] Create workflow-init workflow ✅ -7. [ ] Create phase workflows (1-6) -8. [ ] Create agents (Saga, Freyja, Baldr) -9. [ ] Create templates for component showcase, PRD, etc. -10. [ ] Port Dog Week examples to `examples/dog-week-patterns/` (last - project in active development) +4. [x] Create workflow-init workflow ✅ +5. [x] Create Phase 1-3 workflows ✅ +6. [x] **Create Phase 4 workflow (UX Design)** ✅ **COMPLETE Dec 4, 2025** +7. [ ] Create Phase 5-6 workflows +8. [ ] Create WDS Trigger Map (meta-example for WDS itself) +9. [ ] Create conversation examples +10. [ ] Create agents (Saga, Freyja, Baldr) +11. [ ] Create templates for component showcase, PRD, etc. +12. [ ] Port Dog Week examples to `examples/dog-week-patterns/` (last - project in active development) ### Commit Checkpoint -Ready to commit methodology phase: +**Ready to commit Phase 4 workflow:** ``` -feat(wds): Complete WDS methodology documentation +feat(wds): Complete Phase 4 UX Design workflow with v6 best practices -- All 6 phase guides complete with positive language -- Feature Impact Analysis with scoring (Phase 2) -- Step 4E: PRD Update during design (Phase 4) -- Design System as optional parallel workflow (Phase 5) -- PRD Finalization with continuous handoff (Phase 6) -- Unified naming conventions for Figma/Code -- Main method guide updated +Phase 4 Workflow Complete: +- Main workflow with goal-based instructions +- Substeps 4A-4E following v6 patterns (exploration, analysis, specification, prototype, PRD update) +- Complete page specification template with Object IDs +- Scenario overview template +- Concise, trust-the-agent instruction style +- Optional steps where appropriate + +Conversion Progress: +- Merged WDS-CONVERSION-ANALYSIS.md into roadmap +- Updated roadmap with Phase 4 completion status +- Added section 11: WPS2C → WDS Conversion Reference +- Added section 12: Latest Updates (Dec 4, 2025) + +Templates Created: +- page-specification.template.md (complete spec format) +- scenario-overview.template.md (scenario structure) + +Next: Phase 5 (Design System) and Phase 6 (PRD Finalization) workflows ``` --- @@ -748,7 +776,358 @@ Our product (statement of primary differentiators) --- +## 11. WPS2C → WDS Conversion Reference + +### 11.1 Agent Mapping + +| WPS2C v4 | WDS v6 | Status | +|----------|--------|--------| +| Mary (whiteport-analyst.md) | Saga-Analyst (saga-analyst.agent.yaml) | 🔄 Skeleton exists | +| Sarah (whiteport-pm.md) | Freyja-PM (freyja-pm.agent.yaml) | ⏳ To create | +| Sally (whiteport-ux-expert.md) | Baldr-UX (baldr-ux.agent.yaml) | ⏳ To create | +| James (whiteport-dev.md) | N/A - moved to BMM | ✅ Complete | +| Alex (whiteport-orchestrator.md) | N/A - workflow-status replaces | ✅ Complete | + +**Key Changes:** +- Mary → **Saga** (Goddess of stories & wisdom) +- Sarah → **Freyja** (Goddess of love, war & strategy) +- Sally → **Baldr** (God of light & beauty) +- Norse Pantheon theme for unique WDS identity + +### 11.2 File Format Changes + +**WPS2C v4:** Markdown files (.md) with embedded YAML blocks +```markdown +# agent-name.md +```yaml +agent: + name: Mary + commands: + - help: Show help +``` +``` + +**WDS v6:** Pure YAML files (.agent.yaml) following v6 schema +```yaml +# agent-name.agent.yaml +agent: + metadata: + id: "{bmad_folder}/wds/agents/saga-analyst.agent.yaml" + name: Saga + module: wds + persona: + role: ... + identity: ... + menu: + - trigger: command-name + workflow: path/to/workflow.yaml +``` + +### 11.3 Terminology Changes + +| WPS2C v4 | WDS v6 | +|----------|--------| +| Whiteport Sketch-to-Code | Whiteport Design Studio | +| WPS2C | WDS | +| Commands | Menu Triggers | +| Tasks | Workflows | +| `*command-name` | Workflow triggers | + +### 11.4 Presentation Files Mapping + +| WPS2C v4 File | WDS v6 Location | Purpose | +|---------------|-----------------|---------| +| mary-analyst-personal-presentation.md | data/presentations/saga-intro.md | Saga activation speech | +| sarah-pm-personal-presentation.md | data/presentations/freyja-intro.md | Freyja activation speech | +| sally-ux-expert-personal-presentation.md | data/presentations/baldr-intro.md | Baldr activation speech | +| wps2c-analyst-business-presentation.md | examples/conversation-examples/analyst-session.md | Example session | +| wps2c-pm-product-presentation.md | examples/conversation-examples/pm-session.md | Example session | +| wps2c-ux-design-system-presentation.md | examples/conversation-examples/ux-session.md | Example session | + +### 11.5 Templates Mapping + +| WPS2C v4 Template | WDS v6 Location | Status | +|-------------------|-----------------|--------| +| product-brief-tmpl.yaml | workflows/1-project-brief/complete/project-brief.template.md | ✅ Created | +| trigger-map-tmpl.yaml | workflows/2-trigger-mapping/templates/trigger-map.template.md | ✅ Created | +| persona-tmpl.yaml | workflows/2-trigger-mapping/templates/persona.template.md | ⏳ To create | +| scenarios-tmpl.yaml | workflows/4-ux-design/templates/scenario-overview.template.md | ✅ **Created Dec 4** | +| page-spec-tmpl.yaml | workflows/4-ux-design/templates/page-specification.template.md | ✅ **Created Dec 4** | +| design-system-structure-tmpl.yaml | workflows/5-design-system/templates/component.template.md | ⏳ To create | +| component-tmpl.yaml | reference/templates/component.template.md | ⏳ To create | +| sketch-review-tmpl.yaml | workflows/4-ux-design/templates/review.template.md | ⏳ To create | + +### 11.6 Standards/Data Files Mapping + +| WPS2C v4 File | WDS v6 Location | Purpose | +|---------------|-----------------|---------| +| wps2c-compliance-standards.md | data/wds-standards.md | Core methodology standards | +| analyst-documentation-standards.md | data/documentation-standards.md | Documentation conventions | +| sketch-documentation-standards.md | workflows/4-ux-design/sketch-standards.md | Sketch specification standards | +| pm-documentation-standards.md | workflows/3-prd-platform/prd-standards.md | PRD writing standards | +| mermaid-github-standards.md | data/mermaid-standards.md | Diagram standards | +| technical-documentation-patterns.md | data/technical-patterns.md | Technical writing patterns | + +### 11.7 Content to Preserve from WPS2C + +**Core Methodology Elements:** ✅ +- Product Brief structure and process +- Trigger Mapping (Effect Mapping) methodology +- Feature Impact Analysis with scoring +- Scenario-driven design approach +- Design System integration patterns + +**Agent Personalities:** 🔄 +- Mary's analytical, thoughtful approach → Saga +- Sarah's strategic PM mindset → Freyja +- Sally's design expertise and creativity → Baldr + +**Quality Patterns:** ✅ +- One question at a time (not survey-style) +- Collaborative document building +- Evidence-based analysis +- Soft, encouraging language + +**Technical Patterns:** ✅ +- A-B-C-D-E folder structure +- Title-Case-With-Dashes naming +- Professional markdown formatting +- Mermaid diagram standards + +### 11.8 Key Improvements in WDS v6 + +**1. Soft Language Design Philosophy** +- Removed MUST/FORBIDDEN/NEVER language +- Identity-based persona definitions +- Collaborative, not interrogative approach +- Positive framing (enables vs prevents) + +**2. Example-Driven Learning** +- Complete reference implementations +- Conversation flow examples +- Real project patterns (Dog Week) +- Starter projects for practice + +**3. Phase Flexibility** +- Phase-selectable (not rigid tracks) +- Path presets for common scenarios +- Optional phases (Design System) +- Parallel workflows supported + +**4. Better Integration** +- Clean handoff to BMM via E-UI-Roadmap +- No development artifacts in design module +- Clear separation of concerns +- Continuous handoff model + +**5. Professional Tooling** +- Proper v6 YAML schema compliance +- Workflow validation support +- Installation via BMad CLI +- Module ecosystem integration + +### 11.9 Migration Notes + +**Breaking Changes:** +- Agent activation syntax changes (*command → workflow trigger) +- File format changes (.md → .agent.yaml) +- Folder structure reorganization +- Terminology updates throughout + +**Backward Compatibility:** +- WPS2C v4 users must migrate to WDS v6 +- No automatic migration path +- Dog Week project uses mixed terminology (in transition) +- Old repo remains for reference + +**User Communication:** +- WDS is evolution, not replacement +- Same methodology, better implementation +- Migration guide needed for v4 users +- Clear benefits explanation + +--- + +## 12. Latest Updates (December 5, 2025) + +### Phase 4 Workflow - Dog Week Pattern Implementation ✅ + +#### Phase 4 Architecture (December 4) + +**Step-File Architecture:** +- `workflows/4-ux-design/workflow.yaml` - Main workflow configuration +- `workflows/4-ux-design/workflow.md` - Workflow orchestrator +- `workflows/4-ux-design/steps/step-01-init.md` - Workflow initialization +- `workflows/4-ux-design/steps/step-02-define-scenario.md` - Scenario structure +- `workflows/4-ux-design/steps/step-03-design-page.md` - Page design orchestration +- `workflows/4-ux-design/steps/step-04-complete-scenario.md` - Scenario completion +- `workflows/4-ux-design/steps/step-05-next-steps.md` - Next actions + +**4C Micro-Steps (Specification Breakdown):** +- `substeps/4c-01-page-basics.md` - Page basic information +- `substeps/4c-02-layout-sections.md` - Layout sections definition +- `substeps/4c-03-components-objects.md` - Components & objects identification +- `substeps/4c-04-content-languages.md` - Content & language specs +- `substeps/4c-05-interactions.md` - Interaction definitions +- `substeps/4c-06-states.md` - Object states +- `substeps/4c-07-validation.md` - Validation rules +- `substeps/4c-08-generate-spec.md` - Final spec generation + +#### Dog Week Pattern Implementation (December 5) + +**Purpose-Based Text Organization:** +- `object-types/heading-text.md` - Updated with purpose-based naming +- `object-types/object-router.md` - Enhanced with intelligent interpretation +- Text objects named by FUNCTION, not content (e.g., `start-hero-headline` not `welcome-text`) +- Structure (position/style) separated from content +- Translations grouped so each language reads coherently + +**Sketch Text Analysis:** +- Horizontal line detection → text placeholders +- Line thickness → font size estimation +- Line spacing → line-height calculation +- Character capacity estimation for content validation +- `SKETCH-TEXT-ANALYSIS-GUIDE.md` - Complete analysis methodology + +**Translation Grouping:** +- Text groups keep languages together +- Each language reads as complete, coherent message +- Dog Week format standardized across all projects +- `TRANSLATION-ORGANIZATION-GUIDE.md` - Complete translation pattern +- `DOG-WEEK-SPECIFICATION-PATTERN.md` - Full workflow integration example + +**Object Type Instructions:** +- `object-types/button.md` - Button documentation +- `object-types/text-input.md` - Text input fields +- `object-types/link.md` - Link elements +- `object-types/heading-text.md` - Headings & text with placeholder analysis +- `object-types/image.md` - Image elements +- `object-types/object-router.md` - Intelligent object detection & routing + +**Design Principles Applied:** +- ✅ Goal-based trust-the-agent approach +- ✅ Concise instructions (vs. long procedural lists) +- ✅ Soft, collaborative language throughout +- ✅ Clear step separation with micro-steps +- ✅ Optional steps where appropriate +- ✅ v6 best practices for instruction file sizing +- ✅ Purpose-based naming (stable Object IDs) +- ✅ Grouped translations (coherent reading) +- ✅ Character capacity validation from sketches + +**Key Innovations:** +1. **Purpose-Based Object IDs** - IDs reflect function, remain stable when content changes +2. **Grouped Translations** - Each language reads coherently as a group +3. **Sketch Text Analysis** - Automatic capacity estimation from visual markers +4. **Intelligent Routing** - Agent suggests object types rather than asking lists + +**Architecture Documentation:** +- `workflows/4-ux-design/ARCHITECTURE.md` - Complete Phase 4 architecture +- `workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md` - Text analysis methodology +- `workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md` - Translation patterns +- `workflows/4-ux-design/DOG-WEEK-SPECIFICATION-PATTERN.md` - Complete workflow example + +**Next Actions:** +- Create Phase 5 workflow (Design System) +- Create Phase 6 workflow (PRD Finalization / Dev Integration) +- Complete agent definitions (Freyja, Baldr) +- Port agent presentations +- Create remaining object-type instruction files (~15 more types) + +#### Language Configuration (December 5 - Later) + +**Multi-Language Support:** +- `workflows/workflow-init/instructions.md` - Updated with language configuration (Step 4) +- `workflows/wds-workflow-status-template.yaml` - Added language fields to config +- `workflows/LANGUAGE-CONFIGURATION-GUIDE.md` - Complete multi-language guide +- `workflows/LANGUAGE-FLOW-DIAGRAM.md` - Step-by-step language flow + +**Configuration Settings:** +1. **Specification Language** - Language to write design specs in (EN, SE, etc.) +2. **Product Languages** - Array of languages the product supports + +**Storage:** +```yaml +config: + specification_language: "EN" + product_languages: + - EN + - SE + - NO +``` + +**Impact on Workflows:** +- Specs written in `specification_language` +- All text objects include translations for ALL `product_languages` +- Agents automatically request content for each configured language +- Complete translation coverage from day one + +**Example (Dog Week):** +- Specification Language: EN (specs written in English) +- Product Languages: [EN, SE] (product supports English & Swedish) +- Result: All text objects have both EN and SE content + +**Benefits:** +- ✅ Flexible spec language separate from product languages +- ✅ All translations grouped and coherent +- ✅ No missing translations +- ✅ Developer-friendly config +- ✅ Easy to add languages mid-project + +#### Sketch Text Analysis Corrections (December 5 - Final) + +**Corrected Understanding:** +- **Line thickness** → **font weight** (bold/regular), NOT font size! +- **Distance between lines** → **font size** +- **Confusion risk:** Large spacing (>60px) might be image/colored box, not text + +**Updated Files:** +- `4-ux-design/object-types/heading-text.md` - Corrected analysis logic +- `4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md` - Updated with correct interpretation +- `4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md` - Quick reference card +- `4-ux-design/SKETCH-TEXT-STRATEGY.md` - When to use text vs. markers + +**Best Practice - Actual Text vs. Markers:** + +**Use ACTUAL TEXT for:** +- Headlines (provides content guidance) +- Button labels (shows intended action) +- Navigation items (clarifies structure) +- Short, important text + +**Use LINE MARKERS for:** +- Body paragraphs (content TBD) +- Long descriptions (sizing only) +- Placeholder content + +**Agent Behavior:** +- Reads actual text from sketch as starting suggestion +- **Proactively suggests translations for all configured languages** +- Allows refinement during specification +- Sketch text isn't final, just guidance +- Analyzes markers for font size, weight, capacity + +**Example:** +``` +Every walk. on time. ← Agent reads this +Every time. ← Translates to all languages + +EN: Every walk. on time. Every time. +SE: Varje promenad. i tid. Varje gång. ← Agent suggests! + +Do these work? [1] Use [2] Adjust [3] Manual +``` + +**User can:** +- Accept suggestions (fast!) +- Refine specific translations +- Provide manual input if preferred + +--- + +--- + **End of Roadmap Document** -*To continue: Open this document, review "Next Steps" section, and proceed with creating `wds-method-guide.md`* +*To continue: Open this document, review "Next Steps" section for current priorities* diff --git a/src/modules/wds/agents/saga-analyst.agent.yaml b/src/modules/wds/agents/saga-analyst.agent.yaml new file mode 100644 index 00000000..b263d5cc --- /dev/null +++ b/src/modules/wds/agents/saga-analyst.agent.yaml @@ -0,0 +1,55 @@ +# Saga Analyst Agent Definition + +agent: + metadata: + id: "{bmad_folder}/wds/agents/saga-analyst.agent.yaml" + name: Saga + title: Business Analyst + icon: 📚 + module: wds + + persona: + role: Strategic Business Analyst + Product Discovery Expert + identity: | + Curious, insightful strategic thinker who helps uncover product vision and market positioning. + Specializes in translating vague ideas into clear, actionable strategic foundations. + Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. + communication_style: | + Asks questions that spark 'aha!' moments while structuring insights with precision. + Collaborative approach that builds documents together with users, not interrogatively. + Uses soft, encouraging language that makes users feel heard and understood. + principles: | + - Every product has a story waiting to be discovered + - Ask one question at a time and listen deeply to the answer + - Build documents collaboratively, not through information extraction + - Find if this exists, if it does, always treat it as bible: `**/project-context.md` + + menu: + - trigger: project-brief + workflow: "{project-root}/{bmad_folder}/wds/workflows/1-project-brief/workflow.yaml" + description: Create comprehensive product brief (Phase 1) + + - trigger: trigger-mapping + workflow: "{project-root}/{bmad_folder}/wds/workflows/2-trigger-mapping/workflow.yaml" + description: Create trigger map with user psychology (Phase 2) + + - trigger: workflow-status + workflow: "{project-root}/{bmad_folder}/wds/workflows/workflow-status/workflow.yaml" + description: Get workflow status or initialize a workflow if not already done + + - trigger: brainstorm-project + exec: "{project-root}/{bmad_folder}/core/workflows/brainstorming/workflow.md" + data: "{project-root}/{bmad_folder}/wds/data/project-context-template.md" + description: Guided Project Brainstorming session with final report + + - trigger: research + exec: "{project-root}/{bmad_folder}/bmm/workflows/1-analysis/research/workflow.md" + description: Guided Research scoped to market, domain, competitive analysis + + - trigger: document-project + workflow: "{project-root}/{bmad_folder}/bmm/workflows/document-project/workflow.yaml" + description: Document your existing project + + - trigger: party-mode + exec: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md" + description: Bring whole team in to chat with other expert agents diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-01-init.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-01-init.md new file mode 100644 index 00000000..bf18df11 --- /dev/null +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-01-init.md @@ -0,0 +1,27 @@ +# Step 1: Welcome and Set Expectations + +## Purpose +Welcome user and set expectations for the Project Brief workflow. + +## Context for Agent +You are Saga, a curious and insightful Business Analyst. Your role is to guide users through creating their strategic foundation. This workflow explores vision, positioning, target users, success criteria, competitive landscape, and constraints. + +## Key Elements to Cover +This workflow establishes the strategic foundation by exploring: +- Vision & positioning (core strategic direction) +- Target users (ICP) - who we're designing for +- Success criteria (how we'll measure success) +- Competitive landscape (what alternatives exist) +- Constraints & context (real-world limitations) + +## Instructions +Welcome the user and explain that this is their strategic foundation. Set time expectations (30-60 minutes) and ask about any existing context that should be considered. + +## Next Step +When user confirms readiness, proceed to step-02-vision.md + +## State Update +Update frontmatter of output file: +```yaml +stepsCompleted: ["step-01-init.md"] +``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-02-vision.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-02-vision.md new file mode 100644 index 00000000..00eea8d2 --- /dev/null +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-02-vision.md @@ -0,0 +1,37 @@ +# Step 2: Capture Vision + +## Purpose +Help user articulate their vision for the product. + +## Context for Agent +You are exploring the big picture with the user. Your goal is to help them crystallize their aspirational vision into a clear statement that will guide all decisions. + +## Key Elements +This step captures the high-level, aspirational direction that will guide all decisions. + +## Instructions + +1. **Ask vision question** + - "What's your vision for this product?" + - "If this project succeeds beyond your wildest dreams, what does that look like? Don't worry about being realistic yet - dream big." + +2. **Listen for key elements** + - Aspirational outcomes + - Impact on users + - Market position + - Emotional drivers + +3. **Reflect and crystallize** + - Reflect back what you heard + - Help crystallize into a clear vision statement + - Use collaborative language: "What I'm hearing is..." or "It sounds like..." + +## Next Step +After capturing vision, proceed to step-03-positioning.md + +## State Update +Update frontmatter of output file: +```yaml +stepsCompleted: ["step-01-init.md", "step-02-vision.md"] +vision: "[captured vision statement]" +``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-03-positioning.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-03-positioning.md new file mode 100644 index 00000000..cce1a541 --- /dev/null +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-03-positioning.md @@ -0,0 +1,26 @@ +# Step 3: Define Positioning + +## Purpose +Help user define clear positioning statement for their product. + +## Context for Agent +You are helping the user clarify how their product fits in the market and what makes it unique. + +## Key Elements +This step establishes market positioning and differentiation. + +## Key Framework +Positioning statement format: "For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator]." + +## Instructions +Guide user through positioning framework. Ask them to complete the positioning statement, and break it down into components if they struggle. Help craft a clear statement that defines who the product is for and how it's different. + +## Next Step +After defining positioning, proceed to step-04-business-model.md + +## State Update +Update frontmatter of output file: +```yaml +stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md"] +positioning: "[captured positioning statement]" +``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-04-business-model.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-04-business-model.md new file mode 100644 index 00000000..f7b2ac3d --- /dev/null +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-04-business-model.md @@ -0,0 +1,20 @@ +# Step 4: Determine Business Model + +## Goal +Help user identify whether their product is B2B, B2C, or both. + +## Key Elements +Business model determines who buys/uses the product and affects all strategic decisions. + +## Instructions +Ask user whether their product is B2B, B2C, or both. Present clear options and explain the implications of each choice. + +## Next Step +After determining business model, proceed to step-05-business-customers.md if B2B or Both, or step-06-target-users.md if B2C + +## State Update +Update frontmatter of output file: +```yaml +stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md"] +business_model: "[b2b/b2c/both]" +``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-05-business-customers.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-05-business-customers.md new file mode 100644 index 00000000..7ce3738a --- /dev/null +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-05-business-customers.md @@ -0,0 +1,21 @@ +# Step 5: Identify Business Customers (B2B) + +## Goal +Help user define their ideal business customer profile. + +## Key Elements +Business customer profile determines who buys the product and influences purchasing decisions. + +## Instructions +If business model is B2B or Both, guide user to define their ideal business customer. Ask about company size, industry, decision-making structure, and budget authority. Also identify buying roles (buyer vs. user). + +## Next Step +After identifying business customers, proceed to step-06-target-users.md + +## State Update +Update frontmatter of output file: +```yaml +stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md"] +business_customer_profile: "[captured business customer profile]" +buying_roles: "[captured buying roles]" +``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-06-target-users.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-06-target-users.md new file mode 100644 index 00000000..60773e52 --- /dev/null +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-06-target-users.md @@ -0,0 +1,24 @@ +# Step 6: Identify Target Users + +## Purpose +Help user define their ideal customer profile. + +## Context for Agent +You are identifying who the product is for and what their needs are. This information will guide all design decisions. + +## Key Elements +This step identifies who we're designing for and what their needs are. + +## Instructions +Guide user to describe their ideal users in detail. Ask about their role, demographics, daily experience, frustrations, goals, and current solutions. Also identify any secondary users or stakeholders. + +## Next Step +After identifying target users, proceed to step-07-success-criteria.md + +## State Update +Update frontmatter of output file: +```yaml +stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md"] +ideal_user_profile: "[captured user profile]" +secondary_users: "[captured secondary users]" +``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-07-success-criteria.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-07-success-criteria.md new file mode 100644 index 00000000..dc7e12bb --- /dev/null +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-07-success-criteria.md @@ -0,0 +1,23 @@ +# Step 7: Define Success Criteria + +## Purpose +Help user define measurable success criteria for their project. + +## Context for Agent +You are establishing how the project will know if it's successful. This will guide all future decisions. + +## Key Elements +This step establishes measurable outcomes that indicate success. + +## Instructions +Guide user to define metrics and outcomes that indicate success. Help them think about user behavior, business outcomes, experience quality, and timeline. Work with them to make criteria SMART (Specific, Measurable, Achievable, Relevant, Time-bound). + +## Next Step +After defining success criteria, proceed to step-08-competitive-landscape.md + +## State Update +Update frontmatter of output file: +```yaml +stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md"] +success_criteria: "[captured success criteria]" +``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-08-competitive-landscape.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-08-competitive-landscape.md new file mode 100644 index 00000000..77a9d156 --- /dev/null +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-08-competitive-landscape.md @@ -0,0 +1,24 @@ +# Step 8: Analyze Competitive Landscape + +## Purpose +Help user understand alternatives and their unique advantage. + +## Context for Agent +You are exploring what alternatives exist and what makes the product unique. This information will guide differentiation strategy. + +## Key Elements +This step identifies competitive positioning and unique value proposition. + +## Instructions +Guide user to understand alternatives including direct competitors, different approaches, manual solutions, or doing nothing. For each alternative, explore strengths, weaknesses, and why users might choose them. Help identify their unfair advantage. + +## Next Step +After analyzing competitive landscape, proceed to step-09-constraints.md + +## State Update +Update frontmatter of output file: +```yaml +stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md"] +competitive_landscape: "[captured competitive analysis]" +unfair_advantage: "[captured unfair advantage]" +``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-09-constraints.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-09-constraints.md new file mode 100644 index 00000000..1a5af5e8 --- /dev/null +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-09-constraints.md @@ -0,0 +1,24 @@ +# Step 9: Capture Constraints and Context + +## Purpose +Help user identify constraints that should shape design decisions. + +## Context for Agent +You are grounding the vision in reality by identifying limitations and context. + +## Key Elements +This step identifies real-world limitations and additional context. + +## Instructions +Guide user to identify constraints including timeline, budget, technical requirements, brand guidelines, regulatory needs, and integration requirements. Also ask for additional context like company stage, team capabilities, market conditions, or past attempts. + +## Next Step +After capturing constraints, proceed to step-10-synthesize.md + +## State Update +Update frontmatter of output file: +```yaml +stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md", "step-09-constraints.md"] +constraints: "[captured constraints]" +additional_context: "[captured additional context]" +``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/steps/step-10-synthesize.md b/src/modules/wds/workflows/1-project-brief/complete/steps/step-10-synthesize.md new file mode 100644 index 00000000..1abaee1b --- /dev/null +++ b/src/modules/wds/workflows/1-project-brief/complete/steps/step-10-synthesize.md @@ -0,0 +1,23 @@ +# Step 10: Synthesize and Create Brief + +## Purpose +Synthesize all captured information into a complete project brief document. + +## Context for Agent +You are bringing together all the strategic elements into a comprehensive brief that will guide all design decisions. + +## Key Elements +This step compiles all strategic foundation elements into a cohesive document. + +## Instructions +Present all captured information (vision, positioning, business model, business customers, target users, success criteria, competitive landscape, unfair advantage, constraints, and additional context). Ask for confirmation and make any requested adjustments. Generate final document using the template. + +## Next Step +Workflow complete. User can proceed to Phase 2: Trigger Mapping + +## State Update +Update frontmatter of output file: +```yaml +stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md", "step-09-constraints.md", "step-10-synthesize.md"] +status: "complete" +``` diff --git a/src/modules/wds/workflows/1-project-brief/complete/workflow.md b/src/modules/wds/workflows/1-project-brief/complete/workflow.md new file mode 100644 index 00000000..e6a66037 --- /dev/null +++ b/src/modules/wds/workflows/1-project-brief/complete/workflow.md @@ -0,0 +1,58 @@ +--- +name: Product Brief Workflow +description: Create comprehensive product briefs through collaborative step-by-step discovery +web_bundle: true +--- + +# Product Brief Workflow + +**Goal:** Create comprehensive product briefs through collaborative step-by-step discovery + +**Your Role:** In addition to your name, communication_style, and persona, you are also Saga, a product-focused Business Analyst collaborating with an expert peer. This is a partnership, not a client-vendor relationship. You bring structured thinking and facilitation skills, while user brings domain expertise and product vision. 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 a part of an overall workflow that must be followed exactly +- **Just-In-Time Loading**: Only 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 output file frontmatter using `stepsCompleted` array when a workflow produces a document +- **Append-Only Building**: Build documents by appending content as directed to output file + +### Step Processing Rules + +1. **READ COMPLETELY**: Always read entire step file before taking any action +2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate +3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection +4. **CHECK CONTINUATION**: If step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue) +5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step +6. **LOAD NEXT**: When directed, load, read entire file, then execute 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 frontmatter of output files when writing final output for a specific step +- 🎯 **ALWAYS** follow the exact instructions in 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 {project-root}/{bmad_folder}/wds/config.yaml and resolve: + +- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `user_skill_level` + +### 2. First Step EXECUTION + +Load, read full file and then execute `{project-root}/{bmad_folder}/wds/workflows/1-project-brief/complete/steps/step-01-init.md` to begin workflow. diff --git a/src/modules/wds/workflows/1-project-brief/workflow.yaml b/src/modules/wds/workflows/1-project-brief/workflow.yaml index 76d2ce98..01c7d221 100644 --- a/src/modules/wds/workflows/1-project-brief/workflow.yaml +++ b/src/modules/wds/workflows/1-project-brief/workflow.yaml @@ -1,6 +1,11 @@ +--- +name: Product Brief Workflow +description: Establish project context - foundation for all design work +web_bundle: true +--- + # WDS Phase 1: Project Brief name: project-brief -description: "Establish project context - the foundation for all design work" author: "Whiteport Design Studio" phase: 1 @@ -25,8 +30,9 @@ workflows: instructions: "{installed_path}/simplified/instructions.md" template: "{installed_path}/simplified/simplified-brief.template.md" complete: - instructions: "{installed_path}/complete/instructions.md" + instructions: "{installed_path}/complete/workflow.md" template: "{installed_path}/complete/project-brief.template.md" + steps: "{installed_path}/complete/steps" # Output configuration output_file: "{output_folder}/A-Product-Brief/project-brief.md" diff --git a/src/modules/wds/workflows/3-prd-platform/workflow.yaml b/src/modules/wds/workflows/3-prd-platform/workflow.yaml index a2a04430..5a7fee28 100644 --- a/src/modules/wds/workflows/3-prd-platform/workflow.yaml +++ b/src/modules/wds/workflows/3-prd-platform/workflow.yaml @@ -1,6 +1,12 @@ +--- +name: PRD Platform Workflow +description: Establish technical foundation, validate risky features, and set up experimental endpoints +web_bundle: true +--- + +# WDS Phase 3: PRD Platform (Technical Foundation) name: "Phase 3: PRD Platform (Technical Foundation)" agent: "Freyja the PM" -description: "Establish technical foundation, validate risky features, and set up experimental endpoints" version: "1.0.0" paths: diff --git a/src/modules/wds/workflows/4-ux-design/ARCHITECTURE.md b/src/modules/wds/workflows/4-ux-design/ARCHITECTURE.md new file mode 100644 index 00000000..b13e8bf5 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/ARCHITECTURE.md @@ -0,0 +1,263 @@ +# Phase 4 Workflow Architecture Summary + +**Version:** v6 with Intelligent Object Analysis +**Date:** December 4, 2025 + +--- + +## Complete Structure + +``` +4-ux-design/ +├── workflow.yaml # v6 workflow config +├── workflow.md # v6 initialization with step-file architecture +│ +├── steps/ # Main workflow steps (5 steps) +│ ├── step-01-init.md # Welcome & determine what to design +│ ├── step-02-define-scenario.md # Create scenario structure +│ ├── step-03-design-page.md # Orchestrate 4A-4E for each page +│ ├── step-04-complete-scenario.md # Celebrate completion +│ └── step-05-next-steps.md # Guide to next actions +│ +├── substeps/ # Page design substeps +│ ├── 4a-exploration.md # [Optional] Concept exploration +│ ├── 4b-sketch-analysis.md # [Optional] Systematic sketch analysis +│ │ # • Top-to-bottom, left-to-right +│ │ # • Section-by-section +│ │ # • Component reuse detection +│ │ +│ ├── 4c-01-page-basics.md # Page fundamentals +│ ├── 4c-02-layout-sections.md # Define sections +│ ├── 4c-03-components-objects.md # Route to object-type files +│ │ # • For each section +│ │ # • For each object (top-left to bottom-right) +│ │ # • Uses object-router.md +│ ├── 4c-04-content-languages.md # Multilingual content +│ ├── 4c-05-interactions.md # Interaction behaviors +│ ├── 4c-06-states.md # All states (page & component) +│ ├── 4c-07-validation.md # Validation rules & errors +│ ├── 4c-08-generate-spec.md # Compile final document +│ │ +│ ├── 4d-prototype.md # [Optional] HTML prototype +│ └── 4e-prd-update.md # [Required] Extract requirements +│ +├── object-types/ # Object-specific instructions +│ ├── object-router.md # 🆕 INTELLIGENT ROUTER +│ │ # • Analyzes object +│ │ # • Suggests interpretation +│ │ # • User confirms +│ │ # • Routes to appropriate file +│ │ +│ ├── button.md # Complete button documentation +│ ├── text-input.md # Complete input documentation +│ ├── link.md # Complete link documentation +│ ├── heading-text.md # Complete text documentation +│ ├── image.md # Complete image documentation +│ │ +│ └── [16 more object types to create] # Each with precise examples +│ • textarea.md +│ • select-dropdown.md +│ • checkbox.md +│ • radio-button.md +│ • toggle-switch.md +│ • card.md +│ • modal-dialog.md +│ • table.md +│ • list.md +│ • navigation.md +│ • badge.md +│ • alert-toast.md +│ • progress.md +│ • video.md +│ • custom-component.md +│ +└── templates/ # Document templates + ├── page-specification.template.md # Complete page spec format + └── scenario-overview.template.md # Scenario structure format +``` + +--- + +## Key Innovations + +### 1. Step-File Architecture ✅ +- **Just-in-time loading** - Only current step in memory +- **Sequential enforcement** - Steps load one at a time +- **Clear progression** - 5 main steps → substeps → object-types +- **State tracking** - Progress saved between sessions + +### 2. Granular Specification (8 Micro-Steps) ✅ +Instead of one large 4C step, broke into focused substeps: +1. **Page Basics** - Fundamentals +2. **Layout Sections** - Structure +3. **Components & Objects** - Systematic identification +4. **Content & Languages** - Multilingual +5. **Interactions** - Behaviors +6. **States** - All possibilities +7. **Validation** - Rules & errors +8. **Generate Spec** - Compile document + +### 3. Object-Type Routing System ✅ +- **21 specialized object-type files** (6 created, 15 to create) +- **Each file has precise examples** for consistency +- **Ensures uniform output** across all WDS projects + +### 4. Intelligent Analysis (Trust-the-Agent) ✅✨ + +**Old Approach (Procedural):** +``` +What type of object is this? +1. Button +2. Input +3. Link +[Choose from list] +``` + +**New Approach (Intelligent):** +``` +My interpretation: + +This looks like a PRIMARY BUTTON. + +Based on what I see: +- Prominent placement at bottom of form +- Bright blue background (primary color) +- White text saying "Save Profile" + +I think this "Save Profile Button": +- Saves the form data to the database +- Updates the user's profile information +- Shows loading state during save + +Does this match your intent? [Y/Clarify/No] +``` + +**Benefits:** +- ✅ Agent demonstrates intelligence +- ✅ Context-aware interpretation +- ✅ Natural conversation +- ✅ Quick confirmation when correct +- ✅ v6 "goal-based trust" philosophy + +### 5. Systematic Sketch Analysis ✅ +- **Top-to-bottom, left-to-right** within sections +- **Component reuse detection** across pages +- **Section-by-section** organization +- **Prevents missing elements** + +--- + +## Workflow Flow + +``` +Step 1: Init + ↓ +Step 2: Define Scenario + ↓ +Step 3: Design Page (LOOPS for each page) + ↓ + 4A: Exploration (optional) + ↓ + 4B: Sketch Analysis (optional) + • Top-left to bottom-right + • Section by section + • Check for reusable components + ↓ + 4C: Specification (required) - 8 SUBSTEPS + ↓ + 4C-01: Page Basics + 4C-02: Layout Sections + 4C-03: Components & Objects + ↓ + FOR EACH SECTION: + FOR EACH OBJECT (top-left to bottom-right): + ↓ + object-router.md + • Analyzes object intelligently + • Suggests interpretation + • User confirms + • Routes to object-type file + ↓ + button.md / text-input.md / link.md / etc. + • Precise documentation + • Complete examples + • Consistent format + ↓ + Returns to 4C-03 + NEXT OBJECT + NEXT SECTION + ↓ + 4C-04: Content & Languages + 4C-05: Interactions + 4C-06: States + 4C-07: Validation + 4C-08: Generate Spec + ↓ + 4D: Prototype (optional) + ↓ + 4E: PRD Update (required) + ↓ + NEXT PAGE or Step 4 + ↓ +Step 4: Complete Scenario + ↓ +Step 5: Next Steps +``` + +--- + +## v6 Best Practices Applied + +✅ **Micro-file design** - Small, focused files +✅ **Just-in-time loading** - Load only current step +✅ **Goal-based trust** - Agent interprets intelligently +✅ **Sequential enforcement** - No skipping steps +✅ **State tracking** - Resume capability +✅ **Example-driven** - Show, don't tell +✅ **Soft language** - Collaborative, not commanding +✅ **Object-specific instructions** - Precise, consistent + +--- + +## Benefits for WDS Users + +**Consistency Across Projects:** +- Same object types documented the same way +- Every WDS project produces uniform specs +- Developers know what to expect + +**Agent Clarity:** +- Focused instructions prevent confusion +- Clear routing eliminates ambiguity +- Examples guide output format + +**User Experience:** +- Intelligent suggestions feel natural +- Quick confirmations when agent is right +- Systematic coverage ensures nothing missed + +**Maintainability:** +- Easy to add new object types +- Each file independently improvable +- Clear separation of concerns + +--- + +## Status + +**✅ Complete:** +- Main workflow structure (5 steps) +- All substeps (4A, 4B, 4C-01 through 4C-08, 4D, 4E) +- Object-router with intelligent analysis +- 6 object-type files (button, text-input, link, heading-text, image, object-router) +- Templates + +**⏳ To Create:** +- 15 additional object-type files +- Object-type files should follow same pattern with precise examples + +--- + +**This architecture ensures consistent, high-quality specifications across all WDS projects while making the agent experience intelligent and natural.** 🎨✨ + + diff --git a/src/modules/wds/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md b/src/modules/wds/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md new file mode 100644 index 00000000..9af2dbbe --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/DOCUMENTATION-ARCHITECTURE.md @@ -0,0 +1,153 @@ +# Phase 4 Documentation Architecture + +## Problem: Redundant Information + +Currently sketch text analysis rules are duplicated across multiple files, making maintenance difficult and increasing risk of inconsistency. + +## Solution: Single Source of Truth Pattern + +### Core Documentation (Single Source of Truth) + +1. **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** ← **MASTER GUIDE** + - Complete rules for analyzing text markers + - Line thickness → font weight + - Line spacing → font size + - Line position → text alignment + - Line count → text lines + - Line length → character capacity + - All visual examples and edge cases + +2. **`SKETCH-TEXT-QUICK-REFERENCE.md`** + - One-page summary of the guide + - Quick lookup table + - References master guide for details + +3. **`SKETCH-TEXT-STRATEGY.md`** + - When to use actual text vs. line markers + - Proactive translation workflow + - References master guide for analysis rules + +### Specialized Documentation (References Core) + +4. **`object-types/TEXT-DETECTION-PRIORITY.md`** + - Why text detection is first + - PAIRS = text, SINGLE = decorative + - References master guide for analysis + - Focus: Detection logic only + +5. **`object-types/heading-text.md`** + - Instruction file for AI agent + - References master guide + - Focus: Workflow and user interaction + - Does NOT duplicate analysis rules + +6. **`object-types/object-router.md`** + - Routes to appropriate object type + - References TEXT-DETECTION-PRIORITY.md + - Does NOT duplicate analysis rules + +### Supporting Documentation + +7. **`HTML-VS-VISUAL-STYLES.md`** + - HTML tags vs visual styles + - No sketch analysis (different topic) + +8. **`IMAGE-SKETCHING-BEST-PRACTICES.md`** + - How to sketch images + - No text analysis (different topic) + +9. **`WDS-SPECIFICATION-PATTERN.md`** + - Shows complete specification format + - Examples reference the guides + - Does NOT teach analysis rules + +10. **`TRANSLATION-ORGANIZATION-GUIDE.md`** + - Purpose-based naming + - Grouped translations + - References guides for text detection + +--- + +## Refactoring Plan + +### Keep As-Is (Single Source of Truth) +✅ `SKETCH-TEXT-ANALYSIS-GUIDE.md` - Master guide with all rules +✅ `SKETCH-TEXT-QUICK-REFERENCE.md` - Quick reference +✅ `SKETCH-TEXT-STRATEGY.md` - Strategy guide + +### Refactor (Remove Duplication, Add References) + +**`TEXT-DETECTION-PRIORITY.md`:** +- Keep: Detection logic (pairs vs single) +- Remove: Detailed analysis rules (thickness → weight, spacing → size) +- Add: Reference to master guide + +**`heading-text.md`:** +- Keep: Workflow steps +- Remove: Duplicate explanations of analysis rules +- Add: Reference to master guide +- Show: Example output only + +**`object-router.md`:** +- Keep: Routing logic +- Remove: Any duplicate analysis +- Add: Reference to TEXT-DETECTION-PRIORITY.md + +**`WDS-SPECIFICATION-PATTERN.md`:** +- Keep: Examples +- Add: Note "See SKETCH-TEXT-ANALYSIS-GUIDE.md for how these values were derived" + +**`TRANSLATION-ORGANIZATION-GUIDE.md`:** +- Keep: Organization patterns +- Add: Reference to master guide for analysis + +--- + +## Benefits + +✅ **Single Source of Truth** - One place to update analysis rules +✅ **No Redundancy** - Each file has clear purpose +✅ **Easy Maintenance** - Update once, references everywhere +✅ **Clear Hierarchy** - Master guide → specialized docs +✅ **Reduced File Size** - Instruction files become smaller and focused + +--- + +## Reference Pattern + +In instruction files, use this pattern: + +```markdown +Analyzing text markers in sketch... + +Apply text marker analysis rules from SKETCH-TEXT-ANALYSIS-GUIDE.md: +- Count pairs → number of lines +- Measure thickness → font weight +- Measure spacing → font size estimate +- Check position → alignment +- Calculate length → character capacity + + +**Sketch Analysis:** +- 2 line pairs → 2 lines of text +- Thick lines (3px) → Bold weight +- Spacing (24px) → ~42px font size estimate +- Centered position → Center alignment +- ~35 characters per line + +For detailed analysis rules, see: SKETCH-TEXT-ANALYSIS-GUIDE.md +``` + +--- + +## Status + +**To Do:** +- [ ] Refactor TEXT-DETECTION-PRIORITY.md +- [ ] Refactor heading-text.md +- [ ] Refactor object-router.md +- [ ] Add references in WDS-SPECIFICATION-PATTERN.md +- [ ] Add references in TRANSLATION-ORGANIZATION-GUIDE.md + +**Result:** Clean, maintainable documentation architecture! 🎯 + diff --git a/src/modules/wds/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md b/src/modules/wds/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md new file mode 100644 index 00000000..5a68459e --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/HTML-VS-VISUAL-STYLES.md @@ -0,0 +1,223 @@ +# HTML Tags vs. Visual Text Styles + +**Critical Best Practice for WDS Specifications** + +--- + +## The Two-Layer System + +### Layer 1: HTML Semantic Structure (h1-h6, p, etc.) +**Purpose:** SEO, accessibility, document outline, screen readers + +**Rules:** +- **Each page must have exactly ONE h1** (main page title) +- **Heading hierarchy must be logical** (h1 → h2 → h3, no skipping) +- **Same across all pages** for semantic consistency +- **Not about visual appearance** + +### Layer 2: Visual Text Styles (Design System) +**Purpose:** Visual hierarchy, branding, design consistency + +**Rules:** +- **Named by visual purpose** (Display-Large, Headline-Primary, Body-Regular, etc.) +- **Can be applied to any HTML tag** +- **Different pages can use different visual styles** for the same HTML tag +- **About appearance, not semantics** + +--- + +## Why Separate? + +### Problem: Mixing HTML and Visual Styles +```markdown +❌ BAD: +- **Style**: H1 heading + +What does this mean? +- Is it an h1 tag? +- Is it a visual style that looks like an h1? +- What if another page needs h1 but different visual style? +``` + +### Solution: Specify Both Independently +```markdown +✅ GOOD: +- **HTML Tag**: h1 (semantic structure) +- **Visual Style**: Display-Large (from Design System) +``` + +**Now we know:** +- HTML: This is the main page heading (h1 for SEO) +- Visual: It uses the "Display-Large" design system style +- Another page could have: h1 + Headline-Medium (different visual, same semantic) + +--- + +## Real-World Examples + +### Example 1: Landing Page vs. Article Page + +**Landing Page - Hero Headline:** +```markdown +- **HTML Tag**: h1 +- **Visual Style**: Hero headline +- **Font**: Bold, 56px, line-height 1.1 +``` + +**Article Page - Article Title:** +```markdown +- **HTML Tag**: h1 +- **Visual Style**: Main header +- **Font**: Bold, 32px, line-height 1.3 +``` + +**Both are h1 (semantic), but different visual styles!** + +### Example 2: Same Visual Style, Different Semantics + +**Section Heading:** +```markdown +- **HTML Tag**: h2 +- **Visual Style**: Sub header +- **Font**: Bold, 28px, line-height 1.2 +``` + +**Testimonial Quote:** +```markdown +- **HTML Tag**: p +- **Visual Style**: Sub header +- **Font**: Bold, 28px, line-height 1.2 +``` + +**Same visual style (Sub header), but different HTML tags for proper semantics!** + +--- + +## Design System Visual Style Naming + +### Good Visual Style Names (Descriptive & Purpose-Based) + +**For Headers:** +✅ **Main header** - Primary page header +✅ **Sub header** - Section headers +✅ **Sub header light** - Lighter variant of section header +✅ **Card header** - Headers within cards +✅ **Small header** - Minor headers, labels + +**For Body Text:** +✅ **Body text** - Standard paragraph text +✅ **Body text large** - Larger body text for emphasis +✅ **Body text small** - Smaller body text, secondary info +✅ **Intro text** - Opening paragraph, lead text + +**For Special Purposes:** +✅ **Hero headline** - Large display text for hero sections +✅ **Caption text** - Image captions, metadata +✅ **Label text** - Form labels, UI labels +✅ **Error text** - Error messages +✅ **Success text** - Success messages +✅ **Link text** - Link styling +✅ **Button text** - Text within buttons + +### Bad Visual Style Names +❌ **H1-Style** / **Heading-1** - Confuses with HTML tags +❌ **Text-Size-42** - Just a number, not semantic +❌ **Big-Text** - Too vague +❌ **Display-Large** - Too abstract (unless using design system tokens) + +--- + +## WDS Specification Format + +### Complete Example + +```markdown +#### Primary Headline + +**OBJECT ID**: `start-hero-headline` + +**HTML Structure:** +- **Tag**: h1 +- **Purpose**: Main page heading (SEO/accessibility) + +**Visual Style:** +- **Style Name**: Hero headline +- **Font weight**: Bold (from 3px thick line markers in sketch) +- **Font size**: 56px (est. from 32px spacing between line pairs) +- **Line-height**: 1.1 (est. calculated from font size) +- **Color**: #1a1a1a +- **Letter spacing**: -0.02em + +**Position**: Center of hero section, above supporting text + +**Behavior**: Updates with language toggle + +**Content**: +- EN: "Every walk. on time. Every time." +- SE: "Varje promenad. i tid. Varje gång." +``` + +--- + +## Benefits of This Approach + +✅ **Flexibility** - Different pages can have different visual styles for same semantic tags +✅ **Consistency** - Design system ensures visual consistency across visual styles +✅ **SEO/Accessibility** - Proper HTML structure maintained +✅ **Scalability** - Easy to add new visual styles without breaking semantic structure +✅ **Clarity** - Designers and developers both understand the specification +✅ **Reusability** - Visual styles can be reused across different HTML tags + +--- + +## Common Patterns + +### Pattern 1: Landing Page +``` +h1 → Hero headline (big hero text, 56px) +h2 → Sub header (section headings, 32px) +h3 → Small header (subsection headings, 24px) +p → Body text (regular paragraphs, 16px) +``` + +### Pattern 2: Blog Post +``` +h1 → Main header (article title, 36px) +h2 → Sub header (section headings, 28px) +h3 → Sub header light (subsection headings, 22px) +p → Body text large (article body, 18px) +``` + +### Pattern 3: Dashboard +``` +h1 → Main header (page title, 28px) +h2 → Card header (widget titles, 20px) +h3 → Small header (section labels, 16px) +p → Body text small (compact info, 14px) +``` + +**Same HTML structure (h1, h2, h3, p) but different visual styles for each context!** + +--- + +## Implementation Note + +When generating HTML prototypes or handing off to developers: + +```html + +

Every walk. on time. Every time.

+ + +

Welcome to Your Profile

+ + +

Every walk. on time. Every time.

+``` + +The CSS class references the **visual style name** (hero-headline, main-header), not the HTML tag. + +--- + +**Remember:** HTML tags = Document structure. Visual styles = Appearance. Keep them separate! 🎯 + diff --git a/src/modules/wds/workflows/4-ux-design/IMAGE-SKETCHING-BEST-PRACTICES.md b/src/modules/wds/workflows/4-ux-design/IMAGE-SKETCHING-BEST-PRACTICES.md new file mode 100644 index 00000000..3220c3bc --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/IMAGE-SKETCHING-BEST-PRACTICES.md @@ -0,0 +1,255 @@ +# WDS Sketching Best Practices: Images + +**How to represent images in UI sketches** + +--- + +## ✅ Recommended: Sketch the Actual Image Content + +### Why Sketch Real Content? + +When you sketch what the image should actually show (rather than just "X" or "image here"), you: +- **Provide visual direction** - Designer/developer understands image purpose +- **Enable AI interpretation** - Agent can suggest appropriate image content +- **Guide art direction** - Photographer/illustrator knows what's needed +- **Communicate intent** - Stakeholders visualize the final design +- **Inspire creativity** - More engaging than abstract placeholders + +--- + +## Image Sketching Techniques + +### 1. Portrait/Profile Photos + +**Sketch a simple face:** +``` +┌──────────────┐ +│ ◠ ◠ │ ← Simple eyes +│ │ +│ ᵕ │ ← Simple smile +└──────────────┘ +``` + +or + +``` +┌──────────────┐ +│ ● ● │ ← Dots for eyes +│ │ +│ \_/ │ ← Smile +└──────────────┘ +``` + +**Purpose:** Profile pictures, team photos, author avatars, user images + +### 2. Hero Images / Backgrounds + +**Sketch landscape/scenery:** +``` +┌──────────────────────────┐ +│ │ +│ /\ /\ /\ │ ← Mountains +│ / \ / \ / \ │ +│ / X \/ \ │ +└──────────────────────────┘ +``` + +**Sketch clouds/sky:** +``` +┌──────────────────────────┐ +│ ~ ~ ~ │ +│ ~ ~ ~ ~ │ ← Soft clouds +│ ~ ~ │ +│ │ +└──────────────────────────┘ +``` + +**Sketch abstract shapes:** +``` +┌──────────────────────────┐ +│ ∿∿∿ ≈≈≈ │ +│ ∿∿ ≈≈ ∿∿ │ ← Waves, organic shapes +│ ≈≈≈ ∿∿∿ │ +└──────────────────────────┘ +``` + +**Purpose:** Hero sections, full-width backgrounds, feature images + +### 3. Product Images + +**Sketch the product outline:** +``` +┌──────────────┐ +│ |‾‾‾‾| │ ← Phone outline +│ | | │ +│ | ● | │ ← Home button +│ |____| │ +└──────────────┘ +``` + +``` +┌──────────────┐ +│ _____ │ ← Laptop screen +│ | | │ +│ |_____| │ +│ '-----' │ ← Keyboard +└──────────────┘ +``` + +**Purpose:** Product photos, e-commerce images, feature showcases + +### 4. Icons / Illustrations + +**Sketch simple icon shapes:** +``` +┌──────┐ +│ ⚙ │ ← Settings gear +└──────┘ +``` + +``` +┌──────┐ +│ ♥ │ ← Heart icon (favorites/likes) +└──────┘ +``` + +``` +┌──────┐ +│ ✓ │ ← Checkmark (success) +└──────┘ +``` + +**Purpose:** UI icons, feature illustrations, decorative graphics + +### 5. Abstract/Decorative Images + +**Use soft, flowing shapes:** +``` +┌──────────────────────────┐ +│ ∞ │ +│ ≋≋≋ │ ← Abstract flowing shapes +│ ⌇⌇ │ +│ ∿∿∿ │ +└──────────────────────────┘ +``` + +**Use geometric patterns:** +``` +┌──────────────────────────┐ +│ ◆ ○ ▢ │ +│ ▢ ◆ ○ │ ← Geometric pattern +│ ○ ▢ ◆ │ +└──────────────────────────┘ +``` + +**Purpose:** Background patterns, decorative elements, brand graphics + +--- + +## ❌ Discouraged: Generic "X" Marker + +**Why avoid X markers?** + +``` +┌──────────────┐ +│ X │ ← Generic, uninformative +└──────────────┘ +``` + +**Problems with X markers:** +- ❌ **No context** - Doesn't communicate what image shows +- ❌ **No direction** - No guidance for content selection +- ❌ **Intrusive** - Visually distracting in sketch +- ❌ **Uninspiring** - Doesn't engage stakeholders +- ❌ **Ambiguous** - Could be mistaken for "delete" or error + +**Only use X if:** Sketch is extremely rough/quick and image content is described elsewhere + +--- + +## WDS Detection Rules + +### AI Image Detection + +When analyzing sketches, the AI should: + +1. **Look for rectangular containers** (image boundaries) +2. **Check for sketched content inside** (faces, landscapes, products, shapes) +3. **Interpret the sketch** to understand image purpose +4. **Route to `image.md`** for specification + +### Example Detection + +**Sketch shows:** +``` +┌──────────────────────────┐ +│ /\ /\ /\ │ +│ / \ / \ / \ │ ← Mountains sketched +│ / X \/ \ │ +└──────────────────────────┘ +``` + +**AI interprets:** +- Rectangle container detected +- Mountain/landscape sketch inside +- **Purpose:** Hero background image showing outdoor/nature scene +- **Route to:** `image.md` +- **Suggested content:** Mountain landscape, outdoor scenery, nature photography + +--- + +## Benefits of Sketching Real Content + +### For Designers +- ✅ Communicate visual intent clearly +- ✅ Test composition and layout +- ✅ Provide art direction +- ✅ Inspire creative solutions + +### For AI Agents +- ✅ Understand image purpose from context +- ✅ Suggest appropriate image sources +- ✅ Recommend image dimensions and aspect ratios +- ✅ Generate meaningful alt text + +### For Developers +- ✅ Understand what image represents +- ✅ Know how to style and position image +- ✅ Select appropriate placeholder images +- ✅ Write meaningful alt text for accessibility + +### For Stakeholders +- ✅ Visualize final design better +- ✅ Provide meaningful feedback +- ✅ Understand design intent +- ✅ Approve with confidence + +--- + +## Quick Reference + +| Image Type | Sketch Technique | Example | +|------------|------------------|---------| +| **Portrait/Face** | Simple face with eyes and smile | ◠ ◠ ᵕ | +| **Landscape** | Mountains, trees, horizon | /\\ /\\ /\\ | +| **Sky/Clouds** | Wavy cloud shapes | ~ ~ ~ | +| **Product** | Product outline/silhouette | Phone, laptop shape | +| **Icon** | Simple icon shape | ⚙ ♥ ✓ | +| **Abstract** | Flowing, organic shapes | ∿ ≋ ∞ | +| **Geometric** | Shapes and patterns | ◆ ○ ▢ | + +--- + +## Summary + +**WDS Image Sketching Philosophy:** +> "Sketch what you see, not just where it goes." + +**Guidelines:** +- ✅ **Draw the actual content** - Faces, landscapes, products +- ✅ **Use soft, organic shapes** - Clouds, waves for abstract images +- ✅ **Keep it simple** - Quick sketches are fine, detail level matches sketch fidelity +- ❌ **Avoid generic X markers** - Provides no useful context + +**Result:** Better communication, clearer intent, more useful AI analysis! 🎨✨ + diff --git a/src/modules/wds/workflows/4-ux-design/PROACTIVE-TRANSLATION-WORKFLOW.md b/src/modules/wds/workflows/4-ux-design/PROACTIVE-TRANSLATION-WORKFLOW.md new file mode 100644 index 00000000..01089a0b --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/PROACTIVE-TRANSLATION-WORKFLOW.md @@ -0,0 +1,412 @@ +# Proactive Translation Workflow + +**Agent Always Suggests Translations** + +--- + +## The Principle + +**Agent is proactive, not passive** +- Don't just ask for translations +- **Suggest them!** +- Let user accept, refine, or override + +--- + +## Workflow Examples + +### Example 1: Sketch Has Actual Text + +**Sketch shows:** +``` +Every walk. on time. Every time. +``` + +**Agent says:** +``` +I found text in your sketch: "Every walk. on time. Every time." + +Let me suggest translations... + +Suggested content for Primary Headline: + +EN: Every walk. on time. Every time. +SE: Varje promenad. i tid. Varje gång. +NO: Hver tur. i tide. Hver gang. + +These are my suggestions. Do they work? + +1. Use these translations +2. Adjust translations +3. Manual input + +Choice [1/2/3]: +``` + +**User response options:** + +**Option A: Accept (Fast!)** +``` +1 +``` +→ Done! All translations accepted. + +**Option B: Adjust specific** +``` +2 + +Which language(s) need adjustment? + +EN: Every walk. on time. Every time. ← Keep +SE: Varje promenad. i tid. Varje gång. ← Change this +NO: Hver tur. i tide. Hver gang. ← Keep + +SE: Varje promenad. Punktligt. Varje gång. +``` +→ Done! One adjusted, others kept. + +**Option C: Manual** +``` +3 + +EN: +SE: +NO: +``` +→ User provides all manually. + +--- + +### Example 2: No Sketch Text (Markers Only) + +**Sketch shows:** +``` +───────────────────────────────── ← Line markers +───────────────────────────────── ← (no actual text) +───────────────────────────────── +``` + +**Agent says:** +``` +Text placeholder detected: +- 3 horizontal lines +- Regular weight, 16px font +- Capacity: ~180-210 characters + +Content for Feature Description: + +Please provide content in one language, and I'll suggest translations! + +EN: +``` + +**User provides:** +``` +EN: Organize your family around dog care. Assign walks and never miss one again. +``` + +**Agent immediately suggests:** +``` +Great! Here are translation suggestions: + +SE: Organisera din familj kring hundvård. Tilldela promenader och missa aldrig en igen. +NO: Organiser familien din rundt hundepass. Tildel turer og gå aldri glipp av en. + +Do these work? + +1. Use these translations +2. Adjust translations +3. Manual input + +Choice [1/2/3]: +``` + +**Result:** Agent is proactive even without sketch text! + +--- + +## Benefits + +### ✅ Speed +- User accepts = instant completion +- No typing all translations manually +- Saves significant time + +### ✅ Accuracy +- Agent uses context for better translations +- Considers character capacity +- Maintains tone and style + +### ✅ Flexibility +- Can accept all suggestions +- Can adjust specific ones +- Can override completely +- Full user control + +### ✅ Consistency +- Translations match style +- Terminology stays consistent +- Professional quality + +--- + +## Technical Implementation + +### Agent Logic + +```xml +Read sketch for text + + + Extract text: "Every walk. on time." + Translate to all product_languages + + + I found text in your sketch: "{{text}}" + + Suggested translations: + {{#each product_languages}} + {{this}}: {{translated_content}} + {{/each}} + + Do these work? [1] Use [2] Adjust [3] Manual + + + + + Provide content in {{primary_language}}: + After receiving, translate to remaining languages + + + Translation suggestions: + {{#each remaining_languages}} + {{this}}: {{translated_content}} + {{/each}} + + Do these work? [1] Use [2] Adjust [3] Manual + + +``` + +### Translation Quality + +**Agent considers:** +- Character capacity from sketch +- Tone and style of original +- Context from page purpose +- Previous translations in project +- Language-specific conventions + +--- + +## Real Dog Week Examples + +### Example: Hero Headline + +**Sketch:** +``` +Every walk. on time. Every time. +``` + +**Agent:** +``` +Suggested content for Primary Headline: + +EN: Every walk. on time. Every time. +SE: Varje promenad. i tid. Varje gång. + +Do these work? [1] Use [2] Adjust [3] Manual +``` + +**User:** +``` +1 +``` + +**Result:** ✅ Complete in seconds! + +### Example: Button Label + +**Sketch:** +``` +[Get Started - Free Forever] +``` + +**Agent:** +``` +Suggested content for Primary CTA: + +EN: Get Started - Free Forever +SE: Kom Igång - Gratis För Alltid + +Do these work? [1] Use [2] Adjust [3] Manual +``` + +**User:** +``` +2 + +SE: börja planera - gratis för alltid ← lowercase, different verb +``` + +**Result:** ✅ Refined and complete! + +### Example: Form Label + +**Sketch:** +``` +Email Address: +``` + +**Agent:** +``` +Suggested content for Email Label: + +EN: Email Address +SE: E-postadress + +Do these work? [1] Use [2] Adjust [3] Manual +``` + +**User:** +``` +1 +``` + +**Result:** ✅ Instant! + +--- + +## Multi-Language Example (3+ Languages) + +**Project Config:** +```yaml +product_languages: + - EN + - SE + - NO + - DK +``` + +**Sketch:** +``` +Welcome Home +``` + +**Agent:** +``` +I found text in your sketch: "Welcome Home" + +Suggested translations: + +EN: Welcome Home +SE: Välkommen Hem +NO: Velkommen Hjem +DK: Velkommen Hjem + +Do these work? [1] Use [2] Adjust [3] Manual +``` + +**User:** +``` +1 +``` + +**Result:** ✅ 4 languages in one click! + +--- + +## Error Handling + +### Translation Confidence + +**High confidence:** +``` +✅ These translations look good! + +Do they work? [1] Use [2] Adjust [3] Manual +``` + +**Low confidence:** +``` +⚠️ I'm less confident about these translations. Please review carefully! + +Suggestions: +EN: [original] +SE: [suggested] + +Do they work? [1] Use [2] Adjust [3] Manual +``` + +### Character Capacity Warning + +**If translation exceeds capacity:** +``` +⚠️ Translation length warning: + +EN: "Every walk. on time." (23 chars) ✅ +SE: "Varje promenad i tid hela tiden." (33 chars) ⚠️ + → Exceeds capacity (30 chars) + +Suggested shorter version: +SE: "Varje promenad. I tid." (24 chars) ✅ + +Use shorter version? (y/n) +``` + +--- + +## User Experience + +### Before (Passive): +``` +EN: ← User types +SE: ← User types +NO: ← User types + +Slow, tedious, error-prone +``` + +### After (Proactive): +``` +Suggested translations: +EN: Every walk. on time. +SE: Varje promenad. i tid. +NO: Hver tur. i tide. + +[1] Use these ← ONE CLICK! + +Fast, accurate, professional +``` + +--- + +## Summary + +### Agent Behavior + +**Always suggest translations:** +1. Read sketch text (if present) +2. Generate suggestions for ALL languages +3. Present with options: Accept / Adjust / Manual +4. Validate character capacity +5. Warn if low confidence + +**Never:** +- Present blank fields for translations +- Make user type everything +- Provide only one language at a time + +### User Benefits + +✅ **Speed** - Accept in one click +✅ **Quality** - Professional translations +✅ **Control** - Can adjust or override +✅ **Confidence** - AI-assisted, human-verified + +--- + +**Proactive translation = better UX, faster workflow, higher quality!** 🌍⚡✨ + + + diff --git a/src/modules/wds/workflows/4-ux-design/README.md b/src/modules/wds/workflows/4-ux-design/README.md new file mode 100644 index 00000000..d9539595 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/README.md @@ -0,0 +1,201 @@ +# Phase 4: UX Design Workflow + +**Baldr'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 + +### 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) + diff --git a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md new file mode 100644 index 00000000..70efa3da --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-ANALYSIS-GUIDE.md @@ -0,0 +1,446 @@ +# Sketch Analysis Guide: Reading Text Placeholders + +**For Dog Week and All WDS Projects** + +--- + +## Best Practice: When to Use Text vs. Markers + +### Use ACTUAL TEXT for: +- **Headlines** - Provides content guidance and context +- **Button labels** - Shows intended action clearly +- **Navigation items** - Clarifies structure +- **Short, important text** - Where specific wording matters + +**Example:** +``` +Every walk. on time. Every time. ← Actual text (readable) +``` + +**Benefits:** +- Agent can read and suggest this as starting content +- Provides context for design decisions +- Can still be changed during specification + +### Use HORIZONTAL LINE MARKERS for: +- **Body paragraphs** - Content TBD, just need length indication +- **Long descriptions** - Where specific wording isn't decided yet +- **Placeholder content** - General sizing guidance + +**Example:** +``` +───────────────────────────────────────── ← Line markers +───────────────────────────────────────── ← Show length/size +───────────────────────────────────────── ← Not final content +───────────────────────────────────────── +``` + +**Benefits:** +- Shows font size and capacity without committing to content +- Faster for sketching body text +- Focuses on layout, not copywriting + +--- + +## Understanding Sketch Text Markers + +In Dog Week sketches (and most UI sketches), **text is represented by horizontal lines in groups**. + +### What You See + +``` +Page Title (centered): + ═════════════════════════ ← Thick pair, centered = Heading, center-aligned + ═════════════════ + +Body text (left-aligned): +───────────────────────────────────────── ← Thin pairs, left edge = Body, left-aligned +───────────────────────────────────────── +───────────────────────────────────────── +───────────────────────────────────────── +───────────────────────────────────────── + +Caption (right-aligned): + ────────────────── ← Short pair, right edge = Caption, right-aligned + ────────────────── + +Justified/Full-width text: +═════════════════════════════════════════════ ← Extends full width = Justified +═════════════════════════════════════════════ +``` + +### 3. Line Count → Number of Text Lines + +**Each PAIR of horizontal lines = ONE line of text** + +| Number of Pairs | Text Lines | Typical Use | +|-----------------|------------|-------------| +| 1 pair | 1 line | Headlines, labels, buttons | +| 2 pairs | 2 lines | Short headlines, subheadings | +| 3-4 pairs | 3-4 lines | Intro paragraphs, descriptions | +| 5+ pairs | 5+ lines | Body copy, long descriptions | + +--- + +## Analysis Rules + +### 1. Line Thickness → Font Weight + +**Line thickness indicates font weight (bold/regular), NOT font size** + +| Line Thickness | Font Weight | CSS Value | Typical Use | +|----------------|-------------|-----------|-------------| +| 4-5px thick (═══) | Bold | font-weight: 700 | Headlines, strong emphasis | +| 3px thick (═══) | Semibold | font-weight: 600 | Subheadings, medium emphasis | +| 2px medium (──) | Medium | font-weight: 500 | Slightly emphasized text | +| 1px normal (──) | Regular | font-weight: 400 | Body text, normal content | +| <1px thin (─) | Light | font-weight: 300 | Subtle text, de-emphasized | + +### 2. Distance Between Lines → Font Size + +**The vertical spacing between lines indicates font size** + +| Distance Between Lines | Estimated Font Size | Typical Use | +|------------------------|---------------------|-------------| +| 42-50px | 36-48px | H1 - Page titles | +| 32-40px | 28-36px | H2 - Section headings | +| 24-30px | 20-28px | H3 - Subsection headings | +| 18-24px | 14-20px | Body text / Paragraphs | +| 12-16px | 10-14px | Captions / Helper text | + +**⚠️ Important:** If distance is very large (>60px), verify this is text and not an image placeholder or colored box! + +### 2a. Visual Examples: Text vs. Image Confusion + +**TEXT - Normal spacing:** +``` +═══════════════════════════════ ← Bold line + ← 42px distance +═══════════════════════════════ ← Bold line + +This is clearly TEXT (H1 heading) +``` + +**IMAGE - Large spacing (confusion risk):** +``` +═══════════════════════════════ ← Line? + + ← 80px+ distance (too large!) + +═══════════════════════════════ ← Line? + +This might be an IMAGE PLACEHOLDER or COLORED BOX, not text! +Ask user to confirm. +``` + +**When in doubt:** If distance >60px, ask: "Is this text or an image/box?" + +### 3. Text Alignment → Horizontal Position + +**The position of line pairs within the section indicates text alignment** + +| Alignment | Visual Indicator | Typical Use | +|-----------|------------------|-------------| +| **Left-aligned** | Lines start at left edge of container | Body text, lists, labels | +| **Center-aligned** | Lines centered, equal spacing both sides | Headlines, hero text, CTAs | +| **Right-aligned** | Lines end at right edge of container | Captions, metadata, prices, dates | +| **Justified** | Lines extend full width of container | Dense body text, formal content | + +#### Visual Examples + +**Left-Aligned Text:** +``` +Container: | | + +═════════════════════════ ← Starts at left edge +═════════════════════════ + [empty space →] +``` + +**Center-Aligned Text:** +``` +Container: | | + + ═════════════════════════ ← Centered in container + ═════════════════════════ +``` + +**Right-Aligned Text:** +``` +Container: | | + + ═════════════ ← Ends at right edge + ═════════════ +``` + +**Justified/Full-Width Text:** +``` +Container: | | + +═════════════════════════════════════════════════════ ← Spans full width +═════════════════════════════════════════════════════ +``` + +--- + +### 4. Number of Lines → Content Length + +| Lines in Sketch | Content Type | Character Estimate | +|-----------------|--------------|-------------------| +| 1-2 lines | Heading/Title | 20-60 characters total | +| 3-5 lines | Short paragraph | 150-350 characters | +| 6-10 lines | Full paragraph | 400-700 characters | +| 10+ lines | Long content | 700+ characters | + +### 4. Line-Height Calculation + +**Line-height is derived from font size and spacing:** + +``` +Line-height ratio = (Distance between lines) / (Estimated font size) + +Example: +Distance: 28px +Font size: 24px +Line-height: 28 / 24 = 1.16 ≈ 1.2 +``` + +**Typical ratios:** +- **1.1-1.2** = Tight (headings) +- **1.4-1.5** = Normal (body text) +- **1.6-1.8** = Loose (airy text) + +``` +Left-aligned: Center-aligned: Right-aligned: +────────────────── ────────────────── ────────────────── +────────────────── ────────────── ────────────────── +────────────────── ────────── ────────────────── +``` + +### 5. Characters Per Line + +**Based on font size and line width:** + +``` +Font 48px: ═══════════════════ = ~20-25 chars +Font 36px: ═══════════════════════ = ~25-30 chars +Font 24px: ─────────────────────── = ~40-50 chars +Font 16px: ──────────────────────────────── = ~60-70 chars +Font 12px: ──────────────────────────────────── = ~80-90 chars +``` + +--- + +## Dog Week Example Analysis + +### Example 1: Landing Page Hero + +**Sketch shows:** +``` +═══════════════════════════════ ← Line 1 (thick, center) +═══════════════════════════ ← Line 2 (thick, center) +``` + +**Analysis:** +- **Type:** H1 Heading +- **Lines:** 2 +- **Line thickness:** 4px → **Bold** (font-weight: 700) +- **Distance between lines:** 42px → **42px font-size** +- **Line-height:** ~1.2 (calculated from spacing) +- **Alignment:** Center +- **Capacity:** ~25-30 chars per line = 50-60 total + +**Content Guidance:** +``` +English: "Welcome to Your / Dog Care Hub" (48 chars) ✅ +Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅ +``` + +### Example 2: Feature Description + +**Sketch shows:** +``` +───────────────────────────────────────── ← Line 1 +───────────────────────────────────────── ← Line 2 +───────────────────────────────────────── ← Line 3 +───────────────────────────────────────── ← Line 4 +``` + +**Analysis:** +- **Type:** Body text / Paragraph +- **Lines:** 4 +- **Line thickness:** 1px → **Regular** (font-weight: 400) +- **Distance between lines:** 24px → **16px font-size** +- **Line-height:** ~1.5 (calculated from spacing) +- **Alignment:** Left +- **Capacity:** ~60-70 chars per line = 240-280 total + +**Content Guidance:** +``` +English: "Organize your family around dog care. Assign walks, track +feeding schedules, and never miss a walk again. Perfect for busy +families who want to ensure their dogs get the care they need." +(206 chars) ✅ + +Swedish: "Organisera din familj kring hundvård. Tilldela promenader, +spåra matscheman och missa aldrig en promenad igen. Perfekt för +upptagna familjer som vill säkerställa att deras hundar får den +vård de behöver." (218 chars) ✅ +``` + +### Example 3: Button Text + +**Sketch shows:** +``` +[────────────] ← Single line inside button shape +``` + +**Analysis:** +- **Type:** Button label +- **Lines:** 1 +- **Line thickness:** 2px → **Semibold** (font-weight: 600) +- **Estimated font-size:** 16-18px (button standard) +- **Capacity:** ~8-12 characters + +**Content Guidance:** +``` +English: "Get Started" (11 chars) ✅ +Swedish: "Kom Igång" (9 chars) ✅ +``` + +--- + +## Agent Instructions + +When analyzing sketches with text placeholders: + +### Step 1: Count the Lines +``` +How many horizontal bar groups do you see? +``` + +### Step 2: Measure Line Thickness → Font Weight +``` +Line thickness indicates font weight: +- Very thick (4-5px) → Bold (font-weight: 700) +- Thick (3px) → Semibold (font-weight: 600) +- Normal (2px) → Medium (font-weight: 500) +- Thin (1px) → Regular (font-weight: 400) +- Very thin (<1px) → Light (font-weight: 300) +``` + +### Step 3: Measure Distance Between Lines → Font Size +``` +Vertical distance between horizontal lines: +- 42-50px → 36-48px font (H1) +- 32-40px → 28-36px font (H2) +- 24-30px → 20-28px font (H3) +- 18-24px → 14-20px font (Body) +- 12-16px → 10-14px font (Caption) + +⚠️ If distance is >60px, verify this is text (not image/box)! +``` + +### Step 4: Calculate Line-Height +``` +Line-height = Distance between lines / Font size + +Example: +- Distance: 28px +- Font size: 24px +- Line-height: 28 / 24 = 1.16 ≈ 1.2 +``` + +### Step 5: Calculate Capacity +``` +Lines × Characters-per-line = Total capacity + +Example: +5 lines × 60 chars/line = 300 characters +``` + +### Step 6: Generate Content Guidance +``` +"Content should be: [type], [line count] lines, ~[total chars] characters" + +Example: +"Content should be: Full paragraph, 5 lines, ~300 characters" +``` + +### Step 7: Validate Content +``` +If user provides content: +- Count actual characters +- Compare to capacity +- Warn if mismatch + +Example: +⚠️ Your content (450 chars) exceeds sketch capacity (300 chars). +Consider shortening or increasing font size. +``` + +--- + +## Benefits of This Approach + +✅ **Accurate Content Generation** +- Content matches design space +- No overflow or underflow issues +- Professional fit and finish + +✅ **Design Fidelity** +- Specifications match sketches +- Developers can trust the specs +- Reduces back-and-forth + +✅ **Multilingual Support** +- Can estimate if translation fits +- Adjust content length per language +- Prevents UI breaking + +✅ **Quality Assurance** +- Catches content length issues early +- Ensures consistency +- Professional output + +--- + +## Example in Action + +**User shares Dog Week sketch of profile setup page** + +**Agent analyzes:** + +> "Looking at the profile section heading, I see 2 thick horizontal lines, center-aligned at the top. +> +> **Analysis:** +> - 2 lines of text (thick bars) +> - Line thickness: 3px → ~28-32px font +> - Spacing: 3px → ~1.3 line-height +> - Alignment: Center +> - Capacity: ~50-60 characters (25-30 per line) +> +> **This heading should be:** Brief, 2 short lines, ~50-60 characters total +> +> **Suggested content:** +> - EN: "Complete Your / Profile Setup" (41 chars) ✅ +> - SV: "Slutför Din / Profilinställning" (45 chars) ✅ +> +> Both fit comfortably within the designed space. Does this match your intent?" + +--- + +## Integration with WDS Workflow + +This analysis happens automatically in: +- **4B: Sketch Analysis** - Initial detection +- **object-types/heading-text.md** - Detailed analysis +- **4C-04: Content & Languages** - Content validation +- **4C-08: Generate Spec** - Final documentation + +**Result:** Every text element in WDS specifications includes accurate character capacity and content guidance! 🎨✨ + +--- + +*This guide ensures all WDS projects generate content that perfectly fits the designed space.* + diff --git a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md new file mode 100644 index 00000000..886e2525 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-QUICK-REFERENCE.md @@ -0,0 +1,186 @@ +# Quick Reference: Sketch Text Analysis + +**The Correct Interpretation** + +--- + +## Step 0: Establish Scale (Holistic View) + +**Before analyzing specific text, scan the ENTIRE sketch to establish scale.** + +1. **Find Anchors:** Look for standard UI elements (Browser chrome, Scrollbars, Buttons, Icons). +2. **Determine Base Unit:** If a Scrollbar is "Standard Width" (e.g., 16px), how big is everything else relative to it? +3. **Calibrate:** Use these known objects to calibrate your eye for this specific image resolution. + +--- + +## The Two Key Measurements + +### 1. Line Thickness = Font Weight (Relative) + +**Compare lines against each other in the sketch:** + +``` +═══════════════════ ← Thicker than others = Bold (700) +─────────────────── ← Medium thickness = Medium (500) +───────────────────── ← Thinnest lines = Regular (400) +``` + +**Rule:** Relative thickness indicates hierarchy, not absolute pixels. + +### 2. Vertical Spacing = Font Size (Context-Based) + +**Estimate size by comparing to known UI elements:** + +``` +[ Button ] ← Standard height ref (~40-48px) + ↕ +═══════════════════ ← Matches button height? ~40px font (H1) + ↕ +═══════════════════ +``` + +**Context Anchors:** +- **Browser Address Bar**: ~40px height +- **Standard Button**: ~40-48px height +- **Cursor/Icon**: ~16-24px size +- **Scrollbar**: ~16px width + +**Rule:** Use these anchors to estimate the scale of text spacing. + +--- + +## Complete Analysis Pattern + +### Example: Hero Headline + +**Sketch:** +``` +═══════════════════════════════ ← Line 1: Thickest lines in sketch + ↕ Spacing ≈ Same as button height +═══════════════════ ← Line 2: Thickest lines in sketch +``` + +**Analysis:** +- **Context:** Spacing looks similar to the "Sign In" button height nearby. +- **Inference:** If button is ~48px, this font is ~48px (H1). +- **Weight:** Thicker than body text markers → **Bold**. +- **Result:** `font: bold 48px / 1.2` + +--- + +## Common Patterns + +### H1 Heading +``` +═══════════════════ ← Thickest lines + ↕ +═══════════════════ +``` +- **Clue:** Spacing matches Address Bar height (~40px) +- **Est:** ~40-48px, Bold + +### H2 Heading +``` +═══════════════════ ← Medium-Thick lines + ↕ +═══════════════════ +``` +- **Clue:** Spacing is slightly less than button height +- **Est:** ~32px, Semibold + +### Body Text +``` +───────────────────── ← Thinnest lines + ↕ +───────────────────── +``` +- **Clue:** Spacing matches scrollbar width or small icon (~16-24px) +- **Est:** ~16px, Regular + +--- + +## ⚠️ Confusion Warning + +### Text (Normal) +``` +═══════════════════ + ↕ Spacing < 2x Button Height +═══════════════════ +``` +✅ Likely TEXT + +### Image/Box (Too Large) +``` +═══════════════════ + + + ↕ Spacing > 2x Button Height + + +═══════════════════ +``` +❓ Likely IMAGE or CONTAINER + +**Rule:** If spacing seems disproportionately large compared to UI elements, verify! + +--- + +## Quick Decision Tree + +``` +See horizontal lines? + │ + ├─ Compare THICKNESS (Relative) + │ └─ Thicker than avg? → Bold + │ └─ Thinner than avg? → Regular + │ + ├─ Compare DISTANCE (Context) + │ └─ Matches Button Height? → H1 (~40-48px) + │ └─ Matches Icon Size? → Body (~16-24px) + │ └─ Huge Gap? → Image/Container + │ + └─ Check Context Anchors + └─ Address Bar, Scrollbar, Buttons +``` + +--- + +## Memory Aid + +**THICKNESS = RELATIVE WEIGHT** +**CONTEXT = SCALE** + +Think of it like looking at a map: +- Use the scale key (buttons, bars) to measure distances. +- Don't guess miles (pixels) without a reference! + +--- + +## Real Dog Week Example + +``` +═══════════════════════════════ ← Thickest lines + ↕ Matches "Sign In" button height +═══════════════════ ← Thickest lines +``` + +**Analysis:** +- Thickness: Bold (relative to body lines) +- Distance: Matches button (~48px) +- Result: `font: bold 48px / 1.2` + +**Content:** +``` +EN: "Every walk. on time. Every time." +SE: "Varje promenad. i tid. Varje gång." +``` + +Both fit in ~50-60 character capacity! ✅ + +--- + +**Remember: Context is King! Compare, don't just measure.** 📏✨ + + + diff --git a/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-STRATEGY.md b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-STRATEGY.md new file mode 100644 index 00000000..e881f438 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/SKETCH-TEXT-STRATEGY.md @@ -0,0 +1,476 @@ +# Sketch Text Strategy: Actual Text vs. Markers + +**Guidance for Creating WDS Sketches** + +--- + +## The Two Approaches + +### 1. Actual Text (Recommended for Headlines) + +**Draw readable text directly in sketch** + +``` +┌─────────────────────────────────────┐ +│ │ +│ Every walk. on time. │ +│ Every time. │ +│ │ +│ [Get Started - Free Forever] │ +│ │ +└─────────────────────────────────────┘ +``` + +**When to use:** +- Headlines (H1, H2, H3) +- Button labels +- Navigation items +- CTAs (calls-to-action) +- Any short, important text + +**Why:** +✅ Agent can read and interpret text +✅ Provides content context +✅ Shows character count naturally +✅ Guides design decisions +✅ Can still be refined during specification + +### 2. Horizontal Line Markers (For Body Text) + +**Draw lines to indicate text blocks** + +``` +┌─────────────────────────────────────┐ +│ │ +│ ─────────────────────────────────── │ ← Body text +│ ─────────────────────────────────── │ +│ ─────────────────────────────────── │ +│ ─────────────────────────────────── │ +│ │ +└─────────────────────────────────────┘ +``` + +**When to use:** +- Body paragraphs +- Long descriptions +- Feature lists (when wording TBD) +- Content where you want to show SIZE, not specific text + +**Why:** +✅ Faster to sketch +✅ Shows font size (distance between lines) +✅ Shows font weight (line thickness) +✅ Indicates capacity without committing to content +✅ Focuses on layout, not copywriting + +--- + +## Mixed Approach (Recommended) + +**Combine both methods for best results:** + +``` +┌──────────────────────────────────────────┐ +│ │ +│ Welcome to Dog Week │ ← ACTUAL TEXT (H1) +│ │ +│ ─────────────────────────────────────── │ ← LINE MARKERS +│ ─────────────────────────────────────── │ ← (Body paragraph) +│ ─────────────────────────────────────── │ +│ ─────────────────────────────────────── │ +│ │ +│ [Start Planning] │ ← ACTUAL TEXT (CTA) +│ │ +└──────────────────────────────────────────┘ +``` + +**Result:** +- Headlines provide content guidance +- Body text shows sizing and capacity +- Buttons show clear actions +- Fast to sketch, still informative + +--- + +## Dog Week Example + +### Start Page Hero Sketch + +``` +┌─────────────────────────────────────────────┐ +│ │ +│ 🐕 Dog Week │ ← Logo (actual) +│ [Sign In] SE ▼ │ ← Buttons (actual) +│ │ +│ │ +│ Every walk. on time. │ ← H1 (actual text) +│ Every time. │ +│ │ +│ ──────────────────────────────────────── │ ← Subtext (markers) +│ ──────────────────────────────────────── │ +│ │ +│ [start planning - free forever] │ ← CTA (actual) +│ │ +│ ┌───────────────────────────────────────┐ │ +│ │ │ │ +│ │ [Person with dog image] │ │ ← Image placeholder +│ │ │ │ +│ └───────────────────────────────────────┘ │ +│ │ +│ Never ask whose turn it is again │ ← Small text (actual) +│ │ +│ ─────────────────────────────────────────│ ← Feature description +│ ─────────────────────────────────────────│ ← (markers) +│ ─────────────────────────────────────────│ +│ │ +└─────────────────────────────────────────────┘ +``` + +### Agent Analysis + +**Agent reads:** +1. **Logo text:** "Dog Week" → suggests as logo content +2. **H1 actual text:** "Every walk. on time. Every time." → suggests as starting headline +3. **Marker analysis:** 2 thin lines → body text, 16px, ~120-140 chars +4. **CTA actual text:** "start planning - free forever" → suggests as button label +5. **Small actual text:** "Never ask whose turn it is again" → suggests as supporting text +6. **Marker analysis:** 3 thin lines → feature description, 16px, ~180-210 chars + +**Agent output:** +``` +I found text in your sketch: "Every walk. on time. Every time." + +Would you like to use this for the Primary Headline, or change it? + +EN: Every walk. on time. Every time. +SE: [Your Swedish translation] +``` + +**User can:** +- ✅ Keep the sketch text +- ✅ Change it completely +- ✅ Refine it slightly + +--- + +## Technical Details for Markers + +### Line Thickness → Font Weight + +``` +═══════════════════ ← 4px = Bold (700) +─────────────────── ← 2px = Medium (500) +───────────────────── ← 1px = Regular (400) +``` + +### Distance Between Lines → Font Size + +``` +═══════════════════ + ↕ 42px ← 42px font +═══════════════════ + +─────────────────── + ↕ 24px ← ~16px font (body) +─────────────────── +``` + +### Complete Example + +``` +═══════════════════ ← 4px thick + ↕ 42px +═══════════════════ ← 4px thick +``` + +**Analysis:** +- Thickness: Bold +- Distance: 42px font +- Lines: 2 +- Capacity: ~50-60 chars + +--- + +## Agent Behavior + +### When Sketch Has Actual Text + +**Agent says:** +``` +I found text in your sketch: "Every walk. on time." + +Content for Primary Headline: + +EN: Every walk. on time. +SE: + +(You can keep the sketch text or change it) +``` + +**Benefits:** +- Pre-filled starting point +- Still editable +- Saves time +- Provides context + +### When Sketch Has Line Markers + +**Agent says:** +``` +Text placeholder detected: +- 4 horizontal lines +- Line thickness: 1px → Regular weight +- Distance: 24px → 16px font +- Capacity: ~240-280 characters + +Content for Feature Description: + +Please provide content in one language, and I'll suggest translations! + +EN: +``` + +**User provides:** +``` +EN: Organize your family around dog care. Assign walks, track feeding schedules, and never miss a walk again. +``` + +**Agent suggests:** +``` +Great! Here are translation suggestions: + +SE: Organisera din familj kring hundvård. Tilldela promenader, spåra matscheman och missa aldrig en promenad igen. + +Does this work, or would you like to adjust it? +``` + +**Benefits:** +- Clear capacity guidance +- Agent suggests translations +- User reviews and confirms +- Helps with content length + +--- + +## Workflow: From Analysis to Specification + +When AI analyzes sketch text markers, the workflow is: + +### Step 1: AI Analyzes Sketch +Agent detects text markers and estimates properties: +``` +Line thickness: 3px → Bold font weight +Spacing between pairs: 24px → ~42px font size estimate +Line-height: ~1.2 (calculated from font size) +Character capacity: ~35 characters per line +``` + +### Step 2: AI Presents Estimates with Reasoning +Agent shows analysis WITH explanation of how estimates were derived: +```markdown +- **Style**: + - Font weight: Bold (from 3px thick line markers in sketch) + - Font size: 42px (est. from 24px vertical spacing between line pairs) + - Line-height: 1.2 (est. calculated as font-size × 1.2) +``` + +**Why show reasoning?** +- Designer understands **how** AI interpreted the sketch +- Designer can judge if estimation logic makes sense +- Makes it easy to adjust if sketch measurements were different +- Builds trust through transparency + +### Step 3: Designer Confirms/Adjusts +Designer reviews estimates and either: +1. **Confirms** - "Yes, 42px based on 24px spacing is correct" +2. **Adjusts** - "Actually, the spacing was 28px, so make it 48px instead" +3. **Overrides** - "Ignore the sketch measurements, I want it to be 56px" + +### Step 4: Finalize Specification +Agent updates spec with confirmed values, removes estimation notes: +```markdown +- **Style**: + - Font weight: Bold + - Font size: 48px + - Line-height: 1.15 +``` + +Clean, production-ready specification with no estimation artifacts. + +**Key Principle:** +- **All estimated values are spelled out explicitly** (not hidden) +- **Marked with (est.) label** to indicate AI interpretation +- **Designer confirms or adjusts** each estimated value +- **Label removed** once designer specifies actual values + +This ensures **transparency** about which values came from AI sketch analysis vs. designer specification. + +--- + +## Best Practices + +### ✅ DO: + +1. **Use actual text for headlines** + - Provides content direction + - Agent can read and suggest + - Still changeable during spec + +2. **Use markers for body text** + - Shows sizing without committing + - Faster to sketch + - Focuses on layout + +3. **Mix both approaches** + - Headlines = actual text + - Body = markers + - Best of both worlds + +4. **Keep sketch text informal** + - It's a suggestion, not final + - Can be refined later + - Agent will ask to confirm/change + +### ❌ DON'T: + +1. **Don't use Lorem Ipsum** + - Not helpful for context + - Agent can't interpret + - Use real(ish) content or markers + +2. **Don't commit too early** + - Sketch text is guidance + - Refinement happens in spec phase + - Stay flexible + +3. **Don't mix for same element** + - Either actual text OR markers + - Not both for one text block + - Confuses analysis + +--- + +## Workflow Integration + +### During Sketching + +**Designer:** +``` +1. Draw page layout +2. Add ACTUAL TEXT for headlines/buttons +3. Add LINE MARKERS for body paragraphs +4. Show font weight (thickness) +5. Show font size (distance) +``` + +### During Specification (Phase 4) + +**Agent:** +``` +1. Analyze sketch +2. Read any actual text found +3. Suggest sketch text as starting point +4. Analyze markers for sizing +5. Request final content +6. Allow refinement +7. Document in spec +``` + +**User:** +``` +1. See sketch text as suggestion +2. Keep, change, or refine +3. Add translations +4. Confirm length fits capacity +``` + +--- + +## Real Dog Week Flow + +### Sketch Shows: + +``` +Every walk. on time. Every time. ← Actual text in sketch +``` + +### Agent Says: + +``` +I found text in your sketch: "Every walk. on time. Every time." + +Let me suggest translations... + +Suggested content for Primary Headline: + +EN: Every walk. on time. Every time. +SE: Varje promenad. i tid. Varje gång. + +These are my suggestions. Do they work? + +1. Use these translations +2. Adjust translations +3. Manual input + +Choice [1/2/3]: +``` + +### User Says: + +``` +1 ← Accepts! +``` + +Or refines: + +``` +2 + +SE: Varje promenad. Punktligt. Varje gång. ← Adjusted +``` +EN: Every walk. on time. Every time. ← Keeps it! +SE: Varje promenad. i tid. Varje gång. +``` + +### Specification Result: + +```markdown +#### Primary Headline +**OBJECT ID**: `start-hero-headline` +- **Component**: H1 heading +- **Position**: Center of hero +- **Style**: Bold, 42px, line-height 1.2 +- **Content**: + - EN: "Every walk. on time. Every time." + - SE: "Varje promenad. i tid. Varje gång." +``` + +**Result:** Sketch text became final content! ✅ + +--- + +## Summary + +| Element Type | Sketch Method | Agent Behavior | +|--------------|---------------|----------------| +| **Headlines** | Actual text | Reads & suggests as starting content | +| **Buttons** | Actual text | Reads & suggests as button label | +| **Navigation** | Actual text | Reads & suggests as nav items | +| **Body paragraphs** | Line markers | Analyzes for size/capacity, requests content | +| **Descriptions** | Line markers | Analyzes for size/capacity, requests content | + +**Golden Rule:** +- **Important/short text** = Draw actual text +- **Long/placeholder text** = Use line markers +- **Mix both** for best results + +**Remember:** +- Sketch text is a suggestion, not final +- Agent will ask to confirm or change +- Refinement happens during specification +- Stay flexible, iterate as needed + +--- + +**Use actual text for headlines, markers for body text!** 📝✨ + diff --git a/src/modules/wds/workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md b/src/modules/wds/workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md new file mode 100644 index 00000000..639c2bef --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/TRANSLATION-ORGANIZATION-GUIDE.md @@ -0,0 +1,454 @@ +# Translation Organization Guide + +**Part of WDS Specification Pattern** + +**Purpose-Based Naming with Grouped Translations** + +--- + +## Overview + +This guide explains how to organize text content and translations in WDS specifications using **purpose-based naming** and **grouped translation** patterns. + +**Related Documentation:** +- **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** - How to analyze text markers in sketches +- **`HTML-VS-VISUAL-STYLES.md`** - HTML tags vs visual text styles +- **`WDS-SPECIFICATION-PATTERN.md`** - Complete specification format with examples + +--- + +## Core Principles + +### 1. Name by PURPOSE, Not Content + +**❌ WRONG:** +```markdown +#### Welcome Heading +**OBJECT ID**: `start-hero-welcome-heading` +- Content: "Welcome to Dog Week" +``` + +**✅ CORRECT:** +```markdown +#### Primary Headline +**OBJECT ID**: `start-hero-headline` +- Content: + - EN: "Welcome to Dog Week" + - SE: "Välkommen till Dog Week" +``` + +**Why:** If content changes to "Every walk. on time.", the Object ID still makes sense. + +--- + +### 2. Separate Structure from Content + +**Structure (Position/Style):** +```markdown +- **HTML Tag**: h1 (semantic structure for SEO/accessibility) +- **Visual Style**: Hero headline (from Design System) +- **Position**: Center of hero section, above CTA +- **Style**: + - Font weight: Bold (from 3px thick line markers) + - Font size: 42px (est. from 24px spacing between line pairs) + - Line-height: 1.2 (est. calculated from font size) +- **Behavior**: Updates with language toggle +``` + +> **Important:** HTML tags (h1-h6) define semantic structure for SEO/accessibility. Visual styles (Hero headline, Main header, Sub header, etc.) define appearance and can be applied to any HTML tag. + +> **Note:** Values marked `(est. from...)` show sketch analysis reasoning. Designer should confirm or adjust these values, then update with actual specifications. +``` + +**Content (Translations):** +```markdown +- **Content**: + - EN: "Every walk. on time. Every time." + - SE: "Varje promenad. i tid. Varje gång." +``` + +**Why:** Structure rarely changes, content often does. Keeps specs clean. + +--- + +### 3. Group Related Translations + +**❌ WRONG (Scattered):** +```markdown +#### Headline EN +"Every walk. on time." + +#### Headline SE +"Varje promenad. i tid." + +#### Body EN +"Organize your family..." + +#### Body SE +"Organisera din familj..." +``` + +**✅ CORRECT (Grouped):** +```markdown +### Hero Object +**Purpose**: Primary value proposition + +#### Primary Headline +**OBJECT ID**: `start-hero-headline` +- **Content**: + - EN: "Every walk. on time. Every time." + - SE: "Varje promenad. i tid. Varje gång." + +#### Supporting Text +**OBJECT ID**: `start-hero-supporting` +- **Content**: + - EN: "Organize your family around dog care." + - SE: "Organisera din familj kring hundvård." +``` + +**Why:** Each language reads as complete, coherent message. + +--- + +## Dog Week Examples + +### Example 1: Hero Section (Text Group) + +```markdown +### Hero Object +**Purpose**: Primary value proposition and main conversion action + +#### Primary Headline +**OBJECT ID**: `start-hero-headline` +- **Component**: H1 heading (`.text-heading-1`) +- **Position**: Center of hero, top of section +- **Style**: Bold, no italic, 42px, line-height 1.2 +- **Behavior**: Updates with language toggle +- **Content**: + - EN: "Every walk. on time. Every time." + - SE: "Varje promenad. i tid. Varje gång." + +#### Supporting Text +**OBJECT ID**: `start-hero-supporting` +- **Component**: Body text (`.text-body`) +- **Position**: Below headline, above CTA +- **Style**: Regular, 16px, line-height 1.5 +- **Behavior**: Updates with language toggle +- **Content**: + - EN: "Organize your family around dog care. Never miss a walk again." + - SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen." + +#### Primary CTA Button +**OBJECT ID**: `start-hero-cta` +- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md) +- **Position**: Center, below supporting text +- **Behavior**: Navigate to registration +- **Content**: + - EN: "start planning - free forever" + - SE: "börja planera - gratis för alltid" +``` + +**Reading Experience:** + +**English:** +> Every walk. on time. Every time. +> Organize your family around dog care. Never miss a walk again. +> [start planning - free forever] + +**Swedish:** +> Varje promenad. i tid. Varje gång. +> Organisera din familj kring hundvård. Missa aldrig en promenad igen. +> [börja planera - gratis för alltid] + +Each language flows naturally as a complete message! + +--- + +### Example 2: Form Labels (Individual Elements) + +```markdown +### Sign In Form +**Purpose**: User authentication + +#### Email Label +**OBJECT ID**: `signin-form-email-label` +- **Component**: Label text (`.text-label`) +- **Position**: Above email input field +- **For**: `signin-form-email-input` +- **Content**: + - EN: "Email Address" + - SE: "E-postadress" + +#### Email Input +**OBJECT ID**: `signin-form-email-input` +- **Component**: [Text Input](/docs/.../text-input.md) +- **Placeholder**: + - EN: "your@email.com" + - SE: "din@epost.com" + +#### Password Label +**OBJECT ID**: `signin-form-password-label` +- **Component**: Label text (`.text-label`) +- **Position**: Above password input +- **For**: `signin-form-password-input` +- **Content**: + - EN: "Password" + - SE: "Lösenord" + +#### Password Input +**OBJECT ID**: `signin-form-password-input` +- **Component**: [Password Input](/docs/.../password-input.md) +- **Placeholder**: + - EN: "Enter your password" + - SE: "Ange ditt lösenord" +``` + +--- + +### Example 3: Error Messages + +```markdown +### Validation Messages +**Purpose**: User feedback on form errors + +#### Email Required Error +**OBJECT ID**: `signin-form-email-error-required` +- **Component**: Error text (`.text-error`) +- **Position**: Below email input field +- **Trigger**: When email field is empty on submit +- **Content**: + - EN: "Email address is required" + - SE: "E-postadress krävs" + +#### Email Invalid Error +**OBJECT ID**: `signin-form-email-error-invalid` +- **Component**: Error text (`.text-error`) +- **Position**: Below email input field +- **Trigger**: When email format is invalid +- **Content**: + - EN: "Please enter a valid email address" + - SE: "Ange en giltig e-postadress" + +#### Auth Failed Error +**OBJECT ID**: `signin-form-auth-error` +- **Component**: Alert banner (`.alert-error`) +- **Position**: Above form, below page heading +- **Trigger**: When authentication fails +- **Content**: + - EN: "Invalid email or password. Please try again." + - SE: "Ogiltig e-post eller lösenord. Försök igen." +``` + +--- + +## Object ID Naming Patterns + +### Format: `{page}-{section}-{purpose}` + +**Page Examples:** +- `start` (start/landing page) +- `signin` (sign in page) +- `profile` (profile page) +- `calendar` (calendar page) + +**Section Examples:** +- `hero` (hero section) +- `header` (page header) +- `form` (form section) +- `features` (features section) +- `footer` (page footer) + +**Purpose Examples:** +- `headline` (main heading) +- `subheading` (secondary heading) +- `description` (descriptive text) +- `cta` (call-to-action button) +- `label` (form label) +- `error` (error message) +- `success` (success message) +- `supporting` (supporting/helper text) + +**Complete Examples:** +- `start-hero-headline` +- `signin-form-email-label` +- `profile-success-message` +- `calendar-header-title` +- `features-description-text` + +--- + +## Content Structure + +### Required Fields + +```markdown +#### {{Purpose_Title}} +**OBJECT ID**: `{{page-section-purpose}}` +- **Component**: {{component_type}} ({{class_or_reference}}) +- **Position**: {{position_description}} +- **Content**: + - EN: "{{english_content}}" + - SE: "{{swedish_content}}" + {{#if additional_languages}} + - {{lang}}: "{{content}}" + {{/if}} +``` + +### Optional Fields + +```markdown +- **Behavior**: {{behavior_description}} +- **Style**: {{style_specifications}} +- **For**: {{linked_input_id}} (for labels) +- **Trigger**: {{when_shown}} (for conditional text) +``` + +--- + +## Multi-Language Support + +### 2 Languages (Dog Week) + +```markdown +- **Content**: + - EN: "Welcome to Dog Week" + - SE: "Välkommen till Dog Week" +``` + +### 3+ Languages + +```markdown +- **Content**: + - EN: "Welcome to Dog Week" + - SE: "Välkommen till Dog Week" + - DE: "Willkommen bei Dog Week" + - FR: "Bienvenue à Dog Week" +``` + +### Language Codes + +- **EN** = English +- **SE** = Swedish (Svenska) +- **NO** = Norwegian +- **DK** = Danish +- **FI** = Finnish +- **DE** = German +- **FR** = French +- **ES** = Spanish +- **IT** = Italian + +--- + +## Benefits of This Pattern + +### ✅ For Translators + +```markdown +**Hero Object Translations:** + +#### Primary Headline +- EN: "Every walk. on time. Every time." +- SE: "Varje promenad. i tid. Varje gång." + +#### Supporting Text +- EN: "Organize your family around dog care." +- SE: "Organisera din familj kring hundvård." +``` + +Translator can: +- Read entire section in each language +- Ensure translations flow together +- See context immediately +- Verify character lengths + +### ✅ For Developers + +```typescript +// Object ID makes purpose clear +const headline = document.getElementById('start-hero-headline'); +const supportingText = document.getElementById('start-hero-supporting'); + +// Content referenced by language +const content = { + 'start-hero-headline': { + en: 'Every walk. on time. Every time.', + se: 'Varje promenad. i tid. Varje gång.' + } +}; +``` + +### ✅ For Maintainability + +**Content changes:** +```markdown +#### Primary Headline +**OBJECT ID**: `start-hero-headline` ← Stays same +- **Content**: + - EN: "NEW CONTENT HERE" ← Easy to update + - SE: "NYTT INNEHÅLL HÄR" +``` + +**No Object ID changes needed!** + +--- + +## Text Group Examples + +### Hero Group (Headline + Body + CTA) + +All translations grouped so each language reads coherently: + +```markdown +### Hero Object + +#### Headline +- EN: "Every walk. on time." +- SE: "Varje promenad. i tid." + +#### Body +- EN: "Never miss a walk again." +- SE: "Missa aldrig en promenad." + +#### CTA +- EN: "Get Started" +- SE: "Kom Igång" +``` + +**English reads:** "Every walk. on time. / Never miss a walk again. / [Get Started]" +**Swedish reads:** "Varje promenad. i tid. / Missa aldrig en promenad. / [Kom Igång]" + +### Feature Group (Icon + Title + Description) + +```markdown +### Feature Card 1 + +#### Feature Title +- EN: "Smart Scheduling" +- SE: "Smart Schemaläggning" + +#### Feature Description +- EN: "Automatically assign walks based on family availability." +- SE: "Tilldela promenader automatiskt baserat på familjetillgänglighet." +``` + +--- + +## Validation Checklist + +Before finalizing text specifications: + +- [ ] Object IDs use purpose-based naming (not content) +- [ ] Structure (position/style) separated from content +- [ ] All languages included for each text element +- [ ] Text groups keep translations together +- [ ] Each language reads coherently as a group +- [ ] Character lengths validated against sketch analysis +- [ ] Component references included +- [ ] Behavior specified (if applicable) + +--- + +**This pattern ensures professional, maintainable, translation-friendly specifications across all WDS projects!** 🌍✨ + + + diff --git a/src/modules/wds/workflows/4-ux-design/WDS-SPECIFICATION-PATTERN.md b/src/modules/wds/workflows/4-ux-design/WDS-SPECIFICATION-PATTERN.md new file mode 100644 index 00000000..ba8910ba --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/WDS-SPECIFICATION-PATTERN.md @@ -0,0 +1,393 @@ +# WDS Specification Pattern + +**Complete specification format for Whiteport Design Studio projects** + +--- + +## Overview + +This document defines the **WDS Specification Pattern** used in Phase 4 (UX Design) for all WDS projects. + +**Dog Week Start Page** is used as the example implementation to demonstrate the pattern in action. + +**Related Documentation:** +- **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** - How sketch analysis values are derived +- **`HTML-VS-VISUAL-STYLES.md`** - HTML tags vs visual text styles +- **`TRANSLATION-ORGANIZATION-GUIDE.md`** - Purpose-based text organization + +--- + +## Key Principles + +### 1. Purpose-Based Naming +Text objects are named by **function, not content**: +- ✅ `hero-headline` (describes purpose) +- ❌ `welcome-message` (describes content) + +### 2. Grouped Translations +All product languages grouped together per object for coherent review. + +### 3. Estimated Values from Sketch Analysis +When text properties are estimated from sketch markers: +- **Spell out the values explicitly** (e.g., `42px (est. from 24px spacing)`) +- **Mark with analysis note** to show reasoning +- **Designer confirms or adjusts** during specification dialog +- **Update with final values** once confirmed + +**Analysis methodology:** See `SKETCH-TEXT-ANALYSIS-GUIDE.md` for complete rules on deriving font weight, font size, line-height, and alignment from sketch markers. + +This ensures transparency about which values came from AI interpretation vs. designer specification. + +--- + +## The Pattern in Action + +### Hero Section Example + +```markdown +### Hero Object +**Purpose**: Primary value proposition and main conversion action + +#### Primary Headline + +**OBJECT ID**: `start-hero-headline` + +**HTML Structure:** +- **Tag**: h1 +- **Semantic Purpose**: Main page heading for SEO and accessibility + +**Visual Style:** +- **Style Name**: Hero headline +- **Font weight**: Bold (from 3px thick line markers in sketch) +- **Font size**: 56px (est. from 32px vertical spacing between line pairs) +- **Line-height**: 1.1 (est. calculated as font-size × 1.1) +- **Color**: #1a1a1a +- **Letter spacing**: -0.02em + +**Position**: Center of hero section, above supporting text +**Alignment**: center + +**Behavior**: Updates with language toggle + +**Content**: +- EN: "Every walk. on time. Every time." +- SE: "Varje promenad. i tid. Varje gång." + +> **Sketch Analysis:** Line thickness (3px) → Bold weight. Line spacing (32px) → ~56px font size estimate. Designer should confirm these values. + +#### Supporting Text + +**OBJECT ID**: `start-hero-supporting` + +**HTML Structure:** +- **Tag**: p +- **Semantic Purpose**: Paragraph text providing additional context + +**Visual Style:** +- **Style Name**: Body text large +- **Font weight**: Regular (from 1px thin line markers in sketch) +- **Font size**: 18px (est. from 14px vertical spacing between line pairs) +- **Line-height**: 1.5 (est. calculated as font-size × 1.5) +- **Color**: #4a4a4a + +**Position**: Below headline, above CTA, center-aligned +**Alignment**: center + +**Behavior**: Updates with language toggle + +**Content**: +- EN: "Organize your family around dog care. Never miss a walk again." +- SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen." + +> **Sketch Analysis:** Line thickness (1px) → Regular weight. Line spacing (14px) → ~18px font size estimate. Designer should confirm these values. + +#### Primary CTA Button +**OBJECT ID**: `start-hero-cta` +- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md) +- **Position**: Center, below supporting text, 24px margin-top +- **Behavior**: Navigate to /auth/signup +- **States**: default, hover, active, loading +- **Content**: + - EN: "start planning - free forever" + - SE: "börja planera - gratis för alltid" +``` + +**Reading in English:** +> **Every walk. on time. Every time.** +> Organize your family around dog care. Never miss a walk again. +> [start planning - free forever] + +**Reading in Swedish:** +> **Varje promenad. i tid. Varje gång.** +> Organisera din familj kring hundvård. Missa aldrig en promenad igen. +> [börja planera - gratis för alltid] + +--- + +## The Complete Process + +### Step 1: Sketch Analysis (4B) +``` +Agent sees sketch with horizontal lines: + +═══════════════════════════════ ← Line 1 (thick, 3px) +═══════════════════════════ ← Line 2 (thick, 3px) + +───────────────────────────────────────── ← Line 3 (thin, 1px) +───────────────────────────────────────── ← Line 4 (thin, 1px) + +┌─────────────────────────────┐ +│ start planning │ ← Button +└─────────────────────────────┘ + +Agent identifies: +1. TEXT GROUP (2 thick lines) - Hero headline +2. TEXT GROUP (2 thin lines) - Supporting text +3. BUTTON - CTA +``` + +### Step 2: Object Detection (4C-03 + object-router) +``` +For Object 1: + → Detects horizontal lines + → TEXT DETECTED + → Routes to heading-text.md + +heading-text.md: + → Asks: "What's the PURPOSE?" → "Primary Headline" + → Object ID: `start-hero-headline` + → Sketch analysis: 2 lines, 3px thick, ~50-60 chars + → Content guidance: Brief heading, 2 short lines + → Requests content with length validation +``` + +### Step 3: Content with Grouped Translations +``` +Agent asks: + +"What's the content for Primary Headline? + +Based on sketch: 2 lines, ~50-60 characters total + +I found text in your sketch: 'Every walk. on time. Every time.' + +Let me suggest translations... + +EN: Every walk. on time. Every time. +SE: Varje promenad. i tid. Varje gång. + +Do these work? [1] Use these [2] Adjust [3] Manual" + +User provides: +1 ← Accepts suggestions! + +Agent validates: +✅ EN: 37 chars (fits 60 capacity) +✅ SE: 36 chars (fits 60 capacity) +``` + +### Step 4: Generate Specification +```markdown +#### Primary Headline +**OBJECT ID**: `start-hero-headline` +- **Component**: H1 heading +- **Position**: Center of hero +- **Style**: Bold, 42px, line-height 1.2 +- **Content**: + - EN: "Every walk. on time. Every time." + - SE: "Varje promenad. i tid. Varje gång." +``` + +--- + +## Key Advantages + +### 1. Purpose-Based Object IDs + +**Stable Naming:** +- Content changes don't affect Object IDs +- IDs remain semantic and meaningful +- Easy to find by function + +**Examples:** +```markdown +`start-hero-headline` ← Purpose clear +`signin-form-email-label` ← Function clear +`profile-success-message` ← Role clear +``` + +### 2. Separated Concerns + +**Structure/Style** (rarely changes): +```markdown +- **Component**: H1 heading +- **Position**: Center of hero +- **Style**: Bold, 42px +``` + +**Content** (often changes): +```markdown +- **Content**: + - EN: "..." + - SE: "..." +``` + +### 3. Grouped Translations + +**Benefits:** +- Each language reads as complete message +- Translator sees full context +- Natural language flow +- Easy to verify coherence + +**Format:** +```markdown +### Text Group + +#### Element 1 +- EN: "..." +- SE: "..." + +#### Element 2 +- EN: "..." +- SE: "..." + +#### Element 3 +- EN: "..." +- SE: "..." +``` + +### 4. Character Capacity Validation + +**From Sketch Analysis:** +``` +Agent: "Sketch shows 2 lines, ~50-60 chars capacity" + +User provides: "Every walk. on time. Every time." (37 chars) + +Agent: "✅ Content fits within sketch capacity!" +``` + +**If too long:** +``` +Agent: "⚠️ Your content (85 chars) exceeds capacity (60 chars). +Consider shortening or adjusting font size." +``` + +--- + +## Complete Workflow Integration + +``` +4B: Sketch Analysis + ↓ + Identifies text groups, estimates capacity + ↓ +4C-03: Components & Objects + ↓ + object-router.md + ↓ + STEP 1: TEXT DETECTION (checks horizontal lines) + ↓ + If text → heading-text.md + ↓ + 1. Ask PURPOSE (not content) + 2. Generate Object ID from purpose + 3. Specify position/style + 4. Request content with grouped translations + 5. Validate against sketch capacity + 6. Generate specification (Dog Week format) + ↓ + Return to 4C-03 + ↓ +4C-04: Content & Languages + (Already captured in heading-text.md) + ↓ +4C-08: Generate Final Spec +``` + +--- + +## Template Structure + +**Every text element follows this format:** + +```markdown +#### {{Purpose_Title}} +**OBJECT ID**: `{{page-section-purpose}}` +- **Component**: {{type}} ({{class_or_ref}}) +- **Position**: {{position_description}} +{{#if has_behavior}} +- **Behavior**: {{behavior_description}} +{{/if}} +{{#if has_style_details}} +- **Style**: {{style_specifications}} +{{/if}} +{{#if links_to_input}} +- **For**: {{input_object_id}} +{{/if}} +- **Content**: + - EN: "{{english_text}}" + - SE: "{{swedish_text}}" + {{#each additional_language}} + - {{code}}: "{{text}}" + {{/each}} +``` + +--- + +## Real Dog Week Specifications + +These follow the exact pattern we're implementing: + +**From 1.1-Start-Page.md:** +```markdown +#### Primary Headline +**OBJECT ID**: `start-hero-headline` +- **Component**: H1 heading (`.text-heading-1`) +- **Content**: + - EN: "Every walk. on time. Every time." + - SE: "Varje promenad. i tid. Varje gång." + +#### Primary CTA Button +**OBJECT ID**: `start-hero-cta` +- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md) +- **Content**: + - EN: "start planning - free forever" + - SE: "börja planera - gratis för alltid" +``` + +**From 1.2-Sign-In.md (Header example):** +```markdown +#### Sign In Button +**OBJECT ID**: `start-header-signin` +- **Component**: [Button Secondary](/docs/D-Design-System/.../Button-Secondary.md) +- **Content**: + - EN: "Sign in" + - SE: "Logga in" +- **Behavior**: Navigate to sign-in page +``` + +--- + +## Specification Checklist + +For each text element: + +- [ ] **Purpose-based name** (not content-based) +- [ ] **Object ID** from purpose: `{page}-{section}-{purpose}` +- [ ] **Component** reference specified +- [ ] **Position** clearly described +- [ ] **Style** separated from content +- [ ] **Behavior** specified if applicable +- [ ] **Content** with grouped translations: + - [ ] EN: "..." + - [ ] SE: "..." + - [ ] Additional languages if needed +- [ ] **Character length** validated against sketch +- [ ] **Part of text group** if applicable + +--- + +**This is the WDS standard for text specifications, proven by Dog Week!** 🎨🌍✨ + diff --git a/src/modules/wds/workflows/4-ux-design/object-types/ROUTER-FLOW-DIAGRAM.md b/src/modules/wds/workflows/4-ux-design/object-types/ROUTER-FLOW-DIAGRAM.md new file mode 100644 index 00000000..7834cd06 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/object-types/ROUTER-FLOW-DIAGRAM.md @@ -0,0 +1,271 @@ +# Object Router Flow Diagram + +**Updated with Text-First Detection** + +--- + +## Complete Flow + +``` +┌─────────────────────────────────────────────────────────┐ +│ 4C-03: Components & Objects │ +│ (For each object, top-left to bottom-right) │ +└─────────────────────┬───────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ OBJECT-ROUTER.MD │ +│ Step 1: TEXT DETECTION FIRST │ +└─────────────────────┬───────────────────────────────────┘ + │ + ▼ + ┌────────────────────────┐ + │ Horizontal lines │ + │ detected in sketch? │ + └────────┬───────┬───────┘ + │ │ + YES ◄─────┘ └─────► NO + │ │ + ▼ ▼ +┌──────────────────────┐ ┌──────────────────────────┐ +│ ✓ TEXT DETECTED │ │ Step 2: ANALYZE │ +│ │ │ OTHER OBJECT TYPE │ +│ Quick Analysis: │ │ │ +│ - Line count │ │ Check for: │ +│ - Thickness │ │ - Button shapes │ +│ - Spacing │ │ - Input boxes │ +│ - Alignment │ │ - Image placeholders │ +│ │ │ - Containers │ +│ Appears to be: │ │ - Interactive elements │ +│ {{text_type}} │ └────────┬─────────────────┘ +└──────┬───────────────┘ │ + │ ▼ + │ ┌────────────────────────────┐ + │ │ Agent suggests │ + │ │ interpretation with │ + │ │ reasoning │ + │ └────────┬───────────────────┘ + │ │ + │ ▼ + │ ┌────────────────────────────┐ + │ │ User confirms: │ + │ │ 1. Yes │ + │ │ 2. Close - clarify │ + │ │ 3. No - different │ + │ └────────┬───────────────────┘ + │ │ + │ ▼ + │ ┌────────────────────────────┐ + │ │ Confirmed object type │ + │ └────────┬───────────────────┘ + │ │ + ▼ ▼ +┌─────────────────────────────────────────────────────────┐ +│ ROUTE TO OBJECT-SPECIFIC INSTRUCTION FILE │ +└─────────────────────┬───────────────────────────────────┘ + │ + ┌─────────────┴─────────────────────┐ + │ │ + ▼ ▼ +┌──────────────────┐ ┌──────────────────────┐ +│ heading-text.md │ │ Other object files: │ +│ │ │ │ +│ Complete text │ │ • button.md │ +│ analysis: │ │ • text-input.md │ +│ │ │ • link.md │ +│ 1. Object ID │ │ • image.md │ +│ 2. Text type │ │ • card.md │ +│ 3. Sketch │ │ • modal-dialog.md │ +│ analysis: │ │ • table.md │ +│ - Lines │ │ • list.md │ +│ - Thickness │ │ • navigation.md │ +│ - Spacing │ │ • badge.md │ +│ - Capacity │ │ • alert-toast.md │ +│ 4. Content │ │ • progress.md │ +│ guidance │ │ • video.md │ +│ 5. Styling │ │ • custom.md │ +│ 6. Responsive │ │ │ +│ 7. Generate │ │ Each with: │ +│ spec │ │ - Object ID │ +└────────┬─────────┘ │ - Type-specific │ + │ │ analysis │ + │ │ - Complete examples │ + │ │ - Generate spec │ + │ └──────────┬───────────┘ + │ │ + └─────────────┬───────────────────┘ + │ + ▼ + ┌─────────────────────────────┐ + │ Specification Complete │ + │ │ + │ Object documented with: │ + │ - Object ID assigned │ + │ - Complete specification │ + │ - Examples included │ + │ - Consistent format │ + └─────────────┬───────────────┘ + │ + ▼ + ┌─────────────────────────────┐ + │ Return to 4C-03 │ + │ │ + │ Next object? [Y/N] │ + │ - YES: Loop back to router │ + │ - NO: Section complete │ + └─────────────────────────────┘ +``` + +--- + +## Key Changes + +### OLD: Generic Object Detection +``` +1. Ask user "What type is this?" [list of 20 options] +2. User selects from list +3. Route to file +``` + +### NEW: Text-First with Intelligence +``` +1. Check for horizontal lines FIRST + ├─ YES → Text detected → Route to heading-text.md + └─ NO → Continue analysis +2. Agent analyzes and suggests with reasoning +3. User confirms quickly +4. Route to appropriate file +``` + +--- + +## Text Detection Flow (Detailed) + +``` +Object Router detects horizontal lines: + +═══════════════════════════════ +═══════════════════════════ + + ↓ + +Agent says: +"✓ TEXT ELEMENT DETECTED + +I see 2 thick horizontal lines - text content. + +Quick Analysis: +- 2 lines (text placeholders) +- Thickness: 3px +- Spacing: 3px +- Alignment: Center + +This appears to be HEADING (H2). + +→ Loading text-specific instructions..." + + ↓ + +Routes to heading-text.md + + ↓ + +heading-text.md executes: +1. Confirms text type +2. Analyzes sketch in detail: + - Estimates font size (28-32px) + - Estimates line-height (1.3) + - Calculates capacity (50-60 chars) +3. Requests content with guidance +4. Validates content length +5. Specifies styling +6. Generates complete spec + + ↓ + +Returns to 4c-03 with completed specification +``` + +--- + +## Benefits + +### 1. Efficiency +- Text detected immediately (no menu selection) +- Most common object type caught first +- Reduces decision points + +### 2. Accuracy +- Text has unique signature (horizontal lines) +- Clear visual indicator +- Hard to misidentify + +### 3. Completeness +- Routes to specialized text analysis +- Character capacity automatic +- Content guidance immediate + +### 4. Intelligence +- Agent demonstrates understanding +- Natural interpretation flow +- Trust-the-agent philosophy + +--- + +## Example Scenarios + +### Scenario 1: Page with Heading + Paragraph + Button + +``` +Sketch shows (top to bottom): + +═══════════════════════════════ ← 1. Text: pair of THICK lines (1 line of text) +═══════════════════════════════ = Heading (bold font weight) + +───────────────────────────────── ← 2. Text: 2 pairs of THIN lines (2 lines of text) +───────────────────────────────── = Body paragraph (regular font weight) + +───────────────────────────────── Large spacing between pairs = larger font +───────────────────────────────── + +┌──────────────────┐ +│ Get Started │ ← 3. Button +└──────────────────┘ + +Router processes: +1. Object 1: Detects 1 pair of thick lines → heading-text.md → H2 heading (bold, ~1 line) +2. Object 2: Detects 2 pairs of thin lines → heading-text.md → Body paragraph (~2 lines) +3. Object 3: Detects button shape → button.md → Primary button +``` + +### Scenario 2: Form with Labels + Inputs + +``` +Sketch shows: + +══════════ ← 1. Text: pair of thin lines (1 line = label) +══════════ Small spacing = smaller font + +┌───────────────────────────────┐ +│ │ ← 2. Input box +└───────────────────────────────┘ + +────────── ← 3. Text: pair of thin lines (1 line = label) +────────── Small spacing = smaller font + +┌───────────────────────────────┐ +│ │ ← 4. Input box +└───────────────────────────────┘ + +Router processes: +1. Object 1: Detects pair of lines → heading-text.md → Label text (~20-30 chars) +2. Object 2: Detects input box → text-input.md → Email input +3. Object 3: Detects pair of lines → heading-text.md → Label text (~20-30 chars) +4. Object 4: Detects input box → text-input.md → Password input +``` + +--- + +**Text-first detection ensures accurate routing and complete text analysis!** 📝✨ + + diff --git a/src/modules/wds/workflows/4-ux-design/object-types/TEXT-DETECTION-PRIORITY.md b/src/modules/wds/workflows/4-ux-design/object-types/TEXT-DETECTION-PRIORITY.md new file mode 100644 index 00000000..009af5ac --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/object-types/TEXT-DETECTION-PRIORITY.md @@ -0,0 +1,362 @@ +# Text Detection Priority Rules + +**For Object Router - Always Check for Text FIRST** + +--- + +## Critical Rule: Text Markers = PAIRS of Lines + +**✅ Text = Two horizontal lines together** (representing one line of text) + +``` +═══════════════════════════ ← Line 1 of pair +═══════════════════════════ ← Line 2 of pair = ONE line of text +``` + +**❌ Single line alone = NOT text** (it's a decorative element) + +``` +═══════════════════════════ ← SINGLE LINE = divider, border, underline (NOT text) +``` + +**Important Exception:** Very schematic sketches or miniatures (rare cases) might use single lines for text, but the default assumption should be: **single line = decorative element**. + +--- + +## Why Text Detection is First + +Text elements are the most common objects in sketches, and they have a distinctive visual signature (horizontal line pairs). Detecting them first: +- ✅ Reduces confusion +- ✅ Routes to text-specific analysis immediately +- ✅ Ensures character capacity is calculated +- ✅ Prevents misidentification as other elements + +--- + +## Text Detection Signatures + +### Text Markers (Paired Lines) + +**1 line of heading text (ONE PAIR = ONE TEXT LINE):** +``` +═══════════════════════════ ← Thick pair line 1 +═══════════════════════════ ← Thick pair line 2 = ONE text line +``` + +**2 lines of heading text (TWO PAIRS = TWO TEXT LINES):** +``` +═══════════════════════════ ← Pair 1 line 1 +═══════════════════════════ ← Pair 1 line 2 = Text line 1 + Small gap +═══════════════════════════ ← Pair 2 line 1 +═══════════════════════════ ← Pair 2 line 2 = Text line 2 +``` + +**4 lines of body text (FOUR PAIRS = FOUR TEXT LINES):** +``` +───────────────────────────── ← Pair 1 +───────────────────────────── + +───────────────────────────── ← Pair 2 +───────────────────────────── + +───────────────────────────── ← Pair 3 +───────────────────────────── + +───────────────────────────── ← Pair 4 +───────────────────────────── +``` + +**Label (short text, ONE PAIR = ONE TEXT LINE):** +``` +══════════ ← Short pair line 1 +══════════ ← Short pair line 2 = ONE short text line +``` + +### NOT Text Markers (Single Lines = Decorative Elements) + +**❌ Horizontal divider (`
`):** +``` +═══════════════════════════ ← SINGLE LINE = section divider +``` + +**❌ Underline (decorative):** +``` +Main Heading +───────────────────────────── ← SINGLE LINE = decorative underline +``` + +**❌ Border line:** +``` +___________________________ ← SINGLE LINE = top/bottom border +``` + +**❌ Separator:** +``` +Section 1 content... + +───────────────────────────── ← SINGLE LINE = visual separator + +Section 2 content... +``` + +--- + +## Detection Logic + +### Step 1: Look for Paired Horizontal Lines + +``` +IF horizontal lines come in pairs (2 lines close together): + → TEXT MARKER + → Count pairs to get number of text lines + → Route to heading-text.md + +ELSE IF single horizontal line: + → DECORATIVE ELEMENT (divider, border, underline) + → Document as visual element, not text + +ELSE IF sees button shape (box with text): + → BUTTON + → Route to button.md + +ELSE IF sees input box (rectangular border): + → INPUT FIELD + → Route to text-input.md + +... etc +``` + +### Step 2: Analyze Text Marker Pairs + +**Once text markers are detected, route to `heading-text.md` for complete analysis.** + +The detailed analysis rules are documented in **`SKETCH-TEXT-ANALYSIS-GUIDE.md`**, which covers: +- Line thickness → font weight +- Line spacing between pairs → font size +- Line position in container → text alignment +- Line count → number of text lines +- Line length → character capacity + +**This file focuses on DETECTION only. For ANALYSIS, see `SKETCH-TEXT-ANALYSIS-GUIDE.md`.** + +--- + +## Text vs. Other Elements + +### ✅ Text Element (Horizontal Line PAIRS) +``` +═══════════════════════════ ← Pair indicating text +═══════════════════════════ + +───────────────────────────── ← Another pair +───────────────────────────── +``` +**Detection:** Lines come in pairs, parallel, evenly spaced +**Route to:** `heading-text.md` + +### ❌ NOT Text - Decorative Line (SINGLE) +``` +═══════════════════════════ ← Single line alone +``` +**Detection:** Single horizontal line, no pair +**Type:** Divider, border, separator, underline +**Action:** Document as decorative visual element + +### ❌ NOT Text - Button +``` +┌─────────────────┐ +│ Button Label │ ← Box with centered text inside +└─────────────────┘ +``` +**Detection:** Rectangle with text inside, clickable appearance +**Route to:** `button.md` + +### ❌ NOT Text - Input Field +``` +┌───────────────────────────┐ +│ Placeholder text... │ ← Box with light text inside +└───────────────────────────┘ +``` +**Detection:** Rectangle with subtle border, input appearance +**Route to:** `text-input.md` + +### ❌ NOT Text - Image + +**WDS Best Practice: Sketch the actual image content** + +``` +┌─────────────────┐ +│ ~ ~ ~ │ ← Sketch of clouds (hero image background) +│ ~ ~ ~ │ +└─────────────────┘ + +┌─────────────────┐ +│ ◠ ◠ │ ← Sketch of face/person (profile photo) +│ ᵕ │ +└─────────────────┘ + +┌─────────────────┐ +│ /\ /\ │ ← Sketch of mountains/landscape +│ / \/ \ │ +└─────────────────┘ +``` + +**WDS Recommends:** +- ✅ **Draw what the image shows** - Sketch the actual content (person, landscape, product) +- ✅ **Use soft shapes** - Clouds, waves, organic shapes for abstract images +- ❌ **Avoid "X" markers** - Too intrusive and provides no content guidance + +**Why?** Sketching actual image content: +- Provides visual direction and context +- Helps with AI interpretation of image purpose +- Guides content selection and art direction +- More inspiring and communicative than placeholder X + +**Detection:** Rectangle containing sketch/drawing, not text markers +**Route to:** `image.md` + +### ❌ NOT Text - Link (Often With Text) +``` +══════════ ← Text pair (the link text) +══════════ + ↑ underline indicator or different color +``` +**Detection:** Text with underline or special formatting indicating clickability +**Route to:** `link.md` (which handles the text content) + +--- + +## Detection Algorithm (Pseudo-code) + +```python +def detect_object_type(sketch_element): + """ + Always check for text FIRST before other object types + """ + + # Step 1: Check for horizontal line pairs (TEXT) + if has_horizontal_lines(sketch_element): + lines = get_horizontal_lines(sketch_element) + pairs = group_lines_into_pairs(lines, max_distance=4px) + + if len(pairs) > 0: + # This is text! Count pairs = text lines + text_line_count = len(pairs) + + # Analyze each pair + for pair in pairs: + thickness = measure_line_thickness(pair) + spacing = measure_spacing_between_pairs(pairs) + + font_weight = thickness_to_weight(thickness) + font_size = spacing_to_size(spacing) + + return route_to("heading-text.md", { + "line_count": text_line_count, + "font_weight": font_weight, + "font_size_estimate": font_size + }) + + elif len(lines) == 1: + # Single line = decorative element + return { + "type": "decorative_line", + "purpose": "divider or border" + } + + # Step 2: Check for other object types + if has_button_shape(sketch_element): + return route_to("button.md") + + if has_input_box_shape(sketch_element): + return route_to("text-input.md") + + if has_image_placeholder(sketch_element): + return route_to("image.md") + + # ... etc +``` + +--- + +## Examples from Dog Week + +### Example 1: Hero Headline + +**Sketch:** +``` +═══════════════════════════════ ← Thick pair detected +═══════════════════════════════ +``` + +**Detection:** +- ✅ **Pair detected** → This is TEXT +- **Route to:** `heading-text.md` for detailed analysis + +**For complete analysis of thickness, spacing, size, see:** `SKETCH-TEXT-ANALYSIS-GUIDE.md` + +--- + +### Example 2: Supporting Paragraph + +**Sketch:** +``` +───────────────────────────────────────── ← Thin pairs detected +───────────────────────────────────────── + +───────────────────────────────────────── +───────────────────────────────────────── +``` + +**Detection:** +- ✅ **2 pairs detected** → This is TEXT (2 lines) +- **Route to:** `heading-text.md` for detailed analysis + +**For complete analysis of thickness, spacing, size, see:** `SKETCH-TEXT-ANALYSIS-GUIDE.md` + +--- + +### Example 3: Divider Line (NOT TEXT) + +**Sketch:** +``` +Section 1 content... + +───────────────────────────────────────── ← Single line + +Section 2 content... +``` + +**Detection:** +- ❌ **Single line detected** (no pair) → NOT text +- **Type:** Decorative `
` element + +--- + +## Key Takeaways + +### Detection Rules (This File) +1. **Text markers ALWAYS come in pairs** (two lines = one text line) +2. **Single lines are decorative** (dividers, borders, underlines) +3. **Detect text FIRST** before checking for other object types +4. **Count pairs to get text line count** (3 pairs = 3 lines of text) + +### Analysis Rules (See SKETCH-TEXT-ANALYSIS-GUIDE.md) +5. **Line thickness → font weight** +6. **Spacing between pairs → font size** +7. **Line position → text alignment** +8. **Line length → character capacity** + +--- + +## Related Documentation + +- **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** ← Complete analysis rules (MASTER GUIDE) +- **`heading-text.md`** ← Text object instruction file (uses analysis rules) +- **`SKETCH-TEXT-QUICK-REFERENCE.md`** ← Quick lookup table + +--- + +**This file: DETECTION logic. For detailed ANALYSIS rules, see SKETCH-TEXT-ANALYSIS-GUIDE.md** 🎯 + diff --git a/src/modules/wds/workflows/4-ux-design/object-types/button.md b/src/modules/wds/workflows/4-ux-design/object-types/button.md new file mode 100644 index 00000000..33d6557d --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/object-types/button.md @@ -0,0 +1,322 @@ +# Object Type: Button + +**Goal:** Document button component with complete specification + +--- + +## BUTTON IDENTIFICATION + +**Documenting button: {{button_description}}** + +--- + +## OBJECT ID + +Generate Object ID using format: +`{page}-{section}-{element}-button` + +Example: `signin-form-submit-button` + + +**Object ID:** `{{generated_object_id}}` + +--- + +## BUTTON TYPE + +**What type of button is this?** + +1. **Primary** - Main action (e.g., Submit, Save, Continue) +2. **Secondary** - Alternative action (e.g., Cancel, Back) +3. **Tertiary/Text** - Low priority (e.g., Skip, Learn More) +4. **Destructive** - Dangerous action (e.g., Delete, Remove) +5. **Icon Button** - Icon only, no text +6. **Link Button** - Styled as button but navigates + +Choice [1-6]: + +Store button_type + +--- + +## DESIGN SYSTEM COMPONENT + +{{#if design_system_enabled}} +**Design System component:** + +1. **Use existing component** - From your component library +2. **Create new component** - Add this to the Design System +3. **Page-specific only** - Not a reusable component + +Choice [1/2/3]: + + + **Which existing component?** + + From your component library: + {{list_available_button_components}} + + Component name: + + Store design_system_component + Store component_status = "existing" + + + + **New component name:** + + Suggested: `Button-{{button_type}}` + + Component name: + + Store design_system_component + Store component_status = "new" + Mark for Design System addition in Phase 5 + + ✅ This button will be added to your Design System in Phase 5. + + + + Store component_status = "page-specific" + +{{else}} +Store component_status = "page-specific" +{{/if}} + +--- + +## BUTTON CONTENT + +**Button text in all languages:** + +{{#each language}} +- **{{language}}:** +{{/each}} + + +Store button_text for each language + +**Does the button have an icon?** + +1. Yes - Icon before text +2. Yes - Icon after text +3. Yes - Icon only (no text) +4. No - Text only + +Choice [1-4]: + + + **Icon name/type:** (e.g., arrow-right, check, trash) + Store icon_name and icon_position + + +--- + +## BUTTON STATES + +**Let's define all button states.** + +**For each state, describe the appearance:** + +**Default state:** +- Background color: +- Text color: +- Border: + +**Hover state:** +- Background color: +- Text color: +- Border: +- Other changes (shadow, scale, etc.): + +**Active/Pressed state:** +- Background color: +- Text color: +- Visual feedback: + +**Disabled state:** +- Background color: +- Text color: +- Cursor: +- Why disabled: + +**Loading state** (if applicable): +- Show spinner: yes/no +- Loading text (in all languages): +- Disable other actions: yes/no + + +Store state definitions for all states + +--- + +## BUTTON INTERACTION + +**What happens when user clicks this button?** + +Describe the complete flow: +1. User clicks... +2. Button changes to... (state) +3. System does... (action/API call) +4. If success... +5. If error... +6. User sees... (result) +7. Navigate to... (if applicable) + + +Store interaction_flow + +--- + +## VALIDATION & REQUIREMENTS + +**Any requirements before button can be clicked?** + +- Form validation needed: yes/no +- Required fields must be filled: yes/no +- User must be authenticated: yes/no +- Other prerequisites: + + +Store prerequisites + +--- + +## GENERATE BUTTON SPECIFICATION + +Generate button specification using format: + +```markdown +### {{button_name}} + +**Object ID:** `{{object_id}}` +**Type:** {{button_type}} +{{#if design_system_enabled}} +**Design System Component:** {{design_system_component}} +**Figma Component:** {{figma_component_name}} +{{/if}} + +**Content:** +{{#each language}} +- **{{language}}:** {{button_text}} +{{/each}} + +{{#if has_icon}} +**Icon:** {{icon_name}} ({{icon_position}}) +{{/if}} + +**States:** + +*Default:* +- Background: {{default_bg}} +- Text: {{default_text}} +- Border: {{default_border}} + +*Hover:* +- Background: {{hover_bg}} +- Text: {{hover_text}} +- Changes: {{hover_changes}} + +*Active:* +- Background: {{active_bg}} +- Text: {{active_text}} +- Feedback: {{active_feedback}} + +*Disabled:* +- Background: {{disabled_bg}} +- Text: {{disabled_text}} +- Cursor: not-allowed +- When: {{disabled_condition}} + +{{#if has_loading_state}} +*Loading:* +- Spinner: visible +- Text: {{loading_text}} +- Actions: disabled +{{/if}} + +**Interaction:** +1. {{interaction_step_1}} +2. {{interaction_step_2}} +... + +{{#if has_prerequisites}} +**Requirements:** +- {{prerequisite_list}} +{{/if}} +``` + + +✅ **Button documented!** + +Specification added to page document. + +--- + +## EXAMPLE OUTPUT + +```markdown +### Submit Button + +**Object ID:** `signin-form-submit-button` +**Type:** Primary +**Design System Component:** primary-button-large +**Figma Component:** Button/Primary/Large + +**Content:** +- **English:** Sign In +- **Swedish:** Logga In + +**Icon:** None + +**States:** + +*Default:* +- Background: #0066CC (primary blue) +- Text: #FFFFFF (white) +- Border: none +- Border-radius: 8px +- Padding: 12px 24px + +*Hover:* +- Background: #0052A3 (darker blue) +- Text: #FFFFFF +- Changes: slight shadow (0 2px 8px rgba(0,0,0,0.15)) + +*Active:* +- Background: #003D7A (even darker) +- Text: #FFFFFF +- Feedback: scale(0.98), shadow removed + +*Disabled:* +- Background: #CCCCCC (gray) +- Text: #666666 (dark gray) +- Opacity: 0.6 +- Cursor: not-allowed +- When: Form validation fails or during submission + +*Loading:* +- Spinner: visible (white, 16px) +- Text (EN): "Signing in..." +- Text (SV): "Loggar in..." +- Actions: All form interactions disabled + +**Interaction:** +1. User clicks button +2. Button enters loading state (spinner shows) +3. Validate all form fields +4. If validation fails: show field errors, exit loading +5. If validation passes: POST to /api/auth/signin +6. On API success: redirect to /dashboard +7. On API error: show error message above form, exit loading state + +**Requirements:** +- Email field must contain valid email +- Password field must not be empty +- No existing submission in progress +``` + +--- + +**Return to 4c-03 to continue with next object** + diff --git a/src/modules/wds/workflows/4-ux-design/object-types/heading-text.md b/src/modules/wds/workflows/4-ux-design/object-types/heading-text.md new file mode 100644 index 00000000..3347b2f3 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/object-types/heading-text.md @@ -0,0 +1,515 @@ +# Object Type: Heading/Text (with Purpose-Based Organization) + +**Goal:** Document text element with purpose-based naming and grouped translations + +--- + +## TEXT IDENTIFICATION & ANALYSIS + +**Analyzing text element from sketch...** + +First, check if sketch contains ACTUAL TEXT (readable words): +- Headlines often drawn as actual text +- Provides content guidance +- Can change during conversation + + + + Extract text from sketch + **Text found in sketch:** "{{extracted_text}}" + +I can use this as a starting suggestion, but we can change it if needed. + + + + Analyze text placeholders using rules from SKETCH-TEXT-ANALYSIS-GUIDE.md: + - Count horizontal line pairs (pairs = text lines) + - Measure line thickness (thickness → font weight) + - Measure distance between line pairs (spacing → font size estimate) + - Check line position in container (position → text alignment) + - Calculate line-height from font size + - Estimate character capacity from line length + + + **Text placeholder detected:** + + **Sketch Analysis:** + - **{{line_count}} line pairs** → {{line_count}} lines of text + - **Line thickness:** {{thickness}} → **{{estimated_font_weight}}** + - **Line spacing:** {{distance_between_lines}} → **~{{estimated_font_size}}** font size + - **Line-height:** ~{{estimated_line_height}} (calculated from font size) + - **Alignment:** {{detected_alignment}} (from line position) + - **Capacity:** ~{{total_chars}} characters per line + + **This appears to be:** {{text_type}} (heading/body/caption/label) + + ⚠️ **Note:** If spacing is very large (>60px), verify this is text and not an image placeholder. + + 💡 **Analysis rules:** See `SKETCH-TEXT-ANALYSIS-GUIDE.md` for complete methodology. + + +--- + +## STEP 1: PURPOSE-BASED NAMING + +**Let's define this text element by its PURPOSE, not its content.** + +**What is the PURPOSE of this text on the page?** + +Think about function, not content: +- "Primary headline" (not "Welcome to Dog Week") +- "Feature description" (not "Organize your family") +- "CTA supporting text" (not "Free forever") +- "Error message" (not "Invalid email") +- "Form label" (not "Email Address") + +Purpose/function: + +Store text_purpose (e.g., "hero-headline", "feature-description", "error-message") + +--- + +## STEP 2: OBJECT ID (Based on Purpose) + +Generate Object ID from purpose: +`{page}-{section}-{purpose}` + +Examples: +- `start-hero-headline` (not `start-hero-welcome-text`) +- `signin-form-email-label` (not `signin-form-email-address-text`) +- `profile-success-message` (not `profile-saved-successfully-text`) + + +**Object ID:** `{{generated_object_id}}` + +Based on purpose: {{text_purpose}} + +--- + +## STEP 3: DESIGN SYSTEM COMPONENT + +{{#if design_system_enabled}} +**Design System component:** + +1. **Use existing typography** - From your Design System +2. **Create new typography** - Add this style to the Design System +3. **Page-specific only** - Not a reusable style + +Choice [1/2/3]: + + + **Which existing typography component?** + + From your Design System: + {{list_available_typography_components}} + + Component name: + + Store design_system_component + Store component_status = "existing" + + + + **New typography component name:** + + Suggested: `Typography-{{text_type}}` (e.g., Typography-H1, Typography-Body) + + Component name: + + Store design_system_component + Store component_status = "new" + Mark for Design System addition in Phase 5 + + ✅ This typography style will be added to your Design System in Phase 5. + + + + Store component_status = "page-specific" + +{{else}} +Store component_status = "page-specific" +{{/if}} + +--- + +## STEP 4: TEXT TYPE & POSITIONING + +**Text element specifications:** + +**HTML Tag** (semantic structure for SEO/accessibility): +- h1 (main page heading, only ONE per page) +- h2 (major section heading) +- h3 (subsection heading) +- h4/h5/h6 (minor headings) +- p (paragraph) +- span (inline, no semantic meaning) + +HTML tag: + +**Visual Style Type** (appearance, from Design System): +- Hero headline (large display text for hero sections) +- Main header (primary page/section headers) +- Sub header (section headings, emphasized) +- Sub header light (lighter section headings) +- Card header (headers within cards/panels) +- Small header (minor headers, labels) +- Body text (standard paragraphs) +- Body text large (larger body, intro text) +- Body text small (smaller body, secondary info) +- Caption text (image captions, metadata) +- Label text (form labels, UI labels) + +Visual style name: + +> **Important:** HTML tags define document structure. Visual styles define appearance. Keep them separate! + +**Position on page:** +- Vertical: (top/middle/bottom of section) +- Horizontal: (left/center/right) +- Relative to: (e.g., "above CTA button", "below headline") + +**Text Alignment** (from sketch line position): +- left (lines start at left edge) +- center (lines centered in container) +- right (lines end at right edge) +- justified (lines span full width) + +Alignment: + +**Style specifications:** +- Font size: {{estimated_font_size}} (est. from {{line_spacing}} spacing in sketch) +- Font weight: {{estimated_font_weight}} (from {{line_thickness}} line thickness in sketch) +- Line height: {{estimated_line_height}} (est. calculated from font size) +- Text color: +- Text transform: (none/uppercase/capitalize) + + +Store html_tag, visual_type, visual_style_name, position, and style specifications + +--- + +## STEP 5: CONTENT WITH GROUPED TRANSLATIONS + +**Now let's specify the actual content.** + +**IMPORTANT:** Translations will be grouped so each language reads coherently. +{{#if sketch_has_text}} +Content length: Based on sketch text "{{extracted_text}}" +{{else}} +Content length: ~{{total_chars}} characters (from sketch analysis) +{{/if}} + +**Project languages:** {{product_languages}} (from workflow config) + + + **I found text in your sketch:** "{{extracted_text}}" + +Let me suggest translations for all configured languages... + + Translate extracted_text to all product_languages + Generate suggested translations using context and best practices + + **Suggested content for {{text_purpose}}:** + +{{#each product_languages}} +**{{this}}:** {{suggested_translation}} +{{/each}} + +These are my suggestions based on the sketch text. Please review and adjust as needed! + + Do these translations work, or would you like to change any of them? + +1. **Use these translations** - They look good! +2. **Adjust translations** - I'll provide different versions +3. **Manual input** - I'll enter them myself + +Choice [1/2/3]: + + + Which language(s) need adjustment? + +{{#each product_languages}} +**{{this}}:** {{suggested_translation}} ← Change this? +{{/each}} + +Please provide the corrected versions: + + + + **Content for this {{text_purpose}}:** + +{{#each product_languages}} +**{{this}}:** + +{{/each}} + + + + + + **Content for this {{text_purpose}}:** + +Please provide content. I'll suggest translations once you give me the first language! + +**{{primary_language}}:** + + + + After receiving primary language content, suggest translations for remaining languages + + **Translation suggestions:** + +{{#each remaining_languages}} +**{{this}}:** {{suggested_translation}} +{{/each}} + +Would you like to use these, or provide your own? + + +Store content for each language +Validate length against sketch capacity (if applicable) + + + ⚠️ **Length Warning:** + - Sketch capacity: ~{{sketch_capacity}} characters + - Your content: {{actual_chars}} characters + + Consider shortening or adjusting design. + + +--- + +## STEP 6: BEHAVIOR (if applicable) + +**Does this text change or have behavior?** + +- Static (never changes): no +- Updates with language toggle: yes +- Dynamic content (from API/user): yes +- Conditional display: yes + +If yes, describe behavior: + +Store behavior if applicable + +--- + +## STEP 7: GENERATE SPECIFICATION (WDS Pattern) + +Generate specification following WDS specification pattern: + +```markdown +#### {{Text_Purpose_Title}} + +**OBJECT ID**: `{{object_id}}` + +**HTML Structure:** +- **Tag**: {{html_tag}} +- **Semantic Purpose**: {{semantic_description}} + +**Visual Style:** +{{#if design_system_component}} +- **Design System Component**: {{design_system_component}} +{{/if}} +- **Visual Style Name**: {{visual_style_name}} +- **Font weight**: {{font_weight}} (from {{line_thickness}} line markers in sketch) +- **Font size**: {{font_size}} (est. from {{line_spacing}} spacing between line pairs) +- **Line-height**: {{line_height}} (est. calculated from font size) +{{#if text_color}} +- **Color**: {{text_color}} +{{/if}} +{{#if text_transform}} +- **Transform**: {{text_transform}} +{{/if}} + +**Position**: {{position_description}} +**Alignment**: {{text_alignment}} + +{{#if behavior}} +**Behavior**: {{behavior_description}} +{{/if}} + +**Content**: +{{#each product_languages}} +- {{this}}: "{{content}}" +{{/each}} + +> **Sketch Analysis:** Values derived using `SKETCH-TEXT-ANALYSIS-GUIDE.md` methodology. Designer should review and confirm. +``` + {{#each additional_language}} + - {{lang_code}}: "{{content}}" + {{/each}} +``` + + +--- + +## TEXT GROUP ORGANIZATION + +**Is this text part of a GROUP?** + +Many pages have text groups that should be read together: +- Headline + Body + Link +- Label + Helper text +- Heading + Subheading + Description + +Grouping translations allows reading the entire section in one language. + +**Is this text part of a group?** + +1. **Yes** - Part of a text group +2. **No** - Standalone text element + +Choice [1/2]: + + + **What other text elements are in this group?** + + List them: + + Mark as text group for grouped translation output + + **Text group will be formatted as:** + + ```markdown + ### {{Group_Name}} + **Purpose**: {{group_purpose}} + + #### {{Element_1_Purpose}} + **OBJECT ID**: `{{object_id_1}}` + - **Component**: {{type_1}} + - **Content**: + - EN: "{{content_en_1}}" + - SE: "{{content_se_1}}" + + #### {{Element_2_Purpose}} + **OBJECT ID**: `{{object_id_2}}` + - **Component**: {{type_2}} + - **Content**: + - EN: "{{content_en_2}}" + - SE: "{{content_se_2}}" + + #### {{Element_3_Purpose}} + **OBJECT ID**: `{{object_id_3}}` + - **Component**: {{type_3}} + - **Content**: + - EN: "{{content_en_3}}" + - SE: "{{content_se_3}}" + ``` + + **Reading in English:** + {{content_en_1}} + {{content_en_2}} + {{content_en_3}} + + **Reading in Swedish:** + {{content_se_1}} + {{content_se_2}} + {{content_se_3}} + + Each language reads as a complete, coherent message! + + +--- + +## COMPLETE SPECIFICATION EXAMPLE (Dog Week Style) + +```markdown +### Hero Object +**Purpose**: Primary value proposition and main conversion action + +#### Primary Headline +**OBJECT ID**: `start-hero-headline` +- **Component**: H1 heading (`.text-heading-1`) +- **Position**: Center of hero section, above CTA +- **Style**: + - Font weight: Bold (from 3px thick line markers) + - Font size: 42px (est. from 24px spacing between line pairs) + - Line-height: 1.2 (est. calculated from font size) + - No italic, color: #1a1a1a +- **Behavior**: Updates with language toggle +- **Content**: + +> **Note:** Values marked `(est. from...)` show sketch analysis reasoning. Confirm or adjust, then update with actual values. + - EN: "Every walk. on time. Every time." + - SE: "Varje promenad. i tid. Varje gång." + +#### Supporting Text +**OBJECT ID**: `start-hero-supporting` +- **Component**: Body text (`.text-body`) +- **Position**: Below headline, above CTA button +- **Style**: + - Font weight: Regular (from 1px thin line markers) + - Font size: 16px (est. from 12px spacing between line pairs) + - Line-height: 1.5 (est. calculated from font size) +- **Behavior**: Updates with language toggle +- **Content**: + +> **Note:** Values marked `(est. from...)` show sketch analysis reasoning. Confirm or adjust, then update with actual values. + - EN: "Organize your family around dog care. Never miss a walk again." + - SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen." + +#### Primary CTA Button +**OBJECT ID**: `start-hero-cta` +- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md) +- **Position**: Center, below supporting text +- **Behavior**: Navigate to registration/sign-up +- **Content**: + - EN: "start planning - free forever" + - SE: "börja planera - gratis för alltid" +``` + +**Reading the Hero in English:** +> "Every walk. on time. Every time." +> "Organize your family around dog care. Never miss a walk again." +> [start planning - free forever] + +**Reading the Hero in Swedish:** +> "Varje promenad. i tid. Varje gång." +> "Organisera din familj kring hundvård. Missa aldrig en promenad igen." +> [börja planera - gratis för alltid] + +--- + +## KEY PRINCIPLES + +### 1. Purpose-Based Naming ✅ +**NOT:** `welcome-heading`, `description-paragraph` +**YES:** `hero-headline`, `feature-description` + +Names describe FUNCTION, not content. + +### 2. Separated Structure ✅ +- **Position/Style** specified separately +- **Content** grouped by language +- **Behavior** clearly stated + +### 3. Grouped Translations ✅ +Text groups keep languages together so each reads coherently. + +### 4. Professional Format ✅ +Follows Dog Week specification style for consistency across WDS projects. + +--- + +## BENEFITS + +✅ **Purpose-Driven** +- Object IDs reflect function +- Names remain valid if content changes +- Clear semantic meaning + +✅ **Translation-Friendly** +- Each language grouped together +- Easy to read entire section in one language +- Natural language flow preserved + +✅ **Maintainable** +- Content can change without renaming +- Structure remains stable +- Easy to locate by purpose + +✅ **Developer-Friendly** +- Clear what each text does +- Component references included +- Position clearly stated + +--- + +**Return to object-router after documentation complete** diff --git a/src/modules/wds/workflows/4-ux-design/object-types/image.md b/src/modules/wds/workflows/4-ux-design/object-types/image.md new file mode 100644 index 00000000..10b07eb0 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/object-types/image.md @@ -0,0 +1,155 @@ +# Object Type: Image + +**Goal:** Document image element with complete specification + +--- + +## IMAGE IDENTIFICATION + +**Documenting image: {{image_description}}** + +--- + +## OBJECT ID + +Generate Object ID: `{page}-{section}-{element}-image` + +Example: `landing-hero-illustration-image` + + +--- + +## DESIGN SYSTEM COMPONENT + +{{#if design_system_enabled}} +**Design System component:** + +1. **Use existing pattern** - From your Design System +2. **Create new pattern** - Add this image pattern to the Design System +3. **Page-specific only** - Not a reusable pattern + +Choice [1/2/3]: + + + **Which existing image pattern?** + + From your Design System: + {{list_available_image_patterns}} + + Component name: + + Store design_system_component + Store component_status = "existing" + + + + **New image pattern name:** + + Suggested: `Image-{{pattern_type}}` (e.g., Image-Hero, Image-Avatar, Image-Card) + + Component name: + + Store design_system_component + Store component_status = "new" + Mark for Design System addition in Phase 5 + + ✅ This image pattern will be added to your Design System in Phase 5. + + + + Store component_status = "page-specific" + +{{else}} +Store component_status = "page-specific" +{{/if}} + +--- + +## IMAGE PROPERTIES + +**Image properties:** + +**Source:** +- Image filename/path: +- Alt text (EN): +- Alt text (SV): +- Is decorative (no alt needed): yes/no + +**Dimensions:** +- Width: +- Height: +- Aspect ratio: +- Object-fit: (cover/contain/fill) + +**Responsive behavior:** +- Mobile size: +- Tablet size: +- Desktop size: +- Retina/2x version: yes/no + + +--- + +## IMAGE STATES + +**Image states:** + +**Loading:** +- Placeholder: (color/skeleton/blur) +- Lazy loading: yes/no + +**Error:** +- Fallback image: (if any) +- Error message display: yes/no + +**Loaded:** +- Fade-in animation: yes/no +- Animation duration: + + +--- + +## GENERATE SPECIFICATION + +```markdown +### {{image_name}} + +**Object ID:** `{{object_id}}` +**Type:** image + +**Source:** +- File: {{image_path}} +- Alt (EN): {{alt_text_en}} +- Alt (SV): {{alt_text_sv}} +{{#if is_decorative}} +- Decorative: role="presentation" +{{/if}} + +**Dimensions:** +- Width: {{width}} +- Height: {{height}} +- Aspect ratio: {{aspect_ratio}} +- Object-fit: {{object_fit}} + +**Responsive:** +- Mobile: {{mobile_size}} +- Tablet: {{tablet_size}} +- Desktop: {{desktop_size}} +{{#if has_retina}} +- Retina (@2x): {{retina_path}} +{{/if}} + +**Loading:** +- Placeholder: {{placeholder_type}} +- Lazy load: {{lazy_loading}} + +**States:** +- **Loading:** {{loading_state}} +- **Error:** {{error_fallback}} +- **Loaded:** {{loaded_animation}} +``` + +--- + +**Return to 4c-03** + diff --git a/src/modules/wds/workflows/4-ux-design/object-types/link.md b/src/modules/wds/workflows/4-ux-design/object-types/link.md new file mode 100644 index 00000000..7e5cf7a6 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/object-types/link.md @@ -0,0 +1,159 @@ +# Object Type: Link + +**Goal:** Document link/anchor element with complete specification + +--- + +## LINK IDENTIFICATION + +**Documenting link: {{link_description}}** + +--- + +## OBJECT ID + +Generate Object ID: `{page}-{section}-{element}-link` + +Example: `signin-form-forgot-link` + + +--- + +## LINK TYPE + +**What type of link?** + +1. **Internal** - Same app navigation +2. **External** - External website (opens new tab) +3. **Email** - mailto: link +4. **Phone** - tel: link +5. **Download** - File download + +Choice [1-5]: + +--- + +## DESIGN SYSTEM COMPONENT + +{{#if design_system_enabled}} +**Design System component:** + +1. **Use existing component** - From your component library +2. **Create new component** - Add this to the Design System +3. **Page-specific only** - Not a reusable component + +Choice [1/2/3]: + + + **Which existing component?** + + From your component library: + {{list_available_link_components}} + + Component name: + + Store design_system_component + Store component_status = "existing" + + + + **New component name:** + + Suggested: `Link-{{link_type}}` or `Link-{{style_variant}}` + + Component name: + + Store design_system_component + Store component_status = "new" + Mark for Design System addition in Phase 5 + + ✅ This link style will be added to your Design System in Phase 5. + + + + Store component_status = "page-specific" + +{{else}} +Store component_status = "page-specific" +{{/if}} + +--- + +## LINK CONTENT & TARGET + +**Link text in all languages:** + +{{#each language}} +- **{{language}}:** +{{/each}} + +**Target/Destination:** +- URL or route: +- Opens in: same tab / new tab + + +--- + +## LINK STATES & STYLING + +**Visual styling:** + +**Default:** +- Text color: +- Text decoration: (underline/none) +- Font weight: +- Icon: (if any) + +**Hover:** +- Text color: +- Text decoration: +- Cursor: + +**Active/Visited:** +- Text color: +- Show as visited: yes/no + +**Focus:** +- Outline color: +- Text decoration: + + +--- + +## GENERATE SPECIFICATION + +```markdown +### {{link_name}} + +**Object ID:** `{{object_id}}` +**Type:** {{link_type}} +**Destination:** {{target_url}} +**Opens:** {{same_or_new_tab}} + +**Content:** +{{#each language}} +- **{{language}}:** {{link_text}} +{{/each}} + +{{#if has_icon}} +**Icon:** {{icon_name}} ({{icon_position}}) +{{/if}} + +**States:** +- **Default:** {{default_color}}, {{default_decoration}} +- **Hover:** {{hover_color}}, {{hover_decoration}} +- **Active:** {{active_color}} +- **Focus:** Outline {{focus_outline}} + +**Interaction:** +- On click: Navigate to {{destination}} +{{#if opens_new_tab}} +- Opens in new tab +- Includes rel="noopener noreferrer" +{{/if}} +``` + +--- + +**Return to 4c-03** + diff --git a/src/modules/wds/workflows/4-ux-design/object-types/object-router.md b/src/modules/wds/workflows/4-ux-design/object-types/object-router.md new file mode 100644 index 00000000..6e306a91 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/object-types/object-router.md @@ -0,0 +1,331 @@ +# Object Type Router + +**Goal:** Intelligently analyze object, suggest interpretation, and route to appropriate specification instructions + +--- + +## STEP 1: TEXT ELEMENT DETECTION + +**Analyzing object from sketch...** + +Apply text detection rules from `TEXT-DETECTION-PRIORITY.md`: +- Look for horizontal line PAIRS (2 lines together = text marker) +- Single lines alone = decorative elements (dividers, borders) +- Count pairs to determine number of text lines + + + + **✓ TEXT ELEMENT DETECTED** + + I see horizontal line pairs in the sketch - this is text content. + + **Quick Detection:** + - **{{pair_count}} line pairs** → {{pair_count}} lines of text + - Routing to text analysis for detailed specification... + + + Route immediately to `object-types/heading-text.md` + Pass detected pairs to heading-text.md for analysis using SKETCH-TEXT-ANALYSIS-GUIDE.md + + **→ Loading text-specific instructions...** + + > **Reference:** Text detection rules in `TEXT-DETECTION-PRIORITY.md`, analysis methodology in `SKETCH-TEXT-ANALYSIS-GUIDE.md` + + +--- + +## STEP 2: OTHER OBJECT ANALYSIS + + + +Examine object characteristics: +- Visual appearance (shape, style, position) +- Context (what's around it, where in form/page) +- Interactive indicators (buttons, inputs, links) +- Container indicators (boxes, cards, modals) +- Media indicators (image placeholders, video frames) + + +**My interpretation:** + +**This looks like a {{suggested_object_type}}.** + +Based on what I see: +- {{observation_1}} +- {{observation_2}} +- {{observation_3}} + +{{#if is_text_element}} +**Text Analysis from Sketch:** +- **{{line_count}} lines of text** (horizontal bar groups) +- **Line thickness:** {{thickness}} → ~{{estimated_font_size}} font +- **Line spacing:** {{spacing}} → ~{{estimated_line_height}} line-height +- **Alignment:** {{detected_alignment}} +- **Content capacity:** ~{{total_chars}} characters ({{chars_per_line}} per line) +{{/if}} + +**I think this {{component_name}}:** +- {{suggested_purpose}} +- {{suggested_interaction}} +- {{suggested_result}} + +{{#if is_text_element}} +**Content should be:** {{content_guidance}} ({{line_count}} lines, ~{{total_chars}} characters) +{{/if}} + +**Does this match your intent?** + +1. **Yes** - That's correct +2. **Close** - Similar but let me clarify +3. **No** - It's actually something different + +Choice [1/2/3]: + +--- + +## HANDLE USER RESPONSE + + + ✅ Great! Proceeding with {{suggested_object_type}} documentation. + Store confirmed_object_type + Store confirmed_purpose + Route to appropriate object-type file + + + + **What should I adjust in my interpretation?** + + Please clarify: + + Listen to clarification + Adjust interpretation + + **Updated interpretation:** + + This {{adjusted_object_type}}: + - {{adjusted_purpose}} + + Correct now? + + Once confirmed, route to appropriate object-type file + + + + **What is this object?** + + Please describe what it is and what it does: + + Listen to user description + Determine correct object type + + **Got it!** This is a {{corrected_object_type}}. + + I'll document it accordingly. + + Route to appropriate object-type file + + +--- + +## STEP 3: ROUTE TO OBJECT-SPECIFIC INSTRUCTIONS + +Based on confirmed object type, load appropriate instruction file: + +**TEXT ELEMENTS (DETECTED FIRST):** +- Horizontal line groups → `object-types/heading-text.md` + - Handles: Headings (H1-H6), Paragraphs, Labels, Captions + - Includes: Sketch text analysis, character capacity, content guidance + +**INTERACTIVE ELEMENTS:** +- **Button shapes** → `object-types/button.md` +- **Input fields** → `object-types/text-input.md` +- **Textarea boxes** → `object-types/textarea.md` +- **Dropdown indicators** → `object-types/select-dropdown.md` +- **Checkbox squares** → `object-types/checkbox.md` +- **Radio circles** → `object-types/radio-button.md` +- **Toggle switches** → `object-types/toggle-switch.md` +- **Underlined text/arrows** → `object-types/link.md` + +**MEDIA ELEMENTS:** +- **Image placeholders (X or box)** → `object-types/image.md` +- **Video frame** → `object-types/video.md` + +**CONTAINER ELEMENTS:** +- **Card/box container** → `object-types/card.md` +- **Overlay/popup** → `object-types/modal-dialog.md` +- **Grid/rows** → `object-types/table.md` +- **Bullet/numbered items** → `object-types/list.md` + +**NAVIGATION ELEMENTS:** +- **Menu/tabs** → `object-types/navigation.md` + +**STATUS ELEMENTS:** +- **Small circle/pill** → `object-types/badge.md` +- **Banner/box with icon** → `object-types/alert-toast.md` +- **Bar/spinner** → `object-types/progress.md` + +**CUSTOM:** +- **Unique component** → `object-types/custom-component.md` + + + + +--- + +## AFTER OBJECT DOCUMENTATION + +After object-specific instructions complete, return here + +✅ **{{object_name}} documented!** + +**More objects in this section?** + +Looking at the sketch, I can see {{describe_remaining_objects}}. + +Should I analyze the next object? + +1. **Yes** - Continue with next object +2. **No** - Section complete + +Choice [1/2]: + + + Loop back to top for next object analysis + + + + ✅ Section complete! + Return to 4c-03 + + +--- + +## INTERPRETATION EXAMPLES + +**Example 1: Button** +``` +My interpretation: + +This looks like a PRIMARY BUTTON. + +Based on what I see: +- Prominent placement at bottom of form +- Bright blue background (primary color) +- White text saying "Save Profile" +- Located after all form fields + +I think this "Save Profile Button": +- Saves the form data to the database +- Updates the user's profile information +- Shows loading state during save +- Navigates to profile view on success + +Does this match your intent? +``` + +**Example 2: Text/Heading with Placeholder Lines** +``` +My interpretation: + +This looks like a HEADING (H2). + +Based on what I see: +- Located at top of section, center-aligned +- Group of 2 horizontal bars (text placeholders) +- Thick lines suggesting larger font +- Positioned above body content + +Text Analysis from Sketch: +- 2 lines of text (2 horizontal bar groups) +- Line thickness: 3px → ~28-32px font size +- Line spacing: 3px between lines → ~1.3 line-height +- Alignment: Center +- Content capacity: ~50-60 characters (25-30 per line) + +I think this "Section Heading": +- Introduces the content section +- Draws attention to key message +- Should be brief and impactful + +Content should be: Brief heading, 2 short lines (2 lines, ~50-60 characters) + +Does this match your intent? +``` + +**Example 3: Body Text with Multiple Lines** +``` +My interpretation: + +This looks like BODY TEXT / PARAGRAPH. + +Based on what I see: +- Below heading in main content area +- Group of 5 thin horizontal bars +- Left-aligned +- Comfortable spacing between lines + +Text Analysis from Sketch: +- 5 lines of text (5 horizontal bar groups) +- Line thickness: 1px → ~16px font size +- Line spacing: 3px between lines → ~1.5 line-height +- Alignment: Left +- Content capacity: ~300-350 characters (60-70 per line) + +I think this "Description Paragraph": +- Explains the feature or product +- Provides detailed information +- Engages the user + +Content should be: Full paragraph (5 lines, ~300-350 characters) + +Does this match your intent? +``` + +**Example 3: Link** +``` +My interpretation: + +This looks like a TEXT LINK. + +Based on what I see: +- Underlined text saying "Forgot password?" +- Positioned below password field +- Smaller, less prominent than submit button +- Typical recovery flow placement + +I think this "Forgot Password Link": +- Navigates to password reset flow +- Opens in same window +- For users who can't remember password +- Common authentication pattern + +Does this match your intent? +``` + +--- + +## KEY PRINCIPLES + +**✅ Agent demonstrates intelligence** +- Analyzes visual and contextual clues +- Makes informed suggestions +- Shows reasoning process + +**✅ Trust-the-agent approach** +- Agent interprets, user confirms +- Not procedural checkbox selection +- Collaborative intelligence + +**✅ Efficient workflow** +- Quick confirmation when correct +- Easy correction when needed +- Natural conversation flow + +**✅ Context-aware** +- Understands form flow +- Recognizes UI patterns +- Applies common sense + +--- + +**Return to 4c-03 after documentation complete** diff --git a/src/modules/wds/workflows/4-ux-design/object-types/text-input.md b/src/modules/wds/workflows/4-ux-design/object-types/text-input.md new file mode 100644 index 00000000..fd331603 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/object-types/text-input.md @@ -0,0 +1,423 @@ +# Object Type: Text Input + +**Goal:** Document text input field with complete specification + +--- + +## INPUT IDENTIFICATION + +**Documenting text input: {{input_description}}** + +--- + +## OBJECT ID + +Generate Object ID using format: +`{page}-{section}-{field}-input` + +Example: `signin-form-email-input` + + +**Object ID:** `{{generated_object_id}}` + +--- + +## INPUT TYPE + +**What type of text input is this?** + +1. **Text** - General text (name, title, etc.) +2. **Email** - Email address +3. **Password** - Password (masked) +4. **Tel** - Phone number +5. **URL** - Website address +6. **Search** - Search query +7. **Number** - Numeric input +8. **Date** - Date picker +9. **Textarea** - Multi-line text + +Choice [1-9]: + +Store input_type + +--- + +## DESIGN SYSTEM COMPONENT + +{{#if design_system_enabled}} +**Design System component:** + +1. **Use existing component** - From your component library +2. **Create new component** - Add this to the Design System +3. **Page-specific only** - Not a reusable component + +Choice [1/2/3]: + + + **Which existing component?** + + From your component library: + {{list_available_input_components}} + + Component name: + + Store design_system_component + Store component_status = "existing" + + + + **New component name:** + + Suggested: `Input-{{input_type}}` + + Component name: + + Store design_system_component + Store component_status = "new" + Mark for Design System addition in Phase 5 + + ✅ This input will be added to your Design System in Phase 5. + + + + Store component_status = "page-specific" + +{{else}} +Store component_status = "page-specific" +{{/if}} + +--- + +## INPUT CONTENT + +**Label text in all languages:** + +{{#each language}} +- **{{language}}:** +{{/each}} + + +Store label_text for each language + +**Placeholder text in all languages:** + +{{#each language}} +- **{{language}}:** +{{/each}} + + +Store placeholder_text for each language + +**Helper text** (optional guidance below field): + +{{#each language}} +- **{{language}}:** +{{/each}} + + +Store helper_text for each language + +--- + +## INPUT PROPERTIES + +**Input properties:** + +- Required field: yes/no +- Max length: (number or "none") +- Min length: (number or "none") +- Autocomplete: (on/off/specific type like "email") +- Autofocus: yes/no +- Readonly: yes/no + + +Store input_properties + +--- + +## INPUT STATES + +**Let's define all input states.** + +**For each state, describe the appearance:** + +**Default/Empty state:** +- Border color: +- Background: +- Placeholder visible: yes +- Label position: + +**Focus state:** +- Border color: +- Background: +- Label position: (stays/floats above) +- Outline/glow: + +**Filled state:** +- Border color: +- Background: +- Label position: + +**Error state:** +- Border color: +- Background: +- Error message position: (below/inline) +- Icon: (if any) + +**Disabled state:** +- Border color: +- Background: +- Text color: +- Cursor: +- Why disabled: + +**Success state** (if applicable): +- Border color: +- Icon: (checkmark, etc.) +- When shown: + + +Store state definitions for all states + +--- + +## VALIDATION RULES + +**Validation rules for this input:** + +**Required:** +- Is this field required: yes/no + +**Format validation:** +- Format rules: (e.g., "must be valid email", "must contain @") +- Pattern/regex: (if applicable) + +**Length validation:** +- Minimum length: +- Maximum length: + +**Custom rules:** +- Any custom validation: + +**Validation timing:** +- When to validate: on_blur / on_input / on_submit + + +Store validation_rules + +--- + +## ERROR MESSAGES + +**Error messages for validation failures:** + +{{#each validation_rule}} +**When {{rule_name}} fails:** + +Error code: (e.g., ERR_EMAIL_REQUIRED) + +{{#each language}} +- **{{language}}:** +{{/each}} +{{/each}} + + +Store error_messages with codes and translations + +--- + +## INPUT INTERACTION + +**Interaction behaviors:** + +**On focus:** +- What happens: + +**On input (while typing):** +- Real-time validation: yes/no +- Character counter: yes/no +- Auto-formatting: yes/no (e.g., phone numbers) +- Other behaviors: + +**On blur (loses focus):** +- Validation triggers: yes/no +- Save/update: yes/no +- Other behaviors: + + +Store interaction_behaviors + +--- + +## GENERATE INPUT SPECIFICATION + +Generate input specification using format: + +```markdown +### {{input_name}} + +**Object ID:** `{{object_id}}` +**Type:** {{input_type}} +{{#if design_system_enabled}} +**Design System Component:** {{design_system_component}} +**Figma Component:** {{figma_component_name}} +{{/if}} + +**Label:** +{{#each language}} +- **{{language}}:** {{label_text}} +{{/each}} + +**Placeholder:** +{{#each language}} +- **{{language}}:** {{placeholder_text}} +{{/each}} + +{{#if has_helper_text}} +**Helper Text:** +{{#each language}} +- **{{language}}:** {{helper_text}} +{{/each}} +{{/if}} + +**Properties:** +- Required: {{is_required}} +- Max length: {{max_length}} +- Min length: {{min_length}} +- Autocomplete: {{autocomplete}} +- Autofocus: {{autofocus}} + +**States:** + +*Default:* +- Border: {{default_border}} +- Background: {{default_bg}} +- Label: {{label_position}} + +*Focus:* +- Border: {{focus_border}} +- Label: {{focus_label_position}} +- Outline: {{focus_outline}} + +*Filled:* +- Border: {{filled_border}} +- Label: {{filled_label_position}} + +*Error:* +- Border: {{error_border}} +- Icon: {{error_icon}} +- Message: Below field + +*Disabled:* +- Border: {{disabled_border}} +- Background: {{disabled_bg}} +- Cursor: not-allowed + +**Validation:** +{{#each validation_rule}} +- {{rule_description}} +{{/each}} + +**Error Messages:** +{{#each error}} +- **{{error_code}}:** {{error_messages}} +{{/each}} + +**Interactions:** +- **On Focus:** {{focus_behavior}} +- **On Input:** {{input_behavior}} +- **On Blur:** {{blur_behavior}} +``` + + +✅ **Input field documented!** + +Specification added to page document. + +--- + +## EXAMPLE OUTPUT + +```markdown +### Email Input Field + +**Object ID:** `signin-form-email-input` +**Type:** email +**Design System Component:** text-input +**Figma Component:** Input/Text/Medium + +**Label:** +- **English:** Email Address +- **Swedish:** E-postadress + +**Placeholder:** +- **English:** your@email.com +- **Swedish:** din@epost.com + +**Helper Text:** +- **English:** We'll never share your email +- **Swedish:** Vi delar aldrig din e-post + +**Properties:** +- Required: yes +- Max length: 254 +- Min length: 5 +- Autocomplete: email +- Autofocus: yes + +**States:** + +*Default:* +- Border: 1px solid #CCCCCC +- Background: #FFFFFF +- Label: Inside field (placeholder position) + +*Focus:* +- Border: 2px solid #0066CC (primary) +- Label: Floats above field +- Outline: 0 0 0 3px rgba(0,102,204,0.1) + +*Filled:* +- Border: 1px solid #666666 +- Label: Remains above field + +*Error:* +- Border: 2px solid #DC2626 (red) +- Icon: ⚠️ (warning icon, right side) +- Message: Below field in red + +*Disabled:* +- Border: 1px solid #E5E5E5 +- Background: #F5F5F5 +- Cursor: not-allowed +- Text: #999999 + +**Validation:** +- Required field (cannot be empty) +- Must contain @ symbol +- Must have valid domain +- Must match email format pattern + +**Error Messages:** +- **ERR_EMAIL_REQUIRED:** + - EN: "Email address is required" + - SV: "E-postadress krävs" + +- **ERR_EMAIL_INVALID:** + - EN: "Please enter a valid email address" + - SV: "Ange en giltig e-postadress" + +- **ERR_EMAIL_DOMAIN:** + - EN: "Email domain appears invalid" + - SV: "E-postdomän verkar ogiltig" + +**Interactions:** +- **On Focus:** Border changes to primary color, label floats up with animation (200ms ease-out) +- **On Input:** Real-time validation (debounced 300ms), @ symbol triggers domain validation +- **On Blur:** Full validation runs, error message displays if invalid, save to form state +``` + +--- + +**Return to 4c-03 to continue with next object** + diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-01-init.md b/src/modules/wds/workflows/4-ux-design/steps/step-01-init.md new file mode 100644 index 00000000..3d5d68ce --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/steps/step-01-init.md @@ -0,0 +1,76 @@ +# Step 1: Workflow Initialization + +**Progress: Step 1 of 5** - Next: Scenario Definition + +## YOUR TASK + +Initialize the UX Design workflow by welcoming the user and understanding what they want to design. + +--- + +## GOAL + +Set up the design session and determine what scenario or page the user wants to work on. + +--- + +## EXECUTION + +Hi {user_name}! I'm Baldr, 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? 🎨 + +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]: + +--- + +## MENU HANDLING + +### Choice 1: New Scenario +- Proceed to Step 2 (Scenario Definition) +- Load `steps/step-02-define-scenario.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-define-scenario.md` to begin scenario definition. + +If user selects [2], determine current state and load appropriate step. + +If user selects [3], show structure and return to this step. + diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-02-define-scenario.md b/src/modules/wds/workflows/4-ux-design/steps/step-02-define-scenario.md new file mode 100644 index 00000000..05617318 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/steps/step-02-define-scenario.md @@ -0,0 +1,88 @@ +# Step 2: Define Scenario and Pages + +**Progress: Step 2 of 5** - Next: Page Design + +## YOUR TASK + +Work with the user to define the scenario (user journey) and identify all pages within it. + +--- + +## GOAL + +Create clear scenario structure with numbered pages ready for design. + +--- + +## EXECUTION + +**Let's define your scenario.** + +A scenario is a cohesive user journey containing multiple related pages. + +**What scenario are we designing?** + +Examples: +- "User Onboarding" (sign up through profile setup) +- "Booking Flow" (search through confirmation) +- "Dashboard Experience" (home screen with navigation) + +Scenario name: + +Store scenario_name +Determine scenario number (count existing scenarios, add 1) +Generate scenario folder: {output_folder}/C-Scenarios/{nn}-{scenario-name}/ + +**What pages are in this scenario?** + +List the main screens/pages in order. + +Example: +1. Start Page +2. Sign Up +3. Profile Setup +4. Welcome Dashboard + +Store pages list +Create folder structure for each page: + - {nn}.1-{page-name}/ + - {nn}.2-{page-name}/ + - etc. + + +✅ **Scenario structure created:** + +`C-Scenarios/{nn}-{scenario-name}/` +{{#each page}} + - `{nn}.{n}-{page-name}/` +{{/each}} + +We'll design each page using the 4A-4E process: +- **4A: Exploration** (optional - think through concept) +- **4B: Sketch Analysis** (analyze your sketches) +- **4C: Specification** (document everything systematically) +- **4D: Prototype** (create interactive HTML) +- **4E: PRD Update** (extract functional requirements) + +Ready to design the first page? 🎨 + +--- + +## MENU + +[C] Continue to Step 3 (Page Design) + +--- + +## STATE MANAGEMENT + +Before proceeding: +- Save scenario structure to `C-Scenarios/{nn}-{scenario-name}/scenario-info.yaml` +- Include: scenario_name, scenario_number, pages_list, current_page_index (0) + +--- + +## NEXT STEP + +When user selects [C], load `steps/step-03-design-page.md` to begin designing the first page. + diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-03-design-page.md b/src/modules/wds/workflows/4-ux-design/steps/step-03-design-page.md new file mode 100644 index 00000000..84386bc7 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/steps/step-03-design-page.md @@ -0,0 +1,186 @@ +# 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 + +Load scenario-info.yaml to determine current page +Display: "Designing page {nn}.{current}: {page-name}" + +--- + +## THE 4A-4E DESIGN PROCESS + +Execute substeps in sequence for this page: + +### Substep 4A: Exploration (Optional) + +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]: + + + Load and execute `substeps/4a-exploration.md` + When 4A complete, return here and continue to 4B + + + + Continue to Substep 4B + + +--- + +### Substep 4B: Sketch Analysis + +Do you have sketches to analyze? + +1. **Yes** - I have sketches ready +2. **Skip** - Go directly to specification + +Choice [1/2]: + + + Load and execute `substeps/4b-sketch-analysis.md` + When 4B complete, return here and continue to 4C + + + + Continue to Substep 4C + + +--- + +### Substep 4C: Specification (Required) + +**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. + +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` + + +When all 4C substeps complete, return here and continue to 4D + +--- + +### Substep 4D: HTML Prototype + +Create HTML prototype? + +1. **Yes** - Make it interactive +2. **Skip** - Move to PRD update + +Choice [1/2]: + + + Load and execute `substeps/4d-prototype.md` + When 4D complete, return here and continue to 4E + + + + Continue to Substep 4E + + +--- + +### Substep 4E: PRD Update (Required) + +**Let's capture the requirements this page revealed.** 📋 + +Load and execute `substeps/4e-prd-update.md` +When 4E complete, return here + +--- + +## PAGE COMPLETE + +**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!** ✨ + +--- + +## NEXT PAGE DECISION + +Increment current_page_index in scenario-info.yaml +Check if more pages remain in scenario + + + **Next page: {next_page_name}** + + [C] Continue to next page + [P] Pause - Save and continue later + + Choice [C/P]: + + + Loop back to top of Step 3 with new page + + + + Progress saved! Resume anytime. 👍 + Exit workflow + + + + + Proceed to Step 4 (Complete Scenario) + Load `steps/step-04-complete-scenario.md` + + +--- + +## 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` + diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-04-complete-scenario.md b/src/modules/wds/workflows/4-ux-design/steps/step-04-complete-scenario.md new file mode 100644 index 00000000..7ae541d1 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/steps/step-04-complete-scenario.md @@ -0,0 +1,58 @@ +# 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 + +Load scenario-info.yaml to get final statistics + +✅ **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!** 🎨 + +--- + +## MENU + +What's next? + +[C] Continue to Step 5 (Next Steps) + +Choice [C]: + +--- + +## NEXT STEP + +When user selects [C], load `steps/step-05-next-steps.md` for workflow completion. + diff --git a/src/modules/wds/workflows/4-ux-design/steps/step-05-next-steps.md b/src/modules/wds/workflows/4-ux-design/steps/step-05-next-steps.md new file mode 100644 index 00000000..760191a0 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/steps/step-05-next-steps.md @@ -0,0 +1,72 @@ +# 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 + +**Great design session, {user_name}!** 🎨 + +Your specifications are saved and ready. What would you like to do next? + +--- + +## MENU + +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]: + +--- + +## MENU HANDLING + +### Choice 1: Design Another Scenario +Return to Step 2 (Define Scenario) +Load `steps/step-02-define-scenario.md` + +### Choice 2: Phase 5 (Design System) +To start Phase 5, activate Baldr again and run the Design System workflow. +Exit this workflow + +### Choice 3: Phase 6 (PRD Finalization) +To start Phase 6, activate Freyja (PM) and run the PRD Finalization workflow. +Exit this workflow + +### Choice 4: Review Progress +List all scenarios in C-Scenarios/ +Show completion status for each +Count total pages designed +Show PRD requirement count +Return to menu? [Y] +If Y, return to menu in this step + +### Choice 5: Exit +Perfect! All your work is saved. Resume anytime by running the UX Design workflow again. + +See you next time! 🎨✨ +Exit workflow + +--- + +## WORKFLOW COMPLETE + +This is the final step. User either loops to another scenario or exits. + diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4a-exploration.md b/src/modules/wds/workflows/4-ux-design/substeps/4a-exploration.md new file mode 100644 index 00000000..9154299f --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/substeps/4a-exploration.md @@ -0,0 +1,100 @@ +# Step 4A: Scenario Exploration + +This step is OPTIONAL - only use if user needs conceptual help before sketching + +Help user think through the concept, flow, and solution before sketching begins + +## When to Use This Step + +Use 4A when: +- User has no existing sketches +- User is unsure how to approach a feature +- User wants to explore the concept together + +Skip 4A when: +- User has sketches ready +- User knows exactly what they want + +--- + +## Exploration Process + +**Let's explore this concept together before sketching.** + +I'll help you think through: +- What the user is trying to accomplish +- What content and features they need +- How psychological triggers from your Trigger Map apply +- What the interaction flow should be + +**What is the user trying to accomplish on this page?** + +What's their goal? What brought them here? + +Listen and reflect back the core user goal + +**What do they need to see or do to accomplish that?** + +Think about: +- Information they need +- Actions they can take +- Choices they need to make + +Help structure the page elements + +**Let's check your Trigger Map - what drives this user?** + +Looking at your personas and driving forces: +- What positive goals does this page support? +- What negative outcomes does it help them avoid? + +Reference Trigger Map from B-Trigger-Map/ if available +Connect design choices to user psychology + +**How does the interaction flow?** + +Walk me through: +1. User arrives (from where?) +2. User sees... (what catches attention?) +3. User does... (main actions?) +4. User goes... (where next?) + +Sketch out the interaction flow verbally + +**Great! Here's what we've explored:** + +**User Goal:** {{user_goal}} + +**Key Elements:** +{{key_elements_list}} + +**Psychological Triggers:** +{{trigger_connections}} + +**Flow:** +{{interaction_flow}} + +You're ready to sketch! Would you like to: +1. **Create sketches** - Use your preferred tool, then come back for analysis (4B) +2. **Skip sketching** - Go directly to specification (4C) +3. **Explore more** - Refine the concept further + + + Perfect! Sketch your concept and come back when ready. I'll be here to analyze it (Step 4B). 🎨 + Save exploration notes to page folder as "exploration-notes.md" + Pause workflow - user will return to Step 4B + + + + Proceed directly to Step 4C (specification) + + + + Ask what aspect to explore more deeply + Continue exploration dialog + + +--- + +**Next:** Step 4B (Sketch Analysis) or Step 4C (Specification) + diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4b-sketch-analysis.md b/src/modules/wds/workflows/4-ux-design/substeps/4b-sketch-analysis.md new file mode 100644 index 00000000..39f158d8 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/substeps/4b-sketch-analysis.md @@ -0,0 +1,479 @@ +# Step 4B: Sketch Analysis (AI-Interprets, User-Confirms) + +**Goal:** AI reads entire sketch, identifies sections, interprets function/purpose, user confirms before detailed specification. + +--- + +## WORKFLOW APPROACH + +**Balance: AI Enhancement + User Control** + +1. **AI Reads Entire Sketch** → Identifies all sections holistically +2. **Designer Confirms Structure** → Validates section breakdown +3. **Section-by-Section AI Interpretation** → AI reads each section, interprets objects, function, purpose +4. **User Refinement Dialog** → Designer adds specifics, confirms/adjusts +5. **Batch Generation** → AI generates complete section spec with all translations + +--- + +## STEP 1: HOLISTIC SKETCH READING + +**Let me read your entire sketch and identify the main sections...** + +Please share your sketch: + +- Describe it to me +- Paste/upload an image +- Reference filename in Sketches/ folder + +Your sketch: + +Analyze entire sketch holistically: +1. Identify logical sections (header, hero, features, cards, footer, etc.) +2. Determine section boundaries (whitespace, visual grouping, layout) +3. Recognize section purposes from visual context +4. Count objects/elements in each section +5. Check if sections look like components from previous pages + + +**📊 I've analyzed your sketch. Here's what I see:** + +**{{page_name}}** contains **{{section_count}} main sections:** + +{{#each identified_sections}} +--- +**Section {{index}}: {{section_name}}** ({{location}}) +- **Purpose:** {{interpreted_purpose}} +- **Contains:** {{object_count}} objects/elements +- **Layout:** {{layout_description}} +{{#if looks_like_previous_component}} +- 💡 **Component?** Similar to {{component_name}} from {{previous_page}} +{{/if}} +{{/each}} +--- + +This is my interpretation of the structure. Does this look right? + +Section structure: + +1. **Confirm** - Yes, this is correct! +2. **Adjust** - I need to refine the section breakdown +3. **Add sections** - I see more sections +4. **Remove/merge sections** - Some sections should be combined + +Choice [1/2/3/4]: + + + **How should I adjust the sections?** + +Current breakdown: +{{#each identified_sections}} +{{index}}. {{section_name}} - {{interpreted_purpose}} +{{/each}} + +Your changes: + + Update section structure based on feedback + **Updated structure:** + + {{#each updated_sections}} + {{index}}. {{section_name}} - {{interpreted_purpose}} + {{/each}} + + Does this look better? + + Loop until user confirms structure + + +--- + +## STEP 2: COMPONENT IDENTIFICATION + + + **🔄 I noticed some sections might be reusable components:** + + {{#each potential_components}} + - **{{section_name}}** looks similar to **{{component_name}}** from {{previous_page}} + {{/each}} + + + Should these be components (reusable across pages)? + +1. **Yes, make them components** - Define once, reference later +2. **No, keep them as page-specific** - Each page has unique version +3. **Let me decide section-by-section** - I'll choose as we go + +Choice [1/2/3]: + + Mark sections as components or page-specific based on user choice + + +--- + +## STEP 3: SECTION-BY-SECTION AI INTERPRETATION + +**Perfect! Now I'll analyze each section in detail, one at a time.** + +I'll interpret the objects, functions, and content for each section. You can confirm or refine my interpretation before I generate the spec. + +--- + +**📍 Section {{current_index}}/{{total_sections}}: {{section_name}}** + +### 3A: AI Reads & Interprets Section + +For current section: +1. Identify all objects (top-left to bottom-right within section) +2. Determine object types (button, text, input, image, etc.) +3. Interpret object functions (what does it do?) +4. Interpret object purposes (why is it here?) +5. Detect text (actual text vs. markers) +6. Analyze visual hierarchy +7. Suggest Object IDs based on purpose + + +**My interpretation of "{{section_name}}":** + +**Section Purpose:** {{interpreted_section_purpose}} + +**Objects I see:** + +{{#each interpreted_objects}} +{{object_index}}. **{{interpreted_type}}** ({{position_description}}) + - **Object ID:** `{{suggested_object_id}}` + - **Function:** {{interpreted_function}} + - **Purpose:** {{interpreted_purpose}} + {{#if has_actual_text}} + - **Text in sketch:** "{{extracted_text}}" + {{/if}} + {{#if has_line_markers}} + - **Text capacity:** ~{{estimated_chars}} characters ({{line_count}} lines) + {{/if}} + {{#if is_interactive}} + - **Behavior:** {{interpreted_behavior}} + {{/if}} +{{/each}} + +**Overall Function:** {{section_function_summary}} + +### 3B: User Refinement Dialog + +**Does this interpretation look right?** + +1. **Yes, looks good!** - Move to content/translations +2. **Adjust interpretations** - I need to correct some things +3. **Add missing objects** - You missed something +4. **Remove objects** - Something isn't an object + +Choice [1/2/3/4]: + + + **Which interpretations need adjustment?** + + {{#each interpreted_objects}} + {{object_index}}. {{interpreted_type}} - {{interpreted_function}} + {{/each}} + + Your corrections: + + Update interpretations based on user feedback + + + + **What did I miss?** + + Describe the missing object(s): + + Add missed objects to interpretation + + + + **Which objects should I remove?** + + {{#each interpreted_objects}} + {{object_index}}. {{interpreted_type}} + {{/each}} + + Remove numbers: + + Remove specified objects + + +Re-display updated interpretation for confirmation +Loop until user confirms: "Yes, looks good!" + +--- + +## STEP 4: CONTENT & TRANSLATION GATHERING + +**Great! Now let's gather the content for all text elements in this section.** + +I'll suggest translations for everything at once. + +{{#each text_objects}} +--- +**{{object_purpose}}** (`{{object_id}}`) + +{{#if has_actual_text}} +I found text in your sketch: "{{extracted_text}}" + +Let me suggest translations... + +Generate translations for all product_languages + +**Suggested content:** + +{{#each product_languages}} +{{this}}: {{suggested_translation}} +{{/each}} + + +For "{{object_purpose}}": + +1. **Use these translations** +2. **Adjust translations** +3. **Manual input** + +Choice [1/2/3]: + +{{else}} +**Content for "{{object_purpose}}":** + +{{primary_language}}: + +After receiving primary language, suggest other languages + +**Translation suggestions:** + +{{#each remaining_languages}} +{{this}}: {{suggested_translation}} +{{/each}} + +Use these? [1] Yes [2] Adjust [3] Manual + +{{/if}} + +Store confirmed content for this object +--- +{{/each}} + +--- + +## STEP 5: BATCH SPECIFICATION GENERATION + +**Perfect! I have everything I need for "{{section_name}}".** + +Let me generate the complete section specification... + +Generate section spec: +1. Section header with purpose +2. All objects with full details +3. All translations grouped by object +4. Component references if applicable +5. Interactions and behaviors +6. States if applicable +7. Validation rules if applicable + + +**✅ Section "{{section_name}}" specification generated!** + +```markdown +### {{Section_Name}} +**Purpose**: {{section_purpose}} + +{{#each objects}} +#### {{Object_Purpose_Title}} +**OBJECT ID**: `{{object_id}}` +- **Component**: {{component_type}} +- **Position**: {{position}} +- **Style**: {{style_specs}} +{{#if has_behavior}} +- **Behavior**: {{behavior}} +{{/if}} +{{#if is_text}} +- **Content**: + {{#each product_languages}} + - {{this}}: "{{content}}" + {{/each}} +{{/if}} +{{#if has_states}} +- **States**: {{states}} +{{/if}} + +{{/each}} +``` + +**Next:** {{#if more_sections}}Section {{next_index}}: {{next_section_name}}{{else}}Complete page!{{/if}} + + + Move to next section + Repeat STEP 3 for next section + + + + **🎉 All sections complete!** + + Your page specification includes: + - {{total_sections}} sections + - {{total_objects}} objects + - {{total_text_elements}} text elements with {{language_count}} languages + - {{component_count}} reusable components identified + + Ready to generate prototype! + + Proceed to 4C-08 (Generate Final Spec) + + +--- + +## KEY PRINCIPLES + +### ✅ AI Enhancement + +- **Reads entire sketch** holistically +- **Identifies sections** automatically +- **Interprets function & purpose** from context +- **Suggests translations** proactively +- **Batch generates** complete specs + +### ✅ User Control + +- **Confirms structure** before detailed work +- **Refines interpretations** through dialog +- **Reviews translations** before acceptance +- **Stays in the loop** at key decision points +- **Can adjust** at any step + +### ✅ Efficient Workflow + +- **Section-by-section** keeps focus manageable +- **AI does heavy lifting** (interpretation, translation) +- **User does validation** (confirm, adjust, approve) +- **Batch generation** produces complete specs +- **Faster than pure manual** while maintaining quality + +--- + +## EXAMPLE: Dog Week Start Page + +### Step 1: Holistic Reading + +**AI:** +``` +I've analyzed your sketch. Here's what I see: + +Start Page contains 5 main sections: + +1. Header (Top) + - Purpose: Navigation and user access + - Contains: 3 objects (logo, sign-in button, language selector) + - Layout: Horizontal bar, logo left, buttons right + +2. Hero (Center) + - Purpose: Primary value proposition and CTA + - Contains: 3 objects (headline, supporting text, CTA button) + - Layout: Centered, vertical stack + - 💡 Component? Similar to Hero from other landing pages + +3. Illustration (Center) + - Purpose: Visual storytelling + - Contains: 1 object (hero image) + - Layout: Full-width image + +4. Message (Below illustration) + - Purpose: Supporting messaging + - Contains: 2 objects (preheader, secondary headline) + - Layout: Centered text + +5. Feature Cards (Bottom) + - Purpose: Key benefits showcase + - Contains: 9 objects (3 cards × 3 elements each) + - Layout: 3-column grid + +Does this structure look right? +``` + +**User:** `1` (Confirms) + +### Step 2: Section 1 - Header + +**AI interprets:** +``` +My interpretation of "Header": + +Section Purpose: Primary navigation and user access + +Objects I see: + +1. Image/Logo (Top-left) + - Object ID: `start-header-logo` + - Function: Brand identity, links to home + - Purpose: Establish brand presence + +2. Button (Top-right, before language) + - Object ID: `start-header-signin` + - Function: Navigate to sign-in page + - Purpose: User authentication access + - Text in sketch: "Sign in" + +3. Dropdown (Top-right, far right) + - Object ID: `start-header-language` + - Function: Toggle language + - Purpose: Language selection + - Text in sketch: "SE ▼" + +Overall Function: Provide navigation and access to core functionality + +Does this interpretation look right? +``` + +**User:** `1` (Confirms) + +**AI suggests content:** +``` +Content for "Sign In Button": + +I found text in your sketch: "Sign in" + +Suggested translations: +EN: Sign in +SE: Logga in + +Use these? [1] Yes [2] Adjust [3] Manual +``` + +**User:** `1` (Accepts) + +**AI generates:** +```markdown +### Header Object +**Purpose**: Navigation and user access with language selection + +#### Dog Week Logo +**OBJECT ID**: `start-header-logo` +- **Component**: [Logo Component](/docs/D-Design-System/.../Logo.md) +- **Position**: Left-aligned +- **Behavior**: Links to home page + +#### Sign In Button +**OBJECT ID**: `start-header-signin` +- **Component**: [Button Secondary](/docs/D-Design-System/.../Button-Secondary.md) +- **Position**: Right side (before language selector) +- **Behavior**: Navigate to sign-in page +- **Content**: + - EN: "Sign in" + - SE: "Logga in" + +#### Language Selector +**OBJECT ID**: `start-header-language` +- **Component**: [Language Selector](/docs/D-Design-System/.../LanguageSelector.md) +- **Position**: Right side (after sign-in button) +- **Behavior**: onChange → toggle language +- **Content**: Globe icon + language code dropdown +``` + +**Next: Section 2 - Hero** 🎯 + +--- + +**This workflow balances AI power with designer control perfectly!** 🎨🤖✨ diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-01-page-basics.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-01-page-basics.md new file mode 100644 index 00000000..bceb4f19 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-01-page-basics.md @@ -0,0 +1,59 @@ +# Substep 4C-01: Page Basics + +**Goal:** Capture fundamental page information + +--- + +## EXECUTION + +**Let's start with the page basics.** 📝 + +**Page basics:** + +- Page name/title: +- URL/route (if applicable): +- Main user goal (in one sentence): +- Where users come from (entry points): +- Where users go next (exit points): + +Store page_basics: + - page_title + - url_route + - user_goal + - entry_points + - exit_points + + +✅ **Page basics captured!** + +**Next:** We'll define the layout sections. + +--- + +## MENU + +[C] Continue to 4C-02 (Layout Sections) + +--- + +## EXAMPLE OUTPUT + +```yaml +page_basics: + title: "Sign In" + route: "/auth/signin" + user_goal: "Authenticate to access their account" + entry_points: + - "Landing page 'Sign In' button" + - "Protected route redirects" + exit_points: + - "Dashboard (success)" + - "Password reset (forgot password)" +``` + +--- + +## NEXT STEP + +Load `substeps/4c-02-layout-sections.md` + diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-02-layout-sections.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-02-layout-sections.md new file mode 100644 index 00000000..d39a65af --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-02-layout-sections.md @@ -0,0 +1,65 @@ +# Substep 4C-02: Layout Sections + +**Goal:** Define high-level page structure and sections + +--- + +## EXECUTION + +**Now let's define the layout sections.** + +Think about the major areas of the page (header, main content, sidebar, footer, etc.) + +**What are the main sections of this page?** + +Describe each major section and its purpose. + +Example: +- Header: Logo, navigation, user menu +- Hero: Welcome message and primary CTA +- Main Content: Sign-up form +- Footer: Links and legal info + +For each section: + - Store section_name + - Store section_purpose + - Store section_priority (primary/secondary) + + +✅ **Layout sections defined!** + +**Sections identified:** {{section_count}} + +**Next:** We'll identify all interactive components. + +--- + +## MENU + +[C] Continue to 4C-03 (Components & Object IDs) + +--- + +## EXAMPLE OUTPUT + +```yaml +layout_sections: + - name: "Header" + purpose: "Navigation and branding" + priority: "secondary" + + - name: "Sign In Form" + purpose: "User authentication" + priority: "primary" + + - name: "Footer" + purpose: "Legal links and support" + priority: "secondary" +``` + +--- + +## NEXT STEP + +Load `substeps/4c-03-components-objects.md` + diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-03-components-objects.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-03-components-objects.md new file mode 100644 index 00000000..19045a9b --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-03-components-objects.md @@ -0,0 +1,152 @@ +# Substep 4C-03: Components & Object IDs + +**Goal:** Identify all interactive elements, route to object-specific instructions, and assign Object IDs + +--- + +## EXECUTION + +**Let's identify and document every component systematically.** + +We'll work through each section, going **top-to-bottom, left-to-right** within each section, documenting each object using specialized instructions. + +--- + +## FOR EACH SECTION + +For each section identified in 4C-02: + +**Section: {{section_name}}** + +Starting from top-left corner of this section... + +## FOR EACH OBJECT IN SECTION + +Loop through objects in section (top-to-bottom, left-to-right): + + **Next object in {{section_name}}:** + + What is the first/next object in this section (from top-left)? + + Describe what you see: + + Store object_description + + ### ROUTE TO OBJECT-TYPE INSTRUCTIONS + + Load and execute `object-types/object-router.md` + + Object-router will: + 1. Ask user to identify object type + 2. Load appropriate object-type instruction file + 3. Guide through complete object documentation + 4. Generate specification with Object ID + 5. Return here when complete + + + **More objects in {{section_name}}?** + + 1. **Yes** - Document next object (move right, then down) + 2. **No** - Section complete + + Choice [1/2]: + + + Loop back to document next object in section + + + + ✅ **Section {{section_name}} complete!** + Move to next section + + + + + + +--- + +## ALL SECTIONS COMPLETE + +✅ **All components identified and documented!** + +**Summary:** +- **Sections processed:** {{section_count}} +- **Total components:** {{component_count}} +- **Components by type:** + {{#each component_type}} + - {{type_name}}: {{count}} + {{/each}} + +**Object IDs assigned:** +{{#each component}} +- `{{object_id}}` ({{component_type}}) +{{/each}} + +**Next:** We'll specify the content and languages. + +--- + +## MENU + +[C] Continue to 4C-04 (Content & Languages) + +--- + +## WORKFLOW NOTES + +**This substep uses object-type routing:** + +1. For each object, user identifies the type +2. System loads specialized instruction file (button.md, text-input.md, etc.) +3. Each instruction file has: + - Precise questions for that object type + - Complete example outputs + - Consistent format across all WDS projects +4. After documentation, control returns here +5. Continue until all objects in all sections are documented + +**Benefits:** +- ✅ Consistent specifications across all WDS projects +- ✅ Agents have clear, focused instructions for each object type +- ✅ Example-driven (show, don't tell) +- ✅ Systematic coverage (nothing missed) +- ✅ Reusable patterns across repositories + +--- + +## EXAMPLE COMPONENT REGISTRY + +```yaml +sections_processed: + - signin-form: + components: + - object_id: "signin-form-email-input" + type: "text-input" + documented_via: "object-types/text-input.md" + + - object_id: "signin-form-password-input" + type: "text-input" + documented_via: "object-types/text-input.md" + + - object_id: "signin-form-submit-button" + type: "button" + documented_via: "object-types/button.md" + + - object_id: "signin-form-forgot-link" + type: "link" + documented_via: "object-types/link.md" + +total_components: 4 +component_types: + text-input: 2 + button: 1 + link: 1 +``` + +--- + +## NEXT STEP + +Load `substeps/4c-04-content-languages.md` + diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-04-content-languages.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-04-content-languages.md new file mode 100644 index 00000000..53fecde2 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-04-content-languages.md @@ -0,0 +1,83 @@ +# Substep 4C-04: Content & Languages + +**Goal:** Specify all text content in all supported languages + +--- + +## EXECUTION + +**What languages does this page support?** + +List all languages (e.g., English, Swedish, Spanish): + +Store supported_languages array + +**Now let's specify all text content.** + +We'll go through each text element and provide content in all {{language_count}} languages. + +For each text element (labels, buttons, headings, messages): + **{{element_name}}:** + + {{#each language}} + - {{language}}: + {{/each}} + + + Store multilingual content for element + + +✅ **Content specified in all languages!** + +**Languages:** {{languages_list}} +**Text elements:** {{text_element_count}} + +**Next:** We'll define interactions and behaviors. + +--- + +## MENU + +[C] Continue to 4C-05 (Interactions) + +--- + +## EXAMPLE OUTPUT + +```yaml +supported_languages: + - English + - Swedish + +content: + page_title: + en: "Sign In" + sv: "Logga In" + + email_label: + en: "Email Address" + sv: "E-postadress" + + email_placeholder: + en: "your@email.com" + sv: "din@epost.com" + + password_label: + en: "Password" + sv: "Lösenord" + + submit_button: + en: "Sign In" + sv: "Logga In" + + forgot_password_link: + en: "Forgot password?" + sv: "Glömt lösenord?" +``` + +--- + +## NEXT STEP + +Load `substeps/4c-05-interactions.md` + diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-05-interactions.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-05-interactions.md new file mode 100644 index 00000000..414bb3e6 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-05-interactions.md @@ -0,0 +1,83 @@ +# Substep 4C-05: Interactions + +**Goal:** Define what happens when users interact with each component + +--- + +## EXECUTION + +**Let's define all interactions.** + +For each interactive element, we'll specify what happens when users interact with it. + +For each component with Object ID: + **{{object_id}}** ({{element_type}}) + + What happens when the user interacts with this? + + - On click / on input / on focus? + - What's the immediate response? + - What state changes occur? + - Where does it navigate (if applicable)? + - What data is sent/received? + + + Store interaction_behavior for component + + +✅ **Interactions defined!** + +**Components with behaviors:** {{interactive_count}} + +**Next:** We'll define all possible states. + +--- + +## MENU + +[C] Continue to 4C-06 (States) + +--- + +## EXAMPLE OUTPUT + +```yaml +interactions: + signin-form-email-input: + on_focus: + - "Highlight border (primary color)" + - "Show label above field" + on_input: + - "Real-time validation (email format)" + - "Clear error state if valid" + on_blur: + - "Validate complete email" + - "Show error if invalid" + + signin-form-password-input: + on_focus: + - "Highlight border" + on_input: + - "Mask characters as bullets" + on_blur: + - "Validate not empty" + + signin-form-submit-button: + on_click: + - "Validate all fields" + - "If valid: disable button, show loading state" + - "POST to /api/auth/signin" + - "On success: redirect to /dashboard" + - "On error: show error message, re-enable button" + + signin-form-forgot-link: + on_click: + - "Navigate to /auth/forgot-password" +``` + +--- + +## NEXT STEP + +Load `substeps/4c-06-states.md` + diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-06-states.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-06-states.md new file mode 100644 index 00000000..5ff61f1e --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-06-states.md @@ -0,0 +1,124 @@ +# Substep 4C-06: States + +**Goal:** Define all possible page and component states + +--- + +## EXECUTION + +**Let's define all possible states.** + +States show how the page and components appear in different situations. + +## PAGE-LEVEL STATES + +**What are the different page-level states?** + +Think about: +- Default/loaded state +- Empty state (no data) +- Loading state (fetching data) +- Error state (something went wrong) +- Success state (after action completes) + +For each state, describe: +- When it occurs +- What the user sees +- What actions are available + +Store page_states with descriptions + +## COMPONENT STATES + +**Now let's define component states.** + +For components with multiple appearances, we'll specify each state. + +For components with multiple states: + **{{object_id}}** states: + + - Default: + - Hover: + - Active/Pressed: + - Focus: + - Disabled: + - Loading: + - Error: + - Success: + + (Only specify states that apply to this component) + + Store component_states + + +✅ **All states defined!** + +**Page states:** {{page_state_count}} +**Component states:** {{component_state_count}} + +**Next:** We'll define validation rules. + +--- + +## MENU + +[C] Continue to 4C-07 (Validation) + +--- + +## EXAMPLE OUTPUT + +```yaml +page_states: + default: + trigger: "Page loads normally" + appearance: "Empty form ready for input" + actions: "User can fill form and submit" + + loading: + trigger: "After submit clicked" + appearance: "Submit button shows spinner, form disabled" + actions: "Wait for response" + + error: + trigger: "Authentication fails" + appearance: "Error message above form, submit button re-enabled" + actions: "User can retry with different credentials" + + success: + trigger: "Authentication succeeds" + appearance: "Brief success message" + actions: "Redirect to dashboard" + +component_states: + signin-form-email-input: + default: + appearance: "Gray border, placeholder text" + focus: + appearance: "Primary color border, label floats up" + filled: + appearance: "Dark border, label stays up" + error: + appearance: "Red border, error message below" + disabled: + appearance: "Light gray background, cursor not-allowed" + + signin-form-submit-button: + default: + appearance: "Primary color background, white text" + hover: + appearance: "Darker primary color" + active: + appearance: "Even darker, slight scale down" + loading: + appearance: "Spinner icon, text 'Signing in...'" + disabled: + appearance: "Gray background, lower opacity" +``` + +--- + +## NEXT STEP + +Load `substeps/4c-07-validation.md` + diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-07-validation.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-07-validation.md new file mode 100644 index 00000000..b7373c73 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-07-validation.md @@ -0,0 +1,123 @@ +# Substep 4C-07: Validation & Errors + +**Goal:** Define all validation rules and error messages + +--- + +## EXECUTION + +**Let's define validation rules and error messages.** + +This ensures users get helpful feedback. + +## VALIDATION RULES + +**What fields or inputs need validation?** + +For each field, specify: +- What makes it valid? +- What makes it invalid? +- When is it validated? (on blur, on submit, real-time?) + +For each validated field: + **{{field_name}}** validation: + + - Required: yes/no + - Format rules: + - Length limits: + - Custom rules: + - Validation timing: + + + Store validation_rules for field + + +## ERROR MESSAGES + +**Now let's define error messages for each validation failure.** + +We'll provide messages in all supported languages. + +For each validation rule: + **Error message when {{rule_name}} fails:** + + {{#each language}} + - {{language}}: + {{/each}} + + Error code (e.g., ERR_EMAIL_INVALID): + + + Store error_message with code and translations + + +✅ **Validation and errors defined!** + +**Validated fields:** {{validated_field_count}} +**Error messages:** {{error_message_count}} + +**Next:** We'll generate the complete specification document. + +--- + +## MENU + +[C] Continue to 4C-08 (Generate Specification) + +--- + +## EXAMPLE OUTPUT + +```yaml +validation_rules: + email_input: + required: true + format: "valid email format" + timing: "on_blur and on_submit" + rules: + - "Must contain @" + - "Must have domain" + - "No spaces allowed" + + password_input: + required: true + min_length: 8 + timing: "on_submit" + rules: + - "At least 8 characters" + - "Not empty" + +error_messages: + ERR_EMAIL_REQUIRED: + en: "Email address is required" + sv: "E-postadress krävs" + field: "email_input" + + ERR_EMAIL_INVALID: + en: "Please enter a valid email address" + sv: "Ange en giltig e-postadress" + field: "email_input" + + ERR_PASSWORD_REQUIRED: + en: "Password is required" + sv: "Lösenord krävs" + field: "password_input" + + ERR_PASSWORD_TOO_SHORT: + en: "Password must be at least 8 characters" + sv: "Lösenordet måste vara minst 8 tecken" + field: "password_input" + + ERR_AUTH_INVALID: + en: "Invalid email or password" + sv: "Ogiltig e-post eller lösenord" + severity: "critical" + display_location: "above_form" +``` + +--- + +## NEXT STEP + +Load `substeps/4c-08-generate-spec.md` + diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4c-08-generate-spec.md b/src/modules/wds/workflows/4-ux-design/substeps/4c-08-generate-spec.md new file mode 100644 index 00000000..0a9be87b --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/substeps/4c-08-generate-spec.md @@ -0,0 +1,99 @@ +# Substep 4C-08: Generate Specification Document + +**Goal:** Compile all gathered information into the complete specification + +--- + +## EXECUTION + +**Excellent! We've gathered everything we need.** + +Now I'll compile it all into your complete page specification. 📝 + +Generate specification document using template at `templates/page-specification.template.md` + +Fill in all sections with data collected: +- page_basics (from 4C-01) +- layout_sections (from 4C-02) +- components with object_ids (from 4C-03) +- multilingual_content (from 4C-04) +- interaction_behaviors (from 4C-05) +- page_states and component_states (from 4C-06) +- validation_rules and error_messages (from 4C-07) + + +Save complete specification to: +`{output_folder}/C-Scenarios/{scenario}/{page}/{page}.md` + + +✅ **Complete specification generated!** + +**Saved to:** `C-Scenarios/{scenario}/{page}/{page}.md` + +**What we documented:** +- Page basics and routing +- {{section_count}} layout sections +- {{component_count}} components with Object IDs +- Content in {{language_count}} languages +- {{interaction_count}} interaction behaviors +- {{state_count}} total states (page + component) +- {{validation_count}} validation rules +- {{error_count}} error messages + +**Your specification is development-ready!** 📋✨ + +The specification document includes: +- Clear Object IDs for every element +- Complete multilingual content +- Detailed interaction behaviors +- All possible states defined +- Validation rules and error messages +- Technical notes and data requirements + +--- + +## SPECIFICATION COMPLETE + +Substep 4C is now complete. Return control to Step 3 (step-03-design-page.md) which will proceed to Substep 4D (Prototype). + +--- + +## EXAMPLE SPECIFICATION SNIPPET + +```markdown +### Email Input Field + +**Object ID:** `signin-form-email-input` +**Component Type:** text-input +**Design System Component:** text-input (primary) + +**Content:** +- **Label (EN):** Email Address +- **Label (SV):** E-postadress +- **Placeholder (EN):** your@email.com +- **Placeholder (SV):** din@epost.com + +**States:** +- **Default:** Gray border, placeholder visible +- **Focus:** Primary color border, label floats above +- **Filled:** Dark border, label remains above +- **Error:** Red border, error message below +- **Disabled:** Light gray background, not interactive + +**Interactions:** +- **On Focus:** Highlight border, float label +- **On Input:** Real-time email format validation +- **On Blur:** Full validation, show error if invalid + +**Validation:** +- Required: Yes +- Format: Valid email (contains @, has domain) +- Error Code: ERR_EMAIL_INVALID +- Error Message (EN): "Please enter a valid email address" +- Error Message (SV): "Ange en giltig e-postadress" +``` + +--- + +**Substep 4C Complete!** Return to main page design flow. + diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md b/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md new file mode 100644 index 00000000..7c302149 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/substeps/4d-prototype.md @@ -0,0 +1,159 @@ +# Step 4D: HTML Prototype + +Create interactive prototype to validate design before development + +## Prototype Creation + +**Let's bring your specification to life!** + +I'll create an interactive HTML prototype that: +- Matches your specification exactly +- Uses your Design System (if Phase 5 enabled) +- Includes interactions and validation +- Switches between languages +- Reveals gaps in the design + +This is your chance to click through and test before development. 🎨 + +**Prototype scope - what should it include?** + +1. **Full interactive** - All interactions, validation, state changes +2. **Visual only** - Static design for visual review +3. **Specific features** - Focus on particular interactions + +Choice [1/2/3]: + +Store prototype_scope + +## Generate Prototype Files + +Generate HTML prototype: + +**File 1: HTML** ({page}-Prototype.html) +```html + + + + + + {{page_title}} - Prototype + + + + + {{generate_html_from_spec}} + + + + +``` + +**File 2: CSS** ({page}-Prototype.css) +```css +/* Design System tokens (if Phase 5 enabled) */ +{{design_system_imports}} + +/* Component styles matching specification */ +{{generate_css_from_spec}} + +/* Responsive styles */ +{{responsive_styles}} + +/* State styles */ +{{state_styles}} +``` + +**File 3: JavaScript** ({page}-Prototype.js) +```javascript +// Interaction behaviors from specification +{{generate_interactions_from_spec}} + +// Validation logic +{{validation_logic}} + +// State management +{{state_management}} + +// Language switching +{{language_switching}} + +// Initialize +{{initialization_code}} +``` + + +Save files to {output_folder}/C-Scenarios/{scenario}/{page}/Prototype/ + +✅ **Prototype created!** + +**Files:** +- `Prototype/{page}-Prototype.html` +- `Prototype/{page}-Prototype.css` +- `Prototype/{page}-Prototype.js` + +**Open the HTML file in your browser to test!** + +Try: +- Clicking all interactive elements +- Testing validation +- Switching languages +- Checking different screen sizes +- Looking for gaps or issues + +**After testing, what did you discover?** + +Common findings: +- Visual adjustments needed +- Missing states or interactions +- Content that's too long/short +- Flow issues +- Component needs + +Anything to fix or refine? + + + Would you like to: + 1. **Update specification (4C)** - Fix the specs and regenerate prototype + 2. **Quick prototype fix** - Adjust prototype directly + 3. **Note for later** - Document but move forward + + Choice [1/2/3]: + + + Return to Step 4C + + + + What changes? + Apply changes to prototype files + Updated! Test again in your browser. 🔄 + + + + Document issues as "refinement-notes.md" + + + + + Perfect! Your prototype validates the design. ✨ + + +**Prototype testing complete!** + +Your design is validated and ready for development. Time to extract the functional requirements we discovered. 📋 + +Ready to proceed to **Step 4E: PRD Update**? [Y/N] + + + Proceed to Step 4E + + + + No problem! Resume anytime with "continue scenario". 👍 + Save progress + + +--- + +**Next:** Step 4E (PRD Update) + diff --git a/src/modules/wds/workflows/4-ux-design/substeps/4e-prd-update.md b/src/modules/wds/workflows/4-ux-design/substeps/4e-prd-update.md new file mode 100644 index 00000000..0d76945b --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/substeps/4e-prd-update.md @@ -0,0 +1,131 @@ +# Step 4E: PRD Update + +Extract functional requirements discovered during design and add them to the PRD + +## Why This Step Matters + +**Time to capture what we learned!** + +Every page reveals concrete requirements: +- "This form needs email validation" +- "We need a GET endpoint for availability" +- "Users need to upload images here" + +Capturing these while the page is fresh ensures nothing is forgotten. The PRD becomes a complete feature inventory with traceability to the pages that need each feature. 📋 + +## Requirement Extraction + +**Let's identify the functional requirements this page revealed.** + +Think about: +- API endpoints needed +- Data validation rules +- File upload/storage +- Authentication/authorization +- External integrations +- Business logic +- Performance requirements + +What functionality does this page require from the backend/platform? + +For each requirement: + **Requirement: {{requirement_name}}** + + - What does it do? + - Why is it needed? + - Any specific constraints or rules? + + Document requirement details + + +## PRD Integration + +**I'll add these requirements to your PRD.** + +Each requirement will include: +- Clear description +- Reference to this page (e.g., "Required by: 2.1-Dog-Calendar") +- Any technical notes discovered during design + +Read existing PRD from {output_folder}/D-PRD/PRD.md + +Generate PRD update: + +```markdown +## Functional Requirements + +### {{requirement_name}} +**Required by:** {{page_reference}} +- {{requirement_description}} +- {{constraints}} +- {{technical_notes}} + +[Add to appropriate section of PRD] +``` + + +Update PRD file with new requirements +Maintain traceability: page → requirement + +✅ **PRD updated!** + +**Added {{requirement_count}} requirements:** +{{#each requirement}} +- {{requirement_name}} (required by {{page_reference}}) +{{/each}} + +**PRD Location:** `D-PRD/PRD.md` + +Your PRD is growing incrementally with every page you design. This creates complete traceability from design to requirements. 🎯 + +## Page Complete + +**Page "{page_name}" is complete!** 🎉 + +**Created:** +- ✅ Specification: `C-Scenarios/{scenario}/{page}/{page}.md` +- ✅ Prototype: `C-Scenarios/{scenario}/{page}/Prototype/` +- ✅ PRD Requirements: Added to `D-PRD/PRD.md` + +**Your page is development-ready with:** +- Complete Object ID mapping +- All states and interactions documented +- Multilingual content specified +- Interactive prototype for validation +- Functional requirements captured + +Time to celebrate! ✨ + +What's next? + +1. **Design next page** - Continue with the next page in this scenario +2. **New scenario** - Start a different user journey +3. **Review progress** - See what's been designed +4. **Take a break** - Save and continue later + +Choice [1/2/3/4]: + + + Move to next page in scenario + Return to Step 3 (design pages iteratively) + + + + Return to Step 2 (define new scenario) + + + + List all completed scenarios and pages + Show PRD requirement count + Return to this menu + + + + Great design session, {user_name}! All your work is saved. Resume anytime with "continue scenario". 🎨 + Save progress + + +--- + +**Step 4E Complete** - Page fully designed and specified! + diff --git a/src/modules/wds/workflows/4-ux-design/templates/page-specification.template.md b/src/modules/wds/workflows/4-ux-design/templates/page-specification.template.md new file mode 100644 index 00000000..a17859d8 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/templates/page-specification.template.md @@ -0,0 +1,228 @@ +# {page-number}-{page-name} + +**Scenario:** {scenario-name} +**Page Number:** {page-number} +**Created:** {date} +**Method:** Whiteport Design Studio (WDS) + +--- + +## Overview + +**Page Purpose:** {Brief description of what users accomplish on this page} + +**URL/Route:** {url-path} + +**Entry Points:** +- {How users arrive at this page} + +**Exit Points:** +- {Where users go after completing their goal} + +**Main User Goal:** {Primary objective for users on this page} + +--- + +## Layout Structure + +{High-level description of page layout - header, main content areas, footer, etc.} + +``` +[Optional: ASCII layout diagram] ++------------------+ +| Header | ++------------------+ +| Main Content | +| | ++------------------+ +| Footer | ++------------------+ +``` + +--- + +## Components & Object IDs + +### {Component Name 1} + +**Object ID:** `{page-section-element}` +**Component Type:** {button/input/card/etc.} +{#if design_system_enabled} +**Design System Component:** {component-name} +**Figma Component:** {figma-component-name} +**Variant:** {size=large, type=primary, etc.} +{/if} + +**States:** +- **Default:** {Description and behavior} +- **Hover:** {Hover state appearance and behavior} +- **Active:** {Active/clicked state} +- **Disabled:** {When and why disabled} +- **Loading:** {Loading state if applicable} +- **Error:** {Error state if applicable} + +**Behavior:** +{What happens when user interacts with this component} + +**Content:** +- **English:** {Text content in English} +- **{Language2}:** {Text content in second language} +- **{Language3}:** {Text content in third language} + +**Validation:** {If applicable - validation rules} + +--- + +{Repeat Component section for each element on the page} + +--- + +## Page States + +### Default State + +**When:** {When this state is active} +**Appearance:** {What the user sees} +**Available Actions:** {What users can do} + +### Empty State + +**When:** {When this state is active - e.g., no data available} +**Appearance:** {What the user sees} +**Message:** {Empty state message in all languages} +**Available Actions:** {What users can do} + +### Loading State + +**When:** {When this state is active - e.g., fetching data} +**Appearance:** {Loading indicators, disabled elements} +**Message:** {Loading message in all languages} +**Available Actions:** {What users can do while loading} + +### Error State + +**When:** {When this state is active} +**Appearance:** {Error UI elements} +**Error Messages:** {See Error Messages section} +**Recovery Actions:** {How user fixes the error} + +### Success State + +**When:** {When this state is active - after successful action} +**Appearance:** {Success indicators} +**Message:** {Success message in all languages} +**Next Steps:** {Where user goes or what they can do next} + +--- + +## Validation Rules + +{If applicable - for forms and inputs} + +| Field | Rule | Error Code | Error Message | +|-------|------|------------|---------------| +| {field-name} | {validation-rule} | {ERR_CODE} | {error-message} | + +--- + +## Error Messages + +| Error Code | Trigger | Message (English) | Message ({Lang2}) | Recovery | +|------------|---------|-------------------|-------------------|----------| +| ERR_001 | {When this error occurs} | {English message} | {Translated message} | {How to fix} | + +--- + +## Data Requirements + +### Data Sources + +| Data Element | Source | Type | Required | Notes | +|--------------|--------|------|----------|-------| +| {data-field} | {API endpoint or static} | {data-type} | {yes/no} | {notes} | + +### API Endpoints + +**{Endpoint Name}** +- **Method:** {GET/POST/PUT/DELETE} +- **Path:** `/api/{path}` +- **Purpose:** {What this endpoint does} +- **Request:** {Request format} +- **Response:** {Response format} +- **Error Codes:** {Possible errors} + +--- + +## Responsive Behavior + +### Mobile (< 768px) + +{Describe layout changes, hidden elements, mobile-specific interactions} + +### Tablet (768px - 1024px) + +{Describe layout changes for tablet} + +### Desktop (> 1024px) + +{Describe full desktop layout} + +--- + +## Interactions & Navigation + +### On Page Load + +1. {Action sequence when page loads} +2. {Data fetching} +3. {State initialization} + +### User Interactions + +**{Interaction Name}** +1. User {action} +2. System {response} +3. Page {state change} +4. User sees {result} + +--- + +## Accessibility + +- **Keyboard Navigation:** {Tab order, shortcuts} +- **Screen Readers:** {ARIA labels, descriptions} +- **Focus Management:** {Focus behavior} +- **Color Contrast:** {WCAG compliance notes} + +--- + +## Technical Notes + +{Any technical constraints, performance requirements, browser compatibility notes, etc.} + +--- + +## Design References + +**Sketches:** {Link to sketch files in Sketches/ folder} +**Prototype:** {Link to HTML prototype in Prototype/ folder} +**Trigger Map Reference:** {Which personas/drivers this page addresses} + +--- + +## Development Checklist + +Before implementing: +- [ ] All Object IDs assigned and documented +- [ ] All states defined and specified +- [ ] Validation rules clear +- [ ] Error messages in all languages +- [ ] API endpoints defined +- [ ] Responsive behavior specified +- [ ] Accessibility requirements noted +- [ ] Prototype validated + +--- + +*Created using Whiteport Design Studio (WDS) methodology* + diff --git a/src/modules/wds/workflows/4-ux-design/templates/scenario-overview.template.md b/src/modules/wds/workflows/4-ux-design/templates/scenario-overview.template.md new file mode 100644 index 00000000..50ffae16 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/templates/scenario-overview.template.md @@ -0,0 +1,154 @@ +# {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* + diff --git a/src/modules/wds/workflows/4-ux-design/workflow.md b/src/modules/wds/workflows/4-ux-design/workflow.md new file mode 100644 index 00000000..c03cda86 --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/workflow.md @@ -0,0 +1,62 @@ +--- +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 Baldr the UX Expert. + +**Your Role:** You are Baldr, 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. + diff --git a/src/modules/wds/workflows/4-ux-design/workflow.yaml b/src/modules/wds/workflows/4-ux-design/workflow.yaml new file mode 100644 index 00000000..b5e5216f --- /dev/null +++ b/src/modules/wds/workflows/4-ux-design/workflow.yaml @@ -0,0 +1,7 @@ +--- +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 +--- + diff --git a/src/modules/wds/workflows/LANGUAGE-CONFIGURATION-GUIDE.md b/src/modules/wds/workflows/LANGUAGE-CONFIGURATION-GUIDE.md new file mode 100644 index 00000000..31419348 --- /dev/null +++ b/src/modules/wds/workflows/LANGUAGE-CONFIGURATION-GUIDE.md @@ -0,0 +1,441 @@ +# Language Configuration Guide + +**Setting Up Multi-Language Projects in WDS** + +--- + +## Overview + +WDS supports two distinct language configurations: + +1. **Specification Language** - Language used to WRITE the design specifications +2. **Product Languages** - Languages the final PRODUCT will support + +These are configured during workflow initialization and stored in `wds-workflow-status.yaml`. + +--- + +## Configuration During Setup + +### Workflow Init (Step 4) + +During WDS project setup, you'll be asked: + +**Question 1: Specification Language** +``` +What language should WDS write the design specifications in? + +1. English (EN) +2. Swedish (SE) +3. Norwegian (NO) +4. Danish (DK) +5. Other +``` + +**Question 2: Product Languages** +``` +What languages will the final product support? + +List them separated by commas (e.g., "EN, SE" or "EN, SE, NO, DK") + +Product languages: _____________ +``` + +--- + +## Storage in Config + +Settings are stored in `docs/wds-workflow-status.yaml`: + +```yaml +config: + specification_language: "EN" + product_languages: + - EN + - SE + - NO +``` + +--- + +## How It Works + +### Specification Language + +**Used for:** +- Instructions and guidance text in specs +- Section descriptions +- Comments and annotations +- PRD documentation +- Design system documentation + +**Example:** +```markdown +# 1.1 Start Page + +## Page Purpose +Convert visitors into users by addressing... ← Written in spec language + +## User Situation +Family members experiencing daily stress... ← Written in spec language +``` + +### Product Languages + +**Used for:** +- All user-facing text content +- Button labels +- Form labels +- Error messages +- Help text +- Any text the END USER sees + +**Example:** +```markdown +#### Primary CTA Button +**OBJECT ID**: `start-hero-cta` +- **Component**: Button Primary +- **Content**: ← Product languages + - EN: "Get Started" + - SE: "Kom Igång" + - NO: "Kom i Gang" +``` + +--- + +## Common Configurations + +### Dog Week Example + +```yaml +config: + specification_language: "EN" # Specs written in English + product_languages: + - EN # Product supports English + - SE # and Swedish +``` + +**Result:** +- Design specs written in English +- All text objects have EN and SE translations + +### Nordic SaaS Example + +```yaml +config: + specification_language: "EN" # Specs in English + product_languages: + - EN + - SE + - NO + - DK + - FI # 5 Nordic languages +``` + +### Internal Swedish Tool + +```yaml +config: + specification_language: "SE" # Specs in Swedish + product_languages: + - SE # Only Swedish product +``` + +### Global Product + +```yaml +config: + specification_language: "EN" + product_languages: + - EN + - SE + - DE + - FR + - ES + - IT +``` + +--- + +## Impact on Workflows + +### Phase 1: Product Brief + +**Written in:** `specification_language` + +```markdown +# Product Brief + +## Vision +Create a platform that... ← Spec language + +## Target Users +Swedish families with... ← Spec language +``` + +### Phase 2: Trigger Map + +**Written in:** `specification_language` + +Personas and triggers documented in spec language. + +### Phase 4: UX Design + +**Specs in:** `specification_language` +**Text content in:** `product_languages` (all of them) + +```markdown +## Hero Object +**Purpose**: Primary value proposition ← Spec language + +#### Primary Headline +**OBJECT ID**: `start-hero-headline` +- **Component**: H1 heading +- **Position**: Center of hero ← Spec language +- **Content**: ← Product languages + - EN: "Every walk. on time." + - SE: "Varje promenad. i tid." +``` + +### Phase 5: Design System + +**Documentation in:** `specification_language` +**Component examples in:** All `product_languages` + +```markdown +## Button Component + +### Usage ← Spec language +Use this button for primary actions... + +### Examples ← Product languages +- EN: "Submit", "Save", "Continue" +- SE: "Skicka", "Spara", "Fortsätt" +``` + +### Phase 6: PRD Finalization + +**Written in:** `specification_language` + +PRD is technical documentation for developers. + +--- + +## Text Object Pattern + +Every text object follows this pattern: + +```markdown +#### {{Purpose_Name}} +**OBJECT ID**: `{{id}}` +- **Component**: {{type}} +- **Position**: {{description}} ← Spec language +- **Style**: {{specifications}} ← Spec language +- **Behavior**: {{description}} ← Spec language +- **Content**: ← Product languages + {{#each product_languages}} + - {{this}}: "{{content}}" + {{/each}} +``` + +**Real Example:** + +```markdown +#### Email Label +**OBJECT ID**: `signin-form-email-label` +- **Component**: Label text +- **Position**: Above email input field +- **For**: signin-form-email-input +- **Content**: + - EN: "Email Address" + - SE: "E-postadress" + - NO: "E-postadresse" +``` + +--- + +## Agent Behavior + +### During Phase 4 + +When documenting text objects, agents will: + +1. **Read config** from `wds-workflow-status.yaml` +2. **Extract** `product_languages` array +3. **Request content** for EACH language +4. **Group translations** so each language reads coherently + +**Agent prompt:** + +```markdown +**Content for this Primary Headline:** + +**EN:** + +**SE:** + +**NO:** +``` + +User provides all translations, agent validates and documents. + +--- + +## Benefits + +### ✅ Flexibility + +- Spec language can differ from product languages +- Teams can work in their native language +- Product can target different markets + +### ✅ Consistency + +- All text objects have all languages +- No missing translations +- Complete from the start + +### ✅ Clarity + +- Spec readers understand documentation +- End users see their language +- Translators see all languages together + +### ✅ Developer-Friendly + +Config provides: +```yaml +product_languages: + - EN + - SE + - NO +``` + +Developers know exactly what languages to implement. + +--- + +## Language Codes Reference + +**Nordic:** +- EN = English +- SE = Swedish (Svenska) +- NO = Norwegian (Norsk) +- DK = Danish (Dansk) +- FI = Finnish (Suomi) + +**Western Europe:** +- DE = German (Deutsch) +- FR = French (Français) +- ES = Spanish (Español) +- IT = Italian (Italiano) +- NL = Dutch (Nederlands) +- PT = Portuguese (Português) + +**Eastern Europe:** +- PL = Polish (Polski) +- CZ = Czech (Čeština) +- RU = Russian (Русский) + +**Asia:** +- JA = Japanese (日本語) +- ZH = Chinese (中文) +- KO = Korean (한국어) + +**Other:** +- AR = Arabic (العربية) +- TR = Turkish (Türkçe) + +--- + +## Example: Dog Week Configuration + +### During Setup + +``` +Specification Language: EN +Product Languages: EN, SE +``` + +### Stored Config + +```yaml +# docs/wds-workflow-status.yaml +config: + specification_language: "EN" + product_languages: + - EN + - SE +``` + +### In Specifications + +```markdown +# 1.1 Start Page + +The start page serves as the primary entry point... ← Written in EN + +#### Primary Headline +**OBJECT ID**: `start-hero-headline` +- **Component**: H1 heading +- **Position**: Center of hero section ← Written in EN +- **Content**: + - EN: "Every walk. on time. Every time." ← Product language 1 + - SE: "Varje promenad. i tid. Varje gång." ← Product language 2 +``` + +### For Developers + +```typescript +// Read from config +const languages = ['EN', 'SE']; + +// All text has both languages +const content = { + 'start-hero-headline': { + en: 'Every walk. on time. Every time.', + se: 'Varje promenad. i tid. Varje gång.' + } +}; +``` + +--- + +## Updating Language Configuration + +If you need to add/change languages mid-project: + +1. **Update** `docs/wds-workflow-status.yaml` +2. **Add missing translations** to existing text objects +3. **Continue** with new language config + +**Before:** +```yaml +product_languages: + - EN + - SE +``` + +**After:** +```yaml +product_languages: + - EN + - SE + - NO # Added Norwegian +``` + +**Update existing specs:** +```markdown +#### Primary Headline +- **Content**: + - EN: "Every walk. on time." + - SE: "Varje promenad. i tid." + - NO: "Hver tur. i tide." ← Add new language +``` + +--- + +**Language configuration ensures complete, translation-ready specifications from day one!** 🌍✨ + + + diff --git a/src/modules/wds/workflows/LANGUAGE-FLOW-DIAGRAM.md b/src/modules/wds/workflows/LANGUAGE-FLOW-DIAGRAM.md new file mode 100644 index 00000000..0ffe7249 --- /dev/null +++ b/src/modules/wds/workflows/LANGUAGE-FLOW-DIAGRAM.md @@ -0,0 +1,424 @@ +# Language Flow: Setup to Specification + +**How Language Configuration Flows Through WDS** + +--- + +## 1. Workflow Initialization + +**File:** `workflows/workflow-init/instructions.md` (Step 4) + +**User is asked:** + +``` +Specification Language - What language should WDS write the design specifications in? + +1. English (EN) +2. Swedish (SE) +3. Norwegian (NO) +4. Danish (DK) +5. Other + +Choice: 1 + +Product Languages - What languages will the final product support? + +(e.g., "EN, SE" or "EN, SE, NO, DK") + +Product languages: EN, SE +``` + +**Agent stores:** +- `specification_language = "EN"` +- `product_languages = ["EN", "SE"]` + +--- + +## 2. Config File Creation + +**File:** `docs/wds-workflow-status.yaml` + +**Generated from template:** + +```yaml +# WDS Workflow Status +generated: "2025-12-05" +project: "Dog Week" +project_type: "full-product" + +config: + folder_prefix: "letters" + folder_case: "title" + brief_level: "complete" + include_design_system: true + component_library: "custom" + specification_language: "EN" ← Stored here + product_languages: ← Stored here + - EN + - SE +``` + +--- + +## 3. Phase 4 Agent Reads Config + +**Agent:** Baldr (UX Designer) + +**When starting Phase 4:** + +```xml +Load {output_folder}/wds-workflow-status.yaml +Extract config.specification_language → "EN" +Extract config.product_languages → ["EN", "SE"] +Store in session context +``` + +**Agent now knows:** +- Write specs in English +- Request content in English AND Swedish for all text + +--- + +## 4. Sketch Analysis (4B) + +**File:** `substeps/4b-sketch-analysis.md` + +**Agent analyzes sketch:** + +``` +Detected text placeholder: +- 2 horizontal lines +- ~50-60 characters capacity +- Appears to be headline + +→ Routes to heading-text.md +``` + +**Language not needed yet** - analyzing visual structure only. + +--- + +## 5. Object Documentation (heading-text.md) + +**File:** `object-types/heading-text.md` + +### Step 1: Purpose-Based Naming + +``` +What is the PURPOSE of this text on the page? + +User: "Primary headline" + +→ Generates Object ID: start-hero-headline +``` + +### Step 2: Position & Style + +``` +Text element specifications: + +Type: H1 +Position: Center of hero +Font size: 42px +Line height: 1.2 +... +``` + +*Spec written in English (specification_language)* + +### Step 3: Content with Translations + +**Agent reads config:** +```xml +Load product_languages from config → ["EN", "SE"] +``` + +**Agent asks:** + +``` +Content for this Primary Headline: + +Based on sketch: 2 lines, ~50-60 characters total +Project languages: EN, SE + +EN: + +SE: +``` + +**User provides:** +``` +EN: Every walk. on time. Every time. + +SE: Varje promenad. i tid. Varje gång. +``` + +**Agent validates:** +``` +✅ EN content: 37 characters (fits 60 capacity) +✅ SE content: 36 characters (fits 60 capacity) +``` + +--- + +## 6. Generate Specification + +**Agent writes to:** `docs/C-Scenarios/01-Customer-Onboarding/1.1-Start-Page/1.1-Start-Page.md` + +```markdown +# 1.1 Start Page + +The start page serves as the primary entry point... ← English (spec language) + +## Page Sections + +### Hero Object +**Purpose**: Primary value proposition ← English (spec language) + +#### Primary Headline +**OBJECT ID**: `start-hero-headline` +- **Component**: H1 heading (`.text-heading-1`) +- **Position**: Center of hero section ← English (spec language) +- **Style**: Bold, 42px, line-height 1.2 ← English (spec language) +- **Behavior**: Updates with language toggle ← English (spec language) +- **Content**: ← Product languages + - EN: "Every walk. on time. Every time." + - SE: "Varje promenad. i tid. Varje gång." +``` + +--- + +## 7. Complete Text Group + +**For a full section with multiple text elements:** + +```markdown +### Hero Object +**Purpose**: Primary value proposition ← Spec language + +#### Primary Headline +**OBJECT ID**: `start-hero-headline` +- **Component**: H1 heading +- **Position**: Center of hero, top ← Spec language +- **Content**: + - EN: "Every walk. on time. Every time." ← Product languages + - SE: "Varje promenad. i tid. Varje gång." + +#### Supporting Text +**OBJECT ID**: `start-hero-supporting` +- **Component**: Body text +- **Position**: Below headline ← Spec language +- **Content**: + - EN: "Never miss a walk again." ← Product languages + - SE: "Missa aldrig en promenad." + +#### Primary CTA +**OBJECT ID**: `start-hero-cta` +- **Component**: Button Primary +- **Position**: Center, below text ← Spec language +- **Content**: + - EN: "Get Started" ← Product languages + - SE: "Kom Igång" +``` + +**Reading in English:** +> Every walk. on time. Every time. +> Never miss a walk again. +> [Get Started] + +**Reading in Swedish:** +> Varje promenad. i tid. Varje gång. +> Missa aldrig en promenad. +> [Kom Igång] + +--- + +## 8. Developer Handoff + +**Developer reads:** `docs/wds-workflow-status.yaml` + +```yaml +config: + product_languages: + - EN + - SE +``` + +**Developer implements:** + +```typescript +// i18n config +const supportedLanguages = ['en', 'se']; + +// Text content from specs +const translations = { + 'start-hero-headline': { + en: 'Every walk. on time. Every time.', + se: 'Varje promenad. i tid. Varje gång.' + }, + 'start-hero-supporting': { + en: 'Never miss a walk again.', + se: 'Missa aldrig en promenad.' + }, + 'start-hero-cta': { + en: 'Get Started', + se: 'Kom Igång' + } +}; + +// Language toggle +function setLanguage(lang: 'en' | 'se') { + // All translations ready to use! +} +``` + +--- + +## Flow Diagram + +``` +┌─────────────────────────────────────┐ +│ 1. Workflow Init (Step 4) │ +│ User selects: │ +│ - Spec Language: EN │ +│ - Product Languages: EN, SE │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ 2. Generate Config File │ +│ docs/wds-workflow-status.yaml │ +│ config: │ +│ specification_language: "EN" │ +│ product_languages: [EN, SE] │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ 3. Phase 4: UX Design │ +│ Baldr agent loads config │ +│ Knows: Specs in EN, Content in │ +│ EN + SE │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ 4. Sketch Analysis │ +│ Analyze visual structure │ +│ (Language-agnostic) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ 5. Text Object Documentation │ +│ heading-text.md │ +│ - Purpose naming (in spec lang) │ +│ - Position/style (in spec lang) │ +│ - Content (in ALL product langs) │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ 6. Generate Page Specification │ +│ docs/C-Scenarios/.../page.md │ +│ - Structure/logic in EN │ +│ - All text in EN + SE │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ 7. Developer Implementation │ +│ - Read config │ +│ - Extract translations │ +│ - Implement i18n │ +│ - All languages ready! │ +└─────────────────────────────────────┘ +``` + +--- + +## Key Principles + +### ✅ Two Distinct Languages + +**Specification Language:** +- Documentation language +- For designers, PMs, developers +- Describes structure, behavior, logic + +**Product Languages:** +- User-facing content +- What end users see +- Can be multiple languages + +### ✅ Early Configuration + +**Set during workflow init** - before any design work +- No mid-project surprises +- All stakeholders aligned +- Complete from day one + +### ✅ Automatic Propagation + +**Config flows through all phases:** +- Phase 1: Brief in spec language +- Phase 2: Trigger Map in spec language +- Phase 4: Specs in spec language, content in ALL product languages +- Phase 5: Design System docs in spec language, examples in all product languages +- Phase 6: PRD in spec language + +### ✅ Grouped for Coherence + +**Each text group reads naturally in each language:** + +```markdown +### Hero Object + +#### Headline + Body + CTA + +EN reads: "Every walk. Never miss a walk. Get Started" +SE reads: "Varje promenad. Missa aldrig. Kom Igång" +``` + +Each language complete and coherent! + +--- + +## Example: Adding Norwegian Mid-Project + +**Original config:** +```yaml +product_languages: + - EN + - SE +``` + +**User needs Norwegian:** + +1. **Update config:** +```yaml +product_languages: + - EN + - SE + - NO # Added +``` + +2. **Add to existing specs:** +```markdown +#### Primary Headline +- **Content**: + - EN: "Every walk. on time." + - SE: "Varje promenad. i tid." + - NO: "Hver tur. i tide." ← Add to all text objects +``` + +3. **Future text objects automatically include NO** + +Agents read updated config and request 3 languages going forward. + +--- + +**Language configuration ensures complete, production-ready translations from the very beginning!** 🌍✨ + + + diff --git a/src/modules/wds/workflows/wds-workflow-status-template.yaml b/src/modules/wds/workflows/wds-workflow-status-template.yaml index 26e5cd7b..9dc8546c 100644 --- a/src/modules/wds/workflows/wds-workflow-status-template.yaml +++ b/src/modules/wds/workflows/wds-workflow-status-template.yaml @@ -27,6 +27,8 @@ config: brief_level: "{{brief_level}}" # simplified or complete include_design_system: {{include_design_system}} component_library: "{{component_library}}" + specification_language: "{{specification_language}}" # Language for writing specs (EN, SE, etc.) + product_languages: {{product_languages}} # Array of languages product supports # Folder mapping (generated based on config) folders: diff --git a/src/modules/wds/workflows/workflow-init/instructions.md b/src/modules/wds/workflows/workflow-init/instructions.md index c80df759..89b5f45c 100644 --- a/src/modules/wds/workflows/workflow-init/instructions.md +++ b/src/modules/wds/workflows/workflow-init/instructions.md @@ -141,7 +141,49 @@ Choice [1/2]: brief_level - + +WDS needs to know what language to write specifications in and what languages your product will support. + +**Specification Language** - What language should WDS write the design specifications in? + +Common choices: +1. **English** (EN) - Default, widely used +2. **Swedish** (SE) +3. **Norwegian** (NO) +4. **Danish** (DK) +5. **Other** - I'll specify + +Choice [1-5]: +Store specification_language +specification_language + +**Product Languages** - What languages will the final product support? + +List them separated by commas (e.g., "EN, SE" or "EN, SE, NO, DK"): + +Common language codes: +- EN = English +- SE = Swedish +- NO = Norwegian +- DK = Danish +- FI = Finnish +- DE = German +- FR = French +- ES = Spanish + +Product languages: +Store product_languages (parse as array) +Validate language codes +product_languages + +✅ **Language Configuration:** +- **Specifications written in:** {{specification_language}} +- **Product supports:** {{product_languages_list}} + +All text specifications will include translations for: {{product_languages_list}} + + + WDS creates folders in your project's `docs/` directory. Let's configure how they're named. Folder prefix style: @@ -171,7 +213,7 @@ Choice [1/2]: folder_case - + The **Design System** phase is optional but valuable for building reusable components. @@ -214,7 +256,7 @@ Skip Design System if: include_design_system - + For the Design System, you can build custom components or use an existing library. @@ -235,7 +277,7 @@ Choice [1-8]: - + Load path file: {path_files}/{{project_type}}.yaml Build workflow_items from path file Apply brief_level setting (simplified or complete) @@ -248,14 +290,18 @@ Choice [1-8]: workflow_items folder_names brief_level +specification_language +product_languages - + Your WDS project setup: **Project:** {{project_name}} **Type:** {{project_type}} **Project Brief:** {{#if brief_level == 'complete'}}Complete{{else}}Simplified{{/if}} +**Specification Language:** {{specification_language}} +**Product Languages:** {{product_languages_list}} **Design System:** {{include_design_system}} {{#if component_library}}**Component Library:** {{component_library}}{{/if}} diff --git a/src/modules/wds/workflows/workflow-init/workflow.yaml b/src/modules/wds/workflows/workflow-init/workflow.yaml index 8134233e..b9a98b19 100644 --- a/src/modules/wds/workflows/workflow-init/workflow.yaml +++ b/src/modules/wds/workflows/workflow-init/workflow.yaml @@ -1,6 +1,11 @@ +--- +name: WDS Workflow Init +description: Initialize a WDS design project by selecting phases based on project needs +web_bundle: true +--- + # WDS Workflow Init - Project Setup name: wds-workflow-init -description: "Initialize a WDS design project by selecting phases based on project needs" author: "Whiteport Design Studio" # Critical variables from config diff --git a/src/modules/wds/workflows/workflow-status/workflow.yaml b/src/modules/wds/workflows/workflow-status/workflow.yaml index 633316aa..b48b4476 100644 --- a/src/modules/wds/workflows/workflow-status/workflow.yaml +++ b/src/modules/wds/workflows/workflow-status/workflow.yaml @@ -1,6 +1,11 @@ +--- +name: WDS Workflow Status +description: Check WDS project progress - answers 'what should I do now?' for any agent +web_bundle: true +--- + # WDS Workflow Status - Progress Checker name: wds-workflow-status -description: "Check WDS project progress - answers 'what should I do now?' for any agent" author: "Whiteport Design Studio" # Critical variables from config