Requisitos de software¶
Versão do documento: 0.2 (decisões atualizadas após inspeção do código-fonte upstream).
Estado: especificação; não descreve funcionalidades já implementadas.
Projeto: integração comunitária e não oficial da API de classes Bootstrap 5 com aspectos visuais do GOV.BR DS.
Repositório: https://github.com/abrasileirado/dsgovbr-bootstrapped.
1. Contexto e problema¶
Aplicações existentes com Bootstrap 5 usam classes, estrutura HTML e, por vezes, plugins JavaScript próprios. Migrá-las para o GOV.BR DS exige frequentemente alterar templates para classes e anatomias de componentes diferentes. Este projeto busca oferecer uma opção gradual: manter a API Bootstrap para componentes declarados como suportados, produzindo uma aparência baseada na referência GOV.BR DS.
A composição SCSS dos projetos é uma oportunidade de reaproveitamento, não uma garantia de equivalência. Regras que dependem de .br-*, filhos específicos, JavaScript próprio, fontes ou ícones exigirão mapeamento, adaptação ou exclusão documentada.
2. Objetivos¶
O-01 — Distribuir um pacote reutilizável para projetos Bootstrap 5, sem exigir troca generalizada de classes HTML.
O-02 — Reaproveitar tokens e, quando tecnicamente viável, fontes SCSS do GOV.BR DS de modo rastreável.
O-03 — Disponibilizar CSS compilado e fontes SCSS, respeitando contratos de instalação e entrada documentados.
O-04 — Definir níveis verificáveis de fidelidade, incluindo limitações de markup, comportamento e acessibilidade.
O-05 — Permitir evolução componente a componente sem afirmar certificação, homologação ou endosso oficial.
3. Não objetivos do MVP¶
Reproduzir todos os componentes ou padrões do GOV.BR DS.
Garantir equivalência pixel a pixel em todas as combinações de navegador e dispositivo.
Substituir o JavaScript do Bootstrap pelo JavaScript do GOV.BR DS.
Introduzir silenciosamente classes
.br-*como requisito de uso dos componentes anunciados como Bootstrap compatíveis.Implementar, no MVP, header institucional, navegação complexa, modal ou menu com comportamento próprio.
Publicar fontes, ícones, imagens ou outros ativos de terceiros sem revisão de origem, licença e necessidade.
Alegar conformidade institucional automática pelo simples uso do pacote.
4. Usuários e casos de uso¶
Perfil |
Necessidade |
|---|---|
Desenvolvedor de aplicação Bootstrap |
Aplicar um tema visual GOV.BR DS sem reescrever todos os templates. |
Equipe com pipeline Sass |
Importar fontes para configurar e compilar estilos da aplicação. |
Equipe sem pipeline Sass |
Consumir CSS previamente compilado com contrato de dependências documentado. |
Mantenedor |
Verificar componentes, versões, origem de tokens e regressões antes da publicação. |
5. Premissas e restrições¶
A compatibilidade é fixada em Bootstrap v5.3.8 e @govbr-ds/core v3.7.0, ambos incluídos como git submodules apontando para os repositórios oficiais upstream (não forks) e fixados por tag (ver DP-01/DP-03).
A versão ou revisão de GOV.BR DS usada como referência deve ser explicitamente fixada antes da implementação. Não se deve depender de
latestna geração de releases.O pacote npm
@abrasileirado/dsgovbr-bootstrappedjá está publicado (ver DP-07).A versão do pacote acompanha o GOV.BR DS de referência:
major.minoré a do@govbr-ds/core(hoje 3.7) e opatchconta as revisões do projeto. O npm exige semver de 3 partes, por isso não há quarta posição.O projeto distingue contrato visual, contrato de markup e contrato de comportamento. A aprovação em um contrato não implica aprovação nos outros.
Qualquer versão que contenha CSS pronto deverá informar se ele é autônomo (inclui Bootstrap) ou camada adicional (exige Bootstrap carregado separadamente), com ordem de carregamento e cobertura demonstradas.
Cores, medidas e nomes de tokens nos artefatos finais devem vir das fontes versionadas escolhidas; não são definidos por suposição neste documento.
6. Matriz de compatibilidade atual (v0.5.1)¶
Legenda de esforço: A = adaptação principalmente por tokens/SCSS; B = exige convenção de markup e validação por componente; C = adaptação estrutural e/ou comportamental relevante; D = fora do escopo atual. O status descreve o que foi implementado e verificado neste projeto; não implica equivalência integral com GOV.BR DS. Referências upstream consideradas: Bootstrap v5.3.8 e @govbr-ds/core v3.7.0.
Área |
API Bootstrap pretendida |
Referência GOV.BR DS |
Esforço |
Status atual |
Limite / condição para ampliar suporte |
|---|---|---|---|---|---|
Fundamentos |
Tokens e variáveis Bootstrap |
Fundamentos visuais / tokens |
A |
Limitado |
Mapeamento versionado, origem registrada e testes de compilação; não cobre todos os tokens do GOV.BR DS. |
Layout |
|
Grid e layout |
A |
Não suportado (Bootstrap sem adaptação) |
Preservam-se as classes Bootstrap, mas não se promete paridade visual: breakpoints GOV.BR DS (xs:0, sm:576, md:992, lg:1280, xl:1600) diferem dos Bootstrap (sm:576, md:768, lg:992, xl:1200, xxl:1400). |
Botões |
|
Button |
B |
Limitado |
Apenas variantes e estados documentados e testados; |
Texto e formulários |
|
Input |
B |
Limitado |
Estados, labels, ajuda e erro testados sem exigir |
Auxiliares |
|
Skiplink, Avatar, Sign-in, Divider, Cookiebar |
B |
Limitado |
Issue #47: composições com classes e utilitários Bootstrap;
|
Select e switch |
|
Select, Switch |
B |
Limitado |
Issue #46: select nativo com a superfície do Input e seta na cor
interativa (sem busca nem multisseleção do DS); switch no tamanho médio
do DS, rótulo à esquerda com |
Seleção |
|
Checkbox e Radio |
B |
Limitado |
Conjunto atual verificado para foco, marcação, desabilitado, teclado e alinhamento; sem equivalência geral de markup. |
Feedback |
|
Message |
B |
Limitado |
Severidades e ícones adaptados; fechamento requer o JavaScript Bootstrap e segue seu comportamento. |
Conteúdo |
|
Card |
B |
Limitado |
Apenas anatomia e variações demonstradas na documentação. |
Badge/tag |
|
Tag |
B/C |
Limitado |
Badge estático: fundo padrão, variantes |
Paginação |
|
Pagination |
B/C |
Limitado |
Estados ativo, desabilitado, foco e hover adaptados para paginação estática. Sem seletor de itens por página, dropdowns de reticências ou lógica de navegação do DS; variantes pequenas/grandes preservam os paddings Bootstrap. |
Modal |
|
Modal + Scrim |
C |
Limitado |
Issue #43: visual por tokens e CSS (sem raio nem borda, sombra, 500px,
título 16,8px negrito, rodapé sem divisor, fundo preto a 45% como o
Scrim), mantendo o plugin Bootstrap (análise #38). O backdrop não é o
componente Scrim. Não converter para |
Demais componentes |
Accordion, breadcrumb, close
button, carousel, list group,
navs & tabs, popovers,
progress, spinners, toasts,
tooltips, |
Accordion, Breadcrumb, Button circular, Carousel, List/Item, Tab, Tooltip, Loading, Message |
B |
Limitado |
Issue #43: tokens e CSS por componente e foco tracejado dourado global; as diferenças que restam estão em cada página do catálogo (issue #41). |
Sem equivalente |
Button group, collapse, placeholders, scrollspy |
— |
A |
Não suportado |
Têm página no catálogo; recebem os tokens globais e o foco tracejado dourado. |
Navegação |
|
Header, Menu e Footer |
C/D |
Limitado |
Issue #45: navbar com aparência do Header (sombra, título responsivo,
links interativos, acionador circular, modo escuro em
|
O suporte é por subconjunto e versão: planejado significa ainda sem adaptação; experimental, implementado sem cobertura suficiente; limitado, apenas variantes/estados enumerados e verificados; estável, critérios completos atendidos; não suportado, sem adaptação GOV.BR DS. Apenas componentes com critérios atendidos poderão ser anunciados como estáveis. Paginação cobre somente estados estáticos e não implementa interações específicas do GOV.BR DS. A análise de modal e navegação está em Análise de modal e navegação — issue #38; as possibilidades propostas ali não alteram o status da matriz.
7. Requisitos funcionais¶
ID |
Prioridade |
Requisito |
Critério de aceite |
|---|---|---|---|
RF-01 |
Obrigatório |
Gerar CSS a partir dos fontes SCSS com build documentado. |
Comando de build reproduzível gera CSS normal e minificado, sem erros, nas versões de dependências fixadas. |
RF-02 |
Obrigatório |
Manter mapa rastreável de tokens GOV.BR DS → variáveis/componentes Bootstrap. |
Cada token utilizado registra origem, propósito e destino; valores inexistentes são tratados como escolha local e identificados como tal. |
RF-03 |
Obrigatório |
Preservar as classes públicas Bootstrap para os componentes anunciados como suportados. |
Fixtures de teste usam
classes Bootstrap sem
classes |
RF-04 |
Obrigatório |
Disponibilizar adaptação de botões para variantes selecionadas. |
Página de teste demonstra tamanhos e estados definidos na matriz de variantes; diferenças conhecidas são documentadas. |
RF-05 |
Obrigatório |
Disponibilizar adaptação básica de campos de texto, checkbox e radio. |
Fixtures incluem label associado, ajuda, erro, foco, desabilitado e operação por teclado. |
RF-06 |
Obrigatório |
Disponibilizar adaptações básicas de alertas e cards. |
Cada variação suportada tem fixture, regra documentada de uso e teste visual. |
RF-07 |
Obrigatório |
Fornecer uma matriz pública de suporte. |
Matriz registra status, seletores Bootstrap aceitos, diferenças e versão de introdução por componente. |
RF-08 |
Obrigatório |
Publicar artefatos CSS e SCSS em pacote npm público. |
|
RF-09 |
Obrigatório |
Declarar a relação entre Bootstrap e CSS distribuído. |
README informa se Bootstrap precisa ser importado antes; teste de integração detecta ordem incorreta ou ausência da dependência. |
RF-10 |
Desejável |
Permitir entrada SCSS específica para customização ou consumo parcial. |
Pelo menos uma entrada documentada compila num projeto consumidor; parcialização é entregue apenas se comprovadamente estável. |
RF-11 |
Desejável |
Disponibilizar catálogo demonstrativo. |
Exemplos exibem markup, variante, estados e limitação por componente. |
RF-12 |
Desejável |
Publicar source map para CSS não minificado. |
Arquivo de mapa referencia os fontes distribuídos e não contém caminhos locais indevidos. |
8. Requisitos não funcionais¶
ID |
Prioridade |
Requisito |
Critério de aceite |
|---|---|---|---|
RNF-01 |
Obrigatório |
Compatibilidade de versões explícita. |
|
RNF-02 |
Obrigatório |
Acessibilidade básica verificável. |
Inspeção manual por teclado e testes automatizados aplicáveis cobrem foco, semântica e contraste dos componentes do MVP; problemas são registrados. |
RNF-03 |
Obrigatório |
Build determinístico. |
CI instala a partir de lockfile e recompila os artefatos sem diferenças inesperadas. |
RNF-04 |
Obrigatório |
Isolamento de seletores. |
Testes de regressão procuram conflitos relevantes com Bootstrap e estilos globais GOV.BR DS; não se importa indiscriminadamente o CSS completo de ambas as bibliotecas. |
RNF-05 |
Obrigatório |
Verificação de licenças e atribuições. |
Dependências e ativos redistribuídos têm licença verificada; avisos MIT aplicáveis são preservados. |
RNF-06 |
Obrigatório |
Segurança de publicação. |
CI testa o tarball antes de publicar; fluxo automatizado deve priorizar npm trusted publishing/OIDC e proveniência, sujeito à configuração do pacote. |
RNF-07 |
Obrigatório |
Versionamento e rastreabilidade. |
Toda release tem tag, changelog, matriz atualizada e referência às versões upstream. |
RNF-08 |
Obrigatório |
Comunicação de caráter não oficial. |
README, documentação e metadata não alegam endosso ou homologação. |
RNF-09 |
Desejável |
Cobertura visual automatizada. |
Fixtures do MVP têm capturas de referência em ao menos dois tamanhos de tela e testes de estados interativos relevantes. |
9. Contrato de distribuição¶
A proposta de publicação é um pacote npm contendo dist/ com CSS compilado e src/scss/ com SCSS importável. As superfícies exatas deverão ser congeladas antes da versão 1.0:
Arquivos CSS normal e minificado em caminhos documentados; consumidor sem Sass deve conseguir usar o CSS em uma aplicação de teste.
Uma entrada SCSS documentada; consumidor com Sass deve conseguir compilar no próprio projeto.
Campos
files,exportse, se necessários,style/sassnopackage.json, testados nos ambientes de consumo que o projeto decidir suportar.Declaração da dependência Bootstrap coerente com a estratégia escolhida para o CSS pronto. Se houver um build autônomo e outro de camada adicional, nomes e instruções devem distingui-los sem ambiguidade.
Dependências de compilação e fontes GOV.BR DS não podem depender implicitamente de arquivos que não constem do pacote ou das dependências declaradas.
GitHub Releases e, opcionalmente, documentação online complementam o npm; não substituem o registro primário.
A criação de uma nova Release no GitHub aciona a pipeline de publicação (CI/CD): (1) publica o pacote no npm, preferencialmente via trusted publishing/OIDC (RNF-06); (2) publica o site de documentação/catálogo via GitHub Pages, a partir da pasta docs/ deste mesmo repositório (já habilitado); (3) anexa os artefatos compilados de dist/ (CSS, minificado, source maps) como assets da própria Release.
Um trecho de instalação só poderá ser publicado como instrução oficial após o primeiro tarball ser validado num projeto consumidor limpo.
10. Estratégia de implementação¶
Inspecionar as versões upstream selecionadas: árvore SCSS, tokens, dependências, JavaScript e licenças.
Produzir uma prova de conceito para tokens e
.btn, confrontando estados e estrutura com as referências.Decidir entre reaproveitar mixins upstream ou implementar adaptadores próprios por componente, registrando o custo de manutenção.
Adicionar formulários, alertas e cards, sempre acompanhados de fixtures e matriz de suporte.
Fechar contrato CSS/SCSS do pacote com testes de instalação local.
Publicar versão pré-1.0 com limites claros; só ampliar suporte após regressão visual, de acessibilidade e de comportamento.
Preferir código novo em @use/@forward quando possível. Se uma dependência exigir @import, isolar o uso, registrar avisos de depreciação e planejar migração; não presumir que é possível converter fontes de terceiros sem impacto.
Nota: o passo 1 (inspeção das versões upstream) foi concluído; os achados e decisões resultantes estão registrados em §12.1.
11. Critérios de aceite do MVP¶
☐ Revisões exatas de Bootstrap e GOV.BR DS selecionadas e registradas.
☐ Tokens e fontes incorporados têm origem e licença verificadas.
☐
npm run buildenpm testou equivalentes estão documentados e passam no CI.☐ Botão, input, checkbox/radio, alerta e card têm demonstrações para os subconjuntos efetivamente suportados.
☐ Fixtures não exigem classes
.br-*ocultas nos componentes declarados como Bootstrap compatíveis.☐ Os estados de foco, desabilitado e erro aplicáveis foram avaliados com teclado e testes automatizados pertinentes.
☐ Um projeto consumidor limpo instala o tarball e usa CSS pré-compilado.
☐ Um projeto consumidor limpo instala o tarball e compila a entrada SCSS documentada.
☐ A matriz de compatibilidade informa diferenças, restrições e itens ainda não suportados.
☐ O pacote inclui licença, avisos de terceiros quando necessários, README, changelog e versão correta.
☐
npm pack --dry-rune validação do conteúdo publicado passam antes da release.
12. Decisões pendentes¶
12.1 Decisões já registradas¶
Resultado da inspeção direta do código-fonte upstream (Bootstrap 5.3.8 e @govbr-ds/core 3.7.0) e
de decisões tomadas com o mantenedor após essa inspeção.
ID |
Decisão |
Registro |
|---|---|---|
DP-01 |
Referência GOV.BR DS |
Fixado |
DP-02 |
Formato de CSS pronto |
Build autônoma: o Bootstrap é recompilado por
completo a partir do submódulo oficial, com variáveis
Sass ( |
DP-03 |
Política de dependências |
Bootstrap ( |
DP-04 |
Contrato de Sass |
Empacotar o SCSS junto com o Bootstrap (issue
#20). O pacote inclui |
DP-05 |
Fonte e ícones |
A fonte “Rawline” e os ícones Font Awesome 5 continuam
externos, via CDN, documentados como pré-requisito
de instalação — mesma abordagem que o próprio GOV.BR
DS já adota hoje (confirmado por inspeção: nenhum dos
dois é embutido no pacote |
DP-06 |
Variantes Bootstrap |
Classificação por papel, não por nome, porque
|
DP-07 |
Nome do pacote |
Escopo |
DP-08 |
Política de licenciamento |
Bootstrap e |
DP-09 |
Versões e suporte |
Navegadores: segue a política do Bootstrap 5 (sem
Internet Explorer), mesmo o GOV.BR DS declarando hoje
suporte a IE 9–11 em seu |
DP-10 (novo) |
Tamanho de fonte base |
O |
12.2 Decisões ainda pendentes¶
Nenhuma no momento. Novas decisões entram aqui como DP-xx e migram para 12.1 quando fechadas.
13. Riscos iniciais¶
Risco |
Impacto |
Mitigação |
|---|---|---|
Dependência de
seletores e markup
|
Adaptação não viável por mera composição Sass |
Prova de conceito pequena; usar adaptador próprio ou declarar componente não suportado. |
Colisão de reset, utilitários e estilos globais |
Regressões visuais fora dos componentes alvo |
Importação seletiva; isolamento; testes em aplicação Bootstrap existente. |
Divergência de comportamentos JavaScript |
Interface visualmente correta, mas interação incorreta |
Preservar o motor Bootstrap no MVP e testar suas interações separadamente. |
Atualizações upstream quebrarem tokens/imports |
Build ou aparência instáveis |
Fixar versões, rodar CI de compatibilidade e versionar alterações. |
Publicar CSS com expectativa errada de dependência Bootstrap |
Estilos incompletos ou duplicados no consumidor |
Nomear builds claramente, documentar ordem e testar as duas formas de consumo. |
Distribuição inadvertida de fontes/ícones sem revisão |
Risco jurídico e aumento do pacote |
Inventário de
terceiros, |
14. Referências¶
Sass — depreciação de ``@import` <https://sass-lang.com/documentation/at-rules/import/>`__.