Neste mini-projeto, o objetivo é transformar um kit de UI já existente em um artefato adotável pelo time: documentado, com regras de uso claras, pontos de decisão explícitos e um caminho de onboarding que reduza dúvidas. A diferença entre “ter componentes” e “ter um Design System utilizável” costuma estar menos no desenho e mais na documentação prática: quando usar, quando não usar, como combinar, o que é permitido customizar e como pedir mudanças sem quebrar a consistência.
O foco aqui é produzir documentação orientada à adoção: páginas e seções que respondem às perguntas reais de quem vai usar o kit (designers, devs, PMs e QA). Você vai criar um pacote mínimo de documentação que funcione como “manual de operação” do kit, com exemplos, regras e um fluxo de contribuição simples. Não vamos repetir estrutura de arquivos, taxonomia, tokens, componentes, governança ou handoff em si; vamos usar esses elementos como insumos e concentrar no que falta para o time conseguir aplicar o kit com segurança.
O que significa “adoção pelo time” na prática
Adoção não é só “todo mundo tem acesso à biblioteca”. Adoção é quando o kit vira padrão de decisão e execução. Para isso, a documentação precisa reduzir três tipos de fricção:
Fricção de entendimento: “Qual componente eu uso para este caso?” “Posso alterar este padding?” “Como esse componente se comporta em erro?”
Fricção de confiança: “Isso está atualizado?” “Esse padrão é aprovado pelo time de dev?” “Se eu usar, vai dar retrabalho?”
Continue em nosso aplicativo
Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.
ou continue lendo abaixo...
Baixar o aplicativo
Fricção de contribuição: “Como eu peço uma melhoria?” “Como eu proponho um novo componente?” “Quem aprova?”
O mini-projeto guiado vai atacar essas fricções com um conjunto de páginas e regras. Pense como um “contrato social” do kit: o que ele cobre, o que não cobre, e como evolui.
Escopo do mini-projeto: o pacote mínimo de documentação
Você vai produzir cinco entregáveis (em formato de páginas de documentação dentro do próprio arquivo do kit ou em um espaço de documentação do time, desde que o conteúdo seja o mesmo):
1) Página “Comece por aqui”: propósito, público, o que está dentro/fora do escopo e como usar no dia a dia.
2) Guia de uso do kit (regras operacionais): regras de composição, customização permitida, do’s & don’ts, decisões comuns.
3) Catálogo de padrões (recipes): combinações recomendadas de componentes para cenários recorrentes.
4) Guia de contribuição (como pedir mudanças): como abrir demanda, critérios mínimos, evidências necessárias, fluxo de aprovação.
5) Checklist de adoção por squad: passos para um time começar a usar e medir aderência.
Esses entregáveis são pequenos, mas precisam ser específicos. A regra é: cada seção deve responder a uma pergunta real e frequente.
Passo a passo prático: construindo a página “Comece por aqui”
Passo 1 — Declare o propósito em uma frase operacional
Evite frases genéricas do tipo “garantir consistência”. Escreva algo que indique como o kit deve ser usado:
Exemplo: “Este kit é a fonte padrão para criar telas de produto web e mobile, reduzindo variações visuais e acelerando o handoff ao desenvolvimento.”
Passo 2 — Defina o público e o nível de maturidade esperado
Liste quem usa e para quê. Isso evita que alguém espere que o kit resolva problemas fora do escopo.
Design: montar fluxos, protótipos e specs com componentes do kit.
Dev: validar paridade com implementação e identificar gaps.
PM/QA: revisar consistência e critérios de aceitação visual.
Passo 3 — Escreva “O que este kit cobre” e “O que este kit não cobre”
Essa seção é decisiva para adoção, porque elimina interpretações. Seja explícito:
Cobre: componentes essenciais, padrões de formulários, feedbacks (erro/sucesso), navegação, modais, tabelas, cards, empty states.
Não cobre (por enquanto): ilustrações, templates completos por produto, motion avançado, padrões específicos de um único squad.
Passo 4 — Defina o “caminho feliz” de uso em 4 passos
Crie um mini fluxo de como alguém deve começar um arquivo de design usando o kit. Exemplo:
1) Comece por um frame de layout padrão (se existir) ou por grids definidos pelo time.
2) Monte a tela usando componentes do kit (sem detach).
3) Ajuste apenas propriedades expostas (variants/properties) e conteúdo.
4) Se faltar algo, registre no canal de contribuição antes de criar um componente paralelo.
Passo 5 — Inclua “Regras rápidas” (5 bullets)
Essa seção funciona como um “cartaz” que as pessoas leem. Exemplos úteis:
Não criar novos estilos locais para cores e tipografia.
Evitar detach de instâncias; se necessário, justificar no ticket.
Preferir padrões do catálogo antes de inventar combinações novas.
Qualquer novo componente precisa de caso de uso e estado de erro.
Se houver conflito com implementação, registrar como gap (não “resolver” só no design).
Passo a passo prático: Guia de uso do kit (regras operacionais)
Agora você vai escrever regras que orientam decisões. O segredo é organizar por situações, não por teoria. Estruture em blocos com títulos que pareçam perguntas.
Bloco A — Quando usar componente vs. padrão (recipe)
Explique que componentes são peças e padrões são combinações aprovadas. Dê exemplos de decisão:
Use um componente quando você precisa de uma peça isolada (ex.: botão, input, badge).
Use um padrão quando a combinação já é recorrente e tem regras (ex.: “Formulário com validação”, “Modal de confirmação”, “Empty state com CTA”).
Bloco B — O que pode ser customizado (e o que não pode)
Crie uma tabela textual (em lista) com “permitido” e “não permitido”. Isso reduz variações e evita discussões.
Permitido: texto, ícone (quando houver slot), estado via propriedade, tamanho via variante, largura do container, conteúdo dinâmico.
Não permitido: alterar raio, alterar cores fora das opções, criar sombras novas, mudar espaçamentos internos sem propriedade, editar a estrutura interna do componente.
Inclua uma regra de exceção: quando algo “não permitido” for necessário, deve virar solicitação de melhoria do kit.
Bloco C — Regras de composição (como combinar sem quebrar)
Liste regras simples e verificáveis. Exemplos:
Não misturar dois padrões de feedback na mesma área (ex.: toast + inline error) sem justificativa.
Em formulários, mensagens de erro devem ficar sempre no mesmo local relativo ao campo.
Em listas, ações primárias devem manter posição consistente (ex.: sempre à direita).
Bloco D — Regras de conteúdo (microcopy) para consistência
Mesmo sem entrar em guidelines completas de conteúdo, defina regras mínimas para evitar variações que parecem “design”.
Botões: verbo no imperativo (“Salvar”, “Continuar”).
Confirmações: título descreve a ação, corpo descreve impacto, CTA primário repete o verbo.
Erros: dizer o que aconteceu e como resolver, sem culpar o usuário.
Bloco E — Regras para responsividade e densidade
Sem repetir técnicas de Auto Layout, documente decisões: quando usar versão compacta vs. confortável, e quais componentes têm variações de densidade.
Em tabelas, usar densidade compacta quando houver mais de X colunas ou quando a tela for de operação.
Em mobile, preferir padrões de ação fixa (ex.: barra inferior) quando houver CTA primário recorrente.
Passo a passo prático: Catálogo de padrões (recipes) orientado a cenários
O catálogo de padrões é o que mais acelera adoção porque reduz decisões. Em vez de listar componentes, liste “receitas” com: contexto, composição, variações e anti-exemplos.
Passo 1 — Selecione 6 a 10 cenários recorrentes
Escolha cenários que aparecem em vários squads. Exemplos:
Login com erro e recuperação
Formulário com validação e ajuda contextual
Modal de confirmação destrutiva
Empty state com CTA e link secundário
Lista com filtros + paginação
Detalhe com ações (header + ações + conteúdo)
Passo 2 — Para cada padrão, documente em um template fixo
Use sempre a mesma estrutura para facilitar leitura:
Quando usar: 2 a 3 bullets.
Quando não usar: 1 a 2 bullets.
Composição: lista de componentes e ordem.
Variações: ex.: com/sem descrição, com/sem ícone, compacto/confortável.
Regras: 3 a 6 regras objetivas.
Exemplos: 1 exemplo correto e 1 incorreto (do/don’t).
Passo 3 — Escreva regras que previnem divergência
Exemplo de regras para “Modal de confirmação destrutiva”:
Título deve nomear a ação (“Excluir item”, “Remover acesso”).
CTA primário deve ser a ação destrutiva e usar estilo destrutivo.
CTA secundário deve ser “Cancelar” e ficar à esquerda (ou conforme padrão do produto).
Se a ação for irreversível, o corpo deve declarar isso explicitamente.
Passo 4 — Inclua “decisões rápidas” (if/then)
Esse formato é muito adotável. Exemplo:
Se o usuário puder desfazer, então use confirmação leve (toast com undo) em vez de modal.
Se houver risco alto, então use modal com descrição do impacto.
Passo a passo prático: Guia de contribuição (como pedir mudanças sem criar paralelos)
Sem um caminho claro de contribuição, a adoção degrada: as pessoas criam variações locais “temporárias” que viram permanentes. O guia de contribuição deve ser curto e operacional.
Passo 1 — Defina tipos de solicitação
Crie categorias para organizar triagem:
Bug: algo no kit está quebrado (ex.: alinhamento, estado faltando, propriedade inconsistente).
Melhoria: ajuste em componente/padrão existente (ex.: adicionar tamanho, expor propriedade, melhorar legibilidade).
Novo: novo componente ou novo padrão (recipe).
Alinhamento com código: divergência entre kit e implementação.
Passo 2 — Crie um formulário mínimo (o que precisa vir em toda solicitação)
Você pode documentar isso como um template de ticket. Exemplo:
Tipo: (Bug | Melhoria | Novo | Alinhamento com código) Contexto: qual tela/fluxo e qual problema está sendo resolvido Evidência: link do frame + print do caso real Impacto: quem é afetado e com que frequência Proposta: o que você sugere (se houver) Alternativas consideradas: por que não usar o que já existe Critérios de aceite: como saber que ficou corretoEsse template força clareza e evita discussões abstratas.
Passo 3 — Defina SLA e prioridades (simples)
Não precisa ser burocrático, mas precisa existir. Exemplo:
Bugs críticos: triagem em até 48h úteis.
Melhorias: triagem semanal.
Novos componentes: entram em backlog e exigem validação de recorrência (ex.: aparecer em 2 squads ou 2 fluxos).
Passo 4 — Defina critérios para aceitar um “Novo”
Escreva critérios objetivos para evitar inflar o kit:
Existe recorrência comprovada (mais de um contexto).
Há variações e estados mapeados (incluindo erro quando aplicável).
Existe padrão de conteúdo (título, descrição, microcopy).
Há alinhamento com implementação ou plano de implementação.
Passo 5 — Regra anti-paralelo: o que fazer quando “não existe no kit”
Documente uma regra clara para evitar que cada squad crie sua própria versão:
Se não existe, primeiro procurar no catálogo de padrões.
Se não existe, criar solução temporária marcada como “Provisório” e abrir solicitação no mesmo dia.
Provisório não pode virar componente reutilizável sem passar pelo fluxo de contribuição.
Passo a passo prático: Checklist de adoção por squad
O checklist é um roteiro de implantação. Ele ajuda líderes de design e dev a adotarem sem depender de você. Estruture em fases: preparar, aplicar, validar, manter.
Fase 1 — Preparar (antes de começar a desenhar)
Confirmar que o squad tem acesso à biblioteca correta e está usando a versão combinada.
Definir um “ponto focal” do squad para dúvidas e triagem de gaps.
Escolher um fluxo piloto (1 a 2 telas) para aplicar o kit primeiro.
Fase 2 — Aplicar (durante o design)
Usar componentes do kit sem detach.
Preferir recipes do catálogo para formulários, modais e listas.
Registrar gaps conforme aparecem (não acumular para o final).
Fase 3 — Validar (antes de handoff)
Rodar uma revisão rápida de consistência: estados, mensagens, hierarquia de ações.
Checar se não há estilos locais “novos” criados por conveniência.
Garantir que exceções estão justificadas e registradas como solicitação.
Fase 4 — Manter (após entrega)
Se o dev precisar adaptar algo, registrar como “alinhamento com código” (não ajustar só no design).
Revisar mensalmente os gaps mais frequentes e priorizar melhorias do kit.
Como escrever regras de uso que realmente funcionam (heurísticas práticas)
Regras boas são testáveis e evitam ambiguidade. Use estas heurísticas ao redigir:
Troque “deve ser consistente” por uma regra observável: “O botão primário fica sempre à direita em modais” é verificável; “seja consistente” não.
Inclua um motivo curto: “para manter previsibilidade” ou “para reduzir erro de clique”. Isso aumenta adesão.
Defina exceções: “Exceto em mobile quando…” evita que a regra seja ignorada por ser rígida demais.
Use exemplos de do/don’t: uma imagem (ou frame) correto e outro incorreto elimina interpretação.
Evite regras que dependem de gosto: prefira critérios (densidade, hierarquia, risco, frequência).
Mini-projeto guiado: roteiro de execução em 90 a 120 minutos
Se você precisa executar rápido, siga este roteiro cronometrado. A ideia é sair com um “MVP de documentação” publicável.
0–15 min — Inventário de dúvidas frequentes
Liste 15 perguntas que o time faria ao usar o kit. Exemplos:
“Posso mudar o ícone do botão?”
“Qual padrão usar para confirmação?”
“Como tratar erro em formulário longo?”
“O que faço quando não existe componente?”
Essas perguntas viram títulos de seções.
15–35 min — Escrever “Comece por aqui”
Preencha: propósito, cobre/não cobre, caminho feliz, regras rápidas. Não tente ser perfeito; seja claro.
35–65 min — Escrever o Guia de uso (regras operacionais)
Crie 5 blocos (A–E) e escreva regras em bullets. Para cada bloco, inclua ao menos 1 exemplo prático (mesmo que seja textual).
65–95 min — Criar 6 recipes essenciais
Escolha 6 cenários e documente com o template fixo. Se o time for mais operacional (B2B), priorize tabela/lista/filtros/empty state. Se for mais consumer, priorize onboarding/login/checkout/erro.
95–110 min — Escrever o Guia de contribuição
Defina tipos, template de ticket, SLA simples e critérios de aceitação de novos itens.
110–120 min — Checklist de adoção
Escreva as quatro fases e publique como uma página curta para squads.
Exemplos práticos de regras (prontas para copiar e adaptar)
Regras para botões em telas
Em qualquer tela, deve existir no máximo um CTA primário por área de foco (header, corpo, footer) para evitar competição visual.
Se houver ação destrutiva, ela nunca deve ser o CTA primário fora de contexto de confirmação.
Em formulários, “Salvar” deve ficar alinhado ao final do fluxo (após os campos), e “Cancelar” deve ser secundário.
Regras para mensagens de erro
Erros de campo devem ser inline e aparecer após interação (blur/submit), exceto quando o dado é inválido por padrão (ex.: formato impossível).
Erros globais (ex.: falha de rede) devem aparecer como banner/toast e não substituir erros de campo.
Mensagens devem indicar ação: “Digite um e-mail válido (ex.: nome@dominio.com)”.
Regras para tabelas e listas
Ações por linha devem ser consistentes: se usar menu de overflow em uma tabela, usar em todas as tabelas do produto, salvo exceção documentada.
Se a lista tiver filtros, sempre mostrar estado vazio com explicação e ação de limpar filtros.
Como validar se a documentação está pronta para adoção
Antes de considerar o mini-projeto concluído, valide com um teste simples: peça para alguém do time executar uma tarefa sem sua ajuda, usando apenas a documentação.
Teste 1 — Designer: montar uma tela com um padrão
Tarefa: “Monte um formulário com validação e um modal de confirmação destrutiva.”
Critério de sucesso: a pessoa encontra o recipe, aplica regras e não cria variações locais.
Teste 2 — Dev: revisar uma tela e apontar gaps
Tarefa: “Revise este frame e liste o que está fora do kit e como registrar.”
Critério de sucesso: a pessoa usa o template de ticket e classifica corretamente (bug/melhoria/novo).
Teste 3 — PM/QA: checar consistência
Tarefa: “Verifique se há mais de um CTA primário e se mensagens de erro seguem o padrão.”
Critério de sucesso: a pessoa encontra regras rápidas e consegue auditar sem depender de contexto de design.
Se esses testes falharem, o problema quase sempre é: regras vagas, falta de exemplos, ou ausência de um caminho claro para exceções. Ajuste a documentação até que alguém consiga operar o kit com autonomia.
