> 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 the UI/UX standards you must follow when designing and developing App in Toss mini apps in one place. From how to set the brand logo, name, and colors to the dark pattern prevention policy, UX writing principles, how to use graphic resources, and resolution design standards, we guide you step by step. Before launching your service, carefully check and apply each item. *** ### Mini App Branding Guide These are the standards prepared so App in Toss services can deliver a brand experience that is clearly distinguished from Toss. They are important standards for keeping users from confusing Toss and App in Toss, so be sure to read and follow the guide. *** **1. Brand logo / name / color** Show the brand logo, brand name, and brand color throughout Toss and App in Toss screens so users can clearly recognize the brand. **Brand logo** The partner company's logo will be shown in the All tab, Benefits tab, push notifications, alerts, navigation, and bridge. Please make sure to create the logo using the image or illustration file attached below.
Please follow the criteria below when creating and applying the logo. * The size should be a square 600×600px with sharp corners. Rounded corners cannot be used. * The logo must have a background behind it, and use a background color that is visible in both light mode and dark mode. * If the logo itself includes a background, like in the case of Anipang, place the image so it fills the entire 600×600px area. * Upload the logo file to the App 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 shown 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`is acceptable, but `Toss`is not recommended. * Enter the brand name in the App 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** The brand color is used for entry points inside Toss, bridges, and buttons (when using the Toss Design System). The brand color settings criteria are as follows. * If you already have a brand color, use it as is. * If you do not have a brand color, choose the color used most often in the logo. * If it's hard to choose, [a color extraction site](https://lokeshdhakar.com/projects/color-thief/)can be used to extract a representative color from the logo image. * If the brand color does not meet the color contrast criteria, it will be automatically corrected 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 that includes `#3182F6`for example, enter it like this. *** **2. Navigation bar** The navigation bar is an area fixed at the top of the screen, and App in Toss provides a dedicated component. Please refer to the guide below and configure the navigation bar according to the type of service being onboarded. * Game guide * Non-game guide *** **3. Tab bar** The tab bar is not a required component. However, if you need a tab bar, you must implement it yourself using the floating tab bar provided by Toss. Even if you use your own UI, please implement the tab bar in the provided format. If it overlaps with the default bottom tab on the Toss main screen, users may become confused about their current location.
Please follow the criteria below when configuring the tab bar. * You can use at least 2 tabs and up to 5 tabs. * You must keep the floating format 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 meant to limit creativity; they are the minimum standards for providing users with a predictable and convenient experience. To that end, Toss has set the minimum user experience standards that must be followed, and the examples below are critical usability errors that go beyond these standards and cannot be released as App in Toss services. *** **1. When a bottom sheet appears as soon as the service is entered** As soon as the user enters the service, instead of the screen they expected, **an intrusive promotional bottom sheet**is shown.\ This also includes bottom sheets that request 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 that moment, it breaks their immersion and makes them more likely to leave the service right away.
*** **2. When a bottom sheet blocking the previous screen appears after pressing the back button** When the user tries to go back to the previous screen and browse other services, but unexpectedly **a bottom sheet prompting notification consent appears**this refers to. Additional interrupts intentionally designed to prevent users from leaving can give the impression that their autonomy is being infringed upon. This experience can reduce trust in the service.
*** **3. When there is no option to exit** This refers to a structure where the user has no other choice but to select the CTA guided by the partner company. Such a design that does not allow refusal can feel forced to the user. As a result, it is highly likely to lead to dislike and distrust of the service.
*** **4. When ads are shown at an unexpected moment** The user selected a menu to receive an item, but unexpectedly **an interstitial ad is shown**. Ads that suddenly appear during the usage flow disrupt immersion and can leave a negative impression of the service and brand.
*** **5. When you cannot predict the next action by looking only at the CTA button** If the CTA simply repeats the value already explained on the screen, so that when the button is pressed **it is impossible to know which screen or action will follow**. CTAs are a device 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 uneasiness makes them hesitate to click, which can ultimately lead to a lower conversion rate. Also, if exaggerated or duplicated auxiliary descriptions are shown on top of the CTA, the role of the button becomes blurred and can confuse users.
*** ### UX writing These guidelines are provided so you can use copy that applies Toss app's voice and tone.\ Please follow the guidelines below. *** **1. Use the haeyo style** All copy inside the product should use the 'haeyo' style.\ To create a consistent user experience, **apply the haeyo style to all copy regardless of situation or context.**
*** **2. Speak actively** Inside the product, as much as possible, **active sentences**should be used. Passive sentences are best used only in specific situations. **Was done → Did it**
**Remove the '\~eot' ending**
**Rephrase with a different verb**
*** **3. Speak positively** Inside the product, reduce negative communication as much as possible and use positive sentences. Example: can't, no (X) → if you do \~, you can (O) **None → There is**
**Error messages**
{% hint style="info" %} **The left button in the dialog is \[Close]** The left button in the dialog is **Close**to keep the label consistent. **Cancel**is not used because users may misunderstand it as canceling the task they are doing. {% endhint %} **When benefits cannot be received**
**Benefit eligibility notice** **When the service can be used, but certain benefits cannot be received → positive sentence**\ Because users are scanning, they may easily understand it as meaning they cannot use the entire product.
*** **4. Casual honorifics** Inside the product, do not use overly formal honorifics such as 'would you like to?', 'are you?', or '\~kke'. It's best to use a casual and friendly tone as much as possible. **Remove the '\~si' ending from verbs**
**'gyesida' → 'itta'**
**'yeojjuda' → 'confirm, ask'**
**'kke' → 'ege'**
**When it sounds awkward after removing honorifics** When asking for information from a user, the sentence can sound awkward if you mechanically remove '\~si'.\ **Try rewriting the sentence by making the information you want to find out the subject.**
*** **5. Do not use '{noun} + {noun}'** **Expand Sino-Korean words** You can expand Sino-Korean nouns and use them in verb form.
**When it's difficult to expand a Sino-Korean word** Even just expanding it into the form '{noun} does {noun}' makes it feel more casual.
*** **Exception rules**
Cases where passive sentences are allowed There are cases where passive sentences create clearer and more concise communication. We'll show you examples where passive voice makes for better sentences. **⚠️ Service termination, expiration** **Passive sentence**when written ``` ``` **Do not use 'ends' for products where termination repeats periodically.** **⚠️ When explaining the impact on users** (Main verbs: overdue, cancellation, application, etc.)**Passive sentence**when written ``` ``` **⚠️ Reassure users** **Passive sentence**when written ``` ``` **⚠️ Use '돼요' instead of '되어요' (X) → (O)** Considering the narrow space of mobile screens, please use only '돼요' instead of '되어요'.
Cases where honorifics can be used In limited situations, you can use interrogative endings like 'are you?' or 'did you?' **⚠️ When asking by using the user's context** You can reduce the user's awkwardness by using honorific forms such as 'are you?' or 'did you?' **⚠️ When inferring the user's situation** If Toss does not have clear information and the user needs to make a direct judgment, you can politely ask using honorifics. **⚠️ When the user's goodwill is needed** When you need to expect the user's goodwill, such as in a survey, ask politely with honorifics.
Cases where negative sentences can be used When you need to clearly inform users of something negative, it is okay to use negative sentences. **⚠️ When the service cannot be used due to policy** **Negative sentence**must be used ``` ``` **⚠️ When only some features cannot be used** **Negative sentence**must be used ``` ``` * You can clearly explain the result of the user's choice. **⚠️ Reassure users** **Negative sentence**must be used ``` ```
*** ### Graphics We 안내 you on the graphic resources provided by Toss and how to use them properly. {% hint style="info" %} **Graphic copyright notice** All graphic assets of Toss and graphics generated through Toast are intellectual property of Viva Republica Co., Ltd., protected under the Copyright Act and related laws. The provided graphics may be used only for service operation and promotion within the App in Toss partnership environment, and use in other services or media through reproduction, modification, distribution, transmission, public transmission, etc. is prohibited. {% endhint %} *** **Graphic resources provided by Toss** **1. Icons & emojis** Toss provides more than about 7,000 icons and emoji sets. When designing in App Builder and Figma, you can check the icon and emoji list. In App Builder, from 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, [refer to the App in Toss icon creation guide](https://www.notion.so/21b714bbfde780fb84bac2acfbb4a6b9?pvs=21)and create them according to the standards. **\[Notes for use]** * Please use icons at a size of 24\~40px on screen. * Avoid combining two or more icons or emojis in parallel. Please use only one at a time. * The graphic resources provided by Toss can only be used for UI design within the service screen and cannot be used in app information such as the app logo or thumbnail.
**2. Smartphone mockup files** When creating resources with smartphone mockups, please use the files provided above as they are. Icons are provided in different sizes, so please do not crop them arbitrarily, correct their colors, or distort their shape.
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. Before using the generated graphics on the actual screen, you must obtain approval from the Toss graphic design team. Approval usually takes place within one day. **4. Others** For 3D graphics or animations, only the resources included in the modules provided by Toss can be used.\ The scope of availability will be gradually expanded in the future. *** **How to use graphics properly** **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 a size that matches the information density.** Use simple graphics small, and graphics with a lot of detail large enough.
**3. Do not use too many graphics on one screen.** The more graphics of similar size there are, the more attention gets scattered.\ Use only one most essential graphic, and replace the rest with auxiliary graphics or icons.
**4. Please 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 are considered dark patterns.\ Please do not use these emotional expressions.
**6. Do not use decorative effects or effects.** Meaningless illustrations, particles, and excessive gradients can make the screen complicated and interfere with information delivery.
**7. Please use graphics that accurately convey the situation.** Using an exclamation mark icon when it is not an error,\ or using a loading animation when there is no need to wait, can make users misunderstand the situation.
*** **Notes when partners create graphics directly** **1. Please maintain Toss-style consistency.** Toss aims for a simple, clear, and clean digital graphic style.\ Hand-drawn feelings, lyrical painting styles, and cartoon-like expressions may look out of place on screen. **Examples of Toss's graphic style**
**2. Please use high-resolution graphics.** Please create graphics in a clear and clean high resolution. If the resolution is low or there are many small effects like particles, the quality may look low.
**3. It must be visible well in both dark mode and light mode.** Graphics used in the Toss app must take both dark mode and light mode into account.\ Colors that are too bright or too dark may not be visible well in a specific mode, so please use colors with a medium brightness.
**4. Please compose it so it fits the whole screen.** Make sure the overall color and layout of the screen are balanced so the graphics do not stand out more than elements such as text or CTA buttons.
**5. Give a positive and orderly impression.** Graphics play an important role in creating a sense of stability and trust in the service.\ Avoid overly monotone, hazy, and dull impressions, and design them to feel bright and tidy.
*** ### Resolution This guide explains which resolution should be the 기준 when developing App in Toss mini apps, and how to design and optimize screens. Along with recommended standards, it explains design directions that work stably across various device environments. App in Toss mini apps run on devices with various resolutions and screen ratios. To reduce confusion caused by these environment differences, this guide proposes a 'base resolution-centered design' approach rather than device-specific 대응. {% 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 App in Toss's actual traffic. {% endhint %} *** **App in Toss mini app full-screen design standards** Full-screen implementation is required for App in Toss game mini apps. In a full-screen environment, the following must be considered. * The content must completely fill the screen. * There should be no webview margins or translucent areas left. * The aspect ratio must not break or letterboxing (black margins) must not appear when the device rotates. * 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 set one base resolution and respond through scaling. *** **Two ways to look at resolution** In App in Toss mini apps, we recommend thinking of resolution in the two ways below. **① Logical Resolution** This is the resolution used as the basis for UI placement, coordinate calculations, and game logic. * It is a concept different from the actual device pixel resolution. * We recommend selecting only one logical resolution. * The same play feel and screen composition must be maintained across all devices. **② Asset Resolution** This refers to the pixel density of images, backgrounds, characters, and UI resources. * There is no need to prepare assets separately for each device. * It is efficient to group and manage them in a small number of resolution groups. *** **App in Toss recommended resolution standards** **① Recommended logical resolution range** Please choose one of the ranges below as your base resolution. * **Portrait mini app:** about 360 × 640 \~ 420 × 740 * **Landscape mini app:** about 640 × 360 \~ 740 × 420 We recommend choosing one base resolution within this range and handling differences between devices through scaling. **② Recommended asset resolution standards** It is best to prepare assets by group. * **1x assets**: base resolution support * **2x assets**: high-resolution device support Only add 3x assets selectively when graphic quality is especially important. {% hint style="info" %} **Please be sure to check** For most mini apps, a 1x + 2x setup is enough. Splitting asset resolutions too much can lead to increased memory usage, loading delays, and maintenance costs. {% endhint %} *** **Data-based notes** This guide was organized based on **device resolution data collected from App in Toss's actual service environment**. * About **70\~80%** of total mini app traffic is concentrated in the horizontal range of roughly **800\~900**, and vertical roughly **360\~420** viewport resolutions in the range. * The rest of the traffic is a long tail distributed across various resolutions. So rather than handling every resolution individually, designing based on representative resolution ranges is the most efficient approach. *** **Test device guide** You do not need to test on every device. A **set of 3 to 5 representative devices**that meet the conditions below is enough. * 2 to 3 devices with different screen ratios * 1 device where Safe Area is applied heavily * 1 device with a relatively small screen size *** **Not recommended approaches** Please avoid the following approaches. * Using different logical resolutions for each device model * Calculating UI or coordinates based on actual pixel resolution * Running too many asset resolution groups beyond what is necessary * Maintaining different UI layouts for each resolution Such approaches can lead to UI breakage, letterboxing, and higher 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.