feat(docs): revamp site with Starlight 0.39 re-skin and landing page

packages/docs/astro.config.mjs

@@ -20,7 +20,33 @@ export default defineConfig({
         SiteTitle: "@/components/starlight/SiteTitle.astro",
         Hero: "@/components/starlight/Hero.astro",
       },
-      customCss: ["./src/styles/custom.css"],
+      expressiveCode: {
+        styleOverrides: {
+          // Frame cosmetics only — Night Owl (Starlight's default theme) carries
+          // the syntax palette untouched. We just round the corners, soften the
+          // shadow, and tint the chrome to the brand.
+          borderRadius: "0.6rem",
+          borderColor: "var(--sl-color-gray-5)",
+          frames: {
+            // Let `frameBoxShadowCssValue` own the shadow entirely.
+            shadowColor: "transparent",
+            frameBoxShadowCssValue: "0 24px 60px -34px rgba(0, 0, 0, 0.5)",
+            // Active code-tab indicator picks up the magenta brand pop.
+            editorActiveTabIndicatorTopColor: "var(--mty-magenta-hot)",
+            editorActiveTabIndicatorBottomColor: "transparent",
+            editorTabBarBorderBottomColor: "var(--sl-color-gray-5)",
+            // Copy button tinted to the neutral surface tokens.
+            inlineButtonBorder: "var(--sl-color-gray-5)",
+          },
+        },
+      },
+      customCss: [
+        // Display typeface — Fraunces (variable: weight + optical-size axes,
+        // upright + italic). Body/mono stay on Starlight's system stacks.
+        "@fontsource-variable/fraunces/standard.css",
+        "@fontsource-variable/fraunces/standard-italic.css",
+        "./src/styles/custom.css",
+      ],
       social: [
         {
           icon: "github",
@@ -42,15 +68,15 @@ export default defineConfig({
       sidebar: [
         {
           label: "Hello, World!",
-          autogenerate: { directory: "guides/hello-world" },
+          items: [{ autogenerate: { directory: "guides/hello-world" } }],
         },
         {
           label: "Core Concepts",
-          autogenerate: { directory: "guides/core-concepts" },
+          items: [{ autogenerate: { directory: "guides/core-concepts" } }],
         },
         {
           label: "Backend Adapters",
-          autogenerate: { directory: "guides/backend-adapters" },
+          items: [{ autogenerate: { directory: "guides/backend-adapters" } }],
         },
         {
           slug: "guides/roadmap",

packages/docs/package.json

@@ -15,7 +15,8 @@
     "node": "24.x"
   },
   "dependencies": {
-    "@astrojs/starlight": "^0.38.2",
+    "@astrojs/starlight": "^0.39.3",
+    "@fontsource-variable/fraunces": "^5.2.9",
     "astro": "catalog:",
     "motion": "^12.23.12",
     "sharp": "^0.34.2",

packages/docs/src/components/AstroLogo.astro

@@ -0,0 +1,59 @@
+---
+/**
+ * Astro brand mark — used as a `slot="logo"` inside <CodeCard>. Astro ships two
+ * official logomarks: a gradient-on-dark version (white star + comet tail) and a
+ * solid #17191E version for light backgrounds (the white knockout would vanish
+ * on light). This component owns that swap itself, keyed off the resolved theme.
+ */
+---
+
+<span class="astro-logo">
+  <!-- Gradient logomark — shown in dark mode. -->
+  <svg class="astro-on-dark" viewBox="0 0 85 107" aria-hidden="true">
+    <defs>
+      <linearGradient
+        id="mty-astro-mark"
+        x1="22.4702"
+        y1="107"
+        x2="69.1451"
+        y2="84.9468"
+        gradientUnits="userSpaceOnUse"
+      >
+        <stop stop-color="#D83333"></stop>
+        <stop offset="1" stop-color="#F041FF"></stop>
+      </linearGradient>
+    </defs>
+    <path
+      fill="url(#mty-astro-mark)"
+      d="M27.5894 91.1365C22.7555 86.7178 21.3444 77.4335 23.3583 70.7072C26.8503 74.948 31.6888 76.2914 36.7005 77.0497C44.4375 78.2199 52.0359 77.7822 59.2232 74.2459C60.0454 73.841 60.8052 73.3027 61.7036 72.7574C62.378 74.714 62.5535 76.6892 62.318 78.6996C61.7452 83.5957 59.3086 87.3778 55.4332 90.2448C53.8835 91.3916 52.2437 92.4167 50.6432 93.4979C45.7262 96.8213 44.3959 100.718 46.2435 106.386C46.2874 106.525 46.3267 106.663 46.426 107C43.9155 105.876 42.0817 104.24 40.6845 102.089C39.2087 99.8193 38.5066 97.3081 38.4696 94.5909C38.4511 93.2686 38.4511 91.9345 38.2733 90.6309C37.8391 87.4527 36.3471 86.0297 33.5364 85.9478C30.6518 85.8636 28.37 87.6469 27.7649 90.4554C27.7187 90.6707 27.6517 90.8837 27.5847 91.1341L27.5894 91.1365Z"
+    ></path>
+    <path
+      fill="#fff"
+      d="M0 69.5866C0 69.5866 14.3139 62.6137 28.6678 62.6137L39.4901 29.1204C39.8953 27.5007 41.0783 26.3999 42.4139 26.3999C43.7495 26.3999 44.9325 27.5007 45.3377 29.1204L56.1601 62.6137C73.1601 62.6137 84.8278 69.5866 84.8278 69.5866C84.8278 69.5866 60.5145 3.35233 60.467 3.21944C59.7692 1.2612 58.5911 0 57.0029 0H27.8274C26.2392 0 25.1087 1.2612 24.3634 3.21944C24.3108 3.34983 0 69.5866 0 69.5866Z"
+    ></path>
+  </svg>
+  <!-- Solid logomark — shown in light mode. -->
+  <svg class="astro-on-light" viewBox="0 0 85 107" fill="none" aria-hidden="true">
+    <path
+      fill="#17191E"
+      d="M27.5893 91.1365C22.7555 86.7178 21.3443 77.4335 23.3583 70.7072C26.8503 74.948 31.6888 76.2914 36.7005 77.0497C44.4374 78.2199 52.0358 77.7822 59.2231 74.2459C60.0453 73.841 60.8052 73.3027 61.7036 72.7574C62.378 74.714 62.5535 76.6892 62.3179 78.6996C61.7452 83.5957 59.3086 87.3778 55.4332 90.2448C53.8835 91.3916 52.2437 92.4167 50.6432 93.4979C45.7262 96.8213 44.3959 100.718 46.2435 106.386C46.2874 106.525 46.3267 106.663 46.426 107C43.9155 105.876 42.0817 104.24 40.6844 102.089C39.2086 99.8193 38.5065 97.3081 38.4696 94.5909C38.4511 93.2686 38.4511 91.9345 38.2733 90.6309C37.8391 87.4527 36.3471 86.0297 33.5364 85.9478C30.6518 85.8636 28.37 87.6469 27.7649 90.4554C27.7187 90.6707 27.6517 90.8837 27.5847 91.1341L27.5893 91.1365Z"
+    ></path>
+    <path
+      fill="#17191E"
+      d="M0 69.5866C0 69.5866 14.3139 62.6137 28.6678 62.6137L39.4901 29.1204C39.8953 27.5007 41.0783 26.3999 42.4139 26.3999C43.7495 26.3999 44.9325 27.5007 45.3377 29.1204L56.1601 62.6137C73.1601 62.6137 84.8278 69.5866 84.8278 69.5866C84.8278 69.5866 60.5145 3.35233 60.467 3.21944C59.7692 1.2612 58.5911 0 57.0029 0H27.8274C26.2392 0 25.1087 1.2612 24.3634 3.21944C24.3108 3.34983 0 69.5866 0 69.5866Z"
+    ></path>
+  </svg>
+</span>
+
+<style>
+  /* Owns the theme swap: gradient mark on dark, solid mark on light. */
+  .astro-on-light {
+    display: none;
+  }
+  :global([data-theme="light"]) .astro-on-dark {
+    display: none;
+  }
+  :global([data-theme="light"]) .astro-on-light {
+    display: revert;
+  }
+</style>

packages/docs/src/components/CodeCard.astro

@@ -0,0 +1,123 @@
+---
+/**
+ * A landing-page "hero" code card: bespoke window chrome (macOS dots + a brand
+ * logo + a filename) wrapping a *real* Expressive Code block (passed as the
+ * default slot — author the fence with `frame="none"` so EC renders just the
+ * highlighted code and this card supplies the frame).
+ *
+ * - `file`   — the filename shown in the title bar.
+ * - `logo`   — a named slot for the brand mark (e.g. <HonoLogo slot="logo" />),
+ *              so each card can own its own logo + theme-variant logic.
+ */
+interface Props {
+  file: string;
+}
+
+const { file } = Astro.props;
+---
+
+<div class="code-card">
+  <div class="code-card__head">
+    <span class="code-card__dots" aria-hidden="true">
+      <span class="dot" style="background:#ff5f57"></span>
+      <span class="dot" style="background:#febc2e"></span>
+      <span class="dot" style="background:#28c840"></span>
+    </span>
+    <span class="code-card__logo" aria-hidden="true"><slot name="logo" /></span>
+    <span class="code-card__file">{file}</span>
+  </div>
+  <div class="code-card__body"><slot /></div>
+</div>
+
+<style>
+  .code-card {
+    position: relative;
+    background: var(--sl-color-gray-6);
+    border: 1px solid var(--sl-color-hairline);
+    border-radius: 1rem;
+    overflow: hidden;
+    box-shadow: 0 30px 70px -30px rgba(0, 0, 0, 0.55);
+    transition:
+      transform 0.4s var(--mty-ease),
+      box-shadow 0.4s var(--mty-ease);
+  }
+
+  /* Brand-gradient border, faded in on hover. */
+  .code-card::before {
+    content: "";
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+    padding: 1px;
+    background: var(--mty-grad-soft);
+    -webkit-mask:
+      linear-gradient(#000 0 0) content-box,
+      linear-gradient(#000 0 0);
+    -webkit-mask-composite: xor;
+    mask-composite: exclude;
+    opacity: 0;
+    transition: opacity 0.4s var(--mty-ease);
+    pointer-events: none;
+    z-index: 2;
+  }
+  .code-card:hover {
+    transform: translateY(-5px);
+  }
+  .code-card:hover::before {
+    opacity: 1;
+  }
+
+  .code-card__head {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.8rem 1.1rem;
+    border-bottom: 1px solid var(--sl-color-hairline);
+    background: var(--sl-color-black);
+  }
+  .code-card__dots {
+    display: inline-flex;
+    gap: 0.5rem;
+  }
+  .dot {
+    width: 11px;
+    height: 11px;
+    border-radius: 50%;
+  }
+
+  /* Logo: monochrome at rest, full brand color on card hover. */
+  .code-card__logo {
+    display: inline-flex;
+    align-items: center;
+    margin-left: 0.5rem;
+    filter: grayscale(1) opacity(0.5);
+    transition: filter 0.5s var(--mty-ease);
+  }
+  .code-card:hover .code-card__logo {
+    filter: none;
+  }
+  .code-card__logo :global(svg) {
+    height: 16px;
+    width: auto;
+    display: block;
+  }
+
+  .code-card__file {
+    font-family: var(--__sl-font-mono);
+    font-size: var(--sl-text-xs);
+    color: var(--sl-color-gray-4);
+  }
+
+  /* Let the card own the frame: strip EC's border / radius / shadow / margin so
+     the real code block sits flush inside the chrome above. */
+  .code-card__body :global(.expressive-code) {
+    margin: 0;
+  }
+  .code-card__body :global(.expressive-code .frame) {
+    box-shadow: none;
+  }
+  .code-card__body :global(.expressive-code pre) {
+    border: 0;
+    border-radius: 0;
+  }
+</style>

packages/docs/src/components/CodeCards.astro

@@ -0,0 +1,23 @@
+---
+/**
+ * Two-up grid wrapper for the landing-page <CodeCard>s. Collapses to a single
+ * column below Starlight's primary layout breakpoint (50rem).
+ */
+---
+
+<div class="code-cards"><slot /></div>
+
+<style>
+  .code-cards {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 1.25rem;
+    margin-block: 2.5rem;
+  }
+
+  @media (min-width: 50rem) {
+    .code-cards {
+      grid-template-columns: 1fr 1fr;
+    }
+  }
+</style>

packages/docs/src/components/HonoLogo.astro

@@ -0,0 +1,20 @@
+---
+/**
+ * Hono brand mark — the official flame logomark (gradient on both themes, so it
+ * needs no light/dark variant). Used as a `slot="logo"` inside <CodeCard>.
+ */
+---
+
+<svg viewBox="0 0 76 98" aria-hidden="true" class="hono-logo">
+  <defs>
+    <linearGradient id="mty-hono-flame" x2="0%" y2="100%">
+      <stop stop-color="#FF8844"></stop>
+      <stop offset="100%" stop-color="#FF3300"></stop>
+    </linearGradient>
+  </defs>
+  <path
+    fill="url(#mty-hono-flame)"
+    d="m11 25 7 9s9-18 22-34c17 20 36 48 36 64 0 20-19 34-37 34C17 98 0 81 0 61c0-6 3-24 11-36Z"
+  ></path>
+  <path fill="#FF9955" d="M39 21c47 51 14 66 0 66-11 0-51-11 0-66Z"></path>
+</svg>