--- 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 Read existing component file: - Component ID - Current variants - Shared attributes - Variant-specific attributes **Example:** ```yaml Component: Button [btn-001] Current Variants: - primary (submit actions) - secondary (cancel actions) ``` ``` 📖 Loaded Button [btn-001] Current variants: 2 (primary, secondary) Adding new variant: navigation ```` --- ## Step 2: Extract Variant-Specific Information 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) **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 Generate descriptive variant name: - Based on purpose or visual distinction - Consistent with existing variant naming - Clear and semantic **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) ``` ``` 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: ```` --- ## Step 4: Update Component File Add variant to component definition: ### 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 Track new variant usage: **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 Add note about variant count: **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 Check for potential issues: **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 Track component changes: **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 Generate reference for page spec: **Output:** ```yaml component_reference: id: btn-001 name: Button variant: navigation ← New variant file: D-Design-System/components/button.md ``` --- ## Step 10: Complete ``` ✅ 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 ``` --- ## Designer Guidance ``` 💡 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! ``` --- ## Validation Validate variant addition: - ✓ Variant added to component file - ✓ Variant-specific attributes documented - ✓ Usage tracking updated - ✓ Version history updated - ✓ Reference generated - ✓ Complexity checked --- ## 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 After adding variant, check component health: **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.