H1 headings in badge.mdx, button-group.mdx, and avatar.mdx do not match the {Platform} Name Overview pattern

[jsakamotoIGJP]

Summary

The H1 heading of badge.mdx and button-group.mdx under docs/xplat/src/content/en/components/inputs/ does not follow the pattern used by the other files in the same folder.

Current headings

# Badge Component
# Button Group Component

Headings used by every other file in the same folder

# {Platform} Button Overview
# {Platform} Checkbox Overview
# {Platform} Chip Overview
# {Platform} Circular Progress Overview
# {Platform} Date Time Input Overview
# {Platform} File Input Overview
# {Platform} Icon Button Overview
# {Platform} Input Overview
# {Platform} Linear Progress Overview
# {Platform} Rating Overview
# {Platform} Text Area Overview

18 out of 20 files in docs/xplat/src/content/en/components/inputs/ follow the {Platform} <Name> Overview pattern. Only badge.mdx and button-group.mdx use the older <Name> Component pattern, with no {Platform} token.

Proposed fix

Change the two headings to match the majority pattern.

# {Platform} Badge Overview
# {Platform} Button Group Overview

Why this matters

The Japanese translation for both files was recently updated (button-group PR #468, badge PR #526), and the review found the same mismatch on the Japanese side. Since the Japanese docs follow the English source, fixing the English heading first will let the Japanese translation be corrected to match in a follow-up change.

Scope

This issue is about the H1 heading only. No other content in these two files needs to change.

[jsakamotoIGJP]

Update, one more file found

I checked every .mdx file under docs/xplat/src/content/en/components/ (239 files) for the same pattern.

layouts/avatar.mdx has the same problem.

# Avatar Component

Every other file in docs/xplat/src/content/en/components/layouts/ follows the {Platform} <Name> Overview pattern, the same majority pattern as inputs/.

# {Platform} Accordion Overview
# {Platform} Card Overview
# {Platform} Carousel Overview
# {Platform} Expansion Panel Overview
# {Platform} Splitter Overview
# {Platform} Stepper Overview
# {Platform} Tabs Overview
# {Platform} Tile Manager Overview

Full scan result

Across the whole docs/xplat/src/content/en/components/ tree, only 3 files use the old <Name> Component pattern with no {Platform} token.

docs/xplat/src/content/en/components/inputs/badge.mdx
docs/xplat/src/content/en/components/inputs/button-group.mdx
docs/xplat/src/content/en/components/layouts/avatar.mdx

I also found many other H1 headings that do not use the {Platform} <Name> Overview pattern, for example in grids/, grid-lite/, chart feature pages, changelog pages, and general setup guides. I checked those on purpose and left them out of this issue. They belong to different page families (marketing style headlines, tutorial style headlines, or feature sub pages), so they are not the same case as a plain component overview page. Only the 3 files above are true component overview pages that fell out of sync with the common pattern.

Updated proposed fix

# {Platform} Badge Overview
# {Platform} Button Group Overview
# {Platform} Avatar Overview

The Japanese translation for avatar.mdx also uses the old pattern and follows the English source, so it needs the same follow-up fix once this is done.

[jsakamotoIGJP]

@ChronosSF I'd appreciate it if you could review this issue and decide how we should handle it.

[ChronosSF]

@jsakamotoIGJP , these 3 findings are the first files of a broader effort to modernize and standardize our documentation. They follow a new strict pattern that is UX approved and may differ from what we had before.

We decided to not hide away the effort in a PR forever but rather push the new and improved docs on prod as they come so there may be some discrepancies while we progress through topics.

We are more than happy to receive feedback on this effort so please check the topics in detail when you have the time and let us know if you have structural or other improvements in mind that we can make. As the structure, flow and style are meant to be now consistent and we rely on AI skills and strong models to ensure that, changes are best served if initiated earlier rather than later.

[jsakamotoIGJP]

@ChronosSF Thank you for the explanation. I fully agree with the effort to modernize and standardize the documentation.
 
My concern in this issue is only about consistency. I do not mind seeing both old and new styles while the migration is in progress.
 
I just want to make sure I understood your comment correctly. Does this mean that component overview pages are expected to use the "{Component Name} Component" H1 pattern going forward?
 
If so, that is completely fine with me. I only wanted to confirm the intended direction so that future translations can follow it consistently.

[ChronosSF]

@jsakamotoIGJP , we had a conversation about it today. Most competitors don't even have the "Component" tail in the H1 and the UX team is leaning towards that. The best examples actually had all "component" topics under a "components" section (as opposed to topics about e.g. the MCP server or theming or excel engine etc, that fall under other categories) with the H1 simply stating a name.

While this is great, it contradicts the url pattern we have now and won't be a simple change if we want to keep our google indexing and SEO ranking. I can't fathom writing redirects for everything affected.

Bottom line - note taken, we'll aim for consistency regardless but I can't tell you if we'll keep the current Component template or strip it further. The "Overview" tail is certainly a thing of the past we'll not go back to.

[jsakamotoIGJP]

@ChronosSF Thank you for the clarification.

I understand the situation now. I appreciate the focus on consistency, and I also understand the challenges around SEO and indexing.

We will wait for the final decision and keep following the changes. I have shared this with the JP team as well.

Thank you again for your explanation.