Pular para o conteúdo
murad.guide

A Web Aberta

Capítulo 47

Biblioteca de padrões

7 min de leitura 1.176 palavras 2 gravuras

Este capítulo transforma os módulos da Oficina Costeira numa página que documenta o sistema: a biblioteca de padrões. A Oficina Costeira é um coletivo fictício de design em João Pessoa. Este volume tem 52 capítulos. Esta é a 47.

O exemplo está em exemplos/47-biblioteca-padroes/. Abra padroes.html. O trabalho em equipe entra como GitHub Flow que você consegue simular sozinho. Ciclo: ler, copiar, mudar uma coisa, prever, recarregar, conferir.

O que você vai aprender

Um catálogo ao lado do site

A biblioteca de padrões lista as peças que o site pode usar. Quem constrói uma página nova não inventa um botão. Abre o catálogo, copia o HTML combinado, segue a nota.

Na Oficina Costeira o catálogo é padroes.html. Não substitui Início nem Projetos. É página de oficina, para quem monta o HTML.

<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Padrões — Oficina Costeira</title>
    <link rel="stylesheet" href="assets/stylesheets/main.css">
  </head>
  <body>
    <a class="skip" href="#conteudo">Pular para o conteúdo</a>
    <main id="conteudo" class="wrap">
      <h1>Biblioteca de padrões</h1>
      <section>
        <h2>Botão</h2>
        <p>Use para ação na página. Não envia dado a um servidor.</p>
        <p><button type="button">Ação principal</button></p>
      </section>
      <section>
        <h2>Card</h2>
        <p>Use para um projeto ou uma frente. Título em `h2` ou `h3` conforme a página.</p>
        <article class="card">
          <h3>Título do card</h3>
          <p>Texto de apoio fictício.</p>
        </article>
      </section>
    </main>
  </body>
</html>

O CSS é o mesmo main.css. Se o card da biblioteca divergir do card da home, o sistema quebrou. Uma peça, um visual.

Mude só o texto do botão no catálogo para Inscrever fictício. Preveja o rótulo novo só em padroes.html. Recarregue. Confira a home: o botão, se existir, não muda até você atualizar o módulo de verdade. O catálogo deve espelhar o que o site usa, não um universo paralelo.

Erro comum: estilizar padroes.html com CSS próprio “mais bonito”. A biblioteca mente.

O que cada peça precisa dizer

Para cada padrão, três blocos:

  1. Nome.
  2. Quando usar e quando não usar.
  3. Exemplo HTML que abre e funciona.

Complementos úteis: estado de foco, teclado, aria se o padrão for um controle. Botão precisa de foco de 3 px. Card precisa de título real, não de div.

Não documente vinte variações de cor. Documente o botão principal e, se precisar, o botão secundário com uma classe .botao-secundario. A paleta vem das variáveis :root.

button {
  font: inherit;
  color: #fff;
  background: var(--marca);
  border: 0;
  padding: 0.5rem 1rem;
}

Mude só --marca no :root. Preveja o botão da biblioteca e o cabeçalho mudando juntos. Recarregue padroes.html e index.html. Confira. Se só um mudou, há cor crua no caminho.

Erro comum: print de tela no lugar do HTML de exemplo. Print envelhece. O exemplo vivo quebra na sua frente quando o CSS muda.

Branch: uma alteração, um fio

Branch é uma linha de trabalho no Git. Você sai da linha principal, mexe no card, testa, e só então propõe juntar de volta.

GitHub Flow, em linguagem deste volume:

  1. A linha principal (main) tem o site que abre.
  2. Você cria uma branch padrao-botao.
  3. Commita só o que é do botão.
  4. Abre um pull request (pedido de junção).
  5. Alguém revisa — ou você revisa no dia seguinte, se estiver solo.
  6. Junta. Apaga a branch.

Sozinho, o fluxo ainda vale. A “equipe” pode ser você de manhã e você à noite. O pull request vira uma lista de arquivos e um lugar para escrever o que testou: “Abri padroes.html e a home. Tab no botão. Contraste ok.”

Não precisa de quatro colegas para aprender o ritual. Precisa da disciplina de não commitar direto na main um experimento quebrado.

Mude só o padding do .card numa cópia local. Preveja o catálogo e a home. Recarregue. Confira. Isso é o “teste da branch” mesmo antes do Git.

Erro comum: uma branch alteracoes com biblioteca, JavaScript e README misturados. O revisor não sabe o que aprovar.

Resumo dos conceitos: padrão, doc, troca

Repositório de equipe, simulável solo

Um repositório de equipe tem uma pasta, uma história de commits, issues e combinados. Combinados da Oficina Costeira:

Issue típica, mesmo que você escreva para si:

Título: Acrescentar padrão de lista da equipe

O que: documentar `.lista-grupo` em padroes.html
Como conferir: abrir a biblioteca e equipe.html; Tab; tela estreita
Fora: não publicar; não usar nome de pessoa real

Você fecha a issue quando o padrão está no catálogo e numa página de verdade. Catálogo sem uso é museu. Uso sem catálogo é exceção que vira bagunça.

Mude só o h1 de padroes.html para Padrões da Oficina Costeira. Preveja a aba e o título visível. Recarregue. Confira. O resto do site não precisa do mesmo h1.

Erro comum: mandar o zip do exercício para um servidor público “para a equipe ver”. Use pasta compartilhada local ou um remoto privado, se o grupo já tiver. Este material não pede conta paga.

O que a biblioteca não é

Não é um site gerado por plugin de Jekyll. Não é tema de loja. Não é Moodle. É uma página HTML da própria Oficina Costeira.

Não precisa de hospedagem especial. Abre como as outras. Pode ficar de fora do menu público se você quiser: nem toda visitante precisa do catálogo. Neste volume o arquivo existe na pasta do exemplo para o aluno abrir.

Não copie um “pattern library kit” minificado. Você já tem card, botão, menu, skip-link, formulário de mentira. Documente esses.

Checklist:

Erro comum: biblioteca só com cores e fontes, sem HTML. Paleta não substitui o card.

Conferir o exemplo

Abra exemplos/47-biblioteca-padroes/padroes.html e a home. Compare o card. Percorra o catálogo com teclado. Estreite a janela.

python -m http.server 8769 --bind 127.0.0.1 --directory curso

http://127.0.0.1:8769/exemplos/47-biblioteca-padroes/padroes.html

Encerre com Ctrl+C. Não use 0.0.0.0. Não publique.

Se você estiver com Git no computador, simule o Flow numa pasta de treino, não no zip de entrega, a menos que o autor do volume peça commit. O capítulo cobra o ritual e a página padroes.html, não uma conta no GitHub.

Resumo dos conceitos: troca, doc, padrão

Atividades

  1. Qual a diferença de papel entre index.html e padroes.html?
  2. Por que o botão da biblioteca deve usar o mesmo CSS do site?
  3. Em GitHub Flow, o que você testa antes de juntar a branch?
  4. Como uma pessoa só simula revisão de pull request?
  5. Uma issue da Oficina Costeira deve pedir dados de colegas reais? Por quê?

Respostas comentadas

  1. A home apresenta o coletivo fictício. A biblioteca documenta as peças para quem monta página.
  2. Senão o catálogo mostra um botão que não existe no site. O sistema parte ao meio.
  3. Abrir as páginas afetadas, teclado, tela estreita, e conferir se o padrão novo está no catálogo.
  4. Espera, relê o diff no dia seguinte, percorre o checklist como se fosse outra pessoa, e só então junta.
  5. Não. Personagens fictícios. Formulário de estudo. Nada de telefone, foto ou e-mail de gente de verdade.

Referências

O arquivo completo

Referência do exemplo 47-biblioteca-padroes, reproduzida aqui para que você possa conferir sem sair da página.

assets/javascript/simulacao.js

const form=document.querySelector("#simulacao");if(form){form.querySelector("button[type=submit]").disabled=false;form.addEventListener("submit",event=>{event.preventDefault();document.querySelector("#retorno").textContent="Simulação concluída. Nada foi enviado ou guardado.";});}