fix(a11y): only use baseConcepts in useSemanticElements rule (#9245) by ruidosujeira · Pull Request #9311 · biomejs/biome

ruidosujeira · 2026-03-03T14:25:11Z

Summary

The useSemanticElements rule treated baseConcepts and relatedConcepts as equivalent when suggesting HTML element replacements. This caused incorrect suggestions — for example, suggesting <output> for <div role="status">, when <output> is only a relatedConcept of the "status" role.

The rule now only considers baseConcepts when suggesting semantic HTML elements.

Test Plan

Added test case for <div role="status"> to verify it no longer suggests <output>. Existing tests pass — roles with valid baseConcepts (e.g. navigation → <nav>) continue to work as expected.

…#9245) The rule previously treated baseConcepts and relatedConcepts identically, causing incorrect suggestions like `<output>` for `role="status"`. Now it only flags roles that have direct semantic HTML equivalents (baseConcepts).

changeset-bot · 2026-03-03T14:25:16Z

🦋 Changeset detected

Latest commit: d145ca9

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

This PR includes changesets to release 13 packages

Name	Type
@biomejs/biome	Patch
@biomejs/cli-win32-x64	Patch
@biomejs/cli-win32-arm64	Patch
@biomejs/cli-darwin-x64	Patch
@biomejs/cli-darwin-arm64	Patch
@biomejs/cli-linux-x64	Patch
@biomejs/cli-linux-arm64	Patch
@biomejs/cli-linux-x64-musl	Patch
@biomejs/cli-linux-arm64-musl	Patch
@biomejs/wasm-web	Patch
@biomejs/wasm-bundler	Patch
@biomejs/wasm-nodejs	Patch
@biomejs/backend-jsonrpc	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

coderabbitai · 2026-03-03T14:27:51Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9c85cb06-b52d-47f8-9947-dbd4dc292850

📥 Commits

Reviewing files that changed from the base of the PR and between aeae6e6 and 4e9d06b.

📒 Files selected for processing (1)

crates/biome_js_analyze/src/lint/a11y/use_semantic_elements.rs

🚧 Files skipped from review as they are similar to previous changes (1)

crates/biome_js_analyze/src/lint/a11y/use_semantic_elements.rs

Walkthrough

This change updates the useSemanticElements lint rule to stop suggesting <output> for elements with roles status and alert. The rule now treats those roles as excluded from tag-replacement suggestions (they are relatedConcepts, not baseConcepts). Tests and examples were updated to show that role="status" does not produce a diagnostic. The change addresses issue #9245.

Possibly related PRs

#7129 — Modified the same use_semantic_elements rule to exclude ARIA roles (option, combobox, listbox) from tag suggestions.
#7348 — Also changed the use_semantic_elements lint rule; added early skips for components and custom elements affecting role-exclusion logic.

Suggested reviewers

ematipico
dyc3

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: restricting the useSemanticElements rule to only use baseConcepts instead of both baseConcepts and relatedConcepts.
Description check	✅ Passed	The description clearly explains the problem being fixed, the solution implemented, and includes test verification details related to the changeset.
Linked Issues check	✅ Passed	The PR successfully addresses issue `#9245` by restricting the rule to baseConcepts only, preventing incorrect suggestions of for role="status".
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing the useSemanticElements rule's handling of baseConcepts versus relatedConcepts, with no unrelated modifications present.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/valid.jsx`:
- Around line 46-69: The test block labelled “relatedConcepts-only” incorrectly
includes role="navigation" which should be tested as a baseConcept (navigation →
<nav>); remove the <div role="navigation"></div> from this valid JSX fragment
(the fragment containing the list of <div role="checkbox"> ... ) so the
navigation case remains covered by the baseConcept tests, or replace it with a
different relatedConcept-only role if you need to keep the same number of items.

ℹ️ Review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 753be72 and c41d4f1.

⛔ Files ignored due to path filters (4)

crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/invalid.jsx.snap is excluded by !**/*.snap and included by **
crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/invalid_self_closing.jsx.snap is excluded by !**/*.snap and included by **
crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/valid.jsx.snap is excluded by !**/*.snap and included by **
crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/valid_issue_6384.tsx.snap is excluded by !**/*.snap and included by **

📒 Files selected for processing (6)

.changeset/fix-use-semantic-elements-base-concepts.md
crates/biome_js_analyze/src/lint/a11y/use_semantic_elements.rs
crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/invalid.jsx
crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/invalid_self_closing.jsx
crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/valid.jsx
crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/valid_issue_6384.tsx

💤 Files with no reviewable changes (3)

crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/valid_issue_6384.tsx
crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/invalid.jsx
crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/invalid_self_closing.jsx

crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/valid.jsx

codspeed-hq · 2026-03-03T14:40:39Z

Merging this PR will not alter performance

✅ 58 untouched benchmarks
⏩ 156 skipped benchmarks¹

_{Comparing ruidosujeira:fix/9245-use-semantic-elements-status-role (d145ca9) with main (73205b9)}

156 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

dyc3 · 2026-03-04T20:15:39Z

crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/invalid.jsx

-    <div role="checkbox" ></div>
-    <div role="radio" ></div>
-    <div role="heading" ></div>
-    <div role="separator" ></div>


Ah see, these feel like they should be flagged by the rule.

We should align ourselves with the source rule's behavior: https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/main/src/rules/prefer-tag-over-role.js

@dyc3 Do you think the best approach would be to use both baseConcepts and relatedConcepts (aligning with the source rule), but add status to the exclusion list, similar to how combobox, listbox, and option are already excluded?

ruidosujeira · 2026-03-07T17:40:39Z

I’m currently reviewing the requested changes and comparing the current implementation against the source rule behavior to make sure we preserve the expected cases while fixing the incorrect suggestion. I’m still evaluating the best approach, but I’m actively working on it and will update the PR soon.

…ggestions

ruidosujeira · 2026-03-10T20:15:13Z

@dyc3 I added "status" and "alert" to an existing exclusion list in the code (along with combobox, listbox, and option).

dyc3

Losing these comments is not great. Also, include context for these new exclusions so we can remember why they are excluded.

…nticElements

ruidosujeira · 2026-03-10T22:16:40Z

Losing these comments is not great. Also, include context for these new exclusions so we can remember why they are excluded.

I've reverted to the previous code with the necessary comments and context; thank you for letting me know.

dyc3

I like it. Thank you!

github-actions bot added A-Linter Area: linter L-JavaScript Language: JavaScript and super languages labels Mar 3, 2026

chore: add changeset for biomejs#9245

c41d4f1

coderabbitai bot reviewed Mar 3, 2026

View reviewed changes

crates/biome_js_analyze/tests/specs/a11y/useSemanticElements/valid.jsx Outdated Show resolved Hide resolved

dyc3 requested changes Mar 4, 2026

View reviewed changes

Bruno Romano added 3 commits March 7, 2026 21:15

fix(a11y): exclude status and alert roles from useSemanticElements su…

aeae6e6

…ggestions

refactor(a11y): remove redundant comments from useSemanticElements

4e9d06b

fix: resolve merge conflicts with upstream/main for useSemanticElements

60c5b56

dyc3 requested changes Mar 10, 2026

View reviewed changes

fix(a11y): restore explanatory comments for excluded roles in useSema…

d145ca9

…nticElements

dyc3 approved these changes Mar 10, 2026

View reviewed changes

dyc3 merged commit 78c4e9b into biomejs:main Mar 10, 2026
18 checks passed

github-actions bot mentioned this pull request Mar 10, 2026

ci: release #9346

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(a11y): only use baseConcepts in useSemanticElements rule (#9245)#9311

fix(a11y): only use baseConcepts in useSemanticElements rule (#9245)#9311
dyc3 merged 6 commits intobiomejs:mainfrom
ruidosujeira:fix/9245-use-semantic-elements-status-role

ruidosujeira commented Mar 3, 2026

Uh oh!

changeset-bot bot commented Mar 3, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Mar 3, 2026 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

codspeed-hq bot commented Mar 3, 2026 •

edited

Loading

Uh oh!

dyc3 Mar 4, 2026

Uh oh!

ruidosujeira Mar 5, 2026

Uh oh!

ruidosujeira commented Mar 7, 2026

Uh oh!

ruidosujeira commented Mar 10, 2026

Uh oh!

dyc3 left a comment

Uh oh!

ruidosujeira commented Mar 10, 2026

Uh oh!

dyc3 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ruidosujeira commented Mar 3, 2026

Summary

Test Plan

Uh oh!

changeset-bot bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Possibly related PRs

Suggested reviewers

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codspeed-hq bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

dyc3 Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

ruidosujeira Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

ruidosujeira commented Mar 7, 2026

Uh oh!

ruidosujeira commented Mar 10, 2026

Uh oh!

dyc3 left a comment

Choose a reason for hiding this comment

Uh oh!

ruidosujeira commented Mar 10, 2026

Uh oh!

dyc3 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot bot commented Mar 3, 2026 •

edited

Loading

coderabbitai bot commented Mar 3, 2026 •

edited

Loading

codspeed-hq bot commented Mar 3, 2026 •

edited

Loading