Breaking Change Definition

Breaking change definition establishes clear criteria for identifying modifications that require consumer code updates when upgrading a design system. Without a precise definition, teams struggle to version releases correctly and consumers cannot predict upgrade effort. A well-documented breaking change definition aligns expectations between design system maintainers and their consumers.

What Is a Breaking Change

A breaking change is any modification to a design system that causes existing consumer implementations to fail or behave differently without code changes. This includes changes to the public API, significant visual alterations, and modifications to dependencies or build outputs.

The concept originates from software library maintenance where changing function signatures breaks calling code. For design systems, the definition extends to include visual contracts, accessibility features, and integration patterns that consumers depend upon. Understanding these boundaries helps teams make consistent versioning decisions.

How Breaking Change Definition Works

Identifying breaking changes requires examining all surfaces of the design system that consumers interact with. This analysis considers both explicit contracts (documented APIs) and implicit contracts (undocumented but relied-upon behaviors).

Programmatic API changes form the clearest category of breaking changes. Removing or renaming props, changing prop types, altering event signatures, removing components, or changing export paths all require consumer code modifications. These changes prevent existing code from compiling or functioning correctly.

Behavioral changes may constitute breaking changes even when the API remains stable. If a component previously handled edge cases in a specific way that consumers depend upon, altering that behavior breaks their implementations. Similarly, changing default values for props can break consumers who relied on the previous defaults.

Visual changes occupy a nuanced position. Strictly, visual output is not part of the programmatic API. However, design systems exist to provide visual consistency, and consumers often have visual regression tests or specific layout dependencies. Teams must define their own conventions for when visual changes constitute breaking changes.

Key Considerations

• Removing or renaming any public API surface is always breaking
• Changing TypeScript types to be more restrictive is breaking
• Adding required props to existing components is breaking
• Peer dependency major version bumps are typically breaking
• Dropping browser or framework version support is breaking

Common Questions

Are accessibility improvements considered breaking changes?

Accessibility improvements require case-by-case evaluation. Adding ARIA attributes or improving keyboard navigation typically does not break existing implementations. However, changes that alter the interaction model or DOM structure may affect consumers who have built custom functionality around the existing behavior.

For example, changing focus management in a modal component could break consumers who implemented custom focus handling. Similarly, modifying the accessible name pattern might break consumers’ end-to-end tests. When accessibility improvements involve significant structural changes, treating them as breaking changes with proper migration documentation helps consumers adapt.

How should teams handle breaking changes to undocumented behavior?

Undocumented behavior creates challenges for breaking change classification. Some teams take a strict position that only documented APIs constitute public contracts, making undocumented behavior changes non-breaking. Others recognize that consumers inevitably rely on undocumented behavior and treat significant changes as breaking.

A pragmatic approach documents the team’s stance clearly and uses deprecation warnings for behaviors intended to change. Monitoring support channels can reveal which undocumented behaviors consumers rely upon, informing decisions about whether changes warrant major versions. Ultimately, the goal is minimizing unexpected breakage for consumers.

Summary

Breaking change definition provides the foundation for accurate semantic versioning. Clear criteria covering API changes, behavioral modifications, and visual alterations help teams make consistent versioning decisions. Documenting these definitions and communicating them to consumers establishes shared expectations around upgrade impact.