Human Interface Guidelines




For sections that have not yet been written, please refer to The GNOME HIG

Design Philosophy


What Design Is Not




  1. Design Is Not Veneer, Aral Balkan
  2. Design is Not Subjective, Jeff Law



Avoid Feature Bloat


Think in Modules


Accessible Configuration

Providing settings can be a way to make sure an app is accessible to a wider set of users with special needs, but it can also be an easy way out of making design decisions about an app's behavior. Just like with problems of feature bloat, settings mean more code, more bugs, more testing, more documentation, and more complexity. When considering adding options to your app, try to strike a balance of making your app more accessible without pushing design work onto your users.

Build for the "Out of The Box" Experience


Ask the Operating System


Is It Really About Accessibility?

Ask yourself if the configuration option you are adding is really necessary to make your app more accessible or if it makes sense to have a user make this decision. Don't ever ask users to make uninformed engineering or design decisions.

When You Absolutely Have To



See Also:

  1. Checkboxes That Kill Your Product by Alex Limi
  2. Don't Give Your Users Shit Work by Zach Holman
  3. The Wizard Anti-Pattern by Stef Walter

Minimal Documentation


Use Understandable Copy



For more information, see Writing Style.

User Workflow


First-Launch Experience

Required Configuration


Speed of Launch


Welcoming the User


Resetting the App


Normal Launch








Always Provide an Undo





Always Saved






Saving State

Apps should save their current state when closed so they can be reopened right to where the user left off. Typically, closing and reopening an app should be indistinguishable from the legacy concept of minimizing and unminimizing an app; that is, all elements should be saved including open documents, scroll position, undo history, etc.

Because of the strong convention of saved state, elementary OS does not expose or optimize for legacy minimize behavior; e.g. there is no minimize button, and the Multitasking View does not distinguish minimized windows.

Closing the App Window

Apps should never minimize instead of closing, as that puts the app window into a state that is foreign to users of elementary OS. Instead, windows should close or hide and re-open with a saved state. Any ongoing or background tasks should be completed soon after the window is closed, then the app should quit so as to not use unnecessary resources.

Background Tasks


If an app performs repeat background tasks (such as a mail client fetching mail), the background tasks should be completed by a daemon and not rely on any window being open.

Re-Opening the App Window


See also: That's It, We're Quitting by Matthew Paul Thomas

Desktop Integration

An important advantage that developers have when choosing elementary OS as their platform is the ability to seamlessly integrate their application with the default desktop. There are several ways in which you can make your app a native experience on elementary OS:

App Launchers

The primary method of discovering and using your app will be through an app launcher found in the Applications Menu or in the dock. In order to provide these launchers you must install an appropriate .desktop file with your app. This includes giving your launcher an appropriate name, placing it in the correct category, assigning it an icon, etc.

.desktop files follow the Desktop Entry Specification. They should be installed in /usr/share/applications.

The contents of .desktop files should follow this formula:

Name is a(n) GenericName that lets you Comment.

GenericName=Package Installer
Comment=Install Debian packages


You should not include descriptive words in your app's Name. For example, an address book app might be called "Dexter," not "Dexter Address Book." A web browser might be called "Midori," but not "Midori Web Browser." Instead, use the GenericName attribute of your app's .desktop file for a generic name, and the Comment attribute for a longer descriptive phrase.



If your app is easily categorized or described with a generic name, you should use that for the GenericName attribute in your app's .desktop file. If you can say, "My app is a(n) ____," then whatever fits in that blank could be the generic name. For example, Quilter is a markdown editor, so its generic name is "Markdown Editor".



GenericName=Markdown Editor




Comment=Listen to music


The following categories may be used to aid with searching or browsing for your app. Keep in mind that you can add more than one and you should add all that apply:

For more info, see the FreeDesktop.Org menu entry spec and the list of additional categories

Categories should be separated by and terminated with a semicolon:



You may also include keywords in your launcher to help users find your app via search. These follow the "Keywords" key in your .desktop file. For example, a web browser might include "Internet" as a keyword even though it's not in the app's name, generic name, or description. As a result, a user searching for "Internet" will find the app. Here are some more examples:

Keywords should be single words (in title case) separated by and terminated with a semicolon:


See also: Desktop Entry Specification from



Displaying Results from Contractor


Dock Integration

Integrate your app with the dock to communicate its status to the user at a glance.






System Indicators

Indicators are small icons that live on the top panel. They give users a place to glance for quick information about the state of the system. Selecting an icon opens a small contextual menu with related actions available to the user, including a way to get the the full related system settings.


Does Your App Need an Indicator?

Indicators are designed for the system; they display information that is relevant to or affects the general usage of the device. Given that users will probably install many third-party apps, we must be careful about the number of indicators we show and how they behave. Keep in mind that only a very small set of applications need or benefit from an indicator.

Avoid adding an indicator if:


Notifications play a sound and are displayed as bubbles just below the system indicators. They briefly appear on screen where they can be selected to open the relevant app or manually dismissed by hitting the X icon. After a short time, they automatically slide away. Missed notifications can be seen in and cleared from the Notification Center indicator.


Notifications play a system sound by default, but app developers are able to set an appropriate app-specific sound for users to be able to more quickly recognize the source of the notification. Be sure to use the notifications API via LibNotify to set the sound so that it respects user settings and does not play a duplicate sound.


By default, a notification will include the icon of the app that sent it. For certain apps, it might make sense to display a different relevant image along with a notification, like a user avatar if it's a communication app or album artwork if it's a music app.

User Control

Keep in mind that users are in ultimate control over notifications and whether or not they appear. Being overly aggressive with your notificiations is a quick way to get the user to turn them off entirely or even uninstall your app.

Do Not Disturb

Users can enable Do Not Disturb mode from Notification Center or System Settings. Do Not Disturb blocks all notification bubbles and sounds until it is manually turned back off.

Notification Settings

Notification bubbles, sounds, and appearance in Notification Center can each be toggled on or off on a per-app basis from the system notifications settings. Instead of including a global toggle for all notifications in your app, direct the user to the System Settings using a settings URL to open the Notifications page directly.

See also:

  1. Developer Tips: Backgrounding & System Integration by Cassidy James Blaede
  2. Farewell to the Notification Area by Matthew Paul Thomas
  3. Status Icons and GNOME by Allan Day

Container Widgets



Window Titles


Even if your app uses a headerbar, be sure to set the window's title; it can be shown in the window switcher and elsewhere in the OS.


Dialog warning icon

Primary text providing basic information and a suggestion


Suggested Action

Alert Text

An alert contains both primary and secondary text.

The primary text contains a brief summary of the situation and offer a suggested action. This text should use the CSS class primary. Primary text should be in sentence case and not include terminating punctuation, except in the case of questions.



Please refer to Granite.MessageDialog. It is preferred as an elementary OS styled dialog that follows elementary OS design conventions.

Button Order

Button Order

"OK" is not Okay


Suggested and Destructive Actions

If the primary action is not destructive, its button should be given the .suggested-action style class, rendering it in a highlighted style by default. It should usually be focused by default so it's quicker for the user to perform the action using the keyboard.

If the primary action is destructive—i.e. it cannot be easily reversed or undone—it should be given the .destructive-action style class, rendering it in a red style by default. Destructive actions should not be focused by default to prevent accidental activation.

Multiple suggested and/or destructive actions should not co-exist in the same context; there should only be one of either type in a dialog.

Preference Dialogs


See also:

  3. Should I use Yes/No or Ok/Cancel on my message box? on UX Stack Exchange








Ordering Toolbar Items


Toolbar items should be organized with the most significant objects on the left and the least significant on the right. If you have many toolbar items it may be appropriate to divide them into groups with space in between each group. Keep in mind that when viewed with RTL languages, your toolbar layout will be flipped.

UI Toolkit Elements


Widget Concepts


Controls That Do Nothing






Hidden Widgets









Welcome Screen

Welcome Screen



Typically a Welcome Screen is used for apps like Music or Code where you have to import or create objects in a library before you can interact with them. This provides your users with a clear path to getting started and points out any immediate steps they must take before your app becomes useful.



The Welcome Screen consists of two sets of labels:



Source List


Source List in Files










Tool Buttons

Open button




All Tool Buttons should have tooltips, since they do not contain a label. This assists users with disabilities as well as giving a translation for an unrecognized icon. Tooltips should be done in sentence case without terminating punctuation.


Keyboard Shortcuts

If a button has a related keyboard shortcut that will perform the same action, its tooltip should include the shortcut. See Granite.markup_accel_tooltip () for specifics.

Text Buttons

Cancel button


Text Button labels should be done in title case.







Back Buttons

A back button is simply a text button with a special style class. It should be used to navigate back to a previous view, typically from a child view to the main view.

The text of the button should be the title of the previous view. If the button will take the user “home,” then “Home” may be an appropriate label; however a more specific label is preferred, such as “All Settings” in System Settings. Avoid just using “Back,” as the back button is visually distinct and going back is already implied by its unique shape. The button should tell the user where it will take them back to.

When using a back button, it is recommneded to use a Gtk.Stack to switch between views. This way you get a sliding animation further representing the backwards progression when activating the back button.

Back buttons are typically seen in headerbars, but can be used in other contexts as well.

Search Fields


Search Field

Distinguish Between Search and Find









Selection Controls

Selection controls present a way for users to select or enable options. There are several types of selection controls available in elementary OS:



Use checkboxes when users are making a selection of items. If you have a single option, avoid using a checkbox and use a switch instead.

Make sure that users can toggle the state of the checkbox by clicking on the label associated with the checkbox.

Labels associated with checkboxes should usually be nouns or nounal phrases.



Use a combobox (also called a dropdown) when:

Linked Buttons

Linked Buttons

Use linked buttons when:

Linked buttons can be used to select multiple related options like "Bold", "Italic", and "Underline", or they can be used to select a single mutually exclusive option (also called a mode button) like Grid, List, or Column view.

Linked buttons should never contain colored icons. Only 16px symbolic icons OR text. Do not mix icons and text.

Radio Buttons

Radio Buttons

Use radio buttons when:



Use a switch when users are toggling certain features or behaviors "on" or "off".



Mode Switches

Mode Switches

As of elementary OS 5 Juno, mode switches are a new switch-based widget that communicate switching between two distinct states. For example, switching between a photo or video mode in a camera. The switch is drawn smaller and inline with the provided symbolic icons. Tooltip hints can also be provided when hovering the icons.

Use a mode switch when you have two distinct and opposing states that you are switching between that can be effectively communicated via an icon. If you need text or more than two states, use a Mode Button instead.




Static Notebook

Static Notebook


Dynamic Notebook

Dynamic Notebook

A Dynamic Notebook is a way for an app to provide user-manageable tabbing functionality, commonly seen in web browsers. The tabs appear attached to the toolbar on their own tab bar above the relevant content. Tabs are able to be rearranged and closed, and a "new tab" button is at the start of the notebook widget.





Warning dialog icon Chat icon Photos icon Videos icon Online accounts icon Terminal icon

For example, if your icon's metaphor lends itself well to a unique shape, use that shape for the overall icon shape instead of placing that shape onto a generic rectangle, square, or circle.

Bad (unnecessary base shape) Better (unique shape)
Base shape Unique shape



Camera icon Hard disk icon Mouse icon Package icon HTML Text icon Computer icon

Action Icons


Previous icon Next icon Document export icon Print icon Save icon Delete icon Cut icon Undo icon Inverse icon Play icon New tag icon Menu icon



Icon Sizes


16 pixel Terminal icon 24 pixel Terminal icon 32 pixel Terminal icon 48 pixel Terminal icon 64 pixel Terminal icon 128 pixel Terminal icon
16 24 32 48 64 128
128 pixel Terminal icon


Color Palette

Color—don't be afraid to use it! Many of the elementary OS icons use vibrant colors; it's best to reserve muted tones and grays for boring system icons.

Mail icon RSS Reader icon Web browser icon Photos icon Network icon Calendar icon

Colors do have their connotations, so be cognizant of this when picking them. For instance: red is usually associated with error or "danger", and orange with warnings. But you can use these color connotations to help convey your icon's meaning, such as green for "go". We use the following palette:

Strawberry #c6262e
Strawberry 100 #ff8c82
Strawberry 300 #ed5353
Strawberry 500 #c6262e
Strawberry 700 #a10705
Strawberry 900 #7a0000
Orange #f37329
Orange 100 #ffc27d
Orange 300 #ffa154
Orange 500 #f37329
Orange 700 #cc3b02
Orange 900 #a62100
Banana #f9c440
Banana 100 #fff394
Banana 300 #ffe16b
Banana 500 #f9c440
Banana 700 #d48e15
Banana 900 #ad5f00
Lime #68b723
Lime 100 #d1ff82
Lime 300 #9bdb4d
Lime 500 #68b723
Lime 700 #3a9104
Lime 900 #206b00
Blueberry #3689e6
Blueberry 100 #8cd5ff
Blueberry 300 #64baff
Blueberry 500 #3689e6
Blueberry 700 #0d52bf
Blueberry 900 #002e99
Grape #a56de2
Grape 100 #e4c6fa
Grape 300 #cd9ef7
Grape 500 #a56de2
Grape 700 #7239b3
Grape 900 #452981
Cocoa #715344
Cocoa 100 #a3907c
Cocoa 300 #8a715e
Cocoa 500 #715344
Cocoa 700 #57392d
Cocoa 900 #3d211b
Silver #abacae
Silver 100 #fafafa
Silver 300 #d4d4d4
Silver 500 #abacae
Silver 700 #7e8087
Silver 900 #555761
Slate #485a6c
Slate 100 #95a3ab
Slate 300 #667885
Slate 500 #485a6c
Slate 700 #273445
Slate 900 #0e141f
Black #333333
Black 100 #666666
Black 300 #4d4d4d
Black 500 #333333
Black 700 #1a1a1a
Black 900 #000000

Symbolic Icons

Symbolic icons are common system icons that symbolize files, devices, or directories, and are also used to represent common actions like cut, copy, and save.


Icon style comparison

Colored vs. Symbolic Icons

The use of full-color and symbolic icons is not interchangeable; both have appropriate uses.

Full-color icons are best used for:

Symbolic icons are best used:




Keeping these lines in mind while designing, means you can place elements along them to ensure that icons appear more consistent when put together. For example, notice how some elements in both the Terminal and Videos icons above relate to the mean line.

Common Measurements


Canvas Size Base Line x-Height Mean Line Height
16x16 1 14 8
24x24 2 20 12
32x32 2 26 16
48x48 3 40 24
64x64 4 56 32
128x128 9 104 64





Outlines & Contrast




Shadows & Highlights


Edge Highlight


Edge highlight example in elementary OS Music icon

Drop Shadow


Shadow example 1


Shadow example 2

Pictogram Shadow

If your icon has a pictogram, such as the play triangle in the icon below, you can give it a drop shadow to make appear extruded from the background of the icon.

Video player icon


Alternatively, you can also use a highlight and shadow to make the pictogram appear inset into the background.

Bad (flat pictogram) Better (extruded pictogram) Better (inset pictogram)
Flat foreground Extruded foreground Inset foreground

Icon Materials


Glossy vs. non-glossy

Dos and Don'ts




Writing Style

Use the following rules to keep your text understandable and consistent:

Be Brief


Think Simple


Get To The Bottom Line


Don't Repeat Yourself

Repetition can be annoying and adds unnecessary length to your messaging.

Use Visual Hierarchy






Sentence Case



Title Case

Title case means you capitalize like a book or article title. In elementary OS, we follow the AP Style.



Proper nouns should always be capitalized properly; this means that, for example, Google should always be shown as "Google," and MPEG should always be shown as "MPEG." One major exception is "elementary." It should follow the brand guidelines and always appear lowercase, even at the start of a sentence. If you're unsure how a certain pronoun should be officially capitalized, refer to the documentation of the pronoun in question.

Keep in mind these are the rules elementary OS follows for English; capitalization for other languages should follow the conventions of those languages.



Terminating Punctuation

Whether or not to use terminating punctuation (like a period . in English) depends on context. For secondary labels in dialogs, use terminating punctuation. For single-sentence copy in tooltips and other clarifying contexts, avoid terminating punctuation.

For multi-sentence copy in clarifying contexts, use standard terminating punctuation. If there are single-sentence labels in the same context (alongside multi-sentence labels), terminating punctuation may be used for consistency.

For questions, always include terminating punctuation (i.e. a ? in English).

Prevent Common Mistakes

Hyphens & Dashes

Hyphen (-)

Use \u2010 in code. Used for:

En Dash (–)

Use \u2013 in code. Used for:

Em Dash (—)

Use \u2014 in code. Used for:

If in doubt, refer to Butterick's Practical Typography.


Using Ellipses


Additional Information


Shortened Text


If you're unsure, it's best to use middle truncation, as it keeps both the beginning and end of the string intact. It's also important that you do not ship your app with any truncated text; truncation should only be the result of a user action such as resizing a sidebar or entering custom text.

When Not to Use Ellipsis


Naming Menu Items

