# Guia de Referência: Bootstrap 5.3.8 para IA Este guia é um contrato operacional para uma IA criar, revisar ou refatorar interfaces com **Bootstrap 5.3.8**. O objetivo não é apenas listar classes: é ensinar **como decidir**, **quando aplicar**, **como combinar** e **quando não usar** cada recurso. --- ## 1. Contrato de execução para a IA - **Versão-alvo:** Bootstrap **5.3.8**. Não misturar sintaxe de Bootstrap 4 ou versões futuras sem solicitação explícita. - **Mobile first:** projetar a menor viewport primeiro e adicionar variações nos breakpoints necessários. - **HTML semântico primeiro:** Bootstrap é uma camada de apresentação e comportamento; não deve degradar a semântica de HTML. - **Composição antes de CSS customizado:** use grid, helpers e utilities documentados antes de criar regras locais. - **Componentes antes de reinvenção:** quando Bootstrap já oferece um componente adequado, adapte-o em vez de criar outro incompatível. - **Acessibilidade como requisito:** foco visível, labels, contraste, teclado, nomes acessíveis e feedback textual fazem parte da entrega. - **JS mínimo e explícito:** use Data API (`data-bs-*`) para casos simples; use a API JavaScript quando a aplicação precisa controlar instâncias, eventos ou ciclo de vida. - **Não editar dependências:** nunca modificar arquivos em `node_modules`, `dist` de terceiros ou CDN. Customize via Sass, CSS variables e arquivos próprios. - **Tokens centralizados:** cores, espaçamento, radius e tema devem ser controlados em poucos pontos para evitar divergência visual. - **Compatibilidade consciente:** não inventar classes. Se não souber se uma classe existe na 5.3.8, consultar a referência antes de gerar código. --- ## 2. Inicialização e arquitetura de uso ### 2.1 Formas de incluir Bootstrap - **CDN:** adequada para protótipos, páginas simples e quando não há pipeline de build. - **npm/yarn/bun:** preferível quando o projeto possui build, bundler, Sass ou tree-shaking do código de aplicação. - **Fontes Sass:** escolha quando for necessário customizar tokens, maps, opções e gerar somente as partes utilizadas. - **Bundle JavaScript:** `bootstrap.bundle` inclui as dependências necessárias a componentes que usam posicionamento; ao importar módulos individualmente, gerencie dependências conscientemente. ### 2.2 Estrutura mental do repositório - `scss/`: fontes Sass, variáveis, maps, mixins e componentes CSS. - `js/`: plugins JavaScript e utilitários internos. - `dist/`: distribuição compilada. - `site/`: documentação/exemplos do projeto Bootstrap. - `build/`: scripts e infraestrutura de build. ### 2.3 Documento-base Use HTML5 (``), `lang`, charset, viewport responsivo e uma hierarquia semântica. A IA deve diferenciar **link** (navegação) de **button** (ação) e manter estados de teclado/foco. --- ## 3. Mapa completo do Bootstrap 5.3.8 As seções abaixo cobrem **Customize, Layout, Content, Forms, Components, Helpers, Utilities e Extend**, incluindo todos os itens solicitados. Cada tópico contém conceito e regra de uso para IA. ## 3.1 Customize **Diretriz da categoria:** Centralize tokens e escolhas de tema. A IA não deve sobrescrever dezenas de seletores quando uma variável Sass/CSS resolve o problema. ### 1. Overview - **Conceito:** Visão geral dos mecanismos de personalização: Sass, opções, cores, modos de cor, componentes, variáveis CSS e otimização. - **Regra para IA:** antes de aplicar **Overview**, confirme que o problema pertence à categoria **Customize**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/customize/overview/ ### 2. Sass - **Conceito:** Use os fontes Sass para controlar variáveis, maps, mixins e funções antes da compilação. - **Regra para IA:** antes de aplicar **Sass**, confirme que o problema pertence à categoria **Customize**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/customize/sass/ ### 3. Options - **Conceito:** Preferências globais de CSS controladas por variáveis Sass; centralize as opções em um ponto de configuração. - **Regra para IA:** antes de aplicar **Options**, confirme que o problema pertence à categoria **Customize**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/customize/options/ ### 4. Color - **Conceito:** Sistema de cores, theme colors, maps Sass e geração de variantes/utilitários. - **Regra para IA:** antes de aplicar **Color**, confirme que o problema pertence à categoria **Customize**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/customize/color/ ### 5. Color modes - **Conceito:** Temas claro/escuro e modos personalizados por meio de data-bs-theme e variáveis CSS. - **Regra para IA:** antes de aplicar **Color modes**, confirme que o problema pertence à categoria **Customize**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/customize/color-modes/ ### 6. Components - **Conceito:** Base + modifier, maps e loops Sass para gerar variantes de componentes de modo sistemático. - **Regra para IA:** antes de aplicar **Components**, confirme que o problema pertence à categoria **Customize**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/customize/components/ ### 7. CSS variables - **Conceito:** Variáveis --bs-* para customização em runtime e escopos locais sem recompilar todo o Sass. - **Regra para IA:** antes de aplicar **CSS variables**, confirme que o problema pertence à categoria **Customize**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/customize/css-variables/ ### 8. Optimize - **Conceito:** Reduza CSS/JS não usado, importe somente o necessário, avalie ícones/fontes e minimize payload. - **Regra para IA:** antes de aplicar **Optimize**, confirme que o problema pertence à categoria **Customize**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/customize/optimize/ ## 3.2 Layout **Diretriz da categoria:** Comece mobile-first. Selecione container → grid/flex → gutters → utilitários. Só crie CSS customizado quando a composição nativa não expressar a regra. ### 9. Breakpoints - **Conceito:** Breakpoints mobile-first: xs <576px, sm ≥576, md ≥768, lg ≥992, xl ≥1200, xxl ≥1400. - **Regra para IA:** antes de aplicar **Breakpoints**, confirme que o problema pertence à categoria **Layout**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/layout/breakpoints/ ### 10. Containers - **Conceito:** Use .container para largura responsiva, .container-fluid para 100% e .container-{breakpoint} para alternância. - **Regra para IA:** antes de aplicar **Containers**, confirme que o problema pertence à categoria **Layout**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/layout/containers/ ### 11. Grid - **Conceito:** Grid responsivo de 12 colunas baseado em flexbox com .row e .col-*. - **Regra para IA:** antes de aplicar **Grid**, confirme que o problema pertence à categoria **Layout**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/layout/grid/ ### 12. Columns - **Conceito:** Controle alinhamento, ordem, largura automática, offset e comportamento responsivo de colunas. - **Regra para IA:** antes de aplicar **Columns**, confirme que o problema pertence à categoria **Layout**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/layout/columns/ ### 13. Gutters - **Conceito:** Espaçamento entre colunas/linhas com .g-*, .gx-* e .gy-*. - **Regra para IA:** antes de aplicar **Gutters**, confirme que o problema pertence à categoria **Layout**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/layout/gutters/ ### 14. Utilities - **Conceito:** Combine utilitários de display, flex, spacing e sizing para ajustes de layout sem CSS específico desnecessário. - **Regra para IA:** antes de aplicar **Utilities**, confirme que o problema pertence à categoria **Layout**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/layout/utilities/ ### 15. Z-index - **Conceito:** Entenda a escala de empilhamento dos componentes e crie novos contextos de stacking com cautela. - **Regra para IA:** antes de aplicar **Z-index**, confirme que o problema pertence à categoria **Layout**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/layout/z-index/ ### 16. CSS Grid - **Conceito:** Alternativa opt-in baseada em CSS Grid, usando .grid e .g-col-* quando suas características forem mais adequadas. - **Regra para IA:** antes de aplicar **CSS Grid**, confirme que o problema pertence à categoria **Layout**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/layout/css-grid/ ## 3.3 Content **Diretriz da categoria:** Preserve HTML semântico e use as classes do Bootstrap como camada visual. Não troque semântica por divs apenas para obter estilo. ### 17. Reboot - **Conceito:** Normalização opinativa do Bootstrap para consistência de tipografia, box sizing, elementos nativos e defaults. - **Regra para IA:** antes de aplicar **Reboot**, confirme que o problema pertence à categoria **Content**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/content/reboot/ ### 18. Typography - **Conceito:** Cabeçalhos, display headings, lead, listas, blockquote e utilitários tipográficos. - **Regra para IA:** antes de aplicar **Typography**, confirme que o problema pertence à categoria **Content**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/content/typography/ ### 19. Images - **Conceito:** Imagens responsivas com .img-fluid, thumbnails e alinhamentos adequados. - **Regra para IA:** antes de aplicar **Images**, confirme que o problema pertence à categoria **Content**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/content/images/ ### 20. Tables - **Conceito:** Tabelas opt-in com variantes, hover, striped, borders, responsividade e semântica HTML preservada. - **Regra para IA:** antes de aplicar **Tables**, confirme que o problema pertence à categoria **Content**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/content/tables/ ### 21. Figures - **Conceito:** Estrutura consistente para figura, imagem e legenda com .figure, .figure-img e .figure-caption. - **Regra para IA:** antes de aplicar **Figures**, confirme que o problema pertence à categoria **Content**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/content/figures/ ## 3.4 Forms **Diretriz da categoria:** Label explícito, feedback compreensível e validação acessível. Bootstrap estiliza; a regra de negócio continua no domínio/aplicação. ### 22. Overview - **Conceito:** Visão geral dos controles de formulário, estados, layout, acessibilidade e convenções de markup. - **Regra para IA:** antes de aplicar **Overview**, confirme que o problema pertence à categoria **Forms**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/forms/overview/ ### 23. Form control - **Conceito:** Inputs textuais e textarea com .form-control, tamanhos, estados e arquivos. - **Regra para IA:** antes de aplicar **Form control**, confirme que o problema pertence à categoria **Forms**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/forms/form-control/ ### 24. Select - **Conceito:** Select nativo estilizado com .form-select; preserve labels e semântica do controle. - **Regra para IA:** antes de aplicar **Select**, confirme que o problema pertence à categoria **Forms**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/forms/select/ ### 25. Checks & radios - **Conceito:** Checkbox, radio e switch com .form-check, incluindo inline e estados. - **Regra para IA:** antes de aplicar **Checks & radios**, confirme que o problema pertence à categoria **Forms**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/forms/checks-radios/ ### 26. Range - **Conceito:** Range input estilizado com .form-range. - **Regra para IA:** antes de aplicar **Range**, confirme que o problema pertence à categoria **Forms**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/forms/range/ ### 27. Input group - **Conceito:** Agrupa texto, botões e controles mantendo associação visual e semântica. - **Regra para IA:** antes de aplicar **Input group**, confirme que o problema pertence à categoria **Forms**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/forms/input-group/ ### 28. Floating labels - **Conceito:** Labels flutuantes requerem estrutura e placeholder apropriados; não substituem acessibilidade do label. - **Regra para IA:** antes de aplicar **Floating labels**, confirme que o problema pertence à categoria **Forms**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/forms/floating-labels/ ### 29. Layout - **Conceito:** Grid, gutters e utilitários para formulários inline, responsivos e complexos. - **Regra para IA:** antes de aplicar **Layout**, confirme que o problema pertence à categoria **Forms**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/forms/layout/ ### 30. Validation - **Conceito:** Validação nativa ou customizada com .was-validated, .is-valid e .is-invalid, sempre com feedback textual. - **Regra para IA:** antes de aplicar **Validation**, confirme que o problema pertence à categoria **Forms**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/forms/validation/ ## 3.5 Components **Diretriz da categoria:** Prefira componentes documentados a widgets reinventados. Use Data API quando simples e API JavaScript quando precisar de ciclo de vida/controle programático. ### 31. Accordion - **Conceito:** Conteúdo expansível organizado sobre Collapse; útil para informação secundária e FAQ. - **Regra para IA:** antes de aplicar **Accordion**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/accordion/ ### 32. Alerts - **Conceito:** Mensagens contextuais de status; use role apropriado e não dependa apenas de cor. - **Regra para IA:** antes de aplicar **Alerts**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/alerts/ ### 33. Badge - **Conceito:** Indicador compacto para status, contagem ou categoria; mantenha contexto textual. - **Regra para IA:** antes de aplicar **Badge**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/badge/ ### 34. Breadcrumb - **Conceito:** Trilha de navegação hierárquica; utilize nav e aria-label. - **Regra para IA:** antes de aplicar **Breadcrumb**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/breadcrumb/ ### 35. Buttons - **Conceito:** Ações com .btn; use button para ação e a apenas para navegação. - **Regra para IA:** antes de aplicar **Buttons**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/buttons/ ### 36. Button group - **Conceito:** Agrupamento visual/funcional de ações relacionadas, com rótulos acessíveis. - **Regra para IA:** antes de aplicar **Button group**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/button-group/ ### 37. Card - **Conceito:** Contêiner flexível de conteúdo com header/body/footer, imagens e variantes. - **Regra para IA:** antes de aplicar **Card**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/card/ ### 38. Carousel - **Conceito:** Conteúdo deslizante; use com parcimônia, controle de pausa e rótulos acessíveis. - **Regra para IA:** antes de aplicar **Carousel**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/carousel/ ### 39. Close button - **Conceito:** Controle de fechar com .btn-close e nome acessível. - **Regra para IA:** antes de aplicar **Close button**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/close-button/ ### 40. Collapse - **Conceito:** Mostra/oculta conteúdo via Data API ou JS; sincronize aria-expanded e target. - **Regra para IA:** antes de aplicar **Collapse**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/collapse/ ### 41. Dropdowns - **Conceito:** Menus contextuais posicionados com Popper; preserve navegação por teclado. - **Regra para IA:** antes de aplicar **Dropdowns**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/dropdowns/ ### 42. List group - **Conceito:** Listas estilizadas de itens, links e estados ativos/disabled. - **Regra para IA:** antes de aplicar **List group**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/list-group/ ### 43. Modal - **Conceito:** Diálogo modal para foco temporário; evite modais aninhados e forneça título/fechamento claros. - **Regra para IA:** antes de aplicar **Modal**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/modal/ ### 44. Navbar - **Conceito:** Cabeçalho/navegação responsiva com brand, nav, toggler e collapse/offcanvas. - **Regra para IA:** antes de aplicar **Navbar**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/navbar/ ### 45. Navs & tabs - **Conceito:** Navegação entre seções equivalentes; tabs exigem relação correta entre tab e panel. - **Regra para IA:** antes de aplicar **Navs & tabs**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/navs-tabs/ ### 46. Offcanvas - **Conceito:** Painel lateral/modal, útil para navegação móvel, filtros e tarefas secundárias. - **Regra para IA:** antes de aplicar **Offcanvas**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/offcanvas/ ### 47. Pagination - **Conceito:** Navegação entre páginas; forneça estado atual, disabled e rótulos. - **Regra para IA:** antes de aplicar **Pagination**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/pagination/ ### 48. Placeholders - **Conceito:** Skeletons de carregamento; complemente com estado acessível e evite simular conteúdo por tempo indefinido. - **Regra para IA:** antes de aplicar **Placeholders**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/placeholders/ ### 49. Popovers - **Conceito:** Conteúdo contextual acionável; depende de Popper e precisa de inicialização JS. - **Regra para IA:** antes de aplicar **Popovers**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/popovers/ ### 50. Progress - **Conceito:** Progresso de tarefa; informe valor semanticamente e não apenas visualmente. - **Regra para IA:** antes de aplicar **Progress**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/progress/ ### 51. Scrollspy - **Conceito:** Atualiza navegação conforme a região rolada; requer targets estáveis e estrutura previsível. - **Regra para IA:** antes de aplicar **Scrollspy**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/scrollspy/ ### 52. Spinners - **Conceito:** Indicação indeterminada de carregamento; adicione texto acessível/aria-live quando necessário. - **Regra para IA:** antes de aplicar **Spinners**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/spinners/ ### 53. Toasts - **Conceito:** Feedback não bloqueante e temporário; ajuste delay/autohide e use live regions adequadas. - **Regra para IA:** antes de aplicar **Toasts**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/toasts/ ### 54. Tooltips - **Conceito:** Informação suplementar curta; nunca esconda informação essencial apenas em hover/focus. - **Regra para IA:** antes de aplicar **Tooltips**, confirme que o problema pertence à categoria **Components**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/components/tooltips/ ## 3.6 Helpers **Diretriz da categoria:** Helpers resolvem casos estruturais pequenos. Não os transforme em substitutos de uma arquitetura de layout coerente. ### 55. Clearfix - **Conceito:** Limpa floats legados; prefira flex/grid quando o layout puder ser moderno. - **Regra para IA:** antes de aplicar **Clearfix**, confirme que o problema pertence à categoria **Helpers**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/helpers/clearfix/ ### 56. Color & background - **Conceito:** Pares de cor/fundo com contraste contextual coerente. - **Regra para IA:** antes de aplicar **Color & background**, confirme que o problema pertence à categoria **Helpers**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/helpers/color-background/ ### 57. Colored links - **Conceito:** Links coloridos com estados hover/focus derivados do sistema de cores. - **Regra para IA:** antes de aplicar **Colored links**, confirme que o problema pertence à categoria **Helpers**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/helpers/colored-links/ ### 58. Focus ring - **Conceito:** Anel de foco customizável; nunca remova foco sem substituto claramente visível. - **Regra para IA:** antes de aplicar **Focus ring**, confirme que o problema pertence à categoria **Helpers**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/helpers/focus-ring/ ### 59. Icon link - **Conceito:** Alinha ícone e texto em links e controla transformações de ícone. - **Regra para IA:** antes de aplicar **Icon link**, confirme que o problema pertence à categoria **Helpers**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/helpers/icon-link/ ### 60. Position - **Conceito:** Atalhos para posicionar elementos relativos/absolutos em casos comuns. - **Regra para IA:** antes de aplicar **Position**, confirme que o problema pertence à categoria **Helpers**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/helpers/position/ ### 61. Ratio - **Conceito:** Mantém proporção de embeds/vídeos/conteúdo com .ratio e variantes. - **Regra para IA:** antes de aplicar **Ratio**, confirme que o problema pertence à categoria **Helpers**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/helpers/ratio/ ### 62. Stacks - **Conceito:** Pilhas verticais/horizontais com .vstack/.hstack e gap. - **Regra para IA:** antes de aplicar **Stacks**, confirme que o problema pertence à categoria **Helpers**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/helpers/stacks/ ### 63. Stretched link - **Conceito:** Expande área clicável de um link dentro de um contêiner posicionado; verifique sobreposição/interações. - **Regra para IA:** antes de aplicar **Stretched link**, confirme que o problema pertence à categoria **Helpers**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/helpers/stretched-link/ ### 64. Text truncation - **Conceito:** Trunca uma linha com reticências; disponibilize conteúdo completo quando necessário. - **Regra para IA:** antes de aplicar **Text truncation**, confirme que o problema pertence à categoria **Helpers**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/helpers/text-truncation/ ### 65. Vertical rule - **Conceito:** Separador vertical que herda cor e funciona em layouts flex. - **Regra para IA:** antes de aplicar **Vertical rule**, confirme que o problema pertence à categoria **Helpers**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/helpers/vertical-rule/ ### 66. Visually hidden - **Conceito:** Conteúdo disponível a tecnologias assistivas sem exibição visual; use também focusable quando aplicável. - **Regra para IA:** antes de aplicar **Visually hidden**, confirme que o problema pertence à categoria **Helpers**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/helpers/visually-hidden/ ## 3.7 Utilities **Diretriz da categoria:** Use utilities para composição local e previsível. Quando um conjunto se repete muito, extraia um componente/classe semântica. ### 67. API - **Conceito:** Sass Utilities API para criar, remover ou adaptar famílias de classes utilitárias. - **Regra para IA:** antes de aplicar **API**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/api/ ### 68. Background - **Conceito:** Background colors/gradients com tokens e opacidade. - **Regra para IA:** antes de aplicar **Background**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/background/ ### 69. Borders - **Conceito:** Adicionar/remover bordas, cor, largura, radius e opacidade. - **Regra para IA:** antes de aplicar **Borders**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/borders/ ### 70. Colors - **Conceito:** Classes de cor textual/contextual; valide contraste. - **Regra para IA:** antes de aplicar **Colors**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/colors/ ### 71. Display - **Conceito:** Controla display responsivamente; útil para esconder/mostrar ou alternar layout. - **Regra para IA:** antes de aplicar **Display**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/display/ ### 72. Flex - **Conceito:** Direção, wrap, justify, align, grow/shrink e order sobre flex containers/items. - **Regra para IA:** antes de aplicar **Flex**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/flex/ ### 73. Float - **Conceito:** Floats responsivos; use apenas quando float é semanticamente adequado, não como grid moderno. - **Regra para IA:** antes de aplicar **Float**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/float/ ### 74. Interactions - **Conceito:** Seleção de texto e pointer-events; não bloqueie interação necessária/acessível. - **Regra para IA:** antes de aplicar **Interactions**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/interactions/ ### 75. Link - **Conceito:** Opacity, offset, underline e estados de link. - **Regra para IA:** antes de aplicar **Link**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/link/ ### 76. Object fit - **Conceito:** Controla como mídia substituída ocupa a caixa: contain, cover, fill, scale, none. - **Regra para IA:** antes de aplicar **Object fit**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/object-fit/ ### 77. Opacity - **Conceito:** Opacidade do elemento; atenção a contraste e hit targets. - **Regra para IA:** antes de aplicar **Opacity**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/opacity/ ### 78. Overflow - **Conceito:** Controle de overflow auto/hidden/visible/scroll e eixos conforme suporte. - **Regra para IA:** antes de aplicar **Overflow**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/overflow/ ### 79. Position - **Conceito:** static, relative, absolute, fixed, sticky e utilitários top/start/end/bottom/translate. - **Regra para IA:** antes de aplicar **Position**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/position/ ### 80. Shadows - **Conceito:** Sombras predefinidas para hierarquia visual; não use como único indicador de estado. - **Regra para IA:** antes de aplicar **Shadows**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/shadows/ ### 81. Sizing - **Conceito:** Largura/altura/min/max relativas a parent e viewport. - **Regra para IA:** antes de aplicar **Sizing**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/sizing/ ### 82. Spacing - **Conceito:** Margin, padding e gap responsivos; siga escala do design system. - **Regra para IA:** antes de aplicar **Spacing**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/spacing/ ### 83. Text - **Conceito:** Alinhamento, wrapping, transform, weight, style, decoration, monospace e line-height. - **Regra para IA:** antes de aplicar **Text**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/text/ ### 84. Vertical align - **Conceito:** Alinhamento vertical de inline/table-cell; não substitui alinhamento flex/grid. - **Regra para IA:** antes de aplicar **Vertical align**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/vertical-align/ ### 85. Visibility - **Conceito:** visibility sem alterar layout; diferencie de display:none e de visually-hidden. - **Regra para IA:** antes de aplicar **Visibility**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/visibility/ ### 86. Z-index - **Conceito:** Classes simplificadas de z-index; evite corrida de números e documente camadas. - **Regra para IA:** antes de aplicar **Z-index**, confirme que o problema pertence à categoria **Utilities**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/utilities/z-index/ ## 3.8 Extend **Diretriz da categoria:** Estenda sem modificar arquivos do pacote. Mantenha customizações em fontes próprios e processo de build reproduzível. ### 87. Approach - **Conceito:** Entenda decisões e princípios de extensão para adicionar regras sem lutar contra a arquitetura do Bootstrap. - **Regra para IA:** antes de aplicar **Approach**, confirme que o problema pertence à categoria **Extend**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/extend/approach/ ### 88. Icons - **Conceito:** Bootstrap não inclui ícones no core; escolha biblioteca de ícones conscientemente e preserve acessibilidade. - **Regra para IA:** antes de aplicar **Icons**, confirme que o problema pertence à categoria **Extend**, escolha a menor combinação de classes/markup que resolva o caso e preserve responsividade e acessibilidade. - **Critério de revisão:** verificar semântica, estados responsivos, foco/teclado quando houver interação e ausência de overrides desnecessários. - **Referência oficial:** https://getbootstrap.com/docs/5.3/extend/icons/ --- ## 4. Regras de decisão por situação ### Preciso organizar a página 1. Escolha o container. 2. Defina a estrutura com Grid/Flex. 3. Ajuste gutters. 4. Aplique spacing/sizing somente onde necessário. 5. Teste xs, sm, md, lg, xl e xxl. ### Preciso construir um formulário 1. Use elementos nativos e labels reais. 2. Selecione `.form-control`, `.form-select`, `.form-check` ou `.form-range`. 3. Use grid/layout. 4. Defina mensagens de validação. 5. Teste teclado, erro, disabled, readonly e mobile. ### Preciso fornecer feedback - **Alert:** mensagem persistente/contextual. - **Toast:** feedback breve e não bloqueante. - **Spinner:** atividade indeterminada. - **Progress:** avanço mensurável. - **Placeholder:** esqueleto enquanto conteúdo é carregado. ### Preciso ocultar conteúdo - `display` remove do layout e normalmente da árvore de acessibilidade. - `visibility` mantém espaço. - `.visually-hidden` mantém conteúdo disponível a tecnologias assistivas. - `collapse/offcanvas/modal` são componentes interativos e exigem estados/atributos corretos. ### Preciso personalizar o tema 1. Prefira CSS variables quando a alteração é dinâmica/local. 2. Prefira Sass quando precisa alterar sistema/tokens/build. 3. Use `data-bs-theme` para color modes. 4. Nunca espalhe hexadecimais e overrides repetidos. --- ## 5. JavaScript dos componentes - Instâncias devem ser criadas/obtidas pela API documentada quando a aplicação controla o componente programaticamente. - Ouça eventos `show`, `shown`, `hide`, `hidden` e equivalentes quando a lógica depende do ciclo de vida visual. - Tooltips, popovers e dropdowns têm necessidades de posicionamento; não copie implementações caseiras de Popper. - Não mantenha estado duplicado em DOM e aplicação. Eleja uma fonte de verdade e sincronize via eventos. - Descarte instâncias quando elementos dinâmicos forem destruídos se a API exigir limpeza. --- ## 6. Acessibilidade obrigatória - Nunca use apenas cor para comunicar estado. - Todo ícone interativo precisa de nome acessível; ícones decorativos devem ser ignorados por tecnologia assistiva. - Não remova outline/focus sem um `focus-ring` equivalente ou melhor. - Modais, offcanvas, dropdowns, tabs, accordion e collapse devem conservar relações ARIA previstas pelo componente. - Mensagens de erro devem estar associadas ao campo e ser compreensíveis sem depender do visual. - Tooltips não podem conter a única informação necessária para concluir uma tarefa. - Respeite `prefers-reduced-motion` quando adicionar animação própria. --- ## 7. Performance e otimização - Importe somente módulos Sass/JS necessários quando o pipeline permitir. - Minifique CSS/JS para produção e remova código próprio não utilizado. - Evite múltiplas bibliotecas que resolvem os mesmos componentes. - Não carregue biblioteca de ícones inteira se o projeto usa poucos ícones e o custo for relevante. - Meça antes/depois; otimização não deve quebrar acessibilidade ou manutenção. --- ## 8. Antipadrões que a IA deve evitar - Inventar classes como `.btn-super-primary` sem existir definição no projeto. - Usar `!important` como solução padrão contra especificidade. - Criar grid com margens mágicas quando `.row`, `.col-*`, gap e utilities resolvem. - Usar `` para ações que deveriam ser `