Log-in required.

You are trying to access the internal Editor Foundations design system.
Sign-in with your Unity Google account to continue, or visit the public site.

Implementation references

Scripting API and implementation references.

UI Toolkit
IMGUI

Help box · UX essentials

Essential guidance about effective ways of messaging.

Errors and warnings are relevant, well-written, and actionable
US-0202
Blue plus sign icon indicating that clicking on this will expand this content

Overview

Shader channels displaying a warning helpbox in dark and light themes
  • Help boxes are used to alert the user of an event in a specific section of an Editor window, such as a property setting
  • They appear below the affected area (for example a property in the Inspector window)
  • Help boxes shift the content below it

Help box APIs

Help box in UI Toolkit

UI Toolkit
HelpBox
Makes a help box with a message to the user
IMGUI
API in IMGUI
EditorGUI.HelpBox
Makes a help box with a message to the user

Guidance

When to use

 Illustration showing four Editor message types that include dialog modals, window banners, help boxes and console Logs
1. Dialog modals 2. Window banners 3. Help boxes 4. Console logs

Consider the following criteria to decide when to use help boxes or other feedback options:

  • If the message is about a property or a control in the window, use a help box
  • If the message is operational to the Editor, it should be logged as a console log
  • If the message prevents the user from continuing until a choice or an action is made, use dialogs
  • If the message is a confirmation or an acknowledgment that requires minimal user interaction, use a window banner

Message types

Error messages
A critical error message displayed in a help box
  1. Indicates a function will not complete an action
  2. Use errors for situations where the Editor can not recover or proceed gracefully
  3. Error messages in the console are themed red
Warning messages
A warning message displayed in a help box
  1. Indicates a function that will complete an action but may return results that are not what the user intended
  2. Use warnings for situations where the Editor can recover/proceed, but users may be unaware of the side effects
  3. Warning messages in the console are themed yellow
Informational (log) messages
An informative message displayed in a help box
  1. Used for communicating non-critical information
  2. Can provide helpful advice that is not essential to the operation
  3. Shares similarities to tooltips
  4. Sometimes referred to as a log message

Content best practices

Well written alert messages should be:

Human-readable

Messages should use the plainest possible language that can clearly convey the message. Avoid obscure codes, abbreviations, or technical jargon. Ideally, a beginner-level user of the feature should be able to understand the alert message.

Concise

Only include the information the user needs to understand and resolve the immediate problem.

Polite

Alert messages should not be written in a negative voice that blames users for incorrect usage but in a positive or neutral voice. Avoid phrases like "illegal command".

Do recommendation illustrated by a green checkbox icon

Do include any phrasing that specifically relates to that error so users can look up that exact problem on a search engine using precise wording

Don't recommendation illustrated by a red X icon

Do not use vague wording such as "syntax error"

Don't recommendation illustrated by a red X icon

Do not begin the error or warning message with “Error” or “Warning” as the color styling and associated icon makes this wording redundant

Formatting

Anatomy and positioning

Anatomy
Anatomy and padding of a help box

A help box contains the following elements:

1. Message icon
2. Message text

Positioning
Shader channels help box is displayed below the shader control

Help boxes appear below the affected area (for example a property in the Inspector window) and shift the content below it.

Interaction states

Default

Default state of a help box.

Focus

Use canGrabFocus method if the help box can be focused.

Color

1. Help box background 2. Help box border 3. Icon colors 4. Help box text
Help box colors
Helpbox Background
--unity-colors-helpbox-background
The background color for a helpbox control
rgba(235, 235, 235, 0.2039216)
rgba(96, 96, 96, 0.2039216)
Helpbox Border
--unity-colors-helpbox-border
The border color for a helpbox control
#A9A9A9
#232323
Helpbox Text
--unity-colors-helpbox-text
The text color for a helpbox control
#161616
#BDBDBD
Feedback icon colors
Icon of a red triangle to indicate a message of warning.
Intended for icons only
The icon color palette below is intended to be used for icon colors only. Do not use it in brand / product design implementations.
White
Primarily for icons that need to change color on a selected state.
#F0F0F0
#F0F0F0
Yellow
Primarily for suggesting warning states and messages.
#C99700
#FFC107
Scarlet
Primarily for suggesting error states and messages.
#B10C0C
#FF534A
Status message text colors
Default Text
The default text color
#090909
#D2D2D2
Error Text
The text color for error messages
#5A0000
#D32222
Warning Text
The text color for warning messages
#333308
#F4BC02

Code samples

Code references