Marcus Andrey Estudo
Read in English Biblioteca

Design systems · Passo 7 · 7 min de leitura

Descontinuação e breaking changes

Como mudar ou remover algo num design system sem quebrar os produtos que o usam. O que conta como mudança que quebra, como o Versionamento Semântico ordena descontinuação e remoção, e os avisos, a ajuda na migração e as linhas de changelog que levam os times até o outro lado.

Remover um componente é uma promessa quebrada, a não ser que você tenha avisado cedo, dito por quê e ajudado as pessoas a mudar. Todo sistema tem partes que nunca deveriam ter saído: um banner que ninguém consegue deixar acessível, um token com um nome que não quer dizer nada. Tirá-las é saudável. Tirá-las de surpresa é como um sistema perde a confiança que levou anos para ganhar.

O que você vai conseguir fazer depois de ler:

  • Diferenciar uma mudança que quebra de uma mudança segura
  • Usar o Versionamento Semântico para planejar uma descontinuação
  • Escrever um aviso de descontinuação e um caminho de migração
  • Escrever uma entrada de changelog para quem vai ter que atualizar

1. O que quebra

Uma mudança que quebra ("breaking change") é qualquer mudança que faz o produto de alguém, que funcionava, falhar, ou parecer ou se comportar diferente, sem que essa pessoa tenha escolhido. No código é fácil de ver: um componente removido, uma propriedade renomeada, uma prop que agora precisa de outro valor. No design é mais silencioso, e conta também:

  • Um token removido ou renomeado: color.primary vira color.action.primary.
  • Um componente removido: o Banner é substituído pelo Notice.
  • Uma propriedade renomeada ou com valores diferentes: type="error" vira tone="danger".
  • Um padrão (default) alterado: o Button era md, agora é sm.
  • Uma mudança visual em torno da qual as pessoas construíram: um padding que cresceu 4 px e agora joga uma tabela do console para duas linhas.

Faça uma pergunta: a tela de alguém vai mudar, ou o build vai falhar, quando a pessoa atualizar? Se sim, trate como mudança que quebra.


2. Versões que dizem a verdade

O Versionamento Semântico dá a cada versão três números, MAJOR.MINOR.PATCH. Você aumenta o major para mudanças incompatíveis na API, o minor quando adiciona funcionalidade de forma compatível, e o patch para correções de bugs compatíveis (semver.org).

O FAQ também dá a ordem para remover algo: atualize a documentação, depois "issue a new minor release with the deprecation in place" (lance uma nova versão minor com a descontinuação já marcada), e só remova numa versão major, com pelo menos uma minor contendo a descontinuação no meio (Semantic Versioning 2.0.0, FAQ).

Num design system, a API inclui a biblioteca do Figma. Versione a biblioteca e o código juntos, ou pelo menos anuncie os dois juntos, para "Harbour 4.0" querer dizer a mesma coisa para quem desenha e para quem desenvolve (veja Versões e releases).


3. Primeiro descontinue, depois remova

  1. 3.2.0fevereiro
    O substituto é lançadoNovo componente Notice, com a propriedade tone. O Banner continua funcionando como antes.
  2. 3.4.0abril
    Descontinuado, não removidoBanner marcado como descontinuado no código, no Figma e na documentação. Um aviso no console, em desenvolvimento, diz qual é o substituto e aponta o guia de migração.
  3. 3.4 → 3.9abril a setembro
    Janela de migraçãoUm codemod reescreve a maioria dos usos. O time do sistema faz par com os dois times que mais usam. O painel de adoção conta o que falta.
  4. 4.0.0outubro
    Removido, numa versão majorBanner apagado, listado em "Breaking changes" no changelog com a correção em uma linha. A 3.x recebe correções de segurança por mais seis meses.
Uma descontinuação no Harbour, do substituto à remoção. A regra vem do Versionamento Semântico: descontinue numa versão minor, remova só numa major, e deixe pelo menos uma minor no meio. Os meses são escolha deste exemplo, não uma norma.Diagrama: Marcus Andrey, CC BY 4.0. Regra de versionamento de semver.org 2.0.0.

Descontinuado quer dizer: ainda está lá, ainda funciona, não é mais recomendado, e vai sair. O US Web Design System define com precisão: um componente descontinuado sai do suporte ativo, continua no código, não recebe atualizações, e o time recomenda removê-lo do seu projeto; ele é aposentado quando é apagado (USWDS, Component lifecycle).

Marque a descontinuação em todo lugar onde as pessoas encontram a coisa:

  • Código. Um aviso no console de desenvolvimento que diz qual é o substituto e aponta o guia. Para tokens, o formato DTCG tem a propriedade $deprecated, que pode ser true ou um texto com o motivo (DTCG Format Module 2025.10):
"primary": {
  "$type": "color",
  "$value": "{color.blue.600}",
  "$deprecated": "Use color.action.primary. Removed in Harbour 4.0.0."
}
  • Figma. Mova o componente para uma página "Deprecated", coloque um prefixo no nome e atualize a descrição com o substituto.
  • Documentação. Um rótulo de status na página, e a data em que ele vai sair.

Brad Frost cita a ferramenta Sass Deprecate, da Salesforce, que sinaliza os padrões que estão de saída antes de eles sumirem (Atomic Design, chapter 5). A ideia importa mais do que a ferramenta: avise onde as pessoas já olham.


4. Ajude as pessoas a mudar

Um aviso de descontinuação sem ajuda é uma tarefa que você passou para todos os times de produto. Deixe a mudança barata:

  • Um guia de migração: antes e depois, no código e no Figma, para cada caso.
  • Um codemod, quando a mudança é mecânica, como renomear uma propriedade. É um script que reescreve o código pelas pessoas.
  • Trabalho em par com os times que mais usam a coisa antiga. Os números de adoção de Medir a adoção dizem quem são.
  • Uma janela longa o bastante para o ciclo de release do time mais lento. Para o console da equipe, que lança a cada seis semanas, isso é pelo menos duas versões.
  • Suporte ao major antigo por um tempo: correções de segurança para a 3.x depois que a 4.0 sair.

Quando a IBM levou o Carbon da v10 para a v11, renomeou os tokens de cor para descrever o uso, juntou os pacotes em @carbon/react e manteve bibliotecas separadas da v10 e da v11 no Figma, para os designers trocarem quando estivessem prontos (Carbon, Migration guide). O padrão é o que vale copiar: primeiro o motivo, depois as mudanças, depois um caminho para cada público.


5. A linha do changelog

Harbour 4.0.013 de outubro · versão major

Breaking changes

  • Banner removido. Use Notice: <Banner type="error"> vira <Notice tone="danger">. Rode npx @harbour/codemods banner-to-notice. Descontinuado desde a 3.4.0.
  • Token color.primary removido. Use color.action.primary (mesmo valor). Descontinuado desde a 3.4.0.

Mudou

  • O anel de foco do Button agora tem 2 px com 2 px de afastamento em todos os modos, para continuar visível em superfícies escuras.

Quem é afetado

  • App de reservas: nenhum uso restante. Console da equipe: 3 usos nas telas de check-in, migração em par marcada para a semana 42.
Uma entrada de changelog para uma versão major, escrita para quem vai ter que atualizar. Cada breaking change diz o que saiu, o que usar no lugar, como fazer e desde quando foi avisado.Exemplo: Marcus Andrey, CC BY 4.0. O Harbour é um sistema fictício.

O Keep a Changelog parte de um princípio: changelogs são para humanos, não para máquinas. Ele agrupa as mudanças em Added, Changed, Deprecated, Removed, Fixed e Security (Keep a Changelog 1.1.0). Num design system, acrescente uma linha sobre quem é afetado: quem lê quer saber se aquilo é problema seu.

Uma entrada de mudança que quebra responde a quatro perguntas: o que saiu, o que usar no lugar, como mudar e desde quando isso foi avisado.


6. Erros comuns

  • Remover algo numa versão minor porque "ninguém usa" (alguém usa).
  • Descontinuar no código mas não no Figma, e os designers continuam entregando o componente antigo no handoff.
  • Um aviso que diz "descontinuado" sem dizer qual é o substituto.
  • Juntar muitas mudanças que quebram numa major enorme que ninguém consegue adotar.
  • Mudar o valor de um token em silêncio e chamar de patch.

7. Vocabulário

Termo Significado
Mudança que quebra (breaking change) Uma mudança que faz um produto que funcionava falhar ou mudar sem que o time dele escolhesse
Descontinuado Ainda está lá e funciona, não é mais recomendado, e tem data para sair
Aposentado, removido Apagado do sistema
Guia de migração Instruções de antes e depois para trocar o antigo pelo novo
Codemod Um script que reescreve código automaticamente, para mudanças mecânicas
Major, minor, patch Os três números de uma versão: quebra, novidade compatível, correção

8. Experimente (sem ferramentas)

  1. Escolha um componente ou token do seu sistema que você adoraria remover.
  2. Escreva o aviso de descontinuação em duas frases: o que o substitui e quando ele sai.
  3. Liste os três times mais afetados, e do que cada um precisaria de você.

Perguntas para refletir: Como um time de produto descobriria hoje que algo que usa vai sair? Qual é o ciclo de release mais longo entre os produtos que o seu sistema atende?


9. Se você já pratica

  • Crie uma regra de lint ou um aviso no build para tokens e componentes descontinuados, para a contagem cair sozinha.
  • Mostre "usos descontinuados restantes" por produto ao lado dos números de adoção.
  • Agrupe as mudanças que quebram num ritmo conhecido, como uma major por ano, para os times conseguirem se planejar.

Checklist

Para saber mais

Livros, cursos e vídeos para ir mais fundo

Os links dos livros são de afiliado da Amazon: como associado, recebo por compras qualificadas, sem custo a mais para você.

Relacionadas

Versões e releases · Medir a adoção · Modelos de contribuição · Tokens do Figma ao código · Um roadmap para o sistema · Ciclo de descontinuação

Salvo só neste dispositivo.

↑ ↓ para mover · Enter para abrir · Esc para fechar