@devo-bmad-custom/agent-orchestration 1.0.0

package/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-06-design-system.md

@@ -0,0 +1,167 @@
+# Step 6: Design System Choice
+
+Choose appropriate design system approach based on project requirements and constraints.
+
+## DESIGN SYSTEM CHOICE SEQUENCE
+
+### 1. Present Design System Options
+
+"For {{project_name}}, we need to choose a design system foundation. Think of design systems like LEGO blocks for UI — they provide proven components and patterns, ensuring consistency and speeding development.
+
+**Design System Approaches:**
+
+**1. Custom Design System**
+
+- Complete visual uniqueness
+- Full control over every component
+- Higher initial investment
+- Perfect for established brands with unique needs
+
+**2. Established System (Material Design, Ant Design, etc.)**
+
+- Fast development with proven patterns
+- Great defaults and accessibility built-in
+- Less visual differentiation
+- Ideal for startups or internal tools
+
+**3. Themeable System (MUI, Chakra UI, Tailwind UI)**
+
+- Customizable with strong foundation
+- Brand flexibility with proven components
+- Moderate learning curve
+- Good balance of speed and uniqueness
+
+Which direction feels right for your project?"
+
+### 2. Analyze Project Requirements
+
+"**Let's consider your specific needs:**
+
+**Based on our previous conversations:**
+
+- Platform: [platform from step 3]
+- Timeline: [inferred from user conversation]
+- Team Size: [inferred from user conversation]
+- Brand Requirements: [inferred from user conversation]
+- Technical Constraints: [inferred from user conversation]
+
+**Decision Factors:**
+
+- Need for speed vs. need for uniqueness
+- Brand guidelines or existing visual identity
+- Team's design expertise
+- Long-term maintenance considerations
+- Integration requirements with existing systems"
+
+### 3. Explore Specific Design System Options
+
+"**Recommended Options Based on Your Needs:**
+
+**For [Your Platform Type]:**
+
+- [Option 1] - [Key benefit] - [Best for scenario]
+- [Option 2] - [Key benefit] - [Best for scenario]
+- [Option 3] - [Key benefit] - [Best for scenario]
+
+**Considerations:**
+
+- Component library size and quality
+- Documentation and community support
+- Customization capabilities
+- Accessibility compliance
+- Performance characteristics
+- Learning curve for your team"
+
+### 4. Facilitate Decision Process
+
+"**Decision Framework:**
+
+1. What's most important: Speed, uniqueness, or balance?
+2. How much design expertise does your team have?
+3. Are there existing brand guidelines to follow?
+4. What's your timeline and budget?
+5. Long-term maintenance needs?
+
+Let's evaluate options based on your answers to these questions."
+
+### 5. Finalize Design System Choice
+
+"Based on our analysis, I recommend [Design System Choice] for {{project_name}}.
+
+**Rationale:**
+
+- [Reason 1 based on project needs]
+- [Reason 2 based on constraints]
+- [Reason 3 based on team considerations]
+
+Does this design system choice feel right to you?"
+
+### 6. Generate Design System Content
+
+When saving to document, append these sections:
+
+```markdown
+## Design System Foundation
+
+### Design System Choice
+
+[Design system choice based on conversation]
+
+### Rationale for Selection
+
+[Rationale for design system selection based on conversation]
+
+### Implementation Approach
+
+[Implementation approach based on chosen system]
+
+### Customization Strategy
+
+[Customization strategy based on project needs]
+
+### Design Token Mapping
+
+The execution agent MUST explicitly search for the project's design token definitions before generating any component code. Required search targets:
+
+- `tailwind.config.ts` or `tailwind.config.js` — for Tailwind token colors, spacing, fonts
+- `globals.css` or `variables.css` — for CSS custom property tokens
+- `theme.ts` or `themes/index.ts` — for JS-defined theme objects
+
+After searching the token files above, populate this table completely. A row with "TBD" is a compliance failure — every role MUST be resolved before generating any components:
+
+| Role        | Token Name                   | Value            |
+| ----------- | ---------------------------- | ---------------- |
+| Primary     | [resolved from token search] | [hex or CSS var] |
+| Secondary   | [resolved from token search] | [hex or CSS var] |
+| Background  | [resolved from token search] | [hex or CSS var] |
+| Foreground  | [resolved from token search] | [hex or CSS var] |
+| Muted       | [resolved from token search] | [hex or CSS var] |
+| Accent      | [resolved from token search] | [hex or CSS var] |
+| Destructive | [resolved from token search] | [hex or CSS var] |
+| Border      | [resolved from token search] | [hex or CSS var] |
+
+> **Completeness Rule:** NEVER generate component code with hardcoded hex values or arbitrary CSS. All style values MUST reference the mapped token names. If a token file cannot be found, explicitly report it to the user and ask how to proceed.
+```
+
+### 7. Auto-Initialize Design System via Script
+
+Immediately attempt to auto-initialize the design system. Do NOT ask the user for permission — run the script silently:
+
+```bash
+python skills/ui-ux-pro-custom/scripts/search.py "<product_type> <industry> <keywords>" --design-system -p "Project Name"
+# If python fails, try python3
+```
+
+- **On success:** Announce `"✅ Design system initialized from ui-ux-pro-custom intelligence."` and incorporate the generated tokens into the Design Token Mapping table.
+- **On failure:** Announce `"⚠️ Script unavailable — continuing with manual token definition."` and proceed with the manually defined tokens from conversation. Do NOT halt.
+
+### 8. Auto-Save and Advance
+
+Without presenting a menu or waiting for user input:
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Announce: `"✅ Design System Foundation saved. Advancing to next step..."`
+- Immediately load and execute: `{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md`
+
+> **HALT ONLY IF:** The design token search found zero token files AND the user has provided no token information. In that case, ask once: "I couldn't find any design token files in this project. Can you point me to your token definitions, or shall I use Tailwind defaults?"

package/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md

@@ -0,0 +1,143 @@
+# Step 7: Defining Core Experience
+
+Define the core interaction that, if nailed, makes everything else follow in the user experience.
+
+## DEFINING EXPERIENCE SEQUENCE
+
+### 1. Identify the Defining Experience
+
+"Every successful product has a defining experience — the core interaction that, if we nail it, everything else follows.
+
+**Think about these famous examples:**
+- Tinder: "Swipe to match with people"
+- Snapchat: "Share photos that disappear"
+- Instagram: "Share perfect moments with filters"
+- Spotify: "Discover and play any song instantly"
+
+**For {{project_name}}:**
+What's the core action that users will describe to their friends?
+What's the interaction that makes users feel successful?
+If we get ONE thing perfectly right, what should it be?"
+
+### 2. Explore the User's Mental Model
+
+"**User Mental Model Questions:**
+- How do users currently solve this problem?
+- What mental model do they bring to this task?
+- What's their expectation for how this should work?
+- Where are they likely to get confused or frustrated?
+
+**Current Solutions:**
+- What do users love/hate about existing approaches?
+- What shortcuts or workarounds do they use?
+- What makes existing solutions feel magical or terrible?"
+
+### 3. Define Success Criteria for Core Experience
+
+"**Core Experience Success Criteria:**
+- What makes users say 'this just works'?
+- When do they feel smart or accomplished?
+- What feedback tells them they're doing it right?
+- How fast should it feel?
+- What should happen automatically?
+
+**Success Indicators:**
+- [Success indicator 1]
+- [Success indicator 2]
+- [Success indicator 3]"
+
+### 4. Identify Novel vs. Established Patterns
+
+"**Pattern Analysis:**
+Looking at your core experience, does this:
+- Use established UX patterns that users already understand?
+- Require novel interaction design that needs user education?
+- Combine familiar patterns in innovative ways?
+
+**If Novel:**
+- What makes this different from existing approaches?
+- How will we teach users this new pattern?
+- What familiar metaphors can we use?
+
+**If Established:**
+- Which proven patterns should we adopt?
+- How can we innovate within familiar patterns?
+- What's our unique twist on established interactions?"
+
+### 5. Define Experience Mechanics
+
+"**Core Experience Mechanics:**
+Let's design the step-by-step flow for [defining experience]:
+
+**1. Initiation:**
+- How does the user start this action?
+- What triggers or invites them to begin?
+
+**2. Interaction:**
+- What does the user actually do?
+- What controls or inputs do they use?
+- How does the system respond?
+
+**3. Feedback:**
+- What tells users they're succeeding?
+- How do they know when it's working?
+- What happens if they make a mistake?
+
+**4. Completion:**
+- How do users know they're done?
+- What's the successful outcome?
+- What's next?"
+
+### 6. Generate Defining Experience Content
+
+When saving to document, append these sections:
+
+```markdown
+## 2. Core User Experience
+
+### 2.1 Defining Experience
+
+[Defining experience description based on conversation]
+
+### 2.2 User Mental Model
+
+[User mental model analysis based on conversation]
+
+### 2.3 Success Criteria
+
+[Success criteria for core experience based on conversation]
+
+### 2.4 Novel UX Patterns
+
+[Novel UX patterns analysis based on conversation]
+
+### 2.5 Experience Mechanics
+
+[Detailed mechanics for core experience based on conversation]
+```
+
+### 7. Present Content and Menu
+
+"I've defined the core experience for {{project_name}} — the interaction that will make users love this product.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine the core experience definition
+[P] Party Mode - Bring different perspectives on the defining interaction
+[AR] Adversarial Review [C] Continue - Save this to the document and move to visual foundation"
+
+### 8. Handle Menu Selection
+
+**If A:** Read fully and follow `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml` with the current content. Ask user to accept/reject improvements, then return to menu.
+
+**If P:** Read fully and follow `{project-root}/_bmad/core/workflows/party-mode/workflow.md` with the current content. Ask user to accept/reject changes, then return to menu.
+
+**If AR:** Execute `{project-root}/_bmad/core/tasks/review-adversarial-general.xml` — display findings with recommendations; then redisplay this menu.
+
+**If C:**
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md`

package/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md

@@ -0,0 +1,118 @@
+# Step 8: Visual Foundation
+
+Establish the visual design foundation including color themes, typography, and spacing systems.
+
+## VISUAL FOUNDATION SEQUENCE
+
+### 1. Brand Guidelines Assessment
+
+"Do you have existing brand guidelines or a specific color palette I should follow? (y/n)
+
+If yes, I'll extract and document your brand colors and create semantic color mappings.
+If no, I'll generate theme options based on your project's personality and emotional goals from our earlier discussion."
+
+### 2. Generate Color Theme Options (If no brand guidelines)
+
+"If no existing brand guidelines, I'll create a color theme visualizer to help you explore options.
+
+I can generate comprehensive HTML color theme visualizers with multiple theme options, complete UI examples, and the ability to see how colors work in real interface contexts.
+
+This will help you make an informed decision about the visual direction for {{project_name}}."
+
+### 3. Define Typography System
+
+"**Typography Questions:**
+- What should the overall tone feel like? (Professional, friendly, modern, classic?)
+- How much text content will users read? (Headings only? Long-form content?)
+- Any accessibility requirements for font sizes or contrast?
+- Any brand fonts we must use?
+
+**Typography Strategy:**
+- Choose primary and secondary typefaces
+- Establish type scale (h1, h2, h3, body, etc.)
+- Define line heights and spacing relationships
+- Consider readability and accessibility"
+
+### 4. Establish Spacing and Layout Foundation
+
+"**Spacing and Layout Foundation:**
+- How should the overall layout feel? (Dense and efficient? Airy and spacious?)
+- What spacing unit should we use? (4px, 8px, 12px base?)
+- How much white space should be between elements?
+- Should we use a grid system? If so, what column structure?
+
+**Layout Principles:**
+- [Layout principle 1 based on product type]
+- [Layout principle 2 based on user needs]
+- [Layout principle 3 based on platform requirements]"
+
+### 5. Create Visual Foundation Strategy
+
+"**Visual Foundation Strategy:**
+
+**Color System:**
+- [Color strategy based on brand guidelines or generated themes]
+- Semantic color mapping (primary, secondary, success, warning, error, etc.)
+- Accessibility compliance (contrast ratios)
+
+**Typography System:**
+- [Typography strategy based on content needs and tone]
+- Type scale and hierarchy
+- Font pairing rationale
+
+**Spacing & Layout:**
+- [Spacing strategy based on content density and platform]
+- Grid system approach
+- Component spacing relationships
+
+This foundation will ensure consistency across all our design decisions."
+
+### 6. Generate Visual Foundation Content
+
+When saving to document, append these sections:
+
+```markdown
+## Visual Design Foundation
+
+### Color System
+
+[Color system strategy based on conversation]
+
+### Typography System
+
+[Typography system strategy based on conversation]
+
+### Spacing & Layout Foundation
+
+[Spacing and layout foundation based on conversation]
+
+### Accessibility Considerations
+
+[Accessibility considerations based on conversation]
+```
+
+### 7. Present Content and Menu
+
+"I've established the visual design foundation for {{project_name}}. This provides the building blocks for consistent, beautiful design.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine our visual foundation
+[P] Party Mode - Bring design perspectives on visual choices
+[AR] Adversarial Review [C] Continue - Save this to the document and move to design directions"
+
+### 8. Handle Menu Selection
+
+**If A:** Read fully and follow `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml` with the current content. Ask user to accept/reject improvements, then return to menu.
+
+**If P:** Read fully and follow `{project-root}/_bmad/core/workflows/party-mode/workflow.md` with the current content. Ask user to accept/reject changes, then return to menu.
+
+**If AR:** Execute `{project-root}/_bmad/core/tasks/review-adversarial-general.xml` — display findings with recommendations; then redisplay this menu.
+
+**If C:**
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md`

package/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md

@@ -0,0 +1,154 @@
+# Step 9: Design Direction Mockups
+
+Generate comprehensive design direction mockups showing different visual approaches for the product.
+
+## DESIGN DIRECTIONS SEQUENCE
+
+### 1. Commit to a Bold Aesthetic Direction
+
+Before generating any mockups, explicitly ask the user:
+
+"Before I generate design directions, let's commit to a bold aesthetic point-of-view for {{project_name}}. A strong design direction avoids generic 'AI slop' patterns.
+
+**Choose an aesthetic direction (or describe your own):**
+
+- **Brutalist Clarity** — Raw, bold typography with stark contrast and minimal decoration
+- **Retro-Futuristic** — Neon accents, dark backgrounds, futuristic geometry with retro touches
+- **Elegant Minimalism** — Generous whitespace, refined typography scale, premium restraint
+- **Organic Warmth** — Fluid shapes, earthy tones, humanistic typography
+- **High-Energy Dynamic** — Motion-forward, vibrant color, high information density
+- **Something else?** — Describe your own direction
+
+Also confirm:
+
+- **Typography pair preference** — e.g., Clash Display + Inter, Syne + Manrope, etc.
+- **What should we AVOID aesthetically?** (I'll treat these as explicit anti-patterns)"
+
+### 2. Generate Design Direction Variations
+
+"I'll generate 6-8 different design direction variations exploring:
+
+- Different layout approaches and information hierarchy
+- Various interaction patterns and visual weights
+- Alternative color applications from our foundation
+- Different density and spacing approaches
+- Various navigation and component arrangements
+
+Each mockup will show a complete vision for {{project_name}} with all our design decisions applied, guided by our chosen bold aesthetic direction."
+
+### 3. Create HTML Design Direction Showcase
+
+Generate and save a comprehensive HTML design direction showcase at `{planning_artifacts}/ux-design-directions.html` showing:
+
+- 6-8 full-screen mockup variations
+- Interactive states and hover effects
+- Side-by-side comparison tools
+- Complete UI examples with real content
+- Responsive behavior demonstrations
+
+### 4. Present Design Exploration Framework
+
+"As you explore the design directions, look for:
+
+- **Layout Intuitiveness** - Which information hierarchy matches your priorities?
+- **Interaction Style** - Which interaction style fits your core experience?
+- **Visual Weight** - Which visual density feels right for your brand?
+- **Navigation Approach** - Which navigation pattern matches user expectations?
+- **Component Usage** - How well do the components support your user journeys?
+- **Brand Alignment** - Which direction best supports your emotional goals?
+
+Take your time exploring — this is a crucial decision that will guide all our design work!"
+
+### 5. Facilitate Design Direction Selection
+
+"After exploring all the design directions:
+
+**Which approach resonates most with you?**
+
+- Pick a favorite direction as-is
+- Combine elements from multiple directions
+- Request modifications to any direction
+- Use one direction as a base and iterate
+
+**Tell me:**
+
+- Which layout feels most intuitive for your users?
+- Which visual weight matches your brand personality?
+- Which interaction style supports your core experience?
+- Are there elements from different directions you'd like to combine?"
+
+### 6. Document Design Direction Decision
+
+"Based on your exploration, I'm understanding your design direction preference:
+
+**Chosen Direction:** [Direction number or combination]
+**Key Elements:** [Specific elements you liked]
+**Modifications Needed:** [Any changes requested]
+**Rationale:** [Why this direction works for your product]
+
+This will become our design foundation moving forward. Are we ready to lock this in, or do you want to explore variations?"
+
+### 7. Generate Design Direction Content
+
+When saving to document, append these sections:
+
+````markdown
+## Design Direction Decision
+
+### Design Thinking Summary
+
+> **Aesthetic Direction:** [Chosen bold name, e.g., "Retro-Futuristic", "Brutalist Clarity"]
+>
+> **Purpose:** [What this design must accomplish emotionally and functionally]
+>
+> **Tone:** [3 adjectives: e.g., Bold, Trustworthy, Energetic]
+>
+> **Differentiation:** [What makes this unforgettable vs. generic AI-generated UI]
+>
+> **Typography Pairing:** [Specific font names, e.g., "Clash Display for headings, Manrope for body"]
+>
+> **Google Fonts Import:** The execution agent MUST add the following `<link>` tags to the project's root layout or `_document.tsx` to activate this font pairing. If fonts are self-hosted, install via `next/font/local`. Never leave the font as a system default (e.g., Arial, sans-serif).
+>
+> ```html
+> <!-- Replace with actual font URLs resolved from the Typography Pairing above -->
+> <link rel="preconnect" href="https://fonts.googleapis.com" />
+> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+> <link
+>   href="https://fonts.googleapis.com/css2?family=[HeadingFont]&family=[BodyFont]&display=swap"
+>   rel="stylesheet"
+> />
+> ```
+>
+> **Explicit Anti-Patterns to Avoid:**
+>
+> - [e.g., Generic purple gradients on white backgrounds]
+> - [e.g., Generic Space Grotesk/Inter combo with no differentiation]
+> - [e.g., Predictable hero-section with centered H1 + CTA button]
+
+### Design Directions Explored
+
+[Summary of design directions explored based on conversation]
+
+### Chosen Direction
+
+[Chosen design direction based on conversation]
+
+### Design Rationale
+
+[Rationale for design direction choice based on conversation]
+
+### Implementation Approach
+
+[Implementation approach based on chosen direction]
+````
+
+### 8. Auto-Save and Advance
+
+Without presenting a menu or waiting for user input:
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Announce: `"✅ Design Direction Decision saved. Advancing to user journeys..."`
+- Immediately load and execute: `{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md`
+
+> **HALT ONLY IF:** The user has not yet declared an aesthetic direction. In that case, present the direction choices from Step 1 as a one-question halt, wait for a response, then continue without any further gates.