# rnqs.app · base visual v0.1

Rascunho de identidade compartilhada para projetos de Renan Arques. Use este guia ao criar uma interface rnqs.app ou adaptar um projeto à marca. A página inicial continua como expressão mais intensa da identidade; interfaces usam a mesma linguagem com menos textura e títulos menores.

## Como aplicar

1. Leia este guia e copie [tokens.css](./tokens.css), junto com as fontes e licenças de `../assets/`. Ajuste os caminhos dos `@font-face` à estrutura do projeto.
2. Aplique `data-theme="light"` ou `data-theme="dark"` no elemento raiz. Escolha inicialmente o tema do sistema e permita uma preferência explícita. Os tokens sem seletor usam dark como fallback.
3. Use os tokens semânticos nos componentes. `tokens.css` é a fonte dos valores; esta página exemplifica o uso. Ao mudar um valor, atualize os exemplos e recalcule os contrastes.
4. Valide os dois temas, navegação por teclado, redução de movimento e layout a 360 px antes de considerar a aplicação pronta.

```css
@import './tokens.css';
body {
  background: var(--color-bg);
  color: var(--color-text);
  font: 400 16px/1.6 var(--font-body);
}
.primary-action {
  background: var(--color-accent);
  color: var(--color-on-accent);
  border: 1px solid var(--color-accent-text);
  border-radius: var(--radius-control);
  min-height: 44px;
  padding: 10px 16px;
  font: 600 14px/1.5 var(--font-body);
}
.primary-action:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 4px;
}
```

## Identidade e cores

Preserve a grafia `rnqs.app`. O fundo azul quase preto e a Bricolage 800 vêm da identidade existente. O amarelo manteiga é uma proposta de evolução do dourado original, sem alterar a página inicial.

- `--color-bg`: fundo da página.
- `--color-surface`: painéis e formulários.
- `--color-elevated`: fundo de hover ou segunda camada.
- `--color-text` e `--color-muted`: texto principal e secundário.
- `--color-accent`: preenchimento amarelo. Use `--color-on-accent` para seu texto, em ambos os temas.
- `--color-accent-text`: links e texto de destaque. No claro, é ocre escuro; no escuro, amarelo claro.
- `--color-accent-soft`: seleção discreta, combinada com `--color-accent-text`.
- `--color-border`: separadores decorativos. Para contornos que identificam campos, use `--color-control`.
- `--color-focus`: contorno de foco sobre fundo ou painel.
- `--color-success`, `--color-danger` e `--color-info`: estados acompanhados de rótulo ou ícone. O amarelo da marca não significa automaticamente aviso.

O amarelo claro não funciona como texto pequeno sobre branco. Preserve a cor no preenchimento do botão e use o tom escuro para links. Texto branco sobre amarelo também deve ser substituído pelo token escuro.

Os pares de texto principal, secundário, destaque e estados foram calculados contra bg e surface e superam 4,5:1. Contornos de campos superam 3:1. Isso verifica os pares sólidos, não certifica uma interface inteira. Reavalie cores sobre imagens, transparências e fundos novos.

## Tipografia

- Bricolage Grotesque 800: marca e títulos expressivos. Em telas de produto, reserve-a ao título principal ou a um momento de destaque.
- Geist 400: corpo, 16 px / 1,6. Geist 500–600: labels, navegação e botões, 14–16 px / 1,5.
- Títulos de produto: Geist 600, 22–32 px / 1,2. Títulos editoriais: Bricolage 800, 32–56 px / 1,1.
- Texto auxiliar: 12–14 px / 1,6. Mantenha a informação essencial em tamanho de leitura.
- Mono do sistema: código, valores e tokens. Evite usá-la em parágrafos.
- Limite parágrafos de leitura a aproximadamente 60–70 caracteres por linha.

As fontes são locais e têm licença OFL. Copie `bricolage-grotesque-800.ttf`, `geist-latin-variable.woff2`, `OFL.txt` e `geist-OFL.txt` ao reutilizá-las. O arquivo Geist incluído atende ao português e ao conjunto Latin básico; outros idiomas podem precisar de subconjuntos adicionais.

## Textura

O efeito é ordered dithering com matriz Bayer 4×4, derivado da luz pixelada da página inicial. A implementação de referência está em [design.js](./design.js), nas funções draw e drawAll.

- Em interfaces, limite a textura a um cabeçalho, canto de painel ou estado vazio. Comece em 12–20% de intensidade.
- Por padrão, a camada de textura ocupa toda a largura horizontal da seção. O padding e a largura máxima pertencem ao conteúdo, não à textura. Em uma seção de página, o fundo chega às bordas da viewport; em um painel, chega às bordas do próprio painel.
- Estruture a seção com um canvas absoluto cobrindo seu contêiner e um contêiner interno de conteúdo com padding e largura máxima. Recorte o efeito apenas no limite externo da seção, nunca no limite útil do texto.
- Ancore o centro da luz ao limite direito da área útil. A referência usa 97% da largura útil e 45% da altura da seção. Em monitores largos, o centro acompanha o conteúdo centralizado, enquanto a textura continua pelas margens externas e desaparece naturalmente.
- Calcule a posição e o tamanho do efeito em coordenadas da área útil, independentemente da largura do canvas. Reserve a área de texto e controles: a referência começa a revelar pixels a partir de 58% da largura útil.

```html
<section class="hero">
  <canvas class="pixel-field" data-anchor=".hero-content"
    data-strength="0.2" aria-hidden="true"></canvas>
  <div class="content hero-content">Conteúdo com padding e largura máxima</div>
</section>
```

O seletor `data-anchor` deve identificar o contêiner de conteúdo daquela seção. A referência de layout está em [design.css](./design.css), e o cálculo das coordenadas em [design.js](./design.js).

- Use pixels de aproximadamente 3 px, alinhados à tela e sem esticar a imagem.
- Deixe o canvas decorativo com `aria-hidden="true"` e `pointer-events:none`.
- Renderize ao redimensionar, trocar tema ou ajustar intensidade. A textura fica estática durante a leitura.
- Telas densas, tabelas, formulários e mensagens de erro podem usar apenas os fundos sólidos.

## Fade fora da área útil

Quando a seção é mais larga que o contêiner de largura máxima e surgem margens externas de centralização, elementos decorativos começam a perder opacidade imediatamente ao cruzar o limite útil do conteúdo. A distância de dissolução acompanha o tamanho do elemento, e não cresce indefinidamente com a viewport.

- Em telas pequenas, quando o contêiner ocupa toda a seção, mantenha a textura até a borda sem fade adicional. O padding interno, sozinho, não ativa o fade. Na página de referência, as margens externas surgem acima de 1536 px.
- Preserve a opacidade original dentro da área útil e mantenha o centro do efeito ancorado ao conteúdo.
- À direita, meça a distância desde o limite direito do conteúdo para fora. À esquerda, espelhe esse comportamento a partir do limite esquerdo.
- Nesta textura, a extensão máxima do fade é 24% da largura útil. Se a borda da seção estiver mais perto, use apenas essa margem disponível. Assim, o efeito termina na borda ou antes dela, sem levar peso visual para a periferia de monitores ultralargos.
- Use `alpha × (1 - t)²`, com `t` limitado entre 0 e 1 ao longo dessa extensão. A intensidade cai desde o início e chega a zero suavemente. Evite curvas que preservem um platô perceptível fora do conteúdo.
- Aplique essa regra à camada decorativa, preservando texto, controles e foco. Para outras ilustrações, ajuste a extensão à escala visual do elemento; nunca use apenas a distância até o fim da tela como referência.
- Recalcule a geometria ao redimensionar. Valide telas estreitas e ultralargas: a queda deve continuar visível logo depois do limite útil, mesmo quando houver uma grande margem vazia.

A função `overflowFade` de [design.js](./design.js) implementa os dois lados. O canvas continua cobrindo toda a seção; apenas a opacidade muda fora do conteúdo.

## Espaço, forma e interação

A escala de espaço parte de 4 px e cobre 4, 8, 12, 16, 24, 32, 48 e 64 px. Cantos de controles usam 8 px; painéis, 16 px. Comece com bordas finas, sem sombra. Use separadores e espaço para organizar documentação, sem envolver todo bloco em um card.

Controles têm altura mínima de 44 px. Preserve labels visíveis, foco de teclado e mensagens de erro associadas aos campos. Feedback pode usar 160 ms; com movimento reduzido, use 0 ms. Evite movimentos contínuos na textura.

## Escopo e evolução

Esta base tem tokens CSS, documentação e exemplos de padrões. Ainda não é uma biblioteca de componentes. Extraia um componente quando a mesma solução aparecer em pelo menos dois projetos e suas necessidades forem conhecidas.

Se houver necessidade de intercâmbio com Figma, ferramentas nativas ou múltiplas plataformas, adote o formato DTCG 2025.10 como fonte e gere o CSS. O CSS atual não é um arquivo DTCG. Evite manter manualmente dois catálogos de valores.

Os botões de salvar da página são demonstrações locais de feedback; não persistem dados e não representam integração com um serviço.

## Referências consultadas em 12/11/2026

- [Design.Systems](https://www.design.systems/): recomendação de comunidade para discutir decisões com profissionais. A recomendação é de adequação a este projeto, não um ranking de popularidade.
- [Design Tokens Community Group](https://www.designtokens.org/): referência de interoperabilidade; especificação estável 2025.10.
- [Radix Colors: papéis da escala](https://www.radix-ui.com/colors/docs/palette-composition/understanding-the-scale): inspiração para separar fundos, contornos e texto. Esta paleta é própria, não uma escala oficial do Radix.
- [WCAG: contraste mínimo](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html): critério de contraste para texto.
- [Geist](https://vercel.com/font): fonte complementar para leitura e interface.