Low-Effort/High-Value Redesign Proposal

[FredKSchott]

What version of starlight are you using?

latest

What is your idea?

I've heard mixed reviews on the current design of Starlight from users. This is a shame because there are so many great design decisions that went into Starlight, but I think a few choices (or maybe, accidental side-effects) are holding it back.

This is my proposal for small, surgical efforts to improve the design and user experience of Starlight. These changes are scoped so that they could be collectively tackled in a few days (no "burn it all down" approach allowed here) but have a significant outsized impact on UX.

Before

After

(messed up the sidebar in the screenshot, so here's a clean shot:)

Detailed Proposal

1. The current design uses font size + font weight to signify importance, where font weight alone would be enough. The result is that there are like 6-8 different font sizes on the screenshot shared, which makes it harder for brain to parse the information hierarchy. This proposal simplifies this down to ~3 font sizes, clarifying the link between font size and meaning.
2. The current design uses light-grey grid lines inconsistently, sometimes used to separate different UI and in other places used stylistically. Ex: title and body aren't differenent the same way that nav and body are different. nav and body aren't different the same way that body and sub-navigation are different. The result is that the page feels more "busy" with many meaningful layout components, when really there are only very few. The proposal simplifies this, and uses grid lines sparingly and to signify important page layout elements.
3. The current design doesn't seem to have an intention behind where your eye should go when you first visit the page. The highlighted item in the nav has the most color on the page, so your eyes are naturally drawn there. The title then has to yell at you in a big font to compete to drag your eyes there instead (IMO the correct place for your eyes to go first). This proposal removes loud visual elements on the page and is then able to reduce the font size of the title as a result to something less "shout-y" :)
4. The current design of the asides really demand your attention in a way that breaks up and distracts the reader from the main content on the page, more than the author intended. Reducing the background color luminosity, simplifying the border, and simplifying the layout all make the aside flow more naturally.
5. There is also not enough distinction between "note" and "tip" asides, and it's not clear that purple = tip. The word tip isn't shown anywhere. This proposal simplifies tips and notes to the same color palette. If the distinction between them is actually meaningful, then this proposal would suggest adding a "TIP:" prefix, badge, or some other flair to tips but otherwise keep them using the same design as a regular note).
6. Not tackled in the screenshot above, but still a part of the proposal: The current design mixes rounded corners and 90deg corners inconsistently. Search bar input has a border radius, nav items have a border radius, but asides in the content do not, code snippets do not.

Why is this feature necessary?

I hope I've made the case for why these aren't subjective design preferences but are instead rooted in more objective design theory.

My focus will be on getting consensus on these specific changes. There are probably more suggestions that someone could make, and I'm happy to hear others' suggestions in this discussion as long as they keep to the scope of "low-effort, high-impact".

It will take me a while to prioritize a PR to address this, but I would emphatically support anyone who is able to take a stab at this in an eventual PR.

Do you have examples of this feature in other projects?

No response

Participation

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

[OliverSpeir]

I love it, other than this bit which I guess isn't intential. I'd say extending the search bar is good but not at the sacrifice of the light and language selectors.

From the original:

From the proposal:

Also would love the see the mobile view's menu svg go from hamburger to x when the menu is open as an add on

[FredKSchott]

ack you're right, that was an early experiment that I was playing around with but didn't finish, and didn't realize had made it into the final screenshot. Ignore the header, except for the background color change to match the rest of the page!

[HiDeoo]

Had a small amount of free time so I started playing around with some suggested changes to get a more broad idea of how things might look and feel in a live version, what difficulties might arise, etc.

Warning

The changes have been made to get a visual idea of how things might look and feel. They are not meant to be perfect, final or close to how some changes might actually be implemented with proper refactors, etc. Just a quick and dirty PR.

I'd like to also say, my point is not to say that these changes are good or bad, I'm usually fine at implementing designs, but not the best at judging them. My goal is mostly to get the ball rolling, get feedback, and discuss how easy or more involved some changes might be.

Preview URL: https://starlight-git-fork-hideoo-hd-draft-ui-chan-55d558-astrodotbuild.vercel.app/getting-started/

1. First, I'd like to quote:

   There is also not enough distinction between "note" and "tip" asides, and it's not clear that purple = tip. The word tip isn't shown anywhere.

   By default, all aside types have distinct labels. The fact that "Tip" did not appear in the screenshot was due to the aside having a custom title not mentioning explicitly that it was a tip. Having only 3 different aside colors may feel a bit limiting compared to other documentation tools.

2. The header background removal looks fine in light mode, where the sidebar and content were already of the same color. However, in dark mode, the sidebar is using a different color from the content, so the header background removal made the sidebar look a bit weird so I ended up removing the sidebar background color as well. If one unique color looks fine on light mode, I wonder if this is the same for dark mode. I personally think it looks worse in this case so maybe we would need to have a different approach for dark mode.

3. Regarding asides, in the suggestion screenshot, the title (either the type or the custom title) is inlined with the content. This is something I did not implement as this would probably require changing the generated markup for such aside. Altho, this raises the question of how would this work if the first element of the aside is not a text node, e.g. a code block or a list? Do we have different rules based on the first element and fallback to the current behavior if it's not a text node?

4. I tried to blindly add rounded corners to everything: code blocks, cards, file tree, etc. I assumed this was the suggested direction as the aside had rounded corners in the screenshot.

5. This is very personal, but I'm a bit disturbed by the space above the table of contents.

6. Still personal, but I think removing caret icons from sidebar groups while still being collapsible feels a bit weird.

[FredKSchott]

Love this!!!

This is very personal, but I'm a bit disturbed by the space above the table of contents.

The idea with this suggestion is to group the right-nav with the page content, so that your brain parses it as a part of the page context vs. larger site navigation context. To do this, it's top-padding should be === the vertical distance to the page title, or the vertical distance to the first paragraph. I'd be fine with either, I think! Currently, it's a little off from the page title padding (orange line).

Still personal, but I think removing caret icons from sidebar groups while still being collapsible feels a bit weird.

I don't want to derail too deep on this one point BUT... the idea of collapsing sections doesn't make sense for me on desktop. Because all sections start as expanded, I'm not sure what the use-case is for a user wanting to collapse a section. "As a user, I want to collapse a section so that I can...". I'd rather remove the section collapsing entirely on desktop, caret and behavior.

[delucis]

I'd rather remove the section collapsing entirely on desktop, caret and behavior.

Starlight supports setting groups to be collapsed by default, so I’m not sure we can do this. (Astro’s Docs don’t use this — we prefer to keep everything visible rather than forcing people to guess what category something might be in — but it was a very early user request and is particularly useful for collapsing sub-groups in bigger sidebars.)

[FredKSchott]

By default, all aside types have distinct labels. The fact that "Tip" did not appear in the screenshot was due to the aside having a custom title not mentioning explicitly that it was a tip. Having only 3 different aside colors may feel a bit limiting compared to other documentation tools.

This is helpful context! In that case, I think my feedback here can be boiled down into two distinct points:

1) The title doesn't meaningfully communicate anything new or more clearly in a smaller aside, while adding a new distinct piece of information that your brain has to parse. If you compare this aside currently in the Starlight codebase vs. my proposed change, you can hopefully see what I'm talking about in terms of ease of communication:

I know that some asides are many paragraphs, in which case I do see that there probably is a good case for a standalone title (current design) that helps summarize the entire aside so that you can decide whether you read it at all vs. skip it because it's not relevant to you. The problem is that the majority of asides I see in practice are smaller callouts, not longer deep-dives.

My suggestion would be to use the more compact design for smaller asides, and the current design for larger asides. If you can make it an option passed to the component, great! If you can automatically detect the length as a default behavior, even better!

2) I still don't know what the difference is between "note" and "tip" or when I should use one vs the other. As a docs writer and reader, I basically only ever see an aside used to communicate:

• Primary Note ("hey, btw, here's something special to call attention to, like the "try it in your browser!" callout in the screenshots above")
• Secondary Note ("hey, btw, here's some extra info that you might find interesting, but isn't really required reading / feel free to skip")
• Caution ("hey, watch out for this thing! We're calling this out because it's important!")

My suggestion here would be to revisit the current 4 aside colors, understand their purpose to the reader/author, clarify/document that purpose, and then make sure the design communicated the purpose. Currently, "Note" and "Tip" are two different colors that feel of equal importance, and their colors (blue and purple) don't communicate anything meaningful like yellow/red do. I'd expect one of the two to communicate "secondary" more in its design. Like:

[FredKSchott]

I'd rather remove the section collapsing entirely on desktop, caret and behavior.

Starlight supports setting groups to be collapsed by default, so I’m not sure we can do this. (Astro’s Docs don’t use this — we prefer to keep everything visible rather than forcing people to guess what category something might be in — but it was a very early user request and is particularly useful for collapsing sub-groups in bigger sidebars.)

Gotcha! In that case, I'm scoping my design feedback to be as not-disruptive as possible, so if this is a feature that y'all want to keep then no need to tackle this here. In that case, I'd assume the current carets to collapse sidebar sections would remain (maybe updated a bit to match the new design language of the sidebar).

[ElementalCrisis]

Hello,

I stumbled across this discussion as I've been looking into doing some design changes on our docs I've been working on; I was just wondering if this proposal was still in discussion? The example design shown is pretty close to what I was thinking and would rather wait for the experts to do it than hack my way through it. :)

[FredKSchott]

cc @delucis -- Chris and I were just talking about this. I think there's buy-in from the team but the PR to implement it may have gotten lost (maybe from @HiDeoo).

I'm leaving it to @delucis & the team to take this from here, but I'm happy to jump in and answer any questions / provide any follow-up where I can continue to be helpful.

[evadecker]

@delucis Were these the design changes you alluded to in my PR?

If there's no code champion for this work right now I'm happy to step up there; visually this is more-or-less exactly what I would have recommended.

[delucis]

Not necessarily exactly these — I’m not 100% sold on all of the suggestions here — but would definitely love to have you championing changes you think could be valuable!

My priorities more or less:

• Maintain clarity and accessibility of content structure.
• Keep our base CSS simple enough that people overriding it aren’t struggling.
• Keep our base styles neutral enough that they work well as a starting point for people to either use as is or customize.
• Keep a holistic overview of Starlight’s design system in mind — we have a wide range of components at this point, so it’s important for changes to be made with the full range in mind.
• When making design changes, keep Starlight’s appearance across viewport sizes in mind, not only a desktop view, and same for dark/light modes.

Some quick thoughts on the proposals in this thread:

• The design suggestions in this discussion were thrown together quickly as a conversation starter — don’t feel any restriction to stick to them or not challenge them. As you can see from @HiDeoo’s comment above (and his preview deployment of the changes), there were quite a few details that needed more thought for how things are actually used in practice.

• I’d push back on “The current design uses font size + font weight to signify importance, where font weight alone would be enough” in relation to page content. Heading hierarchy (h1/h2/h3, etc.) is important to preserve for readers as it helps them understand page structure and relationships. In other parts of the UI, this can make sense though.

• “The current design mixes rounded corners and 90deg corners inconsistently” — this was actually an intentional design choice: rounded corners are used for interactive components, 90° corners for static content. (Doesn’t mean it can’t be changed! But FYI.)

Our original design document for reference is in Figma: https://www.figma.com/design/GrDkcguAR7tSWPFuLVDixq/Theme---Starlight-Docs?node-id=454-34005

Anyone should feel free to fork that and use it to test ideas, if it’s helpful!

[evadecker]

Thank you for the thorough writeup!

Follow-up questions:

• Do you intend for the Figma file to remain up-to-date with the components in the repo?
• For the scope of changes recommended at the start of this discussion is it preferable to address them all in one PR, or chunk the changes into smaller PRs (for example, one for spacing and alignment, one for typography, etc)?

[delucis]

Do you intend for the Figma file to remain up-to-date with the components in the repo?

I guess that sounds great ideally, but it isn’t 100% essential. I think I’d be able to grant access if you wanted to e.g. create a new page for your proposals? Up to you, how you prefer to work — forking and keeping your own version would be fine, as would skipping Figma entirely if it isn’t helpful.

is it preferable to address them all in one PR, or chunk the changes into smaller PRs?

In general I think working on things in smaller chunks is helpful — helps keep discussion focused and makes PRs easier to review. That said, obviously sometimes these things intersect and it makes sense to tackle several things together and avoid being in some “in between” state. So happy for you to use your judgement for what makes sense to work on together and where to break things up.

[evadecker]

If there isn't a current owner to push these design changes forward I'd be happy to dive in here.

[jermanuts]

I really like Asides redesign, but I feel like other redesigns undermine accessibility a bit. How about about we highlight selected sidebar page? like Mkdocs material does:

EDIT: tbf, I don't mind the current design of sidebar, it is actually more accessible IMO. If we followed Mkdocs material it will also look like table of contents. Which looks a bit like the one proposed here too. Anyways, Asides proposed in this discussion is a must!

[illright]

Hi! I just made a PR with the redesign of the sidebar, and I'm curious to know what you meant by "undermine accessibility". Was that meant about the new sidebar design? If so, would a thicker line, such as the one I did in that PR, help?

[jermanuts]

Yours is much better, thanks for opening these amazing PRs btw.

I think having a background color is much more noticeable than a left border, but Starlight team or people that are more expert in accessibility might have another option.

[illright]

Just made a series of PRs including some of the proposed design changes, review and discussion welcome!

• Make asides less prominent #2659
• Remove the header color #2660
• Enlarge header icons #2661
• Reduce the prominence of the selected sidebar item #2662