Marcus Andrey Estudo
Read in English Biblioteca

Design systems · Passo 5 · 8 min de leitura

Versões e releases

Um design system é algo de que outros times dependem, então cada mudança é uma mudança no produto deles. Como funciona o versionamento semântico e o que conta como quebra num design system, como manter a biblioteca do Figma e o pacote de código no mesmo número, como escrever um changelog que as pessoas leem, e um ritmo de releases que os times conseguem planejar.

Um número de versão é um recado para cada time que usa o sistema: quanto cuidado você precisa ter com esta atualização? Um patch diz "pode pegar, nada de que você depende muda". Uma major diz "reserve um tempo". Quando os números de um sistema dizem a verdade, os times atualizam sempre e as correções chegam aos usuários. Quando não dizem, os times param de atualizar, e o sistema se divide em tantas versões quanto há produtos.

O que você vai conseguir fazer depois de ler:

  • Explicar MAJOR, MINOR e PATCH em palavras simples
  • Decidir que tipo de mudança é uma mudança no design system, inclusive as que parecem inofensivas
  • Manter a biblioteca do Figma e o código na mesma versão
  • Escrever um changelog e notas de versão que as pessoas usam

1. Três números, três promessas

O versionamento semântico (Semantic Versioning), a convenção que a maioria dos pacotes de código segue, dá a uma versão três números, MAJOR.MINOR.PATCH, e diz para aumentar (Semantic Versioning 2.0.0):

  • MAJOR "when you make incompatible API changes", quando você muda a API de um jeito incompatível
  • MINOR "when you add functionality in a backward compatible manner", quando acrescenta algo sem quebrar o que existe
  • PATCH "when you make backward compatible bug fixes", quando corrige bugs sem quebrar o que existe

Mais duas regras importam para design systems. A versão 0.y.z "is for initial development. Anything MAY change at any time", é para o desenvolvimento inicial e qualquer coisa pode mudar, então um sistema que ainda está achando a sua forma pode dizer isso com honestidade. E descontinuar algo é uma minor: o número minor "MUST be incremented if any public API functionality is marked as deprecated", precisa subir quando algo da API é marcado como descontinuado, e o FAQ da especificação pede "at least one minor release that contains the deprecation", pelo menos uma minor com a descontinuação antes da major que remove (Semantic Versioning 2.0.0). Como fazer bem essa descontinuação está em Descontinuação e breaking changes.


2. O que "quebrar" quer dizer num design system

Mudança no HarbourNúmeroPor quê
O anel de foco do Campo de texto tinha 1 px, a especificação diz 2 px; corrigidoPATCH 2.3.0 → 2.3.1Correção de bug. Nada de que alguém dependa muda
Novo size="compact" no Button, para o console da equipeMINOR 2.3.1 → 2.4.0Novo e opcional. As telas antigas continuam funcionando
color.brand.blue marcado como descontinuado, trocado por color.action.primaryMINOR 2.4.0 → 2.5.0O SemVer diz que descontinuações vão numa minor, antes da remoção
color.brand.blue removido; kind do Button renomeado para variantMAJOR 2.5.0 → 3.0.0Quebra quem ainda usa os nomes antigos
O Button padrão passa do visual secundário para o primárioMAJORNenhum nome mudou, mas toda tela que usava o padrão agora fica diferente
Versionamento semântico aplicado a um design system. O teste de cada linha é o mesmo: algo que funcionava ontem vai quebrar, ou ficar diferente, sem ninguém mexer? A última linha é a que os times esquecem: mudar um padrão é uma breaking change mesmo quando a API é idêntica.Regras do Semantic Versioning 2.0.0; as mudanças do Harbour são inventadas para este curso.

Numa biblioteca de código, a API são as funções e os seus argumentos. Num design system, a API é maior: tudo aquilo de que um produto depende sem pensar. Isso inclui:

  • Nomes: componentes, props, valores de opção, tokens, custom properties do CSS, nomes de propriedade no Figma.
  • Padrões: como um componente é e se comporta quando ninguém configura nada.
  • Layout: um Button que cresce 4 px pode empurrar um formulário para baixo da dobra em toda tela que o usa.
  • Comportamento: um Diálogo que agora fecha com um clique fora muda o que o usuário pode perder.

Então o teste não é "a API mudou?", mas "algo que funcionava ontem vai quebrar, ou ficar diferente, sem ninguém mexer?" Se sim, é uma major, mesmo que a mudança no código seja de uma linha. Os testes visuais no Storybook (Storybook e documentação viva) são como você descobre antes da versão sair. A primeira vez que um time ouve o termo costuma ser em inglês: uma mudança que quebra é uma breaking change.


3. Um número para Figma e código

O fluxo de publicação do Figma pede uma descrição, não um número de versão: cada publicação leva a descrição que você escreve, que as pessoas veem quando aceitam a atualização e no histórico de versões do arquivo (Figma, Publish a library). O pacote de código tem número. O Harbour junta os dois:

  • O pacote @tidewater/harbour segue o versionamento semântico.
  • A publicação da biblioteca correspondente começa a descrição com o mesmo número: "3.0.0: kind do Button agora é variant…".
  • A capa de cada arquivo da biblioteca mostra a versão atual (veja Montar uma biblioteca no Figma).

Assim, design e desenvolvimento podem dizer "estamos na 3.0" e falar da mesma coisa. Lembre que quem assina a biblioteca escolhe quando aceitar a atualização, então o lado do design também fica para trás. O número diz com quanto cuidado aceitar.


4. Um changelog que as pessoas leem

Changelog do Harbour

Segue o versionamento semântico · a biblioteca Figma e o @tidewater/harbour têm o mesmo número

Unreleasedem revisão

Adicionado

  • Cartão de travessia: slot status para atrasos e cancelamentos

3.0.06 out. 2026Quebra

Removido

  • color.brand.blue, descontinuado na 2.5.0. Use color.action.primary

Alterado

  • Button: kind agora é variant, no código e no componente do Figma, na mesma versão

Como atualizar

  • Guia de migração, uns 20 minutos por produto. Plantão de dúvidas na quinta

2.5.01 set. 2026

Descontinuado

  • color.brand.blue. Remoção prevista para a 3.0.0

Adicionado

  • Modo escuro no Diálogo e na Seleção

2.4.04 ago. 2026

Adicionado

  • Button: size="compact", para o console da equipe

Corrigido

  • Campo de texto: anel de foco de volta a 2 px
Um changelog preenchido do Harbour, do mais novo para o mais antigo, agrupado por tipo de mudança. Um número só para design e código significa que designer e dev podem dizer "estamos na 3.0" e falar da mesma coisa. A versão que quebra diz o que saiu, o que usar no lugar e quanto tempo leva a atualização.Formato inspirado no Keep a Changelog 1.1.0; as versões são inventadas.

O Keep a Changelog define o changelog como "a curated, chronologically ordered list of notable changes for each version", uma lista cuidada, em ordem cronológica, das mudanças relevantes de cada versão, e os seus princípios servem bem a design systems: "Changelogs are for humans, not machines" (changelogs são para pessoas, não para máquinas), "The latest version comes first" (a versão mais nova vem primeiro), e as mudanças agrupadas em Added, Changed, Deprecated, Removed, Fixed e Security, com uma seção Unreleased no topo para o que está por vir (Keep a Changelog 1.1.0).

Num design system, acrescente três coisas a toda major:

  1. O que usar no lugar de tudo o que saiu.
  2. Quanto tempo a atualização leva, medido num produto real.
  3. Onde pedir ajuda: um guia de migração, um plantão de dúvidas, um canal.

Escreva para a designer ocupada e para o dev cansado. "Fixed focus ring" é mensagem de commit. "Campo de texto: anel de foco de volta a 2 px" é uma linha de changelog.


5. Um ritmo de releases

  • Uma cadência fixa para as minors, a cada duas ou quatro semanas, para os times saberem quando olhar.
  • Patches quando precisar, principalmente para bugs de acessibilidade, que não devem esperar.
  • Majors raras e anunciadas cedo: pelo menos uma minor antes com as descontinuações, e uma data.
  • O mesmo dia para design e código. Publicar a biblioteca antes de o pacote sair faz o design desenhar o que o desenvolvimento ainda não consegue construir, e o contrário também.
  • Mantenha suporte a mais de uma major por um tempo, e diga por quanto tempo. Ninguém atualiza na semana em que a major sai.

6. Erros comuns

  • Chamar uma mudança visual de patch porque "a API não mudou".
  • Remover algo sem uma versão de descontinuação antes.
  • Publicar a biblioteca do Figma num ritmo diferente do código.
  • Changelogs copiados das mensagens de commit.
  • Majors tão frequentes que os times param de atualizar.
  • Um sistema parado em 0.y.z por anos, então nada nunca é prometido.

7. Vocabulário

Termo Significado
Versionamento semântico (SemVer) MAJOR.MINOR.PATCH, onde cada número diz que tipo de mudança é
Mudança que quebra (breaking change) Uma mudança que faz algo que funcionava parar de funcionar, ou ficar diferente, sem ninguém mexer
Descontinuação Marcar algo como prestes a sair, enquanto ainda funciona
Changelog Uma lista das mudanças relevantes por versão, da mais nova para a mais antiga
Notas de versão O recado de uma versão: o que mudou, quem precisa agir e como
Guia de migração Instruções passo a passo para ir de uma major para a próxima

8. Experimente (sem ferramentas)

  1. Anote as cinco últimas mudanças que o seu time fez nos componentes ou estilos.
  2. Para cada uma, pergunte: algo que funcionava ontem vai quebrar ou ficar diferente sem ninguém mexer?
  3. Dê um número para cada uma: patch, minor ou major. Depois escreva uma linha de changelog para cada, pensando numa pessoa ocupada.

Perguntas para refletir: Qual das cinco você teria chamado de patch antes desta aula? Alguém no seu time sabe em que versão do sistema o produto está?


9. Se você já pratica

  • Coloque a versão na capa de cada arquivo da biblioteca e em toda descrição de publicação.
  • Rode testes visuais antes de cada versão e anexe a diferença à revisão da versão.
  • Meça quanto tempo a última major levou para um time adotar, e coloque esse número nas notas da próxima.
  • Acompanhe quantos produtos estão na major mais recente: é uma das medidas de Medir a adoção.

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

Descontinuação e breaking changes · Storybook e documentação viva · Montar uma biblioteca no Figma · Modelos de contribuição · Movimento na governança do design system · Versionamento semântico para design systems

Salvo só neste dispositivo.

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