From 8835b0ef6d9231d596d8ad3c2f315673707ff158 Mon Sep 17 00:00:00 2001 From: azuma520 Date: Sun, 21 Dec 2025 14:37:54 +0800 Subject: [PATCH] feat(create-ux-design): integrate UI/UX Pro Max KB for design recommendations - Add KB search integration to step-08 (color, typography domains) - Add KB search integration to step-12 (ux domain with severity sorting) - Add Component Resources section to ux-design-template - Include fallback handling for graceful degradation Closes #1137 --- .../steps/step-08-visual-foundation.md | 107 ++++++++++++- .../steps/step-12-ux-patterns.md | 147 +++++++++++++++++- .../create-ux-design/ux-design-template.md | 16 +- 3 files changed, 261 insertions(+), 9 deletions(-) diff --git a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md index eea6d39a..8a5ef4c6 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md +++ b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md @@ -29,8 +29,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Execute {project-root}/\_bmad/core/tasks/advanced-elicitation.xml -- When 'P' selected: Execute {project-root}/\_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Execute {project-root}/.bmad/core/tasks/advanced-elicitation.xml +- When 'P' selected: Execute {project-root}/.bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -55,6 +55,103 @@ Check for existing brand requirements: 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." +### 1.5 Knowledge Base Integration (Auto) + +Before generating design options, automatically query the UI/UX Pro Max knowledge base for professional recommendations. + +#### Prerequisite: Extract Variables from Frontmatter + +Before executing searches, extract the following from the current document's frontmatter or previous step context: + +- `{industry}` - From frontmatter field `industry` or `productType` (e.g., "SaaS", "E-commerce") +- `{style_keywords}` - From frontmatter field `style`, `visualStyle`, or `emotionalGoals` (e.g., "modern minimal") + +**If variables are not available:** +- Use project name or product description as fallback search terms +- Or ask user: "What industry/style keywords should I use for design recommendations?" + +#### Color Palette Search + +Execute the following command using extracted context: + +```bash +python {project-root}/../.shared/ui-ux-pro-max/scripts/search.py "{industry} {style_keywords}" --domain color --json +``` + +> **Note:** Path assumes standard BMAD BMM structure. If `.shared` is elsewhere, please update path in search command. + +**Parse JSON Output Fields:** +- `Primary (Hex)` - Primary brand color +- `Secondary (Hex)` - Secondary accent color +- `CTA (Hex)` - Call-to-action button color +- `Background (Hex)` - Background color recommendation +- `Text (Hex)` - Text color for readability +- `Border (Hex)` - Border/divider color + +**Present to User:** +"🎨 **Knowledge Base Color Recommendations:** + +Based on your project's industry ({industry}) and style ({style_keywords}), here are professional color palette suggestions: + +| Role | Hex Code | Preview | +|------|----------|---------| +| Primary | {Primary (Hex)} | ██████ | +| Secondary | {Secondary (Hex)} | ██████ | +| CTA | {CTA (Hex)} | ██████ | +| Background | {Background (Hex)} | ██████ | +| Text | {Text (Hex)} | ██████ | +| Border | {Border (Hex)} | ██████ | + +**What would you like to do with these recommendations?** +[1] Accept - Use these as the starting point +[2] Modify - Adjust these colors to your preference +[3] Skip - Generate fresh options without these suggestions" + +#### Typography Search + +After color recommendations, execute typography search: + +```bash +python {project-root}/../.shared/ui-ux-pro-max/scripts/search.py "{style_keywords}" --domain typography --json +``` + +**Parse JSON Output Fields:** +- `Font Pairing Name` - Name of the font pairing (e.g., "Geometric Modern") +- `Google Fonts URL` - Ready-to-use Google Fonts import link +- `CSS Import` - CSS @import statement +- `Tailwind Config` - Tailwind CSS configuration snippet +- `Notes` - Additional usage notes + +**Present to User:** +"📝 **Knowledge Base Typography Recommendations:** + +**{Font Pairing Name}** + +| Property | Value | +|----------|-------| +| Google Fonts | {Google Fonts URL} | +| CSS Import | `{CSS Import}` | +| Tailwind Config | ```{Tailwind Config}``` | + +*{Notes}* + +**What would you like to do with these recommendations?** +[1] Accept - Use these font recommendations +[2] Modify - Adjust font choices +[3] Skip - Define typography from scratch" + +#### Fallback Handling + +If the search command fails, returns no results, or variables are unavailable: + +"ℹī¸ **Note:** Knowledge base search returned no specific recommendations for your criteria. Proceeding with standard design exploration. + +This is normal for unique combinations - we'll create custom options tailored to your needs." + +**Then proceed to Generate Color Theme Options normally.** + +--- + ### 2. Generate Color Theme Options (If no brand guidelines) Create visual exploration opportunities: @@ -168,7 +265,7 @@ Show the generated visual foundation content and present choices: #### If 'A' (Advanced Elicitation): -- Execute {project-root}/\_bmad/core/tasks/advanced-elicitation.xml with the current visual foundation content +- Execute {project-root}/.bmad/core/tasks/advanced-elicitation.xml with the current visual foundation content - Process the enhanced visual insights that come back - Ask user: "Accept these improvements to the visual foundation? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -176,7 +273,7 @@ Show the generated visual foundation content and present choices: #### If 'P' (Party Mode): -- Execute {project-root}/\_bmad/core/workflows/party-mode/workflow.md with the current visual foundation +- Execute {project-root}/.bmad/core/workflows/party-mode/workflow.md with the current visual foundation - Process the collaborative visual insights that come back - Ask user: "Accept these changes to the visual foundation? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -195,6 +292,8 @@ When user selects 'C', append the content directly to the document using the str ## SUCCESS METRICS: ✅ Brand guidelines assessed and incorporated if available +✅ Knowledge base integration executed before color generation +✅ User presented with Accept/Modify/Skip choices for KB recommendations ✅ Color system established with accessibility consideration ✅ Typography system defined with appropriate hierarchy ✅ Spacing and layout foundation created diff --git a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md index 8615d111..e0805782 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md +++ b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md @@ -29,8 +29,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Execute {project-root}/\_bmad/core/tasks/advanced-elicitation.xml -- When 'P' selected: Execute {project-root}/\_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Execute {project-root}/.bmad/core/tasks/advanced-elicitation.xml +- When 'P' selected: Execute {project-root}/.bmad/core/workflows/party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -47,6 +47,137 @@ Establish UX consistency patterns for common situations like buttons, forms, nav ## UX PATTERNS SEQUENCE: +### 0.5 Knowledge Base Integration (Auto) + +Before defining patterns, automatically query the UI/UX Pro Max knowledge base for UX best practices and accessibility guidelines. + +#### Prerequisite: Extract Variables from Context + +Extract the following from frontmatter or previous step context: + +- `{product_type}` - From frontmatter field `productCategory` OR `projectType` OR `industry` (e.g., "Dashboard", "E-commerce", "Mobile App") +- `{pattern_focus}` - From user journey analysis in step 10 (e.g., "forms", "navigation", "checkout") + +**Variable Extraction Priority:** +1. Check frontmatter for `productCategory` → use if exists +2. Check frontmatter for `projectType` → use if exists +3. Check frontmatter for `industry` → use if exists +4. If none found → ask user: "What type of product is this? (e.g., Dashboard, E-commerce, SaaS)" + +#### General UX Best Practices Search + +Execute the following command for universal UX guidelines: + +```bash +python {project-root}/../.shared/ui-ux-pro-max/scripts/search.py "animation accessibility" --domain ux --json +``` + +> **Note:** Path assumes standard BMAD BMM structure. If `.shared` is elsewhere, please update path in search command. + +**Parse JSON Output Fields:** +- `Category` - Pattern category (e.g., "Animation", "Forms", "Navigation") +- `Issue` - Specific issue being addressed +- `Platform` - Target platform (Web, iOS, Android, All) +- `Description` - Detailed explanation of the issue +- `Do` - Recommended practice +- `Don't` - Anti-pattern to avoid +- `Severity` - Priority level (High, Medium, Low) +- `Code Example Good` - Example of correct implementation +- `Code Example Bad` - Example of incorrect implementation + +**Sorting Algorithm (MUST follow exactly):** +1. Parse all items from JSON `results` array +2. Assign numeric priority: High=1, Medium=2, Low=3 +3. Sort by numeric priority (ascending = High first) +4. Within same severity, maintain original JSON order +5. Present sorted results in table + +**Present to User:** +"📋 **Knowledge Base UX Best Practices:** + +Based on universal UX and accessibility guidelines, here are recommendations to consider: + +| Severity | Platform | Category | Issue | Description | ✅ Do | ❌ Don't | +|----------|----------|----------|-------|-------------|-------|---------| +| 🔴 High | {Platform} | {Category} | {Issue} | {Description} | {Do} | {Don't} | +| 🟡 Medium | {Platform} | {Category} | {Issue} | {Description} | {Do} | {Don't} | +| đŸŸĸ Low | {Platform} | {Category} | {Issue} | {Description} | {Do} | {Don't} | + +**Code Examples:** +``` +✅ Good: {Code Example Good} +❌ Bad: {Code Example Bad} +``` + +**What would you like to do with these recommendations?** +[1] Accept all - Include these in our pattern definitions +[2] Select specific - Choose which recommendations to include +[3] Skip - Define patterns without these suggestions" + +**Handle User Selection:** + +- **If user selects [1] Accept all:** + - Store ALL Do/Don't pairs as reference for pattern definition + - Prefix each subsequent pattern with: "(KB: {Issue})" to show origin + - Proceed to Product-Specific Search + +- **If user selects [2] Select specific:** + - Ask: "Enter recommendation numbers to include (e.g., 1,3,5):" + - Store only selected recommendations + - Proceed to Product-Specific Search + +- **If user selects [3] Skip:** + - Do not store KB recommendations + - Proceed to Product-Specific Search + +#### Product-Specific UX Search + +After general guidelines, search for product-specific patterns: + +```bash +python {project-root}/../.shared/ui-ux-pro-max/scripts/search.py "{product_type}" --domain ux --json +``` + +**Present to User:** +"đŸŽ¯ **Product-Specific UX Recommendations ({product_type}):** + +| Severity | Platform | Issue | Description | ✅ Do | ❌ Don't | +|----------|----------|-------|-------------|-------|---------| +| {Severity} | {Platform} | {Issue} | {Description} | {Do} | {Don't} | + +These recommendations are tailored for {product_type} applications. + +**Include these in our pattern definitions?** +[1] Yes, include all +[2] Select specific ones +[3] Skip" + +**Handle User Selection:** + +- **If user selects [1] Yes, include all:** + - Merge with previously accepted recommendations + - Proceed to Identify Pattern Categories + +- **If user selects [2] Select specific ones:** + - Ask: "Enter recommendation numbers to include (e.g., 1,2):" + - Merge selected with previously accepted recommendations + - Proceed to Identify Pattern Categories + +- **If user selects [3] Skip:** + - Proceed to Identify Pattern Categories with only general recommendations (if any) + +#### Fallback Handling + +If the search command fails or returns no results: + +"ℹī¸ **Note:** Knowledge base search returned no specific recommendations for your criteria. Proceeding with collaborative pattern definition. + +We'll define patterns based on your product's unique needs." + +**Then proceed to Identify Pattern Categories normally.** + +--- + ### 1. Identify Pattern Categories Determine which patterns need definition for your product: @@ -181,7 +312,7 @@ Show the generated UX patterns content and present choices: #### If 'A' (Advanced Elicitation): -- Execute {project-root}/\_bmad/core/tasks/advanced-elicitation.xml with the current UX patterns content +- Execute {project-root}/.bmad/core/tasks/advanced-elicitation.xml with the current UX patterns content - Process the enhanced pattern insights that come back - Ask user: "Accept these improvements to the UX patterns? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -189,7 +320,7 @@ Show the generated UX patterns content and present choices: #### If 'P' (Party Mode): -- Execute {project-root}/\_bmad/core/workflows/party-mode/workflow.md with the current UX patterns +- Execute {project-root}/.bmad/core/workflows/party-mode/workflow.md with the current UX patterns - Process the collaborative pattern insights that come back - Ask user: "Accept these changes to the UX patterns? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -207,6 +338,9 @@ When user selects 'C', append the content directly to the document using the str ## SUCCESS METRICS: +✅ Knowledge base queried for general UX and accessibility guidelines +✅ Product-specific UX recommendations presented (sorted by severity) +✅ User given choice to accept/select/skip KB recommendations ✅ Critical pattern categories identified and prioritized ✅ Consistency patterns clearly defined and documented ✅ Patterns integrated with chosen design system @@ -225,6 +359,11 @@ When user selects 'C', append the content directly to the document using the str ❌ Not presenting A/P/C menu after content generation ❌ Appending content without user selecting 'C' +❌ **KB INTEGRATION**: Not querying knowledge base before pattern definition +❌ **KB INTEGRATION**: Ignoring user's Accept/Select/Skip choice +❌ **KB INTEGRATION**: Not sorting results by severity (High → Medium → Low) +❌ **KB INTEGRATION**: Missing Platform or Description fields in output table + ❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions ❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file ❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols diff --git a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/ux-design-template.md b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/ux-design-template.md index aeed9dc5..bffcf7a1 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/ux-design-template.md +++ b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/ux-design-template.md @@ -1,6 +1,9 @@ --- stepsCompleted: [] -inputDocuments: [] +inputDocuments: null +componentLibrary: "" +effectsLibrary: "" +referenceSites: null --- # UX Design Specification {{project_name}} @@ -10,4 +13,15 @@ inputDocuments: [] --- +## Component Resources + +| Category | Library / Resource | Notes | +|----------|-------------------|-------| +| **Base UI Library** | *(e.g., shadcn/ui, Radix, Chakra)* | | +| **Effects Library** | *(e.g., Framer Motion, GSAP)* | | +| **Icon Set** | *(e.g., Lucide, Heroicons)* | | +| **Reference Sites** | *(e.g., dribbble.com/xyz)* | | + +--- +