DESIGN.pt-BR.md — como construir uma interface para este projeto

O BRAND.pt-BR.md diz o que a marca é: quatro cores, um acento, as cinco palavras, o que não usar. Este arquivo diz como construir com ela — os tokens como existem no código, os componentes que já embarcam, e o que um pull request que acrescenta interface tem de satisfazer.

Leia o BRAND.pt-BR.md primeiro. Onde os dois discordarem, o BRAND vence e este arquivo é o defeito.

01

A folha de estilo é um arquivo, e é a única

docs/hpp.css

Ela é emitida, não escrita à mão: o tools/catalog_md.py guarda uma constante e produz tanto este arquivo quanto o bloco <style> embutido em cada página. É por isso que as duas não podem divergir, e o tests/test_design_system.py reprova se um dia divergirem.

Duas formas de usar, as duas corretas:

<!-- a page inside this repository -->
<link rel="stylesheet" href="hpp.css">

<!-- a page that must survive on its own: paste the file's contents -->
<style>/* contents of docs/hpp.css */</style>

⚠️ Nunca a referencie por URL. Toda página publicada aqui é autossuficiente por regra — uma página que busca a folha de estilo no domínio de outra pessoa para de funcionar no dia em que aquele domínio parar, e a suíte recusa qualquer @import, qualquer https:// dentro de url() e qualquer @font-face.

02

Tokens

Quatro vêm da marca e são as únicas cores do sistema. Quatro são derivados e existem para que ninguém invente uma quinta.

token	valor	para que serve
--hpp-black	#000000	fundo do material de marca e do lockup
--hpp-ink	#0F1113	fundo de interface, superfície elevada
--hpp-paper	#F4F1EB	texto principal sobre escuro
--hpp-signal	#FF6A00	o acento, único
--line	rgba(15,17,19,.18)	régua e borda — o ink a 18%
--surface	rgba(15,17,19,.04)	bloco elevado — o ink a 4%
--muted	rgba(15,17,19,.72)	texto secundário — o ink a 72%
--max	1120px	a medida do .wrap

Os derivados são o ink com alpha reduzido, nunca uma cor nova. O BRAND declara isso: um passo mais claro é o mesmo token com opacidade reduzida. Um teste lê cada rgb() da folha e reprova qualquer trio que não seja 15,17,19 — porque uma quinta cor entrando por um rgba() é invisível para uma varredura de hex.

03

Os componentes que já existem

Use estes antes de inventar. Cada um está no docs/hpp.css e já é renderizado pelas páginas publicadas, então o que o senhor construir com eles fica parecido com o resto do projeto de graça.

seletor	o que é
.wrap	o contêiner. Tudo mora dentro dele, na medida --max
.lang · .lang a[aria-current]	o seletor de idioma. O lado atual carrega aria-current, o outro é link
.hero	a abertura da página: lockup, .eyebrow, h1, um parágrafo
.eyebrow	o rótulo pequeno em monoespaçada acima do título — caixa alta, tracking largo
.lead	o primeiro parágrafo de uma seção, um passo maior
section · h2 · h2 .version · h3	o corpo. O h2 .version imprime a versão ao lado de um título
table · th · td	dado. td.n / th.n alinham número à direita; tr.total marca a linha de totais
.chips code	uma lista de nomes curtos como chips em linha
footer · footer .five	o fecho. O .five carrega as cinco palavras
a:focus-visible	o anel de foco. Nunca remova

04

As regras que não se negociam

1. Um acento só. O laranja marca o ponto de atenção. Uma tela com dois pontos de atenção não tem nenhum — então, se algo novo precisa do laranja, algo perde o laranja.
2. Cor nunca carrega significado sozinha. Um rótulo ou um ícone vai sempre com ela. Quem não distingue o laranja ainda tem de conseguir ler o estado.
3. Sem webfont, sem pedido externo. A pilha de tipos é só de sistema (Sora, Inter, Segoe UI para títulos; JetBrains Mono, Cascadia Code, Consolas para código e rótulo).
4. Sem vermelho na paleta, de propósito. Para estado, use o vermelho do próprio terminal e nunca pinte fundo: um terminal claro tem de continuar legível.
5. Declare o idioma. <html lang>, e lang em qualquer bloco na outra língua. Leitor de tela que lê português com fonema inglês é página que excluiu alguém.
6. O anel de foco fica. Teclado não é plano B.
7. Todo documento de raiz é um par bilíngue. X.md e X.pt-BR.md, linkados um ao outro no topo. Há teste que cobra.

05

O que um pull request com interface tem de satisfazer

• usa o docs/hpp.css — linkado dentro do repo, ou embutido. Nunca por URL
• nao acrescenta uma quinta cor, nem em hex nem em rgb()
• nao busca nada: sem @import, sem @font-face, sem https:// em url()
• reusa os componentes acima antes de acrescentar seletor
• declara lang, e mantem o anel de foco
• traz o par .pt-BR, se for documento de raiz
• e' GERADO, se for morar junto das paginas geradas -- veja a secao seguinte

Depois: python -m pytest tests/test_design_system.py tests/test_docs_index.py -q.

06

Se for morar em docs/, gere

As páginas de docs/ são artefatos emitidos. O index.html, o hpp.css e o par do catálogo são escritos pelo catalog_md.py --write, que sobrescreve a edição à mão sem avisar. Se o senhor quer uma página desse tipo morando ali, acrescente-a ao render_all() do tools/catalog_md.py e ao OWN_FILES, como o index.html e o hpp.css já estão — aí ela é gerada, é listada uma vez, e não apodrece.

As páginas de documento — o X.html ao lado de cada X.md, e as páginas dos documentos de contrato da raiz — são renderizadas a partir do Markdown na release e listadas no docs/site-pages.json, que o catalog_md.py transforma na navegação da página inicial. Edite o Markdown, nunca a página: o tests/test_docs_html_pages.py reprova quando uma página deixa de carregar os títulos do seu Markdown.

Página que mora em qualquer outro lugar (template, exemplo, relatório) é sua para escrever à mão. O multi-session/lane-kit-*/templates/status-stakeholder.template.html é a referência desse caso: mesmos tokens, escrito à mão, e lê o board sem nunca escrever nele.

07

Onde mora a arte

O BRAND.pt-BR.md tem a tabela inteira. Os dois que o senhor vai buscar:

• assets/hpp-logo-header.png — o lockup para topo de página, 1440 px. É a arte aprovada redimensionada; não redesenhar, não recolorir, não recortar.
• assets/hpp-mark.svg — o símbolo em vetor, para impressão ou escala grande. Onde a fidelidade decidir, use o lockup raster.