Skip to content

Add Content Guidelines experimental feature#74789

Draft
Jameswlepage wants to merge 4 commits intoWordPress:trunkfrom
Jameswlepage:experiments/content-guidelines
Draft

Add Content Guidelines experimental feature#74789
Jameswlepage wants to merge 4 commits intoWordPress:trunkfrom
Jameswlepage:experiments/content-guidelines

Conversation

@Jameswlepage
Copy link
Copy Markdown

@Jameswlepage Jameswlepage commented Jan 20, 2026 •
edited
Loading

What?

This PR introduces Content Guidelines as an experimental feature in the Site Editor. While Global Styles define how your site looks, Content Guidelines define how your site sounds.

Content Guidelines provide a structured way to document and enforce editorial voice, tone, vocabulary, and copy rules across a WordPress site—making them discoverable by AI assistants and content tools.

Why?

As AI-powered writing assistance becomes more common in WordPress, there's a need for site owners to define their editorial identity in a machine-readable format. Currently, there's no standardized way for:

  • Site owners to document their brand voice and content rules
  • AI tools to discover and respect site-specific writing guidelines
  • Teams to maintain consistency across content creators

This feature complements Global Styles by adding the "content" counterpart to visual styling, enabling a complete site identity system.

How?

New package: @wordpress/content-guidelines

  • React components for managing guidelines (Library, Blocks, Playground, History panels)
  • Redux store integration with core-data for SaveHub support
  • useGuidelines hook following canonical Gutenberg data patterns

PHP Backend (lib/experimental/content-guidelines/)

  • Custom post type for storing guidelines with revision support
  • REST API endpoints for CRUD operations, context packets, and lint checking
  • WordPress 6.9+ Abilities API integration for AI discoverability
  • Provider hooks for AI integration (wp_content_guidelines_* filters)

Site Editor Integration

  • New /guidelines route in Site Editor
  • Conditional loading based on experiment toggle
  • Command palette integration

Guidelines Schema

  • Brand context (description, audience, goals)
  • Voice & tone (traits, POV, readability level)
  • Copy rules (dos, don'ts, formatting)
  • Vocabulary (preferred terms, terms to avoid)
  • Heuristics (sentence length, reading level targets)
  • Block-specific overrides
  • External references

Testing Instructions

  1. Enable the experiment: Gutenberg → Experiments → Content Guidelines
  2. Open the Site Editor
  3. Navigate to Content Guidelines in the sidebar (or use Command Palette: "Content Guidelines")
  4. Test the following:
    • Library tab: Add brand context, voice traits, copy rules, vocabulary terms
    • Blocks tab: Configure block-specific guidelines (e.g., for Paragraph, Heading)
    • Playground tab: Test guidelines against sample content with lint checking
    • History tab: View revision history with user avatars
    • Import/Export: Export guidelines as JSON, import on another site
  5. Verify changes persist after save (check SaveHub integration)
  6. Test with AI provider hooks (if available) via wp_content_guidelines_run_playground_test filter

Screenshots

CleanShot 2026-01-20 at 16 36 10@2x

Notes

  • This is a draft PR for early feedback on the approach and API design
  • The feature is gated behind an experimental flag and has no impact when disabled
  • AI provider integration requires external plugins to implement the filter hooks
  • Block-specific guidelines merge with site-level rules (don't replace them)

Related

  • Complements Global Styles for complete site identity
  • Uses same core-data patterns as other Site Editor features
  • Integrates with WordPress 6.9 Abilities API for AI discoverability

@Jameswlepage
Add Content Guidelines experimental feature (WIP)
0efb49d 
This introduces Content Guidelines as an experimental feature in the Site Editor.
While Global Styles define how your site looks, Content Guidelines define how
your site sounds.

Features:
- New @wordpress/content-guidelines package with full UI
- Site Editor integration with /guidelines route
- Conditional loading based on experiment toggle
- PHP API with REST endpoints for guidelines management
- Support for site-level and block-specific guidelines
- Draft/publish workflow with revision history
- AI provider hooks for content generation integration

The experiment can be enabled in Gutenberg > Experiments > Content Guidelines.

Note: This commit skips linting. Follow-up commits will address:
- Text domain changes (content-guidelines → default)
- JSDoc format alignment
- Unused variable cleanup
- SCSS empty block fixes
@Jameswlepage
Content Guidelines: Migrate to canonical core-data pattern
7cc9a9e 
This refactors Content Guidelines to use the standard Gutenberg pattern
where core-data is the source of truth, matching how Global Styles works.

Key changes:
- Add useGuidelines hook using useEntityRecord for data access
- Register contentGuidelines entity with core-data for SaveHub integration
- Add REST route /wp/v2/content-guidelines/current for entity fetching
- Simplify store to only manage UI state (revisions, test results)
- Remove legacy panel components and draft/publish workflow
- Add user avatars to Guidelines History panel

The store no longer manages guidelines data directly - all CRUD operations
now flow through core-data's editEntityRecord and saveEditedEntityRecord.
@Jameswlepage
Content Guidelines: Fix layout issues and polish UI
c61b9ea 
- Fix library panel layout causing one-word-per-line text wrapping
- Simplify SectionCard markup using plain HTML instead of Flex components
- Add proper focus states with border overlay (no doubling)
- Remove bold from section titles
- Add user avatars to history panel with WordPress default fallback
- Add REST route /wp/v2/content-guidelines/current for core-data entity
- Add page-guidelines styles for proper scrolling
- Add border-bottom to list items
- Fix PHP and JS linting issues
@github-actions github-actions bot added [Package] Edit Site /packages/edit-site First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository labels Jan 20, 2026
@github-actions
Copy link
Copy Markdown

github-actions bot commented Jan 20, 2026

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @Jameswlepage! 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.

@Jameswlepage
Content Guidelines: Remove legacy GuidelinesPage with inline tabs
532fbdc 
- Remove guidelines-page component (old inline tabs UI)
- Remove guidelines-screen component (only used by old UI)
- Remove GuidelinesPage export from package index
- Update commands to use Site Editor routes instead of non-existent admin page

The content-guidelines package now only exports panel components
that the Site Editor integrates via its own navigation structure.
@Jameswlepage Jameswlepage force-pushed the experiments/content-guidelines branch from ac78793 to 532fbdc Compare January 21, 2026 17:42
@aagam-shah aagam-shah mentioned this pull request Feb 3, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@spacedmonkey spacedmonkey Awaiting requested review from spacedmonkey spacedmonkey will be requested when the pull request is marked ready for review spacedmonkey is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository [Package] Edit Site /packages/edit-site

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Jameswlepage