Getting Started

Guia de instalação e uso. Leia primeiro a documentação para o contexto do projeto e os requisitos para saber exatamente o que já é suportado.

Estado atual

O pacote ainda não foi publicado no npm (ver DP-07 em Requisitos de software). Por enquanto, a única forma de usar o dsgovbr-bootstrapped é clonando este repositório e compilando localmente.

Usando a partir deste repositório

git clone --recurse-submodules https://github.com/abrasileirado/dsgovbr-bootstrapped.git
cd dsgovbr-bootstrapped
npm install
npm run build

O CSS pronto fica em dist/dsgovbr-bootstrapped.css (ou .min.css, minificado). Inclua no seu HTML:

<link rel="stylesheet" href="caminho/para/dsgovbr-bootstrapped.min.css">

Nenhum outro CSS do Bootstrap precisa ser carregado: a build é autônoma (DP-02 em Requisitos de software) — o arquivo já inclui o Bootstrap inteiro recompilado com os tokens do GOV.BR DS.

Pré-requisitos externos

  • Fonte “Rawline” (fallback: Raleway, sans-serif): não é incluída no pacote (DP-05). Sem ela o navegador usa o fallback. O GOV.BR DS a publica num CDN do SERPRO:

    <link rel="stylesheet" href="https://cdngovbr-ds.estaleiro.serpro.gov.br/design-system/fonts/rawline/css/rawline.css">
    

    A Rawline é SIL OFL 1.1 (conforme as próprias fontes). O CDN não envia CORS, então não aceita integrity; para usar SRI, hospede a fonte você mesmo — ver THIRD_PARTY_NOTICES.

  • Ícones Font Awesome 5: não incluídos. Só são necessários se você for replicar manualmente ícones do GOV.BR DS (nenhum componente do MVP atual exige ícones). Versão usada na documentação do GOV.BR DS:

    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/all.min.css">
    

O que já está suportado

Ver o catálogo de componentes para a lista completa, com exemplos de markup, variantes, tamanhos e estados — e exemplos de uso concreto para ver os componentes compostos numa tela real.

Modo claro/escuro (opcional)

O CSS já pinta o modo escuro pelo data-bs-theme="dark" do Bootstrap 5.3. Para o usuário alternar, carregue o JS opcional dist/dsgovbr-bootstrapped-modo.js (sem dependência) de forma síncrona no ``<head>``, depois do CSS, e marque o botão com data-dsgovbr-modo:

<link rel="stylesheet" href="dist/dsgovbr-bootstrapped.min.css">
<script src="dist/dsgovbr-bootstrapped-modo.js"></script>
...
<button class="btn btn-link btn-sm rounded-circle" type="button"
        data-dsgovbr-modo aria-pressed="false" aria-label="Modo escuro" title="Modo escuro">
  <i class="fas fa-adjust" aria-hidden="true"></i>
</button>
  • Sem escolha salva, segue o sistema (prefers-color-scheme), inclusive quando ele muda.

  • O clique alterna claro/escuro, grava a escolha no localStorage e mantém o aria-pressed (“true” no escuro). data-dsgovbr-modo="light" ou "dark" fixa um modo.

  • API: window.dsgovbrModo.atual(), .aplicar("light" | "dark") e .alternar(). Toda troca dispara dsgovbr:modo no <html> (event.detail.modo).

Exemplo no header do painel administrativo.

Paginação (opcional)

O <dsgovbr-paginacao>, no mesmo dist/dsgovbr-bootstrapped-componentes.js, monta a paginação (.pagination) com janela de páginas e reticências, seletor “Exibir”, texto “1-10 de 100 itens” e a variante compacta (rodapé de tabela). Só classes do Bootstrap:

<dsgovbr-paginacao total="100" por-pagina="10" pagina="1"
                   opcoes-por-pagina="10,25,50" informacao></dsgovbr-paginacao>
  • Com href="?pagina={pagina}" os controles viram links reais (renderização no servidor).

  • Toda troca dispara dsgovbr:pagina (event.detail: pagina, porPagina, total, totalPaginas e origem); pagina e por-pagina são atributos e propriedades mantidos em dia.

Todos os atributos em Paginação (catálogo).

Tabela (opcional)

O <dsgovbr-tabela>, no mesmo dist/dsgovbr-bootstrapped-componentes.js, junta as partes do Table do GOV.BR DS ao redor do seu <table>: busca, filtros, menu de ferramentas (densidade), barra de itens selecionados com ações em lote e paginação (<dsgovbr-paginacao compacta>). Só classes e plugins do Bootstrap (exige o bootstrap.bundle):

<dsgovbr-tabela titulo="Usuários" busca ferramentas selecionavel acao="/usuarios/"
                total="42" por-pagina="10" opcoes-por-pagina="10,25,50">
  <table> … <tr data-valor="7"> … </table>
  <dsgovbr-filtro nome="ativo" rotulo="Ativo">
    <dsgovbr-opcao valor="1">Sim</dsgovbr-opcao>
  </dsgovbr-filtro>
  <dsgovbr-lote-acao acao="excluir" icone="fas fa-trash">Excluir</dsgovbr-lote-acao>
</dsgovbr-tabela>
  • Busca e filtros ficam num <form method="get">: com acao o envio é nativo (servidor); sem ela, só os eventos dsgovbr:tabela-busca e dsgovbr:tabela-filtro.

  • Ação em lote nativa: lote-metodo="post" envia a ação, os selecionados e os <dsgovbr-campo-oculto nome valor> (ex.: CSRF) para lote-acao-url (padrão: a página atual); o evento dsgovbr:tabela-acao é cancelável.

  • Seleção: checkbox por linha (name="selecionados", valor de data-valor); dsgovbr:tabela-selecao e dsgovbr:tabela-acao (detail.valores).

Todos os atributos e eventos em Tabela (catálogo); exemplo de listagem no painel administrativo.

Campo de formulário (opcional)

O <dsgovbr-campo>, no mesmo dist/dsgovbr-bootstrapped-componentes.js, gera rótulo + controle nativo + ajuda + feedback, com for/id/aria-describedby/aria-invalid ligados sozinhos, só com classes do Bootstrap. O <input>, <select> ou <textarea> é real e fica dentro do <form>: o valor é enviado normalmente e a validação nativa funciona.

<form method="post">
  <dsgovbr-campo tipo="email" nome="email" rotulo="E-mail" obrigatorio
                 ajuda="Usamos só para avisos."></dsgovbr-campo>
  <dsgovbr-campo tipo="select" nome="uf" rotulo="Estado" valor="RN">
    <dsgovbr-opcao valor="RN">Rio Grande do Norte</dsgovbr-opcao>
    <dsgovbr-opcao valor="PB">Paraíba</dsgovbr-opcao>
  </dsgovbr-campo>
</form>
  • Tipos: texto e variações de type, textarea, select, checkbox, switch e radio.

  • erro/sucesso (atributos ou <dsgovbr-erro>/<dsgovbr-sucesso>) marcam o campo; um atributo vazio limpa. Mudar um atributo remonta sem perder o digitado nem o foco.

  • Propriedades controle e valor e o método validar().

Detalhes em Formulários (catálogo).

Consentimento de cookies (opcional)

O JS opcional dist/dsgovbr-bootstrapped-cookies.js (sem dependência) traz o <dsgovbr-cookiebar> (barra de consentimento, configurações por grupo num modal e botão flutuante que as reabre) e a API window.dsgovbrCookies. Carregue de forma síncrona no ``<head>``, para a API estar pronta cedo, e mantenha o bootstrap.bundle (abre o modal):

<script src="dist/dsgovbr-bootstrapped-cookies.js"></script>
...
<dsgovbr-cookiebar declaracao="/cookies">
  <dsgovbr-cookies-texto>Usamos cookies para melhorar sua experiência. Veja a nossa</dsgovbr-cookies-texto>
  <dsgovbr-cookies-grupo nome="desempenho" rotulo="Desempenho">Medem o uso do site.</dsgovbr-cookies-grupo>
  <dsgovbr-cookies-grupo nome="funcionais" rotulo="Funcionais">Lembram suas preferências.</dsgovbr-cookies-grupo>
</dsgovbr-cookiebar>
  • O grupo “estritamente necessários” é criado sozinho (sempre ativo e bloqueado). A barra só aparece sem escolha salva (localStorage); depois dela fica só o botão flutuante (sem-botao o desliga). Qualquer elemento com data-dsgovbr-cookies-abrir abre as configurações; <dsgovbr-header cookies> já traz um botão de ação rápida assim.

  • API: dsgovbrCookies.escolha(), .permitido("grupo"), .definir({grupo: true}), .limpar() e .abrir(). Toda mudança dispara dsgovbr:cookies no <html> (event.detail.grupos e event.detail.origem).

Detalhes em Cookiebar (catálogo); exemplo no painel administrativo.

Quando o pacote for publicado no npm (planejado)

npm install @abrasileirado/dsgovbr-bootstrapped
<link rel="stylesheet" href="node_modules/@abrasileirado/dsgovbr-bootstrapped/dist/dsgovbr-bootstrapped.min.css">

Compilando a partir do SCSS

O pacote inclui o SCSS do projeto e o do Bootstrap (vendor/bootstrap/scss), então dá para compilar no seu projeto e sobrescrever os tokens do GOV.BR DS. Defina as variáveis antes de importar a entrada (todas são !default):

// seu-estilo.scss
$primary: #0b5cad; // sobrescreve o azul do GOV.BR DS
@import "@abrasileirado/dsgovbr-bootstrapped/src/scss/index";

Compile com Dart Sass apontando o node_modules como load path (sass --load-path=node_modules seu-estilo.scss saida.css) ou use o resolvedor do seu bundler. O pacote usa @import (o Bootstrap 5.3 ainda não usa @use/@forward), então o Dart Sass emite avisos de depreciação import/color-functions vindos do próprio Bootstrap; --quiet os silencia.