BMAD-METHOD/devKalla-Fordonscervice/_wds/workflows/5-design-system/operations/add-variant.md

Operation: Add Variant

Purpose: Add a new variant to an existing component.

When: Designer chose to extend existing component with new variant

Input: Existing component ID + new variant specification

Output: Updated component file with new variant

---

Step 1: Load Existing Component

Read existing component file: - Component ID - Current variants - Shared attributes - Variant-specific attributes

Example:

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

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

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:

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

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

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

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

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

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

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

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

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