[docs] Redesign the docs site frame, palette and components - #6948
Merged
Merged
Conversation
Contributor
📘 Docs preview
This comment updates in place on every push. |
FlyoverWatch the flyover → · 3 chapters · 52 files This flyover is shared with the repo maintainer @mmabrouk's permission. Please don't mark it as spam. If you are not satisfied with the generated content, we'd greatly appreciate any feedback in the comments instead.
9306944 · comment /flyover to refresh this for the latest commits · flyovers |
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (7)
🚧 Files skipped from review as they are similar to previous changes (2)
Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review. 📝 SummarySummary by CodeRabbit
WalkthroughThe documentation site is reorganized around a shared sidebar layout, a new navbar and footer, modular design tokens and styles, updated changelog and roadmap pages, redesigned content components, and improved Stream embed loading behavior. ChangesDocumentation redesign
Priority: ➖ Normal Estimated code review effort: 4 (Complex) | ~60 minutes Merge Risk: 🔵 Low · up to When the Stream SDK is delayed or unavailable, a loaded embedded video can remain hidden behind its loading placeholder for up to eight seconds. This is a bounded presentation issue but should be accepted knowingly or fixed before merge. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Full details: Docstring CoverageExplanation Docstring coverage is 33.33% which is insufficient. The required threshold is 60.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 54 functions across 28 files. (3 skipped: 3 unsupported.)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Advanced
Run ID: ea312725-9913-452e-bc56-6d050cdcef75
📒 Files selected for processing (52)
docs/design/docs-redesign/plan.mddocs/docusaurus.config.tsdocs/src/clientModules/streamSkeleton.tsdocs/src/components/CARD_ICON_USAGE.mddocs/src/components/CustomCardExample.mdxdocs/src/components/CustomDocCard.tsxdocs/src/components/SectionRail/index.tsxdocs/src/components/SidebarShell/index.tsxdocs/src/components/SidebarShell/styles.module.cssdocs/src/css/api.cssdocs/src/css/changelog.cssdocs/src/css/content.cssdocs/src/css/custom.cssdocs/src/css/footer.cssdocs/src/css/media.cssdocs/src/css/navbar.cssdocs/src/css/search.cssdocs/src/css/sidebar.cssdocs/src/css/tokens.cssdocs/src/css/typography.cssdocs/src/pages/roadmap.module.cssdocs/src/pages/roadmap.tsxdocs/src/theme/BackToTopButton/index.tsxdocs/src/theme/BlogLayout/index.tsxdocs/src/theme/BlogListPage/styles.module.cssdocs/src/theme/BlogPostItem/index.tsxdocs/src/theme/BlogPostItem/styles.module.cssdocs/src/theme/BlogSidebar/Desktop/index.tsxdocs/src/theme/BlogSidebar/Desktop/styles.module.cssdocs/src/theme/BlogTagsPostsPage/index.tsxdocs/src/theme/BlogTagsPostsPage/styles.module.cssdocs/src/theme/DocCard/index.tsxdocs/src/theme/DocCard/styles.module.cssdocs/src/theme/DocCardList/index.tsxdocs/src/theme/DocCardList/styles.module.cssdocs/src/theme/DocSidebar/Desktop/Content/index.tsxdocs/src/theme/DocSidebar/Desktop/Content/styles.module.cssdocs/src/theme/Footer/index.tsxdocs/src/theme/Footer/styles.module.cssdocs/src/theme/Icon/Copy/index.tsxdocs/src/theme/Icon/Menu/index.tsxdocs/src/theme/MDXComponents.tsxdocs/src/theme/Navbar/Content/index.tsxdocs/src/theme/Navbar/Content/styles.module.cssdocs/src/theme/Navbar/Layout/index.tsxdocs/src/theme/Navbar/MobileSidebar/PrimaryMenu/index.tsxdocs/src/theme/NotFound/Content/index.tsxdocs/src/theme/NotFound/Content/styles.module.cssdocs/src/theme/TOC/index.tsxdocs/src/theme/TOC/styles.module.cssdocs/src/utils/formatDate.tsdocs/src/utils/navbarCtas.ts
💤 Files with no reviewable changes (2)
- docs/src/components/CustomCardExample.mdx
- docs/src/components/CARD_ICON_USAGE.md
Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.
…ette tokens.css owns every colour and frame measurement (light + derived dark); typography, navbar, sidebar, content, media, search, changelog and api each get their own file. Drops the invalid values, the :global() rules that never applied, and the hashed module class selectors.
…ebar The section links leave the second navbar row and render as menu rows above the page sidebar (SectionRail, mounted in the ejected DocSidebar content). SidebarShell gives non-docs pages the same sidebar + main frame. The TOC gets an "On this page" title. Reference/Self-host/Enterprise get activeBasePath so the rail highlights on every page of a section.
BlogLayout is ejected into SidebarShell; BlogSidebar/Desktop lists the latest releases (title + date) under the rail. List rows take the 152px meta column, mono version chip and arrow Read more from the design.
Status links jump to the sections; Category links filter the cards. Cards drop the hover lift and coloured labels, dates read '22 August 2026', and each section header shows its count.
Main column padding is a flat 56px (the row/col pair cancels out), the search field is 260x32 border-box, a lone Next card spans the column, a group's pages sit flush with their label, list media sits 16px above its summary, and filter buttons keep the 13px row size.
Changelog entry pages no longer render the TOC block; the column-width override is scoped to the layout row so API request/response panels keep their split; the mobile header uses the navbar padding variable so the search box aligns with the edge; roadmap anchors clear the fixed header; the shell keeps top padding on mobile; <Video> is framed for any host; static roadmap data is derived at module scope.
An ejected Footer renders the logo, X / LinkedIn / GitHub / Slack, four link columns (Product, Deploy, Company, Legal) from themeConfig.footer, and a copyright row. On pages with a sidebar it is offset by the sidebar width and carries the sidebar's rule so the column reads as one. The GitHub and Slack icons leave the header and the hamburger menu.
A system / light / dark segmented control in the footer's bottom row, driven by useColorMode's colorModeChoice; the header's toggle is gone.
The page title, TOC and first rail row share y=80; the header CTAs end on the reading column's right edge. Small laptops (997-1200px) get a 240px sidebar, 200px TOC and 32px gutters; tablets get 32px gutters in the header, content and footer, and the footer keeps four columns; the version pill stays visible beside the logo on mobile; roadmap card titles and dates stack on phones.
…debar group titles
…pes in the navbar
ashrafchowdury
force-pushed
the
docs/redesign-frame
branch
from
September 17, 2026 23:44
09ab0b9 to
7f3a42e
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Advanced
Run ID: a02b53a8-def8-471f-a4c3-03c6b3e1d241
📒 Files selected for processing (3)
docs/src/clientModules/streamSkeleton.tsdocs/src/css/navbar.cssdocs/src/theme/Navbar/Content/styles.module.css
Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.
Contributor
Author
|
The preview is not working normally as usual |
…er dividers; 240px search field
…CTA; search as a ghost icon below the sidebar breakpoint
…e version selector there
… close button; rows full width; no version selector in the drawer
ashrafchowdury
enabled auto-merge
September 18, 2026 10:48
mmabrouk
approved these changes
Sep 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
The docs site still had the Docusaurus default frame: a two-row header with the section links in it, blue links, coloured callouts, a centred changelog and roadmap that did not match the docs pages, and one 1,861-line
custom.cssthat had grown by accretion. The redesign in the Claude Design artifact (docs page, changelog, roadmap) moves the site to a single header row, a section rail at the top of the sidebar, a neutral palette with a derived dark mode, and one reading column for every page type.Changes
The frame. One header row (logo, version pill, search, theme toggle, the two CTAs). The section links (Docs, Reference, Roadmap, Changelog, Self-host, Enterprise) move into a rail at the top of the sidebar. The reading column is 720px with a 240px "On this page" column. The footer sits beside the sidebar and carries the social links, four link columns, the copyright, and a system/light/dark switch. The changelog list, changelog entries, the roadmap and the 404 page all render inside this frame through one
SidebarShellcomponent instead of their own layouts.The palette.
src/css/tokens.cssis now the only place colours and frame measurements are defined (--bgdefault,--contentprimary,--borderdefault,--radius-*,--doc-content-width, ...), with the dark values derived from the light ones. Every other stylesheet reads those names. The oldcustom.cssis split by region:typography,navbar,sidebar,content,media,search,changelog,api,footer.Components, restyled on those tokens: code blocks (soft panel, ghost copy icon, no word-wrap toggle), inline code, tables (full width, header strip, hairline rows, wide tables scroll), admonitions (faint semantic tint), blockquotes, tabs, doc cards (two-column grid), prev/next pagination (compact buttons), the search page and the DocSearch modal, the mobile "On this page" panel, and the hamburger menu. Cloudflare Stream embeds get a skeleton while the player boots. The floating back-to-top button and the unlinked
/changelog/archivepage are removed.Three bugs surfaced while doing this and are fixed here:
clip-path: inset(0)on the sidebar container for its hideable animation, and that clips fixed descendants too.<Stream responsive>positions its iframe absolutely and only adds the 16:9 box after the player reports the video size, so for the first ~600ms the skeleton's play glyph sat on top of the paragraph below. The iframe is static from first paint now.[class*="generatedIndexPage"] article:first-child { display: none }) hid the first card and the lead paragraph on every generated category index, including the first FAQ entry. It is scoped to the OpenAPI info card.Left for a follow-up: the OpenAPI operation pages (method badges, request panel, schema styling) are still on the plugin's own skin.
Tests
pnpm buildpasses (production config,onBrokenLinks: throw).What to QA
/changelog,/roadmap,/faq/platform, a wrong URL. All four sit in the same frame as a docs page./guides/control-what-an-agent-can-doon a slow connection: the Stream box holds its space with a play glyph, nothing overlaps the text below./faq/platform: two cards, both entries present./faq/platform/api-rate-limits: the rate-limits table scrolls sideways inside the column./1.0/prompt-engineering/quick-start(v1.0 docs) still renders its inline cards.