Breaking changes

A breaking change is any change that requires consumers to modify their implementation when upgrading Designsystemet. Breaking changes are released only in major versions, following Semantic Versioning.

For Designsystemet, the public API includes all documented component APIs (including React and web components), CSS variables, design-tokens, documented data attributes, accessibility behaviour, and Figma components.

We treat the following as breaking

• Removing or renaming components, props, Figma variables, CSS variables, or documented data attributes without compatibility fallbacks.
• Changing documented HTML, CSS or React structure that consumers may depend on (Note that React output DOM might change).
• Changing callback signatures or prop types.
• Significant visual changes that alter the documented appearance, behaviour, or layout of a component.

Deprecation

When breaking changes are planned, the feature will be marked as deprecated to signal that bigger changes are coming. Deprecated features will function as normal until next major version before they are changed. All deprecated features will have a migration-guide provided when they are removed.

Not breaking

We treat the following changes as not breaking:

• Bug fixes.
• Internal refactoring.
• Documentation updates.
• Performance improvements.
• Changes to undocumented features.
• Internal changes to design-tokens structure.
• Minor visual refinements that do not require consumer changes.
• Adding new features such as components, props, variants, tokens or configuration.
• Changes to experimental/unstable features or components. Changes will be documented and notified when released.

Backwards compatibility

We provide backwards compatibility whenever practical. When backwards compatibility is not possible, deprecate first when feasable and document the migration path.