Framework · Design systems · 4 min de leitura
Ciclo de descontinuação
Cinco etapas para tirar um componente, token ou propriedade de um design system (decidir, descontinuar numa minor, ajudar as pessoas a mudar, remover numa major, dar suporte à major antiga por um tempo), para que nada suma de surpresa.
- 1Decidir
Veja o que quebra, nomeie o substituto, escreva o aviso.
"Use Notice. Banner sai na 4.0." - 2Descontinuar
Uma minor marca no código, nos tokens, no Figma e na documentação.
Ainda lá, ainda funcionando - 3Migrar
Guia, codemod e pareamento, pelo tempo que o time mais lento precisar.
Acompanhe os usos restantes caírem - 4Remover
Só numa major, com uma entrada de changelog com que dá para agir.
O quê, no lugar, como, desde quando - 5Suportar
Correções para a major antiga por um período declarado.
Ninguém atualiza na primeira semana
Use quando
- Um componente nunca deveria ter saído (um banner que ninguém consegue tornar acessível) e você quer tirá-lo.
- Um token ou uma prop precisa de nome novo, e o antigo é usado em muitos produtos.
- Alguém propõe apagar algo numa minor porque "ninguém usa".
Como usar
- Decida e nomeie o substituto. Teste a mudança com uma pergunta: a tela de alguém vai mudar, ou o build vai falhar, quando atualizarem? Depois escreva o que substitui o antigo, ou por que nada substitui. Resultado: um aviso de descontinuação em duas frases: o que substitui e quando sai.
- Descontinue numa minor, em todo lugar onde as pessoas olham. No código, um aviso no console que cita o substituto e linka o guia; nos tokens,
$deprecated; no Figma, uma página "Deprecated", um prefixo no nome e a descrição atualizada; na documentação, um rótulo de status e a data de remoção. Resultado: uma minor com a descontinuação marcada no código, no Figma e na documentação. - Torne a mudança barata. Um guia de migração com antes e depois, no código e no Figma. Um codemod quando a mudança é mecânica, como uma renomeação. Pareamento com os times que mais usam o antigo; os números de adoção dizem quem são. Resultado: um guia, um codemod se der, e uma lista de times para ajudar.
- Defina a janela pelo time mais lento. A data de remoção precisa caber no ciclo de release mais longo entre os produtos que usam aquilo. Acompanhe os "usos descontinuados restantes" por produto para ver o número cair. Resultado: uma data de remoção e uma contagem para acompanhar.
- Remova só numa major. Junte as breaking changes num ritmo conhecido. A entrada do changelog responde: o que saiu, o que usar no lugar, como mudar, desde quando foi anunciado e quem é afetado. Resultado: uma major com uma seção "Removed" com que as pessoas conseguem agir.
- Dê suporte à major antiga por um tempo. Correções de segurança e de acessibilidade para a major anterior depois que a nova sai, por um período declarado. Resultado: uma data de fim de suporte na documentação.
Exemplo prático
O Banner do Harbour não tem como ficar acessível sem quebrar o jeito como os times o usam, então será substituído pelo Notice. O console de atendimento da Tidewater faz release a cada seis semanas, o mais lento dos produtos.
| Etapa | Release | O que acontece |
|---|---|---|
| Decidir | Aviso: "Use Notice. O Banner sai no Harbour 4.0.0." | |
| Descontinuar | 3.5.0 (minor) | Aviso no console, página "Deprecated" no Figma, rótulo de status na documentação |
| Migrar | 3.5 a 3.8 | Guia de migração, um codemod de type para tone, pareamento com o time do console |
| Remover | 4.0.0 (major) | Changelog: removido, use Notice, link para o guia, anunciado na 3.5.0, afeta todos os produtos que usam Banner |
| Suportar | 3.x | Correções de segurança para a 3.x por um período declarado depois da 4.0.0 |
A janela cobre pelo menos dois releases do console de atendimento, então o time do console consegue mudar sem emergência.
Cuidado com
- Remover numa minor. "Ninguém usa" quase sempre está errado. Alguém usa.
- Descontinuar só no código. Os designers continuam entregando o componente antigo se o Figma não diz que ele vai sair.
- "Descontinuado" sem substituto. Um aviso que não diz o que usar no lugar é uma tarefa jogada para cada time.
- Uma major gigante. Breaking changes demais num release só, e ninguém consegue adotar.
Modelo
Copie na issue da descontinuação e reaproveite o aviso e as linhas do changelog.
O que é descontinuado: ... (componente / token / prop / valor)
Por quê: ...
Substituto: ... (ou: nenhum, porque ...)
A tela de alguém muda ou o build falha ao atualizar? sim / não
Descontinuado na: x.y.0 (minor) Remoção planejada na: x+1.0.0 (major), data ...
Ciclo de release mais lento afetado: ... -> janela de pelo menos ...
Marcado em:
[ ] Código: aviso no console com o substituto e o guia
[ ] Tokens: "$deprecated": "Use ... Removido na ..."
[ ] Figma: página "Deprecated", prefixo no nome, descrição atualizada
[ ] Documentação: rótulo de status e data de remoção
Ajuda: guia de migração ... / codemod ... / times para parear ...
Usos descontinuados restantes: produto A ..., produto B ...
Changelog (remoção):
### Removed
- ...: use ... no lugar. Guia: ... Anunciado na x.y.0. Afeta: ...
- Atomic DesignBrad FrostLivro · 2016 (Amazon)
- Design That ScalesDan MallLivro · 2023 (Amazon)
- Versionamento Semântico 2.0.0, veja o FAQSemVer (site externo)
- Component lifecycleUSWDS (site externo)
- Design Tokens Format Module 2025.10DTCG (site externo)
- Keep a Changelog 1.1.0 (site externo)
Os links "Ver na Amazon" são de afiliado: como associado, recebo por compras qualificadas, sem custo a mais para você.