How FreeITSM is being made usable on a phone — the strategy, the one hard rule that keeps it safe, the reusable patterns, the hard‑won device lessons, and how to bring a new page along. Like Theming & Dark Mode, this is a gradual, non‑breaking rollout layered on top of the existing desktop app rather than a rewrite or a separate mobile site.

Status: Tickets (the inbox) is done deep and is the reference implementation — the master‑detail stack, the drawers, and every reading‑pane action panel (note, reply, forward, schedule, Ask‑AI) work on a phone. The landing page (module launcher) and the waffle menu are mobile‑friendly on every page. Assets is the second module brought along — its list, its detail pane, and its table view, dashboard, settings and servers pages. Calendar is the third: the month grid becomes coloured dots with a tapped‑day agenda, and its table and settings pages inherited their treatment from the Assets round at no CSS cost. Knowledge is the fourth, and the first where search is the primary action — so it goes into the sub‑bar rather than behind a button, and an article's author‑written HTML (wide images, tables, code) is contained so it can't take the layout down with it. Service Status is the fifth, and the first that needed no JavaScript at all — three <link> tags and a CSS layer. Watchtower is the sixth: the attention dashboard was 864px wide on a 360px screen before opting in, and its card metrics became an aligned grid rather than a ragged wrapping row. Problem Management is the seventh, and had the worst starting point of the lot — a fixed sidebar left the list 110px wide on a phone, which every automated check passed. Change Management is the eighth, and half of it came free by inheriting layers built on shared class names. Software is the ninth, and went furthest on that: three of its six pages needed nothing at all, including its 1555-row inventory table, which picked up a finished card feed built for Asset Management because both modules had named the table the same thing. Tasks is the tenth: its Kanban board became one status per screen with a swipe between them, and its detail panel is the round that proves a headless harness can clear a screen that is broken on a real phone — the fault was a native date field, which iOS draws with the month spelled out and a desktop browser does not. Morning Checks is the twelfth (#1269), and turned up a general trap: the module had its own @media block predating the rollout, so a third file was styling the screen — before styling anything for a phone, find what is already styling it. Forms is the thirteenth, and the round where two of its four real faults were invisible to every containment check: a submissions page 1,400px wide inside a container that scrolled, so the document measured clean, and an approvals sidebar that squeezed the content to 100px with its headings at clientWidth: 0. It also ends a long‑standing compromise — a card feed can now keep its column headings, harvested from the table's own translated <thead> instead of hardcoded into the stylesheet. Contracts is the fourteenth and by some way the largest — 22 pages, including the thirteen‑page RFP Builder — and the round that found nine modal shells in one module where LAYER 3 knew about one, which matters because LAYER 3 carries the anti‑zoom rule and an unreached sheet does not degrade, it switches the whole mobile layer off. It also proved that a CSS‑only opt‑in hides a module's navigation: the views drawer is parked off‑screen until mobile.js injects the button that opens it. Honest state: good for the core "on‑the‑go analyst" flow, not yet mobile‑complete — see Where it stands at the bottom. Tickets settings followed in #1005 — 18 tabs, and the first page that had to opt out of a LAYER 2 rule.

The target is the on‑the‑go analyst — someone away from their desk who needs to triage the inbox, read a ticket, reply, change its properties, and link/record things. It is deliberately not an attempt to make every one of the ~20 modules fully usable on a phone.

⚠️ This section used to say the Network Mapper canvas and the Process Mapper "stay desktop‑first", full stop, and that was too coarse. All three canvases have since been brought along, and they landed in three different places — which is the useful part:

	the drag	what shipped
Process Mapper	hand‑rolled, and every per‑step action is behind contextmenu	read‑only, said plainly
Network Mapper	hand‑rolled, but placing and deleting were the missing half	read‑only, then place + move + delete by finger when Ed asked
Workflow	hand‑rolled, but the layout is auto‑generated	fully usable, with no touch‑drag layer at all

🔑 So the question is not "does the drag work on touch?" but "what is the drag FOR?" — decoration on a generated layout needs nothing; the only way to place or remove a thing needs replacing. Say which of the three you are shipping, out loud, before writing anything. The Gantt timeline is still untouched.

⚠️ "Drag is out of scope" used to be written here as a blanket rule, and that was wrong. A drag built on HTML5 drag‑and‑drop works on a phone — iOS Safari has driven it from a long press since iOS 11 — which is why reordering checks in Morning Checks settings and fields in the Forms builder both work on a device today. Only a hand‑rolled mousedown/mousemove drag (a resize divider, a mapper canvas) has no touch events and genuinely cannot work. Check which one a module uses before ruling anything out: Techniques §22.

So the scope is a focused mobile experience for a handful of high‑value journeys, done well — Tickets first, then Assets.

This is the north star, and it's what makes the rollout safe to do incrementally:

Every mobile style lives inside a @media (max-width: 768px) block, and every mobile behaviour is gated on matchMedia('(max-width: 768px)').

The core is two shared files:

This mirrors the dark‑mode safety net: just as var(--token, #fallback) made tokenising a stylesheet non‑breaking, the @media/matchMedia gate makes adding mobile behaviour non‑breaking. You can convert a page and know with certainty you changed nothing for desktop users.

Verify the CSS gate holds — this should print nothing:

grep -nE "^[^[:space:]/}].*\{" assets/css/mobile.css | grep -v "@media"

Corollary — injected chrome must be hidden off‑mobile. mobile.js injects DOM (a back/folders sub‑bar, a views hamburger, section sheets). Because mobile.css is @media‑only it cannot set a desktop default of display:none. So injected elements are either created with an inline style="display:none" (sheets) or toggled by a syncBar() function that runs on load and on every matchMedia change.

mobile.css is the home for page‑specific mobile rules (the tickets inbox links it). But there are two important exceptions, both learned in practice:

• Shared components put their mobile @media in the component's own file. The waffle menu is on every page; its mobile drawer rules live in includes/waffle-menu.php's own <style> (behind an @media block), not in mobile.css — otherwise the drawer only works on the one page that links mobile.css. Rule of thumb: if a shared component needs mobile treatment app‑wide, gate it in the component's file.
• A standalone page can carry its own @media block rather than link mobile.css. The landing page (module launcher) does this — because mobile.css carries tickets‑inbox body/pane rules (body{height:100dvh}, .main-container{overflow:hidden}) that would clip a scrolling launcher page. When mobile.css's baggage would fight a page, a self‑contained block is cleaner.

Per‑page opt‑in. A page joins the mobile experience by linking mobile.css (and, where it needs behaviour, mobile.js) in its <head>, after its own stylesheet so the @media rules win on ties:

<link rel="stylesheet" href="../assets/css/inbox.css?v=40">
<link rel="stylesheet" href="../assets/css/mobile.css?v=62">   <!-- opt in -->
...
<script src="../assets/js/inbox.js?v=53"></script>
<script src="../assets/js/mobile.js?v=26"></script>           <!-- after the page's JS -->

mobile.js loads after the page's own script so it can wrap the globals that page already exposes (see below) rather than editing them. Bump the ?v= query whenever you change a file.

⚠️ Safari caches the HTML page itself. Bumping ?v= busts the CSS/JS, but Mobile Safari also caches index.php, so it may keep requesting the old version numbers until you hard‑clear. A stale mix (new JS + old CSS) produces baffling "it got worse" symptoms. Always full‑clear Safari before judging a fix on‑device.

The hardest conceptual problem on mobile is navigation: how do you move between modules, between views inside a module, and between panes that normally sit side‑by‑side? FreeITSM answers each with a distinct affordance.

The two drawers are symmetric — modules left, views right — which keeps them easy to tell apart.

These are the building blocks. Tickets uses all of them; future modules should reach for the same vocabulary. In mobile.css they're organised into numbered LAYERS (1–29). For the full code‑level catalogue — including the Shadow‑DOM per‑message horizontal scroll, the iOS "reflow to desktop" trap, and how it's all verified headlessly — see Techniques & Tricks.

⭐ The one design decision that comes up every single time: a wide table becomes a card feed, or it keeps its columns and scrolls sideways. Both are defensible, so it gets re-argued on every module. The rule — and the tell that settles most cases, does a column hold prose? — is written up as Techniques §11: Card feed or horizontal scroller?. Read it before deciding, not after.

A multi‑pane split becomes a one‑pane‑at‑a‑time slide stack. State lives in a single attribute on <body> (data-mobile-pane), and the panes are absolutely positioned and slid with transform: translateX(...). Wiring it to history.pushState makes the device back button pop the stack, which is what makes it feel native rather than like a resized website.

The canonical .modal-content (used app‑wide) fills the screen on mobile — so the reply composer, pickers and forms get room instead of a cramped centred box. One rule, every modal benefits.

The sheet from #2 is full‑screen, but the modals were built as centred desktop boxes, so their single field sits at a fixed height with dead space below. Make the modal a flex column and let its main field grow to fill (scoped by #id so multi‑field forms keep their sizing). Done for the note box, the reply/forward editor (TinyMCE, found via :has(#emailBody)), etc.

When a section crowds a small screen, relocate its DOM node into a full‑screen sheet opened by a button. Config‑driven, so adding another panel is one line.

Action buttons drop their text labels to icons only and move to a bottom bar (via flex order) below the scrolling content. When there are too many, keep the first few and push the rest into a "⋯" overflow popover so it stays a single row.

Verbose blocks (e.g. a ticket's From/To/Date/Cc) start collapsed behind a tappable summary + chevron, Gmail‑app style.

A fixed‑width desktop side panel (e.g. the 420px Ask‑AI chat) becomes full‑width 100dvh on a phone. If it's already a flex column, the body scrolls and the input bar stays pinned for free.

These are the bugs that separate "works in DevTools device mode" from "works on an actual iPhone." Every one of them cost a test‑loop round; bank them.

📌 Audit tinymce.init on every module. A sweep in #1388 found eleven rich‑text editors in the product and six of them unguarded, three of those inside modules already shipped as mobile‑friendly. CSS cannot reach into a TinyMCE iframe, so the guard has to be in each editor's own content_style — and it is therefore missed every time an editor is added to a page after that page's mobile round. There is no desktop risk to weigh: pointer: coarse cannot match a mouse.

iOS Safari auto‑zooms when you focus any form field whose font is smaller than 16px. In a full‑screen modal sheet this cascades disastrously: the zoom makes the sheet spill wide → Safari reflows the page to a desktop‑width layout → the max-width: 768px rules stop matching → the phone modal reverts to the big centred desktop box. It looks like everything "went to desktop mode."

Fix: force 16px on every focusable field on mobile.

.modal-content .form-input,
.modal-content .form-textarea,
.modal-content .form-select { font-size: 16px; }

For rich‑text editors the content lives in an iframe CSS can't reach, so fix it in the editor's config — and key it off the device, not width, so desktop is untouched:

// TinyMCE content_style — 14px desktop, 16px on touch so iOS doesn't zoom.
content_style: 'body { font-size: 14px; } @media (pointer: coarse) { body { font-size: 16px; } }'

@media (pointer: coarse) reflects a touch device (phones) vs pointer: fine (mouse), so desktop stays byte‑identical — cleaner than a width query, which is unreliable inside an iframe.

iOS gives native date/time inputs an intrinsic width that ignores width: 100%, so the grey field pushes past the right edge of a narrow sheet. A max-width cap alone doesn't tame it. Fix: -webkit-appearance: none (makes iOS honour the box model) + max-width: 100% + reset the internal value margin. The native picker still opens on tap.

.modal-content input[type="date"],
.modal-content input[type="time"] {
    -webkit-appearance: none; appearance: none;
    width: 100%; min-width: 0; max-width: 100%; box-sizing: border-box;
}
.modal-content input[type="date"]::-webkit-date-and-time-value { margin: 0; text-align: left; }

A bottom‑anchored input (note box, chat input) can end up behind the on‑screen keyboard, because the keyboard overlays a fixed full‑height sheet rather than resizing it. A visualViewport JS handler to fit the sheet above the keyboard was tried and made things worse (unpredictable on iOS) and was removed. This is the top remaining rough edge — it needs a safer approach, not the naive one.

A desktop‑only body class driven by a saved preference can be re‑applied on the phone and break the mobile layout. The real example: a saved tickets_popout (full‑screen reading‑pane mode) made inbox.js add body.ticket-popout on every ticket open — including on a phone — and its .email-list-container { display:none } hid the list, so the mobile Back button had nothing to return to. Fix: neutralise the mode on mobile at the source — wrap the function that manages the class and strip it when mq.matches, with a CSS backstop. Watch for other desktop‑only body classes doing the same.

mobile.js never edits the big inbox.js. Top‑level let/function declarations in a classic script share the global lexical environment, so mobile.js can:

• Read the page's state directly — currentEmail, ticketAttachments (bare identifiers, typeof‑guarded).
• Wrap the page's global functions to add mobile behaviour after they run — selectEmail, selectFolder, renderAttachmentInfoBar, syncPopoutToTicketState.

This keeps the renderer untouched (desktop safe) while layering mobile behaviour on top. The one justified inbox.js edit so far was a single content_style string (see iOS lesson #1) — because CSS genuinely can't reach inside a TinyMCE iframe — and even that is gated on pointer: coarse.

1. Link mobile.css (and mobile.js if it needs behaviour) in the page <head>, after the page's own CSS/JS. Bump the version query. (For a shared component, put the @media in the component's own file instead — see placement.)
2. Fix the height model. Desktop shells often use height: calc(100vh - 48px), which assumes a fixed header — wrong once the header wraps. Switch the body to a flex column so the header takes its natural height and the content flexes (flex: 1; min-height: 0). Use 100dvh, not 100vh.
3. Collapse side‑by‑side layouts into the master‑detail stack (or stack vertically if there are only two).
4. Relocate crowded sections into sheets; tighten padding; icon‑only dense button rows (+ overflow); collapse verbose blocks; fill compose modals.
5. 16px every focusable field (iOS lesson #1). Check native date/time inputs (lesson #2).
6. Wrap, don't edit. Wrap the page's existing global handlers from mobile.js.
7. Keep every rule inside the @media block and every behaviour behind mq.matches.
8. Test on a real device — full‑clear Safari first — there is no substitute.

When another module is brought along, add a Mobile-Friendly-<Module>.md page here and a row above.

For a free, solo‑built product this is a genuinely strong mobile experience on the core journey — better than most free ITSM tools, which have no mobile or a broken responsive layout. But it's good for the core flow, not mobile‑complete:

• Nineteen modules deep — Tickets, Assets, Calendar, Knowledge, Service Status, Watchtower, Problem Management, Change Management, Software, Tasks, Morning Checks, Forms, Contracts, the LMS, CMDB, Process Mapper, Network Mapper, Workflow and System are reflowed; the remaining modules have the shell (waffle/landing) but not their bodies. Process Mapper is readable, not authorable — a deliberate limit, stated on its page. Network Mapper started there and then gained placing, moving and deleting a node by finger (#1468); only its connectors are still desktop-only. Workflow is fully usable, because its layout is generated rather than dragged.
• Bottom inputs vs the keyboard — the top remaining rough edge (see iOS lesson #3).
• Accessibility — icon‑only buttons and injected chrome need an aria-label sweep.
• No PWA / offline / push — "on the go" would eventually want installable + push.
• All hand‑crafted per page — no systematic responsive framework, so breadth keeps costing per‑page effort.
• Self‑verification works but is hand‑built — a headless 360px iframe measuring scrollWidth, plus a desktop positive control, catches real overflow bugs (it found a 776px settings overflow no screenshot made obvious). It is assembled per page, not a test suite, and a real device pass is still the final word.

Recommended next move: finish Tickets to a defensible "done" (kill the keyboard‑input issue + an aria sweep), then make a deliberate breadth‑vs‑depth call — either bring 2–3 more high‑mobile‑value journeys (approvals / morning checks / service status) or invest in a PWA shell. The pitch decides: "tickets from your pocket" (depth) vs "your whole ITSM in your pocket" (breadth/PWA).

• CSS: assets/css/mobile.css — one @media (max-width: 768px) block, LAYERS 1–36 (148 pages opted in). ⚠️ Two layers are numbered 30 (Process Mapper and CMDB, shipped in the same week); Network Mapper is 31 and Workflow is 32.
• JS: assets/js/mobile.js — one matchMedia‑gated IIFE.
• Shared‑component mobile CSS: includes/waffle-menu.php (@media block in its own <style>).
• Code‑level trick catalogue: Mobile: Techniques & Tricks.
• Related: Theming & Dark Mode (the same gradual, non‑breaking philosophy), Architecture.