Add <Steps> component

[delucis]

Description

• Adds a <Steps> component for styling more complex guided tasks.
• The component wraps Markdown numbered lists, adding extra styling to help highlight the numbering and link the steps.
• Preview of test page with various usage examples: https://starlight-git-dx-1012-steps-astrodotbuild.vercel.app/guides/components-steps/
• Docs: https://starlight-git-dx-1012-steps-astrodotbuild.vercel.app/guides/components/#steps (will move these up the page after Add <FileTree> component #1308 has merged)

[changeset-bot]

🦋 Changeset detected

Latest commit: fd16093

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	Mar 1, 2024 5:53pm

1 Ignored Deployment

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

[astrobot-houston]

size-limit report 📦

Path	Size
/index.html	6.09 KB (+5.79% 🔺)
/_astro/*.js	21.54 KB (0%)
/_astro/*.css	13.45 KB (0%)

[sarah11918]

Woo! These are looking so good! I love the step numbers and the lines. The headings look really good, too!

Some gut reaction feedback on the visuals (haven't looked at the authoring experience yet):

1. I first viewed this in dark mode and thought, "Oh, did we decide to NOT have the vertical lines?" I think the lighter grey for the lines, and honestly, maybe even the fill colour of the circles might be too subtle
   in dark mode?

2. With component content: having the code snippet off to the right looks like it's a mistake? It feels off, I think?
3. What if it's a regular code block within Markdown? I don't see an example of that, and that's one of our big use cases.

[delucis]

1. I first viewed this in dark mode and thought, "Oh, did we decide to NOT have the vertical lines?" I think the lighter grey for the lines, and honestly, maybe even the fill colour of the circles might be too subtle in dark mode?

I did go back and forth a bit, but the more intense hairline felt kind of noisy and distracting, especially in medium viewports where it kind of competes with the border of the sidebar in light mode:

I’ll take another look though. Maybe this is a case where we need to tweak things in dark mode vs light mode.

2. With component content: having the code snippet off to the right looks like it's a mistake? It feels off, I think?

That’s just an example, not how things automatically behave — I threw a <CardGrid> in to split those two things vertically kind of like this example. But if someone wants to do that, they’d be on the hook for it and would make it look as good/bad as they want unrelated to <Steps>.

3. What if it's a regular code block within Markdown? I don't see an example of that, and that's one of our big use cases.

Do you mean like the example in the docs for the component?

[sarah11918]

Do you mean like the example in the docs for the component?

Ah, yes I did! Sorry, I was only looking on the test page! That looks great!

[liruifengv]

Wow! This looks so cool. We need it for our Astro docs tutorial.

[HiDeoo]

Tested the new component in one project by replacing my existing <Steps> component with the new one as it uses a similar approach. Drop-in replacement worked perfectly 🎉 (altho it's only basic lists without headings so this does not cover all use cases).

Also played a bit with VoiceOver and as expected considering this is beautifully built around lists, it works perfectly.

Some more general questions:

• Did you already check what the pa11y errors are?
• Are some parts of the docs good candidates to showcase the new component? Do we want to do that? I thought the 3 getting started steps (Create a new project - Start the development server - Add content) could maybe be a good candidate to do that. Could also totally be follow-up PRs. Any thoughts?

[delucis]

• Did you already check what the pa11y errors are?

Yes, started investigating last night but didn’t complete it yet. AFAICT it seems to be a false positive where it somehow thinks a background colour from the ::before/::after pseudo elements are overlapping with something? I didn’t yet fully understand but will investigate and fix somehow.

• Are some parts of the docs good candidates to showcase the new component? Do we want to do that? I thought the 3 getting started steps (Create a new project - Start the development server - Add content) could maybe be a good candidate to do that. Could also totally be follow-up PRs. Any thoughts?

Yes! Locally I tried it already in the numbered steps on the “Customizing Starlight” guide and worked quite well. I’ll try your suggestion too.

My thought was that it might be best to do in a follow-up PR that could also apply the formatting change to other languages in one pass with i18nIgnore.

[delucis]

Wrapped up some investigation into the pa11y failures:

In some cases, when axe can’t determine the contrast ratio for certain elements, for example if the element has a background image or contains a pseudo-element, it will report the issue as “needs review”. The problem is that pa11y is currently reporting these review items as errors

(see pa11y/pa11y#633 (comment))

We have this exact issue: if I remove a background colour from the ::before used as the list marker, the tests pass, but adding it back causes them to fail.

This is tracked as an issue in pa11y/pa11y#623 and there’s a draft PR in pa11y/pa11y#685 but no fix yet. (Also would be fixed in pa11y@7, but pa11y-ci is still on pa11y@6, so lots of stacks of maintenance needed there — shame that seems to be quite slow, wonder if there’s anything we can do to help?)

Given this, I think we’re out of options apart from disabling colour contrast checks in pa11y-ci for now. (We should bring them back once things update hopefully.) Colour contrast is luckily pretty easy to test manually — and even spot visually for the most part — so I think we have a fairly good handle on that and shouldn’t let anything slip by without the automated check 🤞 Made that change in 4214d5b and tests should now pass.

[HiDeoo]

Made that change in 4214d5b and tests should now pass.

This makes sense and I think we should indeed be fine for the time being. 👍

I also want at some point to take the time to test kayle which I found out when the PR to migrate the CI part of pa11y-ci into pa11y was cancelled (they also seem to work on a Rust/WASM runner with the A11yWatch org so maybe good to keep an eye on that too).

[delucis]

I also want at some point to take the time to test kayle

Interesting! Hadn’t seen that — seems early still with one developer although they are building a business of it looks like, so maybe there’ll be more investment in the tools if they are successful.

---

OK, one last update from me this morning: I decided to remove the wrapper <div> this component was outputting. We only had it there to get a scoped class name for styling, and I decided we could get by without that — just making the sl-steps class global. Simplifies things a bit and removes unnecessary wrapper elements. (Also as a side effect technically means people can slap the sl-steps class on anything they wanted I guess.)

---

@sarah11918 Re: your concern about the dark theme guide line — I did end up bumping up the contrast a touch on that, so hopefully should address that!

[dreyfus92]

🚢 🚢 🚢 🚢 🚢 🚢