DataViews: Use the public @wordpress/ui Badge instead of the private one

[youknowriad]

What?

See #81230.

Replaces the private Badge from @wordpress/components with the public Badge from @wordpress/ui at DataViews' three call sites.

Why?

@wordpress/ui's Badge is the recommended one — it's on the use-recommended-components allowlist, and DataViews already uses it in validation-badge.tsx. The two grid layouts and one story were stale.

How?

Badge was the only unlocked symbol in composite-grid.tsx, picker-grid/index.tsx, and dataform/stories/layout-card.tsx, so the unlock and privateApis imports come out with it — those files no longer touch @wordpress/private-apis.

One non-mechanical part: BadgeProps['children'] is string, because Badge is text-only by design. Badge fields render <field.render … />, which is not a string — the private Badge accepted it only because unlock() returns any, so those call sites were never type-checked at all.

Rather than relax the prop for everyone, the two grid layouts carry a @ts-expect-error on the <Badge> tag. The text-only rule stays type-enforced for every other consumer, and DataViews' opt-out is visible exactly where the tradeoff lives. @ts-ignore is banned by ban-ts-comment; @ts-expect-error requires a description. @wordpress/ui is untouched by this PR.

The card story passes a template literal instead of a suppression, since its label really is a string.

Testing Instructions

1. npm run storybook:dev
2. DataViews → Layouts → Grid and Picker Grid: badge fields still render, wrap, and align.
3. DataForm → Layouts → Card: the "Due on: …" and plan badges render.

Testing Instructions for Keyboard

No interaction changes — Badge is non-interactive in both implementations, and no focus order or tab stop is affected.

Screenshots or screencast

Small intentional visual change — the neutral variants use different tokens:

	Background	Text	Border
Before (components, intent="default")	$gray-100	$gray-800	none
After (ui, intent="none")	--wpds-color-background-surface-neutral-strong	--wpds-color-foreground-content-neutral	--wpds-color-stroke-surface-neutral

No DataViews stylesheet targets .components-badge, so nothing else is affected by the class change.

Alternatives considered

Rendering badge fields with field.getValueFormatted (suggested here). Tried and reverted: it broke the patterns grid. patternSyncStatusField derives its value rather than storing it under the field id, so the default getValue resolved to undefined and the badges rendered empty; and its sync-status colour comes from a :has() selector matching a span only render emits, which no parent-selector rewrite can recover once the badge holds a bare string. Making that route work needs a dedicated intent/className API for badge fields — left for later.

Widening BadgeProps['children'] to ReactNode. Also tried and reverted, in response to @aduth and @mirka: it removed the type-level guardrail behind the text-only guideline and made the @ts-expect-error directives in IncorrectBadgeWithIcon unused. The call-site suppression keeps that guardrail intact.

Use of AI Tools

This PR was authored by Claude Opus 5 via Claude Code, from the audit that produced #81230. I reviewed the change and am responsible for its contents.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: youknowriad <youknowriad@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: oandregal <oandregal@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: fcoveram <fcoveram@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[aduth]

I haven't had a chance to look deeply at the usage, but this "so badges can wrap [...] icon" is explicitly unsupported and documented as such:

https://wordpress.github.io/gutenberg/?path=/docs/design-system-components-badge-usage-guidelines--docs#using-with-icons

Badge is text-only. Intent is communicated through color and label — not through icons inside the badge.

❌ Don't

Put icons inside badges. A status icon duplicates what the intent color and label already convey.

[youknowriad]

Well that means that component can't be used in DataViews because in DataViews, the current Badge usage can wrap any field output (which is not something we know before hand). What do you suggest we do?

[youknowriad]

We can reword the changelog to avoid mentioning "icons"

[aduth]

Maybe. Is DataViews actually rendering icons though? I think it opens it up for some abuse potential when the goal is that it should be simple text, and tightening it to string helps keep those guidelines in check. But I acknowledge that children as ReactNode is mostly conventional.

I recognize I'm not being especially helpful with solutions at the moment and would like to take a closer look at this when I get a chance, likely tomorrow 🙂

[youknowriad]

DavaViews is generic, AFAIK our current badge usage in Core is not using icons, but I can't tell about Jetpack, Woo or any other third-party usage.

[aduth]

I can appreciate the frustration in the design system being a point of friction for what feels like a simple types change. However, if the request is "I want a purple badge with whatever variation of content" (e.g. arbitrary icons), that conflicts with what Badge is today, and how intent is communicated through color. That doesn't necessarily mean "Badge is right"; maybe we built the wrong Badge. But it does mean this isn't just a simple typings change and it's worth stepping back to understand how to reconcile this inconsistency. Maybe Badge needs additional intents. Maybe "Synced" shouldn't necessarily be purple and should adopt one of the existing intents. I understand this can feel tedious, but this is the work of a design system to navigate.

This case is also rather unique and challenging in how it's trying to align two established APIs that don't necessarily line up 1-to-1. Widening the types might be a fair compromise, but it does open up the real possibility of the exact misuse we want to prevent (icons + text example), and sometimes the friction is a good stopping point to reflect if either a better option would exist or the design system should provide better supports (example where the design system could have better options/guidance around communicating tooltip content to all users).

On the timing aspect of "two days of back and forth", I personally dropped the ball a bit with my own earlier-stated commitment. I think the outcome ended up about where I would have expected. As described, there's more complexity here than appears at a glance, we tried to align, and ultimately @mirka 's suggestion of consumer-side suppression is generally the right approach if we need an immediate solution in absence of that broader alignment. That's consistent with what you describe about discovering abstractions. The change didn't happen in the Badge component, but this is still a signal (a discovery) about what Badge should be expected to support, or what guidance we should provide for these types of use-cases. I would expect the same would happen in third-party usage, and I'd rather the friction lead to these kinds of conversations and we act on that.

What's important now is that we don't drop that lead. This is unblocked, but what needs to happen in Badge or DataViews to solve the underlying issues that are raised? Ideas like whether "synced" is an intent are things we could explore if that's indeed a common pattern distinct from available options. That feels to me like the better outcome to follow-up on, and I'll make sure that isn't lost.

[youknowriad]

What's important now is that we don't drop that lead. This is unblocked, but what needs to happen in Badge or DataViews to solve the underlying issues that are raised? Ideas like whether #81236 (comment) are things we could explore if that's indeed a common pattern distinct from available options. That feels to me like the better outcome to follow-up on, and I'll make sure that isn't lost.

I explored changing DataViews, it requires an API that is way too custom, so IMO, there's no change to be done there. The purple color as intend would be a good addition I think but not sure it serves here.

[oandregal]

One thing that struck me as odd about the intents is that is not one closed set, but rather three different sets:

• priority: high, medium, low
• status: stable, informational, draft
• neutral: none

Having these sets available and using them consistently to communicate priority and status across screens/products would help users? Yes. But then, the question is, how consumers can add domain-specific intents? Do we add a fourth set in Badge with a single element (sync)?

Perhaps badge is such a low-level component that it shouldn't add any domain semantics to the intents, but rather have generic intents (as colors): neutral, red, orange, green, etc. It's the consumer responsibility to give them meaning. Adding purple in that scenario means making the existing set wider, if that makes sense.

---

As for how to integrate badge in DataViews (or any other consumer): overriding styles locally is bound to break. I'd prefer something along these lines, not sure why something like that wasn't possible?

[youknowriad]

I explained it above, it's not possible because the value of the "intent" depend on the value of the field, not the field itself. If the value of the field "sync status" is "synced" the intent should be purple. That means we need a dedicated API on the field based on the field value, and it's just too specific IMO.

[oandregal]

Ah, missed that, thanks. Makes sense.

[mirka]

I'll also note that the new Badge intentionally doesn't have built-in truncation behavior, whereas the old Badge does. So if that's a problem, the truncation needs to be added back at the consumer level (@jorgefilipecosta maybe?).

[mirka]

We need some alignment here. Badges intentionally restrict non-string content, especially to prevent arbitrary icons. Can we for example switch <field.render> to field.getValueFormatted calls?

I'm also seeing an instance where a synced status badge is customizing its colors from within the Badge content. Badges are intended to have standard colors that are tied to semantic meaning, so the only way to override the built-in colors is going to be through className or style props on the component itself.

gutenberg/packages/fields/src/fields/pattern-sync-status/index.tsx

Line 61 in 61e4398

className={ `fields-field__pattern-sync-status fields-field__pattern-sync-status-${ syncStatus }` }

[youknowriad]

Can we for example switch <field.render> to field.getValueFormatted calls?

I don't know if we can, it breaks a long time assumption for rendering fields, it would be a breaking change so I don't really know if we can make this change safely.

I'm not suggesting we change the Badge recommends, but it feels to me like an ok tradeoff for now.

The other alternative is to duplicate the Badge component in DataViews

[youknowriad]

I would also argue that this doesn't break the guidelines. <>Something <i>something</i></> feels like an entirely valid use-case for Badge even with this guideline in place.

[oandregal]

I confirm the only usage in core for badgeFields is what Lena shared.

I've checked other large consumers I'm familiar with, and I haven't found any usage of badgeFields. This is in sync with what I heard about the feature: people raised the badge is not carried to layouts other than grid, so they defaulted to create their own render with badge (the feature wasn't so popular). I've pinged folks to confirm, should I have missed some cases.

One option forward (requires a breaking change, but perhaps it's not that bad) is to have an optional className prop for the badgeFields (to be forwarded to the wordpress/ui badge). For example:

badgeFields: [ 'field-1', { field: 'field-2', className: 'someClss' } ]` 

We could also have an intent prop in addition to the className. I see that the new badge component is designed around a closed set of intents. But I also see that the component can receive a className so I suppose this is a valid usage?

I'm assuming we want to keep the purplish color for sync patterns that we carry everywhere in the UI. If it can't be the badge, we'd need to find a different way to communicate that.

[youknowriad]

There's also a difference in background right now.

Before:

After:

[github-actions]

Size Change: +1.35 kB (+0.02%)

Total Size: 7.82 MB

📦 View Changed

Filename	Size	Change
build/modules/content-types/index.min.js	172 kB	-6 B (0%)
build/scripts/edit-site/index.min.js	311 kB	-21 B (-0.01%)
build/scripts/editor/index.min.js	510 kB	-62 B (-0.01%)
build/scripts/media-utils/index.min.js	129 kB	+1.42 kB (+1.11%)
build/styles/edit-site/style-rtl.css	21.4 kB	+4 B (+0.02%)
build/styles/edit-site/style-rtl.min.css	17.6 kB	+3 B (+0.02%)
build/styles/edit-site/style.css	21.4 kB	+7 B (+0.03%)
build/styles/edit-site/style.min.css	17.6 kB	+3 B (+0.02%)

_{compressed-size-action}

[youknowriad]

Maybe I should use "draft" tone to keep things close to the previous design. (Probably a bad idea because we don't want the "draft" semantic here)

[youknowriad]

Also noting that we override the colors of the badge for some badge like "synced patterns" where we use the purple color that we always use in Gutenberg for all "global" stuff (template parts, patterns...). I'm actually wondering if that's a valid reason to add an official "intent" for this one.

[jasmussen]

Thanks for tagging me. I'm wondering how I can best provide feedback here. At a glance, the motivation to unify on the newer component is good and valid. I think the change from the grey background to the new neutral border is fine.

It sounds like one of the discussions is whether a badge can include an icon, or even more than simply text. I don't have strong opinions on this, and it's unclear to me if Jay—which largely spearheaded the new badge—had strong opinions on it. Without making the following sounds like a decision, because I'd want defer to more technical folks such as yourself, it sounds like technically you can, which if that's the case, we can provide recommendations to not do that, and try to adhere to it especially when Jay comes back and notes why. But perhaps not enforce it?

Let me know if that makes sense.

[youknowriad]

Here's how the patterns badge look @jasmussen I just want a quick validation that this looks good to you.

[jasmussen]

Ah, that looks good to me. The "Synced" part is something I expect can evolve again in the future, overall, as this is something @fcoveram is thinking about. 👍 👍

[github-actions]

Flaky tests detected in ae2c7af.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/31154717309
📝 Reported tests:

As a user I want to be able to create a navigation overlay for a specific navigation block in /test/e2e/specs/site-editor/navigation-overlay-template-part.spec.js, passed after 1 failed attempt.

TimeoutError: locator.click: Timeout 10000ms exceeded.
Call log:
  - waiting for getByRole('region', { name: /(Editor publish|Save panel)/ }).getByRole('button', { name: 'Save', exact: true })

    at Editor.saveSiteEditorEntities (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/editor/site-editor.ts:45:5)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-overlay-template-part.spec.js:93:4

should allow user to add and remove multiple local font files in /test/e2e/specs/admin/font-library.spec.js, passed after 1 failed attempt.

Error: expect(locator).toBeVisible() failed

Locator: getByLabel('Exo 2 Semi-bold Italic')
Expected: visible
Timeout: 5000ms
Error: element(s) not found

Call log:
  - Expect "toBeVisible" with timeout 5000ms
  - waiting for getByLabel('Exo 2 Semi-bold Italic')

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/admin/font-library.spec.js:61:6

[fcoveram]

Here's how the patterns badge look @jasmussen I just want a quick validation that this looks good to you.

This sync language looks good. I see above that there are mentions that the color has not yet been tokenized. It would be great to push that enhancement, but from a design perspective, I don't have a clear picture of all the instances where the language is being used.

Perhaps that doesn't block having the interactive and non-interactive token sets.

[youknowriad]

Merging this since it's not impacting ui package anymore.

[aduth]

It sounds like one of the discussions is whether a badge can include an icon, or even more than simply text. I don't have strong opinions on this, and it's unclear to me if Jay—which largely spearheaded the new badge—had strong opinions on it.

I don't want to speak on @jameskoster 's behalf, but knowing that he's away for a little longer and unable to respond, my understanding here is that icons were something we want to support, but not necessarily arbitrary icons.

Related comment: #73875 (comment)

This was also something that came up in #79585 in introducing the badge usage guidelines that currently discourage icon use.