--- 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 Determine what's being updated: **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 ``` 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: ``` --- ## Step 2: Load Current Component Read existing component file: - Current definition - All variants - Current states - Current styling - Usage tracking ``` 📖 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 ``` --- ## Step 3: Analyze Impact Determine impact of update: **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? ``` 📊 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) ``` --- ## Step 4: Confirm Update ``` 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) ```` --- ## Step 5: Apply Update Update component file based on type: ### 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 Track update in version history: **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 If update affects existing usage, create notification: ``` 📢 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 ```` --- ## Step 8: Update Design System Stats Update design system metadata: **Update:** `D-Design-System/README.md` ```markdown **Last Updated:** 2024-12-09 **Recent Changes:** - Button [btn-001]: Added loading state ```` --- ## Step 9: Complete ``` ✅ 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 ``` --- ## Validation Validate update: - ✓ Component file updated - ✓ Changes documented - ✓ Version history updated - ✓ Impact assessed - ✓ Notifications sent (if needed) - ✓ Backward compatibility maintained --- ## 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 Create migration checklist: **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 Suggest design system review: ``` 💡 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? ``` --- **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.