Skip to content

feat(pill): improve accessibility #IX-3654#2415

Open
alexkaduk wants to merge 1 commit intomainfrom
feature/IX-3654-pill-a11y
Open

feat(pill): improve accessibility #IX-3654#2415
alexkaduk wants to merge 1 commit intomainfrom
feature/IX-3654-pill-a11y

Conversation

@alexkaduk
Copy link
Collaborator

@alexkaduk alexkaduk commented Mar 1, 2026

💡 What is the current behavior?

ARIA attributes (aria-label, aria-hidden, role, etc.) set on the <ix-pill> host element don't work due to Shadow DOM encapsulation. Icon-only pills have no accessible name (WCAG 1.1.1 violation), and all icons are exposed to screen readers causing redundant announcements. No automated accessibility tests or documentation exists for accessible pill usage patterns.

GitHub Issue Number: #3654

🆕 What is the new behavior?

  • ARIA attributes now properly transferred to internal container using a11yHostAttributes utility
  • Automatic role="group" inference when aria-label is set without explicit role
  • Icons are decorative by default (aria-hidden="true") to prevent redundant screen reader announcements
  • Icon-only pills require aria-label on host element for accessible name
  • New ariaLabelIcon prop (HTML: aria-label-icon) for informational icons that convey additional meaning
  • Support for status indicators with role="status" and aria-live="polite"
  • Fixed icon-only pills in all framework preview examples (HTML, React, Angular, Angular Standalone, Vue)
  • Added 6 component tests for ARIA attribute handling and icon accessibility
  • Added axe-core tests with custom rule configuration
  • Added accessibility tree snapshots
  • Created 12 Storybook accessibility examples
  • Added comprehensive JSDoc documentation with usage patterns and warnings

🏁 Checklist

A pull request can only be merged if all of these conditions are met (where applicable):

  • 🦮 Accessibility (a11y) features were implemented
  • 🗺️ Internationalization (i18n) - no hard coded strings
  • 📲 Responsiveness - components handle viewport changes and content overflow gracefully
  • 📕 Add or update a Storybook story
  • 📄 Documentation was reviewed/updated siemens/ix-docs
  • 🧪 Unit tests were added/updated and pass (pnpm test)
  • 📸 Visual regression tests were added/updated and pass (Guide)
  • 🧐 Static code analysis passes (pnpm lint)
  • 🏗️ Successful compilation (pnpm build, changes pushed)

👨‍💻 Help & support

Breaking Changes: None - all changes are backward compatible.

Action Required for WCAG Compliance:

  • Icon-only pills now need aria-label attribute: <ix-pill icon="star" aria-label="Featured"></ix-pill>

Testing Note: Pills are non-interactive elements - use browse mode (arrow keys) for screen reader testing, not Tab navigation.

@changeset-bot
Copy link

changeset-bot bot commented Mar 1, 2026

🦋 Changeset detected

Latest commit: 979dd39

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages
Name Type
@siemens/ix Patch
@siemens/ix-angular Patch
@siemens/ix-docs Patch
@siemens/ix-react Patch
@siemens/ix-vue Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@gemini-code-assist
Copy link
Contributor

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the accessibility of the Pill component, ensuring it is usable and understandable for screen reader users and other assistive technologies. The changes address issues with ARIA attribute propagation in Shadow DOM, provide granular control over icon accessibility, and introduce robust testing and documentation to guide developers in creating accessible user interfaces.

Highlights

  • ARIA Attribute Handling: Implemented a utility to transfer ARIA attributes from the host element to the internal semantic container, ensuring they are correctly exposed within the Shadow DOM. This includes automatic inference of role="group" when aria-label is present without an explicit role.
  • Icon Accessibility: Icons are now aria-hidden="true" by default, treating them as decorative. A new aria-label-icon prop allows developers to provide accessible names for informational icons, making them perceivable by screen readers.
  • Accessibility Testing: Added comprehensive accessibility tests, including new component tests for ARIA attribute transfer and icon visibility, axe-core tests with custom rule configurations, and accessibility tree snapshots to verify correct structure.
  • Documentation & Examples: Extensive JSDoc has been added to the pill.tsx component, detailing ARIA usage patterns, icon accessibility, and status pill configurations. Preview examples across frameworks and new Storybook accessibility stories have been updated to demonstrate correct usage.
  • Icon-Only Pill Requirement: Icon-only pills now explicitly require an aria-label to meet WCAG 1.1.1 (Non-text Content) guidelines, with updated examples demonstrating this critical fix.
Changelog
  • .gitignore
    • Added an entry for a temporary file, /CLAUDE.md.
  • packages/angular-test-app/src/preview-examples/pill.html
    • Updated an icon-only pill example to include aria-label="Featured" for accessibility.
  • packages/core/src/components/pill/pill.tsx
    • Imported the a11yHostAttributes utility.
    • Applied a11yHostAttributes to transfer ARIA attributes from the host to the internal container.
    • Implemented logic to automatically set role="group" on the container if aria-label is present without an explicit role.
    • Configured ix-icon to be aria-hidden="true" by default unless ariaLabelIcon is provided.
  • packages/core/src/components/pill/test/pill.ct.ts
    • Added new component tests to verify ARIA attribute transfer (aria-label, aria-hidden, role).
    • Added tests to confirm decorative icons are hidden from screen readers and informational icons are correctly labeled.
  • packages/html-test-app/src/preview-examples/pill.html
    • Added a <button> element.
    • Updated an icon-only pill example to include aria-label="Featured" for accessibility.
  • packages/react-test-app/src/preview-examples/pill.tsx
    • Updated an icon-only pill example to include aria-label="Featured" for accessibility.
  • packages/storybook-docs/src/stories/pill/accessibility/a11y-pill.stories.ts
    • Added a new Storybook file dedicated to Pill accessibility examples.
    • Included 12 comprehensive examples demonstrating various ARIA patterns, icon accessibility, and status indicators.
  • packages/vue-test-app/src/preview-examples/pill.vue
    • Updated an icon-only pill example to include aria-label="Featured" for accessibility.
  • testing/framework-tests/snapshots/pill-aria-snapshot.yaml
    • Removed the old accessibility snapshot for pills.
  • testing/framework-tests/snapshots/pill-variants-aria-snapshot.yaml
    • Removed the old accessibility snapshot for pill variants.
  • testing/framework-tests/snapshots/pill-variants.aria-snapshot.yaml
    • Added a new accessibility snapshot for pill variants.
  • testing/framework-tests/snapshots/pill.aria-snapshot.yaml
    • Added a new accessibility snapshot for pills.
  • testing/framework-tests/src/main.ts
    • Introduced customAxeRules to allow per-test disabling of specific axe-core rules.
    • Updated the AxeBuilder configuration to use the new allDisabledRules array.
  • testing/framework-tests/tests/generated/pill-axe.spec.ts
    • Updated the axe-core test to disable the aria-tooltip-name rule for the pill component.
  • testing/framework-tests/tests/generated/pill-variants-axe.spec.ts
    • Updated the axe-core test to disable the aria-tooltip-name rule for pill variants.
  • testing/framework-tests/tests/working-with-axe.spec.ts
    • Imported the generated axe accessibility tests for the pill component.
  • testing/framework-tests/tests/working.spec.ts
    • Imported the generated tests for the pill component.
Activity
  • New component tests were added to pill.ct.ts to validate ARIA attribute transfer and icon accessibility.
  • Axe-core tests were integrated and configured with custom rules to address known limitations, ensuring automated accessibility checks.
  • Accessibility tree snapshots were generated to provide a baseline for verifying the correct semantic structure.
  • New Storybook stories were created to showcase various accessibility patterns and best practices for the Pill component.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces significant and well-implemented accessibility improvements for the ix-pill component, including transferring ARIA attributes to the Shadow DOM, making icons decorative by default, and adding comprehensive tests and documentation. A security audit confirmed that no vulnerabilities were identified, with the implementation safely handling ARIA attributes and data flow. However, a critical issue was found in packages/html-test-app/src/preview-examples/pill.html where reformatting has led to invalid HTML syntax, which will break the preview and requires immediate attention. This issue is in violation of the rule to ensure HTML is well-formed by removing any extra closing tags to prevent invalid HTML.

@alexkaduk
Copy link
Collaborator Author

/gemini review

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request provides a comprehensive set of accessibility improvements for the ix-pill component. The approach of transferring ARIA attributes from the host to an internal element in the Shadow DOM is well-implemented using the a11yHostAttributes utility. The distinction between decorative and informational icons with aria-hidden and aria-label-icon is a great enhancement. The changes are also thoroughly covered by new component tests, accessibility tests (axe-core), and extensive Storybook examples, which is excellent. The updates to the test infrastructure to support custom axe rules per test are also a valuable addition. The minor suggestion to improve adherence to ARIA specifications in a Storybook example remains valid.

@alexkaduk alexkaduk force-pushed the feature/IX-3654-pill-a11y branch from e4e0f29 to 979dd39 Compare March 1, 2026 18:51
@sonarqubecloud
Copy link

sonarqubecloud bot commented Mar 1, 2026

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.

1 participant