> 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/content-creator-pt/criar-para-mobile/desenvolver/ui-best-practices.md).

# Melhores práticas de UI

O que fazer e o que não fazer ao conceber UIs de cena que funcionem bem em mobile.

Ainda não existe uma receita única comprovada para a UI mobile do Decentraland — a plataforma é nova e ainda estamos iterando. As recomendações nesta página são as melhores práticas atuais, extraídas do trabalho em cenas reais. Considere-as um ponto de partida e teste em um dispositivo real.

{% embed url="<https://www.youtube.com/watch?v=5OmTTzpPdDc>" %}

## FAÇA

* **Projete UIs específicas para mobile**, ou varie sua UI conforme o tamanho da tela e a plataforma. Use [`isMobile()`](/creator/content-creator-pt/criar-para-mobile/desenvolver/detect-platform.md) para ramificar.
* **Mantenha a UI crítica dentro da** [**área segura**](/creator/content-creator-pt/criar-para-mobile/desenvolver/safe-area.md)**.** As margens de hardware do dispositivo (notch, barra de status, indicador de início) são removidas para você por padrão — basta não optar por sair com `screenInset: 'none'`. Os controles do próprio cliente são uma área separada, e `screenInset: 'interactable'` cobre parte dessa tarefa: ele posiciona sua UI no retângulo que o Explorer designa para a UI da cena. No mobile, isso libera os controles do lado esquerdo; os botões de ação no canto inferior direito são desenhados sobre a área por design, então mantenha [esses cantos](/creator/content-creator-pt/criar-para-mobile/desenvolver/safe-area.md#where-the-client-controls-live) em mente. `'interactable'` requer cliente mobile `1.12.1` ou mais recente — clientes mais antigos não reportam nenhuma margem e a UI cobre a tela inteira.
* **Minimize as opções.** Mostre apenas o que o jogador precisa agora e revele o restante progressivamente.
* **Coloque diálogos acionáveis no centro da tela** — em qualquer lugar onde o jogador precise ler e responder.
* **Coloque mensagens não acionáveis no centro superior** — estado, notificações e informações ambientais.
* **Oculte os controles por toque por trás de uma UI em tela inteira.** Enquanto uma tabela de pontuação, uma loja ou um painel de resultados estiver aberto, o jogador não precisa pular nem pressionar E. Veja [UI em tela inteira sobre os botões de ação](#full-screen-ui-over-the-action-buttons).

## NÃO FAÇA

* **Não dimensione elementos de UI apenas em pixels sem ter uma tela virtual em mente.** Os valores em pixels são escalados em relação à `virtualWidth` / `virtualHeight` resolução de referência descrita em [UI na tela](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale) — `1600x720` por padrão no mobile, `1920x1080` no desktop e na web. Saiba contra qual resolução de referência seus valores em pixels foram criados, passe-a explicitamente se não for a padrão e combine-a com dimensionamento ciente da plataforma. Desative a tela virtual apenas (passando um tamanho de `0`) se você realmente quiser pixels brutos do canvas.
* **Não posicione elementos fora da área segura.** Eles entrarão em conflito com os controles do cliente.
* **Não ancore a UI no canto superior esquerdo nem na borda esquerda.** É ali que o cliente desenha o chat, o perfil e o joystick virtual, tudo sobre a UI da sua cena. Em vez disso, ancore à direita ou ao centro, ou use `screenInset: 'interactable'`. Veja [Nunca ancore sua UI no canto superior esquerdo](/creator/content-creator-pt/scenes-sdk7/conceber-a-experiencia/ux-ui-guide.md#never-anchor-your-ui-to-the-top-left).
* **Não coloque elementos interativos no canto inferior direito.** Os botões de ação são desenhados sobre essa região, e toques ali vão para os botões do cliente, não para a sua cena.
* **Não dependa de botões pequenos.** Alvos pequenos são pouco confiáveis para tocar em uma tela sensível ao toque.
* **Não vincule ações de tecla a `IA_ACTION_3`–`IA_ACTION_6`** (as `1`/`2`/`3`/`4` teclas de um teclado). Elas não são facilmente acessíveis no mobile. Veja [Entrada no mobile](/creator/content-creator-pt/criar-para-mobile/desenvolver/input-on-mobile.md).

## UI em tela inteira sobre os botões de ação

`screenInset: 'interactable'` mantém sua UI livre dos controles do lado esquerdo, mas os botões de ação no canto inferior direito são desenhados sobre essa área por design. Um painel que ocupe a área ainda é coberto ali, e toques nessa região acionam os botões do cliente em vez da sua UI.

Para um **HUD de gameplay** que precisa permanecer utilizável enquanto o jogador se move, mantenha-o fora do canto inferior direito: ancore-o no canto superior direito ou no centro superior.

Para um **UI que interrompe a jogabilidade**, como uma tabela de pontuação, uma loja ou uma tela de resultados, oculte os controles por toque enquanto ela estiver aberta e restaure-os ao fechar:

```ts
import { TouchScreenControls } from '@dcl/sdk/ecs'

function openScoreboard() {
  TouchScreenControls.hideAll()
  TouchScreenControls.hideJoystick()
  // ... mostre sua UI
}

function closeScoreboard() {
  TouchScreenControls.showAll()
  TouchScreenControls.showJoystick()
  // ... oculte sua UI
}
```

`showAll()` restaura apenas os botões do gamepad, então combine-o com `showJoystick()`. Ambos os helpers não fazem nada no desktop, então não há necessidade de ramificar pela plataforma. Veja [Controles na tela](/creator/content-creator-pt/scenes-sdk7/interatividade/touch-screen-controls.md) para o componente completo.

Se o avatar também deve parar de se mover enquanto o painel está aberto, adicione um [input modifier](/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/locomotion.md#freeze-the-player) por cima.

## Dimensionamento

A antiga regra prática — *desenhe no desktop e depois escale os tamanhos da UI em 3× para mobile* — antecede duas mudanças no SDK e não deve mais ser aplicada cegamente. Hoje, a maior parte desse 3× já é aplicada para você:

* **`devicePixelRatio` não participa do layout da UI.** A UI dimensionada em pixels agora renderiza `devicePixelRatio` vezes maior do que antes — normalmente **2–3× em um telefone**, e também em laptops retina. Não há como desativar.
* **A tela virtual tem padrões por plataforma**, `1600x720` no mobile em relação a `1920x1080` no desktop e na web, então o mesmo valor em pixels já cobre cerca de 1,2× mais da tela em um telefone.

Comece com os tamanhos do desktop sem alterar, meça em um dispositivo real — veja [Pré-visualização no mobile](/creator/content-creator-pt/criar-para-mobile/desenvolver/preview-on-mobile.md) — e aumente apenas onde os alvos de toque ou o texto realmente ficarem aquém. Faça ramificação com [`isMobile()`](/creator/content-creator-pt/criar-para-mobile/desenvolver/detect-platform.md) quando os dois realmente precisarem diferir.

## Relacionado

* [Recursos ausentes](/creator/content-creator-pt/criar-para-mobile/cliente-movel/missing-features.md)
* [Área segura do mobile](/creator/content-creator-pt/criar-para-mobile/desenvolver/safe-area.md)
* [Detecte a plataforma no código](/creator/content-creator-pt/criar-para-mobile/desenvolver/detect-platform.md)
* [UI na tela](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md)
* [Guia de UX e UI](/creator/content-creator-pt/scenes-sdk7/conceber-a-experiencia/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/ui-best-practices.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.