BMAD-METHOD/devKalla-Fordonscervice/_wds/workflows/5-design-system/operations/update-component.md

Operation: Update Component

Purpose: Update an existing component definition (not adding variant, but modifying existing).

When: Component needs changes (new state, styling update, behavior change)

Input: Component ID + update specification

Output: Updated component file

---

When to Use This Operation

Use this operation when:

• Adding new state to all variants (e.g., adding "loading" state)
• Updating shared styling (e.g., changing border-radius)
• Modifying behavior (e.g., adding keyboard shortcut)
• Updating accessibility attributes
• Refining documentation
• Fixing errors in component definition

Don't use this operation for:

• Adding new variant → Use add-variant.md
• Creating new component → Use create-new-component.md
• Reusing component → Handled by assessment flow

---

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:

</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:

## 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):

### Variant-Specific Styling

**Navigation (loading state):**

- Spinner + arrow icon
- Arrow fades out during loading

Type B: Update Styling

Update Styling Section:

Before:

### Visual Properties

**Border Radius:** 0.375rem (md)

After:

### 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:

### Keyboard

- Enter/Space: Triggers button action
- Tab: Moves focus to/from button

After:

### 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:

**ARIA Attributes:**

- role: button
- aria-disabled: true [when disabled]

After:

**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:

### When to Use

- Primary actions
- Secondary actions

After:

### 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

## 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:

## 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

</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

``` ✅ 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

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?

</output>

---

**This operation updates a component. Changes apply to all future usage automatically.**