Guide: Updating Components Without Breaking Everything

1. Purpose

To provide a safe, step-by-step method for updating components in a shared library without disrupting existing designs, developer workflows, or QA.

2. Why This Matters

  • Master components are used across multiple files/projects.
  • If updated recklessly →
    • Instances detach or break.
    • Dev handoff gets inconsistent.
    • Teams lose trust in the library.
  • This guide ensures updates are predictable, reversible, and documented.

3. Golden Rules Before Updating

  1. Never edit directly in production library → always work in a sandbox copy.
  2. Version everything → if you can’t tag changes, you can’t roll them back.
  3. Announce change window → team should know when updates are being made.
  4. Test in consumer files before publishing → validate impact.

4. Step-by-Step Update Process

Stage A – Prep & Sandbox

  1. Duplicate the component into a sandbox page/file.
  2. Tag current version → e.g., Button/Primary v1.3.
  3. Check usage → list all files using this component.

Stage B – Apply Changes Safely

  1. Make updates in sandbox, not in master.
    • Examples: token change (new color), structural update (icon slot), new state.
  2. Test responsiveness (desktop, mobile, tablet).
  3. Validate against Token–Component Sync Map (Doc 10.6).
  4. Confirm all states + variants are still intact.

Stage C – Test & Validate

  1. Swap sandbox component into 1–2 consumer screens.
    • Validate spacing, overrides, responsiveness.
  2. Run peer review with Component Consistency Checklist (Doc 4.7).
  3. Run accessibility validation (contrast, focus states, tap targets).

Stage D – Publish & Communicate

  1. Update component in master library → tag new version (e.g., v1.4).
  2. Document update in Component Review Log (Doc 10.8).
  3. Publish with changelog → include: what changed, what broke, what to test.
  4. Notify team with migration guide (Slack/Email).

Stage E – Post-Update Monitoring

  1. Monitor adoption → check consumer files in 1 sprint.
  2. If bugs appear → hotfix publish (v1.4.1) or rollback to v1.3.

5. Failure Handling

  • If update breaks multiple screens →
    • Immediately rollback to last stable version.
    • Announce rollback + issue fix ETA.
  • If conflicting overrides found in consumer files →
    • Provide migration guidance (swap to correct variant).

6. Example – Updating Button/Primary

  • Before: Blue background (#3B82F6), no icon slot.
  • Change: Add optional left icon property.
  • Process:
    1. Sandbox test → create variant with icon slot.
    2. Swap in 2–3 screens → validate spacing.
    3. Document in Review Log → “v1.4 added icon property.”
    4. Publish → notify devs → “React Button v1.4 now supports icons.”

7. Usage Notes

  • Treat library updates like code releases.
  • Never surprise devs or QA → always log in Review Log & Changelog.
  • If a breaking change is unavoidable → provide migration table.