Deprecation guidelines describe our approach for sunsetting elements of the design system when they are no longer needed. All deprecations should be:
- Supportive: We provide alternatives to solutions or elements we remove.
- Safe: We release thoroughly tested changes that reduce, not introduce debt.
- Noticeable: We communicate deprecations, so they don’t take teams by surprise.
Depreciation steps
1. Identify an item to deprecate
Items might be deprecated because they need upgrading, are being replaced by a new item with different functionality, or are being consolidated (for example, instead of having multiple, similar Button components, we opt to have a more robust, single component).
2. Mark the item as deprecated
Design system users must know that an item is deprecated and shouldn’t be used. Follow the naming conventions below:
|
Element |
Naming convention |
|---|---|
|
Design Token |
color.deprecated.tokenName |
|
Icon |
deprecated-icon-name |
|
Component |
DeprecatedComponentName |
We use these conventions across design and code to communicate intent. When a naming change is introduced in automated generation workflows (tokens, icons), changes will be published across both types of resources.
In Figma, when an item shouldn’t be visible but isn’t suitable for removal, hide it using . name prefix (for example: .Button) or manually hiding components, variables and styles.
Use the JSDoc @deprecated tag to mark deprecated components, functions, or classes. This will mark deprecated areas if developers have eslint-plugin-import/no-deprecated and/or eslint-plugin-deprecated-props installed.
Add the deprecated tag to the component story to automatically apply the deprecated label:
const meta = {
title: "Components/ActionButton",
component: ActionButton,
tags: ["autodocs", "deprecated"],
} satisfies Meta<typeof ActionButton>;
Deprecated is also a state of our component lifecycle. Component status should be updated to Deprecated in Supernova → Component Status and in Component Library for a selected component.
Where relevant, we must also update the Octopus Server documentation to highlight deprecated patterns that remain in the codebase but are being phased out. Include a heading and a warning callout specifying the recommended replacement for each deprecated pattern. Where applicable, link to relevant migration guides to assist with the transition, for example:
3. Provide a suggested replacement with optional migration instructions
When deprecating an item (especially a component), add the following information in design and code resources:
Deprecated: (date in Month Year format)
Replacement: (new component name and link)
Reason: (list of deprecation reasons)
Migration guidelines: (list any tips that are relevant)
This can be done in the Figma description field and JSDoc @deprecated tag documentation. By providing these details, we ensure design system users know what to use instead and can assess the migration effort.
4. Communicate the deprecation
Use the communicating changes guidelines and communications template to broadcast a deprecation. If you intend to remove the deprecated item entirely from the design system, ensure you provide a reasonable timeline for when the removal will take place, alongside at least two reminders in the interim.
Deprecation vs deletion
Deprecation is a clear way of communicating that a design system element should not be used. While the element is deprecated, it still exists in the design system. This might be helpful in some scenarios, such as maintaining historical designs.
If an element needs to be deleted, it should generally go through a deprecation process first, unless there's a good reason not to, such as the component not being used for some time. In these cases, engineers are encouraged to lean into deletion without deprecation, as long as they have confidently verified that the element is no longer used across the codebase or by external consumers.