Mobile App

The sidebar hands over to MobileMenu

AppShell mounts both halves of the frame and lets CSS pick. Sidebar is hidden md:flex; MobileMenu is a Sheet whose content is md:hidden, and the hamburger that opens it lives inside AppHeader. No width is tested in application code.

Open the menu: the order inside it is deliberately not the sidebar’s. Workspace switcher, then this app’s nav, then the app list, then the user — because on a phone the thing you opened the menu to find is the current app’s navigation, and an ecosystem of eight products would otherwise push it below the fold.

Two more things live in this frame. A Banner sits under the app bar — in the frame, not in a screen, because “no signal” is true of every tab. It is a role="status" region, so Retry turning it into “Back online” is announced without moving focus. And the Today tab opens on a CircularProgress: how far through the day the crew is, named by its visible label and read out as “3 of 14”.

Two documentation-only concessions, both visible in the demo: the sheet is given md:flex so it opens on the desktop you are reading this on, and the phone renders its own hamburger because AppHeader cannot be squeezed into a 300px box. The sheet is fixed, so it covers the page rather than the frame — that is the component behaving correctly, and on a real phone the two are the same thing.

One list, two densities

The job table is six columns and 860px wide. At 375px that is a truncated site name and nothing else, so below md the DataTable is swapped for a stack of Item rows — the same StatusPill, AvatarGroup and RelativeTime, rearranged. Sort in one tab and the other agrees: both read one controlled sort object.

Detail arrives as a drawer

There is no room beside the list, and pushing a whole route for one record costs a navigation the user has to undo. ResponsiveDialog picks the presentation by width: below 768px — Tailwind’s md, moved with breakpoint — it is a Drawer, a bottom sheet with a grab handle that a thumb swipes down; from md up the same markup is a centred Dialog with a corner ×. The breakpoint lives in the package, like the shell’s. The footer is where the destructive action lives, behind ConfirmDialog — cancel a visit and it disappears from both tabs.

The Phone tab passes a breakpoint wider than any screen, so the Drawer opens on the desktop you are reading this on — a documentation-only concession, like the menu’s md:flex above; the Desktop tab keeps the default. The drawer takes focus when it opens: since 2.1.0 the package’s Drawer moves focus to the first control inside and keeps Tab there — vaul’s own default left it on the row behind the overlay, and Tab walked the page underneath a modal. On close, a Trigger gets focus back — but these rows open the detail from state. The Dialog branch then returns focus to the row by itself, since 3.3.0; the Drawer branch has no such return, so onCloseAutoFocus on ResponsiveDialogContent sends it back to the row — or to the first row left, when the visit was just cancelled. Its twin, onOpenAutoFocus, picks what takes focus first. Both branches honour both.

Search and filters at 375px

SearchFilterBar needs no mobile variant — its row already wraps, and the result count keeps a fixed min-h-7 so the list does not jump when a filter turns on. FilterChips does need one: six status chips do not fit one row at this width, so the page overrides flex-wrap into a scroll strip. Filter everything away and you get a real EmptyState, not a blank box.

First run: onboarding and sign-in

Onboarding is the one screen where a swipe is the primary control, so it is the one screen where Carousel earns its weight — drag, momentum and arrow keys come with it, and setApi exists so the app can draw its own dots. Sign-in is by phone, because a crew member has a phone and not always a work inbox. PhoneInput is given the workspace’s country — Vietnam, a workspace setting, not the language of this English UI — so a number typed the way people say it, 0912 345 678, is sent as +84912345678. The code goes into InputOTP. Both steps are FormField: submit either one empty and the error is wired through aria-describedby by the field, not by hand.

A long form, cut into steps

The FormSection is the desktop one, unchanged: its content is a 12-column grid, and every colSpan class starts at col-span-full and only widens at sm/md. A two-across form is one field per row here for free. What the phone adds is the split into steps — a Stepper, whose onValidate runs before every move forward, so Continue on an empty Findings step stops and puts the caret in the notes — and a footer that stays under the thumb instead of at the end of a scroll.

A job thread

Every message carries a RelativeTime, which renders a real <time> with the absolute timestamp in its title. LetterAvatar gives one person the same colour in every Comitor app. The composer sends on mod+Enter only — on a soft keyboard the return key is how people start a new line — and says so with KeyboardHint, which prints ⌘ or Ctrl per platform.

Profile and settings

Two screens that are almost entirely composites. InlineEdit replaces an “edit profile” round trip with a tap; StatCard stacks to one column and keeps its delta polarity honest — a falling time on site is coloured as good, a rising one is not. On the settings screen, Switch takes label and description itself, which is what makes the whole row a tap target rather than text sitting next to a control.

What actually changes below md

Two rows are a component swap, and in both the package makes it — AppShell with CSS, ResponsiveDialog with a media query. Field text is the package too: every field is text-base md:text-sm since 3.13.4, so there is nothing to set. The rest are the same components in a different arrangement — which is why a mobile screen in this system is a layout decision, not a second component library. For the full-width version of these screens, see Application Shell and Tasks & Projects.

Best practices