diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index 505cb14..67bd03e 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -231,6 +231,8 @@ body {
    ========================================================================== */
 .md-typeset .grid.cards > ul > li,
 .md-typeset .grid > .card {
+  /* Matches the blog's `--radius: 14px` card token — see the header note about
+     the two sites reading as one system. */
   border-radius: 14px;
   transition: transform 0.18s ease, box-shadow 0.18s ease;
 }
@@ -388,3 +390,132 @@ body.mermaid-zoom-lock {
   pointer-events: auto;
   z-index: 0;
 }
+
+/* ==========================================================================
+   Mobile layout
+   ========================================================================== */
+/* 44.984375em is Material's own mobile breakpoint — keep them identical so our
+   overrides switch on exactly the same viewport Material does. */
+@media screen and (max-width: 44.984375em) {
+  .md-typeset h1 {
+    font-size: 1.75rem;
+    line-height: 1.18;
+  }
+
+  .md-typeset h2 {
+    margin-top: 1.65rem;
+  }
+
+  .ksi-hero {
+    margin-bottom: 1.6rem;
+    padding: 2.1rem 0 1.9rem;
+  }
+
+  /* `text-wrap: balance` evens out the line lengths so the title can't strand a
+     short last line (the original problem here). Prefer it over a hand-tuned
+     max-width, which only works for the current wording. Browsers without it
+     just fall back to normal wrapping. */
+  .ksi-hero h1 {
+    font-size: 1.8rem;
+    line-height: 1.16;
+    text-wrap: balance;
+  }
+
+  /* `pretty` rather than `balance`: it keeps full-measure lines but avoids a
+     one-word last line, which reads better for a multi-line paragraph. */
+  .ksi-hero .ksi-tagline {
+    margin-bottom: 1.25rem;
+    font-size: 0.92rem;
+    line-height: 1.55;
+    text-wrap: pretty;
+  }
+
+  .ksi-cta {
+    display: block;
+  }
+
+  .ksi-cta > p {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    width: min(100%, 19rem);
+    margin: 0 auto;
+    gap: 0.55rem;
+  }
+
+  .ksi-cta .md-button {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 100%;
+    min-height: 2.45rem;
+    padding: 0.45rem 0.75rem;
+    gap: 0.35rem;
+    white-space: nowrap;
+  }
+
+  .ksi-cta .md-button--primary {
+    grid-column: 1 / -1;
+  }
+
+  .md-typeset .grid.cards > ul {
+    gap: 0.7rem;
+  }
+
+  .md-typeset .grid.cards > ul > li {
+    padding: 0.85rem;
+  }
+
+  .md-typeset .grid.cards > ul > li:hover {
+    transform: none;
+    box-shadow: none;
+  }
+
+  /* Long inline code (flags, paths, dotted identifiers) is the one thing Material
+     doesn't already break on a narrow screen — `word-break: break-word` leaves an
+     unbroken token to overflow the column. Block code needs nothing: Material
+     gives `pre > code` its own `overflow: auto` and pulls top-level blocks
+     edge-to-edge at this same breakpoint.
+
+     Wide tables need nothing either — Material wraps every table in
+     `.md-typeset__scrollwrap`, which already scrolls horizontally at all widths. */
+  .md-typeset :not(pre) > code {
+    overflow-wrap: anywhere;
+  }
+
+  /* Diagrams keep their native size here too (see the useMaxWidth:false init
+     directives in architecture.md) and scroll inside their own box. Shrinking a
+     wide flowchart to a 360px column would make its labels unreadable — the
+     exact problem native sizing was introduced to fix — so on mobile the
+     always-visible expand button below is the way to read a large diagram.
+     `overscroll-behavior-x` stops a swipe at the diagram's edge from triggering
+     the browser's back-navigation gesture. */
+  .md-typeset .mermaid {
+    -webkit-overflow-scrolling: touch;
+    overscroll-behavior-x: contain;
+  }
+
+  /* No hover on touch, so the expand affordance has to be permanently visible,
+     and sized to a comfortable touch target. */
+  .mermaid-expand-btn {
+    top: 0.4rem;
+    right: 0.4rem;
+    width: 2.25rem;
+    height: 2.25rem;
+    opacity: 1;
+  }
+
+  .mermaid-zoom-toolbar {
+    gap: 0.5rem;
+    padding: 0.6rem;
+  }
+
+  .mermaid-zoom-toolbar button {
+    min-width: 2.5rem;
+    height: 2.5rem;
+    padding: 0 0.65rem;
+  }
+
+  .mermaid-zoom-toolbar [data-act="reset"] {
+    flex: 1 1 auto;
+  }
+}