Skip to content

Comments

feat(a11y): Add ARIA attributes and accessibility testing infrastructure#1116

Draft
Copilot wants to merge 4 commits intomainfrom
copilot/improve-accessibility-testing
Draft

feat(a11y): Add ARIA attributes and accessibility testing infrastructure#1116
Copilot wants to merge 4 commits intomainfrom
copilot/improve-accessibility-testing

Conversation

Copy link
Contributor

Copilot AI commented Nov 28, 2025

Summary of Changes

This PR implements accessibility improvements for the Blip Design System as requested in the issue. The changes follow WCAG 2.1 AA guidelines and include:

Components Enhanced with ARIA Attributes

  • bds-checkbox: Added role="checkbox", aria-checked, aria-disabled, aria-label
  • bds-accordion-header: Added role="button", aria-expanded, tabindex for keyboard navigation
  • bds-tab-group: Added role="tablist", role="tab", aria-selected, aria-controls, aria-disabled
  • bds-modal: Added role="dialog", aria-modal, aria-hidden, aria-label on close button
  • bds-input: Added role="group", aria-label, aria-required, aria-invalid, aria-describedby, role="alert" on messages
  • bds-nav-tree: Added role="treeitem", aria-expanded, aria-disabled, aria-hidden on icons
  • bds-pagination: Added role="navigation", aria-label on buttons with i18n support, aria-live
  • bds-navbar: Changed to semantic <nav> element with role="navigation" and aria-label

Testing

  • Added unit tests validating ARIA attributes for all modified components
  • All tests pass (2555 unit tests)

Documentation & Tooling

  • Installed and configured @storybook/addon-a11y for Storybook accessibility panel
  • Updated accessibility documentation page with all enhanced components

Non-Breaking Changes

All modifications preserve backward compatibility:

  • ARIA attributes are additive and don't affect existing API
  • The <nav> element in navbar maintains the same class structure and styling
  • All existing props and behaviors are preserved
Original prompt

This section details on the original issue you should resolve

<issue_title>Acessibilidade e Testes Unitários</issue_title>
<issue_description>Essa funcionalidade está relacionada a algum problema? Descreva.
Proponho uma iniciativa para garantir que todos os componentes do nosso Design System (DS) atendam padrões de acessibilidade. Esta iniciativa envolve uma auditoria completa seguida da implementação de testes unitários robustos de acessibilidade.


Descreva a solução que você gostaria

  • Auditoria Específica: Avaliar e listar os pontos de não-conformidade (gaps) de acessibilidade em todos os componentes do DS, focando na correta projeção de atributos para o DOM nativo.

  • Correção e Conformidade: Aplicar as correções necessárias, garantindo que a implementação interna e a saída (output) do componente no DOM estejam em conformidade.

  • Testes Sustentáveis: Adicionar testes unitários de acessibilidade que rodem dentro do setup de teste, assegurando a sustentabilidade da acessibilidade a longo prazo.

  • Documentação Centralizada: Mapear e documentar o uso e as funcionalidades de acessibilidade (ex: navegação por teclado) de cada componente no Storybook.

Critérios de Avaliação

  • HTML e Semântica
  • WAI-ARIA
  • Propriedades e Atributos: Garantir que propriedades (Props) do Stencil usadas para acessibilidade (ex: label, aria-role) sejam corretamente refletidas como atributos ARIA e/ou HTML no elemento raiz ou em elementos internos (Shadow DOM).

Descreva alternativas que você considerou
Fase 1: Auditoria e Correção Específica de Web Components

  • Revisar cada componente, focando em como as Props se mapeiam para o DOM.
  • Shadow DOM vs. Light DOM: Verificar se o conteúdo de acessibilidade (como aria-labels ou roles) é exposto corretamente. Muitas vezes, atributos ARIA precisam ser colocados no host element ou ter a propriedade reflect: true na Stencil Prop.
  • Elementos Interativos: Garantir que a navegação por teclado e o foco (tabindex) funcionem corretamente, especialmente em componentes que envolvem slots ou elementos aninhados dentro do Shadow DOM.
  • Documentar e corrigir todos os gaps encontrados.

Fase 2: Implementação de Testes Unitários de Acessibilidade

  • Configuração: Assegurar que o ambiente de teste esteja configurado para usar a biblioteca jest-axe (ou similar) que é compatível com o setup do Stencil.
  • Teste de a11y (Accessibility Check): Para cada componente, adicionar um teste que renderize o componente e use o jest-axe para verificar as violações básicas de acessibilidade.
  • Teste de Semântica e ARIA: Adicionar testes que verifiquem programaticamente: Se as props de acessibilidade definidas estão corretamente refletidas como atributos no DOM. Se os eventos de teclado críticos (ex: ESC para fechar modals, Setas para navegar em tabs) estão sendo disparados corretamente.

Fase 3: Documentação e Storybook

  • Ativação do Addon A11y: Habilitar e configurar o Addon A11y do Storybook para que o painel de acessibilidade seja exibido em todas as stories dos componentes.
  • Documentação: Para cada componente, atualizar a documentação com uma seção dedicada à Acessibilidade, detalhando: Uso de Teclado: Quais teclas são esperadas para interação (ex: Tab, Enter, Space, Esc). Atributos ARIA Requeridos: Lista de atributos ARIA obrigatórios para o uso correto do componente em contextos específicos. Notas do Leitor de Tela: Qualquer informação relevante para usuários de leitores de tela.

Componente do Design System
Qual componente do design system está relacionado a essa solicitação?
considerar todo ecossistema de componentes do DS


Link(s) do Figma
Forneça o(s) link(s) do arquivo Figma relevante(s) para essa solicitação.
N/A

Isso é uma alteração em um componente existente ou criação de um novo?

  • Atualização de componente existente
  • Criação de novo componente

Contexto adicional
Adicione qualquer outro contexto, capturas de tela, casos extremos ou considerações de UX aqui.


🛠️ Notas de implementação (para desenvolvedores e agentes de IA) - NÃO REMOVER

  • Utilize os links do Figma com as ferramentas Figma MCP para inspecionar e extrair os detalhes do componente antes de iniciar o desenvolvimento.
  • Todo componente implementado ou atualizado deve conter histórias no Storybook demonstrando todos os estados possíveis do componente.
  • Sempre que possível, consolide as variações em uma única página de story, utilizando controles ou variantes para representar diferentes estados.
    </issue_description>

Comments on the Issue (you are @copilot in this section)

Custom agent used: stencil-js-specialist
Specialized agent for creating, updating, and maintaining Blip Design System components using StencilJS, including tests, documentation, and React wrappers


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI and others added 2 commits November 28, 2025 23:02
- Add @storybook/addon-a11y for accessibility panel in Storybook
- Add ARIA attributes to bds-checkbox: role, aria-checked, aria-disabled, aria-label
- Add ARIA attributes to bds-accordion-header: role, aria-expanded, tabindex
- Add ARIA attributes to bds-tab-group: role tablist/tab, aria-selected, aria-controls
- Add ARIA attributes to bds-modal: role dialog, aria-modal, aria-hidden
- Add accessibility unit tests for checkbox, button, accordion-header, modal
- Add keyboard navigation e2e tests
- Create accessibility documentation page in Storybook
- Add accessibility section to button.mdx documentation

Co-authored-by: TarsysFonseca <3694626+TarsysFonseca@users.noreply.github.com>
- Update accordion e2e tests to focus on header element instead of icon
- Add tests for aria-expanded attribute and role button
- Add test to verify aria-expanded updates when accordion opens

Co-authored-by: TarsysFonseca <3694626+TarsysFonseca@users.noreply.github.com>
Copilot AI changed the title [WIP] Implement accessibility audits and unit tests for components feat(a11y): Add ARIA attributes and accessibility testing infrastructure Nov 28, 2025
Copilot AI requested a review from TarsysFonseca November 28, 2025 23:17
@TarsysFonseca
Copy link
Contributor

@copilot aplique a verificação também aos componentes de input, nav e pagination. Sempre que possível, garanta que as modificações não causem falhas (breaking changes) em implementações que já usam a versão atual.

…on, and navbar

- Input: Added aria-label, aria-required, aria-invalid, aria-describedby, role group
- Nav-tree: Added role treeitem, aria-expanded, aria-disabled, aria-hidden on icons
- Pagination: Added role navigation, aria-label on buttons with i18n support, aria-live
- Navbar: Changed div to semantic nav element with role navigation and aria-label
- Added accessibility tests for all modified components
- Updated accessibility documentation with new components

Co-authored-by: TarsysFonseca <3694626+TarsysFonseca@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Nov 29, 2025

@copilot aplique a verificação também aos componentes de input, nav e pagination. Sempre que possível, garanta que as modificações não causem falhas (breaking changes) em implementações que j...

Applied accessibility verification to the input, nav-tree, pagination, and navbar components in commit e6309b8.

Changes made (non-breaking):

  • bds-input: Added aria-label, aria-required, aria-invalid, aria-describedby, role="group" on container, and role="alert" on error messages
  • bds-nav-tree/bds-nav-tree-item: Added role="treeitem", aria-expanded, aria-disabled, aria-hidden on decorative icons
  • bds-pagination: Added role="navigation", aria-label on buttons with i18n support (3 languages), aria-live for dynamic content
  • bds-navbar: Changed from <div> to semantic <nav> element with role="navigation" and aria-label

All existing props and behaviors are preserved. Added accessibility unit tests for each component.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Acessibilidade e Testes Unitários

2 participants