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
localStoragee mantém oaria-pressed(“true” no escuro).data-dsgovbr-modo="light"ou"dark"fixa um modo.API:
window.dsgovbrModo.atual(),.aplicar("light" | "dark")e.alternar(). Toda troca disparadsgovbr:modono<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,totalPaginaseorigem);paginaepor-paginasã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">: comacaoo envio é nativo (servidor); sem ela, só os eventosdsgovbr:tabela-buscaedsgovbr: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) paralote-acao-url(padrão: a página atual); o eventodsgovbr:tabela-acaoé cancelável.Seleção: checkbox por linha (
name="selecionados", valor dedata-valor);dsgovbr:tabela-selecaoedsgovbr: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,switcheradio.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
controleevalore o métodovalidar().
Detalhes em Formulários (catálogo).
Modal (opcional)¶
O <dsgovbr-modal>, no mesmo dist/dsgovbr-bootstrapped-componentes.js, monta o markup do
modal só com classes do Bootstrap e reusa o plugin Modal (exige o bootstrap.bundle). O
próprio elemento é o .modal; o conteúdo livre vira o corpo e <dsgovbr-acoes> o rodapé:
<button data-dsgovbr-modal-abrir="#confirmar">Abrir</button>
<dsgovbr-modal id="confirmar" titulo="Confirmar envio" centralizado>
Depois de enviada, a solicitação não poderá ser alterada.
<dsgovbr-acoes>
<button class="btn btn-outline-primary" data-bs-dismiss="modal">Cancelar</button>
<button class="btn btn-primary" data-bs-dismiss="modal">Enviar</button>
</dsgovbr-acoes>
</dsgovbr-modal>
Atributos:
titulo,tamanho(sm,lg,xl,tela-cheia),rolagem,centralizadoeestatico(sem Escape nem clique fora).API:
abrir(),fechar(),alternar()eaberto; eventodsgovbr:modal(event.detail.aberto);data-bs-toggle="modal"também funciona.
Detalhes em Modal (catálogo).
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.