Desenvolvimento¶
Guia de trabalho inicial. O projeto está em especificação; caminhos, scripts e comandos marcados como propostos deverão ser ajustados e testados quando a implementação existir.
Objetivo técnico¶
Produzir uma integração SCSS/CSS que mantenha classes Bootstrap 5 nos componentes suportados e adote aspectos visuais rastreáveis do GOV.BR DS. A iniciativa é comunitária e não oficial; estilos e comportamento precisam ser verificados separadamente.
Leia primeiro os requisitos, sobretudo a matriz inicial, os critérios de aceite e as decisões pendentes.
Roteiro do MVP¶
O MVP foi quebrado nas issues abaixo, cada uma associada a um marco concreto. A ordem reflete as dependências entre elas (uma issue geralmente depende da anterior estar concluída):
Issue |
Marco |
Estimativa |
|---|---|---|
Estrutura inicial: submodules (Bootstrap + govbr-ds-core) e scaffold do projeto |
6h |
|
Prova de conceito: tokens
de fundação + adaptação de
|
8h |
|
Adaptação: campos de texto, checkbox e radio |
8h |
|
Adaptação: alert e card |
6h |
|
Matriz pública de suporte + página de showcase dos componentes |
10h |
|
Exemplo(s) de uso concreto |
6h |
|
Documentação: Getting Started e Setup |
4h |
|
README.md com screenshots |
3h |
|
Pipeline de CI/CD de release |
6h |
Cada issue detalha objetivo, escopo, critério de aceite e dependências no próprio GitHub. A página
de showcase (#6) é estática (HTML/CSS, sem framework), publicada em docs/showcase/ via o GitHub
Pages já habilitado neste repositório.
Organização proposta¶
src/scss/
index.scss # Entrada pública quando estabilizada
_tokens.scss # Mapeamento documentado de tokens
_bootstrap-settings.scss # Ajustes de variáveis Bootstrap
components/ # Adaptadores específicos, um por componente
src/js/ # JS opcional (modo claro/escuro e web components), copiado para dist/
dist/ # Artefatos gerados para publicação
vendor/ # Submodules (Bootstrap, govbr-ds-core), fixados por tag
docs/
componentes/ # Fixture de teste + catálogo demonstrativo, por componente
*.rst # Documentação (Sphinx) e decisões
package.json
package-lock.json # Ou lockfile do gerenciador escolhido
Essa árvore é uma proposta de arquitetura, não uma descrição dos arquivos já existentes. Não crie/importações rígidas para fontes upstream antes de verificar a estrutura da versão selecionada.
Cada página em docs/componentes/ cumpre dupla função: é a fixture usada para
validar a adaptação de um componente (variantes, tamanhos, estados, diferenças
conhecidas) e, ao mesmo tempo, o catálogo demonstrativo (RF-11) publicado via
GitHub Pages — não há uma pasta tests/fixtures/ separada.
docs/componentes/*.html é gerado por npm run build (script
build:site, issue #15) a partir de um template único em
src/site/layout.html e de fragmentos de conteúdo em
src/site/componentes/*.html — não edite os arquivos em docs/componentes/
diretamente, suas alterações seriam sobrescritas no próximo build (por isso
estão no .gitignore). Isso existe porque as 5 páginas chegaram a duplicar o
mesmo cabeçalho/navegação, e um caminho de CSS errado precisou ser corrigido
em cada uma separadamente — ver histórico das issues #6 e #15.
Criando uma nova página de componente¶
Crie
src/site/componentes/<nome>.htmlcomeçando por este cabeçalho de comentários, um por linha:<!-- title: Componente: <Nome> — dsgovbr-bootstrapped --> <!-- status: Não suportado --> <!-- bootstrap: <slug> -->
title(obrigatório) vira o<title>da página.statusé o status na matriz (Planejado,Experimental,Limitado,EstávelouNão suportado).bootstrapé o nome da página do componente em https://getbootstrap.com/docs/5.3/components/ (ex.:list-group). Os dois geram a faixa de status no topo da página. Depois do cabeçalho vem o conteúdo do<main>— sem repetir a navegação, a chave de tema nem o<link>do CSS, que já vêm do template. Uma seção “Diferenças conhecidas em relação à referência GOV.BR DS” é obrigatória (tests/site.test.jsconfere).Rode
npm run build(ou sónpm run build:sitese o CSS já estiver atualizado) — geradocs/componentes/<nome>.html.Se for um componente novo (não apenas uma página adicional), adicione uma linha na tabela de
src/site/componentes/index.htmlapontando para ele, com o status e o número da issue.Para adaptar um componente: prefira as variáveis Sass do Bootstrap em
src/scss/_bootstrap-settings.scss(com tokens$govbr-*de_tokens.scss, cada um com origem emtests/tokens.test.js) e só então CSS emsrc/scss/components/_<componente>.scss. Hover e foco do GOV.BR DS estão emsrc/scss/_mixins.scss(govbr-hover,govbr-focus); o foco tracejado dourado de todo elemento focável fica emcomponents/_focus.scss.Ao adaptar um componente antes “Não suportado”, atualize o
statusno cabeçalho, a linha do índice e a matriz em Requisitos.Abra a página gerada localmente (ver “Visualizar as páginas de componentes localmente” em Setup) para conferir antes de commitar.
Sequência recomendada¶
Registrar revisão e licença das fontes Bootstrap e GOV.BR DS; inventariar tokens, dependências, mixins e seletores.
Criar uma fixture Bootstrap pura para botões, incluindo estados aplicáveis; documentar diferenças em relação à referência GOV.BR DS.
Compilar um protótipo de tokens + botão sem importar indiscriminadamente o CSS integral dos dois projetos.
Decidir se CSS pré-compilado será autônomo ou exigirá Bootstrap separado; criar teste de integração compatível com a decisão.
Implementar componentes restantes do MVP com testes correspondentes.
Validar instalação de um tarball local antes de publicar.
Comandos e testes¶
npm ci
npm run build # CSS (dist/), cópia para docs/assets/ e páginas de docs/componentes/
npm test # test:unit + test:package
npm pack --dry-run
npm test roda duas camadas (exige npm run build antes e os submodules
inicializados):
npm run test:unit—node:test, sem dependências, emtests/:tokens.test.js: deriva de tokens (RF-02). Cada valor desrc/scss/_tokens.scssé conferido contra o arquivo de origem emvendor/govbr-ds-core; todo$govbr-*precisa ter origem registrada no teste. Para um token novo, acrescente a origem emORIGEM.css.test.js: asserções no CSS compilado — tokens no:root, botão, campo de texto, checkbox/radio, alerta e card, nenhuma classe.br-*(RF-03) ebtn-secondaryno cinza do Bootstrap (DP-06). Ao adaptar um componente novo, acrescente aqui o que o torna “GOV.BR DS”.componentes-js.test.js: o JS dos web components tem sintaxe válida, define os quatro elementos sem Shadow DOM neminnerHTMLe entra embuild-js,build-docs-assets, no teste do pacote e na release.paginacao-js.test.js: a funçãodsgovbrPaginacao.janela(janela de páginas) rodando num contexto isolado (vm), sem DOM.cookies-js.test.js: a API dedsgovbrCookiesrodando num contexto isolado (vm) comlocalStoragede mentira (gravar, normalizar, evento, JSON inválido, armazenamento bloqueado) e o empacotamento do arquivo.site.test.js: o catálogo cobre todo componente devendor/bootstrap/site/src/content/docs/components/(uma página por<!-- bootstrap: <slug> -->), o índice aponta para todas as páginas e cada página declara status e diferenças conhecidas. Um componente novo numa versão futura do Bootstrap faz este teste falhar até ganhar página.
npm run test:package— consumidor limpo:npm pack, instala o tarball num projeto temporário e compila a entrada SCSS com e sem override (DP-04).
Documentação (Sphinx)¶
As páginas de texto (docs/*.rst) são geradas com o Sphinx e o tema
dsgovbr-sphinx-theme.
O catálogo (docs/componentes/), os exemplos e docs/assets/ continuam como
HTML estático e são copiados sem alteração para a saída (ver docs/conf.py).
Rode npm run build antes, para gerar esses arquivos:
python -m venv .venv
.venv/bin/pip install -r docs/requirements.txt # Windows: .venv\Scripts\pip
npm run build
npm run docs # sphinx-build -W -> docs/_build/html
Avisos do Sphinx viram erro (-W), como no workflow pages.yml. As páginas
reST podem usar as diretivas br-* do tema (ex.: .. br-alerta:: warning),
que aplicam o CSS deste repositório recém-compilado (dist/).
Análise estática (Semgrep)¶
.github/workflows/semgrep.yml roda semgrep scan --config auto (container
oficial, regras públicas, sem conta no semgrep.dev) em push, PR e toda segunda,
e envia o SARIF ao code scanning. Os achados são informativos. Para reproduzir
local:
docker run --rm -v "$PWD:/src" -w /src semgrep/semgrep semgrep scan --config auto --exclude vendor --exclude node_modules --exclude dist --exclude docs/assets --exclude-rule yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag
Política (issue #28): o objetivo é zero achados ativos.
Actions por major, não por SHA. A regra
github-actions-mutable-action-tagfica excluída de propósito: fixamos actions oficiais do GitHub pela major (@v7) e deixamos o Dependabot (grupogithub-actions) mantê-las. Fixar por SHA é mais forte contra a troca de uma tag, mas custa legibilidade e PRs de atualização; se a política mudar, remova a exclusão e fixe os SHAs.Dependabot com ``cooldown`` de 7 dias (
npmegithub-actions): não propõe versão recém-publicada. Alertas de segurança ignoram o cooldown.Supressão só com motivo.
// nosemgrep: <regra>precisa de um comentário na linha de cima explicando por que o achado é falso positivo (ex.: o caminho já é validado por guarda). Os casos atuais:scripts/serve.js(servidor só em127.0.0.1, sem TLS) escripts/test-package.js(nome do tarball vindo do nossonpm pack). O servidor não usa guarda de caminho: a URL nunca vira caminho de arquivo, só é buscada num índice dos arquivos existentes sobdocs/(tests/serve.test.jstenta../,%2e%2e,%5cetc.). Isso fechou os alertasjs/path-injectiondo CodeQL, que não reconheciam o guarda comstartsWith.Scripts do projeto usam
execFileSynccom argumentos, nuncaexecSynccom string (que passa por shell).
Antes da primeira publicação de um formato novo (ex.: outro entry point), testar o .tgz gerado por npm pack num projeto consumidor limpo; test:package já cobre o caminho atual (CSS pronto e SCSS).
Verificações por componente¶
Uma contribuição de componente deve conter, no mínimo:
Seletores Bootstrap aceitos e markup de fixture.
Referência GOV.BR DS e revisão utilizada.
Mapeamento semântico das variantes e diferenças deliberadas.
Estados normal,
hover,focus-visible, ativo, desabilitado e erro quando aplicáveis.Testes de teclado, associação de labels e contraste relevantes.
Avaliação se o componente depende de JavaScript, ícones, fontes ou de markup não nativo Bootstrap.
Atualização do status na matriz dos requisitos e documentação de limitações.
Não declare equivalência comportamental com GOV.BR DS apenas porque as capturas visuais se parecem. Componentes operados pelo JavaScript Bootstrap devem conservar seus testes comportamentais.
Sass e dependências¶
Priorizar @use/@forward no código novo. Verificar antes se as dependências efetivamente consumidas ainda dependem de @import e isolar conflitos, avisos e ordem de carregamento. Fixar versões em lockfile e manter a matriz de compatibilidade atualizada.
A decisão de usar fontes upstream como dependência, copiar trechos ou reimplementar adaptadores é tomada por componente, com revisão de licença e manutenção; não há uma estratégia global presumida para todos os arquivos.
Publicação planejada¶
Atualizar documentação e subir a versão em
package.json(epackage-lock.json).Rodar
npm run build,npm test(consumidor limpo: pack → instala → compila SCSS) enpm pack --dry-run; conferir o conteúdo do tarball.Commitar na
maine enviar a tag:git tag vX.Y.Z && git push origin vX.Y.Z.O workflow
.github/workflows/release.yml(disparado pela tag) confere que a tag bate com a versão dopackage.json, compila, publica no npm via trusted publishing/OIDC e cria a GitHub Release com os assets dedist/.
Não rode gh release create antes: o workflow cria a release já com os
assets (rascunho → publicada). Criar a release antes causa o erro
Cannot upload asset to an immutable release. Pré-requisito único: Trusted
Publisher com “Allow npm publish” configurado no npmjs.com (DP-07).
Leituras úteis¶
Sass — ``@import` depreciado <https://sass-lang.com/documentation/at-rules/import/>`__.