@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.