Skip to content

Try: Content Guidelines with AI-powered suggestions#76680

Draft
fditrapani wants to merge 55 commits intoWordPress:trunkfrom
fditrapani:try/content-guidelines-ai
Draft

Try: Content Guidelines with AI-powered suggestions#76680
fditrapani wants to merge 55 commits intoWordPress:trunkfrom
fditrapani:try/content-guidelines-ai

Conversation

@fditrapani
Copy link
Copy Markdown

@fditrapani fditrapani commented Mar 19, 2026

Summary

This branch adds AI-powered suggestion explorations to the Content Guidelines feature. Content Guidelines lets site owners define content standards (site purpose, copy tone, image style, per-block rules) that inform plugins and AI tools.

This PR explores three different UX approaches for how AI could help users create and improve their guidelines:

Option A — Baseline (Current)

The default Content Guidelines page. Each section (Site, Copy, Images, Blocks, Additional) has its own accordion with a text area. No AI features — manual entry only.

Option B — Suggest All

  • A top-level "Improve guidelines" button triggers AI suggestions for all sections at once
  • Suggestions appear as word-level diffs (powered by diffWords) with Accept/Dismiss buttons
  • Block-level guidelines get inline generation with shimmer animation and diff review in a modal
  • An empty-state banner encourages new users to generate their first set of guidelines
  • Staggered block generation with 800ms delays between each block

Option C — Proactive Recommendations

  • Auto-scans on page load and surfaces recommendations in a sticky right sidebar panel
  • Clicking a sidebar recommendation opens and scrolls to the relevant accordion
  • Same Accept/Dismiss diff flow as Option B, but initiated proactively
  • Sidebar items appear immediately as suggestions become available
  • "Dismiss all" button appears after all suggestions are ready
  • Works on empty guidelines too — generates initial content proactively

Switching between explorations

An admin bar dropdown ("Explorations: A/B/C") lets you toggle between options instantly via localStorage — no page reload needed.

How to run locally

# 1. Clone and checkout
git clone https://github.com/WordPress/gutenberg.git
cd gutenberg
git fetch origin pull/76680/head:try/content-guidelines-ai
git checkout try/content-guidelines-ai

# 2. Install and build
npm install
npm run build

# 3. Start WordPress
npx wp-env start

# 4. Enable the experiment
npx wp-env run cli wp option update gutenberg-experiments \
  '{"gutenberg-content-guidelines":true}' --format=json

# 5. Visit the page
# → http://localhost:8888/wp-admin/options-general.php?page=content-guidelines-wp-admin
# Login: admin / password

Use the Explorations dropdown in the admin bar to switch between Options A, B, and C.

Key files

Area Files
Exploration B routes/content-guidelines/components/exploration-b.tsx
Exploration C routes/content-guidelines/components/exploration-c.tsx
Mock AI hook routes/content-guidelines/ai/use-ai-guidelines.ts
Exploration routing routes/content-guidelines/stage.tsx, explorations.ts
Diff component routes/content-guidelines/components/diff-editor.tsx
Admin bar menu lib/experimental/content-guidelines/load.php

Notes

  • AI suggestions are currently mocked (simulated streaming with placeholder text). The hook in ai/use-ai-guidelines.ts is designed to be swapped for a real API integration.
  • This builds on the base Content Guidelines feature in Guidelines: Add actions for Import, Export and Revisions of guidelines #76155.
  • The base feature (Option A) includes: CRUD via REST API, import/export JSON, publish/unpublish, and full revision history with restore.

🤖 Generated with Claude Code

aswasif007 and others added 30 commits March 10, 2026 08:16
And omit dataviews search too when there are less than 6 items
Also, use textcontrol instead of combobox in edit mode
This is because the backend expects empty string in order to delete a block
…ment search in guidelines revision history screen
1. Uses downloadBlob from wordpress/blob
2. Adds isRTL support to the chevron
3. Uses dateI18n to format date on revision screen
4. Adds efficient catching of error during revision restoration
iamchughmayank and others added 25 commits March 10, 2026 10:02
…atch

2. Remov unnecessary lint escapes
3. Use memoisation to avoid rerenders
…acing strings

Rename the feature from "Content Guidelines" to "Guidelines" across all
user-facing strings (page title, menu item, experiments toggle, notices,
modals, aria labels, error messages) while keeping variable and file names
unchanged. This aligns with the decision to use the shorter name while
the feature remains experimental.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
…, and empty state banner

Adds the "Suggest All" exploration (Option B) with:
- Top-level and per-section AI generate/improve buttons (tertiary variant)
- Word-level diff review (DiffEditor) with Accept/Dismiss
- Block modal inline generation with shimmer animation
- Empty state banner with localStorage persistence
- Admin bar exploration switcher (A–F)
- Redux store isGuidelinesEmpty selector
- useSyncExternalStore for instant exploration switching

Co-Authored-By: Claude Opus 4.6 <[email protected]>
- Add shimmer effect on fields during AI generation with green border
- Add textStreamingKeys for conditional streaming vs shimmer phases
- Stagger block suggestion reveals (800ms between each)
- Block suggestions appear as ephemeral rows (not saved until user confirms)
- Suppress suggestion badges in list while modal is editing that block
- Local accept state in modal to avoid updating list in background
- Clear suggestions when removing block guidelines
- Dismiss suggestion-only blocks closes modal and removes from list
- Fix suggestion truncation on accept by explicitly setting draft
- Hide Remove action for suggestion-only blocks in kebab menu
- Add height tethering between textarea and diff wrapper
- Generate block guidelines from Get Started banner and header button

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Replace inline onclick handlers with event delegation for admin bar
exploration links. Rename Option A from "Per-Section" to "Current".

Co-Authored-By: Claude Opus 4.6 <[email protected]>
…sidebar

Introduces Exploration C ("Proactive Recommendations") which automatically
scans guidelines on page load and surfaces suggestions in a right sidebar
panel. Key features:

- Two-column layout with fixed 280px sidebar and flexible main content
- Snapshot-based sidebar that only updates on initial scan or user-initiated
  "Check again" (not affected by individual card generates)
- Staggered reveal animation for suggestion items
- Kebab menu per suggestion with "Review" and "Dismiss" actions
- Review opens and scrolls to the relevant accordion
- Dismiss removes from both sidebar and main content
- Empty state with "Check again" button and last-checked timestamp
- WPDS Badge components replace custom suggestion badges across all explorations
- Shimmer animation width matched to textarea via field container max-width
- Block section spinner scoped to local generates only (showSpinnerOnlyWhenOpen)
- Sidebar hover: blue text highlight instead of gray background
- Focus outline suppressed on mouse click (preserved for keyboard)

Co-Authored-By: Claude Opus 4.6 <[email protected]>
…s for Exploration C

- Make sidebar sticky when scrolling by resetting Navigator overflow contexts
- Add improved mock suggestions for meaningful word-level diffs (diffWords)
- Add epoch-based cancellation for AI generation (cancelAll)
- Fix dismiss restoring last saved value instead of going blank
- Fix forceOpen to use counter so repeated sidebar clicks always expand
- Track locally-generated sections/blocks to prevent sidebar pollution
- Fix block button visibility: Improve stays visible (disabled) during generation
- Add spinner to Blocks card header when generating and card is open
- Add highlighted slug state and click-outside listener for future highlight styling

Co-Authored-By: Claude Opus 4.6 <[email protected]>
…diately, remove unused explorations

- Fix Exploration B global "Improve guidelines" dismiss reverting to empty: auto-capture
  preImproveDraft when sectionState transitions to 'requesting' (same pattern as Exploration C)
- Remove snapshot/stagger model from Exploration C sidebar: suggestions now appear immediately
  as each section finishes generating instead of waiting for all to complete
- Delay "Dismiss all" button until scanning finishes
- Remove placeholder explorations D, E, F from TS config and PHP admin bar

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
…oration C

Extract the Content Guidelines feature into a standalone WordPress plugin
(content-guidelines-plugin/) that requires Gutenberg. Includes all three
explorations (A, B, C) with mock AI, block guidelines, import/export, and
revision history.

Key adaptations for plugin:
- Page/Notice shims replace @wordpress/admin-ui and @wordpress/ui private APIs
- Badge span replaces unlock(componentsPrivateApis)
- wp-admin chrome overrides (white bg, margin-left: 140px, hidden footer)
- Sticky header and sidebar with wp-admin-safe z-index values
- plugins_loaded bootstrap for alphabetical load order

Also removes the empty-state banner from Exploration C (B-only concept) —
C auto-scans proactively on page load regardless of guideline state.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
@github-actions github-actions bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Mar 19, 2026
@github-actions
Copy link
Copy Markdown

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

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

Labels

First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants