Starlight components documentation improvements

[HiDeoo]

This discussion is a proposal to improve Starlight components documentation.

What is the problem?

At the moment, all the Starlight components are documented in a single page and some issues are present:

• The page is becoming too long and this will not scale well as we add more components.
• The table of contents does not provide a good overview of the components props and including them all in the table of contents would make it too long.
• It can be hard to easily identify what is part of the documentation vs the rendered component examples.

What is the proposed solution?

Following Chris's suggestion, a potential idea would be to move the components documentation to a dedicated sidebar group with the first page being an overview on how to use built-in components in Starlight and then have a page for each component.

Each component page would have a similar structure at the top of the page:

• A brief description of the component.
• A visual example of the component in action.
• A code block showing only how to import the component (this one is pretty personaly, I often just want to copy the import statement and not the whole code block — this is also something I noticed in quite a few other design systems documentation).

After that, I did some research on many design systems documentation and I found that multiple approaches could be taken.

Props approach

After the common section described above, this approach list all the props available for the component with a brief description of each one, include the type, default value if any, required or not. Then a code sample is shown for this specific prop with a visual example of the same code.

Usage and props approach

This approach starts with an “Usage” section with sub-sections for each use case of the component in plain English, e.g. “Sync tabs”, “Add icons to tabs”, etc.
Each sub-section would only contain a small description of the use case and a code sample with a visual example.

After that, a “Props” section would list all the props available for the component with a brief description of each one, include the type, default value if any, required or not and link to the sub-section in the “Usage” section where this prop is used.

Usage only approach

This approach is similar to the previous one but does not include a “Props” section. Instead, each sub-section in the “Usage” section would also contain the prop advanced information like type, default value, required or not in addition to the code sample and visual example.

Personal opinion

I am personally leaning towards the “Usage and props” approach as the usage section keeps the documentation friendly for newcomers and the props section provides a reference for more advanced users.
If you're looking for a specific use case, you can find it in the table of contents and if you're looking for a specific prop, you can also find it in the table of contents.
Links between the “Usage” and “Props” sections also make it easier to navigate between them.

Feedback

Any feedback on the proposed organization is welcome, especially if you have a preference for one of the approaches or if you have another idea on how to structure the documentation. Same goes if you have ideas of section that were missed or could be useful.

Note that the text itself in the screenshots is mostly placeholder so far and the structure is the main focus of this discussion.
Same goes for the code block + visual example design, which is mostly something quick I put together to illustrate the idea on how to emphasize that it's an example and not part of the documentation itself.

Participation

• I am willing to submit a pull request for this feature.

[sanscontext]

Pointed here from the Discord :)
One of the ways I approached this on a Jekyll platform was to have a "format demo" page (we called it the "bestiary" internally, as in the medieval catalogue of animals 😆 ) which gave an example of each of the different things available in one place. This meant you could look at the source page in the repo to see how it was built.
It was also super useful when we needed to update our CSS for Branding reasons, because we could see all the elements in one spot.

[delucis]

Ah yes, this is actually kind of the origin of our “Authoring Markdown” page, the initial version of which I wrote to have a quick reference for different elements while working on styles.

I’m not sure how useful a “kitchen sink” page is to your average user, but can definitely be handy for Starlight maintainers when working on styles. We often make temporary versions of these for a specific component when working on a PR for example.

[delucis]

Thanks for writing this up @HiDeoo and exploring the different options for structuring these pages.

I agree with you that the “Usage and props” approach feels most promising. I think a “props reference” is definitely valuable to have (it’s one of the things I miss most in our current setup), but I think it can stick to the terser reference style we have elsewhere, without large examples etc., i.e. just focused on prop name, type, and a brief description. With then the usage section allowing us to more easily group and describe the common usage patterns.

[HiDeoo]

The new components documentation is now available.