Avoid breaking change

@Blandine_PELAT I would love to have such a list too. @Figma_Moderation is there something like that? (btw. hope it is fine that I tag you here)

Some cases that will cause breaking changes:

• delete visually visible layer

• change layer structure (exception: text property already set and that is the only thing to move around)

• updating layer names in only one instance and forget about the others (critical on overrides)

• removing used nested components (… because a new Figma feature makes the use of it redundant 🙂

• remove hidden layers that where needed because of a set boolean prop

you should be cautious when …

• updating granular components (e.g. atom level) for a specific purpose and forget about the other components that use it and where the change might break things.

• when deprecating components (always a critical decision to weigh if its needed or not in each use case, and this can also come with breaking changes)

• cleaning up old components and forget about overrides in instances or structure

• using {selection colors} for updating color tokens and therefore accidently create overrides in nested instances.

• change text inside a textblock which has not yet had a layer naming. Because that might change the layer name to the new text.

When to decide if you should deprecate a component (my 2 cents):
This is a rather difficult question and I do not have a clear answer as I am also struggling a lot with this.
Things I ask myself, the component stats or the teams are:

• How often is it used in the files
• How often is it used in files that we are currently working on
• Is this a change we are doing simultaneously in code?
• Will I potentially need to update it pretty soon again?
• Is this update an important technical update which will speed up time to market in the future a lot?
• Is the instance that I need to do the change in, one we use very often? (that is a crucial point for me because I often experience that the default is kept in most adoptions and e.g. a focus instance barely displayed. What I tend to do here is just removing these focus instances and applying e.g. a focus outline as boolean prop. This way there would be no breaking change, as Figma will show these instances anyways and add a comment “missing property: reset to default state” or something like this and then they could update it for each case manually then.