O que Padrões de Interface Astro & Biblioteca de Componentes Portáteis faz?
Este guia define o catálogo padronizado de componentes de interface portáteis e prontos para uso para sites Astro.
Os exemplos independentes usam o Modelo de Componente Portátil: zero dependências externas de npm, zero runtimes de frameworks cliente (sem React/Vue), tokens CSS com namespace e fallbacks embutidos, e aprimoramento progressivo. Em projetos com framework, mantenha os requisitos semânticos e de interação enquanto adapta a composição e o estilo ao contrato selecionado. Verifique a acessibilidade no projeto renderizado; um modelo sozinho não estabelece conformidade com as WCAG.
Contratos comportamentais e composição do framework
Para um componente listado no índice abaixo, use seu contrato semântico e de interação: suporte a teclado, gerenciamento de foco, elementos nativos, nomes acessíveis, atualizações de estado e aprimoramento progressivo. O contrato do projeto/framework selecionado governa a estilização, tokens, importações e composição do componente. As instruções do usuário permanecem autoritativas.
Os exemplos usam o modelo de componente portátil independente abaixo. Use-o ao adicionar um componente independente sem um contrato de composição de framework. Quando um projeto tem uma biblioteca estabelecida, adapte o comportamento usando suas primitivas apropriadas em vez de duplicar seus botões, cabeçalhos ou controles de formulário. Preserve a semântica e o comportamento necessários enquanto adapta os wrappers e classes do exemplo.
Para um projeto construído sobre um framework de componentes (Lumos, por exemplo), use a composição e estilização desse framework; suas primitivas podem ser importadas. A regra independente de zero importações do site e os tokens de fallback com namespace não substituem o contrato do framework selecionado.
O Modelo de Componente Portátil
Para componentes portáteis independentes, use estas cinco regras. Em um framework selecionado, preserve os requisitos comportamentais e siga seu contrato de composição/estilização conforme descrito acima:
- Zero Importações Externas/do Site: O arquivo do componente NÃO deve importar layouts, botões ou bibliotecas de interface de terceiros do site. A única exceção catalogada é SelfHostedMap, que precisa de um renderizador de mapa e leitor de tiles; sua especificação lista os pacotes, e eles são instalados apenas com a aprovação do proprietário.
- Variáveis CSS com Namespace e Fallback: Nunca faça referência direta a tokens do host (ex:
var(--color-brand)) dentro da folha de estilo do componente. Sempre escrevavar(--comp-property, <fallback>). - BEM com Escopo e Propriedades CSS Lógicas: Use nomenclatura BEM (
.c-theme-toggle,.c-accordion__summary) e propriedades lógicas (inline-size,block-size,padding-inline,margin-block). - Aprimoramento Progressivo Vanilla Idempotente: Os scripts devem executar no carregamento e se religar corretamente se as Transições de Visualização do Astro estiverem ativas (
document.addEventListener('astro:after-swap', init)). - Alvos de Toque e ARIA: Botões e controles interativos devem ter alvos de toque mínimos de
44px(2.75rem) ou48px(3rem), estados ARIA adequados (aria-expanded,aria-selected,aria-pressed,aria-controls) e anéis de foco de teclado.
Índice de Componentes
| Componente | Arquivo de Especificação | Propósito | Contrato Principal |
|---|---|---|---|
| 1. ThemeToggle | components/theme-toggle.md | Alternador de tema Claro/Escuro sem FOUC e com morfismo SVG | Script inline no <head> + mapeamento de tokens OKLCH |
| 2. MobileNavDrawer | components/mobile-nav-drawer.md | Gaveta de navegação acessível com animação de hambúrguer | Alvos de toque de 48px, fechamento com tecla Esc, sem lag de desfoque GPU |
| 3. SearchBar | components/search-bar.md | Campo de busca no lado do cliente com botão limpar e anunciador ao vivo | Debounce com rAF (INP ideal), aria-live, coordenador de eventos personalizado |
| 4. FilterChips | components/filter-chips.md | Barra de filtros por chips de múltiplas categorias com estados pressionados acessíveis | role="group", aria-pressed, coordenador de eventos personalizado |
| 5. SearchFilterBar | components/search-filter-bar.md | Padrão composto combinando SearchBar e FilterChips | Barra de ferramentas empilhada pré-composta, layouts flex de múltiplas colunas, escopo compartilhado |
| 6. AccessibleModal | components/accessible-modal.md | Sobreposição de diálogo acessível usando <dialog> nativo do HTML5 | Camada superior nativa, clique no fundo, tecla Esc, restauração de foco |
| 7. AccessibleAccordion | components/accessible-accordion.md | Acordeão/FAQ nativo com expansão suave em grid CSS | <details name="..."> nativo, 0 KB de JavaScript |
| 8. AccessibleTabs | components/accessible-tabs.md | Alternador de abas WAI-ARIA para níveis de preço ou visões de múltiplos painéis | Navegação por setas do teclado (Esquerda/Direita/Home/End) |
| 9. SocialShare | components/social-share.md | Barra de compartilhamento social com foco em privacidade usando Web Share API | 100% seguro para GDPR, 0 rastreadores, URLs de intenção estáticas |
| 10. TableOfContents | components/table-of-contents.md | Sumário para artigos longos com scrollspy | Rastreamento de cabeçalhos com IntersectionObserver, emparelhado com layout de artigo |
| 11. AccessibleCarousel | components/accessible-carousel.md | Carrossel com scroll snap CSS nativo para avaliações, cartões ou logotipos | Deslize toque nativo (0 KB JS), botões Anterior/Próximo acessíveis |
| 12. InfiniteTicker | components/infinite-ticker.md | Marquee infinito de texto/logotipo em CSS puro com pausa ao passar o mouse/foco | Conforme WCAG 2.2.2, faixa duplicada oculta com aria-hidden |
| 13. StatsCounter | components/stats-counter.md | Barra de contadores de métricas com animação de rolagem com saída suave | 0 CLS, fallback HTML estático, IntersectionObserver |
| 14. AddToCalendar | components/add-to-calendar.md | Link "Salvar a data" para um arquivo iCalendar gerado em tempo de construção | .ics estático de mesma origem + <a download>, válido RFC 5545, 0 KB JS |
| 15. SelfHostedMap | components/self-hosted-map.md | Mapa dos locais de uma lista a partir de um extracto PMTiles auto-hospedado; pinos numerados correspondem à lista | MapLibre lazy, rota de tile HTTP 206, mapa com aria-hidden e equivalentes textuais, segue o tema. Requer pacotes npm (aprovação do proprietário) |
| 16. ClickableParent | components/clickable-parent.md | Cartão/linha inteiro clicável através de um único link ou botão real | Área de clique esticada com ::after, controles secundários elevados, anel de foco no contêiner, 0 KB JS |
| 17. Card | components/card.md | Cartão de conteúdo com mídia, metadados, corpo e ações secundárias | DOM com cabeçalho primeiro, prop headingLevel, layout baseado em consulta de contêiner, contrato ClickableParent quando vinculado |
Portão de Decisão para Componentes Não Catalogados (Ponto de Decisão Humano)
Quando um requisito ou design de projeto exigir um componente de interface interativo que não seja um dos 17 componentes catalogados acima (por exemplo: um slider de comparação Antes/Depois, seletor de data, seletor de intervalo, assistente passo a passo ou player de mídia personalizado):
[!IMPORTANT] PARE E PERGUNTE: O agente NUNCA deve instalar silenciosamente bibliotecas de framework cliente (React, Vue, Svelte), importar pacotes npm de terceiros não verificados ou deixar blocos temporários de texto placeholder (ex:
<div class="c-placeholder">).O agente DEVE pausar e apresentar ao proprietário do projeto três opções distintas:
- Opção A: Componente Vanilla Personalizado (Recomendado): Criar um componente
.astropersonalizado, sem dependências, em conformidade com o Contrato de Fallback para Componente Sob Medida abaixo.- Opção B: Linha de Base HTML Estática: Implementar um layout semântico puramente estático (ex: imagens lado a lado ou cartões empilhados padrão) com 0 KB de JavaScript, omitindo totalmente o aprimoramento interativo.
- Opção C: Adaptação de Padrão do Catálogo: Avaliar se um padrão existente do catálogo pode atender ao requisito (ex: adaptar
AccessibleModalpara uma lightbox de imagens, ouAccessibleTabspara uma visão de painéis em etapas).
O Contrato de Fallback para Componente Sob Medida
Quando o proprietário do projeto aprovar a construção de um componente não catalogado (Opção A), a implementação deve satisfazer estas seis regras; para adaptações de framework, use as regras de composição, nomenclatura de classes e tokens do framework para os itens 3–4:
- HTML Semântico Primeiro: Baseie a interface em elementos HTML padrão antes de escrever JavaScript (ex:
<input type="range">para sliders,<details>para divulgação,<dialog>para sobreposições). - Zero Dependências de Runtime Externas: Zero runtimes de framework cliente (sem React/Vue) e zero pacotes de widget de interface de terceiros. Escreva apenas TypeScript/JavaScript vanilla puro quando a interação do navegador for realmente necessária.
- BEM com Escopo e Propriedades CSS Lógicas: Use nomenclatura BEM padrão (
.c-block,.c-block__element) e propriedades de layout relativas ao fluxo (inline-size,block-size,padding-block,margin-inline,inset). - Tokens com Namespace e Fallback: Nunca codifique valores hexadecimais. Consuma tokens semânticos do host ou propriedades personalizadas com namespace com fallbacks sensatos (
var(--comp-color, var(--color-primary))). - Aprimoramento Progressivo Sem JavaScript: O componente deve permanecer legível, acessível e operável quando o JavaScript do cliente estiver desabilitado. Use
@media (scripting: none)ou layouts de fallback CSS nativos (ex: visões lado a lado ou empilhadas) para que nenhum conteúdo seja ocultado. - Conformidade WCAG 2.2 AA: Mantenha alvos de toque mínimos de
44px(2.75rem), anéis:focus-visiblevisíveis de alto contraste, nomes acessíveis claros (aria-label,<label>) e garanta 0 violações do axe-core.
Orientação de Carregamento Seletivo para Agentes
Quando o usuário solicitar a implementação ou edição de um dos componentes acima, não leia o catálogo inteiro. Em vez disso, leia apenas o arquivo do componente específico necessário (ex: components/accessible-carousel.md).
Verificação de Integração
Verifique a especificação selecionada na saída construída/implantada: semântica e nomes, comportamento de teclado/foco, transições de estado, tratamento sem JavaScript, inicialização repetida e mapeamento de tokens do host. As regras de empacotamento independente aplicam-se apenas a componentes independentes; frameworks reutilizam suas primitivas. Execute os comandos de verificação/build/testes configurados do projeto e divulgue verificações indisponíveis ou lacunas de cobertura. 44px é a convenção de tamanho de alvo desta biblioteca, não o limite da WCAG AA em si.
Popups de seleção nativos permanecem como interface do navegador/SO, a menos que o proprietário aprove as compensações de uma combobox personalizada.