validation tasks added
This commit is contained in:
Brian Madison
Dave Dittrich
parent
1bf2cfdfd5
commit
94f2572b0b
|
|
@ -30,6 +30,12 @@ agent:
|
|||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
|
||||
description: Produce a Scale Adaptive Architecture
|
||||
|
||||
- trigger: validate-architecture
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
|
||||
checklist: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/checklist.md"
|
||||
document: "{output_folder}/architecture.md"
|
||||
description: Validate Architecture Document
|
||||
|
||||
- trigger: solutioning-gate-check
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml"
|
||||
description: Validate solutioning complete, ready for Phase 4 (Level 2-4 only)
|
||||
|
|
|
|||
|
|
@ -39,10 +39,12 @@ agent:
|
|||
workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml"
|
||||
description: Create Tech Spec for Level 0-1 (sometimes Level 2) projects
|
||||
|
||||
- trigger: validate-tech-spec
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml"
|
||||
checklist: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/checklist.md"
|
||||
document: "{output_folder}/tech-spec.md"
|
||||
description: Validate Technical Specification Document
|
||||
|
||||
- trigger: correct-course
|
||||
workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
|
||||
description: Course Correction Analysis
|
||||
|
||||
- trigger: validate
|
||||
exec: "{project-root}/bmad/core/tasks/validate-workflow.xml"
|
||||
description: Validate any document against its workflow checklist
|
||||
|
|
|
|||
|
|
@ -27,11 +27,7 @@ agent:
|
|||
description: Conduct Design Thinking Workshop to Define the User Specification
|
||||
|
||||
- trigger: validate-design
|
||||
workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/validate-ux-design/workflow.yaml"
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml"
|
||||
checklist: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design/checklist.md"
|
||||
document: "{output_folder}/ux-spec.md"
|
||||
description: Validate UX Specification and Design Artifacts
|
||||
|
||||
- trigger: ux-spec
|
||||
workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/ux-spec/workflow.yaml"
|
||||
description: Create UX/UI Specification and AI Frontend Prompts
|
||||
|
|
|
|||
|
|
@ -97,9 +97,10 @@ The workflow adapts automatically based on project assessment, but key configura
|
|||
│ ├── instructions-narrative.md # Narrative design instructions
|
||||
│ ├── narrative-template.md # Narrative planning template
|
||||
│ └── workflow.yaml
|
||||
└── ux/
|
||||
├── instructions-ux.md # UX specification instructions
|
||||
├── ux-spec-template.md # UX specification template
|
||||
└── create-ux-design/
|
||||
├── instructions.md # UX design instructions
|
||||
├── ux-design-template.md # UX design template
|
||||
├── checklist.md # UX design validation checklist
|
||||
└── workflow.yaml
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -205,7 +205,49 @@
|
|||
|
||||
---
|
||||
|
||||
## 14. Decision Rationale
|
||||
## 14. Cross-Workflow Alignment (Epics File Update)
|
||||
|
||||
**As UX design progresses, you discover implementation details that affect the story breakdown**
|
||||
|
||||
### Stories Discovered During UX Design
|
||||
|
||||
- [ ] **Review epics.md file** for alignment with UX design
|
||||
- [ ] **New stories identified** during UX design that weren't in epics.md:
|
||||
- [ ] Custom component build stories (if significant)
|
||||
- [ ] UX pattern implementation stories
|
||||
- [ ] Animation/transition stories
|
||||
- [ ] Responsive adaptation stories
|
||||
- [ ] Accessibility implementation stories
|
||||
- [ ] Edge case handling stories discovered during journey design
|
||||
- [ ] Onboarding/empty state stories
|
||||
- [ ] Error state handling stories
|
||||
|
||||
### Story Complexity Adjustments
|
||||
|
||||
- [ ] **Existing stories complexity reassessed** based on UX design:
|
||||
- [ ] Stories that are now more complex (UX revealed additional requirements)
|
||||
- [ ] Stories that are simpler (design system handles more than expected)
|
||||
- [ ] Stories that should be split (UX design shows multiple components/flows)
|
||||
- [ ] Stories that can be combined (UX design shows they're tightly coupled)
|
||||
|
||||
### Epic Alignment
|
||||
|
||||
- [ ] **Epic scope still accurate** after UX design
|
||||
- [ ] **New epic needed** for discovered work (if significant)
|
||||
- [ ] **Epic ordering might change** based on UX dependencies
|
||||
|
||||
### Action Items for Epics File Update
|
||||
|
||||
- [ ] **List of new stories to add** to epics.md documented
|
||||
- [ ] **Complexity adjustments noted** for existing stories
|
||||
- [ ] **Update epics.md** OR flag for architecture review first
|
||||
- [ ] **Rationale documented** for why new stories/changes are needed
|
||||
|
||||
**Note:** If significant story changes are identified, consider running architecture workflow BEFORE updating epics.md, since architecture decisions might reveal additional adjustments needed.
|
||||
|
||||
---
|
||||
|
||||
## 15. Decision Rationale
|
||||
|
||||
**Unlike template-driven workflows, this workflow should document WHY**
|
||||
|
||||
|
|
@ -219,7 +261,7 @@
|
|||
|
||||
---
|
||||
|
||||
## 15. Implementation Readiness
|
||||
## 16. Implementation Readiness
|
||||
|
||||
- [ ] **Designers can create high-fidelity mockups** from this spec
|
||||
- [ ] **Developers can implement** with clear UX guidance
|
||||
|
|
@ -231,7 +273,7 @@
|
|||
|
||||
---
|
||||
|
||||
## 16. Critical Failures (Auto-Fail)
|
||||
## 17. Critical Failures (Auto-Fail)
|
||||
|
||||
- [ ] ❌ **No visual collaboration** (color themes or design mockups not generated)
|
||||
- [ ] ❌ **User not involved in decisions** (auto-generated without collaboration)
|
||||
|
|
|
|||
|
|
@ -1,337 +0,0 @@
|
|||
# Color Psychology - Guide for color theme generation
|
||||
# Maps emotional goals, industries, and brand personalities to color strategies
|
||||
|
||||
emotional_impacts:
|
||||
trust_and_security:
|
||||
primary_colors: ["Blue", "Navy", "Deep Blue"]
|
||||
supporting_colors: ["Gray", "White", "Silver"]
|
||||
avoid: ["Bright Red", "Neon colors", "Purple"]
|
||||
industries: ["Finance", "Banking", "Insurance", "Healthcare", "Legal"]
|
||||
personality: "Professional, Reliable, Stable, Trustworthy"
|
||||
examples: ["PayPal", "Chase Bank", "Facebook", "LinkedIn"]
|
||||
|
||||
energy_and_excitement:
|
||||
primary_colors: ["Red", "Orange", "Bright Yellow"]
|
||||
supporting_colors: ["Black", "White", "Dark Gray"]
|
||||
avoid: ["Muted tones", "Pastels", "Brown"]
|
||||
industries: ["Sports", "Entertainment", "Food & Beverage", "Events"]
|
||||
personality: "Bold, Dynamic, Passionate, Energetic"
|
||||
examples: ["Coca-Cola", "Netflix", "McDonald's", "Spotify"]
|
||||
|
||||
creativity_and_innovation:
|
||||
primary_colors: ["Purple", "Magenta", "Electric Blue", "Vibrant Green"]
|
||||
supporting_colors: ["White", "Black", "Gradients"]
|
||||
avoid: ["Corporate Blue", "Dull Gray", "Brown"]
|
||||
industries: ["Tech Startups", "Design", "Creative", "Gaming"]
|
||||
personality: "Innovative, Creative, Forward-thinking, Unique"
|
||||
examples: ["Twitch", "Adobe Creative Cloud", "Discord", "Figma"]
|
||||
|
||||
calm_and_wellness:
|
||||
primary_colors: ["Soft Blue", "Green", "Teal", "Mint"]
|
||||
supporting_colors: ["White", "Cream", "Light Gray", "Natural tones"]
|
||||
avoid: ["Harsh Red", "Neon", "Dark/Heavy colors"]
|
||||
industries: ["Healthcare", "Wellness", "Meditation", "Spa", "Fitness"]
|
||||
personality: "Peaceful, Healthy, Natural, Balanced"
|
||||
examples: ["Calm", "Headspace", "Fitbit", "Whole Foods"]
|
||||
|
||||
luxury_and_sophistication:
|
||||
primary_colors: ["Black", "Gold", "Deep Purple", "Burgundy"]
|
||||
supporting_colors: ["White", "Cream", "Silver", "Dark Gray"]
|
||||
avoid: ["Bright primary colors", "Pastels", "Neon"]
|
||||
industries: ["Luxury Brands", "High-end Retail", "Premium Services"]
|
||||
personality: "Elegant, Exclusive, Premium, Refined"
|
||||
examples: ["Chanel", "Rolex", "Lexus", "Apple (premium products)"]
|
||||
|
||||
friendly_and_approachable:
|
||||
primary_colors: ["Warm Orange", "Coral", "Sunny Yellow", "Sky Blue"]
|
||||
supporting_colors: ["White", "Cream", "Light Gray"]
|
||||
avoid: ["Dark/Heavy colors", "Corporate Blue", "Black"]
|
||||
industries: ["Education", "Community", "Social", "Consumer Apps"]
|
||||
personality: "Friendly, Warm, Welcoming, Accessible"
|
||||
examples: ["Mailchimp", "Airbnb", "Duolingo", "Slack"]
|
||||
|
||||
minimal_and_modern:
|
||||
primary_colors: ["Black", "White", "One accent color"]
|
||||
supporting_colors: ["Light Gray", "Dark Gray", "Neutral tones"]
|
||||
avoid: ["Multiple bright colors", "Gradients", "Heavy decoration"]
|
||||
industries: ["Tech", "Design", "Fashion", "Architecture"]
|
||||
personality: "Clean, Modern, Focused, Simple"
|
||||
examples: ["Apple", "Stripe", "Medium", "Notion"]
|
||||
|
||||
playful_and_fun:
|
||||
primary_colors: ["Bright Pink", "Purple", "Turquoise", "Lime Green"]
|
||||
supporting_colors: ["White", "Pastels", "Gradients"]
|
||||
avoid: ["Corporate colors", "Muted tones", "All dark"]
|
||||
industries: ["Kids", "Gaming", "Entertainment", "Creative Tools"]
|
||||
personality: "Playful, Fun, Youthful, Energetic"
|
||||
examples: ["Spotify (brand refresh)", "TikTok", "Snapchat", "Nintendo"]
|
||||
|
||||
natural_and_organic:
|
||||
primary_colors: ["Earth Green", "Brown", "Terracotta", "Sage"]
|
||||
supporting_colors: ["Cream", "Beige", "Natural wood tones"]
|
||||
avoid: ["Neon", "Artificial colors", "Harsh blacks"]
|
||||
industries: ["Organic", "Sustainability", "Outdoor", "Food"]
|
||||
personality: "Natural, Authentic, Earthy, Sustainable"
|
||||
examples: ["Patagonia", "Whole Foods", "The Honest Company", "Allbirds"]
|
||||
|
||||
color_meanings:
|
||||
blue:
|
||||
emotions: ["Trust", "Calm", "Professional", "Reliable", "Security"]
|
||||
variations:
|
||||
light_blue: "Calm, peaceful, open"
|
||||
navy: "Professional, authoritative, corporate"
|
||||
bright_blue: "Energy, tech, modern"
|
||||
teal: "Sophisticated, unique, creative"
|
||||
usage: "Most popular brand color, especially tech and finance"
|
||||
caution: "Overused, can feel cold or corporate"
|
||||
|
||||
red:
|
||||
emotions: ["Passion", "Energy", "Urgency", "Love", "Danger"]
|
||||
variations:
|
||||
bright_red: "Excitement, urgency, action"
|
||||
dark_red: "Sophistication, luxury"
|
||||
coral: "Friendly, warm, modern"
|
||||
usage: "CTAs, warnings, important actions"
|
||||
caution: "Can be aggressive, use sparingly"
|
||||
|
||||
green:
|
||||
emotions: ["Growth", "Nature", "Health", "Wealth", "Harmony"]
|
||||
variations:
|
||||
bright_green: "Energy, growth, fresh"
|
||||
forest_green: "Stable, wealthy, traditional"
|
||||
mint: "Fresh, modern, calm"
|
||||
lime: "Playful, energetic, youthful"
|
||||
usage: "Sustainability, health, finance (money)"
|
||||
caution: "Can feel too natural or environmental"
|
||||
|
||||
yellow:
|
||||
emotions: ["Happiness", "Optimism", "Warmth", "Caution"]
|
||||
variations:
|
||||
bright_yellow: "Happy, energetic, attention-grabbing"
|
||||
gold: "Luxury, premium, celebration"
|
||||
mustard: "Warm, retro, sophisticated"
|
||||
usage: "Accents, highlights, warnings"
|
||||
caution: "Hard to read on white, can be overwhelming"
|
||||
|
||||
purple:
|
||||
emotions: ["Creativity", "Luxury", "Wisdom", "Spirituality"]
|
||||
variations:
|
||||
bright_purple: "Creative, fun, modern"
|
||||
deep_purple: "Luxury, sophistication"
|
||||
lavender: "Calm, gentle, feminine"
|
||||
usage: "Creative brands, beauty, luxury"
|
||||
caution: "Can feel too feminine or spiritual for some brands"
|
||||
|
||||
orange:
|
||||
emotions: ["Energy", "Enthusiasm", "Creativity", "Fun"]
|
||||
variations:
|
||||
bright_orange: "Energy, playful, attention"
|
||||
burnt_orange: "Warm, autumn, natural"
|
||||
coral: "Friendly, modern, approachable"
|
||||
usage: "CTAs, playful brands, food"
|
||||
caution: "Can be overwhelming, use as accent"
|
||||
|
||||
pink:
|
||||
emotions: ["Playfulness", "Romance", "Youthfulness", "Compassion"]
|
||||
variations:
|
||||
hot_pink: "Bold, modern, energetic"
|
||||
soft_pink: "Gentle, romantic, calming"
|
||||
neon_pink: "Edgy, youthful, attention-grabbing"
|
||||
usage: "Beauty, fashion, modern brands breaking gender norms"
|
||||
caution: "Traditionally gendered, modern usage is more diverse"
|
||||
|
||||
black:
|
||||
emotions: ["Sophistication", "Luxury", "Power", "Modern"]
|
||||
usage: "Luxury brands, text, backgrounds, minimalist designs"
|
||||
best_with: ["White", "Gold", "Silver", "One bright accent"]
|
||||
caution: "Can feel heavy or dark if overused"
|
||||
|
||||
white:
|
||||
emotions: ["Purity", "Simplicity", "Clean", "Modern"]
|
||||
usage: "Backgrounds, spacing, minimalist designs"
|
||||
best_with: "Any color as accent"
|
||||
caution: "Needs color for visual interest"
|
||||
|
||||
gray:
|
||||
emotions: ["Neutral", "Professional", "Sophisticated", "Modern"]
|
||||
variations:
|
||||
light_gray: "Subtle, backgrounds, dividers"
|
||||
charcoal: "Professional, modern, readable"
|
||||
usage: "Neutral backgrounds, text, shadows"
|
||||
caution: "Can feel boring or corporate if sole color"
|
||||
|
||||
semantic_colors:
|
||||
success:
|
||||
recommended: ["Green", "Teal", "Blue-Green"]
|
||||
meaning: "Completion, correct, positive action"
|
||||
usage: "Success messages, confirmations, completed states"
|
||||
|
||||
error:
|
||||
recommended: ["Red", "Crimson", "Dark Red"]
|
||||
meaning: "Failure, incorrect, warning"
|
||||
usage: "Error messages, validation failures, destructive actions"
|
||||
|
||||
warning:
|
||||
recommended: ["Orange", "Amber", "Yellow"]
|
||||
meaning: "Caution, attention needed, important"
|
||||
usage: "Warnings, important notices, confirmations needed"
|
||||
|
||||
info:
|
||||
recommended: ["Blue", "Light Blue", "Purple"]
|
||||
meaning: "Information, neutral notification"
|
||||
usage: "Info messages, tips, neutral notifications"
|
||||
|
||||
color_palette_structures:
|
||||
monochromatic:
|
||||
description: "Shades and tints of single color"
|
||||
good_for: "Minimalist, cohesive, simple"
|
||||
example: "Various blues from light to dark"
|
||||
difficulty: "Easy"
|
||||
|
||||
analogous:
|
||||
description: "Colors next to each other on color wheel"
|
||||
good_for: "Harmonious, natural, cohesive"
|
||||
example: "Blue, blue-green, green"
|
||||
difficulty: "Easy"
|
||||
|
||||
complementary:
|
||||
description: "Colors opposite on color wheel"
|
||||
good_for: "High contrast, vibrant, attention-grabbing"
|
||||
example: "Blue and orange"
|
||||
difficulty: "Moderate (can be jarring)"
|
||||
|
||||
triadic:
|
||||
description: "Three colors evenly spaced on wheel"
|
||||
good_for: "Vibrant, balanced, playful"
|
||||
example: "Red, yellow, blue"
|
||||
difficulty: "Moderate"
|
||||
|
||||
split_complementary:
|
||||
description: "Base color + two adjacent to complement"
|
||||
good_for: "Balanced, sophisticated, interesting"
|
||||
example: "Blue, red-orange, yellow-orange"
|
||||
difficulty: "Moderate"
|
||||
|
||||
60_30_10_rule:
|
||||
description: "60% dominant, 30% secondary, 10% accent"
|
||||
good_for: "Balanced, professional, not overwhelming"
|
||||
application:
|
||||
dominant_60: "Background, main surfaces"
|
||||
secondary_30: "Cards, secondary surfaces, navigation"
|
||||
accent_10: "CTAs, highlights, important elements"
|
||||
|
||||
industry_color_trends:
|
||||
tech:
|
||||
trending: ["Blue (trust)", "Purple (innovation)", "Gradients", "Dark mode"]
|
||||
examples: ["Facebook Blue", "Stripe Purple", "GitHub Dark"]
|
||||
|
||||
finance:
|
||||
traditional: ["Blue", "Green (money)", "Navy", "Gold"]
|
||||
modern: ["Bright Blue", "Teal", "Black with accent"]
|
||||
|
||||
healthcare:
|
||||
traditional: ["Blue (trust)", "Green (health)", "White (clean)"]
|
||||
modern: ["Teal", "Soft Blue", "Mint", "Warm accents"]
|
||||
|
||||
ecommerce:
|
||||
trending: ["Bold colors", "Black & White with accent", "Trust colors"]
|
||||
cta_colors: ["Orange", "Red", "Bright Green", "for 'Buy' buttons"]
|
||||
|
||||
saas:
|
||||
trending: ["Blue (trust)", "Purple (innovation)", "Modern Gradients"]
|
||||
avoid: ["Dull gray", "Brown", "Too many colors"]
|
||||
|
||||
education:
|
||||
traditional: ["Red", "Blue", "Green", "Yellow (primary colors)"]
|
||||
modern: ["Friendly Blue", "Warm Orange", "Playful Purple"]
|
||||
|
||||
food_beverage:
|
||||
appetite: ["Red (stimulates)", "Orange", "Yellow", "Brown (natural)"]
|
||||
healthy: ["Green", "Earth tones", "Natural colors"]
|
||||
|
||||
theme_generation_strategies:
|
||||
by_brand_personality:
|
||||
professional:
|
||||
primary: "Navy Blue or Charcoal"
|
||||
secondary: "Light Gray"
|
||||
accent: "Subtle Blue or Green"
|
||||
style: "Minimal, clean, trustworthy"
|
||||
|
||||
playful:
|
||||
primary: "Bright Purple or Turquoise"
|
||||
secondary: "White"
|
||||
accent: "Pink or Yellow"
|
||||
style: "Gradients, rounded, fun"
|
||||
|
||||
luxury:
|
||||
primary: "Black"
|
||||
secondary: "White or Cream"
|
||||
accent: "Gold or Deep Purple"
|
||||
style: "Sophisticated, minimal, high-end"
|
||||
|
||||
friendly:
|
||||
primary: "Warm Orange or Coral"
|
||||
secondary: "Cream or Light Blue"
|
||||
accent: "Sunny Yellow or Teal"
|
||||
style: "Warm, approachable, welcoming"
|
||||
|
||||
by_target_audience:
|
||||
gen_z:
|
||||
style: "Bold, gradients, high contrast, playful"
|
||||
colors: ["Bright Purple", "Neon Green", "Hot Pink", "Electric Blue"]
|
||||
|
||||
millennials:
|
||||
style: "Modern, subtle gradients, sophisticated"
|
||||
colors: ["Teal", "Coral", "Muted Purple", "Navy"]
|
||||
|
||||
business_professionals:
|
||||
style: "Clean, professional, trustworthy"
|
||||
colors: ["Navy", "Charcoal", "Subtle Blue", "Gray"]
|
||||
|
||||
children:
|
||||
style: "Bright, primary colors, playful"
|
||||
colors: ["Primary Red", "Bright Yellow", "Sky Blue", "Grass Green"]
|
||||
|
||||
accessibility_considerations:
|
||||
contrast_ratios:
|
||||
wcag_aa_normal: "4.5:1 minimum for normal text"
|
||||
wcag_aa_large: "3:1 minimum for large text (18pt+ or 14pt+ bold)"
|
||||
wcag_aaa_normal: "7:1 minimum for normal text (enhanced)"
|
||||
|
||||
color_blindness:
|
||||
types:
|
||||
- "Deuteranopia (red-green, most common)"
|
||||
- "Protanopia (red-green)"
|
||||
- "Tritanopia (blue-yellow, rare)"
|
||||
- "Achromatopsia (total color blindness, very rare)"
|
||||
|
||||
safe_combinations:
|
||||
- "Blue and Orange (safe for all types)"
|
||||
- "Blue and Yellow (safe for red-green)"
|
||||
- "Purple and Yellow (safe for most)"
|
||||
|
||||
avoid:
|
||||
- "Red and Green alone (confusing for red-green colorblind)"
|
||||
- "Blue and Purple alone (hard to distinguish)"
|
||||
- "Relying only on color (always pair with icon/text)"
|
||||
|
||||
testing_tools:
|
||||
- "Stark (Figma plugin)"
|
||||
- "Color Oracle (simulator)"
|
||||
- "WebAIM Contrast Checker"
|
||||
- "Coblis Color Blindness Simulator"
|
||||
|
||||
dark_mode_considerations:
|
||||
benefits: ["Reduced eye strain", "Battery savings (OLED)", "Modern aesthetic", "User preference"]
|
||||
|
||||
color_adjustments:
|
||||
primary: "Often brighter/more saturated in dark mode"
|
||||
backgrounds: "True black (#000) vs dark gray (#1a1a1a)"
|
||||
text: "Not pure white (use #e0e0e0 for less harsh)"
|
||||
shadows: "Use lighter shadows or colored glows"
|
||||
|
||||
common_issues:
|
||||
- "Pure black can cause smearing on OLED"
|
||||
- "Colors appear more vibrant on dark backgrounds"
|
||||
- "Need different contrast ratios"
|
||||
- "Shadows don't work (use borders/elevation instead)"
|
||||
|
|
@ -37,7 +37,7 @@ For integrated use, run `workflow-init` first for better context.
|
|||
</check>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Load context and understand the vision">
|
||||
<step n="1a" goal="Confirm project understanding or gather basic context">
|
||||
<critical>A UX designer must understand the WHY before designing the HOW</critical>
|
||||
|
||||
<action>Attempt to load context documents using fuzzy matching: - PRD: {prd_file} - Product Brief: {brief_file} - Brainstorming: {brainstorm_file}
|
||||
|
|
@ -53,6 +53,14 @@ For integrated use, run `workflow-init` first for better context.
|
|||
- Brand personality hints
|
||||
- Competitive landscape references
|
||||
</action>
|
||||
|
||||
<output>I've loaded your project documentation. Let me confirm what I'm seeing:
|
||||
|
||||
**Project:** {{project_summary_from_docs}}
|
||||
**Target Users:** {{user_summary_from_docs}}</output>
|
||||
|
||||
<ask>Does this match your understanding? Any corrections or additions?</ask>
|
||||
|
||||
</check>
|
||||
|
||||
<check if="no_documents_found">
|
||||
|
|
@ -63,17 +71,11 @@ For integrated use, run `workflow-init` first for better context.
|
|||
**Who is this for?** Describe your ideal user.</ask>
|
||||
</check>
|
||||
|
||||
<check if="documents_found">
|
||||
<output>I've loaded your project documentation. Let me confirm what I'm seeing:
|
||||
<template-output>project_and_users_confirmed</template-output>
|
||||
</step>
|
||||
|
||||
**Project:** {{project_summary_from_docs}}
|
||||
**Target Users:** {{user_summary_from_docs}}
|
||||
|
||||
Does this match your understanding?</output>
|
||||
|
||||
<ask>Sounds good? Any corrections?</ask>
|
||||
|
||||
</check>
|
||||
<step n="1b" goal="Understand core experience and platform">
|
||||
<critical>Now we discover the ONE thing that defines this experience</critical>
|
||||
|
||||
<ask>Now let's dig into the experience itself.
|
||||
|
||||
|
|
@ -86,6 +88,12 @@ Does this match your understanding?</output>
|
|||
**Platform:**
|
||||
Where will users experience this? (Web, mobile app, desktop, multiple platforms)</ask>
|
||||
|
||||
<template-output>core_experience_and_platform</template-output>
|
||||
</step>
|
||||
|
||||
<step n="1c" goal="Discover the desired emotional response">
|
||||
<critical>Emotion drives behavior - this shapes everything</critical>
|
||||
|
||||
<ask>This is crucial - **what should users FEEL when using this?**
|
||||
|
||||
Not what they'll do, but what emotion or state they should experience:
|
||||
|
|
@ -100,43 +108,45 @@ Not what they'll do, but what emotion or state they should experience:
|
|||
|
||||
Really think about the emotional response you want. What feeling would make them tell a friend about this?</ask>
|
||||
|
||||
<template-output>desired_emotional_response</template-output>
|
||||
</step>
|
||||
|
||||
<step n="1d" goal="Gather inspiration and analyze UX patterns">
|
||||
<critical>Learn from what users already love</critical>
|
||||
|
||||
<ask>**Inspiration time!**
|
||||
|
||||
Name 2-3 apps your users already love and USE regularly.
|
||||
|
||||
For each one, tell me:
|
||||
|
||||
- What do they do well from a UX perspective?
|
||||
- What makes the experience compelling?
|
||||
|
||||
Feel free to share:
|
||||
|
||||
- App names (I'll look them up to see current UX)
|
||||
- Screenshots (if you have examples of what you like)
|
||||
- Links to products or demos</ask>
|
||||
- Links to products or demos
|
||||
|
||||
<action>For each app mentioned:
|
||||
<WebSearch>{{app_name}} current interface UX design 2025</WebSearch>
|
||||
<action>Analyze what makes that app's UX effective</action>
|
||||
<action>Note patterns and principles that could apply to this project</action>
|
||||
</action>
|
||||
For each one, what do they do well from a UX perspective? What makes the experience compelling?</ask>
|
||||
|
||||
<action>If screenshots provided:
|
||||
<action>Analyze screenshots for UX patterns, visual style, interaction patterns</action>
|
||||
<action>Note what user finds compelling about these examples</action>
|
||||
</action>
|
||||
<action>For each app mentioned:
|
||||
<WebSearch>{{app_name}} current interface UX design 2025</WebSearch>
|
||||
<action>Analyze what makes that app's UX effective</action>
|
||||
<action>Note patterns and principles that could apply to this project</action>
|
||||
</action>
|
||||
|
||||
<action>Analyze project for UX complexity indicators:
|
||||
- Number of distinct user roles or personas
|
||||
- Number of primary user journeys
|
||||
- Interaction complexity (simple CRUD vs rich interactions)
|
||||
- Platform requirements (single vs multi-platform)
|
||||
- Real-time collaboration needs
|
||||
- Content creation vs consumption
|
||||
- Novel interaction patterns
|
||||
</action>
|
||||
<action>If screenshots provided:
|
||||
<action>Analyze screenshots for UX patterns, visual style, interaction patterns</action>
|
||||
<action>Note what user finds compelling about these examples</action>
|
||||
</action>
|
||||
|
||||
<action>Based on {user_skill_level}, set facilitation approach:
|
||||
<template-output>inspiration_analysis</template-output>
|
||||
</step>
|
||||
|
||||
<step n="1e" goal="Synthesize understanding and set facilitation mode">
|
||||
<critical>Now analyze complexity and set the right facilitation approach</critical>
|
||||
|
||||
<action>Analyze project for UX complexity indicators: - Number of distinct user roles or personas - Number of primary user journeys - Interaction complexity (simple CRUD vs rich interactions) - Platform requirements (single vs multi-platform) - Real-time collaboration needs - Content creation vs consumption - Novel interaction patterns
|
||||
</action>
|
||||
|
||||
<action>Based on {user_skill_level}, set facilitation approach:
|
||||
|
||||
<check if="{user_skill_level} == 'expert'">
|
||||
Set mode: UX_EXPERT
|
||||
|
|
@ -161,11 +171,10 @@ Feel free to share:
|
|||
- Focus on "why this matters for users"
|
||||
- Protect from overwhelming choices
|
||||
</check>
|
||||
|
||||
</action>
|
||||
|
||||
<action>Synthesize and reflect understanding back to {user_name}:
|
||||
|
||||
"Here's what I'm understanding about {{project_name}}:
|
||||
<output>Here's what I'm understanding about {{project_name}}:
|
||||
|
||||
**Vision:** {{project_vision_summary}}
|
||||
**Users:** {{user_summary}}
|
||||
|
|
@ -176,10 +185,7 @@ Feel free to share:
|
|||
|
||||
**UX Complexity:** {{complexity_assessment}}
|
||||
|
||||
This helps me understand both what we're building and the experience we're aiming for. It will guide every design decision we make together."
|
||||
</action>
|
||||
|
||||
<ask>Does this capture your vision? Anything I'm missing or misunderstanding?</ask>
|
||||
This helps me understand both what we're building and the experience we're aiming for. Let's start designing!</output>
|
||||
|
||||
<action>Load UX design template: {template}</action>
|
||||
<action>Initialize output document at {default_output_file}</action>
|
||||
|
|
@ -277,9 +283,8 @@ Or tell me:
|
|||
<template-output>design_system_decision</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Define core experience and discover novel patterns">
|
||||
<critical>Every great app has a defining experience - identify and design it</critical>
|
||||
<critical>Some projects need INVENTED UX patterns, not just standard solutions</critical>
|
||||
<step n="3a" goal="Identify the defining experience">
|
||||
<critical>Every great app has a defining experience - identify it first</critical>
|
||||
|
||||
<action>Based on PRD/brief analysis, identify the core user experience: - What is the primary action users will repeat? - What makes this app unique vs. competitors? - What should be delightfully easy?
|
||||
</action>
|
||||
|
|
@ -319,32 +324,49 @@ When someone describes your app to a friend, what would they say?
|
|||
|
||||
</action>
|
||||
|
||||
<template-output>defining_experience</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3b" goal="Design novel UX pattern (if needed)">
|
||||
<critical>Skip this step if standard patterns apply. Run only if novel pattern detected.</critical>
|
||||
|
||||
<check if="novel_pattern_detected">
|
||||
<action>Engage in collaborative UX pattern design:
|
||||
"The {{pattern_name}} interaction is novel - no established pattern exists yet!
|
||||
<output>The **{{pattern_name}}** interaction is novel - no established pattern exists yet!
|
||||
|
||||
Core UX challenge: {{challenge_description}}
|
||||
Core UX challenge: {{challenge_description}}
|
||||
|
||||
This is exciting - we get to invent the user experience together. Let's design this interaction by thinking through:
|
||||
This is exciting - we get to invent the user experience together. Let's design this interaction systematically.</output>
|
||||
|
||||
1. **User Goal:** What does the user want to accomplish?
|
||||
2. **Trigger:** How should they initiate this action? (button, gesture, voice, drag, etc.)
|
||||
3. **Feedback:** What should they see/feel happening?
|
||||
4. **Success:** How do they know it succeeded?
|
||||
5. **Errors:** What if something goes wrong? How do they recover?
|
||||
<ask>Let's think through the core mechanics of this {{pattern_name}} interaction:
|
||||
|
||||
Walk me through your mental model for this interaction - the ideal experience from the user's perspective."
|
||||
</action>
|
||||
1. **User Goal:** What does the user want to accomplish?
|
||||
2. **Trigger:** How should they initiate this action? (button, gesture, voice, drag, etc.)
|
||||
3. **Feedback:** What should they see/feel happening?
|
||||
4. **Success:** How do they know it succeeded?
|
||||
5. **Errors:** What if something goes wrong? How do they recover?
|
||||
|
||||
<action>Use advanced elicitation for UX innovation:
|
||||
"Let's explore this interaction more deeply.
|
||||
Walk me through your mental model for this interaction - the ideal experience from the user's perspective.</ask>
|
||||
|
||||
- What apps have SIMILAR (not identical) patterns we could learn from?
|
||||
- What's the absolute fastest this action could complete?
|
||||
- What's the most delightful way to give feedback?
|
||||
- Should this work on mobile differently than desktop?
|
||||
- What would make someone show this to a friend?"
|
||||
</action>
|
||||
<template-output>novel_pattern_mechanics</template-output>
|
||||
|
||||
</check>
|
||||
|
||||
<check if="!novel_pattern_detected">
|
||||
<action>Skip to Step 3d - standard patterns apply</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="3c" goal="Explore novel pattern deeply (if novel)">
|
||||
<critical>Skip if not designing novel pattern</critical>
|
||||
|
||||
<check if="novel_pattern_detected">
|
||||
<ask>Let's explore the {{pattern_name}} interaction more deeply to make it exceptional:
|
||||
|
||||
- **Similar Patterns:** What apps have SIMILAR (not identical) patterns we could learn from?
|
||||
- **Speed:** What's the absolute fastest this action could complete?
|
||||
- **Delight:** What's the most delightful way to give feedback?
|
||||
- **Platform:** Should this work on mobile differently than desktop?
|
||||
- **Shareability:** What would make someone show this to a friend?</ask>
|
||||
|
||||
<action>Document the novel UX pattern:
|
||||
Pattern Name: {{pattern_name}}
|
||||
|
|
@ -361,20 +383,37 @@ When someone describes your app to a friend, what would they say?
|
|||
Inspiration: {{similar_patterns_from_other_apps}}
|
||||
</action>
|
||||
|
||||
<template-output>novel_pattern_details</template-output>
|
||||
|
||||
</check>
|
||||
|
||||
<action>Define the core experience principles: - Speed: How fast should key actions feel? - Guidance: How much hand-holding do users need? - Flexibility: How much control vs. simplicity? - Feedback: Subtle or celebratory?
|
||||
<check if="!novel_pattern_detected">
|
||||
<action>Skip to Step 3d - standard patterns apply</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="3d" goal="Define core experience principles">
|
||||
<critical>Establish the guiding principles for the entire experience</critical>
|
||||
|
||||
<action>Based on the defining experience and any novel patterns, define the core experience principles: - Speed: How fast should key actions feel? - Guidance: How much hand-holding do users need? - Flexibility: How much control vs. simplicity? - Feedback: Subtle or celebratory?
|
||||
</action>
|
||||
|
||||
<template-output>core_experience</template-output>
|
||||
<template-output>novel_ux_patterns</template-output>
|
||||
<output>Core experience principles established:
|
||||
|
||||
**Speed:** {{speed_principle}}
|
||||
**Guidance:** {{guidance_principle}}
|
||||
**Flexibility:** {{flexibility_principle}}
|
||||
**Feedback:** {{feedback_principle}}
|
||||
|
||||
These principles will guide every UX decision from here forward.</output>
|
||||
|
||||
<template-output>core_experience_principles</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Discover visual foundation through color theme exploration">
|
||||
<critical>Visual design isn't decoration - it communicates brand and guides attention</critical>
|
||||
<critical>SHOW options, don't just describe them - generate HTML visualizations</critical>
|
||||
|
||||
<action>Load color psychology data: {color_psychology}</action>
|
||||
<critical>Use color psychology principles: blue=trust, red=energy, green=growth/calm, purple=creativity, etc.</critical>
|
||||
|
||||
<ask>Do you have existing brand guidelines or a specific color palette in mind? (y/n)
|
||||
|
||||
|
|
@ -512,6 +551,7 @@ What speaks to you?
|
|||
<step n="5" goal="Generate design direction mockups for visual decision-making">
|
||||
<critical>This is the game-changer - SHOW actual design directions, don't just discuss them</critical>
|
||||
<critical>Users make better decisions when they SEE options, not imagine them</critical>
|
||||
<critical>Consider platform norms: desktop apps often use sidebar nav, mobile apps use bottom nav or tabs</critical>
|
||||
|
||||
<action>Based on PRD and core experience, identify 2-3 key screens to mock up:
|
||||
|
||||
|
|
@ -529,7 +569,7 @@ What speaks to you?
|
|||
|
||||
</action>
|
||||
|
||||
<action>Generate 6-8 different design direction variations:
|
||||
<action>Generate 6-8 different design direction variations exploring different UX approaches:
|
||||
|
||||
Vary these dimensions:
|
||||
|
||||
|
|
@ -839,8 +879,7 @@ Component: {{custom_component_name}}
|
|||
<step n="8" goal="Define UX pattern decisions for consistency">
|
||||
<critical>These are implementation patterns for UX - ensure consistency across the app</critical>
|
||||
<critical>Like the architecture workflow's implementation patterns, but for user experience</critical>
|
||||
|
||||
<action>Load UX pattern catalog: {ux_pattern_catalog}</action>
|
||||
<critical>These decisions prevent "it works differently on every page" confusion</critical>
|
||||
|
||||
<action>Based on chosen components and journeys, identify UX consistency decisions needed:
|
||||
|
||||
|
|
@ -905,17 +944,38 @@ Component: {{custom_component_name}}
|
|||
|
||||
</action>
|
||||
|
||||
<action>For each pattern category, facilitate decision:
|
||||
<output>I've identified {{pattern_count}} UX pattern categories that need consistent decisions across your app. Let's make these decisions together to ensure users get a consistent experience.
|
||||
|
||||
<action>For each pattern, present options and recommendation:
|
||||
"Let's decide how {{pattern_category}} works throughout your app.
|
||||
These patterns determine how {{project_name}} behaves in common situations - like how buttons work, how forms validate, how modals behave, etc.</output>
|
||||
|
||||
If we don't decide now, it might work differently on different screens and confuse users.
|
||||
<ask>For each pattern category below, I'll present options and a recommendation. Tell me your preferences or ask questions.
|
||||
|
||||
**Options:** {{option_a}} vs {{option_b}} vs {{option_c_if_applicable}}
|
||||
**Pattern Categories to Decide:**
|
||||
|
||||
**My Recommendation:** {{choice}} for {{reason}}"
|
||||
</action>
|
||||
- Button hierarchy (primary, secondary, destructive)
|
||||
- Feedback patterns (success, error, loading)
|
||||
- Form patterns (labels, validation, help text)
|
||||
- Modal patterns (size, dismiss, focus)
|
||||
- Navigation patterns (active state, back button)
|
||||
- Empty state patterns
|
||||
- Confirmation patterns (delete, unsaved changes)
|
||||
- Notification patterns
|
||||
- Search patterns
|
||||
- Date/time patterns
|
||||
|
||||
For each one, do you want to:
|
||||
|
||||
1. Go through each pattern category one by one (thorough)
|
||||
2. Focus only on the most critical patterns for your app (focused)
|
||||
3. Let me recommend defaults and you override where needed (efficient)</ask>
|
||||
|
||||
<action>Based on user choice, facilitate pattern decisions with appropriate depth: - If thorough: Present all categories with options and reasoning - If focused: Identify 3-5 critical patterns based on app type - If efficient: Recommend smart defaults, ask for overrides
|
||||
|
||||
For each pattern decision, document:
|
||||
- Pattern category
|
||||
- Chosen approach
|
||||
- Rationale (why this choice for this app)
|
||||
- Example scenarios where it applies
|
||||
|
||||
</action>
|
||||
|
||||
|
|
@ -1064,6 +1124,128 @@ Based on your deployment intent: {{recommendation}}
|
|||
</invoke-workflow>
|
||||
</check>
|
||||
|
||||
<ask>🎨 **One more thing!** Want to see your design come to life?
|
||||
|
||||
I can generate interactive HTML mockups using all your design choices:
|
||||
|
||||
**1. Key Screens Showcase** - 6-8 panels showing your app's main screens (home, core action, settings, etc.) with your chosen:
|
||||
|
||||
- Color theme and typography
|
||||
- Design direction and layout
|
||||
- Component styles
|
||||
- Navigation patterns
|
||||
|
||||
**2. User Journey Visualization** - Step-by-step HTML mockup of one of your critical user journeys with:
|
||||
|
||||
- Each screen in the flow
|
||||
- Interactive transitions
|
||||
- Success states and feedback
|
||||
- All your design decisions applied
|
||||
|
||||
**3. Something else** - Tell me what you want to see!
|
||||
|
||||
**4. Skip for now** - I'll just finalize the documentation
|
||||
|
||||
What would you like?</ask>
|
||||
|
||||
<check if="user_choice == 'key_screens' or similar">
|
||||
<action>Generate comprehensive multi-panel HTML showcase:
|
||||
|
||||
Create: {final_app_showcase_html}
|
||||
|
||||
Include 6-8 screens representing:
|
||||
- Landing/Home screen
|
||||
- Main dashboard or feed
|
||||
- Core action screen (primary user task)
|
||||
- Profile or settings
|
||||
- Create/Edit screen
|
||||
- Results or success state
|
||||
- Modal/dialog examples
|
||||
- Empty states
|
||||
|
||||
Apply ALL design decisions:
|
||||
- {{chosen_color_theme}} with exact colors
|
||||
- {{chosen_design_direction}} layout and hierarchy
|
||||
- {{design_system}} components styled per decisions
|
||||
- {{typography_system}} applied consistently
|
||||
- {{spacing_system}} and responsive breakpoints
|
||||
- {{ux_patterns}} for consistency
|
||||
- {{accessibility_requirements}}
|
||||
|
||||
Make it interactive:
|
||||
- Hover states on buttons
|
||||
- Tab switching where applicable
|
||||
- Modal overlays
|
||||
- Form validation states
|
||||
- Navigation highlighting
|
||||
|
||||
Output as single HTML file with inline CSS and minimal JavaScript
|
||||
</action>
|
||||
|
||||
<output>✨ **Created: {final_app_showcase_html}**
|
||||
|
||||
Open this file in your browser to see {{project_name}} come to life with all your design choices applied! You can:
|
||||
|
||||
- Navigate between screens
|
||||
- See hover and interactive states
|
||||
- Experience your chosen design direction
|
||||
- Share with stakeholders for feedback
|
||||
|
||||
This showcases exactly what developers will build.</output>
|
||||
</check>
|
||||
|
||||
<check if="user_choice == 'user_journey' or similar">
|
||||
<ask>Which user journey would you like to visualize?
|
||||
|
||||
{{list_of_designed_journeys}}
|
||||
|
||||
Pick one, or tell me which flow you want to see!</ask>
|
||||
|
||||
<action>Generate step-by-step journey HTML:
|
||||
|
||||
Create: {journey_visualization_html}
|
||||
|
||||
For {{selected_journey}}:
|
||||
- Show each step as a full screen
|
||||
- Include navigation between steps (prev/next buttons)
|
||||
- Apply all design decisions consistently
|
||||
- Show state changes and feedback
|
||||
- Include success/error scenarios
|
||||
- Annotate design decisions on hover
|
||||
|
||||
Make it feel like a real user flow through the app
|
||||
</action>
|
||||
|
||||
<output>✨ **Created: {journey_visualization_html}**
|
||||
|
||||
Walk through the {{selected_journey}} flow step-by-step in your browser! This shows the exact experience users will have, with all your UX decisions applied.</output>
|
||||
</check>
|
||||
|
||||
<check if="user_choice == 'something_else'">
|
||||
<ask>Tell me what you'd like to visualize! I can generate HTML mockups for:
|
||||
- Specific screens or features
|
||||
- Interactive components
|
||||
- Responsive breakpoint comparisons
|
||||
- Accessibility features in action
|
||||
- Animation and transition concepts
|
||||
- Whatever you envision!
|
||||
|
||||
What should I create?</ask>
|
||||
|
||||
<action>Generate custom HTML visualization based on user request:
|
||||
- Parse what they want to see
|
||||
- Apply all relevant design decisions
|
||||
- Create interactive HTML mockup
|
||||
- Make it visually compelling and functional
|
||||
</action>
|
||||
|
||||
<output>✨ **Created: {{custom_visualization_file}}**
|
||||
|
||||
{{description_of_what_was_created}}
|
||||
|
||||
Open in browser to explore!</output>
|
||||
</check>
|
||||
|
||||
<output>**✅ UX Design Specification Complete!**
|
||||
|
||||
**Core Deliverables:**
|
||||
|
|
|
|||
|
|
@ -1,419 +0,0 @@
|
|||
# Layout Patterns - Guide for design direction generation
|
||||
# Maps project types and content to layout strategies
|
||||
|
||||
navigation_patterns:
|
||||
sidebar_navigation:
|
||||
description: "Vertical navigation panel on left or right"
|
||||
best_for: ["Desktop apps", "Dashboards", "Admin panels", "Content-heavy sites"]
|
||||
not_ideal_for: ["Simple sites", "Mobile-only", "Few sections (<5)"]
|
||||
|
||||
variants:
|
||||
always_visible:
|
||||
description: "Sidebar always shown on desktop"
|
||||
width: "200-280px"
|
||||
good_for: "Frequent navigation, many sections"
|
||||
|
||||
collapsible:
|
||||
description: "Can collapse to icons only"
|
||||
collapsed_width: "60-80px"
|
||||
expanded_width: "200-280px"
|
||||
good_for: "Space efficiency, user control"
|
||||
|
||||
mini_sidebar:
|
||||
description: "Icons only, expands on hover"
|
||||
collapsed_width: "60-80px"
|
||||
good_for: "Maximum content space, familiar users"
|
||||
|
||||
mobile_strategy: "Hamburger menu or bottom nav"
|
||||
examples: ["Notion", "Slack", "VS Code", "Gmail"]
|
||||
|
||||
top_navigation:
|
||||
description: "Horizontal navigation bar at top"
|
||||
best_for: ["Marketing sites", "Simple apps", "Few sections", "Mobile-friendly"]
|
||||
not_ideal_for: ["Many menu items (>7)", "Deep hierarchies"]
|
||||
|
||||
variants:
|
||||
horizontal_menu:
|
||||
description: "Simple horizontal list"
|
||||
max_items: "5-7"
|
||||
good_for: "Simple sites, clear hierarchy"
|
||||
|
||||
mega_menu:
|
||||
description: "Dropdown panels with rich content"
|
||||
good_for: "Complex sites, many subsections, ecommerce"
|
||||
|
||||
sticky_header:
|
||||
description: "Nav stays at top when scrolling"
|
||||
good_for: "Easy access, wayfinding"
|
||||
considerations: "Takes screen space, can annoy users"
|
||||
|
||||
mobile_strategy: "Hamburger menu"
|
||||
examples: ["Apple", "Stripe", "Most marketing sites"]
|
||||
|
||||
tab_navigation:
|
||||
description: "Horizontal tabs for section switching"
|
||||
best_for: ["Related content", "Settings", "Multi-view pages"]
|
||||
not_ideal_for: ["Unrelated sections", "Too many tabs (>7)"]
|
||||
max_tabs: "5-7 recommended"
|
||||
placement: ["Below header", "Page level", "Within cards"]
|
||||
examples: ["Settings pages", "Product details", "Profile pages"]
|
||||
|
||||
bottom_navigation:
|
||||
description: "Navigation bar at bottom (mobile)"
|
||||
best_for: ["Mobile apps", "3-5 primary sections", "Quick switching"]
|
||||
not_ideal_for: ["Desktop", "Many sections", "Deep hierarchies"]
|
||||
ideal_items: "3-5 (4 is optimal)"
|
||||
each_item: "Icon + short label"
|
||||
examples: ["Instagram", "Twitter app", "Most mobile apps"]
|
||||
|
||||
floating_action_button:
|
||||
description: "Primary action button floating over content"
|
||||
best_for: ["Mobile apps", "Single primary action", "Content-first"]
|
||||
placement: "Bottom-right (usually)"
|
||||
examples: ["Gmail (compose)", "Google Maps (directions)", "Notes (new note)"]
|
||||
|
||||
content_organization:
|
||||
card_based:
|
||||
description: "Content in distinct card containers"
|
||||
best_for: ["Scannable content", "Mixed content types", "Visual hierarchy"]
|
||||
not_ideal_for: ["Dense data", "Text-heavy content"]
|
||||
|
||||
variants:
|
||||
grid:
|
||||
description: "Equal-sized cards in grid"
|
||||
good_for: "Products, gallery, uniform items"
|
||||
examples: ["Pinterest", "Airbnb listings", "YouTube videos"]
|
||||
|
||||
masonry:
|
||||
description: "Variable-height cards in columns"
|
||||
good_for: "Mixed content heights, visual interest"
|
||||
examples: ["Pinterest", "Unsplash", "Dribbble"]
|
||||
|
||||
horizontal_scroll:
|
||||
description: "Cards in horizontal row"
|
||||
good_for: "Categories, featured items, mobile"
|
||||
examples: ["Netflix rows", "App Store Today"]
|
||||
|
||||
styling:
|
||||
elevated: "Drop shadows, floating appearance"
|
||||
bordered: "Subtle borders, flat appearance"
|
||||
|
||||
spacing:
|
||||
tight: "8-12px gaps (dense, lots of content)"
|
||||
medium: "16-24px gaps (balanced)"
|
||||
spacious: "32-48px gaps (premium, breathing room)"
|
||||
|
||||
list_based:
|
||||
description: "Linear list of items"
|
||||
best_for: ["Scannable data", "Chronological content", "Dense information"]
|
||||
not_ideal_for: ["Visual content", "Products", "Gallery"]
|
||||
|
||||
variants:
|
||||
simple_list:
|
||||
description: "Text-only list"
|
||||
good_for: "Simple data, settings, menus"
|
||||
|
||||
rich_list:
|
||||
description: "Items with images, meta, actions"
|
||||
good_for: "Email, messages, activity feeds"
|
||||
examples: ["Gmail inbox", "Twitter feed", "LinkedIn feed"]
|
||||
|
||||
grouped_list:
|
||||
description: "Lists with section headers"
|
||||
good_for: "Categorized content, settings"
|
||||
|
||||
interaction:
|
||||
clickable_rows: "Entire row is clickable"
|
||||
action_buttons: "Explicit action buttons in row"
|
||||
swipe_actions: "Swipe to reveal actions (mobile)"
|
||||
|
||||
table_based:
|
||||
description: "Data in rows and columns"
|
||||
best_for: ["Structured data", "Comparisons", "Admin panels", "Analytics"]
|
||||
not_ideal_for: ["Mobile", "Varied content", "Storytelling"]
|
||||
|
||||
mobile_strategy:
|
||||
horizontal_scroll: "Scroll table horizontally"
|
||||
hide_columns: "Show only essential columns"
|
||||
card_view: "Convert each row to card"
|
||||
|
||||
features:
|
||||
- "Sortable columns"
|
||||
- "Filterable data"
|
||||
- "Pagination or infinite scroll"
|
||||
- "Row selection"
|
||||
- "Inline editing"
|
||||
|
||||
examples: ["Admin dashboards", "Analytics", "Data management"]
|
||||
|
||||
dashboard_layout:
|
||||
description: "Widget-based information display"
|
||||
best_for: ["Data visualization", "Monitoring", "Analytics", "Admin"]
|
||||
|
||||
patterns:
|
||||
fixed_grid:
|
||||
description: "Predefined widget positions"
|
||||
good_for: "Consistent layout, simple dashboards"
|
||||
|
||||
customizable_grid:
|
||||
description: "Users can rearrange widgets"
|
||||
good_for: "Power users, personalization"
|
||||
examples: ["Google Analytics", "Jira dashboards"]
|
||||
|
||||
responsive_grid:
|
||||
description: "Widgets reflow based on screen size"
|
||||
good_for: "Mobile support, adaptive layouts"
|
||||
|
||||
feed_based:
|
||||
description: "Continuous stream of content"
|
||||
best_for: ["Social media", "News", "Activity", "Discovery"]
|
||||
|
||||
loading:
|
||||
infinite_scroll: "Load more as user scrolls"
|
||||
load_more_button: "Explicit action to load more"
|
||||
pagination: "Page numbers for browsing"
|
||||
|
||||
examples: ["Facebook", "Twitter", "Instagram", "LinkedIn"]
|
||||
|
||||
layout_density:
|
||||
spacious:
|
||||
description: "Lots of white space, breathing room"
|
||||
spacing: "32-64px between sections"
|
||||
card_padding: "24-32px"
|
||||
best_for: ["Premium brands", "Focus", "Minimal content"]
|
||||
examples: ["Apple", "Stripe landing", "Premium portfolios"]
|
||||
feeling: "Premium, focused, calm, elegant"
|
||||
|
||||
balanced:
|
||||
description: "Moderate spacing, comfortable reading"
|
||||
spacing: "16-32px between sections"
|
||||
card_padding: "16-24px"
|
||||
best_for: ["Most applications", "General content"]
|
||||
examples: ["Medium", "Notion", "Most SaaS apps"]
|
||||
feeling: "Professional, balanced, clear"
|
||||
|
||||
dense:
|
||||
description: "Compact layout, maximum information"
|
||||
spacing: "8-16px between sections"
|
||||
card_padding: "12-16px"
|
||||
best_for: ["Data-heavy", "Power users", "Admin panels"]
|
||||
examples: ["Gmail", "Google Analytics", "IDE interfaces"]
|
||||
feeling: "Efficient, information-rich, powerful"
|
||||
|
||||
content_hierarchy:
|
||||
hero_first:
|
||||
description: "Large hero section, then supporting content"
|
||||
best_for: ["Marketing sites", "Landing pages", "Product pages"]
|
||||
hero_height: "60-100vh"
|
||||
examples: ["Stripe", "Apple product pages", "SaaS landing pages"]
|
||||
|
||||
content_first:
|
||||
description: "Jump straight to content, minimal header"
|
||||
best_for: ["Blogs", "News", "Content platforms", "Reading"]
|
||||
examples: ["Medium", "News sites", "Wikipedia"]
|
||||
|
||||
balanced_hierarchy:
|
||||
description: "Clear but not overwhelming hero"
|
||||
best_for: ["General applications", "Balanced focus"]
|
||||
hero_height: "40-60vh"
|
||||
|
||||
visual_weight:
|
||||
minimal:
|
||||
description: "Flat, no shadows, subtle borders"
|
||||
characteristics:
|
||||
- "No or minimal shadows"
|
||||
- "Flat colors"
|
||||
- "Thin or no borders"
|
||||
- "Lots of white space"
|
||||
best_for: ["Modern brands", "Focus", "Clarity"]
|
||||
examples: ["Apple", "Google (recent)", "Superhuman"]
|
||||
|
||||
subtle_depth:
|
||||
description: "Light shadows, gentle elevation"
|
||||
characteristics:
|
||||
- "Subtle drop shadows"
|
||||
- "Light borders"
|
||||
- "Layered appearance"
|
||||
- "Comfortable spacing"
|
||||
best_for: ["Most applications", "Professional look"]
|
||||
examples: ["Notion", "Airtable", "Linear"]
|
||||
|
||||
material_depth:
|
||||
description: "Distinct shadows, clear elevation"
|
||||
characteristics:
|
||||
- "Defined shadows"
|
||||
- "Clear layering"
|
||||
- "Elevation system"
|
||||
- "Floating elements"
|
||||
best_for: ["Tactile feel", "Clarity", "Guidance"]
|
||||
examples: ["Material Design apps", "Gmail", "Google Drive"]
|
||||
|
||||
rich_visual:
|
||||
description: "Gradients, textures, visual interest"
|
||||
characteristics:
|
||||
- "Gradients"
|
||||
- "Background patterns"
|
||||
- "Visual flourishes"
|
||||
- "Rich shadows"
|
||||
best_for: ["Consumer brands", "Engagement", "Delight"]
|
||||
examples: ["Stripe (gradients)", "Instagram", "Spotify"]
|
||||
|
||||
column_layouts:
|
||||
single_column:
|
||||
description: "One content column, centered"
|
||||
max_width: "600-800px"
|
||||
best_for: ["Reading", "Focus", "Mobile-first", "Forms"]
|
||||
examples: ["Medium articles", "Substack", "Simple apps"]
|
||||
|
||||
two_column:
|
||||
description: "Main content + sidebar"
|
||||
ratios:
|
||||
main_sidebar: "2:1 or 3:1 (main content wider)"
|
||||
equal: "1:1 (rare, only for equal importance)"
|
||||
best_for: ["Blogs with sidebar", "Docs with nav", "Dashboard with filters"]
|
||||
mobile_strategy: "Stack vertically"
|
||||
|
||||
three_column:
|
||||
description: "Left nav + main content + right sidebar"
|
||||
typical_use: "Left nav, center content, right metadata/ads"
|
||||
best_for: ["Complex apps", "Social media", "News sites"]
|
||||
mobile_strategy: "Collapse to single column with hamburger"
|
||||
examples: ["Twitter", "Reddit", "Facebook"]
|
||||
|
||||
multi_column_grid:
|
||||
description: "2, 3, 4, or more columns"
|
||||
columns:
|
||||
two: "Tablets, small screens"
|
||||
three: "Desktop standard"
|
||||
four_plus: "Large screens, galleries"
|
||||
best_for: ["Products", "Gallery", "Cards", "Uniform content"]
|
||||
responsive:
|
||||
mobile: "1 column"
|
||||
tablet: "2 columns"
|
||||
desktop: "3-4 columns"
|
||||
large_desktop: "4-6 columns"
|
||||
|
||||
modal_and_overlay_patterns:
|
||||
center_modal:
|
||||
sizes: ["Small (400-500px)", "Medium (600-800px)", "Large (900-1200px)"]
|
||||
best_for: ["Forms", "Confirmations", "Detailed content"]
|
||||
|
||||
drawer_side_panel:
|
||||
position: "Right (common) or left"
|
||||
width: "320-600px"
|
||||
best_for: ["Filters", "Settings", "Details", "Navigation"]
|
||||
examples: ["E-commerce filters", "Gmail compose", "Slack channel details"]
|
||||
|
||||
fullscreen_modal:
|
||||
description: "Takes entire viewport"
|
||||
best_for: ["Mobile primarily", "Complex forms", "Immersive content"]
|
||||
mobile: "Often default on mobile"
|
||||
|
||||
popover:
|
||||
description: "Small overlay near trigger element"
|
||||
best_for: ["Tooltips", "Quick actions", "Contextual menus"]
|
||||
size: "Small (200-400px)"
|
||||
|
||||
responsive_strategies:
|
||||
mobile_first:
|
||||
approach: "Design for mobile, enhance for desktop"
|
||||
best_for: ["Consumer apps", "High mobile traffic", "Content-first"]
|
||||
breakpoints:
|
||||
- "Mobile: 320-767px (base design)"
|
||||
- "Tablet: 768-1023px (add space, possibly columns)"
|
||||
- "Desktop: 1024px+ (full layout, sidebars)"
|
||||
|
||||
desktop_first:
|
||||
approach: "Design for desktop, adapt for mobile"
|
||||
best_for: ["B2B apps", "Desktop-heavy usage", "Complex interfaces"]
|
||||
consideration: "Risk of poor mobile experience"
|
||||
|
||||
adaptive_layout:
|
||||
approach: "Different layouts for different screens, not just scaling"
|
||||
examples:
|
||||
- "Desktop: Sidebar nav | Mobile: Bottom nav"
|
||||
- "Desktop: 3 columns | Tablet: 2 columns | Mobile: 1 column"
|
||||
- "Desktop: Table | Mobile: Card list"
|
||||
|
||||
design_direction_variations:
|
||||
# These combine multiple patterns to create distinct design approaches
|
||||
|
||||
dense_dashboard:
|
||||
description: "Information-rich, efficient, power user focused"
|
||||
patterns:
|
||||
navigation: "Mini sidebar or always-visible sidebar"
|
||||
content: "Dashboard layout with widgets"
|
||||
density: "Dense"
|
||||
visual_weight: "Minimal or subtle depth"
|
||||
hierarchy: "Balanced, not hero-heavy"
|
||||
best_for: ["Analytics", "Admin panels", "Data tools", "Power users"]
|
||||
|
||||
spacious_explorer:
|
||||
description: "Generous spacing, discovery-oriented, visual"
|
||||
patterns:
|
||||
navigation: "Top nav or hidden sidebar"
|
||||
content: "Card-based grid or masonry"
|
||||
density: "Spacious"
|
||||
visual_weight: "Rich visual or subtle depth"
|
||||
hierarchy: "Hero-first or balanced"
|
||||
best_for: ["Content platforms", "Discovery", "Visual products", "Inspiration"]
|
||||
|
||||
focused_creator:
|
||||
description: "Minimal distractions, content creation focus"
|
||||
patterns:
|
||||
navigation: "Minimal top bar or hidden"
|
||||
content: "Single column or two-column with tools"
|
||||
density: "Spacious to balanced"
|
||||
visual_weight: "Minimal"
|
||||
hierarchy: "Content-first"
|
||||
best_for: ["Writing tools", "Editors", "Creative apps", "Focus work"]
|
||||
|
||||
social_feed:
|
||||
description: "Engagement-focused, endless content, familiar"
|
||||
patterns:
|
||||
navigation: "Top bar + bottom nav (mobile)"
|
||||
content: "Feed-based with rich cards"
|
||||
density: "Balanced"
|
||||
visual_weight: "Subtle depth to rich"
|
||||
hierarchy: "Content-first"
|
||||
best_for: ["Social media", "Content feeds", "Community platforms"]
|
||||
|
||||
enterprise_portal:
|
||||
description: "Professional, data-heavy, multi-section"
|
||||
patterns:
|
||||
navigation: "Sidebar (always visible or collapsible)"
|
||||
content: "Dashboard or table-based"
|
||||
density: "Dense to balanced"
|
||||
visual_weight: "Minimal to subtle"
|
||||
hierarchy: "Balanced"
|
||||
best_for: ["B2B SaaS", "Admin tools", "Enterprise apps"]
|
||||
|
||||
marketing_showcase:
|
||||
description: "Visual storytelling, conversion-focused, impressive"
|
||||
patterns:
|
||||
navigation: "Top nav (sticky or hero)"
|
||||
content: "Hero-first with sections"
|
||||
density: "Spacious"
|
||||
visual_weight: "Rich visual"
|
||||
hierarchy: "Hero-first"
|
||||
best_for: ["Landing pages", "Marketing sites", "Product showcases"]
|
||||
|
||||
minimal_focus:
|
||||
description: "Distraction-free, content-centric, elegant"
|
||||
patterns:
|
||||
navigation: "Minimal or hidden"
|
||||
content: "Single column, centered"
|
||||
density: "Spacious"
|
||||
visual_weight: "Minimal"
|
||||
hierarchy: "Content-first"
|
||||
best_for: ["Reading", "Focus apps", "Premium brands", "Portfolios"]
|
||||
|
||||
playful_interactive:
|
||||
description: "Fun, engaging, delightful, consumer-friendly"
|
||||
patterns:
|
||||
navigation: "Creative (could be any, with personality)"
|
||||
content: "Card-based or custom layouts"
|
||||
density: "Balanced to spacious"
|
||||
visual_weight: "Rich visual"
|
||||
hierarchy: "Hero or balanced"
|
||||
best_for: ["Consumer apps", "Gaming", "Entertainment", "Kids"]
|
||||
|
|
@ -1,482 +0,0 @@
|
|||
# UX Pattern Catalog - Knowledge base for UX design decisions
|
||||
# This enables intelligent, composable UX patterns instead of rigid templates
|
||||
|
||||
# ⚠️ CRITICAL: Use WebSearch to verify current design system versions during workflow execution
|
||||
|
||||
design_systems:
|
||||
web:
|
||||
material_ui:
|
||||
name: "Material UI"
|
||||
current_version: "5.15"
|
||||
platform: "Web (React)"
|
||||
good_for: ["Enterprise apps", "Data-heavy interfaces", "Google ecosystem", "Accessibility"]
|
||||
not_ideal_for: ["Unique brand identity", "Minimal designs", "Non-React"]
|
||||
components: "300+"
|
||||
accessibility: "WCAG 2.1 AA compliant"
|
||||
theming: "Extensive theming system"
|
||||
documentation: "Excellent"
|
||||
learning_curve: "Moderate"
|
||||
bundle_size: "Large (can be optimized)"
|
||||
beginner_friendly: true
|
||||
|
||||
shadcn_ui:
|
||||
name: "shadcn/ui"
|
||||
current_version: "Latest"
|
||||
platform: "Web (React + Tailwind)"
|
||||
good_for: ["Modern apps", "Full customization", "Tailwind users", "Copy-paste approach"]
|
||||
not_ideal_for: ["Non-Tailwind projects", "Quick prototyping", "Beginners"]
|
||||
components: "50+ (growing)"
|
||||
accessibility: "WCAG 2.1 AA via Radix primitives"
|
||||
theming: "Full Tailwind theming"
|
||||
documentation: "Good"
|
||||
learning_curve: "Easy if familiar with Tailwind"
|
||||
bundle_size: "Minimal (tree-shakeable)"
|
||||
beginner_friendly: false
|
||||
|
||||
chakra_ui:
|
||||
name: "Chakra UI"
|
||||
current_version: "2.8"
|
||||
platform: "Web (React)"
|
||||
good_for: ["Accessible apps", "Rapid development", "Dark mode", "Component composition"]
|
||||
not_ideal_for: ["Complex customization", "Non-React"]
|
||||
components: "50+"
|
||||
accessibility: "WCAG 2.1 AA compliant (accessibility-first)"
|
||||
theming: "Powerful theming system"
|
||||
documentation: "Excellent"
|
||||
learning_curve: "Easy"
|
||||
bundle_size: "Moderate"
|
||||
beginner_friendly: true
|
||||
|
||||
ant_design:
|
||||
name: "Ant Design"
|
||||
current_version: "5.12"
|
||||
platform: "Web (React)"
|
||||
good_for: ["Enterprise", "Admin panels", "Data tables", "Chinese market"]
|
||||
not_ideal_for: ["Consumer apps", "Minimal designs", "Non-React"]
|
||||
components: "60+"
|
||||
accessibility: "Good (improving)"
|
||||
theming: "Less design tokens"
|
||||
documentation: "Excellent"
|
||||
learning_curve: "Easy"
|
||||
bundle_size: "Large"
|
||||
beginner_friendly: true
|
||||
|
||||
radix_ui:
|
||||
name: "Radix UI"
|
||||
current_version: "1.0+"
|
||||
platform: "Web (React)"
|
||||
good_for: ["Full control", "Unstyled primitives", "Custom design systems"]
|
||||
not_ideal_for: ["Quick prototyping", "Pre-styled needs", "Beginners"]
|
||||
components: "25+ primitives"
|
||||
accessibility: "WCAG 2.1 AA compliant (accessibility-first)"
|
||||
theming: "Bring your own styles"
|
||||
documentation: "Excellent"
|
||||
learning_curve: "Moderate to Hard"
|
||||
bundle_size: "Minimal"
|
||||
beginner_friendly: false
|
||||
|
||||
tailwind_ui:
|
||||
name: "Tailwind UI"
|
||||
platform: "Web (Any framework + Tailwind)"
|
||||
good_for: ["Tailwind users", "Marketing sites", "High-quality examples"]
|
||||
not_ideal_for: ["Non-Tailwind", "Free tier"]
|
||||
components: "500+ examples (paid)"
|
||||
accessibility: "Good"
|
||||
theming: "Tailwind theming"
|
||||
documentation: "Excellent"
|
||||
learning_curve: "Easy if familiar with Tailwind"
|
||||
bundle_size: "Minimal"
|
||||
beginner_friendly: true
|
||||
|
||||
headless_ui:
|
||||
name: "Headless UI"
|
||||
current_version: "1.7"
|
||||
platform: "Web (React, Vue)"
|
||||
good_for: ["Unstyled primitives", "Full control", "Tailwind users"]
|
||||
not_ideal_for: ["Pre-styled needs", "Quick prototyping"]
|
||||
components: "13 primitives"
|
||||
accessibility: "WCAG 2.1 AA compliant"
|
||||
theming: "Bring your own styles"
|
||||
documentation: "Good"
|
||||
learning_curve: "Moderate"
|
||||
bundle_size: "Minimal"
|
||||
beginner_friendly: false
|
||||
|
||||
mobile:
|
||||
ios_hig:
|
||||
name: "iOS Human Interface Guidelines"
|
||||
platform: "iOS"
|
||||
good_for: ["iOS apps", "Native feel", "Apple ecosystem"]
|
||||
not_ideal_for: ["Cross-platform", "Custom branding"]
|
||||
components: "Native UIKit components"
|
||||
accessibility: "Built-in VoiceOver support"
|
||||
documentation: "Excellent (Apple HIG)"
|
||||
learning_curve: "Moderate"
|
||||
beginner_friendly: true
|
||||
|
||||
material_design:
|
||||
name: "Material Design (Mobile)"
|
||||
platform: "Android"
|
||||
good_for: ["Android apps", "Google ecosystem", "Accessibility"]
|
||||
not_ideal_for: ["iOS", "Custom branding"]
|
||||
components: "Material Components for Android"
|
||||
accessibility: "Built-in TalkBack support"
|
||||
documentation: "Excellent"
|
||||
learning_curve: "Moderate"
|
||||
beginner_friendly: true
|
||||
|
||||
react_native_paper:
|
||||
name: "React Native Paper"
|
||||
platform: "React Native (iOS & Android)"
|
||||
good_for: ["Cross-platform", "Material Design", "Quick development"]
|
||||
not_ideal_for: ["Native platform guidelines", "Highly custom designs"]
|
||||
components: "30+"
|
||||
accessibility: "Good"
|
||||
documentation: "Good"
|
||||
learning_curve: "Easy"
|
||||
beginner_friendly: true
|
||||
|
||||
button_hierarchy_patterns:
|
||||
standard:
|
||||
name: "Standard Button Hierarchy"
|
||||
primary:
|
||||
description: "Most important action on screen"
|
||||
style: "Filled with primary color, high contrast"
|
||||
usage: "One per screen (save, submit, next, create)"
|
||||
example: "Submit Form, Create Account, Save Changes"
|
||||
|
||||
secondary:
|
||||
description: "Alternative or supporting action"
|
||||
style: "Outlined or subtle fill with secondary color"
|
||||
usage: "Secondary actions, cancel alternatives"
|
||||
example: "Cancel, Go Back, Learn More"
|
||||
|
||||
tertiary:
|
||||
description: "Least prominent action"
|
||||
style: "Text-only button, minimal styling"
|
||||
usage: "Low-priority actions, links"
|
||||
example: "Skip, Dismiss, View Details"
|
||||
|
||||
destructive:
|
||||
description: "Dangerous or irreversible action"
|
||||
style: "Red or error color, often requires confirmation"
|
||||
usage: "Delete, remove, clear data"
|
||||
example: "Delete Account, Remove Item, Clear All"
|
||||
|
||||
feedback_patterns:
|
||||
toast_notification:
|
||||
name: "Toast Notification"
|
||||
good_for: ["Non-blocking feedback", "Success confirmations", "Quick info"]
|
||||
not_ideal_for: ["Critical errors", "Required user action", "Detailed messages"]
|
||||
placement: ["Top-right", "Bottom-center", "Top-center"]
|
||||
duration: "2-5 seconds (auto-dismiss)"
|
||||
actions: "Optional undo or action button"
|
||||
|
||||
inline_message:
|
||||
name: "Inline Message"
|
||||
good_for: ["Form validation", "Contextual errors", "Field-specific feedback"]
|
||||
not_ideal_for: ["Global messages", "Unrelated to visible content"]
|
||||
placement: "Adjacent to related element"
|
||||
duration: "Persistent until fixed or dismissed"
|
||||
actions: "Minimal (usually just dismiss or fix)"
|
||||
|
||||
modal_alert:
|
||||
name: "Modal Alert/Dialog"
|
||||
good_for: ["Critical errors", "Blocking actions", "Required confirmations"]
|
||||
not_ideal_for: ["Non-critical info", "Frequent messages", "Quick feedback"]
|
||||
placement: "Center overlay"
|
||||
duration: "Requires user dismissal"
|
||||
actions: "Clear action buttons (OK, Cancel, etc.)"
|
||||
|
||||
banner:
|
||||
name: "Banner Notification"
|
||||
good_for: ["System-wide messages", "Important updates", "Persistent alerts"]
|
||||
not_ideal_for: ["Transient feedback", "Frequent changes"]
|
||||
placement: "Top of page/screen"
|
||||
duration: "Persistent until dismissed"
|
||||
actions: "Optional actions or dismiss"
|
||||
|
||||
form_patterns:
|
||||
labels:
|
||||
above_input:
|
||||
name: "Labels Above Input"
|
||||
good_for: ["Clarity", "Mobile-friendly", "Accessibility"]
|
||||
not_ideal_for: ["Horizontal space constraints"]
|
||||
style: "Label above, left-aligned"
|
||||
|
||||
floating_label:
|
||||
name: "Floating/Inline Label"
|
||||
good_for: ["Space efficiency", "Modern aesthetic", "Material Design"]
|
||||
not_ideal_for: ["Accessibility (can be confusing)", "Complex forms"]
|
||||
style: "Label inside input, floats on focus"
|
||||
|
||||
side_by_side:
|
||||
name: "Side-by-Side Label"
|
||||
good_for: ["Dense forms", "Desktop layouts", "Admin panels"]
|
||||
not_ideal_for: ["Mobile", "Long labels", "Accessibility"]
|
||||
style: "Label to left of input, aligned"
|
||||
|
||||
validation:
|
||||
on_blur:
|
||||
name: "Validate on Blur"
|
||||
description: "Check field when user leaves it"
|
||||
good_for: "Immediate feedback without being disruptive"
|
||||
timing: "After user finishes typing and moves away"
|
||||
|
||||
on_change:
|
||||
name: "Validate on Change"
|
||||
description: "Real-time validation as user types"
|
||||
good_for: "Password strength, character limits, format checking"
|
||||
timing: "As user types (debounced)"
|
||||
|
||||
on_submit:
|
||||
name: "Validate on Submit"
|
||||
description: "Check all fields when form submitted"
|
||||
good_for: "Simple forms, avoiding interruption"
|
||||
timing: "When user clicks submit"
|
||||
|
||||
progressive:
|
||||
name: "Progressive Validation"
|
||||
description: "Validate completed fields immediately, others on submit"
|
||||
good_for: "Balance between guidance and interruption"
|
||||
timing: "Hybrid approach"
|
||||
|
||||
modal_patterns:
|
||||
sizes:
|
||||
small:
|
||||
width: "400-500px"
|
||||
usage: "Confirmations, simple alerts, single-field inputs"
|
||||
|
||||
medium:
|
||||
width: "600-800px"
|
||||
usage: "Forms, detailed content, most common use case"
|
||||
|
||||
large:
|
||||
width: "900-1200px"
|
||||
usage: "Complex forms, content preview, rich media"
|
||||
|
||||
fullscreen:
|
||||
width: "100% viewport"
|
||||
usage: "Mobile primarily, immersive experiences"
|
||||
|
||||
dismiss_behavior:
|
||||
click_outside:
|
||||
description: "Click backdrop to close"
|
||||
good_for: "Non-critical modals, user-initiated"
|
||||
not_ideal_for: "Unsaved changes, critical confirmations"
|
||||
|
||||
escape_key:
|
||||
description: "Press ESC to close"
|
||||
good_for: "All modals (accessibility)"
|
||||
implementation: "Always include for keyboard users"
|
||||
|
||||
explicit_close:
|
||||
description: "Must click X or Cancel button"
|
||||
good_for: "Critical modals, unsaved changes, confirmations"
|
||||
not_ideal_for: "Frequent, non-blocking interactions"
|
||||
|
||||
navigation_patterns:
|
||||
sidebar:
|
||||
name: "Sidebar Navigation"
|
||||
good_for: ["Desktop apps", "Many sections", "Persistent navigation"]
|
||||
not_ideal_for: ["Simple sites", "Few sections", "Mobile-only"]
|
||||
variants:
|
||||
- "Always visible (desktop)"
|
||||
- "Collapsible (hamburger on mobile)"
|
||||
- "Mini sidebar (icons only, expands on hover)"
|
||||
|
||||
top_nav:
|
||||
name: "Top Navigation Bar"
|
||||
good_for: ["Marketing sites", "Few sections", "Mobile-friendly"]
|
||||
not_ideal_for: ["Many menu items", "Deep hierarchies"]
|
||||
variants:
|
||||
- "Horizontal menu"
|
||||
- "Mega menu (dropdown panels)"
|
||||
- "Hamburger menu (mobile)"
|
||||
|
||||
tabs:
|
||||
name: "Tab Navigation"
|
||||
good_for: ["Related content sections", "Switching views", "Settings"]
|
||||
not_ideal_for: ["Unrelated sections", "Too many tabs (>7)"]
|
||||
variants:
|
||||
- "Horizontal tabs"
|
||||
- "Vertical tabs"
|
||||
- "Pill tabs"
|
||||
|
||||
bottom_nav:
|
||||
name: "Bottom Navigation (Mobile)"
|
||||
good_for: ["Mobile apps", "3-5 primary sections", "Quick switching"]
|
||||
not_ideal_for: ["Desktop", "Many sections", "Deep hierarchies"]
|
||||
best_practices: "3-5 items, icon + label, highlight active"
|
||||
|
||||
empty_state_patterns:
|
||||
first_use:
|
||||
description: "User's first time, no content yet"
|
||||
components:
|
||||
- "Illustration or icon"
|
||||
- "Welcoming message"
|
||||
- "Clear call-to-action (create first item)"
|
||||
- "Optional: Tutorial or guide link"
|
||||
|
||||
no_results:
|
||||
description: "Search or filter returned nothing"
|
||||
components:
|
||||
- "Clear message (No results found for 'X')"
|
||||
- "Suggestions (check spelling, try different keywords)"
|
||||
- "Alternative action (clear filters, browse all)"
|
||||
|
||||
cleared_content:
|
||||
description: "User deleted/cleared content"
|
||||
components:
|
||||
- "Acknowledgment (Content cleared)"
|
||||
- "Undo option (if possible)"
|
||||
- "Action to create new content"
|
||||
|
||||
confirmation_patterns:
|
||||
no_confirmation:
|
||||
description: "No confirmation dialog, immediate action with undo"
|
||||
good_for: "Low-risk actions, undo available"
|
||||
example: "Archive email (with undo toast)"
|
||||
|
||||
simple_confirmation:
|
||||
description: "Single confirmation dialog"
|
||||
good_for: "Moderate-risk actions"
|
||||
example: "Delete item? [Cancel] [Delete]"
|
||||
|
||||
typed_confirmation:
|
||||
description: "User must type specific text to confirm"
|
||||
good_for: "High-risk, irreversible actions"
|
||||
example: "Type 'DELETE' to confirm account deletion"
|
||||
|
||||
multi_step_confirmation:
|
||||
description: "Multiple confirmations or checkboxes"
|
||||
good_for: "Critical, irreversible, high-impact actions"
|
||||
example: "Delete account: check consequences, type confirmation, verify email"
|
||||
|
||||
loading_patterns:
|
||||
spinner:
|
||||
name: "Spinner/Circular Progress"
|
||||
good_for: ["Unknown duration", "Small areas", "Button states"]
|
||||
usage: "Indeterminate progress"
|
||||
|
||||
progress_bar:
|
||||
name: "Linear Progress Bar"
|
||||
good_for: ["Known duration", "File uploads", "Multi-step processes"]
|
||||
usage: "Determinate progress (0-100%)"
|
||||
|
||||
skeleton_screen:
|
||||
name: "Skeleton/Placeholder"
|
||||
good_for: ["Content loading", "Better perceived performance", "Layout stability"]
|
||||
usage: "Show content structure while loading"
|
||||
|
||||
optimistic_ui:
|
||||
name: "Optimistic Update"
|
||||
good_for: ["Instant feedback", "High success rate actions", "Smooth UX"]
|
||||
usage: "Show result immediately, rollback if fails"
|
||||
|
||||
responsive_breakpoints:
|
||||
mobile_first:
|
||||
sm: "640px (small phones)"
|
||||
md: "768px (tablets portrait)"
|
||||
lg: "1024px (tablets landscape, small desktops)"
|
||||
xl: "1280px (desktops)"
|
||||
xxl: "1536px (large desktops)"
|
||||
|
||||
common_devices:
|
||||
mobile: "320px - 767px"
|
||||
tablet: "768px - 1023px"
|
||||
desktop: "1024px+"
|
||||
|
||||
interaction_patterns:
|
||||
drag_and_drop:
|
||||
good_for: ["Reordering lists", "File uploads", "Visual organization"]
|
||||
not_ideal_for: ["Mobile (touch conflicts)", "Accessibility (needs fallback)"]
|
||||
accessibility: "Must provide keyboard alternative"
|
||||
|
||||
swipe_gestures:
|
||||
good_for: ["Mobile navigation", "Quick actions (swipe to delete)", "Cards"]
|
||||
not_ideal_for: ["Desktop", "Ambiguous actions"]
|
||||
best_practices: "Visual feedback, undo option"
|
||||
|
||||
infinite_scroll:
|
||||
good_for: ["Social feeds", "Discovery", "Engagement"]
|
||||
not_ideal_for: ["Finding specific items", "Footer access", "Performance"]
|
||||
best_practices: "Load more button as fallback, preserve scroll position"
|
||||
|
||||
pagination:
|
||||
good_for: ["Data tables", "Search results", "Performance", "Findability"]
|
||||
not_ideal_for: ["Social feeds", "Real-time content"]
|
||||
variants: ["Numbered pages", "Previous/Next", "Load More button"]
|
||||
|
||||
animation_guidelines:
|
||||
duration:
|
||||
micro: "50-100ms (button hover, checkbox toggle)"
|
||||
small: "150-250ms (dropdown open, tooltip appear)"
|
||||
medium: "250-400ms (modal open, drawer slide)"
|
||||
large: "400-600ms (page transitions, complex animations)"
|
||||
|
||||
easing:
|
||||
ease_out: "Decelerates (entering animations)"
|
||||
ease_in: "Accelerates (exiting animations)"
|
||||
ease_in_out: "Both (moving between states)"
|
||||
linear: "Constant speed (loading spinners)"
|
||||
|
||||
principles:
|
||||
- "Animations should feel natural, not robotic"
|
||||
- "Use for feedback, transitions, and delight"
|
||||
- "Don't slow down user tasks"
|
||||
- "Respect prefers-reduced-motion"
|
||||
- "60fps (under 16ms per frame)"
|
||||
|
||||
accessibility_patterns:
|
||||
keyboard_navigation:
|
||||
tab_order: "Logical, top-to-bottom, left-to-right"
|
||||
skip_links: "Skip to main content"
|
||||
focus_trapping: "Modal keeps focus inside"
|
||||
escape_key: "Close modals, cancel actions"
|
||||
|
||||
screen_readers:
|
||||
landmarks: "header, nav, main, aside, footer"
|
||||
headings: "h1-h6 hierarchy (don't skip levels)"
|
||||
aria_labels: "Descriptive labels for icon buttons"
|
||||
live_regions: "Announce dynamic content changes"
|
||||
|
||||
color_contrast:
|
||||
wcag_aa:
|
||||
normal_text: "4.5:1 contrast ratio"
|
||||
large_text: "3:1 contrast ratio (18pt+ or 14pt+ bold)"
|
||||
ui_components: "3:1 contrast ratio"
|
||||
|
||||
wcag_aaa:
|
||||
normal_text: "7:1 contrast ratio"
|
||||
large_text: "4.5:1 contrast ratio"
|
||||
|
||||
# Novel UX Pattern Examples (for inspiration)
|
||||
novel_patterns_inspiration:
|
||||
- pattern: "Swipe to match"
|
||||
origin: "Tinder"
|
||||
innovation: "Gamified decision-making through gesture"
|
||||
|
||||
- pattern: "Stories (ephemeral content)"
|
||||
origin: "Snapchat, then Instagram"
|
||||
innovation: "Time-limited content creates urgency and authenticity"
|
||||
|
||||
- pattern: "Infinite canvas"
|
||||
origin: "Figma, Miro"
|
||||
innovation: "Spatial organization without page boundaries"
|
||||
|
||||
- pattern: "Real-time collaborative cursors"
|
||||
origin: "Figma, Google Docs"
|
||||
innovation: "See others' activity in real-time"
|
||||
|
||||
- pattern: "Pull to refresh"
|
||||
origin: "Tweetie (Twitter client)"
|
||||
innovation: "Natural gesture for content updates"
|
||||
|
||||
- pattern: "Card-based swiping"
|
||||
origin: "Tinder, then widely adopted"
|
||||
innovation: "Binary decisions through kinetic interaction"
|
||||
|
||||
- pattern: "Algorithmic feed"
|
||||
origin: "Facebook, TikTok"
|
||||
innovation: "Personalized infinite content discovery"
|
||||
|
|
@ -1,152 +0,0 @@
|
|||
# UX/UI Specification Workflow Validation Checklist
|
||||
|
||||
**Purpose**: Validate UX workflow outputs are complete, actionable, and ready for development.
|
||||
|
||||
**Scope**: Can run standalone or integrated with PRD/GDD workflows
|
||||
|
||||
**Expected Outputs**: ux-specification.md, optional ai-frontend-prompt.md
|
||||
|
||||
---
|
||||
|
||||
## 1. Output File Exists
|
||||
|
||||
- [ ] ux-specification.md created in output folder
|
||||
- [ ] Requirements source identified (PRD, GDD, or gathered requirements)
|
||||
- [ ] No unfilled {{template_variables}}
|
||||
|
||||
---
|
||||
|
||||
## 2. UX Foundation
|
||||
|
||||
### User Personas
|
||||
|
||||
- [ ] **At least one primary persona** defined with goals and pain points
|
||||
- [ ] Personas have sufficient detail to inform design decisions
|
||||
- [ ] If PRD/GDD exists, personas align with target audience
|
||||
|
||||
### Design Principles
|
||||
|
||||
- [ ] **3-5 core design principles** established
|
||||
- [ ] Principles are actionable (guide real design decisions)
|
||||
- [ ] Principles fit project goals and users
|
||||
|
||||
---
|
||||
|
||||
## 3. Information Architecture
|
||||
|
||||
### Site/App Structure
|
||||
|
||||
- [ ] **Complete site map** showing all major sections/screens
|
||||
- [ ] Hierarchical relationships clear
|
||||
- [ ] Navigation paths evident
|
||||
- [ ] Structure makes sense for users
|
||||
|
||||
### Navigation
|
||||
|
||||
- [ ] Primary navigation defined
|
||||
- [ ] Mobile navigation strategy clear (if multi-platform)
|
||||
- [ ] Navigation approach logical
|
||||
|
||||
---
|
||||
|
||||
## 4. User Flows
|
||||
|
||||
- [ ] **At least 2-3 critical user flows** documented
|
||||
- [ ] Flows show complete start-to-finish paths
|
||||
- [ ] Decision points and error states considered
|
||||
- [ ] Flows include Mermaid diagrams or clear descriptions
|
||||
- [ ] If PRD exists, flows align with user journeys
|
||||
|
||||
---
|
||||
|
||||
## 5. Component Library and Visual Design
|
||||
|
||||
### Component Approach
|
||||
|
||||
- [ ] **Design system strategy** defined (existing system, custom, or hybrid)
|
||||
- [ ] If using existing, which one specified
|
||||
- [ ] Core components identified
|
||||
- [ ] Component states documented (default, hover, active, disabled, error)
|
||||
|
||||
### Visual Foundation
|
||||
|
||||
- [ ] **Color palette** defined with semantic meanings
|
||||
- [ ] **Typography** specified (fonts, type scale, usage)
|
||||
- [ ] **Spacing system** documented
|
||||
- [ ] Design choices support usability
|
||||
|
||||
---
|
||||
|
||||
## 6. Responsive and Accessibility
|
||||
|
||||
### Responsive Design
|
||||
|
||||
- [ ] **Breakpoints defined** for target devices
|
||||
- [ ] Adaptation patterns explained (how layouts change)
|
||||
- [ ] Mobile strategy clear (if multi-platform)
|
||||
|
||||
### Accessibility
|
||||
|
||||
- [ ] **Compliance target** specified (WCAG level)
|
||||
- [ ] Key accessibility requirements documented
|
||||
- [ ] Keyboard navigation, screen readers, contrast considered
|
||||
|
||||
---
|
||||
|
||||
## 7. Implementation Readiness
|
||||
|
||||
- [ ] **Next steps** clearly defined
|
||||
- [ ] Design handoff requirements clear
|
||||
- [ ] Developers can implement from this spec
|
||||
- [ ] Sufficient detail for front-end development
|
||||
|
||||
---
|
||||
|
||||
## 8. Integration with Requirements
|
||||
|
||||
**If PRD/GDD exists:**
|
||||
|
||||
- [ ] UX covers all user-facing features from requirements
|
||||
- [ ] User flows align with documented user journeys
|
||||
- [ ] Platform matches PRD/GDD platforms
|
||||
- [ ] No contradictions with requirements
|
||||
|
||||
---
|
||||
|
||||
## 9. AI Frontend Prompt (If Generated)
|
||||
|
||||
**If ai-frontend-prompt.md was created:**
|
||||
|
||||
- [ ] File exists in output folder
|
||||
- [ ] Contains complete UX context (colors, typography, components, flows)
|
||||
- [ ] Formatted for AI tools (v0, Lovable, etc.)
|
||||
- [ ] Includes appropriate warnings about reviewing generated code
|
||||
|
||||
---
|
||||
|
||||
## 10. Critical Failures (Auto-Fail)
|
||||
|
||||
- [ ] ❌ **No user personas** (target users not defined)
|
||||
- [ ] ❌ **No user flows** (critical paths not documented)
|
||||
- [ ] ❌ **No information architecture** (site structure missing)
|
||||
- [ ] ❌ **No component approach** (design system not defined)
|
||||
- [ ] ❌ **No visual foundation** (colors/typography missing)
|
||||
- [ ] ❌ **No responsive strategy** (adaptation not addressed for multi-platform)
|
||||
- [ ] ❌ **Contradicts requirements** (UX fights PRD/GDD if they exist)
|
||||
|
||||
---
|
||||
|
||||
## Validation Notes
|
||||
|
||||
**Document any findings:**
|
||||
|
||||
- UX quality: [Production-ready / Good foundation / Needs refinement / Incomplete]
|
||||
- Strengths:
|
||||
- Issues to address:
|
||||
- Recommended actions:
|
||||
|
||||
**Ready for development?** [Yes / Needs design phase / No - explain]
|
||||
|
||||
---
|
||||
|
||||
_Adapt based on whether this is standalone or integrated, and platform requirements._
|
||||
|
|
@ -1,405 +0,0 @@
|
|||
# UX/UI Specification Workflow Instructions
|
||||
|
||||
<workflow>
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
<critical>This workflow creates comprehensive UX/UI specifications - can run standalone or as part of plan-project</critical>
|
||||
<critical>Uses ux-spec-template.md for structured output generation</critical>
|
||||
<critical>Can optionally generate AI Frontend Prompts for tools like Vercel v0, Lovable.ai</critical>
|
||||
|
||||
<critical>DOCUMENT OUTPUT: Professional, precise, actionable UX specs. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
|
||||
|
||||
<step n="0" goal="Check for workflow status">
|
||||
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: init-check</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="status_exists == true">
|
||||
<action>Store {{status_file_path}} for later updates</action>
|
||||
<action>Set tracking_mode = true</action>
|
||||
</check>
|
||||
|
||||
<check if="status_exists == false">
|
||||
<action>Set tracking_mode = false</action>
|
||||
<output>Note: Running without workflow tracking. Run `workflow-init` to enable progress tracking.</output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Load context and analyze project requirements">
|
||||
|
||||
<action>Determine workflow mode (standalone or integrated)</action>
|
||||
|
||||
<check if="mode is standalone">
|
||||
<ask>Do you have an existing PRD or requirements document? (y/n)
|
||||
|
||||
If yes: Provide the path to the PRD
|
||||
If no: We'll gather basic requirements to create the UX spec
|
||||
</ask>
|
||||
</check>
|
||||
|
||||
<check if="no PRD in standalone mode">
|
||||
<ask>Let's gather essential information:
|
||||
|
||||
1. **Project Description**: What are you building?
|
||||
2. **Target Users**: Who will use this?
|
||||
3. **Core Features**: What are the main capabilities? (3-5 key features)
|
||||
4. **Platform**: Web, mobile, desktop, or multi-platform?
|
||||
5. **Existing Brand/Design**: Any existing style guide or brand to follow?
|
||||
</ask>
|
||||
</check>
|
||||
|
||||
<check if="PRD exists or integrated mode">
|
||||
<action>Load the following documents if available:</action>
|
||||
|
||||
- PRD.md (primary source for requirements and user journeys)
|
||||
- epics.md (helps understand feature grouping)
|
||||
- tech-spec.md (understand technical constraints)
|
||||
- architecture.md (if Level 3-4 project)
|
||||
- bmm-workflow-status.md (understand project level and scope)
|
||||
|
||||
</check>
|
||||
|
||||
<action>Analyze project for UX complexity:</action>
|
||||
|
||||
- Number of user-facing features
|
||||
- Types of users/personas mentioned
|
||||
- Interaction complexity
|
||||
- Platform requirements (web, mobile, desktop)
|
||||
|
||||
<action>Load ux-spec-template from workflow.yaml</action>
|
||||
|
||||
<template-output>project_context</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Define UX goals and principles">
|
||||
|
||||
<ask>Let's establish the UX foundation. Based on the PRD:
|
||||
|
||||
**1. Target User Personas** (extract from PRD or define):
|
||||
|
||||
- Primary persona(s)
|
||||
- Secondary persona(s)
|
||||
- Their goals and pain points
|
||||
|
||||
**2. Key Usability Goals:**
|
||||
What does success look like for users?
|
||||
|
||||
- Ease of learning?
|
||||
- Efficiency for power users?
|
||||
- Error prevention?
|
||||
- Accessibility requirements?
|
||||
|
||||
**3. Core Design Principles** (3-5 principles):
|
||||
What will guide all design decisions?
|
||||
</ask>
|
||||
|
||||
<template-output>user_personas</template-output>
|
||||
<template-output>usability_goals</template-output>
|
||||
<template-output>design_principles</template-output>
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Create information architecture">
|
||||
|
||||
<action>Based on functional requirements from PRD, create site/app structure</action>
|
||||
|
||||
**Create comprehensive site map showing:**
|
||||
|
||||
- All major sections/screens
|
||||
- Hierarchical relationships
|
||||
- Navigation paths
|
||||
|
||||
<template-output>site_map</template-output>
|
||||
|
||||
**Define navigation structure:**
|
||||
|
||||
- Primary navigation items
|
||||
- Secondary navigation approach
|
||||
- Mobile navigation strategy
|
||||
- Breadcrumb structure
|
||||
|
||||
<template-output>navigation_structure</template-output>
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Design user flows for critical paths">
|
||||
|
||||
<action>Extract key user journeys from PRD</action>
|
||||
<action>For each critical user task, create detailed flow</action>
|
||||
|
||||
<for-each journey="user_journeys_from_prd">
|
||||
|
||||
**Flow: {{journey_name}}**
|
||||
|
||||
Define:
|
||||
|
||||
- User goal
|
||||
- Entry points
|
||||
- Step-by-step flow with decision points
|
||||
- Success criteria
|
||||
- Error states and edge cases
|
||||
|
||||
Create Mermaid diagram showing complete flow.
|
||||
|
||||
<template-output>user*flow*{{journey_number}}</template-output>
|
||||
|
||||
</for-each>
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Define component library approach">
|
||||
|
||||
<ask>Component Library Strategy:
|
||||
|
||||
**1. Design System Approach:**
|
||||
|
||||
- [ ] Use existing system (Material UI, Ant Design, etc.)
|
||||
- [ ] Create custom component library
|
||||
- [ ] Hybrid approach
|
||||
|
||||
**2. If using existing, which one?**
|
||||
|
||||
**3. Core Components Needed** (based on PRD features):
|
||||
We'll need to define states and variants for key components.
|
||||
</ask>
|
||||
|
||||
<action>For primary components, define:</action>
|
||||
|
||||
- Component purpose
|
||||
- Variants needed
|
||||
- States (default, hover, active, disabled, error)
|
||||
- Usage guidelines
|
||||
|
||||
<template-output>design_system_approach</template-output>
|
||||
<template-output>core_components</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Establish visual design foundation">
|
||||
|
||||
<ask>Visual Design Foundation:
|
||||
|
||||
**1. Brand Guidelines:**
|
||||
Do you have existing brand guidelines to follow? (y/n)
|
||||
|
||||
**2. If yes, provide link or key elements.**
|
||||
|
||||
**3. If no, let's define basics:**
|
||||
|
||||
- Primary brand personality (professional, playful, minimal, bold)
|
||||
- Industry conventions to follow or break
|
||||
</ask>
|
||||
|
||||
<action>Define color palette with semantic meanings</action>
|
||||
|
||||
<template-output>color_palette</template-output>
|
||||
|
||||
<action>Define typography system</action>
|
||||
|
||||
<template-output>font_families</template-output>
|
||||
<template-output>type_scale</template-output>
|
||||
|
||||
<action>Define spacing and layout grid</action>
|
||||
|
||||
<template-output>spacing_layout</template-output>
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Define responsive and accessibility strategy">
|
||||
|
||||
**Responsive Design:**
|
||||
|
||||
<action>Define breakpoints based on target devices from PRD</action>
|
||||
|
||||
<template-output>breakpoints</template-output>
|
||||
|
||||
<action>Define adaptation patterns for different screen sizes</action>
|
||||
|
||||
<template-output>adaptation_patterns</template-output>
|
||||
|
||||
**Accessibility Requirements:**
|
||||
|
||||
<action>Based on deployment intent from PRD, define compliance level</action>
|
||||
|
||||
<template-output>compliance_target</template-output>
|
||||
<template-output>accessibility_requirements</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Document interaction patterns" optional="true">
|
||||
|
||||
<ask>Would you like to define animation and micro-interactions? (y/n)
|
||||
|
||||
This is recommended for:
|
||||
|
||||
- Consumer-facing applications
|
||||
- Projects emphasizing user delight
|
||||
- Complex state transitions
|
||||
</ask>
|
||||
|
||||
<check if="yes or fuzzy match the user wants to define animation or micro interactions">
|
||||
|
||||
<action>Define motion principles</action>
|
||||
<template-output>motion_principles</template-output>
|
||||
|
||||
<action>Define key animations and transitions</action>
|
||||
<template-output>key_animations</template-output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Create wireframes and design references" optional="true">
|
||||
|
||||
<ask>Design File Strategy:
|
||||
|
||||
**1. Will you be creating high-fidelity designs?**
|
||||
|
||||
- Yes, in Figma
|
||||
- Yes, in Sketch
|
||||
- Yes, in Adobe XD
|
||||
- No, development from spec
|
||||
- Other (describe)
|
||||
|
||||
**2. For key screens, should we:**
|
||||
|
||||
- Reference design file locations
|
||||
- Create low-fi wireframe descriptions
|
||||
- Skip visual representations
|
||||
</ask>
|
||||
|
||||
<template-output if="design files will be created">design_files</template-output>
|
||||
|
||||
<check if="wireframe descriptions needed">
|
||||
<for-each screen="key_screens">
|
||||
<template-output>screen*layout*{{screen_number}}</template-output>
|
||||
</for-each>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Generate next steps and output options">
|
||||
|
||||
## UX Specification Complete
|
||||
|
||||
<action>Generate specific next steps based on project level and outputs</action>
|
||||
|
||||
<template-output>immediate_actions</template-output>
|
||||
|
||||
**Design Handoff Checklist:**
|
||||
|
||||
- [ ] All user flows documented
|
||||
- [ ] Component inventory complete
|
||||
- [ ] Accessibility requirements defined
|
||||
- [ ] Responsive strategy clear
|
||||
- [ ] Brand guidelines incorporated
|
||||
- [ ] Performance goals established
|
||||
|
||||
<check if="Level 3-4 project">
|
||||
- [ ] Ready for detailed visual design
|
||||
- [ ] Frontend architecture can proceed
|
||||
- [ ] Story generation can include UX details
|
||||
</check>
|
||||
|
||||
<check if="Level 1-2 project or standalone">
|
||||
- [ ] Development can proceed with spec
|
||||
- [ ] Component implementation order defined
|
||||
- [ ] MVP scope clear
|
||||
|
||||
</check>
|
||||
|
||||
<template-output>design_handoff_checklist</template-output>
|
||||
|
||||
<ask>**✅ UX Specification Complete, {user_name}!**
|
||||
|
||||
UX Specification saved to {{ux_spec_file}}
|
||||
|
||||
**Additional Output Options:**
|
||||
|
||||
1. Generate AI Frontend Prompt (for Vercel v0, Lovable.ai, etc.)
|
||||
2. Review UX specification
|
||||
3. Create/update visual designs in design tool
|
||||
4. Return to planning workflow (if not standalone)
|
||||
5. Exit
|
||||
|
||||
Would you like to generate an AI Frontend Prompt? (y/n):</ask>
|
||||
|
||||
<check if="user selects yes or option 1">
|
||||
<goto step="11">Generate AI Frontend Prompt</goto>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="11" goal="Generate AI Frontend Prompt" optional="true">
|
||||
|
||||
<action>Prepare context for AI Frontend Prompt generation</action>
|
||||
|
||||
<ask>What type of AI frontend generation are you targeting?
|
||||
|
||||
1. **Full application** - Complete multi-page application
|
||||
2. **Single page** - One complete page/screen
|
||||
3. **Component set** - Specific components or sections
|
||||
4. **Design system** - Component library setup
|
||||
|
||||
Select option (1-4):</ask>
|
||||
|
||||
<action>Gather UX spec details for prompt generation:</action>
|
||||
|
||||
- Design system approach
|
||||
- Color palette and typography
|
||||
- Key components and their states
|
||||
- User flows to implement
|
||||
- Responsive requirements
|
||||
|
||||
<invoke-task>{project-root}/bmad/bmm/tasks/ai-fe-prompt.md</invoke-task>
|
||||
|
||||
<action>Save AI Frontend Prompt to {{ai_frontend_prompt_file}}</action>
|
||||
|
||||
<ask>AI Frontend Prompt saved to {{ai_frontend_prompt_file}}
|
||||
|
||||
This prompt is optimized for:
|
||||
|
||||
- Vercel v0
|
||||
- Lovable.ai
|
||||
- Other AI frontend generation tools
|
||||
|
||||
**Remember**: AI-generated code requires careful review and testing!
|
||||
|
||||
Next actions:
|
||||
|
||||
1. Copy prompt to AI tool
|
||||
2. Return to UX specification
|
||||
3. Exit workflow
|
||||
|
||||
Select option (1-3):</ask>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="12" goal="Update status if tracking enabled">
|
||||
|
||||
<check if="tracking_mode == true">
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: update</param>
|
||||
<param>action: complete_workflow</param>
|
||||
<param>workflow_name: ux</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="success == true">
|
||||
<output>✅ Status updated! Next: {{next_workflow}}</output>
|
||||
</check>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
|
|
@ -1,162 +0,0 @@
|
|||
# {{project_name}} UX/UI Specification
|
||||
|
||||
_Generated on {{date}} by {{user_name}}_
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{project_context}}
|
||||
|
||||
---
|
||||
|
||||
## 1. UX Goals and Principles
|
||||
|
||||
### 1.1 Target User Personas
|
||||
|
||||
{{user_personas}}
|
||||
|
||||
### 1.2 Usability Goals
|
||||
|
||||
{{usability_goals}}
|
||||
|
||||
### 1.3 Design Principles
|
||||
|
||||
{{design_principles}}
|
||||
|
||||
---
|
||||
|
||||
## 2. Information Architecture
|
||||
|
||||
### 2.1 Site Map
|
||||
|
||||
{{site_map}}
|
||||
|
||||
### 2.2 Navigation Structure
|
||||
|
||||
{{navigation_structure}}
|
||||
|
||||
---
|
||||
|
||||
## 3. User Flows
|
||||
|
||||
{{user_flow_1}}
|
||||
|
||||
{{user_flow_2}}
|
||||
|
||||
{{user_flow_3}}
|
||||
|
||||
{{user_flow_4}}
|
||||
|
||||
{{user_flow_5}}
|
||||
|
||||
---
|
||||
|
||||
## 4. Component Library and Design System
|
||||
|
||||
### 4.1 Design System Approach
|
||||
|
||||
{{design_system_approach}}
|
||||
|
||||
### 4.2 Core Components
|
||||
|
||||
{{core_components}}
|
||||
|
||||
---
|
||||
|
||||
## 5. Visual Design Foundation
|
||||
|
||||
### 5.1 Color Palette
|
||||
|
||||
{{color_palette}}
|
||||
|
||||
### 5.2 Typography
|
||||
|
||||
**Font Families:**
|
||||
{{font_families}}
|
||||
|
||||
**Type Scale:**
|
||||
{{type_scale}}
|
||||
|
||||
### 5.3 Spacing and Layout
|
||||
|
||||
{{spacing_layout}}
|
||||
|
||||
---
|
||||
|
||||
## 6. Responsive Design
|
||||
|
||||
### 6.1 Breakpoints
|
||||
|
||||
{{breakpoints}}
|
||||
|
||||
### 6.2 Adaptation Patterns
|
||||
|
||||
{{adaptation_patterns}}
|
||||
|
||||
---
|
||||
|
||||
## 7. Accessibility
|
||||
|
||||
### 7.1 Compliance Target
|
||||
|
||||
{{compliance_target}}
|
||||
|
||||
### 7.2 Key Requirements
|
||||
|
||||
{{accessibility_requirements}}
|
||||
|
||||
---
|
||||
|
||||
## 8. Interaction and Motion
|
||||
|
||||
### 8.1 Motion Principles
|
||||
|
||||
{{motion_principles}}
|
||||
|
||||
### 8.2 Key Animations
|
||||
|
||||
{{key_animations}}
|
||||
|
||||
---
|
||||
|
||||
## 9. Design Files and Wireframes
|
||||
|
||||
### 9.1 Design Files
|
||||
|
||||
{{design_files}}
|
||||
|
||||
### 9.2 Key Screen Layouts
|
||||
|
||||
{{screen_layout_1}}
|
||||
|
||||
{{screen_layout_2}}
|
||||
|
||||
{{screen_layout_3}}
|
||||
|
||||
---
|
||||
|
||||
## 10. Next Steps
|
||||
|
||||
### 10.1 Immediate Actions
|
||||
|
||||
{{immediate_actions}}
|
||||
|
||||
### 10.2 Design Handoff Checklist
|
||||
|
||||
{{design_handoff_checklist}}
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### Related Documents
|
||||
|
||||
- PRD: `{{prd}}`
|
||||
- Epics: `{{epics}}`
|
||||
- Tech Spec: `{{tech_spec}}`
|
||||
- Architecture: `{{architecture}}`
|
||||
|
||||
### Version History
|
||||
|
||||
| Date | Version | Changes | Author |
|
||||
| -------- | ------- | --------------------- | ------------- |
|
||||
| {{date}} | 1.0 | Initial specification | {{user_name}} |
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
# UX/UI Specification Workflow
|
||||
name: ux-spec
|
||||
description: "UX/UI specification workflow for defining user experience and interface design. Creates comprehensive UX documentation including wireframes, user flows, component specifications, and design system guidelines."
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
date: system-generated
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/ux-spec"
|
||||
instructions: "{installed_path}/instructions-ux.md"
|
||||
template: "{installed_path}/ux-spec-template.md"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/ux-specification.md"
|
||||
ai_frontend_prompt_file: "{output_folder}/ai-frontend-prompt.md"
|
||||
|
||||
# Recommended input documents
|
||||
recommended_inputs:
|
||||
- prd: "{output_folder}/PRD.md"
|
||||
- product_brief: "{output_folder}/product-brief.md"
|
||||
- gdd: "{output_folder}/GDD.md"
|
||||
|
||||
web_bundle:
|
||||
name: "ux-spec"
|
||||
description: "UX/UI specification workflow for defining user experience and interface design. Creates comprehensive UX documentation including wireframes, user flows, component specifications, and design system guidelines."
|
||||
author: "BMad"
|
||||
instructions: "bmad/bmm/workflows/2-plan-workflows/ux-spec/instructions-ux.md"
|
||||
web_bundle_files:
|
||||
- "bmad/bmm/workflows/2-plan-workflows/ux-spec/instructions-ux.md"
|
||||
- "bmad/bmm/workflows/2-plan-workflows/ux-spec/ux-spec-template.md"
|
||||
|
|
@ -1,49 +1,67 @@
|
|||
# Decision Architecture Validation Checklist
|
||||
# Architecture Document Validation Checklist
|
||||
|
||||
## Critical Requirements (MUST PASS)
|
||||
**Purpose**: Validate the architecture document itself is complete, implementable, and provides clear guidance for AI agents.
|
||||
|
||||
### Decision Completeness
|
||||
**Note**: This checklist validates the ARCHITECTURE DOCUMENT only. For cross-workflow validation (PRD → Architecture → Stories alignment), use the solutioning-gate-check workflow.
|
||||
|
||||
- [ ] Every functional requirement from PRD has architectural support
|
||||
- [ ] Every non-functional requirement from PRD is addressed
|
||||
- [ ] All critical decision categories have been resolved
|
||||
---
|
||||
|
||||
## 1. Decision Completeness
|
||||
|
||||
### All Decisions Made
|
||||
|
||||
- [ ] Every critical decision category has been resolved
|
||||
- [ ] All important decision categories addressed
|
||||
- [ ] No placeholder text like "TBD", "[choose]", or "{TODO}" remains
|
||||
- [ ] Optional decisions either resolved or explicitly deferred with rationale
|
||||
|
||||
### Version Specificity
|
||||
### Decision Coverage
|
||||
|
||||
- [ ] Data persistence approach decided
|
||||
- [ ] API pattern chosen
|
||||
- [ ] Authentication/authorization strategy defined
|
||||
- [ ] Deployment target selected
|
||||
- [ ] All functional requirements have architectural support
|
||||
|
||||
---
|
||||
|
||||
## 2. Version Specificity
|
||||
|
||||
### Technology Versions
|
||||
|
||||
- [ ] Every technology choice includes a specific version number
|
||||
- [ ] Version numbers are current (verified via WebSearch, not hardcoded)
|
||||
- [ ] Compatible versions selected (e.g., Node.js version supports chosen packages)
|
||||
- [ ] Verification dates noted for version checks
|
||||
|
||||
### Starter Template Integration (if applicable)
|
||||
### Version Verification Process
|
||||
|
||||
- [ ] WebSearch used during workflow to verify current versions
|
||||
- [ ] No hardcoded versions from decision catalog trusted without verification
|
||||
- [ ] LTS vs. latest versions considered and documented
|
||||
- [ ] Breaking changes between versions noted if relevant
|
||||
|
||||
---
|
||||
|
||||
## 3. Starter Template Integration (if applicable)
|
||||
|
||||
### Template Selection
|
||||
|
||||
- [ ] Starter template chosen (or "from scratch" decision documented)
|
||||
- [ ] Project initialization command documented with exact flags
|
||||
- [ ] Starter-provided decisions marked as "PROVIDED BY STARTER"
|
||||
- [ ] First implementation story references starter initialization
|
||||
- [ ] Starter template version is current and specified
|
||||
- [ ] Command search term provided for verification
|
||||
|
||||
### Epic Coverage
|
||||
### Starter-Provided Decisions
|
||||
|
||||
- [ ] Every epic from PRD is explicitly mapped to architectural components
|
||||
- [ ] Decision summary table shows which epics each decision affects
|
||||
- [ ] No orphan epics without architectural support
|
||||
- [ ] Novel patterns mapped to affected epics
|
||||
- [ ] Decisions provided by starter marked as "PROVIDED BY STARTER"
|
||||
- [ ] List of what starter provides is complete
|
||||
- [ ] Remaining decisions (not covered by starter) clearly identified
|
||||
- [ ] No duplicate decisions that starter already makes
|
||||
|
||||
### Document Structure
|
||||
---
|
||||
|
||||
- [ ] Executive summary is present and concise (2-3 sentences maximum)
|
||||
- [ ] Project initialization section present (if using starter template)
|
||||
- [ ] Decision summary table has ALL required columns:
|
||||
- Category
|
||||
- Decision
|
||||
- Version
|
||||
- Affects Epics
|
||||
- Rationale
|
||||
- [ ] Project structure section shows complete source tree
|
||||
- [ ] Source tree reflects actual technology decisions (not generic)
|
||||
|
||||
## Novel Pattern Design (if applicable)
|
||||
## 4. Novel Pattern Design (if applicable)
|
||||
|
||||
### Pattern Detection
|
||||
|
||||
|
|
@ -51,16 +69,25 @@
|
|||
- [ ] Patterns that don't have standard solutions documented
|
||||
- [ ] Multi-epic workflows requiring custom design captured
|
||||
|
||||
### Pattern Documentation
|
||||
### Pattern Documentation Quality
|
||||
|
||||
- [ ] Pattern name and purpose clearly defined
|
||||
- [ ] Component interactions specified
|
||||
- [ ] Data flow documented (with sequence diagrams if complex)
|
||||
- [ ] Implementation guide provided for agents
|
||||
- [ ] Affected epics listed
|
||||
- [ ] Edge cases and failure modes considered
|
||||
- [ ] States and transitions clearly defined
|
||||
|
||||
## Implementation Patterns
|
||||
### Pattern Implementability
|
||||
|
||||
- [ ] Pattern is implementable by AI agents with provided guidance
|
||||
- [ ] No ambiguous decisions that could be interpreted differently
|
||||
- [ ] Clear boundaries between components
|
||||
- [ ] Explicit integration points with standard patterns
|
||||
|
||||
---
|
||||
|
||||
## 5. Implementation Patterns
|
||||
|
||||
### Pattern Categories Coverage
|
||||
|
||||
|
|
@ -78,10 +105,13 @@
|
|||
- [ ] Conventions are unambiguous (agents can't interpret differently)
|
||||
- [ ] Patterns cover all technologies in the stack
|
||||
- [ ] No gaps where agents would have to guess
|
||||
- [ ] Implementation patterns don't conflict with each other
|
||||
|
||||
## Consistency Validation
|
||||
---
|
||||
|
||||
### Technology Compatibility
|
||||
## 6. Technology Compatibility
|
||||
|
||||
### Stack Coherence
|
||||
|
||||
- [ ] Database choice compatible with ORM choice
|
||||
- [ ] Frontend framework compatible with deployment target
|
||||
|
|
@ -89,31 +119,65 @@
|
|||
- [ ] All API patterns consistent (not mixing REST and GraphQL for same data)
|
||||
- [ ] Starter template compatible with additional choices
|
||||
|
||||
### Pattern Consistency
|
||||
### Integration Compatibility
|
||||
|
||||
- [ ] Single source of truth for each data type
|
||||
- [ ] Consistent error handling approach across components
|
||||
- [ ] Uniform authentication/authorization pattern
|
||||
- [ ] Implementation patterns don't conflict with each other
|
||||
- [ ] Third-party services compatible with chosen stack
|
||||
- [ ] Real-time solutions (if any) work with deployment target
|
||||
- [ ] File storage solution integrates with framework
|
||||
- [ ] Background job system compatible with infrastructure
|
||||
|
||||
### AI Agent Clarity
|
||||
---
|
||||
|
||||
## 7. Document Structure
|
||||
|
||||
### Required Sections Present
|
||||
|
||||
- [ ] Executive summary exists (2-3 sentences maximum)
|
||||
- [ ] Project initialization section (if using starter template)
|
||||
- [ ] Decision summary table with ALL required columns:
|
||||
- Category
|
||||
- Decision
|
||||
- Version
|
||||
- Rationale
|
||||
- [ ] Project structure section shows complete source tree
|
||||
- [ ] Implementation patterns section comprehensive
|
||||
- [ ] Novel patterns section (if applicable)
|
||||
|
||||
### Document Quality
|
||||
|
||||
- [ ] Source tree reflects actual technology decisions (not generic)
|
||||
- [ ] Technical language used consistently
|
||||
- [ ] Tables used instead of prose where appropriate
|
||||
- [ ] No unnecessary explanations or justifications
|
||||
- [ ] Focused on WHAT and HOW, not WHY (rationale is brief)
|
||||
|
||||
---
|
||||
|
||||
## 8. AI Agent Clarity
|
||||
|
||||
### Clear Guidance for Agents
|
||||
|
||||
- [ ] No ambiguous decisions that agents could interpret differently
|
||||
- [ ] Clear boundaries between components/modules
|
||||
- [ ] Explicit file organization patterns
|
||||
- [ ] Defined patterns for common operations (CRUD, auth checks, etc.)
|
||||
- [ ] Novel patterns have clear implementation guidance
|
||||
- [ ] Document provides clear constraints for agents
|
||||
- [ ] No conflicting guidance present
|
||||
|
||||
## Quality Checks
|
||||
### Implementation Readiness
|
||||
|
||||
### Documentation Quality
|
||||
- [ ] Sufficient detail for agents to implement without guessing
|
||||
- [ ] File paths and naming conventions explicit
|
||||
- [ ] Integration points clearly defined
|
||||
- [ ] Error handling patterns specified
|
||||
- [ ] Testing patterns documented
|
||||
|
||||
- [ ] Technical language used consistently
|
||||
- [ ] Tables used instead of prose where appropriate
|
||||
- [ ] No unnecessary explanations or justifications
|
||||
- [ ] Focused on WHAT and HOW, not WHY (rationale is brief)
|
||||
---
|
||||
|
||||
### Practical Implementation
|
||||
## 9. Practical Considerations
|
||||
|
||||
### Technology Viability
|
||||
|
||||
- [ ] Chosen stack has good documentation and community support
|
||||
- [ ] Development environment can be set up with specified versions
|
||||
|
|
@ -121,118 +185,21 @@
|
|||
- [ ] Deployment target supports all chosen technologies
|
||||
- [ ] Starter template (if used) is stable and well-maintained
|
||||
|
||||
### Scalability Considerations
|
||||
### Scalability
|
||||
|
||||
- [ ] Architecture can handle expected user load from PRD
|
||||
- [ ] Architecture can handle expected user load
|
||||
- [ ] Data model supports expected growth
|
||||
- [ ] Caching strategy defined if performance is critical
|
||||
- [ ] Background job processing defined if async work needed
|
||||
- [ ] Novel patterns scalable for production use
|
||||
|
||||
## Completeness by Section
|
||||
---
|
||||
|
||||
### Executive Summary
|
||||
|
||||
- [ ] States what is being built in one sentence
|
||||
- [ ] Identifies primary architectural pattern
|
||||
- [ ] Notes any unique or critical decisions
|
||||
|
||||
### Project Initialization (if using starter)
|
||||
|
||||
- [ ] Exact command with all flags documented
|
||||
- [ ] Lists what the starter provides
|
||||
- [ ] Notes what decisions remain to be made
|
||||
|
||||
### Decision Summary Table
|
||||
|
||||
- [ ] Contains all major technology decisions
|
||||
- [ ] Each row has complete information
|
||||
- [ ] Versions are specific and current
|
||||
- [ ] Rationales are brief but clear
|
||||
- [ ] Epic mapping is specific (epic IDs, not descriptions)
|
||||
- [ ] Starter-provided decisions marked appropriately
|
||||
|
||||
### Project Structure
|
||||
|
||||
- [ ] Shows actual directory structure
|
||||
- [ ] Follows conventions of chosen framework/starter
|
||||
- [ ] Maps epics to directories
|
||||
- [ ] Includes configuration files
|
||||
- [ ] Reflects starter template structure (if applicable)
|
||||
|
||||
### Novel Pattern Designs (if present)
|
||||
|
||||
- [ ] Each pattern fully documented
|
||||
- [ ] Component interactions clear
|
||||
- [ ] Implementation guidance specific
|
||||
- [ ] Integration with standard patterns defined
|
||||
|
||||
### Implementation Patterns
|
||||
|
||||
- [ ] All 7 pattern categories addressed
|
||||
- [ ] Examples provided for each pattern
|
||||
- [ ] No ambiguity in conventions
|
||||
- [ ] Covers all potential agent decision points
|
||||
|
||||
### Integration Points
|
||||
|
||||
- [ ] External service integrations documented
|
||||
- [ ] API contracts or patterns defined
|
||||
- [ ] Authentication flow specified
|
||||
- [ ] Data flow between components clear
|
||||
- [ ] Novel patterns integrated properly
|
||||
|
||||
### Consistency Rules
|
||||
|
||||
- [ ] Naming conventions specified with examples
|
||||
- [ ] Code organization patterns defined
|
||||
- [ ] Error handling approach documented
|
||||
- [ ] Logging strategy defined
|
||||
- [ ] All implementation patterns included
|
||||
|
||||
## Final Validation
|
||||
|
||||
### Ready for Implementation
|
||||
|
||||
- [ ] An AI agent could start implementing any epic with this document
|
||||
- [ ] First story can initialize project (if using starter)
|
||||
- [ ] No critical decisions left undefined
|
||||
- [ ] No conflicting guidance present
|
||||
- [ ] Document provides clear constraints for agents
|
||||
- [ ] Novel patterns implementable by agents
|
||||
|
||||
### PRD Alignment
|
||||
|
||||
- [ ] All must-have features architecturally supported
|
||||
- [ ] Performance requirements achievable with chosen stack
|
||||
- [ ] Security requirements addressed
|
||||
- [ ] Compliance requirements (if any) met by architecture
|
||||
- [ ] Novel concepts from PRD have architectural solutions
|
||||
|
||||
### UX Specification Alignment (if applicable)
|
||||
|
||||
- [ ] UI component library supports required interaction patterns
|
||||
- [ ] Animation/transition requirements achievable with chosen stack
|
||||
- [ ] Accessibility standards (WCAG level) met by component choices
|
||||
- [ ] Responsive design approach supports all specified breakpoints
|
||||
- [ ] Real-time update requirements addressed in architecture
|
||||
- [ ] Offline capability architecture defined (if required)
|
||||
- [ ] Performance targets from UX spec achievable
|
||||
- [ ] Platform-specific UI requirements supported
|
||||
|
||||
### Risk Mitigation
|
||||
|
||||
- [ ] Single points of failure identified and addressed
|
||||
- [ ] Backup and recovery approach defined (if critical)
|
||||
- [ ] Monitoring and observability approach included
|
||||
- [ ] Rollback strategy considered for deployments
|
||||
- [ ] Novel patterns don't introduce unmanageable risks
|
||||
|
||||
## Common Issues to Check
|
||||
## 10. Common Issues to Check
|
||||
|
||||
### Beginner Protection
|
||||
|
||||
- [ ] Not overengineered for the actual requirements
|
||||
- [ ] Not overengineered for actual requirements
|
||||
- [ ] Standard patterns used where possible (starter templates leveraged)
|
||||
- [ ] Complex technologies justified by specific needs
|
||||
- [ ] Maintenance complexity appropriate for team size
|
||||
|
|
@ -245,17 +212,33 @@
|
|||
- [ ] Future migration paths not blocked
|
||||
- [ ] Novel patterns follow architectural principles
|
||||
|
||||
### Document Usability
|
||||
---
|
||||
|
||||
- [ ] Can be consumed by AI agents without human interpretation
|
||||
- [ ] Provides sufficient detail for consistent implementation
|
||||
- [ ] Free from internal contradictions
|
||||
- [ ] Complete enough to prevent agent "creativity" in critical areas
|
||||
- [ ] Implementation patterns leave no room for conflicting interpretations
|
||||
## Validation Summary
|
||||
|
||||
## Version Verification
|
||||
### Document Quality Score
|
||||
|
||||
- [ ] All versions verified to be current (not relying on potentially outdated catalogs)
|
||||
- [ ] WebSearch used to verify versions during workflow execution
|
||||
- [ ] No hardcoded versions from knowledge bases trusted without verification
|
||||
- [ ] Starter template version checked for latest
|
||||
- Architecture Completeness: [Complete / Mostly Complete / Partial / Incomplete]
|
||||
- Version Specificity: [All Verified / Most Verified / Some Missing / Many Missing]
|
||||
- Pattern Clarity: [Crystal Clear / Clear / Somewhat Ambiguous / Ambiguous]
|
||||
- AI Agent Readiness: [Ready / Mostly Ready / Needs Work / Not Ready]
|
||||
|
||||
### Critical Issues Found
|
||||
|
||||
- [ ] Issue 1: **\*\***\_\_\_**\*\***
|
||||
- [ ] Issue 2: **\*\***\_\_\_**\*\***
|
||||
- [ ] Issue 3: **\*\***\_\_\_**\*\***
|
||||
|
||||
### Recommended Actions Before Implementation
|
||||
|
||||
1. ***
|
||||
2. ***
|
||||
3. ***
|
||||
|
||||
---
|
||||
|
||||
**Next Step**: Run the **solutioning-gate-check** workflow to validate alignment between PRD, Architecture, and Stories before beginning implementation.
|
||||
|
||||
---
|
||||
|
||||
_This checklist validates architecture document quality only. Use solutioning-gate-check for comprehensive readiness validation._
|
||||
|
|
|
|||
|
|
@ -1,19 +1,8 @@
|
|||
# Decision Catalog - Knowledge base for architectural decisions
|
||||
# This replaces rigid project-type templates with intelligent, composable decisions
|
||||
|
||||
# ⚠️ CRITICAL WARNING ABOUT VERSIONS ⚠️
|
||||
# =====================================
|
||||
# Version numbers in this file are EXAMPLES ONLY and will become outdated!
|
||||
# The workflow MUST use WebSearch to verify current versions during execution.
|
||||
# Decision Catalog - Composability knowledge for architectural decisions
|
||||
# This provides RELATIONSHIPS and WORKFLOW LOGIC, not generic tech knowledge
|
||||
#
|
||||
# During facilitation, the AI should:
|
||||
# 1. Use this file for patterns and relationships
|
||||
# 2. Search for "{{technology}} latest stable version 2024" (or current year)
|
||||
# 3. Present the current version found, not the version in this file
|
||||
# 4. Document the verified current version in the architecture
|
||||
#
|
||||
# Versions listed here are for understanding compatibility relationships only.
|
||||
# NEVER trust these version numbers - ALWAYS verify current versions!
|
||||
# ⚠️ CRITICAL: All version/feature info MUST be verified via WebSearch during workflow
|
||||
# This file only provides: triggers, relationships (pairs_with), and opinionated stacks
|
||||
|
||||
decision_categories:
|
||||
data_persistence:
|
||||
|
|
@ -22,57 +11,15 @@ decision_categories:
|
|||
affects: "most epics"
|
||||
options:
|
||||
postgresql:
|
||||
name: "PostgreSQL"
|
||||
current_version: "15.4"
|
||||
lts_version: "14.9"
|
||||
good_for: ["relational data", "complex queries", "ACID compliance", "JSON support"]
|
||||
not_ideal_for: ["massive scale writes", "unstructured data"]
|
||||
pairs_with:
|
||||
- "Prisma ORM 5.6"
|
||||
- "TypeORM 0.3"
|
||||
- "Drizzle 0.29"
|
||||
- "node-postgres 8.11"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["Prisma ORM", "TypeORM", "Drizzle", "node-postgres"]
|
||||
mongodb:
|
||||
name: "MongoDB"
|
||||
current_version: "7.0"
|
||||
lts_version: "6.0"
|
||||
good_for: ["document storage", "flexible schema", "horizontal scaling", "real-time"]
|
||||
not_ideal_for: ["complex relationships", "transactions", "strong consistency"]
|
||||
pairs_with:
|
||||
- "Mongoose 8.0"
|
||||
- "Prisma 5.6"
|
||||
- "MongoDB driver 6.3"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["Mongoose", "Prisma", "MongoDB driver"]
|
||||
redis:
|
||||
name: "Redis"
|
||||
current_version: "7.2"
|
||||
good_for: ["caching", "sessions", "pub/sub", "real-time", "leaderboards"]
|
||||
not_ideal_for: ["primary data store", "complex queries"]
|
||||
pairs_with:
|
||||
- "ioredis 5.3"
|
||||
- "node-redis 4.6"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["ioredis", "node-redis"]
|
||||
supabase:
|
||||
name: "Supabase"
|
||||
current_version: "2.39"
|
||||
good_for: ["PostgreSQL with batteries", "real-time", "auth included", "rapid development"]
|
||||
not_ideal_for: ["custom infrastructure", "specific compliance needs"]
|
||||
pairs_with:
|
||||
- "@supabase/supabase-js 2.39"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["@supabase/supabase-js"]
|
||||
firebase:
|
||||
name: "Firebase Firestore"
|
||||
current_version: "10.7"
|
||||
good_for: ["real-time sync", "offline-first", "serverless", "rapid prototyping"]
|
||||
not_ideal_for: ["complex queries", "data migrations", "cost at scale"]
|
||||
pairs_with:
|
||||
- "firebase-admin 12.0"
|
||||
beginner_friendly: true
|
||||
pairs_with: ["firebase-admin"]
|
||||
|
||||
api_pattern:
|
||||
triggers: ["API", "client communication", "frontend backend", "service communication"]
|
||||
|
|
@ -80,48 +27,13 @@ decision_categories:
|
|||
affects: "all client-facing epics"
|
||||
options:
|
||||
rest:
|
||||
name: "REST API"
|
||||
specification: "OpenAPI 3.0"
|
||||
good_for: ["standard CRUD", "caching", "simple patterns", "wide support"]
|
||||
not_ideal_for: ["complex queries", "real-time updates", "over/under fetching"]
|
||||
pairs_with:
|
||||
- "Express 4.18"
|
||||
- "Fastify 4.25"
|
||||
- "NestJS 10.3"
|
||||
- "Hono 3.12"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["Express", "Fastify", "NestJS", "Hono"]
|
||||
graphql:
|
||||
name: "GraphQL"
|
||||
specification: "GraphQL"
|
||||
current_version: "16.8"
|
||||
good_for: ["flexible queries", "type safety", "avoiding over-fetching", "aggregation"]
|
||||
not_ideal_for: ["simple CRUD", "file uploads", "caching complexity"]
|
||||
pairs_with:
|
||||
- "Apollo Server 4.10"
|
||||
- "GraphQL Yoga 5.1"
|
||||
- "Mercurius 14.0"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["Apollo Server", "GraphQL Yoga", "Mercurius"]
|
||||
trpc:
|
||||
name: "tRPC"
|
||||
current_version: "10.45"
|
||||
good_for: ["type safety", "TypeScript projects", "full-stack type sharing"]
|
||||
not_ideal_for: ["non-TypeScript clients", "public APIs"]
|
||||
pairs_with:
|
||||
- "Next.js 14"
|
||||
- "React Query 5.17"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["Next.js", "React Query"]
|
||||
grpc:
|
||||
name: "gRPC"
|
||||
current_version: "1.60"
|
||||
good_for: ["microservices", "binary protocol", "streaming", "performance"]
|
||||
not_ideal_for: ["browser clients", "debugging", "REST ecosystem"]
|
||||
pairs_with:
|
||||
- "@grpc/grpc-js 1.9"
|
||||
- "protobufjs 7.2"
|
||||
beginner_friendly: false
|
||||
pairs_with: ["@grpc/grpc-js", "protobufjs"]
|
||||
|
||||
authentication:
|
||||
triggers: ["auth", "login", "user management", "security", "identity"]
|
||||
|
|
@ -129,200 +41,59 @@ decision_categories:
|
|||
affects: "security and user epics"
|
||||
options:
|
||||
nextauth:
|
||||
name: "NextAuth.js"
|
||||
current_version: "4.24"
|
||||
good_for: ["Next.js projects", "OAuth providers", "database sessions", "JWT"]
|
||||
not_ideal_for: ["non-Next.js", "complex RBAC", "native mobile"]
|
||||
pairs_with:
|
||||
- "Next.js 14"
|
||||
- "Prisma 5.6"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["Next.js", "Prisma"]
|
||||
auth0:
|
||||
name: "Auth0"
|
||||
good_for: ["enterprise", "compliance", "multi-tenant", "social login"]
|
||||
not_ideal_for: ["cost sensitive", "custom requirements"]
|
||||
pairs_with:
|
||||
- "@auth0/nextjs-auth0 3.5"
|
||||
- "auth0 4.2"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["@auth0/nextjs-auth0"]
|
||||
clerk:
|
||||
name: "Clerk"
|
||||
current_version: "4.29"
|
||||
good_for: ["modern stack", "user management UI", "React/Next.js"]
|
||||
not_ideal_for: ["custom UI requirements", "legacy systems"]
|
||||
pairs_with:
|
||||
- "@clerk/nextjs 4.29"
|
||||
beginner_friendly: true
|
||||
pairs_with: ["@clerk/nextjs"]
|
||||
supabase_auth:
|
||||
pairs_with: ["@supabase/supabase-js"]
|
||||
firebase_auth:
|
||||
pairs_with: ["firebase-admin"]
|
||||
|
||||
supertokens:
|
||||
name: "SuperTokens"
|
||||
current_version: "16.6"
|
||||
good_for: ["open source", "self-hosted", "customizable"]
|
||||
not_ideal_for: ["quick setup", "managed service"]
|
||||
pairs_with:
|
||||
- "supertokens-node 16.6"
|
||||
beginner_friendly: false
|
||||
|
||||
frontend_framework:
|
||||
triggers: ["UI", "frontend", "client", "web app", "user interface"]
|
||||
importance: "critical"
|
||||
affects: "all UI epics"
|
||||
real_time:
|
||||
triggers: ["real-time", "websocket", "live updates", "chat", "collaboration"]
|
||||
importance: "medium"
|
||||
affects: "real-time features"
|
||||
options:
|
||||
nextjs:
|
||||
name: "Next.js"
|
||||
current_version: "14.0"
|
||||
good_for: ["full-stack", "SSR/SSG", "React ecosystem", "SEO"]
|
||||
not_ideal_for: ["pure SPA", "non-React", "simple sites"]
|
||||
pairs_with:
|
||||
- "React 18.2"
|
||||
- "TypeScript 5.3"
|
||||
- "Tailwind CSS 3.4"
|
||||
beginner_friendly: true
|
||||
|
||||
react_spa:
|
||||
name: "React SPA"
|
||||
current_version: "18.2"
|
||||
good_for: ["complex interactions", "existing APIs", "flexibility"]
|
||||
not_ideal_for: ["SEO critical", "initial load time"]
|
||||
pairs_with:
|
||||
- "Vite 5.0"
|
||||
- "React Router 6.21"
|
||||
- "TypeScript 5.3"
|
||||
beginner_friendly: true
|
||||
|
||||
vue:
|
||||
name: "Vue.js"
|
||||
current_version: "3.4"
|
||||
good_for: ["progressive enhancement", "simple mental model", "template syntax"]
|
||||
not_ideal_for: ["React ecosystem needs", "hiring pool"]
|
||||
pairs_with:
|
||||
- "Nuxt 3.9"
|
||||
- "Vite 5.0"
|
||||
- "Pinia 2.1"
|
||||
beginner_friendly: true
|
||||
|
||||
solidjs:
|
||||
name: "SolidJS"
|
||||
current_version: "1.8"
|
||||
good_for: ["performance", "fine-grained reactivity", "small bundle"]
|
||||
not_ideal_for: ["ecosystem size", "learning resources"]
|
||||
pairs_with:
|
||||
- "SolidStart 0.4"
|
||||
- "Vite 5.0"
|
||||
beginner_friendly: false
|
||||
|
||||
state_management:
|
||||
triggers: ["state", "store", "client state", "data flow", "redux"]
|
||||
importance: "high"
|
||||
affects: "frontend epics"
|
||||
options:
|
||||
zustand:
|
||||
name: "Zustand"
|
||||
current_version: "4.4"
|
||||
good_for: ["simplicity", "TypeScript", "small bundle", "React"]
|
||||
not_ideal_for: ["time-travel debugging", "Redux ecosystem"]
|
||||
beginner_friendly: true
|
||||
|
||||
redux_toolkit:
|
||||
name: "Redux Toolkit"
|
||||
current_version: "2.0"
|
||||
good_for: ["complex state", "debugging", "ecosystem", "predictable"]
|
||||
not_ideal_for: ["simple apps", "boilerplate"]
|
||||
beginner_friendly: false
|
||||
|
||||
tanstack_query:
|
||||
name: "TanStack Query"
|
||||
current_version: "5.17"
|
||||
good_for: ["server state", "caching", "synchronization", "mutations"]
|
||||
not_ideal_for: ["pure client state", "offline-heavy"]
|
||||
beginner_friendly: true
|
||||
|
||||
jotai:
|
||||
name: "Jotai"
|
||||
current_version: "2.6"
|
||||
good_for: ["atomic state", "React Suspense", "TypeScript"]
|
||||
not_ideal_for: ["debugging tools", "ecosystem size"]
|
||||
beginner_friendly: false
|
||||
|
||||
realtime:
|
||||
triggers: ["real-time", "websocket", "live", "push", "streaming", "collaborative"]
|
||||
importance: "high"
|
||||
affects: "real-time feature epics"
|
||||
options:
|
||||
socketio:
|
||||
name: "Socket.io"
|
||||
current_version: "4.6"
|
||||
good_for: ["fallbacks", "rooms", "namespaces", "reliability"]
|
||||
not_ideal_for: ["raw performance", "simple needs"]
|
||||
pairs_with:
|
||||
- "socket.io-client 4.6"
|
||||
beginner_friendly: true
|
||||
|
||||
websocket_native:
|
||||
name: "Native WebSocket"
|
||||
good_for: ["performance", "simple needs", "no dependencies"]
|
||||
not_ideal_for: ["fallbacks", "reconnection", "complex patterns"]
|
||||
pairs_with:
|
||||
- "ws 8.16"
|
||||
beginner_friendly: false
|
||||
|
||||
socket_io:
|
||||
pairs_with: ["Express", "socket.io-client"]
|
||||
pusher:
|
||||
name: "Pusher"
|
||||
good_for: ["managed service", "quick setup", "global infrastructure"]
|
||||
not_ideal_for: ["cost at scale", "self-hosted needs"]
|
||||
pairs_with:
|
||||
- "pusher-js 8.4"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["pusher-js"]
|
||||
ably:
|
||||
name: "Ably"
|
||||
current_version: "1.2"
|
||||
good_for: ["guaranteed delivery", "presence", "history", "managed"]
|
||||
not_ideal_for: ["cost sensitive", "simple needs"]
|
||||
pairs_with:
|
||||
- "ably 1.2"
|
||||
beginner_friendly: true
|
||||
pairs_with: ["ably"]
|
||||
supabase_realtime:
|
||||
pairs_with: ["@supabase/supabase-js"]
|
||||
firebase_realtime:
|
||||
pairs_with: ["firebase"]
|
||||
|
||||
email:
|
||||
triggers: ["email", "notifications", "transactional email"]
|
||||
importance: "medium"
|
||||
affects: "notification epics"
|
||||
options:
|
||||
resend:
|
||||
pairs_with: ["resend", "react-email"]
|
||||
sendgrid:
|
||||
pairs_with: ["@sendgrid/mail"]
|
||||
postmark:
|
||||
pairs_with: ["postmark"]
|
||||
ses:
|
||||
pairs_with: ["@aws-sdk/client-ses"]
|
||||
|
||||
file_storage:
|
||||
triggers: ["file upload", "images", "documents", "media", "blob storage", "assets"]
|
||||
triggers: ["upload", "file storage", "images", "media", "CDN"]
|
||||
importance: "medium"
|
||||
affects: "content epics"
|
||||
affects: "media handling epics"
|
||||
options:
|
||||
s3:
|
||||
name: "AWS S3"
|
||||
good_for: ["scale", "durability", "ecosystem", "CDN integration"]
|
||||
not_ideal_for: ["simple needs", "cost optimization"]
|
||||
pairs_with:
|
||||
- "@aws-sdk/client-s3 3.478"
|
||||
- "multer-s3 3.0"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["@aws-sdk/client-s3", "multer"]
|
||||
cloudinary:
|
||||
name: "Cloudinary"
|
||||
good_for: ["image optimization", "transformations", "CDN", "easy setup"]
|
||||
not_ideal_for: ["raw files", "cost at scale"]
|
||||
pairs_with:
|
||||
- "cloudinary 1.41"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["cloudinary"]
|
||||
uploadthing:
|
||||
name: "UploadThing"
|
||||
current_version: "6.0"
|
||||
good_for: ["Next.js", "type safety", "simple setup"]
|
||||
not_ideal_for: ["non-Next.js", "complex requirements"]
|
||||
pairs_with:
|
||||
- "uploadthing 6.0"
|
||||
beginner_friendly: true
|
||||
|
||||
local_storage:
|
||||
name: "Local File System"
|
||||
good_for: ["development", "on-premise", "simple needs"]
|
||||
not_ideal_for: ["scale", "CDN", "distributed systems"]
|
||||
pairs_with:
|
||||
- "multer 1.4"
|
||||
beginner_friendly: true
|
||||
pairs_with: ["uploadthing"]
|
||||
supabase_storage:
|
||||
pairs_with: ["@supabase/supabase-js"]
|
||||
|
||||
search:
|
||||
triggers: ["search", "full text", "elasticsearch", "algolia", "fuzzy"]
|
||||
|
|
@ -330,36 +101,13 @@ decision_categories:
|
|||
affects: "search and discovery epics"
|
||||
options:
|
||||
postgres_fts:
|
||||
name: "PostgreSQL Full Text Search"
|
||||
good_for: ["simple search", "no extra infrastructure", "cost effective"]
|
||||
not_ideal_for: ["complex relevance", "fuzzy matching", "facets"]
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["PostgreSQL"]
|
||||
elasticsearch:
|
||||
name: "Elasticsearch"
|
||||
current_version: "8.11"
|
||||
good_for: ["complex search", "analytics", "aggregations", "scale"]
|
||||
not_ideal_for: ["simple needs", "operational overhead"]
|
||||
pairs_with:
|
||||
- "@elastic/elasticsearch 8.11"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["@elastic/elasticsearch"]
|
||||
algolia:
|
||||
name: "Algolia"
|
||||
good_for: ["instant search", "typo tolerance", "managed service", "speed"]
|
||||
not_ideal_for: ["cost at scale", "data sovereignty"]
|
||||
pairs_with:
|
||||
- "algoliasearch 4.22"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["algoliasearch"]
|
||||
typesense:
|
||||
name: "Typesense"
|
||||
current_version: "1.7"
|
||||
good_for: ["open source alternative to Algolia", "typo tolerance", "self-hosted"]
|
||||
not_ideal_for: ["managed service needs", "small projects"]
|
||||
pairs_with:
|
||||
- "typesense 1.7"
|
||||
beginner_friendly: false
|
||||
pairs_with: ["typesense"]
|
||||
|
||||
background_jobs:
|
||||
triggers: ["queue", "jobs", "workers", "async", "background processing", "scheduled"]
|
||||
|
|
@ -367,39 +115,13 @@ decision_categories:
|
|||
affects: "async processing epics"
|
||||
options:
|
||||
bullmq:
|
||||
name: "BullMQ"
|
||||
current_version: "5.1"
|
||||
good_for: ["Redis-based", "reliable", "dashboard", "Node.js"]
|
||||
not_ideal_for: ["multi-language", "serverless"]
|
||||
pairs_with:
|
||||
- "Redis 7.2"
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["Redis"]
|
||||
sqs:
|
||||
name: "AWS SQS"
|
||||
good_for: ["managed service", "scale", "AWS ecosystem", "serverless"]
|
||||
not_ideal_for: ["local development", "complex patterns"]
|
||||
pairs_with:
|
||||
- "@aws-sdk/client-sqs 3.478"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["@aws-sdk/client-sqs"]
|
||||
temporal:
|
||||
name: "Temporal"
|
||||
current_version: "1.22"
|
||||
good_for: ["complex workflows", "durability", "long-running", "saga pattern"]
|
||||
not_ideal_for: ["simple jobs", "quick setup"]
|
||||
pairs_with:
|
||||
- "@temporalio/client 1.9"
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["@temporalio/client"]
|
||||
inngest:
|
||||
name: "Inngest"
|
||||
current_version: "3.8"
|
||||
good_for: ["serverless", "event-driven", "TypeScript", "retries"]
|
||||
not_ideal_for: ["self-hosted", "complex workflows"]
|
||||
pairs_with:
|
||||
- "inngest 3.8"
|
||||
beginner_friendly: true
|
||||
pairs_with: ["inngest"]
|
||||
|
||||
deployment_target:
|
||||
triggers: ["deployment", "hosting", "infrastructure", "cloud", "server"]
|
||||
|
|
@ -407,277 +129,80 @@ decision_categories:
|
|||
affects: "all epics"
|
||||
options:
|
||||
vercel:
|
||||
name: "Vercel"
|
||||
good_for: ["Next.js", "edge functions", "preview deployments", "simplicity"]
|
||||
not_ideal_for: ["complex backends", "cost at scale", "non-JS"]
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["Next.js", "serverless functions"]
|
||||
aws:
|
||||
name: "AWS"
|
||||
good_for: ["everything", "scale", "compliance", "flexibility"]
|
||||
not_ideal_for: ["simplicity", "predictable costs", "small projects"]
|
||||
beginner_friendly: false
|
||||
|
||||
pairs_with: ["any stack"]
|
||||
railway:
|
||||
name: "Railway"
|
||||
good_for: ["simplicity", "databases included", "quick setup"]
|
||||
not_ideal_for: ["enterprise needs", "complex requirements"]
|
||||
beginner_friendly: true
|
||||
|
||||
pairs_with: ["any stack", "managed databases"]
|
||||
fly_io:
|
||||
name: "Fly.io"
|
||||
good_for: ["edge deployment", "global distribution", "containers"]
|
||||
not_ideal_for: ["managed databases", "enterprise support"]
|
||||
beginner_friendly: false
|
||||
pairs_with: ["Docker containers"]
|
||||
|
||||
# Pattern combinations that work well together
|
||||
# Opinionated stack combinations (BMM methodology)
|
||||
common_stacks:
|
||||
modern_fullstack:
|
||||
name: "Modern Full-Stack"
|
||||
components:
|
||||
- "Next.js 14"
|
||||
- "PostgreSQL 15 or Supabase"
|
||||
- "Prisma ORM 5.6"
|
||||
- "NextAuth.js 4.24"
|
||||
- "Tailwind CSS 3.4"
|
||||
- "TypeScript 5.3"
|
||||
- "Vercel deployment"
|
||||
components: ["Next.js", "PostgreSQL or Supabase", "Prisma ORM", "NextAuth.js", "Tailwind CSS", "TypeScript", "Vercel"]
|
||||
good_for: "Most web applications"
|
||||
|
||||
enterprise_stack:
|
||||
name: "Enterprise Stack"
|
||||
components:
|
||||
- "NestJS 10.3"
|
||||
- "PostgreSQL 15"
|
||||
- "TypeORM 0.3"
|
||||
- "Auth0"
|
||||
- "React 18.2 + TypeScript"
|
||||
- "AWS deployment"
|
||||
good_for: "Large scale, compliance needs"
|
||||
components: ["NestJS", "PostgreSQL", "TypeORM", "Auth0", "Redis", "Docker", "AWS"]
|
||||
good_for: "Large-scale enterprise applications"
|
||||
|
||||
startup_stack:
|
||||
name: "Rapid Development Stack"
|
||||
components:
|
||||
- "Next.js 14"
|
||||
- "Supabase"
|
||||
- "Clerk Auth"
|
||||
- "Tailwind CSS 3.4"
|
||||
- "Vercel deployment"
|
||||
good_for: "MVPs and rapid prototyping"
|
||||
rapid_prototype:
|
||||
name: "Rapid Prototype"
|
||||
components: ["Next.js", "Supabase", "shadcn/ui", "Vercel"]
|
||||
good_for: "MVP and rapid development"
|
||||
|
||||
realtime_stack:
|
||||
name: "Real-time Collaboration"
|
||||
components:
|
||||
- "Next.js 14"
|
||||
- "Socket.io 4.6"
|
||||
- "Redis 7.2"
|
||||
- "PostgreSQL 15"
|
||||
- "Railway deployment"
|
||||
good_for: "Collaborative applications"
|
||||
real_time_app:
|
||||
name: "Real-Time Application"
|
||||
components: ["Next.js", "Supabase Realtime", "PostgreSQL", "Prisma", "Socket.io fallback"]
|
||||
good_for: "Chat, collaboration, live updates"
|
||||
|
||||
# WARNING: Version numbers are illustrative - actual versions should be verified
|
||||
# during workflow execution via web search for current stable versions
|
||||
mobile_app:
|
||||
name: "Mobile Application"
|
||||
components: ["Expo", "React Native", "Supabase or Firebase", "React Query"]
|
||||
good_for: "Cross-platform mobile apps"
|
||||
|
||||
# Starter templates that make architectural decisions
|
||||
# Starter templates and what decisions they make
|
||||
starter_templates:
|
||||
create_next_app:
|
||||
name: "Create Next App"
|
||||
command_search: "npx create-next-app@latest options"
|
||||
base_command: "npx create-next-app@latest"
|
||||
interactive: true
|
||||
decisions_provided:
|
||||
- "TypeScript vs JavaScript (--typescript flag)"
|
||||
- "ESLint configuration (--eslint flag)"
|
||||
- "Tailwind CSS setup (--tailwind flag)"
|
||||
- "App Router vs Pages Router (--app flag)"
|
||||
- "src/ directory structure (--src-dir flag)"
|
||||
- "Import alias (@/* default)"
|
||||
project_structure: "Standard Next.js structure with app/ or pages/"
|
||||
good_for: ["Web applications", "SSR/SSG needs", "Full-stack React"]
|
||||
command_search: "npx create-next-app@latest"
|
||||
decisions_provided: ["Next.js framework", "TypeScript option", "App Router vs Pages", "Tailwind CSS option", "ESLint"]
|
||||
good_for: ["React web applications", "Full-stack apps", "SSR/SSG"]
|
||||
|
||||
create_t3_app:
|
||||
name: "Create T3 App"
|
||||
command_search: "create t3 app latest CLI options"
|
||||
base_command: "npm create t3-app@latest"
|
||||
interactive: true
|
||||
decisions_provided:
|
||||
- "Next.js framework (always)"
|
||||
- "TypeScript (always)"
|
||||
- "tRPC for type-safe APIs"
|
||||
- "Prisma ORM"
|
||||
- "NextAuth.js authentication"
|
||||
- "Tailwind CSS"
|
||||
- "Drizzle ORM (alternative to Prisma)"
|
||||
project_structure: "Opinionated full-stack structure"
|
||||
good_for: ["Type-safe full-stack", "Rapid development", "Best practices"]
|
||||
command_search: "npm create t3-app@latest"
|
||||
decisions_provided: ["Next.js", "TypeScript", "tRPC", "Prisma", "NextAuth", "Tailwind CSS"]
|
||||
good_for: ["Type-safe full-stack apps"]
|
||||
|
||||
create_vite:
|
||||
name: "Create Vite"
|
||||
command_search: "npm create vite templates options"
|
||||
base_command: "npm create vite@latest"
|
||||
interactive: true
|
||||
templates_available:
|
||||
- "vanilla"
|
||||
- "vanilla-ts"
|
||||
- "react"
|
||||
- "react-ts"
|
||||
- "react-swc"
|
||||
- "react-swc-ts"
|
||||
- "vue"
|
||||
- "vue-ts"
|
||||
- "svelte"
|
||||
- "svelte-ts"
|
||||
decisions_provided:
|
||||
- "Build tool (Vite)"
|
||||
- "Framework choice"
|
||||
- "TypeScript setup"
|
||||
- "HMR configuration"
|
||||
- "Development server"
|
||||
project_structure: "Minimal, framework-specific"
|
||||
good_for: ["SPAs", "Fast development", "Modern tooling"]
|
||||
|
||||
create_react_app:
|
||||
name: "Create React App"
|
||||
status: "DEPRECATED - Use Vite or Next.js instead"
|
||||
note: "No longer recommended by React team"
|
||||
command_search: "npm create vite@latest"
|
||||
decisions_provided: ["Framework choice (React/Vue/Svelte)", "TypeScript option", "Vite bundler"]
|
||||
good_for: ["Fast dev SPAs", "Library development"]
|
||||
|
||||
create_remix:
|
||||
name: "Create Remix"
|
||||
command_search: "npx create-remix latest options"
|
||||
base_command: "npx create-remix@latest"
|
||||
decisions_provided:
|
||||
- "Remix framework"
|
||||
- "TypeScript option"
|
||||
- "Deployment target"
|
||||
- "CSS solution"
|
||||
command_search: "npx create-remix@latest"
|
||||
decisions_provided: ["Remix framework", "TypeScript option", "Deployment target", "CSS solution"]
|
||||
good_for: ["Web standards", "Nested routing", "Progressive enhancement"]
|
||||
|
||||
nest_new:
|
||||
name: "NestJS CLI"
|
||||
command_search: "nest new project options"
|
||||
base_command: "nest new"
|
||||
decisions_provided:
|
||||
- "TypeScript (always)"
|
||||
- "Package manager"
|
||||
- "Testing framework (Jest)"
|
||||
- "Linting (ESLint)"
|
||||
- "Project structure (modules/controllers/services)"
|
||||
project_structure: "Enterprise Angular-style backend"
|
||||
command_search: "nest new project"
|
||||
decisions_provided: ["TypeScript (always)", "Package manager", "Testing framework (Jest)", "Project structure"]
|
||||
good_for: ["Enterprise APIs", "Microservices", "GraphQL APIs"]
|
||||
|
||||
create_expo_app:
|
||||
name: "Create Expo App"
|
||||
command_search: "create-expo-app templates latest"
|
||||
base_command: "npx create-expo-app"
|
||||
decisions_provided:
|
||||
- "React Native setup"
|
||||
- "TypeScript option"
|
||||
- "Navigation library option"
|
||||
- "Expo SDK version"
|
||||
command_search: "npx create-expo-app"
|
||||
decisions_provided: ["React Native", "Expo SDK", "TypeScript option", "Navigation option"]
|
||||
good_for: ["Cross-platform mobile", "React Native apps"]
|
||||
|
||||
create_vue:
|
||||
name: "Create Vue"
|
||||
command_search: "npm create vue latest options"
|
||||
base_command: "npm create vue@latest"
|
||||
decisions_provided:
|
||||
- "Vue 3"
|
||||
- "TypeScript option"
|
||||
- "JSX support"
|
||||
- "Vue Router"
|
||||
- "Pinia state management"
|
||||
- "Vitest for testing"
|
||||
- "ESLint + Prettier"
|
||||
good_for: ["Vue applications", "Progressive web apps"]
|
||||
|
||||
create_astro:
|
||||
name: "Create Astro"
|
||||
command_search: "npm create astro latest templates"
|
||||
base_command: "npm create astro@latest"
|
||||
decisions_provided:
|
||||
- "Astro framework"
|
||||
- "TypeScript strictness"
|
||||
- "Template choice"
|
||||
- "Framework integrations"
|
||||
good_for: ["Content sites", "Static sites", "Islands architecture"]
|
||||
|
||||
create_svelte:
|
||||
name: "Create Svelte"
|
||||
command_search: "npm create svelte latest options"
|
||||
base_command: "npm create svelte@latest"
|
||||
decisions_provided:
|
||||
- "SvelteKit framework"
|
||||
- "TypeScript option"
|
||||
- "ESLint"
|
||||
- "Prettier"
|
||||
- "Testing setup"
|
||||
good_for: ["Svelte applications", "Compiled frameworks"]
|
||||
|
||||
cargo_new:
|
||||
name: "Cargo New (Rust)"
|
||||
command_search: "cargo new options binary library"
|
||||
base_command: "cargo new"
|
||||
decisions_provided:
|
||||
- "Binary vs Library (--bin or --lib)"
|
||||
- "Project structure"
|
||||
- "Cargo.toml setup"
|
||||
good_for: ["Rust CLI tools", "Systems programming", "Performance critical"]
|
||||
|
||||
dotnet_new:
|
||||
name: ".NET CLI"
|
||||
command_search: "dotnet new templates list"
|
||||
base_command: "dotnet new"
|
||||
templates_available:
|
||||
- "webapi"
|
||||
- "webapp"
|
||||
- "blazor"
|
||||
- "console"
|
||||
- "classlib"
|
||||
decisions_provided:
|
||||
- "Project type"
|
||||
- ".NET version"
|
||||
- "Authentication option"
|
||||
- "HTTPS configuration"
|
||||
good_for: ["C# applications", "Enterprise", "Windows development"]
|
||||
|
||||
rails_new:
|
||||
name: "Rails New"
|
||||
command_search: "rails new options latest"
|
||||
base_command: "rails new"
|
||||
decisions_provided:
|
||||
- "Database (PostgreSQL/MySQL/SQLite)"
|
||||
- "CSS framework"
|
||||
- "JavaScript approach"
|
||||
- "Testing framework"
|
||||
- "API-only mode"
|
||||
good_for: ["Ruby web apps", "Rapid prototyping", "Convention over configuration"]
|
||||
|
||||
django_startproject:
|
||||
name: "Django Start Project"
|
||||
command_search: "django-admin startproject structure"
|
||||
base_command: "django-admin startproject"
|
||||
decisions_provided:
|
||||
- "Django framework"
|
||||
- "Project structure"
|
||||
- "Settings configuration"
|
||||
- "Database (SQLite default)"
|
||||
good_for: ["Python web apps", "Admin interfaces", "Content management"]
|
||||
|
||||
create_redwood_app:
|
||||
name: "Create RedwoodJS App"
|
||||
command_search: "yarn create redwood-app latest"
|
||||
base_command: "yarn create redwood-app"
|
||||
decisions_provided:
|
||||
- "RedwoodJS framework"
|
||||
- "TypeScript (default)"
|
||||
- "Prisma ORM"
|
||||
- "GraphQL API"
|
||||
- "Storybook"
|
||||
- "Testing setup"
|
||||
project_structure: "Monorepo with api/ and web/"
|
||||
good_for: ["Full-stack JAMstack", "Startups", "Rapid development"]
|
||||
|
||||
# Starter template selection heuristics
|
||||
# Starter selection heuristics (workflow logic)
|
||||
starter_selection_rules:
|
||||
by_project_type:
|
||||
web_application:
|
||||
|
|
@ -685,17 +210,13 @@ starter_selection_rules:
|
|||
considerations: "SSR needs? → Next.js. Type safety critical? → T3. SPA only? → Vite"
|
||||
|
||||
mobile_app:
|
||||
recommended: ["create_expo_app", "react_native_cli"]
|
||||
considerations: "Need native modules? → React Native CLI. Simpler setup? → Expo"
|
||||
recommended: ["create_expo_app"]
|
||||
considerations: "Cross-platform → Expo. Native-heavy → React Native CLI"
|
||||
|
||||
api_backend:
|
||||
recommended: ["nest_new", "express_generator", "fastify_cli"]
|
||||
considerations: "Enterprise? → NestJS. Simple? → Express. Performance? → Fastify"
|
||||
|
||||
cli_tool:
|
||||
recommended: ["cargo_new", "go_mod_init", "npm_init"]
|
||||
considerations: "Performance critical? → Rust/Go. Quick script? → Node.js/Python"
|
||||
recommended: ["nest_new"]
|
||||
considerations: "Enterprise → NestJS. Simple → Express starter. Performance → Fastify"
|
||||
|
||||
full_stack:
|
||||
recommended: ["create_t3_app", "create_redwood_app", "rails_new"]
|
||||
considerations: "Type safety? → T3. JAMstack? → Redwood. Ruby? → Rails"
|
||||
recommended: ["create_t3_app", "create_remix"]
|
||||
considerations: "Type safety → T3. Web standards → Remix. Monolith → RedwoodJS"
|
||||
|
|
|
|||
|
|
@ -50,10 +50,10 @@ phases:
|
|||
command: "tech-spec"
|
||||
output: "Creates spec with multiple story files"
|
||||
note: "Integrate with existing patterns"
|
||||
- id: "ux-spec"
|
||||
- id: "create-design"
|
||||
conditional: "if_has_ui"
|
||||
agent: "ux-designer"
|
||||
command: "ux-spec"
|
||||
command: "create-design"
|
||||
|
||||
- phase: 3
|
||||
name: "Solutioning"
|
||||
|
|
|
|||
|
|
@ -44,10 +44,10 @@ phases:
|
|||
agent: "pm"
|
||||
command: "prd"
|
||||
output: "Requirements with integration points"
|
||||
- id: "ux-spec"
|
||||
- id: "create-design"
|
||||
conditional: "if_has_ui"
|
||||
agent: "pm"
|
||||
command: "ux-spec"
|
||||
agent: "ux-designer"
|
||||
command: "create-design"
|
||||
note: "Must align with existing UI patterns"
|
||||
|
||||
- phase: 3
|
||||
|
|
|
|||
|
|
@ -46,10 +46,10 @@ phases:
|
|||
agent: "pm"
|
||||
command: "prd"
|
||||
output: "Comprehensive PRD considering existing system"
|
||||
- id: "ux-spec"
|
||||
- id: "create-design"
|
||||
required: true
|
||||
agent: "pm"
|
||||
command: "ux-spec"
|
||||
agent: "ux-designer"
|
||||
command: "create-design"
|
||||
note: "Multiple UI/UX specifications"
|
||||
|
||||
- phase: 3
|
||||
|
|
|
|||
|
|
@ -34,10 +34,10 @@ phases:
|
|||
agent: "pm"
|
||||
command: "prd"
|
||||
output: "Creates PRD with epics.md and story list"
|
||||
- id: "ux-spec"
|
||||
- id: "create-design"
|
||||
conditional: "if_has_ui"
|
||||
agent: "ux-designer"
|
||||
command: "ux-spec"
|
||||
command: "create-design"
|
||||
- id: "tech-spec"
|
||||
optional: true
|
||||
agent: "pm"
|
||||
|
|
|
|||
|
|
@ -34,10 +34,10 @@ phases:
|
|||
agent: "pm"
|
||||
command: "prd"
|
||||
output: "High-level requirements and epic definitions"
|
||||
- id: "ux-spec"
|
||||
- id: "create-design"
|
||||
conditional: "if_has_ui"
|
||||
agent: "ux-designer"
|
||||
command: "ux-spec"
|
||||
command: "create-design"
|
||||
|
||||
- phase: 3
|
||||
name: "Solutioning"
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ phases:
|
|||
agent: "analyst"
|
||||
command: "brainstorm-project"
|
||||
- id: "research"
|
||||
required: true
|
||||
required: false
|
||||
agent: "analyst"
|
||||
command: "research"
|
||||
note: "Extensive research across multiple domains"
|
||||
|
|
@ -35,10 +35,10 @@ phases:
|
|||
agent: "pm"
|
||||
command: "prd"
|
||||
output: "Comprehensive product requirements document"
|
||||
- id: "ux-spec"
|
||||
- id: "create-design"
|
||||
required: true
|
||||
agent: "ux-designer"
|
||||
command: "ux-spec"
|
||||
command: "create-design"
|
||||
note: "Multiple UI/UX specifications needed"
|
||||
|
||||
- phase: 3
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ levels:
|
|||
title: "Enterprise Scale"
|
||||
stories: "40+ stories"
|
||||
description: "Multiple products, enterprise architecture"
|
||||
documentation: "Full suite - PRD, architecture, product specs"
|
||||
documentation: "PRD + architecture + JIT tech specs"
|
||||
architecture: true
|
||||
|
||||
# Quick detection hints for workflow-init
|
||||
|
|
|
|||
|
|
@ -25,21 +25,6 @@ NEXT_ACTION: {{next_action}}
|
|||
NEXT_COMMAND: {{next_command}}
|
||||
NEXT_AGENT: {{next_agent}}
|
||||
|
||||
## Story Backlog
|
||||
|
||||
{{#backlog_stories}}
|
||||
|
||||
- {{story_id}}: {{story_title}}
|
||||
{{/backlog_stories}}
|
||||
|
||||
## Completed Stories
|
||||
|
||||
{{#done_stories}}
|
||||
|
||||
- {{story_id}}: {{completed_date}}
|
||||
{{/done_stories}}
|
||||
|
||||
---
|
||||
|
||||
_Last Updated: {{last_updated}}_
|
||||
_Status Version: 2.0_
|
||||
|
|
|
|||
Loading…
Reference in New Issue