I added a new mobile usability rule to the dev docs today, and it turned into one of those small updates that touches more of the product than expected. The change itself was simple on paper: make sure every new interface we ship works cleanly on mobile before it gets merged.
But once I started writing the rule, I realized the docs needed more than a vague “make it responsive” note. That kind of guidance sounds fine, but it does not help when you are tired, moving fast, and trying to decide if a cramped button layout is acceptable or not.
So I wrote the rule like I would want to read it while building: clear, testable, and a little opinionated.
Why I added the rule
The trigger was a pretty normal build session. I was working through a docs pass while also testing a few screens on my phone. Desktop looked good. Tablet was passable. Mobile had the usual little cuts: a button too close to another button, a table pushing off the side, a form label wrapping in a weird place, and one section where the user had to pinch zoom to read comfortably.
None of these issues felt dramatic by themselves. That is exactly the problem. Mobile usability problems often sneak in as tiny compromises. One layout gets shipped because it “mostly works.” Then another. A few weeks later, the product feels clumsy on a phone even though nobody made one big bad decision.
I wanted the docs to catch that pattern early. Not with a huge process. Just a rule that gives builders a shared baseline.
The rule is not here to slow down shipping. It is here to make the default path better, especially when we are moving fast.
The first draft was too soft
My first version said something like: “Make sure pages are responsive and usable on mobile.” That sentence was technically true, but almost useless. It gave no test, no edge cases, and no decision support.
If someone asked, “Is this usable enough?” the docs would not help them answer. That is a sign the rule is too soft.
So I rewrote it around actual checks. I wanted the rule to answer these questions:
- Can someone read the page without zooming?
- Can someone tap controls without accidentally hitting the wrong thing?
- Does the layout avoid sideways scrolling unless the content truly requires it?
- Do forms still make sense on a narrow screen?
- Can the main task be completed with one thumb and a little patience?
That last one is not a formal metric, but it is a useful gut check. If the page works only when I hold the phone with both hands, zoom in, and aim carefully, the page is not done.
The actual rule I added
I ended up adding the rule as a short section inside the dev docs where we keep our interface standards. I did not bury it in a long accessibility page or a catch-all QA checklist. Mobile behavior deserves to sit close to the day-to-day build rules, because it affects layout, spacing, components, content, and testing.
| Rule | Every user-facing page, component, and flow must be usable on mobile before merge. |
| Minimum width to test | Test at a narrow mobile width, starting around 360px wide. |
| Tap targets | Interactive elements need enough spacing to avoid accidental taps. |
| Text | Text must be readable without pinch zooming. |
| Layout | No accidental horizontal scrolling. Tables, code samples, and wide media need an intentional mobile treatment. |
| Forms | Labels, inputs, errors, and helper text must remain clear on small screens. |
| Navigation | Primary actions should stay easy to find and use. |
This format worked better than a paragraph because it lets someone scan the rule while they are building. I like docs that behave like tools. If I have to read three dense sections just to remember whether a button can be 28px tall on mobile, the doc is not helping enough.
Where I placed it in the docs
I debated where this should live. At first, I had it under quality checks. That felt clean, but a little late in the process. If mobile usability only shows up during QA, the builder may have to rework the layout after everything feels finished.
So I moved it into the development standards area, right near component behavior and page layout guidance. That placement sends a better signal: mobile is part of the build, not a final polish pass.
I also added a shorter reminder in the pull request checklist. The docs hold the full rule. The checklist gives the nudge at the moment of merge.
The mobile checklist I attached to the rule
The rule needed a companion checklist. I kept it short because long checklists get ignored. The goal was to make mobile testing feel doable in two or three minutes for a normal change, then deeper if the change affects a key flow.
- Open the page at a narrow mobile width, around 360px.
- Scan for accidental horizontal scroll.
- Check that headings, body text, labels, and errors are readable.
- Tap every primary action and make sure spacing feels safe.
- Complete the main user task on mobile.
- Check empty, loading, error, and long-content states if the screen has them.
The long-content state is the one I almost forgot. It is also where mobile layouts break all the time. A card title that looks perfect with six words can wreck the layout with sixteen. Same with names, file titles, product labels, slugs, and status messages.
What broke while testing the rule
After writing the first version, I ran it against a few existing screens to see if it was realistic. That part was useful and slightly annoying, which usually means the rule is doing its job.
The first issue was a settings table. On desktop, it looked tidy. On mobile, it pushed the whole page sideways. The quick fix would have been to wrap the table in a scroll container and call it done. That is sometimes fine, but this table only had two meaningful columns, so a stacked mobile layout was better.
I changed the guidance to say wide content needs an intentional mobile treatment. That leaves room for horizontal scrolling when it makes sense, like code samples or data-heavy tables, but it prevents lazy overflow from passing as responsive design.
The second issue was button spacing. A pair of secondary actions sat too close together in a card footer. I had tapped the wrong one twice during testing. That made the rule feel less theoretical. If I can mis-tap it while calmly testing on my own device, a real user can absolutely mis-tap it while walking, multitasking, or using an older phone.
The third issue was form errors. On desktop, the error text sat neatly under the input. On mobile, the layout wrapped in a way that made the error feel attached to the next field. That is the kind of bug that does not show up in a screenshot unless you are looking for it.
The small wording change that made the rule better
I originally wrote, “Pages should be mobile responsive.” I changed it to, “Pages must be usable on mobile.”
That wording matters. Responsive can become a CSS checkbox. Usable forces the builder to think about the person holding the device.
A layout can technically respond to screen size and still feel awful. A sidebar can collapse. A grid can turn into one column. A menu can hide behind an icon. None of that guarantees the page is pleasant to use.
Usability pulls in the full experience: reading, tapping, scrolling, scanning, correcting mistakes, waiting for data, and finishing the task.
How I handled exceptions
I did not want the rule to pretend every screen can become a perfect tiny-phone experience. Some content is naturally wide. Some admin tools are dense. Some workflows are rare on mobile but still need to avoid breaking.
So I added an exception note: if a page cannot fully adapt to mobile because of the content type, the limitation needs to be intentional, documented, and safe. That means no mystery overflow, no hidden primary actions, and no broken navigation.
For example, a wide comparison table might scroll horizontally on mobile. That is acceptable if the scroll area is clear, the rest of the page stays fixed to the viewport width, and the user can still understand what they are looking at. A page that accidentally creates a full-body horizontal scroll because one element is too wide does not pass.
Adding the pull request reminder
Docs are helpful, but they are not magic. People forget. I forget. So I added a lightweight reminder to the pull request checklist.
The checkbox is simple: “Tested the main change at mobile width and confirmed the primary flow is usable.”
I like that phrasing because it does not ask for perfection across every possible screen size. It asks for a real test of the main change. If the change touches a component used across the app, then the builder should test a few places where that component appears. If the change touches one page, test that page and its main states.
This is the part that keeps the rule practical. A rule that demands too much gets skipped. A rule that fits into the normal rhythm has a better chance of sticking.
A quick testing flow that worked well
Here is the testing flow I used while refining the docs. It is not fancy, but it catches a lot.
- Open the changed page in the browser.
- Switch to responsive mode and set the width to around 360px.
- Refresh the page at that width so any initial layout behavior runs from mobile size.
- Scroll from top to bottom without interacting and look for overflow, cramped sections, or clipped content.
- Use the page normally. Tap buttons, open menus, fill forms, trigger errors, and complete the main task.
- Test one awkward content case, like a long title, missing image, empty state, or validation error.
Refreshing after resizing is a small habit, but it matters. Some components measure the viewport on load. If you resize after the page is already mounted, you might miss bugs that happen when a user lands directly on the page from a phone.
What I learned from writing the rule
The main lesson: documentation works better when it is written from the point of friction.
If the friction is “people forget to test mobile,” then a giant essay is not the fix. A clear rule, a short checklist, and a merge reminder are better. If the friction is “people do not know what counts as usable,” then examples and pass-fail language help more than broad advice.
I also learned that mobile usability is a team habit, not a single task. You can fix one page today, but the product only stays good if the next ten changes respect the same baseline.
That is why I am treating this as a living doc. If we hit a new pattern, like sticky footers covering actions or modals that feel trapped on small screens, I will add that to the rule. Not as a lecture. As field notes from real builds.
The version that shipped
The final version is short enough to use and specific enough to enforce. That was the balance I wanted.
Every user-facing page, component, and flow must be usable on mobile before merge. Test the main change at a narrow mobile width, confirm text is readable without zooming, controls are easy to tap, layout does not create accidental horizontal scrolling, and the primary task can be completed.
That paragraph now sits in the dev docs, with the checklist underneath it. The pull request template has the matching checkbox. Small change, but it gives every future build a better default.
I like this kind of progress. It is not flashy. It does not feel like a big feature launch. But it raises the floor for everything that comes after it. The next time I build a page, the rule is sitting there waiting for me, quietly asking: did you try this on a phone yet?