Overview

Following the 2019.1 release of the Editor and the introduction of UIElements, our design material has begun to shift towards a more modern, sleek, and usable appearance that reflects the Unity of today. As a result, it will be necessary to update existing developer packages to align with the new theme.

Many of these design changes address accessibility and usability issues without affecting workflows, updating the design of elements and interfaces to increase readability and navigation. UX initiatives have worked to establish a new material which ensures consistency in usage and construction, facilitates alignment across the Editor, and provides developers with the tools necessary to develop efficiently and effectively.

To minimize the impact of updating the custom styles in the UI owned by your team, this transition guide provides a summary of the changes, as well as information on how to resolve problems you may encounter and how to use the USS files to extend or override supported CSS style properties.

The introduction of UIElements has allowed us to provide developers with a toolkit to create custom interfaces which look and feel consistent with the Editor. This tool provides a library of existing elements as well as examples of how to generate them in code.




What this means for you

For those building new UI Panels or Editor Windows

When building new UI Panels or Editor windows, it is important to align with the new Editor theming. Depending on the nature of the UI, two courses of action exist:

New UI Panels and Editor Windows compatible with 2019.1 or later should be built with UIElements technology whenever possible for standard controls: Default styles can refresh to new themes allowing for the automatic updating of elements built using IMGUI and UIElements technologies, allowing designers and developers to simply refresh with each new version.
It’s important to note that hard-coded elements will not inherit these changes and will require the developer to manually update to the new theme: custom USS files will be required to be provided in two versions, one adapted to the 2019.1 theme and another for earlier versions.
UI Panels and Editor Windows aimed to be compatible with version 2018 or older will require the use of IMGUI to create UI and should refrain from using non-standard GUIStyles, offsets, widths, and heights.




For those with existing UI Panels or Editor Windows

Panels or Windows built with IMGUI may or may not require manual updating depending on the level of customization of default styles being used. It is advisable to begin diagnosing the amount of manual updating required by downloading and installing the latest build available in the forums (APPROPRIATE LINK HERE) to see if and how UI has been effected.

Remember to test on Windows, Mac, and Linux platforms using appropriate fonts and both the light and dark themes (located in the General section of the Preferences window).

Note : As stated above, custom hard-coded elements will not automatically inherit these changes and will require a manual update to the new theme. We recommend remaking any existing UI using UIElements to ensure consistency and ease of maintenance with future updates as IMGUI gets deprecated.




Summary of Changes

  • The Editor now support multiple fonts (bold are defaults):
  • Inter Verdana on Windows
  • Inter and Lucida Grande on Mac
  • Inter uses the same font size as before, but the font itself is slightly wider.
  • EditorGUIUtility.singleLineHeight was changed from 16 to 18 pixels.
  • Toolbar Height was changed from 17 to 20 pixels.
  • Main toolbar buttons are all the same height.
  • Gradients are no longer used in UI controls.
  • Hover state was added to most UI controls.
  • New icons for High DPI displays were introduced.
  • UI controls no longer use an image file as background but a background color and drawn borders.
  • Standard colors are now defined using style sheet variables.
  • New styles were implemented by supporting Cascading Style Sheet (CSS) properties in Unity Style Sheet (USS) files. The list of supported CSS properties is provided in the Refreshed styles section, later in this document.



Refreshed styles

The easiest method to update your UI is to use one of the refreshed core styles below instead of a custom style, which can help you achieve consistency with the rest of the UI and will future-proof your UI for upcoming style changes.

If you cannot update to one of the refreshed styles below and need to update a custom style you can find instructions on how to do so in the Common Issues and Solutions section below.

The following styles were refreshed

  • AnimationSelectionTextField
  • AppToolbar
  • AppToolbar-Button
  • AppToolbar-Button-Large
  • box
  • CN-Box
  • CN-CountBadge
  • CN-EntryErrorIconSmall
  • CN-EntryErrorSmall
  • CN-EntryInfoIconSmall
  • CN-EntryInfoSmall
  • CN-EntryWarnIconSmall
  • CN-EntryWarnSmall
  • ColorField
  • dockarea
  • dockareaOverlay
  • dragtab-label
  • EditModeToolbar
  • grey_border
  • horizontalscrollbarthumb
  • horizontalscrollbarthumb
  • horizontalslider
  • horizontalslider:disabled
  • horizontalsliderthumb
  • horizontalsliderthumb:disabled
  • hostview
  • IN-BigTitle
  • IN-Title
  • IN-TitleText
  • LargeButtonRight
  • MiniLabel
  • ObjectField
  • PreBackground
  • PreOverlayLabel
  • PreToolbar
  • PreToolbar2
  • ProjectBrowserIconAreaBg
  • ProjectBrowserTopBarBg
  • scrollview
  • SearchCancelButtonEmpty
  • ShurikenObjectField
  • StaticDropdown
  • TabWindowBackground
  • TE-Toolbar
  • TE-toolbarbutton
  • TE-ToolbarDropDown
  • textfield
  • Toolbar
  • ToolbarSeachCancelButtonEmpty
  • Window






Common issues and solutions

Vertical misalignment

Since EditorGUIUtility.singleLineHeight has changed, some elements may no longer be aligned vertically. This could be the case if hard-coded offsets were used to position elements.

You should use the EditorGUIUtility.singleLineHeight constant when calculating the position of elements. For example, to middle align an element of height h, you can use the following calculation:


element.y = element.y + (EditorGUIUtility.singleLineHeight - h) * 0.5f;



Button text does not fit

Since the Inter font has a different width your button text may no longer fit. You can use GUIStyle.calcSize () or GUIStyle to compute the proper size of the content based on the font, and then fix this issue as follows:

  • Reduce the size of the text displayed on your button, but do not go below 9pt (as per W3C regulations).
  • Increase the button width.
  • If neither of the above solutions work you may use an abbreviation as required, but you must provide the full name of the button in its tooltip.



Styles have not changed

If your styles have not changed, you can fix this issue as follows:

  • Make sure your style does not use a background image or a custom text color.
  • Use one of the standard styles listed on the EditorStyles page in the Static Properties table.
  • Use one of the refreshed styles listed in the Refreshed styles section above.



My custom window is too small

If your custom window is too small you can follow these steps:

  1. Use the GUIStyle.CalcHeight function to retrieve the height of each vertical element.
  2. Calculate the required height based on the summation of each retrieved height.
  3. Set the window height to the newly calculated height that fits all vertical elements.