Skip to content

Polish docs mobile layout - #13

Merged
xuefei-wang merged 3 commits into
mainfrom
agent/docs-mobile-polish
Jul 22, 2026
Merged

xuefei-wang merged 3 commits into
mainfrom
agent/docs-mobile-polish

Conversation

@xuefei-wang

@xuefei-wang xuefei-wang commented Jul 22, 2026 •

Copy link
Copy Markdown
Contributor

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: balance and the tagline text-wrap: pretty, so neither strands a
short final line — this replaces hand-tuned max-width values that only worked
for 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: contain so a swipe at the diagram's edge
doesn't trigger back-navigation.

Inline code gets overflow-wrap: anywhere — long flags and dotted paths are
the one thing Material's word-break: break-word won't break on a narrow column.

Deliberately left to Material

Verified against Material 9.7.6's compiled CSS rather than assumed:

  • Wide tables — every table is wrapped in .md-typeset__scrollwrap, which
    already has overflow-x: auto at all widths. An earlier draft added a second
    overflow-x to the inner .md-typeset__table (nesting a scroller inside the
    scroller) 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.
  • Block code — pre > code already carries its own overflow: auto, and
    Material pulls top-level blocks edge-to-edge at this same breakpoint via
    .md-content__inner > .highlight. An earlier pre { margin-inline: 0 } was
    outranked by that selector and never applied; a font-size: 0.68rem restated
    the value already inherited (.md-typeset is .8rem, code is .85em).

The breakpoint is Material's own 44.984375em so the two switch on exactly the
same viewport.

Scope

This PR is now purely additive mobile CSS — it touches nothing outside the
@media block.

An earlier revision also flattened heading letter-spacing to 0 and card /
table border-radius to 8px. Those are viewport-independent and sat outside
the 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.02em on
headings and defines --radius: 14px for its card surfaces, which is exactly
what 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.
  • Audited the rendered homepage, architecture, experiments, and getting-started
    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.
  • Not verified: a live-rendered Mermaid diagram. Material lazy-loads mermaid
    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.

xuefei-wang and others added 2 commits July 21, 2026 21:42
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
xuefei-wang force-pushed the agent/docs-mobile-polish branch from 02c7902 to a0e7a8a Compare July 22, 2026 04:55
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
@xuefei-wang
xuefei-wang marked this pull request as ready for review July 22, 2026 05:30
@xuefei-wang
xuefei-wang merged commit 43610e0 into main Jul 22, 2026
3 checks passed
@xuefei-wang
xuefei-wang deleted the agent/docs-mobile-polish branch July 22, 2026 15:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant