docs: use better examples + document cascade layers

[trueberryless]

Description

• general clean up of docs
• add examples/ with all possible Starlight components

Note

Cascade layer docs depend on #50 to be merged before this PR

[sgoudham]

Just a general comment, do we need to add all this documentation? Felt like the components on the current page gave a pretty decent overview of how the theme looked already.

Feels like a lot of duplication from Astro's own docs 🤔

[trueberryless]

Just a general comment, do we need to add all this documentation? Felt like the components on the current page gave a pretty decent overview of how the theme looked already.

Feels like a lot of duplication from Astro's own docs 🤔

I personally wouldn't see such a duplication as a bad thing, as the user can get the feel of the theme before actually using it. Alto I have to agree that it makes more sense if not only colors get adapted, but also eg border radius, margins, paddings and other positional modifications.

For me there are basically two arguments for the more detailed pages:

• It's consistent and standardized with other themes. Users can expect to be able to play around and look at every theme demo the same way. This structure is already used in Rapide, Next.js and Flexoki themes to my knowledge. IMHO this also strengthens the uniformity and also kinda marketing.
• If we maybe add positional adjustments in the future to make the theme more modern, we have nice references to see the changes in action already (even more detailed). Because this detailed version is very bulletproof, covering all the different possibilities of Starlight.

But maybe you want to keep things minimalist here. I see a valid point in not including it, on the other hand, with the given advantages + already existing changes here, I don't see a huge benefit in not including it as I listed my points above...

[sgoudham]

Alto I have to agree that it makes more sense if not only colors get adapted, but also eg border radius, margins, paddings and other positional modifications.

Yeah, the organisation's philosophy is to avoid changes outside of colours as much as possible, and for this theme specifically, the less tweaks the better.

If we maybe add positional adjustments in the future to make the theme more modern, we have nice references to see the changes in action already (even more detailed). Because this detailed version is very bulletproof, covering all the different possibilities of Starlight.

I'd personally push back on this due to my statement above. We should stick to the defaults as much as possible, and only move away for adherence to the style guide.

[trueberryless]

I reverted the example changes, just moved all docs to the root of /docs now.
Since I am currently setting up my new PC and have pnpm + node not installed yet, I have not tried it out, please do try it out before approving, thanks!