> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/build-for-mobile/develop/ui-best-practices.md). # UI Best Practices There is no single proven recipe for Decentraland mobile UI yet — the platform is new and we are still iterating. The recommendations on this page are the current best practices, distilled from work on real scenes. Treat them as a starting point and test on a real device. {% embed url="" %} ## DOs * **Design mobile-specific UIs**, or vary your UI by screen size and platform. Use [`isMobile()`](/creator/build-for-mobile/develop/detect-platform.md) to branch. * **Keep critical UI inside the** [**safe area**](/creator/build-for-mobile/develop/safe-area.md)**.** The device's hardware margins (notch, status bar, home indicator) are cleared for you by default — just don't opt out with `screenInset: 'none'`. The client's own controls are a separate area, and `screenInset: 'interactable'` covers part of that job: it positions your UI in the rectangle the explorer designates for scene UI. On mobile that clears the left-hand controls; the action buttons on the bottom right are drawn over the area by design, so keep [those corners](/creator/build-for-mobile/develop/safe-area.md#where-the-client-controls-live) in mind. `'interactable'` requires mobile client `1.12.1` or newer — older clients report no margins at all and the UI covers the whole screen. * **Minimize options.** Show only what the player needs right now and progressively disclose the rest. * **Place actionable dialogs at the center of the screen** — anywhere a player needs to read and respond. * **Place non-actionable messages at the top-center** — status, notifications, and ambient information. ## DON'Ts * **Don't size UI elements purely in pixels without a virtual screen in mind.** Pixel values are scaled against the `virtualWidth` / `virtualHeight` reference resolution described in [On-screen UI](/creator/scenes-sdk7/2d-ui/onscreen-ui.md#screen-virtual-scale) — `1600x720` by default on mobile, `1920x1080` on desktop and web. Know which reference resolution your pixel values are authored against, pass it explicitly if it isn't the default, and pair it with platform-aware sizing. Only disable the virtual screen (by passing a size of `0`) if you genuinely want raw canvas pixels. * **Don't place elements outside the safe area.** They will clash with the client's controls. * **Don't rely on small buttons.** Small targets are unreliable to tap on a touch screen. * **Don't bind key actions to `IA_ACTION_3`–`IA_ACTION_6`** (the `1`/`2`/`3`/`4` keys on a keyboard). They are not easily reachable on mobile. See [Input on mobile](/creator/build-for-mobile/develop/input-on-mobile.md). ## Sizing The old rule of thumb — *design on desktop, then scale UI sizes by 3× for mobile* — predates two SDK changes and should no longer be applied blindly. Most of that 3× is now applied for you: * **`devicePixelRatio` takes no part in UI layout.** Pixel-sized UI now renders `devicePixelRatio` times larger than it used to — typically **2–3× on a phone**, and on retina laptops too. There is no opt-out. * **The virtual screen defaults per platform**, `1600x720` on mobile against `1920x1080` on desktop and web, so the same pixel value already covers about 1.2× more of the screen on a phone. Start from your desktop sizes unchanged, measure on a real device — see [Preview on mobile](/creator/build-for-mobile/develop/preview-on-mobile.md) — and scale up only where tap targets or text actually come up short. Branch with [`isMobile()`](/creator/build-for-mobile/develop/detect-platform.md) when the two genuinely need to differ. ## Related * [Missing Features](/creator/build-for-mobile/mobile-client/missing-features.md) * [Mobile safe area](/creator/build-for-mobile/develop/safe-area.md) * [Detect the platform from code](/creator/build-for-mobile/develop/detect-platform.md) * [On-screen UI](/creator/scenes-sdk7/2d-ui/onscreen-ui.md) * [UX & UI Guide](/creator/scenes-sdk7/designing-the-experience/ux-ui-guide.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.decentraland.org/creator/build-for-mobile/develop/ui-best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.