Responsive report
How the site decides between desktop and mobile today, what's wrong with it, and a plan for one central place to control it.
Summary
The short answer
The site decides desktop versus mobile by window width alone. One width, 56rem, is the real switch, with a second at 80rem for the notes column. The only device check is (hover: none), used five times as "a touch screen", and none of it is connected to the width rules.
What's wrong with that
- The numbers are copied. 56rem is typed in seven places, in CSS and in JavaScript, held together by comments.
- Width stands in for device. A narrow desktop window gets the drawer, and a wide tablet doesn't.
- Too many tiers. 30, 40, 48, 56 and 80rem are all in use, and only two are on purpose.
What I'd do
Name three things once: wide (window is 56rem or more), notes (80rem or more) and touch (the main input is a finger). CSS uses them as variants, TypeScript through one small file, and a script checks they agree. Then move every raw width and every hover: none over to the names, and make the code block choose its drawer by touch.
Findings
How the site decides today
Layout is decided by window width, with one main switch at 56rem and a second one at 80rem. Device type isn't checked at all; the closest thing is (hover: none), used in a few places to mean "a touch screen". There's no pointer check, no orientation check and no user-agent check anywhere.
Every width threshold
Where 56rem and 80rem are written
The wide: variant comes from one definition, but the same widths are also typed out by hand, in CSS and in JavaScript. A comment in each place says to keep it in step with the others.
Where the wide: variant is used
- Header: sticky bar with a menu below it, a static intro block above it.
- Mobile menu: the hamburger button is hidden from it up.
- Contents: the "On this page" button below it, the contents column above.
- Notes table: columns that appear only from it up.
- Code block: the file tab strip below it, the explorer column above.
- Page frame side padding, and the scroll offset when jumping to a heading.
- Two test pages (browse previews, wrap indent).
Device checks
All five mean the same thing: this device can't hover. They're written out by hand each time, and none of them is connected to the width rules above.
What expanding a code block does
The expand button reads matchMedia("(min-width: 56rem)") when clicked: wide opens the lightbox, narrow opens the drawer. While one is open, another listener swaps it for the other if the window crosses 56rem. So a narrow desktop window gets the drawer, and a phone in landscape or an iPad at 1024px gets the lightbox.
Smaller findings
use-mobile.ts(768px) is a leftover from adding shadcn. Nothing in this repo calls it. goatboat's sidebar does use its copy.- Headings, spacing and code text are scaled continuously with
clamp()between a 375px and a 1024px window. That's not a breakpoint, but the range is only written in comments, nine times. - Container queries are rare: the code block's wrapped-line indent, the wrap-indent test page, and shadcn's card and field.
- shadcn's own files in
ui/usesm:andmd:for details like dialog width and pagination labels. prefers-reduced-motionis checked in three scroll handlers and two CSS files; that one is a user setting, not a device or a width, so it isn't part of this.- The JavaScript checks run only inside effects and click handlers, never during render, so there's no hydration mismatch.
- goatboat has the same pattern on a smaller scale:
use-mobile.tsat 768px for the sidebar,sm:andmd:in shadcn files, onehover: none.
Problems
One number, many copies
56rem is written in at least seven places, 80rem in four more. CSS media queries can't read a variable, so the only protection is a comment saying "keep in step". Change one and nothing tells you about the others.
Width stands in for device
The code block picks the drawer by window width, but a drawer is a touch idea. A narrow desktop window gets it, and a tablet wider than 56rem doesn't. Anything that should follow the device has no way to say so.
Too many tiers
The site has thresholds at 30, 40, 48, 56 and 80rem, plus 768px in a hook nobody calls. Only 56 and 80 are deliberate. The rest came from copying Tailwind defaults or shadcn files, so between 40 and 56rem some pages are in their phone layout and others aren't.
Touch has no name
Each @media (hover: none) is typed out on its own. There's no name for "touch", so there's no way to ask "where do we treat touch differently?" except searching.
The swap listener
While a code block view is open, a listener turns the lightbox into the drawer (or back) when the window crosses 56rem. Those are two different components, so the open block is mounted again and view state, like whether lines are wrapped, may reset. With a device-based rule this listener has no job: a device doesn't change type mid-session.
Hard to test
A responsive change today means dragging the window across several widths. Once width and device are separate, there are four combinations to look at, and nothing says which ones a page has been checked in.
Smaller problems
- The fluid range lives in comments. Nine
clamp()values share a 375 to 1024px range that's only written in their comments. - Raw hover rules. A CSS module's
:hoverapplies on touch screens too, where it sticks after a tap. Tailwind'shover:variant only applies on devices that can hover. - A dead hook.
use-mobile.tsinvites someone to use a third definition of mobile. - Nothing enforces any of this. New code can add a seventh breakpoint and nothing complains.
Proposal
The idea
Name three things and define each once. Everything else asks for them by name. Nobody writes 56rem or hover: none again.
Which tool for which question
This is the rule that keeps the number of tiers down. If a component only cares about its own width, it shouldn't be asking the window.
The four combinations
Because width and touch are separate, a page is in one of four situations. This is also the test matrix.
The explorer and the file tabs stay width-based, since that's about room. Only the choice of lightbox or drawer follows touch.
In CSS
Register the widths and the touch variant once, in globals.css.
/* globals.css */
/* Layout switches. Every width comes from here: CSS uses the variants, TypeScript uses src/lib/media.ts */
@theme static {
--breakpoint-wide: 56rem; /* phone layout below, desktop layout from here */
--breakpoint-notes: 80rem; /* the project's notes get their own column */
}
/* The main input is a finger. Not "any" touch: a laptop with a touch screen still has a trackpad as its main input */
@custom-variant touch (@media (hover: none) and (pointer: coarse));CSS modules then use the variants where they now use raw media queries. Tailwind's @variant goes inside a rule, so each query block becomes a nested one.
/* a CSS module, replacing @media (width >= 56rem) */
.columnsWithAside {
@variant wide {
@apply grid-cols-[minmax(0,var(--container-content))_var(--container-aside)];
}
}
/* replacing @media (hover: none) */
.go {
display: none;
@variant touch {
@apply inline-flex items-center;
}
}Worth proving on one file first: @variant next to @reference in a module should work, but it's the one part of this I haven't run.
In TypeScript
One small file holds the queries, with one function for handlers and one hook for render. CSS can't share a number with TypeScript, so a check script compares the two and fails the commit if they drift. That replaces today's comments with something that can fail.
// src/lib/media.ts
import { useSyncExternalStore } from "react";
// Keep in step with --breakpoint-* in globals.css; scripts/check-media.mts fails the commit if they differ
export const queries = {
wide: "(min-width: 56rem)",
notes: "(min-width: 80rem)",
touch: "(hover: none) and (pointer: coarse)",
} as const;
type Query = keyof typeof queries;
/** For event handlers and effects: the answer right now. */
export const matches = (query: Query) => window.matchMedia(queries[query]).matches;
/** For render: updates when the answer changes. The server and first render say no, so there's no mismatch. */
export function useMedia(query: Query) {
return useSyncExternalStore(
(onChange) => {
const list = window.matchMedia(queries[query]);
list.addEventListener("change", onChange);
return () => list.removeEventListener("change", onChange);
},
() => matches(query),
() => false,
);
}Why not read the width from the CSS variable?
It's possible: getComputedStyle on the root returns --breakpoint-wide, which would make the CSS the only source. The cost is a runtime read, a fallback while the page loads, and a theme variable that must be forced into the output. A checked constant is simpler and fails earlier.
The code block, in one line
// CodeBlockClient.tsx: the expand button
onClick={() => setView(matches("touch") ? "drawer" : "lightbox")}
// and the effect that swapped an open view when the window crossed 56rem is deletedLightbox on every desktop width, drawer only when the main input is a finger. The lightbox already caps at 94% of the window's width, so it should hold up in a narrow desktop window.
Edge cases
- iPad. It reports touch, so it gets the drawer even at 1024px. With a trackpad attached, the browser reports the trackpad as the main input and it gets the lightbox.
- Touch laptop. The main input is the trackpad, so it counts as mouse.
- Phone in landscape. Touch, so the drawer. Wide enough for the desktop layout, which is fine: the layout and the drawer are separate decisions.
- Desktop dev tools in device mode. They switch the browser to touch, so the drawer can be tested without a phone.
Fixes
Swap the copies for the names
No visible change. Once the tokens and variants exist, each literal becomes a name.
Make the drawer a touch decision
The change you asked for. In CodeBlockClient.tsx, expanding chooses the drawer on touch and the lightbox otherwise, and the swap listener goes. Lightbox on every desktop width, drawer only on a phone or tablet.
Name the touch rule
No visible change on any device that behaves the same as before.
One difference to watch: hover: none alone also matches some stylus and game-console browsers. The combined rule is a little stricter.
Remove the extra tiers
This is the only step that changes how pages look. Anything at 40 or 48rem moves to 56rem, so between those widths a page keeps its phone layout for longer. Look at each in a window between 640 and 896px.
Delete the dead hook
src/hooks/use-mobile.ts has no users in this repo. Deleting it removes a third meaning of "mobile". If a shadcn component is added later that needs it, re-adding the component will bring it back.
Leave alone
The shadcn files in ui/ keep their own sm: and md: classes, as the project rules say, and the fluid clamp() scale stays as it is. Both work, and neither causes the problems above.
Factoring
The order
Seven small slices, each working on its own. The first two change nothing visible, so they can be checked in a few minutes. The two that change what a person sees are 3 and 5, and they're kept apart on purpose.
The guard
The rules only last if something enforces them. A small script, run by the same pre-commit hook that stamps pages, checks the four things below.
// scripts/check-media.mts: what it checks
// 1. --breakpoint-* in globals.css equal the widths in src/lib/media.ts
// 2. No "@media (width" or "matchMedia(" with a literal width outside globals.css and media.ts
// 3. No sm:, md:, lg: or xl: outside src/components/ui (shadcn keeps its own)
// 4. No "(hover: none)" outside globals.css and media.tsThe written rule
A short instruction file, so that every new page and every assistant gets it without being told. The build-ui skill would get one line pointing at it.
# .github/instructions/responsive.instructions.md (new)
- Page layout follows the window: use wide: or notes:, never a width in rem or px.
- A component's own layout follows its container: use a container query.
- Behaviour that depends on how the person is holding the device uses touch:.
- In JavaScript, use matches() or useMedia() from @/lib/media.What gets easier
- Changing the switch width. One line in
globals.cssand one inmedia.ts, and the script tells you if you forgot the second. - Asking "where do we treat touch differently?" Search for
touch. - Writing a new page. There are two layout names and one device name to choose from, instead of five widths and a media query to remember.
- Testing. Four combinations, written down, with the dev tools' device mode covering touch.
goatboat
goatboat has its own copy of the same problem on a smaller scale: a 768px hook for the sidebar and a few sm: classes. It's an admin tool, so I'd leave it until this site's version has settled, then copy the same tokens across.
Decisions
Before slice 1
- iPad gets the drawer. It reports touch even at 1024px wide. I think that's right, since a lightbox on a tablet is an awkward target. Agree?
- Drop the 40rem tier? Moving two-column grids and the avatar from 40rem to 56rem means pages between 640 and 896px stay single column for longer. The alternative is to keep one in-between tier, or switch those grids to container queries.
- Keep shadcn's classes? Resetting Tailwind's default breakpoints would make any leftover
sm:class do nothing, shadcn's included. I'd keep the defaults and let the guard script ban them everywhere exceptui/. - The name "notes". It's the width where the notes column appears, so
notes:reads naturally, but it's also a section of the site.rail:orframe:are options. - CSS-first or constant-plus-check. I'd use a TypeScript constant with a script that checks it against the CSS. Reading the width from the CSS variable at runtime also works.
One thing to confirm by trying rather than deciding: that @variant works in a CSS module with @reference. Slice 1 starts with that.