Tudo o que uma nota pode conter

Esta nota é um inventário. Serve para verificar que todos os elementos de composição funcionam como esperado — tipograficamente, estruturalmente, semanticamente. Não é para publicar, é para ver.

Fica aqui como referência permanente. Quando se adiciona um novo elemento ao sistema, testa-se aqui primeiro.

Cabeçalhos

Os cabeçalhos estabelecem hierarquia. O h1 é o título da nota e não aparece no corpo. Aqui começa no h2.

Nível 3

Usado para subsecções dentro de uma secção principal.

Nível 4

A partir daqui, o estilo muda: caixa alta, espaçamento de letras, mesmo tamanho que o corpo. Sinal de aviso tipográfico.

Nível 5

Raramente justificável. Se chegares aqui, questiona a estrutura.

Nível 6

O fundo do poço hierárquico. Usa-o e questiona-te.

Texto e formatação inline

Parágrafo normal, com espaçamento vertical entre parágrafos sucessivos. O corpo de texto usa a escala fluida definida nos tokens — cresce ligeiramente entre viewport estreita e larga, sem saltos.

Segundo parágrafo, para verificar o espaçamento. Negrito para ênfase forte. Itálico para ênfase suave, títulos de obras, ou termos estrangeiros. Negrito e itálico em simultâneo, usado com parcimónia. código inline dentro de uma frase, para referir identificadores, comandos, ou valores.

Texto com riscado, para conteúdo revogado ou corrigido que convém manter visível.

Texto com destaque, equivalente ao marca-texto. Texto com eliminado e inserido para rastreabilidade de alterações. Referências com CSS onde a expansão acrescenta valor.

Expoentes: E = mc². Índices: H₂O. Combinados: CO₂ a 400 ppm é já ^{[citação necessária]}.

Atalhos de teclado: pressiona ⌘ + K para abrir o palete de comandos. Ou Ctrl + Shift + P no Windows.

Listas

Lista não ordenada simples

• Primeiro item
• Segundo item
• Terceiro item

Lista com vários níveis

• Primeiro nível
  • Segundo nível
  • Outro item no segundo nível
    • Terceiro nível
      • Quarto nível — aqui o outline colapsa por defeito
      • Mais um no quarto
    • De volta ao terceiro
  • De volta ao segundo
• De volta ao primeiro

Lista ordenada

1. Abre o terminal
2. Navega para o directório do projecto
3. Corre npm run build
4. Verifica o output em _site/
5. Faz deploy se tudo estiver bem

Lista ordenada com sublista mista

1. Escolhe uma abordagem
   • Abordagem A: rápida, frágil
   • Abordagem B: lenta, robusta
2. Implementa com testes
3. Documenta as decisões

Lista de definições (HTML em Markdown)

Design system

Um conjunto de decisões documentadas, componentes reutilizáveis, e princípios que tornam o design consistente à escala.

Token

Um valor nomeado que representa uma decisão de design — cor, espaçamento, tipografia — independente da sua implementação concreta.

Grelha

A estrutura invisível que torna a disposição de elementos previsível e audível.

Lista de tarefas

• Definir a paleta de cores
• Estabelecer a escala tipográfica
• Criar os tokens CSS
• Documentar os padrões de composição
• Publicar o guia de estilo
• Verificar acessibilidade em todos os componentes

Citações

Uma citação simples:

O que não está documentado não existe. O que existe sem documentação é acidente.

Uma citação mais longa, com atribuição manual:

A tipografia tem uma função antes de ter uma forma. A legibilidade não é uma restrição — é o ponto de partida. Qualquer decisão que não serve o conteúdo serve apenas o designer.

— Emil Ruder, Typographie als Ausdruck, 1959

Citação aninhada:

Perguntaram-lhe o que era o design.

"É a intenção tornada visível", respondeu.

Ninguém ficou satisfeito com a resposta. Ele também não.

Código

Código inline

Usa const em vez de let quando o valor não muda. O selector .note-body aplica estilos de prosa. A propriedade --text-base é um token CSS.

Bloco de código — CSS

/* Escala tipográfica fluida */
:root {
  --text-sm:      clamp(0.875rem, 0.825rem + 0.25vw, 1rem);
  --text-base:    clamp(1rem,     0.95rem  + 0.25vw, 1.125rem);
  --text-lg:      clamp(1.25rem,  1.1rem   + 0.65vw, 1.625rem);
  --text-xl:      clamp(1.875rem, 1.5rem   + 1.5vw,  2.75rem);
  --text-display: clamp(3rem,     2.25rem  + 3vw,    5.5rem);
}

Bloco de código — JavaScript

// Wikilink resolver — transforma título em <a href="...">
function resolveWikilinks(content, pages) {
  const pageMap = new Map(
    pages
      .filter(p => p.data.title && p.page.url)
      .map(p => [p.data.title.toLowerCase(), p.page.url])
  );

  return content.replace(/\[\[([^\]]+)\]\]/g, (_, title) => {
    const url = pageMap.get(title.toLowerCase());
    return url ? `<a href="${url}">${title}</a>` : title;
  });
}

Bloco de código — HTML

<!DOCTYPE html>
<html lang="pt">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>tavar.es</title>
  </head>
  <body>
    <a href="#main" class="skip-link">Saltar para o conteúdo</a>
    <main id="main">
      <h1>Olá.</h1>
    </main>
  </body>
</html>

Bloco de código — Bash

# Build e verificação de acessibilidade
npm run build && npm run check:a11y

# Servir localmente com hot reload
npx @11ty/eleventy --serve --port=8080

Bloco de código — Python

def encode_email(email: str, key: int = 23) -> str:
    """XOR-encode an email address for obfuscation in HTML."""
    return "".join(
        format(ord(c) ^ key, "02x")
        for c in email
    )

Bloco de código — JSON

{
  "name": "tavar.es",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "eleventy",
    "start": "eleventy --serve"
  }
}

Bloco de código sem linguagem

Texto pré-formatado sem highlighting.
Útil para output de terminal, logs, ou conteúdo ASCII.

    ┌─────────────────────────────┐
    │  nome          tipo         │
    │  ──────────    ────────     │
    │  --text-sm     clamp()      │
    │  --text-base   clamp()      │
    └─────────────────────────────┘

Tabelas

Tabela simples

Tabela com múltiplas colunas e alinhamento

Tabela com alinhamento de colunas

Imagens

Imagem simples (sem legenda)

Imagem com legenda

Imagem com largura explícita

Ligações

Wikilink para outra nota

Esta nota relaciona-se com design como prática e com linguagem no design.

Ligação externa explícita

Eleventy — documentação oficial

URL exposta (linkificada automaticamente)

https://www.w3.org/WAI/WCAG22/Understanding/

Ligação de email (obfuscada automaticamente no build)

Podes contactar-me em miguel [at] tavar [dot] es.

Divisória horizontal

Uma regra horizontal dentro do corpo de uma nota tem estilo diferente da regra que separa secções de layout — é tracejada e mais fina.

Após a regra.

Notas de rodapé

O sistema de notas de rodapé^[1] é gerido pelo plugin markdown-it-footnote.^[2] As notas aparecem no fim da página, separadas do corpo por uma regra horizontal.^[3]

Pode-se referenciar a mesma nota várias vezes.^[1:1]

HTML em linha

Markdown permite HTML em linha quando nenhuma sintaxe Markdown cobre o caso.

Detalhes e sumário (disclosure widget)

Mostrar detalhes técnicos

Este conteúdo está escondido por defeito e expandido ao clicar. Útil para informação acessória que não deve sobrecarregar o fluxo principal.

Pode conter qualquer conteúdo HTML. Não é Markdown processado dentro de <details> por defeito no markdown-it — precisaria de configuração adicional.

Sup, sub, abbr, kbd, mark, del, ins

W3C define os padrões. O WCAG 2.2 é o nível mínimo de acessibilidade que este sítio cumpre.

Pressiona Tab para navegar entre elementos interactivos. Enter ou Espaço para activar. Escape para fechar diálogos.

O texto marcado a amarelo chama a atenção para partes específicas de uma citação ou listagem.

Versão 1.0 2.0 — a primeira foi removida, a segunda inserida.

E = mc². A fórmula da água é H₂O. Nota à margem^*.

Tabela com células mais ricas

Conteúdo misto — tudo junto

Uma secção que mistura tipos de conteúdo como acontece numa nota real.

Ao rever o sistema de design, identifiquei três categorias de problemas^[4]:

1. Tokens sem uso — valores definidos mas nunca referenciados em componentes. Acumulam-se com o tempo.
2. Componentes sem tokens — valores hardcoded em vez de variáveis. Difíceis de actualizar globalmente.
3. Inconsistências de escala — espaçamentos que não pertencem a nenhuma escala definida.

A correcção passa por um processo iterativo:

• Auditar o código existente (ver ferramentas que uso para a lista de ferramentas)
• Mapear cada valor para o token mais próximo
• Eliminar duplicados
• Documentar excepções justificadas

A disciplina não é a ausência de exceções. É saber exactamente onde e porquê existem.

O estado actual do sistema:

Os três espaçamentos e duas bordas sem token são excepções documentadas. Não são erros — são decisões.^[4:1]

---

1. Esta é uma nota de rodapé simples, referenciada múltiplas vezes no texto. ↩︎ ↩︎

2. As notas de rodapé podem ter identificadores arbitrários — não precisam de ser números. O identificador não aparece no output; o que aparece é a sequência numérica gerada automaticamente.

   As notas de rodapé podem também ter vários parágrafos. Basta indentar o conteúdo adicional com quatro espaços ou um tab. Isto permite notas longas sem quebrar o fluxo do texto principal. ↩︎

3. Esta é a terceira nota, mas o seu identificador é 3. A numeração no output é sempre sequencial, independentemente dos identificadores usados. ↩︎

4. A auditoria foi feita manualmente com grep e uma folha de cálculo. Não é elegante mas funciona. Ferramentas sofisticadas introduzem complexidade; às vezes a complexidade certa é um terminal aberto. ↩︎ ↩︎