---
name: responsive-ui
user-invocable: true
description: >-
  How to make an Adom app adapt from phone to desktop: a rich, dense layout on a large screen and a
  lean, thumb-friendly one on a phone, the same app reshaped rather than a desktop layout shrunk
  until it is unusable. Covers a breakpoint set, reshape-not-shrink, what to show on desktop versus
  collapse on mobile, 44px minimum touch targets, safe-area insets and the soft keyboard, and the
  big one: tooltips on touch, where hover does not exist, so you replace hover tooltips with visible
  labels, tap-to-reveal sheets, or long-press. Read BEFORE building any UI that a phone might open.
  Trigger words: responsive, responsive design, mobile layout, mobile UI, phone layout, adapt to
  screen, breakpoint, breakpoints, media query, touch target, mobile tooltip, hover none, pointer
  coarse, tap to reveal, long press, safe area, soft keyboard, desktop vs mobile, container query.
---

# Responsive and touch

The same Adom app should feel native on a 32 inch monitor and on a phone. This is part of treating
the user well, not an afterthought bolted on at the end.

## Reshape, do not shrink

- **Pick a small set of breakpoints** and change the layout at each, rather than scaling one fixed
  desktop layout down. A reasonable default set:
  - phone: up to 600px
  - tablet: 600 to 1024px
  - desktop: 1024px and up
- **Rich on desktop, focused on mobile.** A desktop has room for side panels, dense tables,
  persistent toolbars, and secondary stats inline. On a phone:
  - collapse multi-column layouts into a single column,
  - move primary actions into a bottom bar or a menu within thumb reach,
  - hide secondary detail behind a tap, do not cram it in,
  - turn a fixed HUD into a bottom sheet.
  The app header already models this: the subject meta line hides below ~720px and returns on
  request.
- **Container queries** are good when a panel needs to reshape by its own width, not the viewport's.

## Touch

- **Touch targets are at least 44 by 44 px.** Fingers are not cursors. Space them so a thumb does
  not hit two at once.
- **Respect safe areas and the soft keyboard.** Use `env(safe-area-inset-*)` for notches and home
  bars, keep primary actions reachable with a thumb, and do not let the on-screen keyboard cover the
  field being typed into.

## Tooltips on touch: hover does not exist

This is the rule that is easy to miss. A hover tooltip can never fire on a phone, so it must not be
the only way to learn a control.

```css
@media (hover: none), (pointer: coarse) {
  /* hover tooltips never trigger here */
}
```

Under that query, replace the hover tooltip with one of:
- **A visible label** next to or under the icon (best for primary controls).
- **A tap that opens an info sheet or popover** describing the control (good for dense toolbars).
- **A long-press** that reveals the description (familiar from mobile OSes).

Never hide essential meaning behind a hover a phone can never produce. See the `tooltips` skill for
the desktop renderer this complements.

## Test it

Test every app at a phone width before publishing, not just at desktop. When the AI is building the
app it can resize the pup window to a phone viewport and ralph-loop the mobile layout the same way
it does the desktop one (see `ai-driven-apps`).

## Related skills

`tooltips` (desktop tooltips), `app-shell` (the fluid layout that reshapes), `human-ui-patterns`,
`ai-driven-apps` (testing the mobile layout), and `adom-ui-design` (the hub).