cassel/bi-agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update all documentation and add AI tooling configs

Browse Source 
- Rewrite README.md with current architecture, features and stack
- Update docs/API.md with all current endpoints (corporate, BI, client 360)
- Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL
- Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente)
- Add docs/INDEX.md documentation index
- Add PROJETO.md comprehensive project reference
- Add BI-CCC-Implementation-Guide.md
- Include AI agent configs (.claude, .agents, .gemini, _bmad)
- Add netbird VPN configuration
- Add status report

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Cassel
2026-03-19 13:29:03 -04:00
parent c5b377e788
commit 647cbec54f
3246 changed files with 479789 additions and 983 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
_bmad/wds/workflows/7-design-system/steps-c/step-01-scan-existing.md Normal file
View File

@@ -0,0 +1,130 @@
---
name: 'step-01-scan-existing'
description: 'Scan existing design system components to find matches for the current component type'
# File References
nextStepFile: './step-02-compare-attributes.md'
---
# Step 1: Scan Existing Components
## STEP GOAL:
Find all components in the design system that match the current component type. Scan the design system folder, extract component metadata, and build a candidate list for comparison.
## MANDATORY EXECUTION RULES (READ FIRST):
### Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
### Role Reinforcement:
- ✅ You are the Design System Architect guiding design system creation and maintenance
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
- ✅ Maintain systematic and analytical tone throughout
### Step-Specific Rules:
- 🎯 Focus ONLY on this step's specific goal — do not skip ahead
- 🚫 FORBIDDEN to jump to later steps before this step is complete
- 💬 Approach: Systematic execution with clear reporting
- 📋 All outputs must be documented and presented to user
## EXECUTION PROTOCOLS:
- 🎯 Execute each instruction in the sequence below
- 💾 Document all findings and decisions
- 📖 Present results to user before proceeding
- 🚫 FORBIDDEN to skip instructions or optimize the sequence
## CONTEXT BOUNDARIES:
- Available context: Previous step outputs and project configuration
- Focus: This step's specific goal only
- Limits: Do not perform actions belonging to subsequent steps
- Dependencies: Requires all previous steps to be completed
## Sequence of Instructions (Do not deviate, skip, or optimize)
### 1. Read Design System Folder
Scan design system components:
- Read all files in `D-Design-System/components/`
- Parse component type from each file
- Filter by matching type
### 2. Extract Component Metadata
For each matching component, extract:
- Component ID (e.g., `btn-001`)
- Variants (e.g., primary, secondary, ghost)
- States (e.g., default, hover, active, disabled)
- Key styling attributes
- Usage count (how many pages use it)
### 3. Build Candidate List
Present matching components to user with full metadata.
### 4. Handle Edge Cases
**No matching components found:** Route to `step-08b-create-new-component.md`
**Design system empty:** Route to `step-08a-initialize-design-system.md`
**Multiple type matches:** Continue to comparison for each candidate.
### 5. Pass Data to Next Step
Pass candidate list to comparison step:
- Component IDs
- Full metadata
- Current component specification
### 6. Present MENU OPTIONS
Display: "**Select an Option:** [C] Continue to Compare Attributes"
#### Menu Handling Logic:
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [C continue option is selected and scan is complete with candidate list built], will you then load and read fully `{nextStepFile}` to execute the next step.
---
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated
### ❌ SYSTEM FAILURE:
- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

369
_bmad/wds/workflows/7-design-system/steps-c/step-02-compare-attributes.md Normal file
View File

@@ -0,0 +1,369 @@
---
name: 'step-02-compare-attributes'
description: 'Systematically compare current component to existing candidates across visual, functional, behavioral, and contextual dimensions'
# File References
nextStepFile: './step-03-calculate-similarity.md'
---
# Step 2: Compare Attributes
## STEP GOAL:
Systematically compare the current component specification against existing candidates across four dimensions: visual, functional, behavioral, and contextual attributes.
## MANDATORY EXECUTION RULES (READ FIRST):
### Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
### Role Reinforcement:
- ✅ You are the Design System Architect guiding design system creation and maintenance
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
- ✅ Maintain systematic and analytical tone throughout
### Step-Specific Rules:
- 🎯 Focus ONLY on this step's specific goal — do not skip ahead
- 🚫 FORBIDDEN to jump to later steps before this step is complete
- 💬 Approach: Systematic execution with clear reporting
- 📋 All outputs must be documented and presented to user
## EXECUTION PROTOCOLS:
- 🎯 Execute each instruction in the sequence below
- 💾 Document all findings and decisions
- 📖 Present results to user before proceeding
- 🚫 FORBIDDEN to skip instructions or optimize the sequence
## CONTEXT BOUNDARIES:
- Available context: Previous step outputs and project configuration
- Focus: This step's specific goal only
- Limits: Do not perform actions belonging to subsequent steps
- Dependencies: Requires all previous steps to be completed
## Sequence of Instructions (Do not deviate, skip, or optimize)
## Comparison Framework
**Compare across 4 dimensions:**
### 1. Visual Attributes
- Size (small, medium, large)
- Shape (rounded, square, pill)
- Color scheme
- Typography
- Spacing/padding
- Border style
### 2. Functional Attributes
- Purpose/intent
- User action
- Input/output type
- Validation rules
- Required/optional
### 3. Behavioral Attributes
- States (default, hover, active, disabled, loading, error)
- Interactions (click, hover, focus, blur)
- Animations/transitions
- Keyboard support
- Accessibility
### 4. Contextual Attributes
- Usage pattern (where it appears)
- Frequency (how often used)
- Relationship to other components
- User journey stage
---
## Step 1: Visual Comparison
<action>
Compare visual attributes:
- Extract visual properties from current spec
- Extract visual properties from candidate
- Calculate matches and differences
</action>
**Example:**
```
Visual Comparison: Current Button vs Button [btn-001]
Similarities:
✓ Size: medium (both)
✓ Shape: rounded (both)
✓ Color scheme: blue primary (both)
Differences:
✗ Current: Has icon on left
✗ btn-001: Text only
✗ Current: Slightly larger padding
```
---
## Step 2: Functional Comparison
<action>
Compare functional attributes:
- What does it do?
- What's the user intent?
- What's the outcome?
</action>
**Example:**
```
Functional Comparison: Current Button vs Button [btn-001]
Similarities:
✓ Purpose: Primary action trigger
✓ User action: Click to submit/proceed
✓ Outcome: Form submission or navigation
Differences:
✗ Current: "Continue to next step"
✗ btn-001: "Submit form"
✗ Current: Navigation action
✗ btn-001: Form submission action
```
---
## Step 3: Behavioral Comparison
<action>
Compare behavioral attributes:
- States
- Interactions
- Animations
</action>
**Example:**
```
Behavioral Comparison: Current Button vs Button [btn-001]
Similarities:
✓ States: default, hover, active, disabled (both)
✓ Hover: Darkens background (both)
✓ Disabled: Grayed out (both)
Differences:
✗ Current: Has loading state with spinner
✗ btn-001: No loading state
✗ Current: Icon rotates on hover
```
---
## Step 4: Contextual Comparison
<action>
Compare contextual attributes:
- Where is it used?
- How often?
- What's the pattern?
</action>
**Example:**
```
Contextual Comparison: Current Button vs Button [btn-001]
Similarities:
✓ Both: Primary action in forms
✓ Both: Bottom-right of containers
✓ Both: High-frequency usage
Differences:
✗ Current: Multi-step flow navigation
✗ btn-001: Single-page form submission
✗ Current: Always has "next" context
```
---
## Step 5: Calculate Similarity Score
<action>
Score each dimension:
- Visual: High/Medium/Low similarity
- Functional: High/Medium/Low similarity
- Behavioral: High/Medium/Low similarity
- Contextual: High/Medium/Low similarity
</action>
**Scoring Guide:**
- **High:** 80%+ attributes match
- **Medium:** 50-79% attributes match
- **Low:** <50% attributes match
**Example:**
```
Similarity Score: Current Button vs Button [btn-001]
Visual: High (90% match)
Functional: Medium (60% match)
Behavioral: Medium (70% match)
Contextual: Medium (65% match)
Overall: Medium-High Similarity
```
---
## Step 6: Summarize Comparison
<output>
Present comparison summary:
```
📊 Comparison: Current Button vs Button [btn-001]
**Similarities:**
✓ Visual appearance (size, shape, color)
✓ Primary action purpose
✓ Standard states (default, hover, active, disabled)
✓ High-frequency usage pattern
**Differences:**
✗ Current has icon, btn-001 is text-only
✗ Current has loading state, btn-001 doesn't
✗ Current for navigation, btn-001 for submission
✗ Current has icon animation
**Similarity Score:** Medium-High (71%)
```
</output>
---
## Step 7: Pass to Next Step
<action>
Pass comparison data to similarity calculation:
- Detailed comparison
- Similarity scores
- Key differences
</action>
**Next:** `step-03-calculate-similarity.md`
---
## Edge Cases
**Perfect match (100%):**
```
✓ This component is identical to btn-001.
This is likely the same component with different content.
```
**Recommend:** Reuse existing component
**Very low similarity (<30%):**
```
✗ This component is very different from btn-001.
Despite being the same type, these serve different purposes.
```
**Recommend:** Create new component
**Multiple candidates:**
```
📊 Comparing to 2 candidates:
Button [btn-001]: 71% similarity
Icon Button [btn-002]: 45% similarity
btn-001 is the closest match.
```
**Continue with best match**
---
## Output Format
**For next step:**
```json
{
"comparison": {
"candidate_id": "btn-001",
"visual_similarity": "high",
"functional_similarity": "medium",
"behavioral_similarity": "medium",
"contextual_similarity": "medium",
"overall_score": 0.71,
"similarities": [...],
"differences": [...]
}
}
```
### 8. Present MENU OPTIONS
Display: "**Select an Option:** [C] Continue to Calculate Similarity"
#### Menu Handling Logic:
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [C continue option is selected and all four dimensions compared with scores assigned], will you then load and read fully `{nextStepFile}` to execute the next step.
---
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated
### ❌ SYSTEM FAILURE:
- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

439
_bmad/wds/workflows/7-design-system/steps-c/step-03-calculate-similarity.md Normal file
View File

@@ -0,0 +1,439 @@
---
name: 'step-03-calculate-similarity'
description: 'Interpret comparison data, calculate weighted similarity score, and classify similarity level'
# File References
nextStepFile: './step-04-identify-opportunities.md'
---
# Step 3: Calculate Similarity
## STEP GOAL:
Interpret the comparison data, apply weighted scoring to calculate an overall similarity percentage, classify the similarity level, and generate an initial recommendation.
## MANDATORY EXECUTION RULES (READ FIRST):
### Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
### Role Reinforcement:
- ✅ You are the Design System Architect guiding design system creation and maintenance
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
- ✅ Maintain systematic and analytical tone throughout
### Step-Specific Rules:
- 🎯 Focus ONLY on this step's specific goal — do not skip ahead
- 🚫 FORBIDDEN to jump to later steps before this step is complete
- 💬 Approach: Systematic execution with clear reporting
- 📋 All outputs must be documented and presented to user
## EXECUTION PROTOCOLS:
- 🎯 Execute each instruction in the sequence below
- 💾 Document all findings and decisions
- 📖 Present results to user before proceeding
- 🚫 FORBIDDEN to skip instructions or optimize the sequence
## CONTEXT BOUNDARIES:
- Available context: Previous step outputs and project configuration
- Focus: This step's specific goal only
- Limits: Do not perform actions belonging to subsequent steps
- Dependencies: Requires all previous steps to be completed
## Sequence of Instructions (Do not deviate, skip, or optimize)
## Similarity Levels
### Level 1: Identical (95-100%)
**Characteristics:**
- All visual attributes match
- Same functional purpose
- Same behavioral patterns
- Only content differs (labels, text)
**Interpretation:** This is the same component
**Recommendation:** Reuse existing component reference
---
### Level 2: Very High Similarity (80-94%)
**Characteristics:**
- Visual attributes mostly match
- Same core function
- Minor behavioral differences
- Same usage context
**Interpretation:** This is likely the same component with minor variations
**Recommendation:** Consider adding variant to existing component
---
### Level 3: High Similarity (65-79%)
**Characteristics:**
- Visual attributes similar
- Related functional purpose
- Some behavioral differences
- Similar usage context
**Interpretation:** Could be same component or new variant
**Recommendation:** Designer decision needed - variant or new?
---
### Level 4: Medium Similarity (45-64%)
**Characteristics:**
- Some visual overlap
- Different functional purpose
- Different behaviors
- Different usage context
**Interpretation:** Related but distinct components
**Recommendation:** Likely new component, but designer should confirm
---
### Level 5: Low Similarity (20-44%)
**Characteristics:**
- Minimal visual overlap
- Different function
- Different behaviors
- Different context
**Interpretation:** Different components that happen to share a type
**Recommendation:** Create new component
---
### Level 6: No Similarity (<20%)
**Characteristics:**
- No meaningful overlap
- Completely different purpose
- Unrelated patterns
**Interpretation:** Unrelated components
**Recommendation:** Definitely create new component
---
## Calculation Logic
<action>
Calculate overall similarity:
1. Weight each dimension:
- Visual: 30%
- Functional: 30%
- Behavioral: 25%
- Contextual: 15%
2. Convert dimension scores to numeric:
- High = 1.0
- Medium = 0.6
- Low = 0.2
3. Calculate weighted average:
- Overall = (Visual × 0.3) + (Functional × 0.3) + (Behavioral × 0.25) + (Contextual × 0.15)
4. Convert to percentage:
- Similarity % = Overall × 100
</action>
**Example:**
```
Dimension Scores:
- Visual: High (1.0)
- Functional: Medium (0.6)
- Behavioral: Medium (0.6)
- Contextual: Medium (0.6)
Calculation:
(1.0 × 0.3) + (0.6 × 0.3) + (0.6 × 0.25) + (0.6 × 0.15)
= 0.3 + 0.18 + 0.15 + 0.09
= 0.72
Similarity: 72% (High Similarity - Level 3)
```
---
## Step 1: Calculate Score
<action>
Apply calculation logic to comparison data
</action>
<output>
```
📊 Similarity Calculation
Visual: High (1.0) × 30% = 0.30
Functional: Medium (0.6) × 30% = 0.18
Behavioral: Medium (0.6) × 25% = 0.15
Contextual: Medium (0.6) × 15% = 0.09
Overall Similarity: 72%
Level: High Similarity (Level 3)
```
</output>
---
## Step 2: Classify Similarity
<action>
Map percentage to similarity level
</action>
<output>
```
**Similarity Level: High (72%)**
This component is similar to Button [btn-001] but has some differences.
Could be:
- A variant of the existing button
- A new related button component
Designer decision needed.
```
</output>
---
## Step 3: Generate Recommendation
<action>
Based on similarity level, generate recommendation with reasoning
</action>
**For Level 1-2 (Identical/Very High):**
```
✅ Recommendation: Reuse existing component
Reasoning:
- Components are nearly identical
- Only content/labels differ
- Same visual and behavioral patterns
- Maintaining consistency is straightforward
```
**For Level 3 (High):**
```
🤔 Recommendation: Designer decision needed
This could go either way:
- Similar enough to be a variant
- Different enough to be separate
I'll present the trade-offs so you can decide.
```
**For Level 4-5 (Medium/Low):**
```
🆕 Recommendation: Create new component
Reasoning:
- Significant functional differences
- Different usage contexts
- Trying to merge would create complexity
- Better to keep separate
```
**For Level 6 (No similarity):**
```
✅ Recommendation: Definitely create new component
Reasoning:
- Components are fundamentally different
- No meaningful overlap
- No benefit to linking them
```
---
## Step 4: Identify Key Decision Factors
<action>
Highlight the most important differences that affect the decision
</action>
**Example:**
```
🔑 Key Decision Factors:
1. **Icon presence** - Current has icon, existing doesn't
Impact: Visual consistency, component complexity
2. **Loading state** - Current has loading, existing doesn't
Impact: Behavioral complexity, reusability
3. **Navigation vs Submission** - Different purposes
Impact: Semantic meaning, developer understanding
These differences will affect your decision.
```
---
## Step 5: Pass to Next Step
<action>
Pass classification and recommendation to opportunity identification:
- Similarity level
- Recommendation
- Key decision factors
</action>
**Next:** `step-04-identify-opportunities.md`
---
## Edge Cases
**Borderline cases (near threshold):**
```
⚠️ Borderline Case: 64% similarity
This is right on the edge between "High" and "Medium" similarity.
I'll present both perspectives so you can make an informed decision.
```
**Multiple candidates with similar scores:**
```
📊 Multiple Similar Candidates:
Button [btn-001]: 72% similarity
Button [btn-003]: 68% similarity
btn-001 is slightly closer, but both are viable options.
I'll compare to btn-001 for the decision.
```
**Perfect match but different context:**
```
⚠️ Unusual Pattern: 98% similarity but different context
Visually and behaviorally identical, but used in completely different contexts.
This might indicate:
- Same component, different use case ✓
- Accidental duplication ⚠️
- Context-specific variant needed 🤔
````
---
## Output Format
**For next step:**
```json
{
"similarity": {
"percentage": 72,
"level": "high",
"level_number": 3,
"recommendation": "designer_decision",
"key_factors": [
"Icon presence",
"Loading state",
"Navigation vs Submission"
]
}
}
````
### 6. Present MENU OPTIONS
Display: "**Select an Option:** [C] Continue to Identify Opportunities"
#### Menu Handling Logic:
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [C continue option is selected and similarity calculated and classified], will you then load and read fully `{nextStepFile}` to execute the next step.
---
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated
### ❌ SYSTEM FAILURE:
- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

421
_bmad/wds/workflows/7-design-system/steps-c/step-04-identify-opportunities.md Normal file
View File

@@ -0,0 +1,421 @@
---
name: 'step-04-identify-opportunities'
description: 'Identify potential benefits of each design system decision option: reuse, variant, or create new'
# File References
nextStepFile: './step-05-identify-risks.md'
---
# Step 4: Identify Opportunities
## STEP GOAL:
Identify potential benefits of each design system decision option (reuse existing, add variant, create new). Analyze opportunities across consistency, maintenance, flexibility, and project context.
## MANDATORY EXECUTION RULES (READ FIRST):
### Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
### Role Reinforcement:
- ✅ You are the Design System Architect guiding design system creation and maintenance
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
- ✅ Maintain systematic and analytical tone throughout
### Step-Specific Rules:
- 🎯 Focus ONLY on this step's specific goal — do not skip ahead
- 🚫 FORBIDDEN to jump to later steps before this step is complete
- 💬 Approach: Systematic execution with clear reporting
- 📋 All outputs must be documented and presented to user
## EXECUTION PROTOCOLS:
- 🎯 Execute each instruction in the sequence below
- 💾 Document all findings and decisions
- 📖 Present results to user before proceeding
- 🚫 FORBIDDEN to skip instructions or optimize the sequence
## CONTEXT BOUNDARIES:
- Available context: Previous step outputs and project configuration
- Focus: This step's specific goal only
- Limits: Do not perform actions belonging to subsequent steps
- Dependencies: Requires all previous steps to be completed
## Sequence of Instructions (Do not deviate, skip, or optimize)
## Decision Options
For each similar component, there are 3 options:
### Option 1: Reuse Existing Component
Use the existing component reference, just change content
### Option 2: Add Variant to Existing
Extend existing component with new variant
### Option 3: Create New Component
Create separate component in design system
---
## Opportunity Analysis Framework
### For Option 1: Reuse Existing
**Potential Opportunities:**
#### Consistency
- ✅ Visual consistency across pages
- ✅ Behavioral consistency (same interactions)
- ✅ User familiarity (looks/works the same)
- ✅ Brand coherence
#### Maintenance
- ✅ Single source of truth
- ✅ Update once, applies everywhere
- ✅ Easier to maintain
- ✅ Fewer files to manage
#### Development
- ✅ Faster development (component exists)
- ✅ Less code duplication
- ✅ Easier testing (test once)
- ✅ Better performance (reused code)
#### Design System
- ✅ Cleaner design system
- ✅ Fewer components to document
- ✅ Easier for developers to find
- ✅ Simpler component library
---
### For Option 2: Add Variant
**Potential Opportunities:**
#### Flexibility
- ✅ Accommodates different use cases
- ✅ Maintains component family
- ✅ Allows contextual adaptation
- ✅ Supports design evolution
#### Consistency
- ✅ Related components stay connected
- ✅ Shared base styling
- ✅ Consistent naming pattern
- ✅ Clear component relationships
#### Scalability
- ✅ Easy to add more variants later
- ✅ Supports design system growth
- ✅ Handles edge cases gracefully
- ✅ Accommodates future needs
#### Documentation
- ✅ Variants documented together
- ✅ Clear component family
- ✅ Easier to understand relationships
- ✅ Better developer guidance
---
### For Option 3: Create New
**Potential Opportunities:**
#### Clarity
- ✅ Clear separation of concerns
- ✅ Distinct purpose/function
- ✅ No confusion about usage
- ✅ Semantic clarity
#### Simplicity
- ✅ Simpler component definition
- ✅ No complex variant logic
- ✅ Easier to understand
- ✅ Fewer edge cases
#### Independence
- ✅ Can evolve independently
- ✅ No impact on other components
- ✅ Easier to modify
- ✅ No unintended side effects
#### Specificity
- ✅ Optimized for specific use case
- ✅ No unnecessary features
- ✅ Better performance
- ✅ Clearer developer intent
---
## Step 1: Analyze Current Situation
<action>
Based on similarity level and comparison, identify which opportunities apply
</action>
**Example (72% similarity):**
```
Current Situation:
- High visual similarity
- Different functional purpose (navigation vs submission)
- Some behavioral differences (loading state, icon)
- Similar usage context
Applicable Opportunities:
- Reuse: Consistency, maintenance benefits
- Variant: Flexibility, maintains family
- New: Clarity of purpose, independence
```
---
## Step 2: Generate Opportunity Lists
<output>
**Option 1: Reuse Button [btn-001]**
Opportunities:
✅ **Consistency:** All buttons look and behave the same
✅ **Maintenance:** Update button styling once, applies everywhere
✅ **Simplicity:** Fewer components in design system
✅ **Development:** Faster implementation (component exists)
Best if: Visual consistency is more important than functional distinction
</output>
<output>
**Option 2: Add "Navigation" Variant to Button [btn-001]**
Opportunities:
✅ **Flexibility:** Supports both submission and navigation use cases
✅ **Family:** Keeps related buttons together
✅ **Scalability:** Easy to add more button types later
✅ **Documentation:** All button variants in one place
Best if: You want to maintain button family but need different behaviors
</output>
<output>
**Option 3: Create New "Navigation Button" Component**
Opportunities:
✅ **Clarity:** Clear distinction between submission and navigation
✅ **Semantics:** Developers understand purpose immediately
✅ **Independence:** Can evolve without affecting submit buttons
✅ **Optimization:** Tailored for navigation use case
Best if: Functional distinction is more important than visual consistency
</output>
---
## Step 3: Highlight Strongest Opportunities
<action>
Based on comparison data, identify the most compelling opportunities for each option
</action>
**Example:**
```
🌟 Strongest Opportunities:
**For Reuse:**
- Your buttons are 90% visually identical
- Consistency would be very strong
- Maintenance would be significantly easier
**For Variant:**
- You have 2 distinct button purposes emerging
- Variant structure would accommodate both
- Future button types could fit this pattern
**For New:**
- Navigation and submission are semantically different
- Developers would benefit from clear distinction
- Each could evolve independently as needs change
```
---
## Step 4: Consider Project Context
<action>
Factor in project-specific considerations:
- Design system maturity (new vs established)
- Team size (solo vs large team)
- Project complexity (simple vs complex)
- Timeline (fast vs thorough)
</action>
**Example:**
```
📋 Project Context:
Design System: New (3 components so far)
Team: Small (2-3 people)
Complexity: Medium
Timeline: Moderate
Context-Specific Opportunities:
- **New design system:** Easier to keep simple (favors reuse/variant)
- **Small team:** Fewer components = easier maintenance (favors reuse)
- **Medium complexity:** Room for some structure (favors variant)
```
---
## Step 5: Pass to Next Step
<action>
Pass opportunity analysis to risk identification:
- Opportunities for each option
- Strongest opportunities
- Context considerations
</action>
**Next:** `step-05-identify-risks.md`
---
## Edge Cases
**All options have strong opportunities:**
```
✨ All Options Look Good!
Each approach has compelling opportunities:
- Reuse: Strong consistency benefits
- Variant: Good balance of flexibility
- New: Clear semantic distinction
This means the risks will be the deciding factor.
```
**No clear opportunities:**
```
⚠️ No Strong Opportunities Identified
This might mean:
- Components are too different to benefit from connection
- Or too similar to benefit from separation
I'll focus on risks to help clarify the decision.
```
**Conflicting opportunities:**
```
⚠️ Conflicting Opportunities
Reuse offers consistency, but New offers clarity.
These are competing values.
Your design philosophy will guide this decision:
- Value consistency? → Reuse
- Value semantics? → New
```
---
## Output Format
**For next step:**
```json
{
"opportunities": {
"reuse": {
"consistency": "high",
"maintenance": "high",
"development": "medium",
"strongest": ["consistency", "maintenance"]
},
"variant": {
"flexibility": "high",
"family": "medium",
"scalability": "high",
"strongest": ["flexibility", "scalability"]
},
"new": {
"clarity": "high",
"independence": "high",
"specificity": "medium",
"strongest": ["clarity", "independence"]
}
}
}
```
### 8. Present MENU OPTIONS
Display: "**Select an Option:** [C] Continue to Identify Risks"
#### Menu Handling Logic:
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [C continue option is selected and opportunities identified for all three options], will you then load and read fully `{nextStepFile}` to execute the next step.
---
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated
### ❌ SYSTEM FAILURE:
- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

439
_bmad/wds/workflows/7-design-system/steps-c/step-05-identify-risks.md Normal file
View File

@@ -0,0 +1,439 @@
---
name: 'step-05-identify-risks'
description: 'Identify potential risks and problems with each design system decision option'
# File References
nextStepFile: './step-06-present-decision.md'
---
# Step 5: Identify Risks
## STEP GOAL:
Identify potential risks and problems with each design system decision option. Assess severity, identify deal-breakers, and consider mitigation strategies.
## MANDATORY EXECUTION RULES (READ FIRST):
### Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
### Role Reinforcement:
- ✅ You are the Design System Architect guiding design system creation and maintenance
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
- ✅ Maintain systematic and analytical tone throughout
### Step-Specific Rules:
- 🎯 Focus ONLY on this step's specific goal — do not skip ahead
- 🚫 FORBIDDEN to jump to later steps before this step is complete
- 💬 Approach: Systematic execution with clear reporting
- 📋 All outputs must be documented and presented to user
## EXECUTION PROTOCOLS:
- 🎯 Execute each instruction in the sequence below
- 💾 Document all findings and decisions
- 📖 Present results to user before proceeding
- 🚫 FORBIDDEN to skip instructions or optimize the sequence
## CONTEXT BOUNDARIES:
- Available context: Previous step outputs and project configuration
- Focus: This step's specific goal only
- Limits: Do not perform actions belonging to subsequent steps
- Dependencies: Requires all previous steps to be completed
## Sequence of Instructions (Do not deviate, skip, or optimize)
## Risk Analysis Framework
### For Option 1: Reuse Existing
**Potential Risks:**
#### Loss of Distinction
- ❌ Different purposes look identical
- ❌ Users can't distinguish actions
- ❌ Semantic meaning lost
- ❌ Accessibility issues (same label, different action)
#### Constraint
- ❌ Forced to use existing styling
- ❌ Can't optimize for specific use case
- ❌ Future changes constrained
- ❌ Design evolution limited
#### Confusion
- ❌ Developers confused about usage
- ❌ Same component, different behaviors
- ❌ Unclear when to use
- ❌ Documentation complexity
#### Technical Debt
- ❌ Component becomes overloaded
- ❌ Too many conditional behaviors
- ❌ Hard to maintain
- ❌ Performance issues
---
### For Option 2: Add Variant
**Potential Risks:**
#### Complexity
- ❌ Component becomes complex
- ❌ Many variants to manage
- ❌ Harder to understand
- ❌ More documentation needed
#### Maintenance Burden
- ❌ Changes affect all variants
- ❌ Testing becomes complex
- ❌ More edge cases to handle
- ❌ Harder to refactor
#### Variant Explosion
- ❌ Too many variants over time
- ❌ Unclear which variant to use
- ❌ Variants become too specific
- ❌ Component loses coherence
#### Coupling
- ❌ Variants tightly coupled
- ❌ Can't change one without affecting others
- ❌ Shared code creates dependencies
- ❌ Harder to deprecate
---
### For Option 3: Create New
**Potential Risks:**
#### Inconsistency
- ❌ Visual inconsistency across pages
- ❌ Different styling for similar components
- ❌ User confusion
- ❌ Brand fragmentation
#### Duplication
- ❌ Duplicate code
- ❌ Duplicate maintenance
- ❌ Duplicate testing
- ❌ Duplicate documentation
#### Proliferation
- ❌ Too many components in design system
- ❌ Hard to find right component
- ❌ Developers create more duplicates
- ❌ Design system becomes unwieldy
#### Divergence
- ❌ Components drift over time
- ❌ Accidental inconsistencies
- ❌ Harder to maintain coherence
- ❌ More work to keep aligned
---
## Step 1: Analyze Current Situation for Risks
<action>
Based on similarity level and comparison, identify which risks apply
</action>
**Example (72% similarity, different purposes):**
```
Current Situation:
- High visual similarity (90%)
- Different functional purpose (navigation vs submission)
- Some behavioral differences (loading state, icon)
Risk Indicators:
- Reuse: High risk of semantic confusion
- Variant: Medium risk of complexity
- New: Medium risk of visual inconsistency
```
---
## Step 2: Generate Risk Lists
<output>
**Option 1: Reuse Button [btn-001]**
Risks:
❌ **Semantic Confusion:** Navigation and submission look identical
❌ **Accessibility:** Screen readers can't distinguish actions
❌ **Developer Confusion:** Same component, different behaviors
❌ **Future Constraint:** Can't optimize for navigation use case
Highest Risk: Semantic confusion - users won't understand the difference
</output>
<output>
**Option 2: Add "Navigation" Variant to Button [btn-001]**
Risks:
❌ **Complexity:** Button component now handles 2 different purposes
❌ **Maintenance:** Changes to button affect both submission and navigation
❌ **Variant Explosion:** What about other button types? (delete, cancel, etc.)
❌ **Documentation:** Need to explain when to use each variant
Highest Risk: Variant explosion - could lead to 10+ button variants
</output>
<output>
**Option 3: Create New "Navigation Button" Component**
Risks:
❌ **Visual Inconsistency:** Two similar-looking buttons with different names
❌ **Duplication:** Similar code in two components
❌ **Proliferation:** More components in design system
❌ **Developer Choice:** Which button should I use?
Highest Risk: Visual inconsistency - buttons might drift apart over time
</output>
---
## Step 3: Assess Risk Severity
<action>
Rate each risk as Low/Medium/High severity based on:
- Impact if it occurs
- Likelihood of occurring
- Difficulty to fix later
</action>
**Example:**
```
Risk Severity Assessment:
**Reuse Option:**
- Semantic confusion: HIGH (impacts UX, hard to fix)
- Accessibility: HIGH (compliance issue)
- Developer confusion: MEDIUM (documentation can help)
- Future constraint: MEDIUM (can refactor later)
**Variant Option:**
- Complexity: MEDIUM (manageable with good structure)
- Maintenance: MEDIUM (testing helps)
- Variant explosion: HIGH (hard to reverse)
- Documentation: LOW (just needs writing)
**New Option:**
- Visual inconsistency: MEDIUM (can be monitored)
- Duplication: LOW (acceptable trade-off)
- Proliferation: MEDIUM (can be managed)
- Developer choice: LOW (documentation helps)
```
---
## Step 4: Identify Deal-Breaker Risks
<action>
Highlight risks that would make an option unsuitable
</action>
**Example:**
```
🚨 Deal-Breaker Risks:
**Reuse:**
- Semantic confusion is HIGH risk
- Accessibility issue is HIGH risk
→ This option might not be viable
**Variant:**
- Variant explosion is HIGH risk
- But can be mitigated with clear guidelines
→ This option is risky but manageable
**New:**
- No HIGH severity risks identified
- All risks are manageable
→ This option is safest
```
---
## Step 5: Consider Mitigation Strategies
<action>
For each risk, identify if/how it can be mitigated
</action>
**Example:**
```
Risk Mitigation:
**Reuse - Semantic Confusion:**
- Mitigation: Use different labels/icons
- Effectiveness: LOW (still same component)
- Verdict: Hard to mitigate
**Variant - Variant Explosion:**
- Mitigation: Strict variant guidelines
- Effectiveness: MEDIUM (requires discipline)
- Verdict: Can be managed
**New - Visual Inconsistency:**
- Mitigation: Shared design tokens
- Effectiveness: HIGH (tokens ensure consistency)
- Verdict: Easily mitigated
```
---
## Step 6: Pass to Next Step
<action>
Pass risk analysis to decision presentation:
- Risks for each option
- Severity ratings
- Deal-breaker risks
- Mitigation strategies
</action>
**Next:** `step-06-present-decision.md`
---
## Edge Cases
**All options have high risks:**
```
⚠️ All Options Have Significant Risks
This is a tough decision:
- Reuse: Semantic confusion
- Variant: Complexity explosion
- New: Inconsistency
I'll present all trade-offs clearly so you can make an informed choice.
```
**No significant risks:**
```
✅ Low Risk Situation
All options have manageable risks:
- Reuse: Minor constraint
- Variant: Slight complexity
- New: Minimal duplication
Focus on opportunities to decide.
```
**One option has deal-breaker risk:**
```
🚨 One Option Not Recommended
Reuse has HIGH accessibility risk that's hard to mitigate.
I'll present Variant vs New as the viable options.
```
---
## Output Format
**For next step:**
```json
{
"risks": {
"reuse": {
"semantic_confusion": "high",
"accessibility": "high",
"developer_confusion": "medium",
"deal_breaker": true
},
"variant": {
"complexity": "medium",
"variant_explosion": "high",
"maintenance": "medium",
"deal_breaker": false,
"mitigation": "strict_guidelines"
},
"new": {
"visual_inconsistency": "medium",
"duplication": "low",
"proliferation": "medium",
"deal_breaker": false,
"mitigation": "shared_tokens"
}
}
}
```
### 7. Present MENU OPTIONS
Display: "**Select an Option:** [C] Continue to Present Decision"
#### Menu Handling Logic:
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [C continue option is selected and risks identified with severity ratings for all options], will you then load and read fully `{nextStepFile}` to execute the next step.
---
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated
### ❌ SYSTEM FAILURE:
- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

517
_bmad/wds/workflows/7-design-system/steps-c/step-06-present-decision.md Normal file
View File

@@ -0,0 +1,517 @@
---
name: 'step-06-present-decision'
description: 'Present complete analysis to designer with trade-offs for informed decision'
# File References
nextStepFile: './step-07-execute-decision.md'
---
# Step 6: Present Decision
## STEP GOAL:
Present the complete analysis to the designer with clear options, trade-off comparison, AI recommendation, and let the designer make an informed decision.
## MANDATORY EXECUTION RULES (READ FIRST):
### Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
### Role Reinforcement:
- ✅ You are the Design System Architect guiding design system creation and maintenance
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
- ✅ Maintain systematic and analytical tone throughout
### Step-Specific Rules:
- 🎯 Focus ONLY on this step's specific goal — do not skip ahead
- 🚫 FORBIDDEN to jump to later steps before this step is complete
- 💬 Approach: Systematic execution with clear reporting
- 📋 All outputs must be documented and presented to user
## EXECUTION PROTOCOLS:
- 🎯 Execute each instruction in the sequence below
- 💾 Document all findings and decisions
- 📖 Present results to user before proceeding
- 🚫 FORBIDDEN to skip instructions or optimize the sequence
## CONTEXT BOUNDARIES:
- Available context: Previous step outputs and project configuration
- Focus: This step's specific goal only
- Limits: Do not perform actions belonging to subsequent steps
- Dependencies: Requires all previous steps to be completed
## Sequence of Instructions (Do not deviate, skip, or optimize)
## Presentation Structure
### 1. Context Summary
What we're deciding and why
### 2. The Options
Clear description of each choice
### 3. Comparison Table
Side-by-side trade-offs
### 4. Recommendation
AI's suggestion based on analysis
### 5. Designer Choice
Let designer decide
---
## Step 1: Present Context
<output>
```
🔍 Design System Decision Needed
**Current Component:** Navigation Button
**Similar Component Found:** Button [btn-001]
**Similarity:** 72% (High)
**Key Similarities:**
✓ Visual appearance (size, shape, color)
✓ Primary action purpose
✓ Standard states
**Key Differences:**
✗ Navigation vs submission purpose
✗ Has icon and loading state
✗ Different usage context
**Decision:** How should we handle this in the design system?
```
</output>
---
## Step 2: Present Options
<output>
```
📋 Your Options:
**Option 1: Reuse Existing Component**
Use Button [btn-001], just change the label to "Continue"
**Option 2: Add Variant**
Add "navigation" variant to Button [btn-001]
- Button.primary (submit)
- Button.navigation (continue)
**Option 3: Create New Component**
Create separate "Navigation Button" component [btn-002]
```
</output>
---
## Step 3: Present Trade-Offs Table
<output>
```
📊 Trade-Offs Comparison:
┌─────────────┬──────────────────┬──────────────────┬──────────────────┐
│ │ Reuse [btn-001] │ Add Variant │ Create New │
├─────────────┼──────────────────┼──────────────────┼──────────────────┤
│ Consistency │ ✅ Highest │ ✅ High │ ⚠️ Medium │
│ Maintenance │ ✅ Easiest │ ⚠️ Moderate │ ❌ More work │
│ Clarity │ ❌ Confusing │ ⚠️ Moderate │ ✅ Clearest │
│ Flexibility │ ❌ Constrained │ ✅ Flexible │ ✅ Independent │
│ Complexity │ ✅ Simple │ ⚠️ More complex │ ✅ Simple │
│ Semantics │ ❌ Lost │ ⚠️ Preserved │ ✅ Clear │
├─────────────┼──────────────────┼──────────────────┼──────────────────┤
│ Best For │ Identical use │ Related purposes │ Different roles │
└─────────────┴──────────────────┴──────────────────┴──────────────────┘
Legend: ✅ Strong benefit | ⚠️ Trade-off | ❌ Potential issue
```
</output>
---
## Step 4: Present Detailed Analysis
<output>
```
🔍 Detailed Analysis:
**Option 1: Reuse Button [btn-001]**
Opportunities:
✅ Perfect visual consistency
✅ Single source of truth
✅ Easiest to maintain
✅ Simplest design system
Risks:
❌ HIGH: Semantic confusion (navigation looks like submission)
❌ HIGH: Accessibility issues (same component, different actions)
❌ MEDIUM: Developer confusion
❌ MEDIUM: Future constraint
Verdict: ⚠️ Not recommended due to semantic/accessibility risks
---
**Option 2: Add "Navigation" Variant to Button [btn-001]**
Opportunities:
✅ Maintains button family
✅ Flexible for different use cases
✅ Easy to add more variants
✅ All buttons documented together
Risks:
❌ HIGH: Variant explosion (could lead to 10+ variants)
⚠️ MEDIUM: Component complexity increases
⚠️ MEDIUM: Maintenance burden grows
⚠️ LOW: Documentation overhead
Mitigation: Strict variant guidelines can manage explosion risk
Verdict: ✅ Viable option if you expect more button types
---
**Option 3: Create New "Navigation Button" [btn-002]**
Opportunities:
✅ Clear semantic distinction
✅ Optimized for navigation use case
✅ Independent evolution
✅ Simple component definition
Risks:
⚠️ MEDIUM: Visual inconsistency over time
⚠️ MEDIUM: More components to manage
⚠️ LOW: Some code duplication
⚠️ LOW: Developer choice overhead
Mitigation: Shared design tokens ensure visual consistency
Verdict: ✅ Safest option, especially for semantically different purposes
```
</output>
---
## Step 5: Present AI Recommendation
<action>
Based on analysis, provide recommendation with reasoning
</action>
<output>
```
🤖 AI Recommendation: Create New Component (Option 3)
**Reasoning:**
1. **Semantic Distinction Matters**
- Navigation and submission are fundamentally different actions
- Users and developers benefit from clear distinction
- Accessibility is better with separate components
2. **Manageable Risks**
- Visual inconsistency can be prevented with shared tokens
- Duplication is minimal and acceptable
- Proliferation can be monitored
3. **Future Flexibility**
- Each component can evolve independently
- No risk of variant explosion
- Clear component boundaries
4. **Your Project Context**
- Design system is new (only 3 components)
- Better to establish clear patterns now
- Easier to merge later than split
**However:** If you expect many button types (delete, cancel, save, etc.),
Option 2 (variant) might be better for organization.
```
</output>
---
## Step 6: Ask for Designer Decision
<ask>
```
💭 Your Decision:
Based on this analysis, which approach fits your design intent?
[1] Reuse Button [btn-001]
→ Choose if: Visual consistency is paramount, purposes are actually the same
[2] Add "navigation" variant to Button [btn-001]
→ Choose if: You want button family, expect more button types
[3] Create new "Navigation Button" [btn-002]
→ Choose if: Semantic distinction matters, want independence
[4] I need more information
→ I can clarify any aspect of the analysis
Your choice (1/2/3/4):
```
</ask>
---
## Step 7: Handle Designer Response
<action>
Based on designer's choice, route to appropriate operation
</action>
**If Choice 1 (Reuse):**
```
✅ Got it - reusing Button [btn-001]
I'll update the page spec to reference the existing component.
```
**Route to:** `step-07-execute-decision.md` with action: `reuse`
**If Choice 2 (Variant):**
```
✅ Got it - adding "navigation" variant to Button [btn-001]
I'll update the component definition and create the reference.
```
**Route to:** `step-07-execute-decision.md` with action: `add_variant`
**If Choice 3 (New):**
```
✅ Got it - creating new Navigation Button [btn-002]
I'll create the new component and set up the reference.
```
**Route to:** `step-07-execute-decision.md` with action: `create_new`
**If Choice 4 (More Info):**
```
📚 What would you like to know more about?
- Similarity calculation details
- Specific opportunities or risks
- How variants work
- Component boundaries
- Something else
Your question:
```
**Provide clarification, then re-present decision**
---
## Presentation Variations
### For High Similarity (80%+)
<output>
```
✨ These components are very similar!
Similarity: 87%
The main question is: Are they the same thing with different content,
or different things that happen to look similar?
If same thing → Reuse
If different things → Variant or New
```
</output>
### For Low Similarity (40%-)
<output>
```
⚠️ These components are quite different.
Similarity: 38%
They share a type (Button) but serve different purposes.
Creating a new component is likely the best choice.
Would you like to proceed with creating a new component,
or would you like to see the full analysis?
```
</output>
### For Borderline Cases
<output>
```
🤔 This is a borderline case.
Similarity: 64% (right between "High" and "Medium")
This could go either way. I'll present both perspectives:
**Perspective 1: Similar Enough**
[Present variant option]
**Perspective 2: Different Enough**
[Present new component option]
Your design philosophy will guide this decision.
```
</output>
---
## Edge Cases
**Designer asks for recommendation:**
```
Based on the analysis, I recommend Option 3 (Create New).
But this is your design system - you know your project best.
What's most important to you?
- Consistency? → Reuse or Variant
- Clarity? → New
- Flexibility? → Variant
- Simplicity? → Reuse or New
```
**Designer is unsure:**
```
That's okay! This is a judgment call.
Here's a simple heuristic:
If a developer saw both buttons, would they think:
A) "Same button, different label" → Reuse
B) "Related buttons, different purposes" → Variant
C) "Different buttons entirely" → New
What's your gut feeling?
```
**Designer wants to defer decision:**
```
✅ No problem!
I'll create it as a new component for now.
You can always:
- Merge it later if you decide they're the same
- Convert it to a variant if you see a pattern
- Keep it separate if the distinction is valuable
Design systems evolve - this isn't permanent.
````
---
## Output Format
**For next step:**
```json
{
"decision": {
"choice": "create_new",
"component_id": "btn-002",
"reasoning": "Semantic distinction matters",
"designer_notes": "Navigation and submission are different actions"
}
}
````
### 7. Present MENU OPTIONS
Display: "**Select an Option:** [1/2/3/4] Choose option or request more info"
#### Menu Handling Logic:
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [designer has selected an option (1/2/3) and decision is confirmed], will you then load and read fully `{nextStepFile}` to execute the next step.
---
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated
### ❌ SYSTEM FAILURE:
- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

609
_bmad/wds/workflows/7-design-system/steps-c/step-07-execute-decision.md Normal file
View File

@@ -0,0 +1,609 @@
---
name: 'step-07-execute-decision'
description: 'Execute the designer decision: reuse, add variant, or create new component'
# File References
nextStepFile: './step-08a-initialize-design-system.md'
---
# Step 7: Execute Decision
## STEP GOAL:
Execute the designer decision by routing to the appropriate operation: reuse existing component, add variant to existing, or create new component.
## MANDATORY EXECUTION RULES (READ FIRST):
### Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
### Role Reinforcement:
- ✅ You are the Design System Architect guiding design system creation and maintenance
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
- ✅ Maintain systematic and analytical tone throughout
### Step-Specific Rules:
- 🎯 Focus ONLY on this step's specific goal — do not skip ahead
- 🚫 FORBIDDEN to jump to later steps before this step is complete
- 💬 Approach: Systematic execution with clear reporting
- 📋 All outputs must be documented and presented to user
## EXECUTION PROTOCOLS:
- 🎯 Execute each instruction in the sequence below
- 💾 Document all findings and decisions
- 📖 Present results to user before proceeding
- 🚫 FORBIDDEN to skip instructions or optimize the sequence
## CONTEXT BOUNDARIES:
- Available context: Previous step outputs and project configuration
- Focus: This step's specific goal only
- Limits: Do not perform actions belonging to subsequent steps
- Dependencies: Requires all previous steps to be completed
## Sequence of Instructions (Do not deviate, skip, or optimize)
## Execution Paths
### Path A: Reuse Existing Component
Designer chose to use existing component as-is
### Path B: Add Variant
Designer chose to add variant to existing component
### Path C: Create New Component
Designer chose to create new component
---
## Path A: Reuse Existing Component
### Step 1: Confirm Action
<output>
```
✅ Reusing Button [btn-001]
I'll update your page spec to reference the existing component.
````
</output>
### Step 2: Extract Page-Specific Content
<action>
From complete specification, extract:
- Labels/text content
- Page-specific why/purpose
- Error messages
- Contextual information
</action>
**Example:**
```yaml
Page-Specific Content:
- label: "Continue"
- why: "Navigate to next step in onboarding"
- context: "Multi-step form navigation"
````
### Step 3: Create Reference
<action>
Create reference to existing component:
- Component ID: btn-001
- Variant: primary (or whichever applies)
- Page-specific content
</action>
**Output:**
```yaml
# C-UX-Scenarios/onboarding-page.md
Continue Button:
component: Button.primary [btn-001]
why: Navigate to next step in onboarding
label: 'Continue'
```
### Step 4: Update Component Usage
<action>
Update design system component to track usage:
- Add page to "Used In" list
- Increment usage count
</action>
**Update:**
```yaml
# D-Design-System/components/button.md
Used In:
- Login page (login button)
- Signup page (create account button)
- Dashboard (action buttons)
- Onboarding page (continue button) ← Added
```
### Step 5: Complete
<output>
```
✅ Done! Button [btn-001] is now used on onboarding page.
Page spec updated with reference.
Component usage tracked.
```
</output>
**Return to Phase 4**
---
## Path B: Add Variant
### Step 1: Confirm Action
<output>
```
✅ Adding "navigation" variant to Button [btn-001]
I'll update the component definition and create the reference.
````
</output>
### Step 2: Extract Component-Level Info
<action>
From complete specification, extract:
- Variant-specific styling
- Variant-specific states
- Variant-specific behaviors
</action>
**Example:**
```yaml
Navigation Variant:
- icon: arrow-right
- loading_state: true
- hover_animation: icon_shift
````
### Step 3: Update Component Definition
<action>
Add variant to existing component:
- Add to variants list
- Document variant-specific attributes
- Maintain shared attributes
</action>
**Update:**
```yaml
# D-Design-System/components/button.md
Button Component [btn-001]:
variants:
- primary (submit actions)
- secondary (cancel actions)
- navigation (continue/next actions) ← Added
shared_states:
- default, hover, active, disabled
variant_specific:
navigation:
icon: arrow-right
loading_state: true
hover_animation: icon_shift
```
### Step 4: Create Reference
<action>
Create reference with variant specified:
</action>
**Output:**
```yaml
# C-UX-Scenarios/onboarding-page.md
Continue Button:
component: Button.navigation [btn-001] ← Variant specified
why: Navigate to next step in onboarding
label: 'Continue'
```
### Step 5: Update Usage Tracking
<action>
Track variant usage:
</action>
**Update:**
```yaml
# D-Design-System/components/button.md
Variant Usage:
primary: 5 pages
secondary: 3 pages
navigation: 1 page ← Added
```
### Step 6: Complete
<output>
```
✅ Done! Navigation variant added to Button [btn-001].
Component definition updated.
Page spec created with variant reference.
Variant usage tracked.
```
</output>
**Return to Phase 4**
---
## Path C: Create New Component
### Step 1: Confirm Action
<output>
```
✅ Creating new Navigation Button [btn-002]
I'll create the component definition and set up the reference.
```
</output>
### Step 2: Generate Component ID
<action>
Generate unique component ID:
- Check existing IDs
- Increment counter for type
- Format: [type-prefix]-[number]
</action>
**Example:**
```
Existing Button IDs: btn-001
New ID: btn-002
````
### Step 3: Extract Component-Level Info
<action>
From complete specification, extract:
- Visual attributes (size, shape, color)
- States (default, hover, active, disabled, loading)
- Behaviors (interactions, animations)
- Styling (design tokens or Figma reference)
</action>
**Example:**
```yaml
Component-Level Info:
type: Button
purpose: Navigation actions
states: [default, hover, active, disabled, loading]
icon: arrow-right
size: medium
color: blue
shape: rounded
hover_animation: icon_shift
````
### Step 4: Create Component File
<action>
Create new component file using template:
</action>
**Route to:** `step-08b-create-new-component.md`
**Output:**
```yaml
# D-Design-System/components/navigation-button.md
# Navigation Button [btn-002]
**Type:** Interactive
**Purpose:** Navigation actions (continue, next, proceed)
**Library:** shadcn/ui Button (if Mode C)
**Figma:** [Link] (if Mode B)
## States
- default
- hover
- active
- disabled
- loading (with spinner)
## Styling
- Size: medium
- Color: blue primary
- Shape: rounded
- Icon: arrow-right
- Hover: icon shifts right
## Used In
- Onboarding page (continue button)
```
### Step 5: Create Reference
<action>
Create reference in page spec:
</action>
**Output:**
```yaml
# C-UX-Scenarios/onboarding-page.md
Continue Button:
component: NavigationButton [btn-002]
why: Navigate to next step in onboarding
label: 'Continue'
```
### Step 6: Update Design System Index
<action>
Add to design system component list:
</action>
**Update:**
```yaml
# D-Design-System/components/README.md
Components:
- Button [btn-001] - Primary action buttons
- Input Field [inp-001] - Text input fields
- Card [crd-001] - Content cards
- Navigation Button [btn-002] - Navigation actions ← Added
```
### Step 7: Complete
<output>
```
✅ Done! Navigation Button [btn-002] created.
Component file created: D-Design-System/components/navigation-button.md
Page spec created with reference.
Design system index updated.
````
</output>
**Return to Phase 4**
---
## Post-Execution Actions
### Update Project State
<action>
Update project tracking:
- Increment component count
- Update design system status
- Log decision for future reference
</action>
**Example:**
```yaml
# A-Project-Brief/design-system-log.md
2024-12-09: Created Navigation Button [btn-002]
- Reason: Semantic distinction from submit buttons
- Decision: Create new vs variant
- Designer: Chose clarity over consistency
````
### Notify Designer
<output>
```
📊 Design System Update:
Components: 4 (was 3)
Latest: Navigation Button [btn-002]
Your design system is growing! Consider reviewing component
organization when you reach 10+ components.
```
</output>
---
## Error Handling
**If component creation fails:**
```
❌ Error creating component file.
Error: [error message]
Would you like to:
1. Retry
2. Create manually
3. Skip design system for this component
Your choice:
```
**If reference creation fails:**
```
❌ Error updating page spec.
Error: [error message]
Component was created successfully, but page reference failed.
I'll keep the complete spec on the page for now.
```
**If ID conflict:**
```
⚠️ Component ID conflict detected.
btn-002 already exists but with different content.
Generating alternative ID: btn-003
```
---
## Validation
### Before Completing
<action>
Validate execution:
- ✓ Component file created (if new)
- ✓ Component updated (if variant)
- ✓ Page spec has reference
- ✓ Usage tracked
- ✓ Design system index updated
</action>
**If validation fails:**
```
⚠️ Validation Warning:
Some steps may not have completed successfully.
Please review:
- [List of potential issues]
Continue anyway? (y/n)
```
---
## Return to Phase 4
<action>
Return control to Phase 4 orchestration:
- Pass component reference
- Pass page-specific content
- Signal completion
</action>
**Phase 4 continues with:**
- Update page spec with reference
- Continue to next component
- Or complete page specification
---
## Summary Output
<output>
```
✅ Design System Operation Complete
Action: Created new component
Component: Navigation Button [btn-002]
Page: Onboarding page
Reference: NavigationButton [btn-002]
Files Updated:
- D-Design-System/components/navigation-button.md (created)
- C-UX-Scenarios/onboarding-page.md (reference added)
- D-Design-System/components/README.md (index updated)
Next: Continue with next component in Phase 4
```
</output>
---
**This completes the assessment and execution flow. Control returns to Phase 4.**
```
### 5. Present MENU OPTIONS
Display: "**Select an Option:** [C] Continue to next operation"
#### Menu Handling Logic:
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#5-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [decision has been executed and design system updated accordingly], will you then load and read fully `{nextStepFile}` to execute the next step.
---
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated
### ❌ SYSTEM FAILURE:
- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

551
_bmad/wds/workflows/7-design-system/steps-c/step-08a-initialize-design-system.md Normal file
View File

@@ -0,0 +1,551 @@
---
name: 'step-08a-initialize-design-system'
description: 'Create design system folder structure and initialize for the first component'
# File References
nextStepFile: './step-08b-create-new-component.md'
---
# Step 8a: Initialize Design System
## STEP GOAL:
Create the design system folder structure, token placeholders, mode-specific files, and component index. Prepare for the first component addition.
## MANDATORY EXECUTION RULES (READ FIRST):
### Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
### Role Reinforcement:
- ✅ You are the Design System Architect guiding design system creation and maintenance
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
- ✅ Maintain systematic and analytical tone throughout
### Step-Specific Rules:
- 🎯 Focus ONLY on this step's specific goal — do not skip ahead
- 🚫 FORBIDDEN to jump to later steps before this step is complete
- 💬 Approach: Systematic execution with clear reporting
- 📋 All outputs must be documented and presented to user
## EXECUTION PROTOCOLS:
- 🎯 Execute each instruction in the sequence below
- 💾 Document all findings and decisions
- 📖 Present results to user before proceeding
- 🚫 FORBIDDEN to skip instructions or optimize the sequence
## CONTEXT BOUNDARIES:
- Available context: Previous step outputs and project configuration
- Focus: This step's specific goal only
- Limits: Do not perform actions belonging to subsequent steps
- Dependencies: Requires all previous steps to be completed
## Sequence of Instructions (Do not deviate, skip, or optimize)
## Step 1: Confirm Initialization
<output>
```
🎉 Initializing Design System!
This is your first design system component.
I'll create the folder structure and add this component.
Design System Mode: [Custom/Library]
Component Library: [shadcn/Radix/etc. if applicable]
```
</output>
---
## Step 2: Create Folder Structure
<action>
Create design system folders:
```
D-Design-System/
├── components/
├── design-tokens.md (placeholder)
├── component-library-config.md (if Mode C)
└── figma-mappings.md (if Mode B)
```
</action>
<output>
```
📁 Created Design System Structure:
D-Design-System/
├── components/ (empty, ready for first component)
├── design-tokens.md (placeholder)
└── [mode-specific files]
✅ Folder structure ready!
````
</output>
---
## Step 3: Create Design Tokens Placeholder
<action>
Create initial design tokens file:
</action>
**File:** `D-Design-System/design-tokens.md`
```markdown
# Design Tokens
**Status:** To be defined
Design tokens will be extracted as components are added to the design system.
## Token Categories
### Colors
- Primary colors
- Secondary colors
- Semantic colors (success, error, warning, info)
- Neutral colors
### Typography
- Font families
- Font sizes
- Font weights
- Line heights
- Letter spacing
### Spacing
- Spacing scale
- Padding values
- Margin values
- Gap values
### Layout
- Breakpoints
- Container widths
- Grid columns
### Effects
- Shadows
- Border radius
- Transitions
- Animations
---
**Tokens will be populated as components are specified.**
````
---
## Step 4: Create Mode-Specific Files
### If Mode B: Custom Design System
<action>
Create Figma mappings file:
</action>
**File:** `D-Design-System/figma-mappings.md`
```markdown
# Figma Component Mappings
**Figma File:** [To be specified]
**Last Updated:** [Date]
## Component Mappings
Components in this design system are linked to Figma components for visual reference and design handoff.
### Format
```
Component ID → Figma Node ID
[component-id] → figma://file/[file-id]/node/[node-id]
```
## Mappings
[To be populated as components are added]
---
**How to find Figma node IDs:**
1. Select component in Figma
2. Right-click → Copy link to selection
3. Extract node ID from URL
```
### If Mode C: Component Library
<action>
Create component library config:
</action>
**File:** `D-Design-System/component-library-config.md`
````markdown
# Component Library Configuration
**Library:** [shadcn/Radix/MUI/etc.]
**Version:** [Version]
**Installation:** [Installation command]
## Library Components Used
This design system uses components from [Library Name].
### Component Mappings
Format: `WDS Component → Library Component`
[To be populated as components are added]
## Customizations
### Theme Configuration
```json
{
"colors": {},
"typography": {},
"spacing": {},
"borderRadius": {}
}
```
````
[To be updated as design system grows]
## Installation Instructions
```bash
[Installation commands]
```
---
**Library documentation:** [Link]
````
---
## Step 5: Create Component Index
<action>
Create components README:
</action>
**File:** `D-Design-System/components/README.md`
```markdown
# Design System Components
**Total Components:** 1
**Last Updated:** [Date]
## Component List
### Interactive Components
- [First component will be listed here]
### Form Components
[None yet]
### Layout Components
[None yet]
### Content Components
[None yet]
---
## Component Naming Convention
**Format:** `[type]-[number]`
Examples:
- btn-001 (Button)
- inp-001 (Input Field)
- crd-001 (Card)
## Component File Structure
Each component file includes:
- Component ID
- Type and purpose
- Variants (if any)
- States
- Styling/tokens
- Usage tracking
---
**Components are added automatically as they're discovered during specification.**
````
---
## Step 6: Add First Component
<action>
Route to create-new-component operation:
- Pass component specification
- Generate first component ID
- Create component file
</action>
**Route to:** `step-08b-create-new-component.md`
---
## Step 7: Generate Initial Catalog
<action>
Create interactive HTML catalog:
</action>
**Load and execute:** `step-08e-generate-catalog.md`
**Initial catalog includes:**
- Project introduction
- Design tokens (if defined)
- First component showcase
- Getting started guide
- Empty changelog
**Output:**
```
✅ Initial catalog generated
File: D-Design-System/catalog.html
Components: 1
View: file:///path/to/catalog.html
```
---
## Step 8: Update Project Config
<action>
Mark design system as initialized:
</action>
**Update project config:**
```yaml
design_system:
enabled: true
mode: [mode]
initialized: true
initialized_date: [date]
folder: D-Design-System/
first_component: [component-id]
catalog: D-Design-System/catalog.html
```
---
## Success Message
```
✅ Design system initialized
Mode: [mode]
Folder: D-Design-System/
First component: [ComponentType] [[component-id]]
Catalog: D-Design-System/catalog.html
Design system is ready to use.
Components will be extracted automatically as discovered.
Interactive catalog available for viewing.
added to the design system if they're reusable.
Next: Continue with component specification in Phase 4
```
</output>
---
## Validation
<action>
Validate initialization:
- ✓ D-Design-System/ folder exists
- ✓ components/ subfolder exists
- ✓ design-tokens.md created
- ✓ Mode-specific files created
- ✓ Component index created
- ✓ First component added
- ✓ Project config updated
</action>
**If validation fails:**
```
⚠️ Initialization Warning
Some files may not have been created successfully.
Please check:
- [List of missing files]
Would you like to retry initialization? (y/n)
```
---
## Error Handling
**If folder already exists:**
```
⚠️ D-Design-System/ folder already exists.
This shouldn't happen for first component initialization.
Options:
1. Use existing structure (merge)
2. Backup and recreate
3. Cancel initialization
Your choice:
```
**If component creation fails:**
```
❌ Error creating first component.
Error: [error message]
Design system structure was created, but component addition failed.
You can add components manually or retry.
```
**If mode not specified:**
```
⚠️ Design system mode not specified in project config.
Please specify:
1. Custom (Figma-based)
2. Component Library (shadcn/Radix/etc.)
Your choice:
```
---
## Post-Initialization
### Designer Guidance
<output>
```
💡 Design System Tips:
**What happens next:**
- As you specify components, I'll check for similarities
- Reusable components will be added to the design system
- You'll make decisions about variants vs new components
**Best practices:**
- Be consistent with component boundaries
- Think about reusability early
- Don't over-engineer - start simple
**You can always:**
- Add components manually
- Refactor the design system
- Merge or split components later
Design systems evolve - this is just the beginning!
```
</output>
---
## Return to Workflow
<action>
Return to design system router:
- Signal initialization complete
- Pass first component reference
- Continue with component addition
</action>
**Router continues with:** Adding first component to design system
---
**This operation runs once per project. Subsequent components use create-new-component or add-variant operations.**
```
### 9. Present MENU OPTIONS
Display: "**Select an Option:** [C] Continue to Create First Component"
#### Menu Handling Logic:
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#9-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [C continue option is selected and design system structure is initialized], will you then load and read fully `{nextStepFile}` to execute the next step.
---
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated
### ❌ SYSTEM FAILURE:
- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

795
_bmad/wds/workflows/7-design-system/steps-c/step-08b-create-new-component.md Normal file
View File

@@ -0,0 +1,795 @@
---
name: 'step-08b-create-new-component'
description: 'Add a new component to the design system with full specification'
# File References
nextStepFile: './step-08c-update-component.md'
---
# Step 8b: Create New Component
## STEP GOAL:
Add a new component to the design system: generate ID, determine category, extract attributes, create component file from template, update index and stats.
## MANDATORY EXECUTION RULES (READ FIRST):
### Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
### Role Reinforcement:
- ✅ You are the Design System Architect guiding design system creation and maintenance
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
- ✅ Maintain systematic and analytical tone throughout
### Step-Specific Rules:
- 🎯 Focus ONLY on this step's specific goal — do not skip ahead
- 🚫 FORBIDDEN to jump to later steps before this step is complete
- 💬 Approach: Systematic execution with clear reporting
- 📋 All outputs must be documented and presented to user
## EXECUTION PROTOCOLS:
- 🎯 Execute each instruction in the sequence below
- 💾 Document all findings and decisions
- 📖 Present results to user before proceeding
- 🚫 FORBIDDEN to skip instructions or optimize the sequence
## CONTEXT BOUNDARIES:
- Available context: Previous step outputs and project configuration
- Focus: This step's specific goal only
- Limits: Do not perform actions belonging to subsequent steps
- Dependencies: Requires all previous steps to be completed
## Sequence of Instructions (Do not deviate, skip, or optimize)
## Step 1: Generate Component ID
<action>
Generate unique component ID:
1. Determine component type prefix
2. Check existing IDs for that type
3. Increment counter
4. Format: [prefix]-[number]
</action>
**Type Prefixes:**
```
Button → btn
Input Field → inp
Card → crd
Modal → mdl
Dropdown → drp
Checkbox → chk
Radio → rad
Toggle → tgl
Tab → tab
Accordion → acc
Alert → alt
Badge → bdg
Avatar → avt
Icon → icn
Image → img
Link → lnk
Text → txt
Heading → hdg
List → lst
Table → tbl
Form → frm
Container → cnt
Grid → grd
Flex → flx
Divider → div
Spacer → spc
```
**Example:**
```
Component Type: Button
Existing Button IDs: btn-001, btn-002
New ID: btn-003
```
<output>
```
🆔 Generated Component ID: btn-003
```
</output>
---
## Step 2: Determine Component Category
<action>
Categorize component for organization:
- Interactive (buttons, links, controls)
- Form (inputs, selects, checkboxes)
- Layout (containers, grids, dividers)
- Content (text, images, media)
- Feedback (alerts, toasts, modals)
- Navigation (tabs, breadcrumbs, menus)
</action>
**Example:**
```
Component: Button
Category: Interactive
```
---
## Step 3: Extract Component-Level Information
<action>
From complete specification, extract component-level info:
**Visual Attributes:**
- Size (small, medium, large)
- Shape (rounded, square, pill)
- Color scheme
- Typography
- Spacing/padding
- Border style
**Behavioral Attributes:**
- States (default, hover, active, disabled, loading, error)
- Interactions (click, hover, focus, blur)
- Animations/transitions
- Keyboard support
- Accessibility attributes
**Functional Attributes:**
- Purpose/role
- Input/output type
- Validation rules
- Required/optional
**Design System Attributes:**
- Variants (if any)
- Design tokens used
- Figma reference (if Mode B)
- Library component (if Mode C)
</action>
---
## Step 4: Create Component File
<action>
Use component template to create file:
</action>
**File:** `D-Design-System/components/[component-name].md`
**Template Structure:**
````markdown
# [Component Name] [component-id]
**Type:** [Interactive/Form/Layout/Content/Feedback/Navigation]
**Category:** [Specific category]
**Purpose:** [Brief description]
---
## Overview
[Component description and when to use it]
---
## Variants
[If component has variants, list them]
**Example:**
- primary - Main call-to-action
- secondary - Secondary actions
- ghost - Subtle actions
[If no variants:]
This component has no variants.
---
## States
**Required States:**
- default
- hover
- active
- disabled
**Optional States:**
- loading
- error
- success
- focus
**State Descriptions:**
[Describe what each state looks like/does]
---
## Styling
### Visual Properties
**Size:** [small/medium/large or specific values]
**Shape:** [rounded/square/pill or specific border-radius]
**Colors:** [Color tokens or values]
**Typography:** [Font tokens or values]
**Spacing:** [Padding/margin values]
### Design Tokens
[If using design tokens:]
```yaml
colors:
background: primary-500
text: white
border: primary-600
typography:
font-size: text-base
font-weight: semibold
spacing:
padding-x: 4
padding-y: 2
effects:
border-radius: md
shadow: sm
```
````
### Figma Reference
[If Mode B - Custom Design System:]
**Figma Component:** [Link to Figma component]
**Node ID:** [Figma node ID]
**Last Synced:** [Date]
### Library Component
[If Mode C - Component Library:]
**Library:** [shadcn/Radix/etc.]
**Component:** [Library component name]
**Customizations:** [Any overrides from library default]
---
## Behavior
### Interactions
**Click:**
[What happens on click]
**Hover:**
[What happens on hover]
**Focus:**
[What happens on focus]
**Keyboard:**
[Keyboard shortcuts/navigation]
### Animations
[If component has animations:]
- [Animation description]
- Duration: [ms]
- Easing: [easing function]
---
## Accessibility
**ARIA Attributes:**
- role: [role]
- aria-label: [label]
- aria-disabled: [when disabled]
- [Other ARIA attributes]
**Keyboard Support:**
- Enter/Space: [action]
- Tab: [navigation]
- [Other keyboard support]
**Screen Reader:**
[How screen readers should announce this component]
---
## Usage
### When to Use
[Guidelines for when this component is appropriate]
### When Not to Use
[Guidelines for when to use a different component]
### Best Practices
- [Best practice 1]
- [Best practice 2]
- [Best practice 3]
---
## Used In
**Pages:** [List of pages using this component]
**Usage Count:** [Number]
**Examples:**
- [Page name] - [Specific usage]
- [Page name] - [Specific usage]
---
## Related Components
[If this component is related to others:]
- [Related component 1] - [Relationship]
- [Related component 2] - [Relationship]
---
## Version History
**Created:** [Date]
**Last Updated:** [Date]
**Changes:**
- [Date]: Created component
- [Date]: [Change description]
---
## Notes
[Any additional notes, considerations, or future plans]
````
---
## Step 5: Populate Template
<action>
Fill template with extracted information:
</action>
**Example Output:**
```markdown
# Button [btn-003]
**Type:** Interactive
**Category:** Action
**Purpose:** Trigger primary and secondary actions
---
## Overview
Buttons are used to trigger actions. They should have clear, action-oriented labels that describe what will happen when clicked.
Use buttons for important actions that change state or navigate to new content.
---
## Variants
- **primary** - Main call-to-action (submit, save, continue)
- **secondary** - Secondary actions (cancel, back)
- **ghost** - Subtle actions (close, dismiss)
---
## States
**Required States:**
- default - Normal state
- hover - Mouse over button
- active - Button being clicked
- disabled - Button cannot be clicked
**Optional States:**
- loading - Action in progress (shows spinner)
**State Descriptions:**
**Default:** Blue background, white text, medium size
**Hover:** Darker blue background, slight scale increase
**Active:** Even darker blue, slight scale decrease
**Disabled:** Gray background, gray text, reduced opacity
**Loading:** Disabled state + spinner icon
---
## Styling
### Visual Properties
**Size:** medium (h-10, px-4)
**Shape:** rounded (border-radius: 0.375rem)
**Colors:**
- Background: blue-600
- Text: white
- Border: none
**Typography:**
- Font size: 14px
- Font weight: 600
- Line height: 1.5
**Spacing:**
- Padding X: 16px
- Padding Y: 8px
- Gap (if icon): 8px
### Design Tokens
```yaml
colors:
primary:
background: blue-600
hover: blue-700
active: blue-800
text: white
typography:
size: text-sm
weight: semibold
spacing:
padding-x: 4
padding-y: 2
gap: 2
effects:
border-radius: md
shadow: sm
transition: all 150ms ease
````
### Library Component
**Library:** shadcn/ui
**Component:** Button
**Customizations:** None (using library defaults)
---
## Behavior
### Interactions
**Click:**
Triggers associated action (form submit, navigation, etc.)
**Hover:**
- Background darkens
- Slight scale increase (1.02)
- Cursor changes to pointer
**Focus:**
- Blue outline ring
- Maintains hover state
**Keyboard:**
- Enter/Space triggers click
- Tab navigates to/from button
### Animations
**Hover Scale:**
- Duration: 150ms
- Easing: ease-in-out
- Scale: 1.02
**Click Feedback:**
- Duration: 100ms
- Scale: 0.98
---
## Accessibility
**ARIA Attributes:**
- role: button
- aria-label: [Descriptive label if icon-only]
- aria-disabled: true [when disabled]
- aria-busy: true [when loading]
**Keyboard Support:**
- Enter/Space: Triggers button action
- Tab: Moves focus to/from button
**Screen Reader:**
Announces button label and state (disabled, busy, etc.)
---
## Usage
### When to Use
- Primary actions (submit forms, save data, proceed to next step)
- Secondary actions (cancel, go back, dismiss)
- Triggering modals or dialogs
- Navigation to new pages/sections
### When Not to Use
- For navigation that looks like text (use Link component)
- For toggling states (use Toggle or Checkbox)
- For selecting from options (use Radio or Checkbox)
### Best Practices
- Use action-oriented labels ("Save Changes" not "Save")
- Limit primary buttons to one per section
- Place primary button on the right in button groups
- Ensure sufficient touch target size (min 44x44px)
- Provide loading state for async actions
---
## Used In
**Pages:** 1
**Usage Count:** 1
**Examples:**
- Login page - Submit credentials button
---
## Related Components
- Link [lnk-001] - For text-style navigation
- Icon Button [btn-002] - For icon-only actions
---
## Version History
**Created:** 2024-12-09
**Last Updated:** 2024-12-09
**Changes:**
- 2024-12-09: Created component
---
## Notes
This is the primary button component. Consider adding more variants as needs emerge (danger, success, etc.).
````
---
## Step 6: Update Component Index
<action>
Add component to index:
</action>
**Update:** `D-Design-System/components/README.md`
```markdown
## Component List
### Interactive Components
- Button [btn-001] - Primary action buttons
- Icon Button [btn-002] - Icon-only actions
- Button [btn-003] - Standard action button ← Added
**Total Interactive:** 3
````
---
## Step 7: Update Design System Stats
<action>
Update design system statistics:
</action>
**Update:** `D-Design-System/README.md` (if exists)
```yaml
**Total Components:** 4 (was 3)
**Last Updated:** [Date]
**Latest Addition:** Button [btn-003]
```
---
## Step 8: Create Component Reference
<action>
Generate reference for page spec:
</action>
**Output:**
```yaml
component_reference:
id: btn-003
name: Button
variant: primary
file: D-Design-System/components/button.md
```
---
## Step 9: Complete
<output>
```
✅ Component Created: Button [btn-003]
File: D-Design-System/components/button.md
Category: Interactive
Variants: primary, secondary, ghost
States: default, hover, active, disabled, loading
Component index updated.
Design system stats updated.
Reference ready for page spec.
Next: Return to Phase 4 to complete page specification
```
</output>
---
## Validation
<action>
Validate component creation:
- ✓ Component file created
- ✓ Component ID unique
- ✓ Template fully populated
- ✓ Index updated
- ✓ Stats updated
- ✓ Reference generated
</action>
---
## Error Handling
**If ID conflict:**
```
⚠️ Component ID btn-003 already exists.
Generating alternative ID: btn-004
```
**If file creation fails:**
```
❌ Error creating component file.
Error: [error message]
Would you like to:
1. Retry
2. Create with different ID
3. Skip design system for this component
Your choice:
```
**If template population incomplete:**
```
⚠️ Some component information is missing.
Missing:
- [List of missing fields]
I'll create the component with placeholders.
You can fill in details later.
```
---
**This operation creates a new component. Return to Phase 4 with component reference.**
```
### 10. Present MENU OPTIONS
Display: "**Select an Option:** [C] Continue or [M] Return to Activity Menu"
#### Menu Handling Logic:
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#10-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [component is created with full specification, index updated, and reference generated], will you then load and read fully `{nextStepFile}` to execute the next step.
---
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated
### ❌ SYSTEM FAILURE:
- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

665
_bmad/wds/workflows/7-design-system/steps-c/step-08c-update-component.md Normal file
View File

@@ -0,0 +1,665 @@
---
name: 'step-08c-update-component'
description: 'Update an existing component definition with new states, styling, or behavior'
# File References
nextStepFile: './step-08d-add-variant.md'
---
# Step 8c: Update Component
## STEP GOAL:
Update an existing component definition: identify update type, analyze impact, apply changes, track version history, notify affected pages.
## MANDATORY EXECUTION RULES (READ FIRST):
### Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
### Role Reinforcement:
- ✅ You are the Design System Architect guiding design system creation and maintenance
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
- ✅ Maintain systematic and analytical tone throughout
### Step-Specific Rules:
- 🎯 Focus ONLY on this step's specific goal — do not skip ahead
- 🚫 FORBIDDEN to jump to later steps before this step is complete
- 💬 Approach: Systematic execution with clear reporting
- 📋 All outputs must be documented and presented to user
## EXECUTION PROTOCOLS:
- 🎯 Execute each instruction in the sequence below
- 💾 Document all findings and decisions
- 📖 Present results to user before proceeding
- 🚫 FORBIDDEN to skip instructions or optimize the sequence
## CONTEXT BOUNDARIES:
- Available context: Previous step outputs and project configuration
- Focus: This step's specific goal only
- Limits: Do not perform actions belonging to subsequent steps
- Dependencies: Requires all previous steps to be completed
## Sequence of Instructions (Do not deviate, skip, or optimize)
## Step 1: Identify Update Type
<action>
Determine what's being updated:
</action>
**Update Types:**
### Type A: Add New State
Adding state to all variants (e.g., loading, error, success)
### Type B: Update Styling
Changing visual properties (colors, sizing, spacing)
### Type C: Update Behavior
Changing interactions, animations, or keyboard support
### Type D: Update Accessibility
Adding/modifying ARIA attributes or screen reader support
### Type E: Update Documentation
Clarifying usage, adding examples, fixing errors
### Type F: Refactor
Reorganizing component structure, splitting/merging variants
<ask>
```
What type of update is this?
[A] Add new state
[B] Update styling
[C] Update behavior
[D] Update accessibility
[E] Update documentation
[F] Refactor component
Your choice:
```
</ask>
---
## Step 2: Load Current Component
<action>
Read existing component file:
- Current definition
- All variants
- Current states
- Current styling
- Usage tracking
</action>
<output>
```
📖 Loaded Button [btn-001]
Current state:
- Variants: 3 (primary, secondary, navigation)
- States: default, hover, active, disabled
- Used in: 9 pages
- Last updated: 2024-12-09
```
</output>
---
## Step 3: Analyze Impact
<action>
Determine impact of update:
</action>
**Impact Assessment:**
### Scope
- All variants affected?
- Specific variant only?
- All instances affected?
- Specific usage only?
### Breaking Changes
- Does this change existing behavior?
- Will existing pages need updates?
- Does this affect developers?
### Compatibility
- Compatible with current usage?
- Requires page spec updates?
- Requires code changes?
<output>
```
📊 Impact Analysis:
Update: Adding "loading" state to all button variants
Scope: All variants (primary, secondary, navigation)
Affected Pages: 9 pages using Button component
Breaking Change: No (additive only)
Compatibility: Fully compatible (optional state)
Impact Level: Low (safe to proceed)
```
</output>
---
## Step 4: Confirm Update
<ask>
```
Ready to update Button [btn-001]
Update: Add "loading" state
Impact: 9 pages (no breaking changes)
This will:
✓ Add loading state to component definition
✓ Update all variant documentation
✓ Maintain backward compatibility
Proceed with update? (y/n)
````
</ask>
---
## Step 5: Apply Update
<action>
Update component file based on type:
</action>
### Type A: Add New State
**Update States Section:**
**Before:**
```markdown
## States
**Shared States:**
- default
- hover
- active
- disabled
````
**After:**
```markdown
## States
**Shared States:**
- default
- hover
- active
- disabled
- loading ← Added
**State Descriptions:**
**Loading:**
- Disabled interaction
- Shows spinner icon
- Maintains button size
- Reduced opacity (0.7)
```
**Update Variant-Specific Sections (if needed):**
```markdown
### Variant-Specific Styling
**Navigation (loading state):**
- Spinner + arrow icon
- Arrow fades out during loading
```
### Type B: Update Styling
**Update Styling Section:**
**Before:**
```markdown
### Visual Properties
**Border Radius:** 0.375rem (md)
```
**After:**
```markdown
### Visual Properties
**Border Radius:** 0.5rem (lg) ← Updated
**Change Reason:** Increased for better visual consistency with other components
```
### Type C: Update Behavior
**Update Behavior Section:**
**Before:**
```markdown
### Keyboard
- Enter/Space: Triggers button action
- Tab: Moves focus to/from button
```
**After:**
```markdown
### Keyboard
- Enter/Space: Triggers button action
- Tab: Moves focus to/from button
- Escape: Cancels action (if in progress) ← Added
```
### Type D: Update Accessibility
**Update Accessibility Section:**
**Before:**
```markdown
**ARIA Attributes:**
- role: button
- aria-disabled: true [when disabled]
```
**After:**
```markdown
**ARIA Attributes:**
- role: button
- aria-disabled: true [when disabled]
- aria-busy: true [when loading] ← Added
- aria-live: polite [for status updates] ← Added
```
### Type E: Update Documentation
**Update Usage Section:**
**Before:**
```markdown
### When to Use
- Primary actions
- Secondary actions
```
**After:**
```markdown
### When to Use
- Primary actions (submit forms, save data, proceed to next step)
- Secondary actions (cancel, go back, dismiss)
- Triggering modals or dialogs ← Added
- Navigation to new pages/sections ← Added
### When Not to Use
- For navigation that looks like text (use Link component) ← Added
- For toggling states (use Toggle or Checkbox) ← Added
```
### Type F: Refactor
**Example: Split variant into separate component**
```markdown
## Refactoring Note
**Date:** 2024-12-09
**Change:** Moved "icon-only" variant to separate Icon Button component
**Reason:** Icon-only buttons have significantly different:
- Visual structure (no text)
- Accessibility requirements (requires aria-label)
- Usage patterns (toolbars, compact spaces)
**Migration:**
- Old: Button.icon-only [btn-001]
- New: Icon Button [btn-002]
**Affected Pages:** 5 pages
**Migration Status:** Complete
```
---
## Step 6: Update Version History
<action>
Track update in version history:
</action>
**Update:**
```markdown
## Version History
**Created:** 2024-12-01
**Last Updated:** 2024-12-09
**Changes:**
- 2024-12-01: Created component
- 2024-12-05: Added navigation variant
- 2024-12-09: Added loading state to all variants ← Added
```
---
## Step 7: Notify Affected Pages
<action>
If update affects existing usage, create notification:
</action>
<output>
```
📢 Component Update Notification
Component: Button [btn-001]
Update: Added loading state
Affected Pages: 9
Pages using this component:
- Login page
- Signup page
- Dashboard
- [... 6 more]
Action Required: None (backward compatible)
Optional: Consider using loading state for async actions
Documentation: See Button component for loading state usage
````
</output>
---
## Step 8: Update Design System Stats
<action>
Update design system metadata:
</action>
**Update:** `D-Design-System/README.md`
```markdown
**Last Updated:** 2024-12-09
**Recent Changes:**
- Button [btn-001]: Added loading state
````
---
## Step 9: Complete
<output>
```
✅ Component Updated: Button [btn-001]
Update Type: Add new state
Changes:
- Added "loading" state to all variants
- Updated state documentation
- Version history updated
Impact:
- 9 pages affected
- No breaking changes
- Backward compatible
Next Steps:
- Pages can optionally use new loading state
- No immediate action required
- Consider updating high-traffic pages first
```
</output>
---
## Validation
<action>
Validate update:
- ✓ Component file updated
- ✓ Changes documented
- ✓ Version history updated
- ✓ Impact assessed
- ✓ Notifications sent (if needed)
- ✓ Backward compatibility maintained
</action>
---
## Error Handling
**If update creates breaking change:**
```
⚠️ Breaking Change Detected
This update will break existing usage:
- [List of breaking changes]
- Affected pages: [count]
Breaking changes require:
1. Designer confirmation
2. Migration plan
3. Page spec updates
Proceed with breaking change? (y/n)
If yes, I'll create a migration checklist.
```
**If component file locked:**
```
⚠️ Component file is being edited elsewhere.
Component: Button [btn-001]
Status: Locked by [user/process]
Options:
1. Wait and retry
2. Force update (may cause conflicts)
3. Cancel update
Your choice:
```
**If update conflicts with variants:**
```
⚠️ Update Conflict Detected
You're trying to add "loading" state to all variants,
but "navigation" variant already has a different loading implementation.
Current navigation loading: Spinner + icon animation
Proposed loading: Spinner only
Options:
1. Override navigation variant (make consistent)
2. Keep navigation variant different (document exception)
3. Cancel update
Your choice:
````
---
## Post-Update Actions
### If Breaking Change
<action>
Create migration checklist:
</action>
**Output:**
```markdown
# Migration Checklist: Button [btn-001] Update
**Update:** [Description]
**Breaking Changes:** [List]
**Affected Pages:** [Count]
## Migration Steps
- [ ] Review all affected pages
- [ ] Update page specifications
- [ ] Test updated pages
- [ ] Update documentation
- [ ] Deploy changes
## Affected Pages
- [ ] Login page - [Specific changes needed]
- [ ] Signup page - [Specific changes needed]
- [ ] Dashboard - [Specific changes needed]
[... more pages]
## Rollback Plan
If issues arise:
1. Revert component file to previous version
2. Restore page specifications
3. Document issues encountered
````
### If Major Update
<action>
Suggest design system review:
</action>
<output>
```
💡 Design System Health Check Recommended
This is a significant update to a widely-used component.
Consider reviewing:
- Component consistency across design system
- Other components that might need similar updates
- Overall design system patterns
Schedule a design system review session?
```
</output>
---
**This operation updates a component. Changes apply to all future usage automatically.**
```
### 10. Present MENU OPTIONS
Display: "**Select an Option:** [C] Continue or [M] Return to Activity Menu"
#### Menu Handling Logic:
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#10-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [component is updated, version history tracked, and affected pages notified], will you then load and read fully `{nextStepFile}` to execute the next step.
---
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated
### ❌ SYSTEM FAILURE:
- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

574
_bmad/wds/workflows/7-design-system/steps-c/step-08d-add-variant.md Normal file
View File

@@ -0,0 +1,574 @@
---
name: 'step-08d-add-variant'
description: 'Add a new variant to an existing component in the design system'
# File References
nextStepFile: './step-08e-generate-catalog.md'
---
# Step 8d: Add Variant
## STEP GOAL:
Add a new variant to an existing component: extract variant-specific info, determine name, update component file, track usage, validate addition.
## MANDATORY EXECUTION RULES (READ FIRST):
### Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
### Role Reinforcement:
- ✅ You are the Design System Architect guiding design system creation and maintenance
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
- ✅ Maintain systematic and analytical tone throughout
### Step-Specific Rules:
- 🎯 Focus ONLY on this step's specific goal — do not skip ahead
- 🚫 FORBIDDEN to jump to later steps before this step is complete
- 💬 Approach: Systematic execution with clear reporting
- 📋 All outputs must be documented and presented to user
## EXECUTION PROTOCOLS:
- 🎯 Execute each instruction in the sequence below
- 💾 Document all findings and decisions
- 📖 Present results to user before proceeding
- 🚫 FORBIDDEN to skip instructions or optimize the sequence
## CONTEXT BOUNDARIES:
- Available context: Previous step outputs and project configuration
- Focus: This step's specific goal only
- Limits: Do not perform actions belonging to subsequent steps
- Dependencies: Requires all previous steps to be completed
## Sequence of Instructions (Do not deviate, skip, or optimize)
## Step 1: Load Existing Component
<action>
Read existing component file:
- Component ID
- Current variants
- Shared attributes
- Variant-specific attributes
</action>
**Example:**
```yaml
Component: Button [btn-001]
Current Variants:
- primary (submit actions)
- secondary (cancel actions)
```
<output>
```
📖 Loaded Button [btn-001]
Current variants: 2 (primary, secondary)
Adding new variant: navigation
````
</output>
---
## Step 2: Extract Variant-Specific Information
<action>
From new component specification, extract:
- What's different from existing variants?
- What's shared with existing variants?
- Variant-specific styling
- Variant-specific behaviors
- Variant-specific states (if any)
</action>
**Example:**
```yaml
Shared with existing:
- Size: medium
- Shape: rounded
- Base states: default, hover, active, disabled
Different from existing:
- Has icon (arrow-right)
- Has loading state
- Icon animation on hover
- Purpose: navigation vs submission
````
---
## Step 3: Determine Variant Name
<action>
Generate descriptive variant name:
- Based on purpose or visual distinction
- Consistent with existing variant naming
- Clear and semantic
</action>
**Examples:**
```
Purpose-based:
- navigation (for navigation actions)
- destructive (for delete/remove actions)
- success (for positive confirmations)
Visual-based:
- outlined (border, no fill)
- ghost (transparent background)
- large (bigger size)
Context-based:
- header (used in headers)
- footer (used in footers)
- inline (used inline with text)
```
<ask>
```
Suggested variant name: "navigation"
This variant is for navigation actions (continue, next, proceed).
Is this name clear and appropriate? (y/n)
Or suggest alternative name:
````
</ask>
---
## Step 4: Update Component File
<action>
Add variant to component definition:
</action>
### Update Variants Section
**Before:**
```markdown
## Variants
- **primary** - Main call-to-action (submit, save, continue)
- **secondary** - Secondary actions (cancel, back)
````
**After:**
```markdown
## Variants
- **primary** - Main call-to-action (submit, save, continue)
- **secondary** - Secondary actions (cancel, back)
- **navigation** - Navigation actions (next, proceed, continue) ← Added
```
### Add Variant-Specific Styling
**Add section:**
```markdown
### Variant-Specific Styling
**Primary:**
- Background: blue-600
- Icon: none
- Loading: spinner only
**Secondary:**
- Background: gray-200
- Text: gray-900
- Icon: none
**Navigation:** ← Added
- Background: blue-600
- Icon: arrow-right
- Loading: spinner + icon
- Hover: icon shifts right
```
### Update States (if variant has unique states)
**If navigation variant has loading state but others don't:**
```markdown
## States
**Shared States (all variants):**
- default
- hover
- active
- disabled
**Variant-Specific States:**
**Navigation:**
- loading (shows spinner, disables interaction)
```
---
## Step 5: Update Usage Tracking
<action>
Track new variant usage:
</action>
**Add to component file:**
```markdown
## Variant Usage
**Primary:** 5 pages
**Secondary:** 3 pages
**Navigation:** 1 page ← Added
**Navigation variant used in:**
- Onboarding page (continue button)
```
---
## Step 6: Update Component Complexity Note
<action>
Add note about variant count:
</action>
**If this is 3rd+ variant:**
```markdown
## Notes
This component now has 3 variants. Consider:
- Are all variants necessary?
- Should any variants be separate components?
- Is the component becoming too complex?
Review component organization when reaching 5+ variants.
```
---
## Step 7: Validate Variant Addition
<action>
Check for potential issues:
</action>
**Variant Explosion Check:**
```
⚠️ Variant Count: 3
This is manageable. Monitor for variant explosion as more are added.
Recommended maximum: 5 variants per component
```
**Consistency Check:**
```
✓ New variant consistent with existing variants
✓ Naming convention followed
✓ Shared attributes maintained
```
**Complexity Check:**
```
⚠️ Navigation variant adds loading state not present in other variants.
This increases component complexity. Consider:
- Should loading state be shared across all variants?
- Or is it truly navigation-specific?
Current approach: Variant-specific (acceptable)
```
---
## Step 8: Update Component Version
<action>
Track component changes:
</action>
**Update version history:**
```markdown
## Version History
**Created:** 2024-12-01
**Last Updated:** 2024-12-09
**Changes:**
- 2024-12-01: Created component with primary and secondary variants
- 2024-12-09: Added navigation variant ← Added
```
---
## Step 9: Create Component Reference
<action>
Generate reference for page spec:
</action>
**Output:**
```yaml
component_reference:
id: btn-001
name: Button
variant: navigation ← New variant
file: D-Design-System/components/button.md
```
---
## Step 10: Complete
<output>
```
✅ Variant Added: Button.navigation [btn-001]
Component: Button [btn-001]
New Variant: navigation
Total Variants: 3 (primary, secondary, navigation)
Component file updated:
- Variant added to list
- Variant-specific styling documented
- Usage tracking added
- Version history updated
Reference ready for page spec.
Next: Return to Phase 4 to complete page specification
```
</output>
---
## Designer Guidance
<output>
```
💡 Variant Management Tips:
**Current Status:**
- Component: Button [btn-001]
- Variants: 3
- Status: Healthy
**Watch for:**
- 5+ variants → Consider splitting component
- Variants with very different purposes → Might need separate components
- Variants rarely used together → Might indicate separate components
**Best Practices:**
- Keep variants related (same base purpose)
- Use clear, semantic variant names
- Document when to use each variant
- Review variant list periodically
You can always refactor later if needed!
```
</output>
---
## Validation
<action>
Validate variant addition:
- ✓ Variant added to component file
- ✓ Variant-specific attributes documented
- ✓ Usage tracking updated
- ✓ Version history updated
- ✓ Reference generated
- ✓ Complexity checked
</action>
---
## Error Handling
**If variant name conflicts:**
```
⚠️ Variant "navigation" already exists in Button [btn-001].
This might mean:
1. You're trying to add a duplicate
2. The existing variant should be updated
3. A different variant name is needed
Current navigation variant:
[Show existing variant details]
Options:
1. Update existing variant
2. Choose different name
3. Cancel
Your choice:
```
**If component file not found:**
```
❌ Error: Component file not found.
Component ID: btn-001
Expected file: D-Design-System/components/button.md
This shouldn't happen. Possible causes:
- File was deleted
- Component ID is incorrect
- Design system structure corrupted
Would you like to:
1. Create component as new
2. Specify correct component ID
3. Cancel
Your choice:
```
**If variant too different:**
```
⚠️ Warning: High Divergence Detected
The new variant is very different from existing variants:
- Different core purpose
- Different visual structure
- Different behavioral patterns
Similarity to existing variants: 35%
This might be better as a separate component.
Options:
1. Add as variant anyway
2. Create as new component instead
3. Review differences in detail
Your choice:
```
---
## Post-Addition Review
<action>
After adding variant, check component health:
</action>
**Component Health Check:**
```
📊 Component Health: Button [btn-001]
Variants: 3
Complexity: Medium
Consistency: High
Usage: 9 pages
Health Status: ✅ Healthy
Recommendations:
- Document variant selection guidelines
- Consider adding variant usage examples
- Monitor for variant explosion
```
---
**This operation adds a variant. Return to Phase 4 with component reference.**
```
### 11. Present MENU OPTIONS
Display: "**Select an Option:** [C] Continue to Generate Catalog or [M] Return to Activity Menu"
#### Menu Handling Logic:
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#11-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [variant is added, component file updated, and usage tracked], will you then load and read fully `{nextStepFile}` to execute the next step.
---
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated
### ❌ SYSTEM FAILURE:
- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

755
_bmad/wds/workflows/7-design-system/steps-c/step-08e-generate-catalog.md Normal file
View File

@@ -0,0 +1,755 @@
---
name: 'step-08e-generate-catalog'
description: 'Generate or update the interactive HTML catalog showcasing all design system components'
# File References
activityWorkflowFile: '../workflow-create.md'
---
# Step 8e: Generate Catalog
## STEP GOAL:
Generate or update the interactive HTML catalog from design system data. Load template, gather project info, generate navigation, token sections, component sections, and changelog.
## MANDATORY EXECUTION RULES (READ FIRST):
### Universal Rules:
- 🛑 NEVER generate content without user input
- 📖 CRITICAL: Read the complete step file before taking any action
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
- 📋 YOU ARE A FACILITATOR, not a content generator
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
### Role Reinforcement:
- ✅ You are the Design System Architect guiding design system creation and maintenance
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
- ✅ We engage in collaborative dialogue, not command-response
- ✅ You bring design system expertise and component analysis, user brings design knowledge and project context
- ✅ Maintain systematic and analytical tone throughout
### Step-Specific Rules:
- 🎯 Focus ONLY on this step's specific goal — do not skip ahead
- 🚫 FORBIDDEN to jump to later steps before this step is complete
- 💬 Approach: Systematic execution with clear reporting
- 📋 All outputs must be documented and presented to user
## EXECUTION PROTOCOLS:
- 🎯 Execute each instruction in the sequence below
- 💾 Document all findings and decisions
- 📖 Present results to user before proceeding
- 🚫 FORBIDDEN to skip instructions or optimize the sequence
## CONTEXT BOUNDARIES:
- Available context: Previous step outputs and project configuration
- Focus: This step's specific goal only
- Limits: Do not perform actions belonging to subsequent steps
- Dependencies: Requires all previous steps to be completed
## Sequence of Instructions (Do not deviate, skip, or optimize)
## Input
**Design System Files:**
- `D-Design-System/components/*.md` - All component specifications
- `D-Design-System/design-tokens.md` - Design token definitions
- `D-Design-System/figma-mappings.md` - Figma references (if Mode B)
- `D-Design-System/component-library-config.md` - Library config (if Mode C)
**Project Config:**
- Project name
- Design system mode
- Version number
- Creation date
---
## Output
**Generated File:**
- `D-Design-System/catalog.html` - Interactive HTML catalog
**Features:**
- Fixed sidebar navigation
- Live component previews
- Interactive state toggles
- Code examples
- Design token swatches
- Changelog
- Figma links (if Mode B)
- Responsive design
---
## Step 1: Load Template
<action>
Load catalog template:
</action>
**File:** `workflows/7-design-system/templates/catalog.template.html`
**Template variables:**
```
{{PROJECT_NAME}}
{{PROJECT_ICON}}
{{PROJECT_DESCRIPTION}}
{{PROJECT_OVERVIEW}}
{{VERSION}}
{{COMPONENT_COUNT}}
{{DESIGN_SYSTEM_MODE}}
{{CREATED_DATE}}
{{LAST_UPDATED}}
{{INSTALLATION_INSTRUCTIONS}}
{{USAGE_EXAMPLE}}
{{COMPONENT_NAVIGATION}}
{{DESIGN_TOKENS_CONTENT}}
{{COLOR_TOKENS}}
{{TYPOGRAPHY_TOKENS}}
{{SPACING_TOKENS}}
{{COMPONENTS_CONTENT}}
{{CHANGELOG_CONTENT}}
{{FIGMA_LINKS}}
```
---
## Step 2: Gather Project Information
<action>
Extract project metadata:
</action>
**From project config:**
```yaml
project_name: 'Dog Week'
project_icon: '🐕'
project_description: 'Family dog care coordination platform'
design_system_mode: 'custom' # or "library" or "none"
created_date: '2024-09-15'
version: '1.0.0'
```
**Calculate:**
```
component_count: Count files in D-Design-System/components/
last_updated: Current date/time
```
---
## Step 3: Generate Navigation
<action>
Build component navigation from component files:
</action>
**Scan components:**
```
D-Design-System/components/
├── button.md [btn-001]
├── input.md [inp-001]
├── card.md [crd-001]
└── ...
```
**Group by category:**
```
Interactive:
- Button [btn-001]
- Link [lnk-001]
Form:
- Input [inp-001]
- Select [sel-001]
Display:
- Card [crd-001]
- Badge [bdg-001]
```
**Generate HTML:**
```html
<div class="nav-section">
<h4 class="nav-section-title">Interactive</h4>
<ul class="nav-list">
<li><a href="#button" class="nav-link">Button</a></li>
<li><a href="#link" class="nav-link">Link</a></li>
</ul>
</div>
<div class="nav-section">
<h4 class="nav-section-title">Form</h4>
<ul class="nav-list">
<li><a href="#input" class="nav-link">Input</a></li>
<li><a href="#select" class="nav-link">Select</a></li>
</ul>
</div>
```
**Replace:** `{{COMPONENT_NAVIGATION}}`
---
## Step 4: Generate Design Tokens Section
<action>
Read and format design tokens:
</action>
**Load:** `D-Design-System/design-tokens.md`
**Parse tokens:**
```yaml
Colors:
primary-500: #3b82f6
primary-600: #2563eb
gray-900: #111827
Typography:
text-display: 3.75rem
text-heading-1: 3rem
text-body: 1rem
Spacing:
spacing-2: 0.5rem
spacing-4: 1rem
spacing-6: 1.5rem
```
**Generate color swatches:**
```html
<div class="component-card">
<h3 class="text-lg font-semibold mb-4">Primary Colors</h3>
<div class="variant-grid">
<div>
<div class="token-swatch" style="background: #3b82f6;"></div>
<p class="text-sm font-mono mt-2">primary-500</p>
<p class="text-xs text-gray-500">#3b82f6</p>
</div>
<div>
<div class="token-swatch" style="background: #2563eb;"></div>
<p class="text-sm font-mono mt-2">primary-600</p>
<p class="text-xs text-gray-500">#2563eb</p>
</div>
</div>
</div>
```
**Generate typography examples:**
```html
<div class="component-card">
<h3 class="text-lg font-semibold mb-4">Typography Scale</h3>
<div class="space-y-4">
<div>
<p class="text-sm text-gray-500 mb-1">text-display (3.75rem)</p>
<p style="font-size: 3.75rem; font-weight: 800; line-height: 1.1;">Display Text</p>
</div>
<div>
<p class="text-sm text-gray-500 mb-1">text-heading-1 (3rem)</p>
<p style="font-size: 3rem; font-weight: 700; line-height: 1.2;">Heading 1</p>
</div>
</div>
</div>
```
**Replace:** `{{COLOR_TOKENS}}`, `{{TYPOGRAPHY_TOKENS}}`, `{{SPACING_TOKENS}}`
---
## Step 5: Generate Component Sections
<action>
For each component, generate interactive showcase:
</action>
**For each file in `D-Design-System/components/`:**
### Parse Component
**Read component file:**
```markdown
# Button Component [btn-001]
**Type:** Interactive
**Category:** Action
## Variants
- primary
- secondary
- ghost
- outline
## States
- default
- hover
- active
- disabled
- loading
## Sizes
- small
- medium
- large
```
### Generate Component Section
**HTML structure:**
```html
<section id="button" class="mb-16" style="scroll-margin-top: 2rem;">
<h2 class="text-3xl font-bold text-gray-900 mb-6">
Button
<span class="version-badge">[btn-001]</span>
<span class="usage-badge">Used in 12 pages</span>
</h2>
<!-- Component Description -->
<div class="component-card">
<p class="text-gray-700 mb-4">{{COMPONENT_DESCRIPTION}}</p>
<div class="flex gap-2">
<span class="text-sm text-gray-600"> <strong>Type:</strong> Interactive </span>
<span class="text-sm text-gray-600"> <strong>Category:</strong> Action </span>
</div>
</div>
<!-- Variants -->
<div class="component-card">
<h3 class="text-xl font-semibold mb-4">Variants</h3>
<div class="component-preview">
<div class="variant-grid">{{VARIANT_EXAMPLES}}</div>
</div>
</div>
<!-- States -->
<div class="component-card">
<h3 class="text-xl font-semibold mb-4">States</h3>
<div class="component-preview">
<div class="state-grid">{{STATE_EXAMPLES}}</div>
</div>
<!-- Interactive State Toggle -->
<div class="mt-4">
<p class="text-sm text-gray-600 mb-2">Try it:</p>
<div class="flex gap-2 mb-4">
<button onclick="toggleState(this, 'demo-button', 'default')" class="px-3 py-1 rounded text-sm bg-blue-500 text-white">
Default
</button>
<button onclick="toggleState(this, 'demo-button', 'hover')" class="px-3 py-1 rounded text-sm bg-gray-200 text-gray-700">
Hover
</button>
<button onclick="toggleState(this, 'demo-button', 'active')" class="px-3 py-1 rounded text-sm bg-gray-200 text-gray-700">
Active
</button>
<button onclick="toggleState(this, 'demo-button', 'disabled')" class="px-3 py-1 rounded text-sm bg-gray-200 text-gray-700">
Disabled
</button>
</div>
<div class="component-preview">
<button id="demo-button" class="state-default">Interactive Button</button>
</div>
</div>
</div>
<!-- Code Example -->
<div class="component-card">
<h3 class="text-xl font-semibold mb-4">Code Example</h3>
<div class="code-block">
<pre>{{CODE_EXAMPLE}}</pre>
</div>
</div>
<!-- Usage Guidelines -->
<div class="component-card">
<h3 class="text-xl font-semibold mb-4">Usage Guidelines</h3>
{{USAGE_GUIDELINES}}
</div>
<!-- Figma Link (if Mode B) -->
{{FIGMA_COMPONENT_LINK}}
</section>
```
### Generate Variant Examples
**For each variant:**
```html
<div>
<button class="btn-primary btn-medium">Primary Button</button>
<p class="text-xs text-gray-500 mt-2">primary</p>
</div>
<div>
<button class="btn-secondary btn-medium">Secondary Button</button>
<p class="text-xs text-gray-500 mt-2">secondary</p>
</div>
```
### Generate State Examples
**For each state:**
```html
<div>
<button class="btn-primary btn-medium state-default">Default</button>
<p class="text-xs text-gray-500 mt-2">default</p>
</div>
<div>
<button class="btn-primary btn-medium state-hover">Hover</button>
<p class="text-xs text-gray-500 mt-2">hover</p>
</div>
```
### Generate Code Example
**Extract from component spec:**
```tsx
import { Button } from '@/components/button';
<Button variant="primary" size="medium">
Click me
</Button>
<Button variant="secondary" size="large" disabled>
Disabled
</Button>
```
**Replace:** `{{COMPONENTS_CONTENT}}`
---
## Step 6: Generate Changelog
<action>
Build changelog from component version histories:
</action>
**Scan all components for version history:**
```markdown
## Version History
**Created:** 2024-09-15
**Last Updated:** 2024-12-09
**Changes:**
- 2024-09-15: Created component
- 2024-10-01: Added loading state
- 2024-12-09: Updated hover animation
```
**Generate changelog HTML:**
```html
<div class="space-y-4">
<div class="border-l-4 border-blue-500 pl-4">
<p class="font-semibold">December 9, 2024</p>
<ul class="text-sm text-gray-600 mt-1">
<li>• Button: Updated hover animation</li>
<li>• Input: Added success state</li>
</ul>
</div>
<div class="border-l-4 border-gray-300 pl-4">
<p class="font-semibold">October 1, 2024</p>
<ul class="text-sm text-gray-600 mt-1">
<li>• Button: Added loading state</li>
</ul>
</div>
</div>
```
**Replace:** `{{CHANGELOG_CONTENT}}`
---
## Step 7: Add Figma Links (Mode B)
<action>
If Mode B, add Figma component links:
</action>
**Load:** `D-Design-System/figma-mappings.md`
**Parse mappings:**
```yaml
Button [btn-001] → figma://file/abc123/node/456:789
Input [inp-001] → figma://file/abc123/node/456:790
```
**Generate Figma section:**
```html
<h3 class="text-lg font-semibold mb-4">Figma Components</h3>
<div class="space-y-2">
<a href="figma://file/abc123/node/456:789" class="flex items-center gap-2 text-blue-600 hover:text-blue-800">
<svg><!-- Figma icon --></svg>
Button [btn-001]
</a>
<a href="figma://file/abc123/node/456:790" class="flex items-center gap-2 text-blue-600 hover:text-blue-800">
<svg><!-- Figma icon --></svg>
Input [inp-001]
</a>
</div>
```
**Replace:** `{{FIGMA_LINKS}}`
---
## Step 8: Generate Installation Instructions
<action>
Create mode-specific installation instructions:
</action>
**Mode B (Custom/Figma):**
```bash
# Install dependencies
npm install
# Import design tokens
import '@/styles/design-tokens.css';
# Import components
import { Button } from '@/components/button';
```
**Mode C (Component Library):**
```bash
# Install component library
npm install shadcn-ui
# Configure library
npx shadcn-ui init
# Import components
import { Button } from '@/components/ui/button';
```
**Replace:** `{{INSTALLATION_INSTRUCTIONS}}`, `{{USAGE_EXAMPLE}}`
---
## Step 9: Write Catalog File
<action>
Save generated HTML:
</action>
**File:** `D-Design-System/catalog.html`
**Content:** Fully populated template with all sections
**Validation:**
- All template variables replaced
- Valid HTML structure
- All component sections included
- Navigation links work
- Interactive demos functional
---
## Step 10: Update Git
<action>
Version control the catalog:
</action>
**Git operations:**
```bash
git add D-Design-System/catalog.html
git commit -m "Update design system catalog - [component changes]"
```
**Commit message format:**
```
Update design system catalog - Added Button loading state
- Button [btn-001]: Added loading state variant
- Updated catalog with interactive demo
- Version: 1.0.1
```
---
## Output Format
**Success message:**
```
✅ Design system catalog generated
File: D-Design-System/catalog.html
Components: 12
Last updated: 2024-12-09 14:30
View catalog:
file:///path/to/D-Design-System/catalog.html
Changes committed to git.
```
---
## Error Handling
### Missing Template
**Error:** Catalog template not found
**Action:**
```
⚠️ Catalog template missing
Expected: workflows/7-design-system/templates/catalog.template.html
Please ensure WDS is properly installed.
```
### Invalid Component Spec
**Error:** Component file has invalid format
**Action:**
```
⚠️ Invalid component specification
File: D-Design-System/components/button.md
Issue: Missing required sections
Skipping component in catalog.
Please fix component specification.
```
### No Components
**Error:** No components in design system
**Action:**
```
⚠️ No components found
Design system appears empty.
Catalog will include only foundation (tokens).
Add components to populate catalog.
```
---
## Automation
**Catalog is automatically regenerated:**
- After creating new component
- After adding variant
- After updating component
- After updating design tokens
**Manual regeneration:**
```
Agent: Regenerate design system catalog
```
---
## Best Practices
### DO ✅
- Regenerate after every component change
- Commit catalog with component changes
- Include all variants and states
- Add interactive demos
- Keep changelog updated
### DON'T ❌
- Don't manually edit catalog.html
- Don't skip catalog regeneration
- Don't forget to commit changes
- Don't remove interactive features
---
**The interactive catalog is the living documentation of your design system, always up-to-date and version controlled.**
### 11. Present MENU OPTIONS
Display: "**Select an Option:** [M] Return to Activity Menu"
#### Menu Handling Logic:
- IF M: Return to {activityWorkflowFile} activity menu
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#11-present-menu-options)
#### EXECUTION RULES:
- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects the appropriate option
- User can chat or ask questions — always respond and then redisplay menu options
## CRITICAL STEP COMPLETION NOTE
ONLY WHEN [M is selected and catalog is generated and saved], will you then return to the activity workflow menu.
---
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
### ✅ SUCCESS:
- Step goal achieved completely
- All instructions executed in sequence
- Results documented and presented to user
- User confirmed before proceeding
- Design log updated
### ❌ SYSTEM FAILURE:
- Skipping any instruction in the sequence
- Generating content without user input
- Jumping ahead to later steps
- Not presenting results to user
- Proceeding without user confirmation
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.