Documentação de componentes

BetaNotice

Aviso discreto (faixa fina no topo, não fixa) informando que o site está numa versão beta do novo layout. O link “Saiba mais” abre um diálogo explicando o que muda, o que não muda e como enviar feedback.

• Pode ser dispensado; a escolha fica em localStorage (dougdesign-beta-notice-v1) e é aplicada antes da primeira pintura para não piscar.
• Para encerrar o beta, remova <BetaNotice /> de src/layouts/Layout.astro e o selo “Layout v2 · Beta” de Footer.astro.

ConsentBanner

O componente ConsentBanner gerencia as preferências de cookies e scripts do site. A adequação à LGPD depende também da configuração dos fornecedores e da revisão da política de privacidade.

Interface do Componente (Props & Slots)

Este componente não aceita propriedades externas (Props). Ele gerencia seu estado internamente utilizando localStorage.

Comportamento Interativo

• Chaves de Armazenamento:
  • dougdesign-consent-v1: Armazena se os cookies gerais de personalização foram aceitos (accepted) ou recusados (rejected).
  • dougdesign-comments-consent-v1: Armazena a escolha de comentários (comments-accepted ou comments-rejected).
• Eventos Disparados:
  • doug:consent-granted: Emitido no document global quando o usuário clica em “Aceitar tudo”.
  • doug:consent-denied: Emitido no document global quando o usuário clica em “Recusar tudo”.
• O botão “Preferências de cookies” no rodapé reabre o painel para revisão ou revogação da escolha.

O painel é compacto (canto inferior) e os controles de comentários (Giscus) ficam recolhidos em “Comentários (Giscus)”. Os IDs consent-accept, consent-reject, consent-comments-accept e consent-comments-reject são usados pelos testes E2E e pelo script do componente.

Exemplo de Uso

O banner deve ser incluído uma única vez no layout principal do site:

---
import ConsentBanner from '../components/ConsentBanner.astro';
---
<html>
  <body>
    <!-- Outros componentes -->
    <ConsentBanner />
  </body>
</html>

Design System (layout v2 · beta)

Fonte única de verdade: src/styles/global.css. Componentes usam tokens semânticos (não cores fixas), então claro/escuro funcionam sem dark: espalhado pelo HTML.

Princípios

1. Leitura primeiro. Superfícies calmas, texto em tom suave (nunca preto/branco puro) e medida de ~65 caracteres nos artigos.
2. Azul de marca só em elementos grandes ou de ação: mega menu, faixa “Explore por tema”, cabeçalho de categoria, newsletter, botão primário.
3. Sem animação contínua. Movimento só em resposta à interação e respeitando prefers-reduced-motion.
4. Desempenho como requisito: sem carrossel em JavaScript, imagens com proporção fixa, fontes com pré-carga só do essencial, content-visibility nas seções longas.

Tokens

Cada categoria tem um matiz próprio (data-cat="games" etc.) usado só no marcador de categoria.

Classes utilitárias do sistema

.wrap (container), .eyebrow, .h-display, .h-section, .meta, .cat, .btn (+ -primary, -ink, -outline, -white), .icon-btn, .chip, .field, .panel, .thumb, .snap-row, .badge-beta, .stretched, .hover-title, .prose.

Componentes

Header (com mega menu e busca), BetaNotice, Footer, Logo, PostCard, SectionHeading, PageHero, Pagination, CategoryBand, Picks, Hero, Feed, Sidebar, Newsletter, MuralJobs, JobCard, LivePixWidget, AdSense, ConsentBanner, GiscusComments, ReadingProgressBar.

Taxonomia

src/lib/nav.ts concentra as categorias exibidas (rótulos com acento, descrições, contagens e últimos posts). Novas categorias entram ali.

Header (mega menu e busca)

Cabeçalho fixo que recolhe ao rolar para baixo e reaparece ao rolar para cima. Inclui:

• Explorar — abre o mega menu, um painel azul de marca com todas as categorias, prévia das publicações recentes da categoria em foco (desktop) e atalhos. No celular o painel ocupa a tela toda, abaixo da barra superior.
• Busca instantânea — botão de lupa, Ctrl/⌘ + K ou /. O índice (/search-index.json) só é baixado na primeira abertura. Sem JavaScript, o botão leva a /posts/?search=focus.
• Tema — botão #theme-toggle alterna claro/escuro e guarda a escolha em localStorage (theme).

Acessibilidade

• aria-expanded e aria-controls nos botões do menu; Esc fecha e devolve o foco.
• Links do painel só recebem foco quando ele está aberto.
• A busca usa <dialog> modal, navegação por setas e Enter.

Dados

As categorias e os posts recentes vêm de getCategoryStats() (src/lib/nav.ts), calculado em build.

PostCard

O componente PostCard renderiza o resumo de uma publicação em quatro formatos. O título é o único link do cartão e usa um pseudo-elemento para tornar a área inteira clicável (melhor para leitores de tela e SEO do que um link vazio sobreposto).

Interface do Componente (Props)

Variantes

• lead — manchete principal da home: imagem grande, título em destaque, resumo e autor.
• card — vertical (imagem, categoria, título, resumo, data). Usado em grades de categoria, arquivo, autor e relacionados.
• row — linha do feed: texto à esquerda e miniatura à direita (no celular, miniatura quadrada e resumo oculto).
• compact — título curto com miniatura pequena, para listas laterais.

Exemplo de Uso

---
import { getPublishedPosts } from '../lib/blog';
import PostCard from '../components/PostCard.astro';

const posts = await getPublishedPosts();
---
<div class="grid grid-cols-1 gap-8 md:grid-cols-3">
  {posts.slice(0, 3).map((post) => <PostCard post={post} variant="card" />)}
</div>