Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add <Badge> component #1530

Merged
merged 32 commits into from
Jun 5, 2024
Merged

Add <Badge> component #1530

merged 32 commits into from
Jun 5, 2024

Conversation

kevinzunigacuellar
Copy link
Sponsor Member

@kevinzunigacuellar kevinzunigacuellar commented Feb 18, 2024

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" />

Copy link

changeset-bot bot commented Feb 18, 2024

🦋 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

Copy link

vercel bot commented Feb 18, 2024

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

@github-actions github-actions bot added 📚 docs Documentation website changes 🌟 core Changes to Starlight’s main package labels Feb 18, 2024
@astrobot-houston
Copy link
Collaborator

astrobot-houston commented Feb 18, 2024

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
Copy link
Member

HiDeoo commented Feb 22, 2024

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
Copy link
Sponsor Member Author

kevinzunigacuellar commented Feb 22, 2024

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>

Copy link
Member

@HiDeoo HiDeoo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

packages/starlight/user-components/Badge.astro Outdated Show resolved Hide resolved
packages/starlight/user-components/Badge.astro Outdated Show resolved Hide resolved
packages/starlight/user-components/Badge.astro Outdated Show resolved Hide resolved
packages/starlight/user-components/Badge.astro Outdated Show resolved Hide resolved
packages/starlight/user-components/Badge.astro Outdated Show resolved Hide resolved
docs/src/content/docs/guides/components.mdx Outdated Show resolved Hide resolved
docs/src/content/docs/guides/components.mdx Outdated Show resolved Hide resolved
docs/src/content/docs/guides/components.mdx Outdated Show resolved Hide resolved
docs/src/content/docs/guides/components.mdx Outdated Show resolved Hide resolved
Co-authored-by: Sarah Rainsberger <[email protected]>
Copy link
Member

@delucis delucis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks again for all the work advocating for this component @kevinzunigacuellar! Can’t wait to release it. Left a couple of final small notes.

.changeset/wicked-melons-study.md Outdated Show resolved Hide resolved
docs/src/content/docs/guides/sidebar.mdx Outdated Show resolved Hide resolved
Co-authored-by: Chris Swithinbank <[email protected]>
Copy link
Member

@delucis delucis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hereby approve this PR! ✅

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

@delucis delucis added the 🌟 minor Change that triggers a minor release label Jun 5, 2024
@trueberryless
Copy link
Contributor

HYPE!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
🌟 core Changes to Starlight’s main package 📚 docs Documentation website changes 🌟 minor Change that triggers a minor release
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

7 participants