> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/landing-page/landing-page-en/design/consumer-ux-guide.md). # UI/UX Guide This document is a guide that gathers in one place the UI/UX standards you should follow when designing and developing Apps in Toss mini apps. From how to set the brand logo, name, and color to the dark pattern prevention policy, UX writing principles, graphic resource usage, and resolution design standards, we guide you step by step. Please carefully check and apply each item before launching your service. If the standards are not followed or a dark pattern is found, the review will not be approved, and even if it is found after launch, service exposure may be restricted or suspended. *** ### Mini app branding guide These are the standards prepared so that Apps in Toss services can deliver a brand experience that is clearly distinguished from Toss. Since they are important standards for keeping users from confusing Toss with Apps in Toss, please be sure to read and follow the guide. *** **1. Brand logo / name / color** We display the brand logo, brand name, and brand color throughout Toss and Apps in Toss screens so users can clearly recognize the brand. **Brand logo** The partner company's logo is shown in the All tab, Benefits tab, push notifications, alerts, navigation, and bridge. Please be sure to use the image or illustration file attached below to create the logo.
Please follow the standards below when creating and applying the logo. * The size should be a square with sharp corners at 600×600 px. Rounded corners are not allowed. * The logo must always have a background, and use a background color that is visible in both light mode and dark mode. * If the logo itself already includes a background, like Anipang, make the image fill the entire 600×600 px area. * Upload the logo file to the Apps in Toss console, and `granite.config.ts` at the top of the file `appsInToss` in the function `brand.icon` enter the same logo link in the property. **Brand name** The brand name is displayed in the All tab, Benefits tab, push notifications, alerts, navigation, and bridge. Unless there is a special reason, please write it in Korean. For example, `Toss`can be `Toss`is not recommended. * Enter the brand name in the Apps in Toss console. * `granite.config.ts` at the top of the file `appsInToss` in the function `brand.displayName` Enter the same brand name in the property. **Brand color** Brand color is used for entry points in Toss, bridges, and buttons (when using the Toss design system), among other places. The criteria for setting the brand color are as follows. * If you already have a brand color, use it as is. * If you don't have a brand color, choose the color most used in the logo. * If it's hard to choose, [color extraction site](https://lokeshdhakar.com/projects/color-thief/)you can also use it to extract a representative color from the logo image. * If the brand color does not meet the color contrast criteria, it will be automatically adjusted while preserving the existing color as much as possible. * `granite.config.ts` at the top of the file `appsInToss` in the function `brand.primaryColor` Enter a six-digit hex code value including `#`# `#3182F6`like this. *** **2. Navigation bar** The navigation bar is a fixed area at the top of the screen, and Apps in Toss provides a dedicated component for it. Depending on the type of service being onboarded, please refer to the guide below to set up the navigation bar. * Game guide * Non-game guide *** **3. Tab bar** The tab bar is not a required component. However, if you need one, you must implement it yourself using the floating tab bar provided by Toss. Even if you use your own UI, please implement only the tab bar in the provided form. This is because if it overlaps with the default bottom tab on the Toss main screen, users may get confused about their current location.
Please follow the standards below when setting up the tab bar. * You can use a minimum of 2 tabs and a maximum of 5. * You must keep the floating form provided by Toss. *** ### Dark pattern prevention policy Toss users expect a consistent and trustworthy user experience anywhere. If standards differ from service to service, users may feel confused, and this can lead to a decline in trust in the service overall.\ UX guidelines are not rules to limit creativity, but minimum standards for providing users with a predictable and convenient experience. For this reason, Toss has established minimum user experience standards that must be followed, and the examples below are fatal usability issues that fall outside these standards and cannot be launched as Apps in Toss services. *** **1. When a bottom sheet appears as soon as you enter the service** Instead of the screen the user expected right after entering the service, **an ad-like bottom sheet that blocks the entire screen**is shown.\ This includes bottom sheets requesting notification consent. When users enter a service, they expect to be able to immediately carry out the purpose they intended.\ If an unexpected interrupt appears at this point, immersion is broken, and they are more likely to leave the service immediately.
*** **2. When a bottom sheet that blocks the previous screen appears after pressing the back button** When a user is trying to go back to the previous screen and explore another service, but unexpectedly **a bottom sheet prompting notification consent appears**refers to this. An additional interrupt intentionally designed to prevent users from leaving can give the impression that their autonomy is being violated. This experience can undermine trust in the service.
*** **3. When there is no exit option** This refers to a structure in which the user has no other choice but to select the CTA guided by the partner. Such a design, where there is no way to decline, can feel coercive to users. As a result, it is likely to lead to resentment and distrust of the service.
*** **4. When ads are shown at unexpected moments** The user selected a menu to receive an item, but contrary to expectation, **a full-screen ad appears**. Ads that suddenly appear during the usage flow disrupt immersion and can leave an unpleasant impression of the service and brand.
*** **5. When users cannot predict the next action by looking only at the CTA button** When the value already explained on the screen is repeated exactly in the CTA, so users cannot tell what screen or action the button will lead to. CTA is a tool that clearly tells users what they will do next. If the button label is vague or only repeats the explanation, users cannot predict the result of the click and feel uneasy. This unease can make them hesitate to click and can ultimately lead to lower conversion rates. Also, if exaggerated or redundant supporting text is displayed together above the CTA, the role of the button becomes blurred and can confuse users.
*** ### UX writing This guideline is a set of instructions provided so that you can use wording that applies Toss app's voice and tone.\ Please follow the guidelines below. *** **1. haeyo-che (polite informal style)** All text inside the product should be written in haeyo-che (polite informal style).\ **To create a consistent user experience, apply haeyo-che (polite informal style) to all text regardless of situation or context.**
*** **2. Active wording** Inside the product, use active **active sentences**whenever possible. Passive sentences should be used only in specific situations. **`Done` → `Did it`**
**Remove '\~었'**
**Reword the verb**
*** **3. Positive wording** Reduce negative communication inside the product as much as possible and use positive sentences. Example: You can't, there isn't any (X) → If you \~, you can (O) **There isn't any → There is**
**Error message**
{% hint style="info" %} **The left button in the dialog is \[Close]** The left button in the dialog is **Close**to standardize the wording. **Cancel**is not used because users may misunderstand it as canceling the task they are working on. {% endhint %} **When benefits cannot be received**
**Benefits eligibility notice** **When the service can be used, but certain benefits cannot be received → positive sentence**\ Users may easily think they cannot use the entire product because of scanning.
*** **4. Casual honorifics** Inside the product, '`Would you like to ~?`', '`Are you ~?`', '`to (honorific)`' and other overly polite forms like these are not used. It's better to use a casual, friendly tone as much as possible. **Remove '\~시' from verbs**
**'`be there`' → '`be`'**
**'`ask respectfully`' → '`check`, `ask`'**
**'`to (honorific)`' → '`to`'**
**When it sounds awkward without honorifics** In questions asking for user information, if you mechanically remove '`~시`', the sentence may sound awkward.\ **Try rewriting the sentence by making the information you want to find out the 'subject'.**
*** **5. '`{noun} + {noun}`Don't use** **Write out Sino-Korean compounds** You can break down Sino-Korean nouns and use them in verb form.
**When it is difficult to write out Sino-Korean words** '`{noun} is {noun} so`Even just breaking it down into a '{noun} is {noun}' form can make it sound more casual.
*** **Exception rules**
Cases where passive sentences are allowed There are times when passive sentences create clearer and more concise communication. We'll show you cases where passive sentences can produce better wording. **⚠️ Service termination, period expiration** **Passive sentence**when written as {% code collapsedlinecount="10" %} ``` ``` {% endcode %} **For products where termination repeats periodically, do not use '`ends`'.** **⚠️ When explaining the impact on users** (main verbs: overdue, cancellation, application, etc.)**Passive sentence**when written as {% code collapsedlinecount="10" %} ``` ``` {% endcode %} **⚠️ Reassuring users** **Passive sentence**when written as {% code collapsedlinecount="10" %} ``` ``` {% endcode %} **⚠️ `becomes` (X) → `becomes` (O)** Considering the limited space on mobile screens, please use all forms of '`becomes`' as '`becomes`'.
Cases where honorifics are allowed In specific situations, you can use the interrogative ending '`Are you ~?`, `Did you?`'. **⚠️ When asking a question using the user's context** '`Are you ~?`', '`Did you?`You can reduce the user's embarrassment by using the honorific form ' **⚠️ When inferring the user's situation** When Toss does not have clear information and you need the user to judge directly, you can politely ask with honorifics. **⚠️ When the user's goodwill is needed** When you need to rely on the user's goodwill, such as in a survey, ask politely in honorifics.
Cases where negative sentences are allowed When you need to clearly tell the user something negative, it is okay to use negative sentences. **⚠️ When the service cannot be used due to policy** **Negative sentence**must be written {% code collapsedlinecount="10" %} ``` ``` {% endcode %} **⚠️ When only some features cannot be used** **Negative sentence**must be written {% code collapsedlinecount="10" %} ``` ``` {% endcode %} * You can clearly explain the result of the user's choice. **⚠️ Reassuring users** **Negative sentence**must be written {% code collapsedlinecount="10" %} ``` ``` {% endcode %}
*** ### Graphics We provide guidance on the graphic resources provided by Toss and how to use them correctly. {% hint style="info" %} **Graphic copyright notice** All Toss graphic assets and graphics created with Toast are Viva Republica's intellectual property and are protected under the Copyright Act and related laws. The provided graphics may only be used for service operation and promotion within the Apps in Toss partnership environment, and using them in other services or media through copying, modifying, distributing, transmitting, or public transmission is prohibited. {% endhint %} *** **Graphic resources provided by Toss** **1. Icons & emojis** Toss provides more than 7,000 icons and emoji sets. When designing in App Builder and Figma, you can check the icon and emoji list. In App Builder, after registering the app in the workspace, [after registering the app](https://appsintoss.gitbook.io/appsintoss-docs/guide/operation/console-workspace) you can start from the 'Design' menu. If you need to create icons yourself, [Apps in Toss icon creation guide](https://www.notion.so/21b714bbfde780fb84bac2acfbb4a6b9?pvs=21)please refer to it and create them according to the standards. **\[Notes for use]** * Please use icons at a size of 24–40 px on screen. * Avoid combining two or more icons or emojis in parallel. Please use only one at a time. * Graphic resources provided by Toss may only be used for UI design purposes within service screens and cannot be used in app information such as app logos or thumbnails.
**2. Smartphone mockup files** When creating resources using smartphone mockups, please use the files provided above as is. Icons are provided in different sizes, so please do not crop them arbitrarily, adjust colors, or distort the shapes.
To reflect design updates, we recommend using the URL below even during development. * **Full** * * **Large** * Top: * Bottom: * **Medium** * Top: * Bottom: * **Small** * Top: * Bottom:
**3. Toast (AI image generation tool)** Based on the icons and emojis provided in item 1, you can generate 3D images. The generated graphics must receive approval for use from the Toss Graphic Design Team before being used on actual screens. Approval is usually completed within one day. **4. Other** For 3D graphics or animations, you can only use the resources included in the module provided by Toss.\ The scope of what is provided will gradually expand in the future. *** **Proper use of graphics** **1. Please use graphics that fit the context.** Graphics are not decoration; they help users understand the meaning of the screen more easily.
**2. Please use them at a size appropriate for the information density.** Use simple graphics small, and graphics with lots of detail large enough.
**3. Do not use too many graphics on one screen.** As the number of graphics of similar size increases, attention gets scattered.\ Use only the single most essential graphic, and replace the rest with supporting graphics or icons.
**4. Place them so they do not cover key information.** Adjust the size and position so important content is not pushed down and unnecessary scrolling does not occur.
**5. Avoid negative or pleading emotional expressions.** Expressions that make users uncomfortable or feel like begging or pleading count as dark patterns.\ Please do not use such emotional expressions.
**6. Do not use decorative effects or visual effects.** Meaningless illustrations, particles, or excessive gradients make the screen complex and hinder information delivery.
**7. Use graphics that accurately convey the situation.** Using an exclamation-mark icon in a situation that is not an error, or using a loading animation when there is no need to wait, can cause users to misunderstand the situation.
*** **Notes when partner companies create graphics themselves** **1. Please maintain consistency with the Toss style.** Toss aims for a simple, clear, and clean digital graphic style.\ Lyrical art styles, cartoon-like expressions, and hand-drawn feel can look out of place on screen. **Examples of Toss's graphic style**
**2. Please use high-resolution graphics.** Please create graphics in sharp, clean high resolution. If the resolution is low or there are many tiny particle-like effects, the quality may look low.
**3. They must be clearly visible in both dark mode and light mode.** Graphics used in the Toss app should take both dark mode and light mode into account.\ Colors that are too bright or too dark may not be visible well in certain modes, so please use mid-tone colors.
**4. Make them fit the whole screen.** Balance the screen's overall color and layout so the graphics do not stand out more than other elements like text or CTA buttons.
**5. Give a positive and tidy impression.** Graphics play an important role in creating a sense of stability and trust in the service.\ Avoid overly monochrome, blurry, or dull impressions, and design them to feel bright and orderly.
*** ### Resolution This guide explains which resolution to use as the standard when developing Apps in Toss mini apps and how to design and optimize screens. Along with the recommended standards, it explains design directions that work stably across a variety of device environments. Apps in Toss mini apps run on devices with various resolutions and aspect ratios. To reduce confusion caused by these environmental differences, this guide proposes a 'base-resolution-centered design' approach rather than a device-by-device approach. {% hint style="info" %} **Please be sure to check** If you design based on one logical resolution and prepare assets at 1x and 2x, you can stably cover most of the actual traffic of Apps in Toss. {% endhint %} *** **Apps in Toss mini app fullscreen design standards** Game mini apps in Apps in Toss must be implemented fullscreen. In fullscreen environments, you must consider the following. * The content must fill the screen completely. * There must be no webview margins or translucent areas left. * The aspect ratio must not break, and letterboxing (black margins) must not appear due to device rotation. * Notches, camera holes, and Dynamic Island must be handled as Safe Area. * Asset quality must not noticeably degrade due to scaling. So rather than adjusting the resolution differently for each device, it is important to choose one base resolution and handle differences through scaling. *** **Two ways to think about resolution** In Apps in Toss mini apps, we recommend thinking about resolution in the two ways below. **① Logical Resolution** The resolution used as the basis for UI layout, coordinate calculations, and game logic. * This is a different concept from the actual device pixel resolution. * We recommend choosing only one logical resolution. * The same play feel and screen composition must be maintained across all devices. **② Asset Resolution** It refers to the pixel density of images, backgrounds, characters, and UI resources. * There is no need to prepare assets separately for each device. * Managing them in a small number of resolution groups is efficient. *** **Recommended resolution standards for Apps in Toss** **① Recommended logical resolution range** Please choose one of the ranges below as your base resolution. * **Vertical mini app:** About 360 × 640 to 420 × 740 * **Horizontal mini app:** About 640 × 360 to 740 × 420 We recommend choosing one base resolution within this range and handling differences between devices through scaling. **② Recommended asset resolution standards** It's best to prepare assets by group. * **1x assets**: support for the base resolution * **2x assets**: support for high-resolution devices Add 3x assets selectively only when graphic quality is especially important. {% hint style="info" %} **Please be sure to check** For most mini apps, a 1x + 2x setup is sufficient. Excessively splitting asset resolutions can lead to increased memory usage, longer loading times, and higher maintenance costs. {% endhint %} *** **Data-based reference** This guide is organized based on **device resolution data collected in the actual Apps in Toss service environment**. * About **70\~80%** of the total mini app traffic is concentrated in roughly **800\~900**horizontal, roughly **360\~420** vertical viewport resolution ranges. * The rest of the traffic is a long tail spread across various resolutions. So rather than handling every resolution individually, designing around representative resolution ranges is the most efficient approach. *** **Test device guide** that satisfy the following conditions, **3 to 5 representative devices**are enough. * 2 to 3 devices with different screen ratios * 1 device where Safe Area is heavily applied * 1 device with a relatively small screen size *** **Not recommended methods** Please avoid the following methods. * Using different logical resolutions by device model * Calculating UI or coordinates based on actual pixel resolution * Operating too many asset resolution groups beyond what is necessary * Maintaining different UI layouts for each resolution This approach can lead to UI breakage, letterboxing, and increased maintenance costs. --- # 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://developers-apps-in-toss.toss.im/landing-page/landing-page-en/design/consumer-ux-guide.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.