fix(docsite): stop blog card grids overflowing on small screens

[rubyycheung]

Summary

On small screens the blog cards overflowed the viewport horizontally.

Root cause: both blog card grids were built with repeat(auto-fit/fill, minmax(<minWidth>px, 1fr)) (via the core Grid's columns={{minWidth}} API). A bare minmax(<minWidth>px, 1fr) track can't shrink below its fixed min, so on a viewport narrower than that min the column overflowed the page:

• Home "Stay in the know" (BlogShowcase, 2-post layout) used minWidth: 480 → overflowed on every phone <480px.
• /blog index (BlogIndex) used minWidth: 320 → overflowed on ~320px devices.

Fix: use a container-clamped track, minmax(min(<minWidth>px, 100%), 1fr), so the column collapses to the viewport width on small screens and stacks cleanly. Implemented as small local grids in the docsite (leaving the shared core Grid untouched, per scope).

Rationale: the core Grid issue

This overflow is not specific to the blog cards — it's a latent limitation of the core Grid's responsive API. Grid emits its responsive track as:

repeat(auto-fill|auto-fit, minmax(<minWidth>px, 1fr))

The minmax() minimum is a fixed <minWidth>px. A grid track will never render narrower than its min, so whenever the container is narrower than minWidth, the single column is wider than the viewport and the page overflows horizontally. This affects any columns={{minWidth}} usage where minWidth can exceed the smallest supported viewport (~320px), which is exactly what happened with the minWidth: 480 home grid.

The robust, idiomatic CSS fix is to clamp the track min to the container: minmax(min(<minWidth>px, 100%), 1fr). The min(<minWidth>px, 100%) lets the track shrink to the container width when there isn't room for the full minWidth, so it stacks instead of overflowing, while still preferring minWidth when space allows.

Why fix it locally instead of in core Grid: changing the core track generation would alter the rendered CSS for every columns={{minWidth}} consumer across the system, so it needs its own dedicated change (snapshot/test updates in Grid.test.tsx, a changeset, and broader visual verification) rather than riding along in a docsite bug fix. This PR is scoped to unblocking the docsite overflow; the core Grid should be updated separately to emit minmax(min(<minWidth>px, 100%), 1fr) so no consumer hits this again.

Test plan

• No horizontal overflow at 320 / 360 / 390px on / and /blog (document.scrollWidth === innerWidth)
• Desktop still renders 2-up (home) / multi-column (blog index) as before
• Pre-commit checks (lint, prettier, sync/boundaries/changesets/demo-media) pass
• Visual spot-check on a real phone

Made with Cursor

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jul 2, 2026 7:58pm

[cixzhang]

Hmm any reason this wasn't achievable via Grid?

[rubyycheung]

It's not currently achievable via Grid — that's actually the root cause of the overflow. Grid's responsive API emits its track as repeat(auto-fill|auto-fit, minmax(<minWidth>px, 1fr)), and the minmax() minimum is a fixed <minWidth>px. A grid track never renders narrower than its min, so once the viewport is narrower than minWidth (480px on the home grid, 320px here) the single column is wider than the screen and the page overflows.

To do this via Grid we'd need to change core to clamp the min to the container: minmax(min(<minWidth>px, 100%), 1fr). That's the right long-term fix, but it changes the rendered CSS for every columns={{minWidth}} consumer, so it needs its own PR (snapshot/test updates in Grid.test.tsx, a changeset, broader visual check) rather than riding along in a docsite bug fix. I kept this one scoped to unblocking the overflow and left a note in the PR description that core Grid should be updated separately so no one hits this again.

Happy to open that core Grid follow-up if you'd prefer to fix it centrally instead.