Skip to content

feat(documentation): add accessibility reference relationship stories and demo components #6123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
myrta2302 wants to merge 37 commits into
base: main
Choose a base branch
from
Open

feat(documentation): add accessibility reference relationship stories and demo components #6123

myrta2302 wants to merge 37 commits into from

Conversation

@myrta2302
Copy link
Contributor

@myrta2302 myrta2302 commented Aug 29, 2025 •
edited
Loading

📄 Description

This PR adds documentation for the following cross-component referencing scenarios under the (private) Accessibility section:

  1. for / label
  2. aria-labelledby
  3. aria-describedby
  4. role="list"

To support these examples, a new demo-components folder has been added under documentation/src, containing the following native web components:

  • demo-button
  • demo-label
  • demo-list-item-group
  • demo-list-item
  • demo-list
  • demo-span
  • demo-target

📝 Checklist

  • ✅ My code follows the style guidelines of this project
  • 🛠️ I have performed a self-review of my own code
  • 📄 I have made corresponding changes to the documentation
  • ⚠️ My changes generate no new warnings or errors
  • ✔️ New and existing unit tests pass locally with my changes

@changeset-bot
Copy link

changeset-bot bot commented Aug 29, 2025 •
edited
Loading

⚠️ No Changeset found

Latest commit: 4ad0d57

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

@swisspost-bot
Copy link
Contributor

swisspost-bot commented Aug 29, 2025 •
edited
Loading

Related Previews

@myrta2302 myrta2302 changed the title feat(documentation): add accessibility 'for-label' story and demo target component feat(documentation): add accessibility reference relationship stories and demo components Sep 9, 2025
@myrta2302 myrta2302 marked this pull request as ready for review September 9, 2025 09:29
@myrta2302 myrta2302 requested review from a team as code owners September 9, 2025 09:29
@myrta2302 myrta2302 linked an issue Sep 12, 2025 that may be closed by this pull request
Investigate and Document Cross-Component DOM Referencing #5300
Open
3 tasks
@sonarqubecloud
Copy link

sonarqubecloud bot commented Sep 24, 2025

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

oliverschuerch
oliverschuerch requested changes Oct 30, 2025
View reviewed changes
Copy link
Contributor

@oliverschuerch oliverschuerch left a comment

Choose a reason for hiding this comment

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

The preview URL is not working.

@myrta2302
Copy link
Contributor Author

myrta2302 commented Nov 5, 2025

The preview URL is not working.

I merged the conflicts to main and it is working now.

oliverschuerch
oliverschuerch requested changes Nov 6, 2025
View reviewed changes
Copy link
Contributor

@oliverschuerch oliverschuerch left a comment

Choose a reason for hiding this comment

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

Currently, the guidelines are always visible, no matther which mode the docs are rendered in (development | production).
Shouldn't we hide the guidelines in production mode, or is the content also relevant for our users?

The docs pages aria-describedby and aria-labelledby are almost the same (compared by page structur and content).
Please update the CRs requested for one also on the other.

During the review, I asked my self if the examples are just to specific? At least it's a lot of repeating information on all of the example pages.

I think it could be beneficial to add a page with general information about, how different HTML attributes or JS properties can cross the DOM borders or not. And then additionally only document exceptions.

e.g.

  • light -> light ✔️
  • light -> shadow ❌
  • shadow -> light ❌
  • shadow -> slotted ❌
  • shadow A -> shadow A ✔️
  • shadow B -> shadow B ❌
  • ...

if we'd do that and add examples, most of the content of the other pages could become obsolete.

Since you've already put a lot of effort into it, I'll leave it up to you if you want to do that, ask the team about it or completely ignore this idea.

@myrta2302
Copy link
Contributor Author

myrta2302 commented Nov 18, 2025 •
edited
Loading

Currently, the guidelines are always visible, no matther which mode the docs are rendered in (development | production). Shouldn't we hide the guidelines in production mode, or is the content also relevant for our users?

The docs pages aria-describedby and aria-labelledby are almost the same (compared by page structur and content). Please update the CRs requested for one also on the other.

During the review, I asked my self if the examples are just to specific? At least it's a lot of repeating information on all of the example pages.

I think it could be beneficial to add a page with general information about, how different HTML attributes or JS properties can cross the DOM borders or not. And then additionally only document exceptions.

e.g.

  • light -> light ✔️
  • light -> shadow ❌
  • shadow -> light ❌
  • shadow -> slotted ❌
  • shadow A -> shadow A ✔️
  • shadow B -> shadow B ❌
  • ...

if we'd do that and add examples, most of the content of the other pages could become obsolete.

Since you've already put a lot of effort into it, I'll leave it up to you if you want to do that, ask the team about it or completely ignore this idea.

Currently, the guidelines are always visible

It is because of the current Storybook bug #6631. Raw components are also visible right now.

The docs pages aria-describedby and aria-labelledby are almost the same

I would prefer to keep both pages.

I asked my self if the examples are just to specific

Specific examples was exactly my intention for a quick reference for every case. I personally benefit from some "stupid" examples too.

a page with general information

That is i would say what the table reference for. Do you think it needs more text?

oliverschuerch
oliverschuerch requested changes Nov 21, 2025
View reviewed changes
myrta2302 and others added 5 commits December 3, 2025 07:10
@myrta2302 @oliverschuerch
Update packages/documentation/src/stories/accessibility-practices/fou…
3ab6008 
…ndational-structure-and-semantics/reference-crossing-the-shadowdom/aria-role-list/examples/working-example-II.sample.html

Co-authored-by: Oliver Schürch <oliver.schuerch@post.ch>
@myrta2302
Merge branch 'main' into add-for-label-stories-in-the-accessibility-s…
6d9cdf6 
…ection
@myrta2302
review comments update
bc4e88c
@myrta2302
lint error
3b4fdc3
@myrta2302
fix lint error
4ad0d57
@sonarqubecloud
Copy link

sonarqubecloud bot commented Dec 3, 2025

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

@myrta2302
Copy link
Contributor Author

myrta2302 commented Dec 4, 2025

To be merged when the storybook navigation issue (that causes the hidden sections to be public) is resolved.

@myrta2302 myrta2302 added the on hold Wait for something to be done, before continue working on this Issue label Dec 4, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@oliverschuerch oliverschuerch oliverschuerch approved these changes

Assignees

No one assigned

Labels

on hold Wait for something to be done, before continue working on this Issue

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Investigate and Document Cross-Component DOM Referencing

4 participants

@myrta2302 @swisspost-bot @oliverschuerch