Update starlight docs

[mikemazara]

Reference Issues or PRs

PR 1 of 2
partial implementation of #25

• Tokens and typography — #9547c0 accent, sm/md/full radii, Geist + IBM Plex Mono self-hosted (12 woff2 → 2, no external requests), full type scale, Expressive Code syntax colours.
• Header and navigation — #f8f8f8 header at 56px with one hairline, nav tabs with a 2px accent underline, search as a bordered md input with Search docs… and a ⌘K chip, sidebar accent bar + fill, TOC eyebrow + accent bar + hairline, 375px drawer.
• Article page — breadcrumbs, Updated <date> • N min read meta row, hairline under the title block, prev/next cards.
• Landing — multi-column footer with brand, three link columns and bottom bar.

Chrome CSS is split into a new chrome.css so a Starlight upgrade has one file to review. Adds one option, nav; unset, header markup is unchanged, so existing packs upgrade without visual change.

Not included: callouts, tables, code-frame variants (Phase 4); hero, guides landing, 404, ⌘K modal (Phase 5); docs, screenshots, version bump (Phase 6). Ask AI and the version selector are out of scope. Was this page helpful? is deferred — no behaviour is specified for it.

What does this implement/fix?

Put a x in the boxes that apply

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds a feature)
• Breaking change (fix or feature that would cause existing features not to work as expected)
• Documentation Update
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no API changes)
• Build related changes
• Other (please describe):

Testing

• Did you test the pull request locally?
• Did you add new tests?

Documentation

Access-centered content checklist

Text styling

• The content is written with plain language (where relevant).
• If there are headers, they use the proper header tags (with only one level-one header: H1 or # in markdown).
• All links describe where they link to (for example, check the Nebari website).
• This content adheres to the Nebari style guides.

Non-text content

• All content is represented as text (for example, images need alt text, and videos need captions or descriptive transcripts).
• If there are emojis, there are not more than three in a row.
• Don't use flashing GIFs or videos.
• If the content were to be read as plain text, it still makes sense, and no information is missing.

Any other comments?

Accessibility notes, since this changes presentation site-wide:

• All text/background pairs clear WCAG AA in both themes. The axe sweep previously ran only in light mode; it now covers light and dark at both widths, which caught five dark-mode pairs below 4.5:1.
• Breadcrumbs render as a labelled nav; the page title keeps id="_top" for the skip link; exactly one nav tab is aria-current="page" and one "Site" landmark is exposed at any width.
• Search placeholder comes from injectTranslations, so it changes the real accessible name rather than being faked in CSS.
• Fixes an inherited Starlight issue where overflowing tables became scroll containers with no keyboard access at narrow widths.

[jbouder]

Not sure if maybe you need to push a commit or something, but i'm seeing a number of issues, based on the designs. A few to mention (see screenshots)

1. Sidebar: selected nav item has dark purple background, should be gray, with purple border on left, font, weight, and spacing looks off, and the looks to be more bold
2. Header: Search should be right aligned, the dark/light mode icons are off
3. Footer: showing partial width in the content area. I would think this would span the entire width of the page (outside of the content area) or not show on the content pages (only on the intro page). Might need to check with Smera on that.
4. Alert: doesn't match the design, should have a colored header and transparent body

[mikemazara]

@jbouder looks like your working with a stale build? I dont see many of the changes. that being said there is a bug with the footer, that i'll push a fix for. the designs only have the footer on the main page. the alerts styling is one of the first things i have in the second pr, but I can move it to this one?

[mikemazara]

@jbouder I just modified the script to make sure it regenerates dist when you run the dev server so that its never stale, so should be good now

[smeragoel]

Hi @mikemazara, thanks for working on this, looks neat! A few things:

1. Left navbar items:
   1. The hover state should have an underline on the text and a left border. Having these indicators essentally removes the contrast requirement for the background since we have non-colour indicators for hover.
   2. Focus rings should be the Nebari brand purple rather than black.
2. Breadcrumbs: the parent pages don't render as links and aren't clickable. The active page should use primary font color and parent pages are muted.
3. The table breaks long components at narrow widths (Overridden). I am curious what'd happen to long strings / literals / paths that ideally should not be broken.

4. Is Copy As Markdown in scope for this PR or the next one?
5. This would be a design fix but I personally don't like how light the code literals are, both in weight and color. What do others think?

[mikemazara]

@smeragoel:
1- updated!
2- I had the render as links slated for the next PR but thanks for catching the font colour oversight, I just updated both as I was already in there, should be sorted!
3- updated to hold the space, and only break at spaces. if for some reason a large url or something else gets inputed that doesnt have spaces, and it exceeds the container, then the cell becomes scrollable (maybe adding a design for an arrow indicator when that happens is a good idea?)
4- There is a separate issue for the copy button and behavior: #24
5- I agree i think it is a bit light. I think the colour is a bigger issue than the weight, as it makes it more dainty looking, but open to trying some variations

[smeragoel]

1. I am seeing the docs content panel shifted to the right side 🤔
2. Similarly, at mobile view size, there is a gap on the right size and the page content doesn't span the full available screen space. Also, the whole page scrolls horizontally.

3. One other thing is that I added a new color/background/canvas variable to NDS, which is a bit darker than the color we currently use for background fill. What'd be the best way to get that added to NDS?
4. For cell scrolling, from what I can tell, having the the scroll bar and the text being cut off should be enough indication for cell scrollability.
5. For the code text, I'll design the code literals and send that over separately.

[mikemazara]

@smeragoel Updated!
and as for adding a new theme colour, that would go into the nebari-design repo, and then we would run a token sync to updated it on this end

[smeragoel]

Thanks for the changes @mikemazara, looking good! I am previewing both this PR and PR #29 together. I will try to separate the feedback, but there might be some overlaps!

1. Hover interactions: A lot of components are missing hover interactions, mainly underline. I'm assuming that most (if not all) of them are being pulled from NDS, so not sure why we have this issue. For example,

   1. The homepage buttons Get Started, Read the Guides, don't have underline or bg color change on hover.
   2. Links (Install the theme etc.) are missing an underline on hover.
   3. For the popular pages row, it is a custom card so it doesn't have an NDS basis, but it will be nice to have hover interactions on it as well. Added the design here.

2. Footer:

   1. The logo should be left aligned with the text below it.
   2. What do you think of the footer content responsiveness? Right now, it extends to the same width as the text on the page. I am wondering whether it should span the entire available width?

3. Code literals: I designed updated code literals.

4. There are some fill clipping and border issues with the code preview.

5. The on-this-page sidebar is missing the hover interactions you added to the left sidebar.

[mikemazara]

@smeragoel another round!
as for the footer, i dont think it needs to go the full width, but theres an argument to be made about the footer and the header always spanning the full space. ive seen both in practice and cant say i have a preference. up to you, easy add if you want

[smeragoel]

1. Row card (Figma):

   1. Can we add some padding to row card
   2. We don't have a bg color change, just the underline on hover. Almost like link behaviour.
   3. Focus should encapsulate the entire clickable area

2. Card links don't have underline on hover.

Also, I like how the new code literals are looking!

[mikemazara]

1. Row card (Figma):

   1. Can we add some padding to row card
   2. We don't have a bg color change, just the underline on hover. Almost like link behaviour.
   3. Focus should encapsulate the entire clickable area

2. Card links don't have underline on hover.

Also, I like how the new code literals are looking!

I think all these live comments live in the changes in the next PR! will update #29 and keep you posted