Content Guidelines: Add UX for site, copy, image, and additional guidelines by aswasif007 · Pull Request #75420 · WordPress/gutenberg

aswasif007 · 2026-02-11T13:26:29Z

What?

Related issue: #75260

This PR introduces a new Content Guidelines admin page that allows site administrators to define content standards for their site. The page is accessible via Settings > Content Guidelines in wp-admin and provides a structured interface for setting guidelines across four categories: Site, Copy, Images, and Additional guidelines.

Why?

This feature enables site administrators to establish and maintain content standards that can guide content creators, inform plugins, and help AI tools generate content that matches the site's voice and requirements. By providing a centralized location for content guidelines, teams can ensure consistency across all content creation workflows.

How?

This PR adds:

New Admin Page Route: Created routes/content-guidelines/ with a React-based admin page route that integrates with wp-admin
PHP Integration: Added lib/experimental/content-guidelines/load.php to register the admin submenu page under Settings
UI Components:
- GuidelineItemCard: Displays guideline categories as clickable cards in the list view
- GuidelineItemEdit: Form component for editing individual guideline categories with TextareaControl
Navigation: Uses WordPress Navigator component for seamless navigation between list and edit views
Four Guideline Categories:
- Site: Purpose, goals, and primary audience
- Copy: Writing standards for tone, voice, style, and formatting
- Images: Style, dimensions, formats, mood and aesthetic preferences
- Additional guidelines: SEO preferences, legal requirements, citation styles, etc.
Accessibility: Proper ARIA labels, semantic HTML, keyboard navigation support, and screen reader friendly attributes
Styling: Custom SCSS following Figma design tokens for consistent UI

The page follows the same wp-admin integrated pattern as other admin pages like Font Library, maintaining the WordPress admin sidebar.

Note: This is an experimental feature (located in lib/experimental/). The save functionality for guidelines is not yet implemented - this PR focuses on establishing the UI structure and navigation flow.

Testing Instructions

Navigate to Settings > Content Guidelines in wp-admin
Verify the list view displays all four guideline categories (Site, Copy, Images, Additional guidelines)
Verify each card displays an icon, title, and description
Click on any category card (e.g., "Site") to navigate to the edit view
Verify the edit view displays:
- A back button in the header
- The category title
- A description explaining what the category is for
- A textarea control for entering guidelines
- A "Save guidelines" button
Click the back button to return to the list view
Repeat steps 4-6 for all four categories
Verify the page maintains the WordPress admin sidebar and styling

Testing Instructions for Keyboard

Navigate to Settings > Content Guidelines using keyboard navigation (Tab key)
Use Tab to navigate through the guideline category cards
Press Enter or Space on a category card to navigate to its edit view
Verify focus is visible on all interactive elements (cards, back button, textarea, save button)
Use Tab to navigate through the edit form elements:
- Back button
- Textarea control
- Save button
Press Enter on the back button to return to the list view
Verify screen reader announcements are clear and descriptive (test with NVDA/JAWS/VoiceOver)
Verify all interactive elements are reachable via keyboard only

Screenshots

github-actions · 2026-02-11T13:27:17Z

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @aswasif007! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

mirka

Just left some high level notes for components usage. Markup itself seems pretty solid 👍

routes/content-guidelines/components/guideline-item-card.tsx

routes/content-guidelines/components/guideline-item-edit.scss

github-actions · 2026-02-27T09:57:48Z

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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @aswasif007, @iamchughmayank.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

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

Unlinked contributors: aswasif007, iamchughmayank.

Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: andrewserong <andrewserong@git.wordpress.org>
Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>
Co-authored-by: aagam-shah <aagam94@git.wordpress.org>
Co-authored-by: saroshaga <saroshaga@git.wordpress.org>
Co-authored-by: fditrapani <fditrapani@git.wordpress.org>

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

andrewserong

This is generally looking pretty good as a starting point to me!

Looks like the PR could use a rebase as it's currently got some failing checks.

I see the implementation here uses an accordion instead of separate views. What's the reason behind the design shift (not a blocker as I'm sure the UI can evolve over time). To me it can look a bit repetitive when multiple accordions are open, and I found navigate between and expanding / collapsing the accordions a bit fiddly since you have to click on the button itself rather than the heading.

I was also wondering if there's an opportunity to re-use DataForm / Card components, etc, for consistency, too.

In terms of code organisation, it could be a good time to add a types.ts file, and at some point I imagine the store.ts file could be split up into separate files for selector / reducer, etc, if and when more methods etc are added.

Was there any particular feedback you were looking for at this stage? Does this need a design review, or were you planning to land this in the short-term and continue iterating on the design in follow-ups?

routes/content-guidelines/stage.tsx

routes/content-guidelines/store.ts

routes/content-guidelines/api.ts

routes/content-guidelines/components/guideline-accordion-form.tsx

routes/content-guidelines/components/guideline-accordion.tsx

andrewserong · 2026-03-03T01:10:38Z

@aagam-shah and @saroshaga, I know you're both keen on this feature — did you have any thoughts / concerns with the approach here? Overall it's looking like a pretty good start to me, just flagged a few code quality ideas, and looks like the PR will need a rebase.

Were there any designers y'all have been working with who can give this a once over, too?

aswasif007 · 2026-03-03T01:14:52Z

Thanks you @andrewserong!

What's the reason behind the design shift

I think we wanted to simplify the design. Previously we had multiple screens, but here we are combining them and using accordions.

I was also wondering if there's an opportunity to re-use DataForm / Card components, etc, for consistency, too.

We are using Card component on the accordion. I'll see if I can replace the form with DataForm. Thanks for pointing it out!

In terms of code organisation, it could be a good time to add a types.ts file

👍

Was there any particular feedback you were looking for at this stage?

I was looking for general feedback because this is a foundational PR for the Content Guideline UX, and also my first PR on this repository! Thanks for the reviews!

andrewserong · 2026-03-03T01:57:51Z

I was looking for general feedback because this is a foundational PR for the Content Guideline UX, and also my first PR on this repository! Thanks for the reviews!

Sounds great. I think because it's behind an experiment we can comfortably land this in whatever shape you and @aagam-shah and others feel comfortable with and that helps you to continue iterating on the feature.

Let me know once this has had a rebase and you're happy with the overall shape, and I can give it another 👀 and ✅ !

(Also as always, if any of the feedback feels too rabbit-holey, please call that out — I certainly don't want to derail any progress with my comments!)

andrewserong · 2026-03-03T02:02:21Z

We are using Card component on the accordion. I'll see if I can replace the form with DataForm. Thanks for pointing it out!

Oh, sorry, I meant the card layout of DataForm 😄 . There's an example here in case it helps:

https://wordpress.github.io/gutenberg/?path=/story/dataviews-dataform--layout-card

The code for that example lives here:

gutenberg/packages/dataviews/src/dataform/stories/layout-card.tsx

Line 16 in b0634ee

const LayoutCardComponent = ( {

And this is timely, looks like there's a dev doc blog post on using that kind of approach here, too:

https://developer.wordpress.org/news/2026/01/how-to-use-dataform-to-create-plugin-settings-pages/

aswasif007 · 2026-03-03T04:25:42Z

I can't seem to reproduce the exact result using the data-form though. Particularly there is no way to place the subtitle below the title like this:

I can place it on the right side of the title, but that doesn't go with the design.

ramonjd · 2026-03-03T05:59:58Z

routes/content-guidelines/components/guideline-accordion-form.tsx

+	const handleSave = ( event: FormEvent< HTMLFormElement > ) => {
+		event.preventDefault();
+		setGuideline( slug, draft );
+		saveContentGuidelines();
+	};


Just thinking about form validation, maybe it's too early but I'll add some notes anyway 😄 Nothing blocking here. There should be probably be a design review at a later state.

what is considered "valid" content for guidelines? are there any best practices a user needs to know, e.g., structure, no HTML, no line breaks, for real-time validation? at the very least I guess the forms should check for empty values before allowing submission

a later task might be to include a helpful tips section for the above

i'd be interested to hear from design folks, but maybe validation could be centralized via a single save button. that might also mitigate multiple, simultaneous submissions given there are 4 x submit buttons

what is considered "valid" content for guidelines?

for now, only text. but I'd wait a bit before putting guardrails/validations here.

andrewserong · 2026-03-03T06:01:40Z

Ah, fair enough! It might be better to use an ad hoc approach in the short-term, then. You could always still use DataForm for the body of the accordion if that suits your needs?

I can place it on the right side of the title, but that doesn't go with the design.

If you think it'll be a common use case for the DataForm card layout, it could be worth opening an issue to propose adding an optional description/sub-title or other approach?

For now, though, sounds like going with Card itself is expedient 👍

routes/content-guidelines/components/guideline-accordion.tsx

routes/content-guidelines/package.json

routes/content-guidelines/components/guideline-accordion.scss

aagam-shah · 2026-03-03T07:07:32Z

Thanks for the review @andrewserong! I've gone through the PR and left some additional inline feedback.

On the design side — good call on flagging the need for a design review. @fditrapani has been working with us on this. I think getting a design review from them before merge would be good, especially to align on component patterns (accordion vs DataForm card layout vs the Item pattern from connectors-home).

On the data layer — the PR currently uses a custom Redux store and hand-rolled apiFetch calls. Since content guidelines is backed by a CPT with a REST controller, I was wondering if we should look into using @wordpress/core-data instead, similar to how Global Styles handles its singleton CPT? That would give us dirty tracking, isResolving/hasResolved states, and revision support for free. What do you think? Either way, this can be tackled separately and isn't a blocker for this PR.

routes/content-guidelines/components/guideline-accordion-form.tsx

routes/content-guidelines/api.ts

aagam-shah

Thanks for working on this 🎉 ! Also verified the responsiveness and it looks good

saroshaga

There are a couple of non-blocking things to discuss and follow-up on, but it looks good to go. Thank you for working on this, and for addressing the feedback @aswasif007 ❤️

andrewserong

This is testing well for me, too!

Thanks for all the back-and-forth @aswasif007, this feels like a good basis for the feature to me, too.

Since the card layout in DataForm didn't quite work out for you, it could be worth opening a follow-up issue to capture the limitations you ran into, and how you expected it to work / which features felt missing surrounding descriptions, etc.

But this LGTM! 🚀

github-actions · 2026-03-05T07:09:28Z

Congratulations on your first merged pull request, @aswasif007! We'd like to credit you for your contribution in the post announcing the next WordPress release, but we can't find a WordPress.org profile associated with your GitHub account. When you have a moment, visit the following URL and click "link your GitHub account" under "GitHub Username" to link your accounts:

https://profiles.wordpress.org/me/profile/edit/

And if you don't have a WordPress.org account, you can create one on this page:

https://login.wordpress.org/register

Kudos!

ramonjd · 2026-03-05T07:45:18Z

Great work, all!

…ines (#75420) * Add ux components for content guidelines * Integrate api and store with content-guidelines * Display snackbar for success/error * Rename additional guideline -> internal * Update behaviour so that each guideline can be saved separately * Refactor to separate form from accordion * Update package-lock.json * Refactor to not have to clone react element * Update spacing * Improve error handling * Manage ts types and interfaces with types.ts * Use DataForm instead of TextAreaControl * Improve css * Remove unwanted dep * Stop propagation on chevron click * Rename css * Update draft when value changes * Rename internal to additional * Clear error if user retries and succeeds * Improve accordion accessibility * Do not disable save when textarea is empty * Eliminate redundant logic Unlinked contributors: aswasif007, iamchughmayank. Co-authored-by: mirka <0mirka00@git.wordpress.org> Co-authored-by: andrewserong <andrewserong@git.wordpress.org> Co-authored-by: ramonjd <ramonopoly@git.wordpress.org> Co-authored-by: aagam-shah <aagam94@git.wordpress.org> Co-authored-by: saroshaga <saroshaga@git.wordpress.org> Co-authored-by: fditrapani <fditrapani@git.wordpress.org>

scruffian · 2026-03-11T10:45:40Z

I just cherry-picked this PR to the release/22.7 branch to get it included in the next release: 6c8572e

github-actions bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Feb 11, 2026

iamchughmayank mentioned this pull request Feb 11, 2026

Content Guidelines: Add Import, Export and Restore from revision history actions #75434

Closed

mirka reviewed Feb 12, 2026

View reviewed changes

routes/content-guidelines/components/guideline-item-card.tsx Outdated Show resolved Hide resolved

routes/content-guidelines/components/guideline-item-edit.scss Outdated Show resolved Hide resolved

aswasif007 force-pushed the add/content-guidelines branch from e153a01 to 11a4cc7 Compare February 16, 2026 03:08

aswasif007 force-pushed the add/content-guidelines branch from 11a4cc7 to 51dd71c Compare February 27, 2026 09:56

aswasif007 marked this pull request as ready for review February 27, 2026 09:57

aswasif007 requested a review from spacedmonkey as a code owner February 27, 2026 09:57

aswasif007 changed the title ~~Content Guidelines: Add UX components for site, copy, image, and additional guidelines~~ Mar 2, 2026

aswasif007 changed the title ~~Content Guidelines: Add UX for site, copy, image, and additional guidelines~~ Mar 2, 2026

bph added [Feature] Guidelines An experimental feature for adding site-wide editorial rules. [Type] Enhancement A suggestion for improvement. [Type] Experimental Experimental feature or API. labels Mar 2, 2026

andrewserong reviewed Mar 3, 2026

View reviewed changes

routes/content-guidelines/components/guideline-accordion.tsx Outdated Show resolved Hide resolved

aswasif007 force-pushed the add/content-guidelines branch from 1081558 to 65bc7c4 Compare March 3, 2026 01:59

ramonjd reviewed Mar 3, 2026

View reviewed changes

aagam-shah reviewed Mar 3, 2026

View reviewed changes

routes/content-guidelines/components/guideline-accordion.tsx Show resolved Hide resolved

aagam-shah reviewed Mar 3, 2026

View reviewed changes

routes/content-guidelines/package.json Outdated Show resolved Hide resolved

aagam-shah reviewed Mar 3, 2026

View reviewed changes

routes/content-guidelines/components/guideline-accordion.scss Outdated Show resolved Hide resolved

iamchughmayank reviewed Mar 3, 2026

View reviewed changes

routes/content-guidelines/components/guideline-accordion-form.tsx Outdated Show resolved Hide resolved

iamchughmayank reviewed Mar 3, 2026

View reviewed changes

routes/content-guidelines/api.ts Show resolved Hide resolved

aswasif007 added 5 commits March 5, 2026 05:37

Stop propagation on chevron click

3a2065b

Rename css

17ff1b4

Update draft when value changes

17932a6

Rename internal to additional

c386d92

Clear error if user retries and succeeds

c45aa2b

aswasif007 force-pushed the add/content-guidelines branch from 3f0df29 to c45aa2b Compare March 4, 2026 23:37

Improve accordion accessibility

c9de462

aswasif007 force-pushed the add/content-guidelines branch from 493fb5e to c9de462 Compare March 5, 2026 00:12

aswasif007 requested a review from saroshaga March 5, 2026 00:17

Do not disable save when textarea is empty

b045b3d

ramonjd reviewed Mar 5, 2026

View reviewed changes

routes/content-guidelines/api.ts Outdated Show resolved Hide resolved

ramonjd reviewed Mar 5, 2026

View reviewed changes

routes/content-guidelines/api.ts Outdated Show resolved Hide resolved

Eliminate redundant logic

0a84312

aswasif007 requested a review from ramonjd March 5, 2026 06:10

aagam-shah approved these changes Mar 5, 2026

View reviewed changes

saroshaga approved these changes Mar 5, 2026

View reviewed changes

andrewserong approved these changes Mar 5, 2026

View reviewed changes

andrewserong enabled auto-merge (squash) March 5, 2026 06:38

andrewserong merged commit fed23a3 into WordPress:trunk Mar 5, 2026
42 checks passed

github-actions bot added this to the Gutenberg 22.8 milestone Mar 5, 2026

iamchughmayank mentioned this pull request Mar 5, 2026

Guidelines: Add actions for Import, Export and Revisions of guidelines #76155

Merged

aswasif007 changed the title ~~Content Guidelines: Add UX for site, copy, image, and internal guidelines~~ Mar 6, 2026

ramonjd mentioned this pull request Mar 9, 2026

Content Guidelines: Add block guidelines management #76187

Merged

andrewserong added the Backport to Gutenberg RC Pull request that needs to be backported to a Gutenberg release candidate (RC) label Mar 11, 2026

scruffian removed the Backport to Gutenberg RC Pull request that needs to be backported to a Gutenberg release candidate (RC) label Mar 11, 2026

andrewserong mentioned this pull request Mar 13, 2026

Content Guidelines: UI/UX Design Discussion #75260

Closed

Conversation

aswasif007 commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Testing Instructions for Keyboard

Screenshots

github-actions bot commented Feb 11, 2026

mirka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unlinked Accounts

andrewserong left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

andrewserong commented Mar 3, 2026

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

Uh oh!

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

Uh oh!

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

Uh oh!

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

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

aswasif007 Mar 4, 2026

Choose a reason for hiding this comment

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aagam-shah commented Mar 3, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aagam-shah left a comment

Choose a reason for hiding this comment

saroshaga left a comment

Choose a reason for hiding this comment

andrewserong left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 5, 2026

ramonjd commented Mar 5, 2026

scruffian commented Mar 11, 2026

Labels

10 participants

aswasif007 commented Feb 11, 2026 •

edited

Loading

github-actions bot commented Feb 27, 2026 •

edited

Loading

aswasif007 commented Mar 3, 2026 •

edited

Loading

andrewserong commented Mar 3, 2026 •

edited

Loading

andrewserong commented Mar 3, 2026 •

edited

Loading

aswasif007 commented Mar 3, 2026 •

edited

Loading

ramonjd Mar 3, 2026 •

edited

Loading

andrewserong commented Mar 3, 2026 •

edited

Loading