This document outlines Zendesk’s design recommendations for sidebar apps to help developers create a consistent experience with the rest of Zendesk’s products. This document is written whether or not you are using Garden, Zendesk’s design system, as many of these principles apply even if you are using your own design system or UI components.

Introducing Zendesk Garden

Zendesk Garden is an open-source design system where Zendesk grows accessible user interface components for all its products.

While it is not required to build an app interface, using Garden will not only help you create a consistent experience, but it will let you take advantage of the large collection of pre-built components, speeding up development to allow you to get your app to customers or in production faster.

Garden also provides the following benefits:

  • A strong focus on accessibility meeting WCAG guidelines
  • Pre-built components allow you to create an interface quick and easily
  • Take advantage of continuous improvements made and published by the dedicated Garden development team

Design with Garden

To make it as easy as possible to design with Garden, a Figma library is available with all of the components and their variations pre-built that you can use in your designs.

Install Garden in your app

A complete list of assets you can import into your app is available from the jsDelivr CDN. See jsDelivr. The jsDelivr files are npm packages that can also be installed from npm. See zendeskgarden - npm search.

See Garden in action

To see what the Garden system looks like in action, install the demo app. This app provides an example of the various components that you can interact with.

User interface design fundamentals

Accessibility

Accessibility is a fundamental aspect of design at Zendesk. Not only is it important when considering those with temporary or permanent impairment, it is also shown to improve the usability of products for everyone. Zendesk abides by WCAG 2.1 guidelines and we encourage app developers to follow these guidelines too.

Learn more about Zendesk’s commitment to accessibility.

Spacing and sizing

When you design an app for the apps sidebar, there are several things to take into consideration due to the amount of space available. In general, try to keep your app as compact and as simple as possible.

Garden components use the base-4 system, meaning things like text sizes and spacings are in multiples of 4px. We encourage that apps are designed using this system to maintain consistency.

The only exception to using base-4 system is the left-padding and right-padding for the app container which should be 15px. Otherwise some elements could be cut off due to the iframe.

In the following example, the focus state of the text field is slightly cut off due to the left and right padding being too small. Increasing the padding will resolve this issue.

Typography

The Zendesk interface uses the font-family SF font/system font at 14px with a 20px line-height by default, with any bolding using semi-bold.

The SF font is available for free from Apple. Download the SF font family.

Below is a quick summary of typography styles you may need when designing your app:

Component Font Size Line height Garden token Hex value
Default SF Pro - Regular 14px 20px grey-800 #2F3941
Labels SF Pro - Semi-Bold 14px 20px grey-800 #2F3941
Hint & Empty state SF Pro - Regular 14px 20px grey-600 #68737D
Placeholder SF Pro - Regular 14px 20px grey-400 #C2C8CC
Text link SF Pro - Regular 14px 20px blue-600 #1F73B7

Colors

The Zendesk interface places strong focus on colour considerations, ensuring things like contrast ratios meet accessibility guidelines.

Below is a list of colors used with our common elements.

Buttons

State Garden token Hex value
Default blue-600 #1F73B7
Hover, active and focus blue-700 #144A75

Icons

State Garden token Hex value
Default grey-600 #68737D
Hover, active and focus (if interactive) grey-700 #49545C

System status

State Garden token Hex value
Error red-600 #CC3340
Warning yellow-700 #AD5918
Success green-600 #038153

Although these are the most commonly used colours within the Zendesk interface, Garden includes a range of colours and shades to make your experience feel like Zendesk.

Disabled components

Avoid using any disabled components anywhere unless there’s a necessary reason. However, in certain cases, you can show disabled buttons to avoid having buttons constantly appear and disappear which can be confusing for the end user.

Components and patterns

Buttons

Buttons are used for a user to take action within your app. The Zendesk interface uses different styles of buttons depending on the circumstance. Here is a quick overview explaining the button style you should use to maintain consistency with the rest of the UI:

  • Primary buttons are for the most important action in a given view. There is typically one call-to-action on a page or view
  • Secondary buttons are for secondary actions
  • Tertiary buttons are for repetitive or de-emphasized actions in a given view

Button placement

Zendesk normally places the primary button on the right-hand side of the container, and Cancel buttons to the left of the primary button. If there is only a single button, it can span the entire app width, but it’s up to your discretion whether it is necessary.

Button wrapping

Try to avoid using too many buttons in a row as this can result in wrapping when localized, which could disrupt the rest of the content in your app. This is not a design requirement, but it’s good to understand the potential impact for some of your users.

For buttons with a long label, consider using a text link instead. Unlike buttons, it’s okay for text links to wrap over multiple lines.

Dividers

Use dividers to break up content within an app. Any dividers in between content or data should be #E9EBED (grey-200).

Displaying errors

Providing system feedback is crucial to let users know what is happening, especially when they are in the midst of resolving a customer query. Here are some tips about designing and displaying errors:

  • Show validation messages when a user encounters errors
  • Don’t use live validation as the user types. Instead, opt for inline validation messages after submission. This speeds up form completion and is more accessible
  • Provide instructions, don’t just state the problem. Avoid vague labels

Garden components, such as input fields, are built to handle validation natively.

Empty states

People see an empty state when there are no items or data to show. There may be no items or data to show because the customer is onboarding, they’ve completed all their tasks, or a search came back with no results. An empty state is not an error message.

  • Keep it positive
  • Inform the user
  • Use "you," not "the user"
  • Leave us out of it: Avoid "we" and "our"

Forms

Size and alignment

Because there isn’t much space available in the app container, you don’t want to take up excessive vertical height. It is recommendation is to use small buttons and fields. In Garden, these are 32px high.

Where you have more space, such as in a modal, you could revert back to a default size. Make sure you keep component sizes similar when used in proximity with each other.

In this example, a Search button is next to an input field which is not ideal for localization because it will likely wrap in a foreign language. However, it’s not uncommon to see a button below an input field so it still works.

Hierarchy of actions

It’s likely your app will have a range of actions the user can take. For a better user experience, use different types of buttons to bring focus and attention to key actions. As a rule of thumb, only use one primary button per screen.

Labels and help text

For accessibility and ease of use, it’s important that each field in your form includes a label. For fields that need to communicate a little more information to the user, you can help and placeholder text. Don’t include important information in your placeholder text, as this is hidden when the user enters something in the field, and isn’t great for accessibility.

Icons

The Zendesk interface uses icons at either 12px or 16px, and mainly use stroke icons. For consistency, we recommend using icons with the same size and style in your app designs. Try to avoid multiple icon sizes in a single app.

Garden has a large collection of icons you can use in your app. Follow the Installation guide to use them in your app.

Interacting with icons

If as icon is meant to be actionable or clickable, make sure to apply a default and hover state, as discussed in the Color section of this document. If they are just for visual purposes, then set the icon color to #68737D (grey-600).

Garden has an icon button component with these considerations already taken into account.

Loading states

When elements take time to fully display, it’s important to communicate system status to users. Loading states provide a visual cue that activity is happening but not yet complete.

If something takes more than 400 milliseconds to load, use loaders to reduce the perception of waiting time and make the experience less frustrating for users.

We use five different loaders at Zendesk to show loading states: skeleton, spinner, dots, progress, and inline.

Garden has components for each type of loader you might need in your app.

Type Situation
Skeleton Default to this loader where possible Use when content on the page is known or predictable
Spinner Use when the content is unknown or unpredictable Backup for skeleton
Dots Use within components to represent a busy state in response to user actions such as submitting
Inline Reserved for person-to-person communication Typing indicators
Progress Use to communicate the amount of time left when downloading or uploading content

Lists

Often apps contain lists of data. Here are some guidelines for displaying this data in an optimal way that can improve legibility.

Columns and rows

We do not recommend using more than two columns for data due to the app container width and localization issues that might occur. Although you can have as many rows as you like, we recommend paginating content to limit the vertical height of your app.

Paginate for long lists

If lists get long, we recommend using pagination so users can sort through the data easily and the app doesn’t become excessively long.

Garden has a range of pagination components that cover most use cases.

Tabs

Avoid using tabs in app containers due to the lack of width. Tabs also often cause wrapping issues for localization when used in width-restricted spaces.

If a tab wraps like in the example below, you’ll run into issues with the relationship between the content being displayed and the active or inactive tabs.

If tabs fit using the English language and the app doesn’t need to be localized, then it could work fine.

Alternative solutions

Try using buttons or text links to open a completely new screen in the app container and provide a Back button to return to the previous screen. Here’s an example:

Another option could be using buttons to open the information in a modal, which would give you more space to display information.

Further reading

  • Learn about Zendesk’s tone and voice to help with your apps content design
  • Explore the Garden website to see all of the components available