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.primaryviracolor.action.primary. - Um componente removido: o
Banneré substituído peloNotice. - Uma propriedade renomeada ou com valores diferentes:
type="error"viratone="danger". - Um padrão (default) alterado: o
Buttoneramd, 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
- 3.2.0fevereiroO substituto é lançadoNovo componente
Notice, com a propriedadetone. OBannercontinua funcionando como antes. - 3.4.0abrilDescontinuado, não removido
Bannermarcado 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.4 → 3.9abril a setembroJanela 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.0.0outubroRemovido, numa versão major
Bannerapagado, 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.
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 sertrueou 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
Bannerremovido. UseNotice:<Banner type="error">vira<Notice tone="danger">. Rodenpx @harbour/codemods banner-to-notice. Descontinuado desde a 3.4.0.- Token
color.primaryremovido. Usecolor.(mesmo valor). Descontinuado desde a 3.4.0.action. primary
Mudou
- O anel de foco do
Buttonagora 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.
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)
- Escolha um componente ou token do seu sistema que você adoraria remover.
- Escreva o aviso de descontinuação em duas frases: o que o substitui e quando ele sai.
- 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
- Semantic Versioning 2.0.0
- USWDS, Component lifecycle
- Design Tokens Community Group, Format Module 2025.10: a propriedade
$deprecated - IBM Carbon, Migration guide v10 to v11
- Keep a Changelog 1.1.0
Livros, cursos e vídeos para ir mais fundo
- Atomic DesignBrad FrostLivro · Brad Frost, 2016 (Amazon)
- Design That ScalesDan MallLivro · Rosenfeld Media, 2023 (Amazon)
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