From 4d337b020043db0442f063b2770e1d3f6c1c30fc Mon Sep 17 00:00:00 2001 From: xuefei-wang Date: Tue, 21 Jul 2026 21:28:51 -0700 Subject: [PATCH 1/3] Polish docs mobile layout --- docs/stylesheets/extra.css | 140 +++++++++++++++++++++++++++++++++++-- 1 file changed, 136 insertions(+), 4 deletions(-) diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 505cb14..5eb80c4 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -99,11 +99,11 @@ body { /* ---- Typographic rhythm --------------------------------------------------- */ .md-typeset h1 { font-weight: 700; - letter-spacing: -0.02em; + letter-spacing: 0; } .md-typeset h2 { font-weight: 650; - letter-spacing: -0.01em; + letter-spacing: 0; margin-top: 2.2rem; } .md-typeset h3, @@ -128,7 +128,7 @@ body { and a subtly tinted header row. Scoped to `:not([class])` so mkdocstrings and other generated tables keep their own styling. */ .md-typeset table:not([class]) { - border-radius: 10px; + border-radius: 8px; border-spacing: 0; overflow: hidden; } @@ -231,7 +231,7 @@ body { ========================================================================== */ .md-typeset .grid.cards > ul > li, .md-typeset .grid > .card { - border-radius: 14px; + border-radius: 8px; transition: transform 0.18s ease, box-shadow 0.18s ease; } @@ -388,3 +388,135 @@ body.mermaid-zoom-lock { pointer-events: auto; z-index: 0; } + +/* ========================================================================== + Mobile layout + ========================================================================== */ +@media screen and (max-width: 44.984em) { + .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; + } + + .ksi-hero h1 { + max-width: 18.5rem; + margin-right: auto; + margin-left: auto; + font-size: 1.8rem; + line-height: 1.16; + } + + .ksi-hero .ksi-tagline { + max-width: 20rem; + margin-bottom: 1.25rem; + font-size: 0.92rem; + line-height: 1.55; + } + + .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; + } + + .md-typeset pre { + margin-right: 0; + margin-left: 0; + } + + .md-typeset pre > code { + font-size: 0.68rem; + } + + .md-typeset :not(pre) > code { + overflow-wrap: anywhere; + } + + .md-typeset .md-typeset__table { + max-width: 100%; + overflow-x: auto; + -webkit-overflow-scrolling: touch; + } + + .md-typeset table:not([class]) { + min-width: 34rem; + } + + .md-typeset .mermaid { + overflow-x: auto; + -webkit-overflow-scrolling: touch; + overscroll-behavior-x: contain; + } + + .md-typeset .mermaid > svg { + display: block; + max-width: 100% !important; + height: auto !important; + } + + .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; + } +} From a0e7a8a23eedbfe82e623ab2c725a2c60154171c Mon Sep 17 00:00:00 2001 From: xuefei-wang Date: Tue, 21 Jul 2026 21:54:33 -0700 Subject: [PATCH 2/3] docs: drop mobile rules that fight Material's own layout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The mobile block re-implemented behavior MkDocs Material already provides, and in three places actively regressed it. Verified against Material 9.7.6's compiled CSS and by auditing the rendered pages in headless Chrome at 360px and 390px. - Mermaid: `max-width: 100% !important` on the SVG reverted 5cfa2e1 for phones, shrinking a wide flowchart into a 360px column until its labels were unreadable — the exact problem native sizing was added to fix. It also made the sibling `overflow-x: auto` dead, since a clamped diagram never overflows. Diagrams now keep native size and scroll, with the expand button (already forced visible here) as the way to read a large one. - Tables: Material wraps every table in `.md-typeset__scrollwrap`, which has `overflow-x: auto` at all widths. Adding `overflow-x` to the inner `.md-typeset__table` nested a second scroller inside it, and `min-width: 34rem` forced narrow tables to scroll needlessly. On architecture.md at 390px this meant all five tables scrolled; now only the one genuinely wider than the column does. - Code: `pre > code { font-size: 0.68rem }` restated the inherited value (.md-typeset is .8rem, code is .85em), and `pre { margin-inline: 0 }` never applied — Material's edge-to-edge rule is `.md-content__inner > .highlight`, which outranks it. Both were no-ops. `pre > code` already scrolls on its own. Also replace the hero's hand-tuned `max-width` values with `text-wrap: balance` (title) and `pretty` (tagline), which prevent a stranded last line without being tied to the current wording, and align the breakpoint with Material's 44.984375em. Verified: no document-level horizontal overflow and no nested scrollers on the homepage, architecture, experiments, and getting-started pages at 360px/390px; hero balances to 3 lines at 360px and 2 at 390px. `mkdocs build --strict` and `pytest` (3097 passed, 22 skipped) both pass. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01P6L4fHB1V6FYgiPHgCKogQ --- docs/stylesheets/extra.css | 57 ++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 30 deletions(-) diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 5eb80c4..4df9ef7 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -392,7 +392,9 @@ body.mermaid-zoom-lock { /* ========================================================================== Mobile layout ========================================================================== */ -@media screen and (max-width: 44.984em) { +/* 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; @@ -407,19 +409,23 @@ body.mermaid-zoom-lock { 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 { - max-width: 18.5rem; - margin-right: auto; - margin-left: auto; 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 { - max-width: 20rem; margin-bottom: 1.25rem; font-size: 0.92rem; line-height: 1.55; + text-wrap: pretty; } .ksi-cta { @@ -462,41 +468,32 @@ body.mermaid-zoom-lock { box-shadow: none; } - .md-typeset pre { - margin-right: 0; - margin-left: 0; - } - - .md-typeset pre > code { - font-size: 0.68rem; - } + /* 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; } - .md-typeset .md-typeset__table { - max-width: 100%; - overflow-x: auto; - -webkit-overflow-scrolling: touch; - } - - .md-typeset table:not([class]) { - min-width: 34rem; - } - + /* 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 { - overflow-x: auto; -webkit-overflow-scrolling: touch; overscroll-behavior-x: contain; } - .md-typeset .mermaid > svg { - display: block; - max-width: 100% !important; - height: auto !important; - } - + /* 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; From 54dddd914bec0b3271a22ba814263bbfa6ba72a1 Mon Sep 17 00:00:00 2001 From: xuefei-wang Date: Tue, 21 Jul 2026 22:08:09 -0700 Subject: [PATCH 3/3] docs: restore the blog-matched heading tracking and radius scale MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These three values are viewport-independent and sit outside the media query, so they were changing desktop too — they don't belong in a mobile PR. Checked them against the design source this file names in its own header (the blog at recursive-knowledge.github.io/knowledge-centric-self-improvement, which it says it mirrors "so the two sites read as one system"): - The blog sets `letter-spacing: -0.02em` on headings; the docs' -0.02em/-0.01em matched it. Flattening to 0 diverged from it. - The blog defines `--radius: 14px` and uses it for every card surface (.stage-card, .example-card, .code-block, .tldr). The docs' 14px card radius was that token. Collapsing cards to 8px diverged from it, and flattening code 8px / tables 10px / cards 14px into a single 8px destroyed a deliberate scale. All three came in with 8c7cb7a (the public release) and were changed by 4d337b0 under a bare "Polish docs mobile layout" message with no stated rationale, so this reads as drift rather than an intentional redesign. Restoring them leaves the PR purely additive mobile CSS. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01P6L4fHB1V6FYgiPHgCKogQ --- docs/stylesheets/extra.css | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 4df9ef7..67bd03e 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -99,11 +99,11 @@ body { /* ---- Typographic rhythm --------------------------------------------------- */ .md-typeset h1 { font-weight: 700; - letter-spacing: 0; + letter-spacing: -0.02em; } .md-typeset h2 { font-weight: 650; - letter-spacing: 0; + letter-spacing: -0.01em; margin-top: 2.2rem; } .md-typeset h3, @@ -128,7 +128,7 @@ body { and a subtly tinted header row. Scoped to `:not([class])` so mkdocstrings and other generated tables keep their own styling. */ .md-typeset table:not([class]) { - border-radius: 8px; + border-radius: 10px; border-spacing: 0; overflow: hidden; } @@ -231,7 +231,9 @@ body { ========================================================================== */ .md-typeset .grid.cards > ul > li, .md-typeset .grid > .card { - border-radius: 8px; + /* 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; }