Charts documentation standardization by adamwoodnz · Pull Request #47363 · Automattic/jetpack

adamwoodnz · 2026-02-26T21:39:42Z

Proposed changes:

This PR standardizes the charts documentation system end-to-end (guide, template, changelog entry, chart docs, and package-level docs metadata) so section coverage and ordering stay consistent.

Guide and template updates

Remove Browser Compatibility guidance and references.
Remove generic Performance Considerations guidance.
Add ## Responsive Behavior as a standard section.
Add ## Interactive Features as a conditional section.
Add ## Legends as a conditional section.
Fix a broken MDX code fence in the guide so prose sections render correctly.
Normalize canonical section order to place Responsive Behavior before Animation.

Chart docs standardization

Remove browser-compatibility boilerplate from chart docs where it had drifted in.
Remove non-actionable generic performance sections (keeping meaningful performance docs where relevant).
Promote Responsive Behavior to top-level ## sections where needed.
Standardize section naming to ## Styling and Customization.
Extract legend content into dedicated ## Legends sections (instead of nesting under Interactive Features).
Rename remaining ## Accessibility Considerations headings to ## Accessibility.
Fix misplaced guidance that had ended up under styling-related sections.
Reorder sections across chart docs to follow one canonical structure.

Package-level docs and agent guidance alignment

Update projects/js-packages/charts/README.md Storybook link to the current docs namespace (js-packages-charts-library).
Add missing public export (@automattic/charts/utils) to the README entry-point list.
Update projects/js-packages/charts/AGENTS.md docs workflow wording to clarify the standard triplet applies when applicable, and that guide-only/scope-specific docs are valid.

Other information:

Have you written new tests for your changes, if applicable? (N/A — documentation-only changes)
Have you checked the E2E test CI results, and verified that your changes do not break them? (Typecheck passed)
Have you tested your changes on WordPress.com, if applicable (if so, you'll see a generated comment below with a script to run)?

Jetpack product discussion

N/A

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

No.

Testing instructions:

Review projects/js-packages/charts/docs/ai-documentation-guide.md and confirm:
- Browser compatibility and generic performance guidance were removed.
- Interactive Features, Legends, and Responsive Behavior are documented as standard/conditional sections.
- The MDX examples render correctly (no unintended code-fenced prose).
Review projects/js-packages/charts/docs/feature-documentation.mdx.template and confirm those sections and ordering are reflected in the template.
Spot-check updated chart docs and confirm:
- No ## Browser Compatibility sections remain.
- ## Responsive Behavior is a top-level section.
- Styling sections are consistently named ## Styling and Customization.
- ## Legends appears as its own section where applicable.
- Section order follows the same canonical sequence.
Review package-level docs metadata alignment:
- projects/js-packages/charts/README.md links to ?path=/docs/js-packages-charts-library.
- README entry-point list includes @automattic/charts/utils.
- projects/js-packages/charts/AGENTS.md allows guide-only/scope-specific docs where the full triplet is not applicable.
Run pnpm typecheck in projects/js-packages/charts and confirm no errors.

Changelog

Generate changelog entries for this PR (using AI).

Linear Issue: CHARTS-174

…lines Audited all chart documentation against the established guidelines and templates. The Browser Compatibility section was identified as drift from the settled standard — it appeared in 6 docs but was never part of the required template structure. Changes: - Removed Browser Compatibility sections from: - trend-indicator docs - sparkline docs - leaderboard-chart docs - line-chart docs - line-chart annotation docs - bar-chart docs - Removed browser compatibility checklist item from ai-documentation-guide.md - Removed browser considerations from the Example Analysis section in the guide Typecheck passes cleanly.

cursor · 2026-02-26T21:39:43Z

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

github-actions · 2026-02-26T21:40:37Z

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 cursor/CHARTS-174-charts-documentation-standardization-6157 branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack cursor/CHARTS-174-charts-documentation-standardization-6157

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 · 2026-02-26T21:40:48Z

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:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
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!

Move the Safari foreignObject positioning note and Popover API details back into the Interactive Popovers section of annotation docs, where they serve as behavioral documentation rather than browser compatibility info.

Add back the Safari foreignObject positioning note to the Annotations section of the line-chart docs as a behavioral note.

Remove generic performance sections from line-chart, bar-chart, sparkline, and geo-chart docs. These sections contained boilerplate statements about built-in optimizations that aren't useful to consumers. The Performance Considerations section in chart-context (GlobalChartsProvider) is kept as it documents meaningful caching and update behavior. Also removed the performance documentation guidance from the AI documentation guide.

Add Responsive Behavior to the documentation template and AI guide as a required section. Charts are responsive by default and this pattern already appears in 7 chart docs. The section documents parent container sizing, aspectRatio, and fixed dimensions.

Add Interactive Features to the documentation template and AI guide as a required section. This pattern already appears in 5 chart docs covering tooltips, pointer events, and keyboard navigation. Placed after Feature Variations and before Styling, renumbered subsequent guide sections.

Add instructions to only include the Interactive Features section when the chart actually supports interactivity (tooltips, pointer events).

Add Legends to the documentation template and AI guide as a conditional section for charts that support legends. Covers basic legend display, interactive legends with GlobalChartsProvider, and composition API patterns. Renumbered subsequent guide sections.

Move nested ### Responsive Behavior subsections to top-level ## sections in 6 chart docs: line-chart, bar-chart, pie-chart, donut, sparkline, and geo-chart. Each is now positioned after Animation (or Theming if no animation) and before Accessibility, matching the standard section order defined in the guidelines.

jp-launch-control · 2026-02-26T22:34:57Z

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

Rename non-standard section headers to '## Styling and Customization': - sparkline: Visual Customization - leaderboard-chart: Visual Customization - trend-indicator: Visual Customization - geo-chart: Custom Styling - legend: Customization - donut: Styling and Best Practices - conversion-funnel: Styling and Theming

…derboard docs Move the CSS Custom Properties subsection from the second Styling and Customization section into the first, eliminating the duplicate heading.

- Trend Indicator: Move 'Without Icon' and 'Value Formats' into Basic Usage where they belong as feature configuration, keep only actual styling content under Styling and Customization. - Donut: Move 'Thickness Guidelines', 'Center Content Guidelines', and 'Responsive Center Content' into Basic Usage as usage guidance. Remove the now-empty Styling and Customization section. - Conversion Funnel: Remove empty Styling and Customization heading.

…el chart Create a proper top-level Styling and Customization section covering className/style props and CSS custom properties (--funnel-font-family, --step-font-family). Moved the Custom Styling content out from under Theming Integration where it was misplaced.

…onut docs

- Pie Chart: Move Legend Positioning and Vertical Legend out of Interactive Features into a new top-level ## Legends section. - Donut: Move Donut with Legend out of Interactive Features into a new top-level ## Legends section.

…order - index.docs.mdx: Swap Animation and Responsive Behavior (Responsive before Animation) - donut.docs.mdx: Swap Animation and Responsive Behavior; move Common Use Cases before Accessibility

- Line chart: Overview, API Reference, Basic Usage, chart-specific sections (Curve Types, Multiple Series, Semantic Line Types, Visual Features, Data Formats, Error Handling, Annotations), Interactive Features, Legends, Theming Integration, Responsive Behavior, Animation, Advanced Customization, Accessibility - Bar chart: Overview, API Reference, Basic Usage, chart-specific sections (Chart Orientations, Multiple Series, Visual Features, Data Formats, Zero Value Display, Error Handling), Interactive Features, Legends, Theming Integration, Responsive Behavior, Animation, Advanced Customization, Accessibility

- Leaderboard: Data States, Data Preparation, Legend now before Styling; Examples moved before Accessibility - Geo: Advanced Features early; Loading, Country ID, Interactive before Styling; Styling before Theming; Responsive, Map Projection, Best Practices before Accessibility

Establish consistent section ordering across all chart docs: Overview → API Reference → Basic Usage → [chart-specific sections] → Interactive Features → Legends → Styling and Customization → Theming Integration → Responsive Behavior → Animation → Advanced Usage → Accessibility → Migration Key changes: - Guide: Swap Animation/Responsive to Responsive-first (sections 11/12) - pie-semi-circle: Move Error Handling and Legend Integration earlier, Responsive Behavior later - conversion-funnel: Move Responsive Behavior from position 4 to 9 - bar-list-chart: Swap Animation and Responsive Behavior - sparkline: Move Dashboard Integration before Styling, Edge Cases after Animation - annotation: Move API Reference from near end to position 2

- Clarify documentation standards for public charts, emphasizing the maintenance of paired files and the inclusion of guide-only documents. - Update the Storybook link in README.md to point to the library introduction section. - Add shared chart utility functions to the list of importable components in README.md.

adamwoodnz · 2026-02-26T23:58:11Z

@claude review again

claude · 2026-02-26T23:58:33Z

Claude finished @adamwoodnz's task in 2m 15s —— View job

Code Review

All three issues from the previous review have been addressed:

✅ Code fence bug fixed — ai-documentation-guide.md sections 10–12 (Theming Integration, Responsive Behavior, Animation) are now proper prose headings outside the code fence.
✅ Conversion funnel ## Sizing → ## Responsive Behavior — renamed in commit 92e9fce7.
✅ Changelog updated — now reads the full-scope description suggested previously.

Remaining issues

Leaderboard chart: missing `## Responsive Behavior` section

projects/js-packages/charts/src/charts/leaderboard-chart/stories/index.docs.mdx

The guide states: "Always include a Responsive Behavior section." Every other changed chart doc now has this section at the top level, but the leaderboard chart has none. The leaderboard chart section order is:

Overview → API Reference → Basic Usage → Comparison Features → Data Formatting → Data States → Data Preparation → Legend Configuration → Styling and Customization → Theming Integration → Animation → Examples → Accessibility

A ## Responsive Behavior section is absent. Fix this →

Leaderboard chart: `## Legend Configuration` should be `## Legends`

projects/js-packages/charts/src/charts/leaderboard-chart/stories/index.docs.mdx, line 315

The PR standardizes legend sections to ## Legends across bar, line, pie, and donut docs. The leaderboard chart, which was modified in this PR, still uses ## Legend Configuration. This is a naming inconsistency given what this PR sets out to do. Fix this →

Minor: `trend-indicator` uses `## Theming` instead of `## Theming Integration`

projects/js-packages/charts/src/components/trend-indicator/stories/index.docs.mdx, line 124

The guide and template use ## Theming Integration as the standardized heading. The trend-indicator doc was modified in this PR (to rename the styling section) but the ## Theming heading was left unchanged. Since this is a component rather than a full chart it may be intentional — just worth being aware of.

Positive observations

The two most impactful fixes from the last review are clean:

The guide's Theming/Animation/Responsive Behavior guidance is now readable prose, not literal code inside a fence.
The conversion funnel ## Responsive Behavior section is well-formed with a FixedDimensions Canvas story, a code snippet, and the standard intro link.
The comprehensive changelog entry now accurately describes the scope of the PR.
All other chart docs reviewed (bar, line, pie, donut, sparkline, geo, conversion-funnel) have the correct ## Responsive Behavior and ## Legends sections where applicable.

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…x.docs.mdx Fix code snippet Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

- Rename "Legend Configuration" to "Legends" in leaderboard chart docs for consistency. - Change "Theming" to "Theming Integration" in trend indicator docs to better reflect content focus.

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

kangzj

LGTM 🚢

cursoragent added 2 commits February 26, 2026 21:38

CHARTS-174: Add changelog entry

ea9cef5

adamwoodnz self-assigned this Feb 26, 2026

github-actions Bot added [JS Package] Charts [Status] In Progress Docs RNA labels Feb 26, 2026

github-actions Bot added the [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. label Feb 26, 2026

cursoragent added 8 commits February 26, 2026 21:46

CHARTS-174: Restore annotation popover behavioral notes

2c43abf

Move the Safari foreignObject positioning note and Popover API details back into the Interactive Popovers section of annotation docs, where they serve as behavioral documentation rather than browser compatibility info.

CHARTS-174: Restore annotation popover note in line-chart docs

3c4bfaf

Add back the Safari foreignObject positioning note to the Annotations section of the line-chart docs as a behavioral note.

CHARTS-174: Make Interactive Features section conditional

5cc0c04

Add instructions to only include the Interactive Features section when the chart actually supports interactivity (tooltips, pointer events).

cursoragent added 6 commits February 26, 2026 22:48

CHARTS-174: Merge duplicate Styling and Customization sections in lea…

83cfb5b

…derboard docs Move the CSS Custom Properties subsection from the second Styling and Customization section into the first, eliminating the duplicate heading.

CHARTS-174: Rename Accessibility Considerations to Accessibility in d…

38c640b

…onut docs

adamwoodnz marked this pull request as ready for review February 26, 2026 23:07

Copilot AI review requested due to automatic review settings February 26, 2026 23:07

Copilot started reviewing on behalf of adamwoodnz February 26, 2026 23:08 View session

adamwoodnz removed the [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. label Feb 26, 2026

adamwoodnz review requested due to automatic review settings February 26, 2026 23:18

Charts: Reorder ## sections in pie and donut chart docs to canonical …

f9ee245

…order - index.docs.mdx: Swap Animation and Responsive Behavior (Responsive before Animation) - donut.docs.mdx: Swap Animation and Responsive Behavior; move Common Use Cases before Accessibility

Copilot AI review requested due to automatic review settings February 26, 2026 23:40

adamwoodnz review requested due to automatic review settings February 26, 2026 23:40

cursoragent added 2 commits February 26, 2026 23:40

Copilot AI review requested due to automatic review settings February 26, 2026 23:40

adamwoodnz review requested due to automatic review settings February 26, 2026 23:40

Copilot AI review requested due to automatic review settings February 26, 2026 23:40

adamwoodnz review requested due to automatic review settings February 26, 2026 23:40

Copilot AI review requested due to automatic review settings February 26, 2026 23:44

adamwoodnz review requested due to automatic review settings February 26, 2026 23:44

Copilot AI review requested due to automatic review settings February 26, 2026 23:57

Copilot started reviewing on behalf of adamwoodnz February 26, 2026 23:58 View session

adamwoodnz requested a review from a team February 26, 2026 23:59

Copilot AI reviewed Feb 27, 2026

View reviewed changes

Comment thread projects/js-packages/charts/src/charts/line-chart/stories/index.docs.mdx Outdated

Update projects/js-packages/charts/src/charts/line-chart/stories/inde…

4c9df70

…x.docs.mdx Fix code snippet Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 27, 2026 00:05

Copilot started reviewing on behalf of adamwoodnz February 27, 2026 00:06 View session

Update documentation section titles for clarity

9a24b91

- Rename "Legend Configuration" to "Legends" in leaderboard chart docs for consistency. - Change "Theming" to "Theming Integration" in trend indicator docs to better reflect content focus.

Copilot AI reviewed Feb 27, 2026

View reviewed changes

kangzj approved these changes Feb 27, 2026

View reviewed changes

adamwoodnz merged commit fbbe7ee into trunk Feb 27, 2026
115 of 116 checks passed

adamwoodnz deleted the cursor/CHARTS-174-charts-documentation-standardization-6157 branch February 27, 2026 02:15

github-actions Bot removed [Status] In Progress [Status] Needs Review This PR is ready for review. labels Feb 27, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Charts documentation standardization#47363

Charts documentation standardization#47363
adamwoodnz merged 25 commits intotrunkfrom
cursor/CHARTS-174-charts-documentation-standardization-6157

adamwoodnz commented Feb 26, 2026 •

edited

Loading

Uh oh!

cursor Bot commented Feb 26, 2026

Uh oh!

github-actions Bot commented Feb 26, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Feb 26, 2026 •

edited

Loading

Uh oh!

jp-launch-control Bot commented Feb 26, 2026 •

edited

Loading

Uh oh!

adamwoodnz commented Feb 26, 2026

Uh oh!

claude Bot commented Feb 26, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

kangzj left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

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

Uh oh!

Proposed changes:

Guide and template updates

Chart docs standardization

Package-level docs and agent guidance alignment

Other information:

Jetpack product discussion

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

Testing instructions:

Uh oh!

cursor Bot commented Feb 26, 2026

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

jp-launch-control Bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Summary

Uh oh!

adamwoodnz commented Feb 26, 2026

Uh oh!

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

Uh oh!

Code Review

Remaining issues

Leaderboard chart: missing ## Responsive Behavior section

Leaderboard chart: ## Legend Configuration should be ## Legends

Minor: trend-indicator uses ## Theming instead of ## Theming Integration

Positive observations

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

kangzj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

adamwoodnz commented Feb 26, 2026 •

edited

Loading

github-actions Bot commented Feb 26, 2026 •

edited

Loading

github-actions Bot commented Feb 26, 2026 •

edited

Loading

jp-launch-control Bot commented Feb 26, 2026 •

edited

Loading

claude Bot commented Feb 26, 2026 •

edited

Loading

Leaderboard chart: missing `## Responsive Behavior` section

Leaderboard chart: `## Legend Configuration` should be `## Legends`

Minor: `trend-indicator` uses `## Theming` instead of `## Theming Integration`