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

WidthWritten asWhereWhat it does
30rem@media (width < 30rem)Contact pageA small-phone tweak
40remsm:About, Contact, My stack, Resume, several note pagesTailwind's default; two-column grids, a bigger avatar
48remmd:FooterFooter links go from a grid to a row
56remwide: and 56remHeader, menu, contents, tables, code block tabs, page frameThe phone/desktop switch
80rem80remPage layout, shell layout, headerThe notes column appears and the frame widens
768pxMOBILE_BREAKPOINTuse-mobile.tsshadcn's own cutoff; nothing in this repo uses it

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.

FileLineFormPurpose
globals.css80--breakpoint-wide: 56remThe definition behind wide:
globals.css90@media (width < 56rem)Scroll padding under the sticky header
page-layout.module.css24@media (width >= 56rem)Article and contents side by side
page-layout.module.css72@media (width < 56rem)Notes and contents buttons share a row
mobile-menu.tsx101matchMedia("(min-width: 56rem)")Close the menu if the window grows
CodeBlockClient.tsx103matchMedia("(min-width: 56rem)")Swap an open lightbox and drawer
CodeBlockClient.tsx139matchMedia("(min-width: 56rem)")Choose lightbox or drawer on expand
page-layout.module.css50, 113@media (width >= 80rem)Notes column, wider gaps
layout.module.css16@media (width >= 80rem)Shell widens
header.module.css7@media (width >= 80rem)Header makes room for the notes column

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

FileRuleMeaning
CodeBlockClient.module.css (2)@media (hover: none)Buttons stay visible; the floating background stays
header.module.css@media (hover: none)No hover treatment on the site name
page-jump.module.css (2)@media (hover: none)A Go arrow, and 16px text so iOS doesn't zoom
content.module.css (goatboat)@media (hover: none)Edit buttons stay visible

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/ use sm: and md: for details like dialog width and pagination labels.
  • prefers-reduced-motion is 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.ts at 768px for the sidebar, sm: and md: in shadcn files, one hover: 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 :hover applies on touch screens too, where it sticks after a tap. Tailwind's hover: variant only applies on devices that can hover.
  • A dead hook. use-mobile.ts invites 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.

NameMeaningCSSJavaScriptUsed for
wideWindow is 56rem or morewide: and max-wide:queries.widePage layout: header, menu, contents, tables, explorer
notesWindow is 80rem or morenotes: and max-notes:queries.notesThe notes column and the wider frame
touchMain input is a finger: no hover and a coarse pointertouch:queries.touchThe drawer, always-visible buttons, 16px inputs, Go arrows

Which tool for which question

QuestionUseBecause
How much room does the page have?wide or notesChrome and page frames follow the window
How much room does this component have?A container queryA card in a column shouldn't care how wide the window is
What is the person holding?touchBehaviour follows the input, not the width
Does the person want less motion?prefers-reduced-motionA setting, unrelated to the rest

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.

Narrow windowWide window
MousePhone layout, lightboxDesktop layout, lightbox
TouchPhone layout, drawerDesktop layout, drawer (tablet, or a phone in landscape)

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.

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.

css
/* 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.

ts
// 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

tsx
// 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 deleted

Lightbox 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.

FileNowChange to
globals.css line 90@media (width < 56rem) on htmlmax-wide: variant
page-layout.module.css lines 24, 72@media (width >= 56rem), (width < 56rem)@variant wide, @variant max-wide
page-layout.module.css lines 50, 113@media (width >= 80rem)@variant notes
layout.module.css line 16, header.module.css line 7@media (width >= 80rem)@variant notes
mobile-menu.tsx line 101matchMedia("(min-width: 56rem)")useMedia("wide"), closing in an effect when it turns true
CodeBlockClient.tsx lines 103, 139Two matchMedia callsmatches("touch") on click; delete the swap effect

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.

FileNowChange to
CodeBlockClient.module.css (2)@media (hover: none)@variant touch
header.module.css@media (hover: none)@variant touch
page-jump.module.css (2)@media (hover: none)@variant touch

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.

FileNowSuggested
about/page.module.css, contact/page.module.csssm:size-48 on the avatarwide:size-48
contact/page.module.css@media (width < 30rem)Make the small layout the default and drop the query
my-stack/page.module.csssm:flex …, sm:w-96wide:
resume/page.module.csssm:flex-row, sm:w-32wide:
footer.module.cssmd:flex …wide:
Container.module.cssmax-sm:mb-48max-wide:mb-48
Notes pages with sm:grid-cols-2 (goatboat content, projects, components, hover-borders, text-colors, before-after)sm:wide:, or a container query if the grid sits in a narrow column

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.

SliceWhatVisible changeHow to check
1Add --breakpoint-notes, the touch variant and src/lib/media.ts. Convert one CSS module to @variant wide as a trialNoneThe converted page looks the same at 55rem and 57rem
2Swap every 56rem and 80rem literal for the namesNonePage layout, header and menu at 55, 57, 79 and 81rem
3Lightbox on desktop, drawer on touchCode block on narrow desktop windowsExpand a block in a narrow desktop window; then in device mode
4hover: none becomes touchNoneDevice mode: Go arrow, 16px input, always-visible buttons
5Remove the 30, 40 and 48rem tiersPages between 640 and 896pxEach affected page in that range
6Add the guard script and the written ruleNoneA commit with a stray literal fails
7Delete the dead hookNoneNothing imports it

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.

ts
// 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.ts

The 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.

md
# .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.css and one in media.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 except ui/.
  • 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: or frame: 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.