Convert to component: Badge

[jameskoster]

A recently-merged data views feature allows consumers to display field values as a 'badge' in grid layout. This is utilised in the Patterns page to communicate sync status:

This element will likely have applications beyond data views, so it may be worth extracting and converting to a reusable component.

[jasmussen]

Indeed, that seems useful. However it's probably important to do that effort only if and when the need for this chip emerges organically.

[jameskoster]

In addition to badge fields in data views, another potential use case is #57763.

But yes, no need to rush for only one or two applications.

[jameskoster]

Another potential use case for the badge: #38277 (comment)

[Vrishabhsk]

Hi @jameskoster 👋

• I have raised a PR for adding the Badge component : Enhancement : Badge Component  #66555

Let me know your thoughts on this. Thanks

[orcunomattic]

@jameskoster could we please add a version of this badge component where we have the option to include an icon (before OR after the text)?

[rogermattic]

@jameskoster @Vrishabhsk I worked on the component design a bit, and here's my proposal.

To cover a range of usecases we need to have a few different colour badges. So I started exploring the colour mixes using the WordPress palette. Came up with fairly simple rules (that hopefully can be algorithmically generated):

Base colours
If we take these as our base colours:

Background
We can take the base colours and apply 10% transparency on solid white.

Foreground
We can apply the $gray-700 with a multiply blending mode onto the base colour.

And in that way, we will have all colour badges, which all pass the accessibility tests.

In terms of design they have (but I'll spec that when we have the final designs) 8px padding left and right, 4px top and bottom. We are thinking about adding a larger variant as well, just FYI.

@jameskoster could we please add a version of this badge component where we have the option to include an icon (before OR after the text)?

@orcunomattic we were just talking about this with @jameskoster ! Yes, there will be a variant with an icon (on the left and on the right). I'll add them as symbols once we are all aligned on this!

[afercia]

I'd support the variant with icon and clear usage guidelines to educate that the meaning of the variants can't be communicated only via the color. From an accessibility perspective, color alone isn't sufficient.

Typically, the meaning of the various colors may be summarized as follows:

• generic - gray
• info - blue
• warning - yellow
• alert - red
• success - green

All these meanings must be communicated either via a clearly recognizable shape or via the text used within the badge. Useers must be able to understand 'hey this is a warning', or 'hey this is an alert' etc.

[Vrishabhsk]

Hi @orcunomattic @rogermattic @afercia 👋 Thanks for your input on the component

• I have added the capability for different variants and styled them according to the designs shared
• Also attached a context with each variant apart from the generic one
• Added the capability for adding an icon as well.

With Icon + Context	With Variant + Context	Without Context

Let me know your thoughts on this. Thanks

[jameskoster]

I'm not sure about offering an icon and context as separate props. It's not 100% clear that we need an icon affordance just yet, so we might be better off adding that later.

For the initial implementation perhaps icon usage is built into the context prop? IE an icon is only displayed when context is one of; warning, danger, success?

@afercia would it be acceptable for a lack of icon to be indicative of an informational badge?

Here's a quick mockup exploring icons and shapes:

@rogermattic transparency can lead to contrast issues down the road if the badges ever appear on non-white backgrounds. Do you think there's a way to apply color without using transparency?

[rogermattic]

Thanks for your feedback!

I'm not sure about offering an icon and context as separate props. It's not 100% clear that we need an icon affordance just yet, so we might be better off adding that later.

For the current use case I’m exploring, an icon isn’t necessary, but believe others might benefit from a variant with one. I can look into this further and gather evidence and examples to support the need for an icon variant.

From an accessibility perspective, color alone isn't sufficient.

With a different perspective, I believe we’re accessibility-safe even without the icon. The text label, paired with the color, ensures accessibility for users. That said, I still think an icon would be a nice addition as it adds a helpful visual clue and enhances the meaning. Actually, the opposite is true for accessibility concerns: when we have an icon and color but no text to clarify the meaning, it could be considered less accessible.

@rogermattic transparency can lead to contrast issues down the road if the badges ever appear on non-white backgrounds. Do you think there's a way to apply color without using transparency?

Great point! I realize I could've been clearer in the specs (honestly didn’t expect things to move this fast!). By ‘transparency,’ I was only referring to the transparency of the color on the layer above white. I completely agree that the badge itself shouldn’t be transparent. And while it’s designed primarily for use on a white background, we should also consider cases where it might appear on light gray or similar shades, where the color should remain consistent.

I have added the capability for different variants and styled them according to the designs shared
Also attached a context with each variant apart from the generic one
Added the capability for adding an icon as well.

@Vrishabhsk thank you for your speedy work on this!
I love the badges (just one small adjustment needed regarding the color as mentioned above). As for the icons, I agree with @jameskoster that we can initially release the version without them. Visually, I believe the icon proportions and spacing could use a bit more refinement. I’ll revisit this and get back to you soon.

[afercia]

would it be acceptable for a lack of icon to be indicative of an informational badge?

@jameskoster a generic, informational badge may not use any icon. However, in Core the 'info' notices use a blue color and I'd recommend consistency.

For the current use case I’m exploring, an icon isn’t necessary,
With a different perspective, I believe we’re accessibility-safe even without the icon. The text label, paired with the color, ensures accessibility for users.

@rogermattic can you please add more context? I'm not sure whether the 'text label' you mention is a sort of text prefix e.g. 'Error:', 'Warning:' etc. that is prefixed to all badges content. In that case, without an icon, this prefix should be required.

The distinction between the badge types can't be only conveyed using color. Ideally, badges should provide cues through color, icon, and text. For screen reader users, some textual content is required to distinguish the badge type.

This issue is very similar to the one discussed on Trac for the admin notices. See this trac ticket: https://core.trac.wordpress.org/ticket/50442. I would recommend to give that a read to better understand color alone is insufficient.

Quick tip:
There's a series of tools that can be used to emulate color perception impairments, including monochromacy. For macOS I'd recommend Sim Daltonism. Screenshot:

[afercia]

Cc @joedolson for any additional feedback he may want to bring in.

[Vrishabhsk]

I have added a few more commits to the PR for improvement. Let me know your thoughts on it. Thanks

[rogermattic]

@rogermattic can you please add more context? I'm not sure whether the 'text label' you mention is a sort of text prefix e.g. 'Error:', 'Warning:' etc. that is prefixed to all badges content. In that case, without an icon, this prefix should be required.

I believe the content of these badges should be clear enough for users to understand their meaning on its own, so that even color-blind users won’t miss the message if there’s no icon accompanying the label.

It seems we might have different use cases in mind for these badges. I’d love to hear more about the primary usage you envision. From my perspective, color is secondary—we’ll use these for things like labeling content categories, order statuses, and transaction statuses. Some examples include:

This issue is very similar to the one discussed on Trac for the admin notices. See this trac ticket: https://core.trac.wordpress.org/ticket/50442. I would recommend to give that a read to better understand color alone is insufficient.

That's a great point and a helpful example! For notices, I agree that color plays a primary role—indicating 'Error,' 'Warning,' etc.—so communicating the color itself is essential. In this case, icons will likely be important to reinforce the message.

[joedolson]

I think most of the feedback I might add has already been added via the references to track ticket 50442; but in general, I agree that the combination of color and icon is fairly crucial for having a consistent perceivability of the value.

The text itself should generally convey the significant meaning of the badge, no matter what color or icon is used; though obviously some text can be ambiguous. However, if we want to increase the recognition affordance to allow improved at-a-glance recognition of the badges, then we need to have both color, context and icon, so that improvement is available to all users.

When an icon is present, the context can be the icon; the text would simply serve as the alternative text for that icon - just to clarify that I'm not recommending that the context string always be visibly present.

[afercia]

From my perspective, color is secondary—we’ll use these for things like labeling content categories, order statuses, and transaction statuses.

Good point. I;d argue those are two different cases:

• Generic 'tag labels' á la GitHub: In this case color doesn't necessarily convey meaning.
• Statuses: In this case color does convey meaning. Even if they're not notices, colors would be used to commuicate concepts like 'compelted', 'pending', 'suspended' etc. As such, this information needs to be communicated with something that is alternative to color alone.

I believe the content of these badges should be clear enough for users to understand their meaning on its own

Yes but we can't enforce strict rules about the type of content. Consumers of this component may use it with any content so that we can't guarantee a correct usage.

Overall, wherever color is used to communicate meaning, there should be an alternative way to communicate that meaning.

[rogermattic]

Good point. I;d argue those are two different cases:

• Generic 'tag labels' á la GitHub: In this case color doesn't necessarily convey meaning.
• Statuses: In this case color does convey meaning. Even if they're not notices, colors would be used to commuicate concepts like 'compelted', 'pending', 'suspended' etc. As such, this information needs to be communicated with something that is alternative to color alone.

Excellent examples and I do agree :) A status label needs an icon to be a complete component.

But I do think that we also need a generic variant as you described it above! So ideally we have both variants :)

Yes but we can't enforce strict rules about the type of content. Consumers of this component may use it with any content so that we can't guarantee a correct usage.

Agreed! But it seems to me that what we also cannot enforce is the right use of icons / or / the use of right icons, so providing both variants and some guidance is probably the way to go. WDYT?

[jameskoster]

But it seems to me that what we also cannot enforce is the right use of icons / or / the use of right icons

I think we can if the icon is a feature of the context property. We should define that, and the associated icons. For instance <Badge context="danger"> would include the appropriate icon. <Badge context="neutral"> would not include an icon. Icons should be reserved for specific contexts to begin with.

What's less clear to me is how colors should be applied to neutral badges. <Badge context="neutral" color="red"> might make sense, but what if a consumer did something like <Badge context="danger" color="green">? Is the color property ignored in this case?

[rogermattic]

<Badge context="neutral"> would not include an icon.

🙌 awesome idea.

What's less clear to me is how colors should be applied to neutral badges. <Badge context="neutral" color="red"> might make sense,
but what if a consumer did something like <Badge context="danger" color="green">? Is the color property ignored in this case?

Great point @jameskoster ! I think, whencontext is set up to "danger", "warning" or "success" the colour property gets overwritten, as they (icons) link 1 to 1 with a specific colour. Context "neutral" should allow (though I need to think more if we want to limit it somehow) any colour, but preferably gray and blue that we should use as examples for consumers).

We should define that, and the associated icons. For instance <Badge context="danger"> would include the appropriate icon. <Badge context="neutral"> would not include an icon. Icons should be reserved for specific contexts to begin with.

I'll work on this asap, and get back here with an update:

• propose layouts with icons
• context x colour definitions
• propose large size badge

[rogermattic]

Coming back with some updates! Here are the different badge variants:

It would be great to get your general feedback, and I’m especially interested in your thoughts on the following:

• Proposed Icons: The warning icon would need to be added to the library, or we could use a rotated (i) icon as a placeholder for now.
• Actionable Variant: Do you think it makes sense to add this to the library as well? I have a use case in mind and can expand on it.
• Variant Sizes: Your thoughts on size options would be helpful.
• Neutral Variants: All colors would have no icon, with the gray badge serving as the neutral option (so no icon allowed here).

Additionally, I considered a gray badge variant with a toggle tip icon, though I’m still debating whether that’s necessary.

I wonder how we can ensure this isn't overused. Perhaps we should set a rule to always place a toggle tip in the column header if needed additional explanation.

Looking forward to hearing your feedback! cc: @jameskoster @Vrishabhsk

[Vrishabhsk]

Thanks, @rogermattic @jameskoster for the work done here. The mockup looks pretty accurate as per our use case

Wanted to summarize a few things here :

size attribute

• Small & Large : I didn't come across any use case that required Large variant, so was wondering about its requirement.
• We could instead allow them to modify this using the className field

context attribute

• Warning / Error / Success would have an Icon and color associated with them
• Neutral context would not have an icon by default.

color attribute

• When this property is used in conjunction with context, the latter has the higher precedence. (Correct me if I'm wrong)
• Will there be predefined colors to select from? Will they be limited to these states : Warning / Error / Success / Neutral
• If so, shouldn't they be named as per their state and not color?

icon attribute

• This prop can be used to override the predefined icon for Warning / Error / Success and add an icon for Neutral

hideIcon attribute

• This prop will enable toggling the icon in case of simple display.

iconPosition attribute

• This would justify the icon's position in the badge, either to the left/right or the content.

Actionable variant

• This does not make sense to me since this component will mostly be used in context of data-views and will likely not have any operation associated with it, but please elaborate on the use case you had in mind.

These were my initial thoughts on it. Feel free to correct me if I was mistaken somewhere and let me know the next steps regarding the component.

Also, I have implemented the color based on operations previously discussed using the color presets available. Are there any changes to be made for this? Would be helpful to get a color-code schema for the variant discussed above.

@mixin badge-color-variant( $base-color ) {
	background-color: mix($white, $base-color, 90%);
	color: mix($black, $base-color, 50%);
}

$badge-colors: (
	"info": #3858e9,
	"warning": $alert-yellow,
	"error": $alert-red,
	"success": $alert-green,
);

[jameskoster]

Thanks for the continued work on this @rogermattic :) My overarching feedback would be to keep things as simple as possible for the initial implementation; it's much easier to add features later as needed, than to remove them. In that train of thought:

• I suggest holding off on the size variation for now.
• Good idea to use existing icons, we can easily revisit this detail later.
• I don't know that Badge's should ever be actionable, let's discuss that separately after the initial implementation.

Should there be an info variant? We have one for Notice so it might be good to align.

@Vrishabhsk Thanks for summarising, this is helpful. Based on my comments above I think we can simplify quite a bit:

• No need to include an icon property. For now the icon should be hard-coded, informed by the context prop.
• It should not be possible to hide the icon as this will violate a11y best practises.
• I'm also unconvinced about the iconPosition prop. Though the icon position should adapt based on locale (rtl/ltr).
• For now I'd suggest neutral = gray, and we explore a color prop separately as a follow-up.

One other comment on the design; the current 'badges' are 20px tall which ensures they neatly align with the most common text styles (20px line-height) without affecting layout. See the screenshot below for a demo of what I mean. It might be nice to preserve this detail if we can.

[rogermattic]

@Vrishabhsk @jameskoster thank you for reviewing and working on this!

My overarching feedback would be to keep things as simple as possible for the initial implementation; it's much easier to add features later as needed, than to remove them.

Agreed!

I suggest holding off on the size variation for now.

Agreed!

Good idea to use existing icons, we can easily revisit this detail later.

Are you okay with the icons I suggested?

I don't know that Badge's should ever be actionable, let's discuss that separately after the initial implementation.

I have some use case that I can describe for this; can I go ahead and open a separate issue for that?

Should there be an info variant? We have one for Notice so it might be good to align.
Could you expand on that? I'm just interested what do you mean by the Notice variant? Agred on aligning if that's what I assume it is! A badge with an ( i ) icon? in neutral colour?)

No need to include an icon property. For now the icon should be hard-coded, informed by the context prop.

I agree, for now this can be a 1:1 reference, until we prove the need for the property

It should not be possible to hide the icon as this will violate a11y best practises.
But there will be the neutral badge without an icon, won't it?

One other comment on the design; the current 'badges' are 20px tall which ensures they neatly align with the most common text styles (20px line-height) without affecting layout. See the screenshot below for a demo of what I mean. It might be nice to preserve this detail if we can.

I used the smallest line height $font-line-height-x-small and the $font-size-small font size, which corresponds to the Body Small text style in Figma (set at 12/16px). Adding a 4px padding on the top and bottom brings the total height to 24px. I think of it this way rather than as a fixed height.

In my opinion, it looks fine, though it’s a bit tight in the screenshot you attached. However when I apply these settings in the table context, it feels a bit cramped. WDYT?

This:

vs this:

Also I think the variants with icons look really tight with these settings and I don't think we should go any smaller with the icon size?

[Vrishabhsk]

Hi @jameskoster @rogermattic 👋

• I have updated the component as per our discussion here. You review it here : Commit

• Here's how the component structure looks

  

• I have created the following context variants

Neutral	Info	Warning	Error	Success

Let me know your thoughts on this. Thanks

[annchichi]

I don't know that Badge's should ever be actionable, let's discuss that separately after the initial implementation.
I agree with @jameskoster here. I wonder we need to have some rules/guides here. Badge is more for static but tag (such as filter tag) this can be static or interactive as well.

those variants
@rogermattic, are these variants also called "badge," right? I asked because I saw the design with a chip label, so I thought I'd double-check on this.

[jameskoster]

I have some use case that I can describe for this; can I go ahead and open a separate issue for that?

Yes please!

Are you okay with the icons I suggested?

Looking at the screenshot in @Vrishabhsk's comment above, I'd say the warning icon looks a bit strong. It seems to be a remnant from Dashicons that we should revisit.

The x in Error looks a bit like an inline close/remove button, I wonder if there's anything we could do about that? One idea could be to use different shapes around the ! to denote severity; one for warning and another for error:

What do you think @rogermattic?

[rogermattic]

are these variants also called "badge," right? I asked because I saw #61106 (comment) with a chip label, so I thought I'd double-check on this.

Yes yes, all called a badge – sorry I will clean that Figma up.

Looking at the screenshot in @Vrishabhsk's comment above, I'd say the warning icon looks a bit strong. It seems to be a remnant from Dashicons that we should revisit.

Agreed 100%. The warning icon surprised me too. I used the WordPress icons in my designs, just the outlined not filled) variants. But I do see it now that we would probably benefit from having a bit more consistency between the icons, exactly like you said @jameskoster :

The x in Error looks a bit like an inline close/remove button, I wonder if there's anything we could do about that? One idea could be to use different shapes around the ! to denote severity; one for warning and another for error:

I cannot unsee it now :D

But I wonder, if I introduce some icons similar to what you proposed in your comment, would I need to add them to the Gutenberg library?

I feel like we could use the circle for error, triangle for warning and have a tick inside an outlined circle for the success too, for consistency.

[jameskoster]

would I need to add them to the Gutenberg library?

Yes, we can do it as a part of the PR :)

I feel like we could use the circle for error, triangle for warning and have a tick inside an outlined circle for the success too, for consistency.

That sounds like a good place to start :)

[jameskoster]

@jasmussen noticed that the info icon is slightly larger than other circular icons (like the checkmark-within-circle). It would be good to update that at the same time :)

[Vrishabhsk]

Hi @jameskoster @rogermattic 👋

• I have added 2 icons : Caution and Error

Caution	Error

• Here is how the contexts look along with the new icons

Info	Warning	Error	Success

Let me know your thoughts on this. Thanks

[jameskoster]

Thanks for the update @Vrishabhsk.

Looking at this I wonder if the error should use the triangular outline as it seems more severe.

The designs could use some tweaks to the footprints and details like roundedness align. I'll push some updates to the PR :)

[rogermattic]

@jameskoster thanks for working on these icons and apologies @Vrishabhsk for the lack of my guidance in the meantime.

Just wanted to double-check, we have 4 variants with icons, right?

• Info
• Warning
• Error
• Success

and one without an icon:

• Neutral

Is this possible to use the red, yellow and green also without an icons?

[mirka]

Is this possible to use the red, yellow and green also without an icons?

@rogermattic Not in the current implementation. Given the accessibility concerns and overall coherence as a design system, I'm also leaning toward keeping the color and intent closely coupled. Green and red feel kind of safe in this regard, but once we allow no-icon usage of blue and yellow I feel like we would quickly see a lot of usage straying from the original intents reinforced by the icon. The colors would lose meaning once we have ecosystem tenants using the colors arbitrarily.

One can always just use the neutral variant and override the color with their own CSS class, but that's purely a consumer decision and not officially part of the design system. Would that be reasonable?