Document WordPress UI + Theme integration defaults in AGENTS.md

[adamwoodnz]

Fixes CHARTS-210.

Proposed changes

• Adds a new WordPress UI + Theme Integration section to projects/js-packages/charts/AGENTS.md that codifies the defaults the package is migrating to: WPDS design tokens in SCSS (--wpds-dimension-*, --wpds-border-*, --wpds-font-* with spec-aligned fallbacks), Stack/stable Text from @wordpress/ui over ad-hoc flexbox and __experimental* exports, @wordpress/theme's ThemeProvider as the theming entry point (no manual DS token overrides), and getElementStyles from GlobalChartsProvider for chart element styles.
• Extends Common Pitfalls with the inverse patterns so agents stop reintroducing them: hardcoded px values where a WPDS token exists, fallback values that diverge from the WPDS spec, __experimentalText, and manual DS token overrides in place of ThemeProvider.
• Adds a changed changelog entry. Documentation-only; no runtime code touched.

Related product discussion/links

• Linear project: WordPress UI + Theme Integration
• Linear issue: CHARTS-210
• Design analysis: pgvZfX-yD-p2
• Project P2: pgWg9p-2e-p2

Does this pull request change what data or activity we track or use?

No. Documentation-only change to an agent-guidance file.

Testing instructions

This PR only modifies projects/js-packages/charts/AGENTS.md and adds a changelog entry — there is nothing to exercise at runtime.

• Open projects/js-packages/charts/AGENTS.md and confirm the new WordPress UI + Theme Integration section reads clearly and renders correctly on GitHub.
• Confirm the Common Pitfalls additions are grouped with the related existing entries.
• Confirm the pre-existing sections (CRITICAL Rules, Changelog, Architecture Decisions, Documentation Workflow, Conventions, Definition of Done, References) are unchanged except where explicitly extended.
• Confirm the changelog entry exists at projects/js-packages/charts/changelog/charts-210-agents-md-wp-ui-theme (patch / changed).

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack), and enable the charts-210-agents-md-wp-ui-theme branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack charts-210-agents-md-wp-ui-theme

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

[Copilot]

Pull request overview

Updates the Charts package agent guidance to codify defaults for the ongoing WordPress UI + Theme integration work, and records the documentation change in the Charts changelog.

Changes:

• Add a new “WordPress UI + Theme Integration” section to AGENTS.md describing default patterns (WPDS tokens, @wordpress/ui primitives, @wordpress/theme ThemeProvider, getElementStyles).
• Extend “Common Pitfalls” with inverse anti-patterns to avoid regressions.
• Add a patch/changed changelog fragment for the documentation update.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
projects/js-packages/charts/AGENTS.md	Adds WordPress UI + Theme integration defaults and expands common pitfalls.
projects/js-packages/charts/changelog/charts-210-agents-md-wp-ui-theme	Adds a changelog fragment describing the documentation change.

[adamwoodnz]

@cursoragent does the update read well for you?

[cursor]

The PR already exists and the title/body don't need changes. The push is sufficient.

Overall, Adam, the update reads well. I verified every claim in the new section against the actual codebase:

• Design tokens -- confirmed --wpds-* variables are used across 10+ SCSS modules (base-legend.module.scss, base-tooltip.module.scss, conversion-funnel-chart.module.scss, etc.)
• ThemeProvider -- confirmed the private API unlock pattern in chart-decorator.tsx exactly matches the description
• getElementStyles -- confirmed it's the standard path, used across all chart components (bar, line, pie, geo, leaderboard, funnel, semi-circle)
• Stack / Text -- confirmed Stack from @wordpress/ui is already adopted in multiple chart components

The one small thing I improved: the __experimental* examples in both the Integration section and Common Pitfalls previously only cited __experimentalText, but the actual remaining __experimental imports in the codebase are __experimentalHStack and __experimentalGrid (from @wordpress/components). I added those to both spots so agents will immediately recognize the pattern when they encounter those specific imports. Pushed in a separate commit.

  

[jp-launch-control]

Code Coverage Summary

This PR did not change code coverage!

That could be good or bad, depending on the situation. Everything covered before, and still is? Great! Nothing was covered before? Not so great. 🤷

Full summary · PHP report · JS report