Add <Badge> component

[kevinzunigacuellar]

Description

• Adds an <Badge> component to @astrojs/starlight/components module.

Notes

• Move outline style to be applied with css only to the sidebar current-aria="page"

• Add global variables to edit badge variants

• Add prop "size" (small, medium, large) to edit badge sizes (font size and padding).

• Adds class prop for injecting custom variables

  .custom-badge {
    --sl-color-bg-badge: red;
    --sl-color-border-badge: blue;
    --sl-color-text-badge: cyan;
  }

  <Badge class="custom-badge" text="custom" />

[changeset-bot]

🦋 Changeset detected

Latest commit: a9aee3d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
starlight	✅ Ready (Inspect)	Visit Preview	Jun 5, 2024 1:42pm

1 Ignored Deployment

Name	Status	Preview	Updated (UTC)
starlight-i18n	⬜️ Ignored (Inspect)		Jun 5, 2024 1:42pm

[astrobot-houston]

size-limit report 📦

Path	Size
/index.html	5.79 KB (+10.01% 🔺)
/_astro/*.js	21.81 KB (0%)
/_astro/*.css	13.57 KB (-1.56% 🔽)

[HiDeoo]

Kevin and badges, as a huge badge consumer, I'm always happy to see your PRs and this one is definitely gonna remove a lot of duplicated code for me 🙌

I did not yet closely look at the code, but some general (and personal) thoughts:

• Overall, I find the badges/font a bit too big outside of the sidebar. I usually find the Vitepress version too small but I think the current version is the opposite and wonder if we could find a middle ground. Note that I'm usually not the best person to ask for design feedback, so take this with a grain of salt.
• Would it make sense to also provide the outline variant to users?
• I wonder if allowing a class prop would be nice to allow users to customize the badge even further. To explain, some of the use cases I encountered where a custom class would help:
  • Defining more custom colors, for example in the requests/OpenAPI land, there are more request types than variants we have, so being able to define a custom color would be nice.
  • Having badges themed to a brand color for a company or project.

Is an update in the package.json required?

If I understand correctly, the packages/starlight/components.ts update should be enough.

[kevinzunigacuellar]

Thank you for the review @HiDeoo 💜

Overall, I find the badges/font a bit too big outside of the sidebar. I usually find the Vitepress version too small but I think the current version is the opposite and wonder if we could find a middle ground. Note that I'm usually not the best person to ask for design feedback, so take this with a grain of salt.

You are right. They do look a bit bigger, I will follow the same style as the inline code block which uses a smaller font size.

Would it make sense to also provide the outline variant to users?

I have mixed feelings about exposing outline. it is not an official variant since it's only applied when the sidebar is active. But then I don't see why it couldn't be an official one.

I am not sure what the best way to go about this. I could use some guidance here.

I wonder if allowing a class prop would be nice to allow users to customize the badge even further. To explain, some of the use cases I encountered where a custom class would help:
Defining more custom colors, for example in the requests/OpenAPI land, there are more request types than variants we have, so being able to define a custom color would be nice.
Having badges themed to a brand color for a company or project.

It would be nice to have more theme versions. A class would be a very nice addition to include more customizations.

In terms of customizing current variants. I think the nicest DX would be to override a global variable similar to what VitePress does.

Then class could override variables locally resulting in a new badge theme.

After adding class prop it should the user should be able to create a new theme like this

.custom-badge {
  --sl-color-bg-badge: cyan;
  --sl-color-border-badge: purple;
  --sl-color-text-badge: red;
}

And use it like

<Badge class="custom-badge">custom</Badge>

[HiDeoo]

Sorry it took me so long to get back to this PR after my first review and also for the new updates you have been working on since then. Super appreciate your patience and hard work on this. 🙌

I left a few new comments and suggestions on the code, nothing major. I'd also like to recap everything else remaining to be done so we can push this PR to the finish line.

• Confirm that the class prop is a good idea (I'm personally in favor as I suggested it and have use-cases for it, but I'd like to hear more opinions) I talked a bit with Chris who suggested that we could actually support all valid HTML attributes for <span> which I think is a great idea.
• Check if the new light mode styles are something we want to include (may need to check Starlight design documents) Regarding the new light mode styles, after talking with Chris, a follow-up PR would be better to discuss and implement them.
• After discussing the new component and checking various design systems, one important aspect that Chris brought up was the font size of the badge. It looks like the most common approach when it comes to badges and font sizes is to usually provide a limited set of sizes instead of matching the current font-size. Some examples includes for example IBM’s Carbon, GitHub Primer, Adobe Spectrum, etc. For a first iteration, we could start with a similar approach and provide a limited set of sizes, e.g. size?: 'small' | 'medium' | 'large' (considering users would still be able to override this with custom CSS if needed).
• Update the branch so that we get the new updated docs/src/content/docs/guides/components.mdx file
• Move the new section in docs/src/content/docs/guides/components.mdx just above the Icon section
• Remove the docs/src/content/docs/reference/test.mdx file

Does this sound correct to you? Do you see anything missing?

[delucis]

I hereby approve this PR! ✅

Will release it later today — thanks again for your work @kevinzunigacuellar and to @HiDeoo for shepherding it through 💖

[trueberryless]

HYPE!