> 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/scenes-sdk7/conceber-a-experiencia/ux-ui-guide.md).

# Guia de UX e UI

Dicas e práticas para criar cenas nas quais os jogadores vão querer ficar e voltar!

É de vital importância para nós que os criadores de conteúdo de Decentraland possam usar a criatividade ao máximo. Isso é essencial para que Decentraland se torne um lugar gratificante para explorar. No entanto, também é importante ter em mente que as cenas de Decentraland serão visitadas por uma grande variedade de usuários e queremos que sejam acessíveis a todos. Por isso, não podemos ignorar a necessidade de estabelecer critérios de design unificados: um guia que garanta que os jogadores tenham uma experiência intuitiva e agradável de forma consistente, independentemente da cena em que estejam.

Neste documento, partilhamos os Valores de Design de Decentraland, com o objetivo de promover o que consideramos serem as melhores práticas para criar a interface e a experiência dos jogadores. Esperamos que estes critérios possam servir como ponto de partida para criar e/ou melhorar as cenas que compõem o Metaverso.

## Valores de design

Todas as cenas de Decentraland devem ser concebidas tendo estes valores em mente:

* **Acolhedora**: O jogador sente-se calorosamente recebido.
* **Fácil de usar**: A UI é fácil e divertida de usar — evite reinventar a roda.
* **Fácil de aprender**: Os jogadores consideram a UI familiar e intuitiva. Os padrões devem ser usados de forma consistente em toda a cena.
* **Orientadora**: A cena dá uma ajuda. Texto, movimento, som e gráficos guiam os jogadores e dão-lhes indicações na direção certa.
* **Reativa**: Ação e reação claras às ações dos jogadores.
* **Minimalista**: Menos é mais. Os jogadores podem concentrar a atenção no que importa.
* **Interessante**: A cena tira partido dos aspetos que tornam Decentraland única e digna de ser visitada.
* **Com propósito**: Os jogadores têm um bom motivo para voltar.
* **Agradável**: Os jogadores apreciam o aspeto, o som e a sensação das coisas.

## Experiência do usuário

### Por onde começar?

Qual é o objetivo da sua cena? Oferecer uma bela paisagem para contemplar e explorar? É um museu? Um jogo para um jogador? Um jogo competitivo? Ou segue uma narrativa linear?

É importante ter este objetivo sempre presente em todas as etapas do processo de design. Ele deve orientar todas as suas decisões, que podem afetar profundamente a experiência dos visitantes.

Para cenas com um fluxo linear, em que cada etapa depende da anterior, recomendamos que delimite a cena e estabeleça um ou vários pontos de entrada fixos, para evitar que os jogadores se deparem com as coisas pela ordem errada. Além disso, os pontos de entrada são um excelente local para apresentar uma mensagem de boas-vindas ao jogador e explicar qual deve ser o seu objetivo na cena.

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-8002e215fc5f1b75d94c1feb415d19c3a31aa3ed%2Fux-instructions.webp?alt=media" alt="In-world banner" width="800"><figcaption><p>Instruções no mundo</p></figcaption></figure>

Se a experiência do jogador na sua cena não tiver de ser linear, mas ainda assim precisar de fornecer algumas instruções básicas para garantir que ele a aproveite ao máximo, pode apresentar instruções numa janela pop-up. É possível mostrar uma janela pop-up no ecrã do jogador assim que este entrar, independentemente da direção de onde venha, garantindo assim que os jogadores conheçam sempre o essencial.

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-97f77921fa7c0e473dcdb420c883d97d3fc8dc74%2Fux-banner.webp?alt=media" alt="Pop-up banner" width="800"><figcaption><p>Instruções em janelas pop-up</p></figcaption></figure>

{% hint style="warning" %}
**📔 Nota**: Certifique-se de que a janela pop-up não é demasiado intrusiva e que é fácil fechá-la clicando em qualquer lugar.
{% endhint %}

Uma mensagem de boas-vindas deve comunicar ao jogador o seguinte:

* O título da cena
* Dar as boas-vindas ao jogador
* Objetivo final e motivação do jogador
* Instruções/próximos passos
* *(Opcional)* Controlos. São sobretudo úteis se a sua cena usar eventos globais de botões. Caso contrário, os próprios itens indicam como usá-los quando o jogador passa o cursor sobre eles.

### Motivação

Provavelmente vai querer que os visitantes voltem à sua cena. Pense em formas de os motivar a fazê-lo! Pergunte a si mesmo: «O que faria um jogador querer voltar à minha cena ou recomendá-la a um amigo?»

Por exemplo, pode desafiá-los, propondo algo difícil o suficiente para exigir várias tentativas. Também pode organizar eventos competitivos para vários jogadores, que são uma oportunidade interessante para socializar. Transforme a sua cena num lugar dinâmico onde os jogadores gostem de passar o tempo!

### Feedback e som

O som desempenha um papel duplamente importante; não deixe de o usar! Por um lado, é vital para criar imersão: muitas coisas não parecem reais se não forem acompanhadas por som. O outro papel crucial do som é dar feedback sobre as ações do jogador. Se depender apenas de indicações visuais, não pode ter a certeza de que o jogador estará a olhar na direção certa para ver os efeitos das suas ações. Ao usar som, pode garantir que ele se apercebe de que algo aconteceu. Se combinar indicações visuais e sonoras, ouvir o som leva o jogador a procurar a indicação visual, caso não a tenha visto.

Tenha em mente que alguns jogadores podem estar a jogar com o som desligado. Se usar o som para dar instruções sobre a cena ou como elemento essencial da mecânica do jogo, tente também fornecer uma indicação visual na mesma direção. Por exemplo, pode apresentar texto na parte inferior da UI a acompanhar estes sons, como as legendas de um filme.

## Interface do usuário

Esta secção pretende ajudar a construir uma narrativa através do design da sua cena, direcionando a atenção do jogador para os elementos mais importantes. O bom uso das ferramentas aqui descritas pode tornar a experiência muito mais imersiva e bem-sucedida.

Não é possível exagerar a importância das cores, dos ícones, do movimento e da escala para transmitir a mensagem certa: tudo na cena comunica um significado, não se esqueça disso.

### Disposição

Tenha cuidado ao colocar a UI em áreas do ecrã que se sobreponham aos elementos predefinidos da UI de Decentraland. No cliente para computador, a UI predefinida de Decentraland (barra lateral, minimapa, chat, etc.) foi concebida para ocupar apenas os 25% do lado esquerdo do ecrã (destacados a vermelho na imagem). O espaço restante do ecrã é uma zona segura que os criadores de conteúdo podem usar livremente.

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-30a2804e36ab358f7fafec3cffac8b4b7494a185%2FUI-Zones.webp?alt=media" alt="Screen regions used by UI" width="800"><figcaption></figcaption></figure>

Não há restrições à colocação de elementos de UI nos 25% esquerdos do ecrã, mas tenha em conta que o Explorer está continuamente a fazer alterações e melhorias ao seu design. Qualquer espaço que não esteja oculto nessa área hoje poderá ser coberto em versões futuras.

{% hint style="info" %}
**📱 Área segura para dispositivos móveis**: O [cliente para dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/cliente-movel/overview.md) desenha os seus próprios controlos sobre parte do canvas: o **lado esquerdo** (chat, pesquisa, perfil, joystick, emotes), o **canto superior direito** (controlos de perfil e da câmara) e o **canto inferior direito** (botões de ação e interação). Não meça essas áreas manualmente: desenhe dentro da área indicada pelo cliente, usando `screenInset: 'interactable'`. Mantenha os elementos de UI essenciais no centro ou na parte superior central do ecrã e siga a [Área segura para dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/safe-area.md). Use [`isMobile()`](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/detect-platform.md) para alternar entre esquemas quando as limitações do computador e dos dispositivos móveis forem incompatíveis.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Os elementos de UI das cenas e dos wearables inteligentes aparecem sempre numa camada atrás da UI predefinida do Decentraland.
{% endhint %}

#### Nunca ancore a sua UI no canto superior esquerdo

O erro de disposição mais comum é fixar um painel no canto superior esquerdo ou deixá-lo na origem de um elemento raiz que cobre o ecrã. Esse canto e toda a margem esquerda são onde o Explorer apresenta o minimapa e o chat, e, nos dispositivos móveis, o joystick virtual. A UI da cena colocada aí continua a ser desenhada, mas a UI do próprio cliente é apresentada por cima, acabando por a cobrir e tornando muitas vezes os seus botões impossíveis de clicar. O motor de disposição não avisa sobre isto.

Em vez disso, use uma destas opções:

* **Ancore à direita ou centre o elemento.** Para uma pontuação, um temporizador ou um painel pequeno, defina `positionType: 'absolute'` e `position: { top: 40, right: 40 }`, ou centre-o com `justifyContent: 'center'` no elemento raiz.
* **Deixe que o Explorer lhe indique onde é seguro.** Defina [`screenInset: 'interactable'`](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-inset-area) no renderer. A sua UI será então colocada dentro do retângulo que o Explorer reserva para a UI da cena, que já exclui o minimapa, o chat e os controlos do lado esquerdo.

```ts
ReactEcsRenderer.setUiRenderer(uiComponent, { screenInset: 'interactable' })
```

Nos dispositivos móveis, os botões de ação no canto inferior direito são intencionalmente apresentados sobre essa área, e os toques aí acionam os botões do cliente, não os da sua cena. Mantenha os elementos interativos afastados do canto inferior direito ou, se a sua UI ocupar o ecrã inteiro, oculte os controlos táteis enquanto estiver aberta:

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

// enquanto um painel de ecrã inteiro estiver aberto, o jogador não precisa de saltar nem de premir E
TouchScreenControls.hideAll()
TouchScreenControls.hideJoystick()

// volte a apresentá-los quando o painel fechar
TouchScreenControls.showDefault()
TouchScreenControls.showJoystick()
```

`showDefault()` restaura o conjunto inicial de uma cena: salto, ponteiro e ação principal. Use `showAll()` apenas se a sua cena precisar mesmo de ter os oito botões no ecrã. Ambos requerem o SDK 7.32.0 ou posterior; nas versões mais antigas do SDK, os oito botões são apresentados por predefinição e `showAll()` é a única opção de restauro. Estes auxiliares não fazem nada no computador, por isso pode chamá-los incondicionalmente. Consulte [Controlos no ecrã](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/touch-screen-controls.md).

Tenha sempre uma grelha em mente e use-a como principal critério para organizar espacialmente a sua UI. Se estiver a trabalhar numa cena que precise de um HUD, pode começar por agrupar todos os consumíveis (por exemplo, moeda, comida e vida) e colocar do outro lado os itens armazenáveis, como ferramentas ou armas. Procure manter consistentes as dimensões da grelha e o espaçamento interno. Torne claro o feedback de cada ação do jogador.

### Cor

É importante escolher uma paleta de cores, pois esta confere identidade à sua cena e também indica as relações e a hierarquia entre os elementos.

Ao criar uma paleta de cores, comece por selecionar uma cor principal e, opcionalmente, uma secundária. Depois, decida se pretende que a paleta seja análoga, complementar, triádica, etc., em relação à cor principal.

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-aada709f889385e6e835f3154970ed3a9b5e348b%2Fux-color-wheel2.webp?alt=media" alt="Chromatic color palette" width="300"><figcaption><p>Paleta de cores cromática</p></figcaption></figure>

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-fc0d778612170f72974571286484db43f2f07b10%2Fux-color-wheel.webp?alt=media" alt="Strategies for combining colors properly" width="300"><figcaption><p>Estratégias para combinar cores corretamente</p></figcaption></figure>

{% hint style="info" %}
**💡 Dica**: Geradores gratuitos de paletas de cores que recomendamos: [Coolors](https://coolors.co), [Adobe Color CC](https://color.adobe.com/), [Colour Lovers](http://www.colourlovers.com), [Color Hunt](http://www.colorhunt.co), [Color by Hailpixel](http://color.hailpixel.com), [Colour Code](http://colourco.de), [Sip](https://sipapp.io/), [Color Scheme Designer by Paletton](http://paletton.com), [Cohesive Colors](http://javierbyte.github.io/cohesive-colors), [Colr](http://www.colr.org)
{% endhint %}

A cor principal deve ser a mais utilizada nos componentes da UI. Se a sua paleta não tiver uma cor secundária, pode realçar elementos combinando a cor principal com preto ou branco. Ter uma cor secundária não é obrigatório, mas ajuda a realçar e distinguir os elementos da UI da sua cena. As cores secundárias funcionam melhor em destaques, controlos de seleção (cursores e interruptores), ligações e títulos.

Lembre-se de que cada cor tem qualidades expressivas únicas. Aproveite-as para comunicar mensagens. Por exemplo, o vermelho está frequentemente associado a conotações negativas, enquanto o verde está associado a conotações positivas.

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-f5cbc5f2e6e848665a9d08759c8fdad738af4e6c%2Fux-switches.webp?alt=media" alt="Colored switches" width="300"><figcaption><p>Usar as cores de forma inadequada pode causar confusão</p></figcaption></figure>

Também pode usar as cores estrategicamente para indicar alterações de estado, por exemplo, mudando a cor de um elemento para indicar se está ativo ou inativo.

{% hint style="warning" %}
**📔 Nota**: Os estados comunicam a situação dos elementos da UI. Os estados de um elemento devem manter uma certa continuidade, mas também devem ser claramente identificáveis e facilmente distinguíveis dos outros estados e do layout à sua volta.
{% endhint %}

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-b51fbf7e16991153fb038889053770cd43a14b29%2Fux-active-button.webp?alt=media" alt="Active inactive button" width="300"><figcaption><p>Usar cores nos estados dos botões</p></figcaption></figure>

Aviso! Ao selecionar cores que serão apresentadas sobrepostas, tenha especial cuidado para garantir que são legíveis quando usadas em conjunto. Eis uma regra fundamental: as cores dos elementos apresentados em simultâneo devem ter sempre bastante contraste entre si. Tenha em conta que alguns jogadores poderão estar a olhar para os ecrãs em condições de iluminação pouco ideais, o que dificulta a leitura.

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-127f115cc7629669cfaa6de01582936d79fe90f2%2Fux-icons.webp?alt=media" alt="Icon contrast" width="300"><figcaption><p>É possível distinguir ambos os ícones, mas o primeiro tem melhor contraste. É mais fácil de ler e exige menos esforço para compreender.</p></figcaption></figure>

### Hierarquia tipográfica

Tente definir uma escala de pelo menos 3 tamanhos para títulos, subtítulos e texto corrido. Tenha cuidado ao usar cores e tamanhos de letra. Todos os tamanhos de letra devem ser iguais ou superiores a 12 px.

Se pretender colocar texto sobre imagens (ou sobre o mundo), terá certamente de testar a sua legibilidade. Nesses casos, recomendamos que adicione uma área de cor sólida numa camada entre o texto e as imagens, para garantir que o texto permanece legível.

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-c3cce99063bb171a155c1eda34c7fdd39ada6648%2Fux-text-over-images.webp?alt=media" alt="Text over images" width="300"><figcaption><p>Dê prioridade à legibilidade</p></figcaption></figure>

### Ícones

Os ícones sintetizam informação e ajudam a identificar ações através de imagens. São uma ferramenta extremamente eficaz para fornecer indicações que podem ser interpretadas rapidamente, ao contrário dos rótulos de texto, que exigem mais atenção e tempo por parte do jogador. Também é útil apresentar ícones juntamente com texto, pois isso ajuda a esclarecer o seu significado.

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-941fdc057e8aca15237bafe412b6d79a7dcc5030%2Fux-icons2.webp?alt=media" alt="Icon examples" width="300"><figcaption><p>Use ícones como uma linguagem universal</p></figcaption></figure>

### Movimento

Use o movimento para dar feedback e orientar os jogadores quando necessário. O movimento ajuda os jogadores a concentrar a atenção e a manter a continuidade à medida que a UI muda.

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-6a52459a01f90e0f18a6172c0c9f6edf41fd5b3f%2Fux-glow.webp?alt=media" alt="Adding glow" width="300"><figcaption><p>Use partículas, escala ou margens com desvanecimento para dar destaque aos elementos</p></figcaption></figure>

#### Evite efeitos intermitentes

Luzes intermitentes, efeitos estroboscópicos e alterações rápidas de luminosidade ou cor podem provocar convulsões em pessoas com epilepsia fotossensível. Isto inclui materiais emissivos pulsantes, luzes a piscar, flashes na UI em ecrã inteiro e vídeos.

* Limite os efeitos intermitentes a **3 flashes por segundo ou menos**, de acordo com a [diretriz WCAG «Three Flashes or Below Threshold»](https://www.w3.org/WAI/WCAG22/Understanding/three-flashes-or-below-threshold.html) .
* Mantenha pequenas as áreas intermitentes e evite o vermelho saturado e flashes grandes, de elevado contraste, que ocupem todo o ecrã.
* Se a sua cena depender de efeitos intensos, como luzes estroboscópicas de discoteca, relâmpagos ou flashes de dano, adicione uma opção na cena para os desativar ou reduzir a intensidade.

### Redação e estrutura do conteúdo

O texto da UI pode tornar as interfaces mais fáceis de usar e dar aos jogadores mais confiança nas suas ações. Escreva sempre o texto da UI da forma mais concisa possível. Os jogadores estão aqui para jogar, não para ler. A maioria dos jogadores não lerá textos que pareçam demasiado longos.

Dê as boas-vindas aos jogadores com uma mensagem de boas-vindas e explique-lhes o objetivo da cena. Comece por esclarecer qual é o objetivo dos jogadores na cena e, em seguida, que ações têm de realizar para o alcançar. Depois, pode revelar informação gradualmente, à medida que for necessária, para que os jogadores não se sintam sobrecarregados no início da experiência. Tal como acontece com os recursos gráficos, procure usar termos consistentes nas funcionalidades da UI e na narrativa.

#### Mostre, não explique

Dois padrões fazem com que os jogadores desistam antes da primeira interação:

* **A janela pop-up com as regras**: um painel introdutório com vários parágrafos densos que explicam todas as mecânicas, regras de pontuação e controlos. Os jogadores fecham-no sem o ler.
* **O livro de regras no mundo**: os mesmos parágrafos num letreiro ou quadro na cena. Parece fazer parte do design, mas o texto no mundo é demasiado pequeno e longo para ser lido, e os jogadores não vão ficar parados a esforçar a vista para o ler.

Limite o painel introdutório a um ecrã, sem deslocamento: 3 a 5 linhas curtas, idealmente uma linha para o objetivo, uma para os controlos e uma imagem. Cada letreiro deve transmitir uma única ideia, em 10 palavras ou menos, com letra grande e um letreiro por ideia.

Depois, mostre o resto em vez de escrevê-lo:

* Torne o primeiro objetivo impossível de ignorar. Coloque um objeto brilhante, animado ou enorme no campo de visão inicial do jogador. Um contorno pulsante ensina «clica em mim» melhor do que uma frase.
* Deixe o jogador experimentar uma mecânica uma vez, em segurança, numa área de treino, antes de começar o jogo a sério.
* Use `hoverText` em Entities interativas como instrução no momento certo. Ela aparece exatamente quando é relevante e não exige leitura prévia. Consulte [Feedback ao passar o cursor](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/register-callback.md#hover-feedback).
* Use um diagrama para explicar regras espaciais ou de sequência. Uma imagem de «gemas vermelhas = 1, gemas azuis = 5» substitui um parágrafo.
* Apresente qualquer conteúdo mais longo uma mensagem de cada vez, por meio de um NPC ou de um diálogo que o jogador possa ignorar.

Se uma regra precisar de mais texto do que isso, reformule a mecânica ou mostre-a visualmente.

### Interações com objetos

Certifique-se de que os jogadores conseguem distinguir os objetos interativos dos que não são interativos. Ao registar eventos de botão numa Entity, o SDK apresenta feedback ao passar o cursor por predefinição: um contorno realçado na Entity e uma indicação junto ao cursor que mostra que comando usar, com texto personalizado para descrever os efeitos da interação. Recomendamos vivamente que o utilize; a sua Scene parecerá mais natural e será mais fácil de usar. Consulte [Feedback ao passar o cursor](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/register-callback.md#hover-feedback).

### Câmara na terceira pessoa

Os jogadores podem alternar entre as câmaras na primeira e na terceira pessoa a qualquer momento, premindo a tecla ‘V’. Conceba a sua Scene para que as interações funcionem confortavelmente nos dois modos: por exemplo, é mais difícil clicar em alvos pequenos na terceira pessoa. A sua Scene pode consultar o modo de câmara atual do jogador ou forçar um modo específico numa área; consulte [Câmara](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/camera.md).

A câmara na terceira pessoa também altera o tamanho necessário de uma divisão. Os interiores construídos à escala real parecem apertados no ecrã; consulte [Construa interiores maiores do que na vida real](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/conceber-a-experiencia/design-games.md#build-interiors-larger-than-real-life).


---

# 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/scenes-sdk7/conceber-a-experiencia/ux-ui-guide.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.
