The Expenses apps were built desktop-first and patched for mobile afterward. The admin
console shipped outright unusable on phones (full-width sidebar over the content,
overflowing tables) and needed a retrofit in v0.2.0–v0.2.1. Retrofitting is
painful and error-prone; designing for the small screen up front is cheaper and
produces better layouts. Real users open these on phones.
Decision
New frontend work is authored mobile-first.
Author the small-viewport layout as the base, then enhance upward with min-width media queries — not desktop-base + max-width patches.
Minimum bar (definition of done) for any frontend surface:
Works at 375px wide with no horizontal page scroll.
No business-critical element is hidden on mobile. Reflow/restack it —
never display: none an action the user needs.
Dense data tables either reflow/stack (e.g. rows → cards) or use a contained horizontal scroll (the table scrolls inside its own wrapper via overflow-x: auto; the page never scrolls sideways) — whichever keeps the
data readable. What’s banned: page-level horizontal scroll, and a clipped /
cut-off column (an overflow: hidden wrapper with no scroll container).
The mobile viewport is actually checked before “done” (generalizes the prior feedback_mobile_check_required rule).
Brand-neutral mobile-UX baseline (the useful kernel of systems like Material — ergonomics, not a visual skin; each app keeps its own design language, so we do not adopt the Material look, Roboto, FABs, etc.):
Touch targets ≥ ~44px on the mobile layout — no dense desktop-size hit
areas (padding counts toward the target).
Primary action stays thumb-reachable — prefer a bottom sheet / sticky
bottom action over a top-corner placement for a screen’s main action on phones.
Visible press/active + focus state on interactive elements — never
hover-only (touch has no hover).
Existing code is desktop-first (max-width queries). This ADR governs new
work and surfaces being touched — not a wholesale rewrite. Migrate
opportunistically.
Per-app responsive mechanics (breakpoints, drawer, table-stacking) are recorded
in the app’s project folder in this handbook (e.g. docs/expenses/frontend-web/0002-responsive-layout-mechanics.md, docs/expenses/frontend-admin/0001-responsive-layout-mechanics.md).
Consequences
Mobile is a first-class default, not an afterthought, so we stop shipping
desktop-only screens that need a later rescue.
A clear, checkable bar that the handbook:ask-mobile reviewer agent can audit.
Mixed paradigms during the transition (old max-width, new min-width) —
accepted; consistency improves as surfaces are revisited.
Example
Real code from the repos — optional
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
export const Inner = styled.div` display: grid; align-items: center; /* base = phone: brand and actions pair on one row, nav takes its own */ grid-template-columns: auto auto; grid-template-areas: 'brand actions' 'nav nav'; justify-content: space-between; /* enhance upward, never patch downward */ @media (min-width: ${({ theme }) => theme.layout.breakpoint.xl}) { grid-template-columns: auto 1fr auto; grid-template-areas: 'brand nav actions'; }`;
The base case is the phone and every media query is min-width. Nothing here is a max-width patch undoing a desktop assumption.
The header earned this rule the hard way. It was written with flex-wrap and looked
fine in English; in Portuguese — 20–30% longer — six anchors wrapped onto three centred
rows and the CTA dropped onto a line of its own, eating about a quarter of a 390px
viewport. flex-wrap chose where to break, and it chose badly.
Two consequences the rule demands, both visible here: the nav becomes one horizontally
scrollable row rather than a wrapped block (contained scroll, the page never scrolls
sideways), and nav items get a 40px minimum height because they were landing near 33px.
The header CTA is hidden below md — allowed only because contact is reachable from the
hero, the founder section and the footer, so no business-critical action is lost.