Polish docs mobile layout - #13
Merged
Merged
Conversation
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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P6L4fHB1V6FYgiPHgCKogQ
xuefei-wang
force-pushed
the
agent/docs-mobile-polish
branch
from
July 22, 2026 04:55
02c7902 to
a0e7a8a
Compare
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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P6L4fHB1V6FYgiPHgCKogQ
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
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.
Summary
Mobile styles for the docs: hero, CTA buttons, cards, and the Mermaid expand /
zoom controls. The guiding rule is to add rules only where MkDocs Material does
not already handle the narrow viewport — several first-draft rules turned out
to duplicate or actively fight Material's own layout, and have been dropped.
What changed
Hero. Tighter type scale and spacing at phone widths. The title uses
text-wrap: balanceand the taglinetext-wrap: pretty, so neither strands ashort final line — this replaces hand-tuned
max-widthvalues that only workedfor the current wording.
CTA. The three buttons become a small grid: the primary spans the full
width, with Blog / GitHub side by side beneath it, and all three get a
comfortable touch target.
Cards. Tighter gaps and padding, and the hover lift is disabled — on touch
a hover transform sticks after a tap.
Mermaid. The expand button is permanently visible (there is no hover on
touch) and sized as a touch target; the zoom toolbar gets larger controls.
Diagrams keep the native sizing introduced in 5cfa2e1 and scroll inside their
own box, with
overscroll-behavior-x: containso a swipe at the diagram's edgedoesn't trigger back-navigation.
Inline code gets
overflow-wrap: anywhere— long flags and dotted paths arethe one thing Material's
word-break: break-wordwon't break on a narrow column.Deliberately left to Material
Verified against Material 9.7.6's compiled CSS rather than assumed:
.md-typeset__scrollwrap, whichalready has
overflow-x: autoat all widths. An earlier draft added a secondoverflow-xto the inner.md-typeset__table(nesting a scroller inside thescroller) plus
min-width: 34rem, which forced narrow tables to scroll too.On architecture.md at 390px that meant all five tables scrolled; now only the
one genuinely wider than the column does.
pre > codealready carries its ownoverflow: auto, andMaterial pulls top-level blocks edge-to-edge at this same breakpoint via
.md-content__inner > .highlight. An earlierpre { margin-inline: 0 }wasoutranked by that selector and never applied; a
font-size: 0.68remrestatedthe value already inherited (
.md-typesetis.8rem,codeis.85em).The breakpoint is Material's own
44.984375emso the two switch on exactly thesame viewport.
Scope
This PR is now purely additive mobile CSS — it touches nothing outside the
@mediablock.An earlier revision also flattened heading
letter-spacingto0and card /table
border-radiusto8px. Those are viewport-independent and sat outsidethe media query, so they changed desktop too. Checked against the design source
this stylesheet names in its own header — the blog, which it says it mirrors "so
the two sites read as one system" — the blog uses
letter-spacing: -0.02emonheadings and defines
--radius: 14pxfor its card surfaces, which is exactlywhat the docs originally had. The values also predate this work (they came in
with the public release). They've been restored.
Validation
uv run pytest: 3097 passed, 22 skipped.uv run mkdocs build --strict: passes.pages in headless Chrome at 360px and 390px: no document-level horizontal
overflow and no nested scroll containers on any of them. The hero title
balances to 3 lines at 360px and 2 at 390px.
from unpkg and its sub-chunks return 403 in this sandbox, so the diagram
reasoning above rests on the CSS and on 5cfa2e1's intent, not on a screenshot.