Skip to content

Guidelines: Add data-slug attribute to settings list items#78676

Open
aagam-shah wants to merge 3 commits into
WordPress:trunkfrom
aagam-shah:add/guidelines-data-slug-attribute
Open

Guidelines: Add data-slug attribute to settings list items#78676
aagam-shah wants to merge 3 commits into
WordPress:trunkfrom
aagam-shah:add/guidelines-data-slug-attribute

Conversation

@aagam-shah
Copy link
Copy Markdown
Contributor

@aagam-shah aagam-shah commented May 26, 2026

What?

Adds a data-slug attribute to each guideline section <li> in the Guidelines settings page list (routes/guidelines/stage.tsx).

Why?

The guideline section list items currently expose no stable way to identify an individual section from the markup:

  • The content-guidelines__* class names were renamed to guidelines__*.
  • The accordion was refactored to CollapsibleCard, whose header/trigger uses hashed CSS-module class names (e.g. _0625b55e82a0d93d__header-trigger) that change per build.
  • The per-section element id (previously guidelines-${slug}) was removed in that refactor.

As a result there is no resilient selector for targeting a specific guideline section, which makes it hard for external code, extensions, automation, and e2e tests to reliably locate one. A data-slug attribute is stable across styling/markup refactors and matches the convention WordPress core already uses to identify list items in wp-admin (e.g. theme cards in the theme browser carry data-slug).

How?

Adds data-slug={ item.slug } to the list-item rendered from GUIDELINE_ITEMS in stage.tsx. The slug values are the existing section identifiers (site, copy, images, blocks, additional).

Testing Instructions

  1. Enable the gutenberg-guidelines experiment.
  2. Go to Settings → Guidelines.
  3. Inspect the section list. Each <li class="guidelines__list-item"> now carries data-slug="<slug>".

There is no visual change.

Screenshots or screencast

N/A — markup-only change, no visual impact.

Expose a stable per-section hook on the Guidelines settings list so an
individual section can be targeted reliably by extensions, automation,
and tests.

The accordion refactor to CollapsibleCard (hashed CSS-module class
names) and the content-guidelines -> guidelines rename left the section
list items without any stable selector or element id. A `data-slug`
attribute is resilient to styling/markup refactors and matches the
convention WordPress core already uses to identify list items in
wp-admin (e.g. theme cards carry `data-slug`).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aagam-shah aagam-shah force-pushed the add/guidelines-data-slug-attribute branch from a828100 to 8814f77 Compare May 26, 2026 10:30
@aagam-shah aagam-shah changed the title Guidelines: Add data-guideline-slug attribute to settings list items Guidelines: Add data-slug attribute to settings list items May 26, 2026
@aagam-shah aagam-shah marked this pull request as ready for review May 26, 2026 10:50
Copy link
Copy Markdown
Contributor

@aswasif007 aswasif007 left a comment

Choose a reason for hiding this comment

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

🎉

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 26, 2026

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: aagam-shah <aagam94@git.wordpress.org>
Co-authored-by: aswasif007 <aswasif007@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@t-hamano
Copy link
Copy Markdown
Contributor

I'm not blocking this PR, but we need to use the accessible selector in our e2e testing. The need for the data-slug attribute suggests that the Guideline page itself might not be accessible.

What problems are you currently experiencing?

@t-hamano t-hamano added [Type] Code Quality Issues or PRs that relate to code quality [Feature] Guidelines An experimental feature for adding site-wide editorial rules. labels May 26, 2026
@aagam-shah
Copy link
Copy Markdown
Contributor Author

Thanks @t-hamano - agreed, e2e tests should use accessible selectors, and this isn't for that.

This is really about restoring compatibility. Each section used to have a stable per-section id (guidelines-${slug}), but it was dropped in the CollapsibleCard refactor. That left no stable way for code that adds UI to this page at runtime to tell the sections apart - the titles are translated, and the CollapsibleCard class names are hashed and change per build. data-slug just brings that stable hook back, using the slug the page already uses internally.

The page itself is accessible (each section has an <h2> heading) - this is only about restoring a stable key.

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

Labels

[Feature] Guidelines An experimental feature for adding site-wide editorial rules. [Type] Code Quality Issues or PRs that relate to code quality

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants