[Docs] Fix cramped docs layout on mobile and tablet viewports

.changeset/responsive-docs-layout.md

@@ -0,0 +1,9 @@
+---
+"@cloudflare/kumo-docs-astro": patch
+---
+
+Improve mobile and tablet responsive layout of the docs site.
+
+- Introduce a tiered horizontal padding scale for docs content: tight on mobile, medium on tablet, full-width on desktop.
+- Move the desktop sidebar to the `lg:` breakpoint (≥1024px) so tablets use the mobile drawer UX instead of a cramped side-by-side layout.
+- Align padding across chrome bars (hamburger, sticky doc header) with content wrappers at each breakpoint for visual consistency.

packages/kumo-docs-astro/src/components/Header.astro

@@ -8,7 +8,7 @@ const kumoVersion =
 ---
 
 <header
-  class="sticky top-0 z-10 h-12 border-b border-kumo-hairline bg-kumo-canvas hidden md:flex"
+  class="sticky top-0 z-10 h-12 border-b border-kumo-hairline bg-kumo-canvas hidden lg:flex"
 >
   <div
     class="flex min-w-0 flex-1 items-center justify-end border-r border-kumo-hairline px-4"

packages/kumo-docs-astro/src/components/SidebarNav.tsx

@@ -351,7 +351,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
       {/* Mobile header bar with hamburger */}
       <div
         className={cn(
-          "fixed inset-x-0 top-0 z-50 flex h-12 items-center justify-between border-b border-kumo-hairline bg-kumo-canvas px-3 md:hidden",
+          "fixed inset-x-0 top-0 z-50 flex h-12 items-center justify-between border-b border-kumo-hairline bg-kumo-canvas px-3 md:px-6 lg:hidden",
         )}
       >
         <Button
@@ -369,7 +369,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
       {/* Mobile slide-out drawer */}
       <aside
         className={cn(
-          "fixed inset-y-0 left-0 z-50 flex w-72 flex-col border-r border-kumo-hairline bg-kumo-canvas md:hidden",
+          "fixed inset-y-0 left-0 z-50 flex w-72 flex-col border-r border-kumo-hairline bg-kumo-canvas lg:hidden",
           "transition-transform duration-300 will-change-transform",
           mobileMenuOpen ? "translate-x-0" : "-translate-x-full",
         )}
@@ -398,7 +398,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
       {/* Desktop: Left rail that always stays put */}
       <div
         className={cn(
-          "fixed inset-y-0 left-0 z-50 hidden w-12 bg-kumo-canvas ated md:block",
+          "fixed inset-y-0 left-0 z-50 hidden w-12 bg-kumo-canvas lg:block",
           "border-r border-kumo-hairline",
         )}
       >
@@ -418,15 +418,15 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
       </div>
 
       {/* Desktop: Kumo brand label - always visible, panel slides behind it */}
-      <div className="pointer-events-none fixed top-0 left-12 z-50 hidden h-12 items-center px-3 font-medium select-none md:flex">
+      <div className="pointer-events-none fixed top-0 left-12 z-50 hidden h-12 items-center px-3 font-medium select-none lg:flex">
         <h1 className="text-base">Kumo</h1>
       </div>
 
       {/* Desktop: Sliding panel that opens to the right of the rail */}
       <aside
         data-sidebar-open={sidebarOpen}
         className={cn(
-          "fixed inset-y-0 left-12 z-40 hidden w-64 flex-col bg-kumo-canvas md:flex",
+          "fixed inset-y-0 left-12 z-40 hidden w-64 flex-col bg-kumo-canvas lg:flex",
           "transition-transform duration-300 ease-out will-change-transform",
           sidebarOpen
             ? "translate-x-0 border-r border-kumo-hairline"

packages/kumo-docs-astro/src/components/docs/StickyDocHeader.tsx

@@ -111,9 +111,9 @@ export function StickyDocHeader({
       {/* Sticky header bar */}
       <header
         ref={headerRef}
-        className="sticky flex h-12 top-12 md:top-0 z-10 border-b border-kumo-hairline bg-kumo-elevated"
+        className="sticky flex h-12 top-12 lg:top-0 z-10 border-b border-kumo-hairline bg-kumo-elevated"
       >
-        <div className="flex min-w-0 flex-1 items-center justify-between px-4 md:border-r md:border-kumo-hairline">
+        <div className="flex min-w-0 flex-1 items-center justify-between px-3 md:px-6 lg:px-4 lg:border-r lg:border-kumo-hairline">
           <div
             className={cn(
               "flex items-center gap-2 transition-opacity duration-200",
@@ -161,7 +161,7 @@ export function StickyDocHeader({
             @cloudflare/kumo
           </a>
         </div>
-        <div className="hidden w-12 shrink-0 items-center justify-center md:flex">
+        <div className="hidden w-12 shrink-0 items-center justify-center lg:flex">
           <ThemeToggle />
         </div>
       </header>

packages/kumo-docs-astro/src/layouts/DocLayout.astro

@@ -56,11 +56,11 @@ const githubSourceUrl = sourceFile
     />
 
     <!-- Page Header -->
-    <div id="page-header" class="border-b border-kumo-hairline md:pr-12">
-      <div class="mx-auto md:border-r md:border-kumo-hairline">
-        <div class="mx-auto max-w-7xl p-12">
+    <div id="page-header" class="border-b border-kumo-hairline lg:pr-12">
+      <div class="mx-auto lg:border-r lg:border-kumo-hairline">
+        <div class="mx-auto max-w-7xl px-3 py-4 md:px-6 lg:p-12">
           <!-- Mobile: Copy page button above title -->
-          <div class="mb-3 md:hidden">
+          <div class="mb-3 lg:hidden">
             <CopyPageButton align="center" client:idle />
           </div>
           <div class="mb-3 flex items-center gap-3">
@@ -94,7 +94,7 @@ const githubSourceUrl = sourceFile
               )
             }
             <!-- Desktop: Copy page button on far right -->
-            <div class="hidden md:block md:ml-auto">
+            <div class="hidden lg:block lg:ml-auto">
               <CopyPageButton client:idle />
             </div>
           </div>
@@ -106,16 +106,16 @@ const githubSourceUrl = sourceFile
     </div>
 
     <!-- Content -->
-    <main class="flex grow flex-col md:pr-12">
-      <div class="mx-auto w-full grow md:border-r md:border-kumo-hairline">
+    <main class="flex grow flex-col lg:pr-12">
+      <div class="mx-auto w-full grow lg:border-r lg:border-kumo-hairline">
         <!-- Select TOC: visible below xl, hidden at xl+ where sidebar takes over -->
-        <div class="xl:hidden sticky top-24 md:top-12 z-1 border-b border-kumo-hairline bg-kumo-canvas">
-          <div class="mx-auto max-w-7xl px-2 md:px-3 py-3">
+        <div class="xl:hidden sticky top-24 lg:top-12 z-1 border-b border-kumo-hairline bg-kumo-canvas">
+          <div class="mx-auto max-w-7xl px-3 py-3 md:px-6 lg:px-12 lg:pr-10">
             <TableOfContents layout="select" headings={headings.length > 0 ? headings : undefined} client:load />
           </div>
         </div>
 
-        <div class="mx-auto max-w-7xl p-12 pr-10">
+        <div class="mx-auto max-w-7xl px-3 py-4 md:px-6 lg:p-12 lg:pr-10">
           <div class="grid grid-cols-1 gap-16 xl:grid-cols-[3fr_1fr]">
             <div class="kumo-prose prose max-w-none min-w-0">
               <slot />

packages/kumo-docs-astro/src/layouts/MainLayout.astro

@@ -41,7 +41,7 @@ const currentPath = Astro.url.pathname;
     <!-- Main content area - margin controlled by CSS :has() based on sidebar state -->
     <div
       id="main-content"
-      class="main-content mt-12 md:mt-0 md:ml-12 transition-[margin] duration-300"
+      class="main-content mt-12 lg:mt-0 lg:ml-12 transition-[margin] duration-300"
     >
       <slot />
     </div>
@@ -50,7 +50,7 @@ const currentPath = Astro.url.pathname;
 
 <style is:global>
   /* Use CSS :has() to detect sidebar state and adjust main content margin */
-  @media (min-width: 768px) {
+  @media (min-width: 1024px) {
     /* When sidebar is open, add full margin */
     body:has(aside[data-sidebar-open="true"]) .main-content {
       margin-left: 304px; /* 48px rail + 256px sidebar panel */

packages/kumo-docs-astro/src/pages/index.astro

@@ -7,9 +7,9 @@ import { HomeGrid } from "../components/demos/HomeGrid";
 <MainLayout title="Kumo" description="Kumo – a modern component library">
   <div class="flex flex-col">
     <Header />
-    <main class="flex grow flex-col md:pr-12">
+    <main class="flex grow flex-col lg:pr-12">
       <div
-        class="mx-auto w-full grow md:border-r md:border-kumo-hairline"
+        class="mx-auto w-full grow lg:border-r lg:border-kumo-hairline"
       >
         <HomeGrid client:only="react" />
       </div>