New style guide for Drupal 8

Drupal Seven needs to be continuously reinvented. We developed a proposal after much discussion, that set to change how Drupal 8 administration looks out-of-the-box.

This style guide proposal for Drupal 8 core and contributed modules is intended to help shape and direct administrative UI development, with the goal being a theme- and brand-consistent administrative user experience.

This is a cross post from the discussion that happend at, the style guide is now fully implemented in Drupal 8.

Motivation and Principles

In the Drupal 8 development cycle many additions and changes have been made to Drupal’s administrative user interface, and more will be required as new features are completed. The existing changes have been completed in relative isolation from each other. Although each change and addition has been a step in the right direction, the result is a UI that lacks consistency.

This is largely for lack of a guidebook for Drupal’s admin UI. Even though great, coherent UX work was done for Drupal 7, and we have functional UI standards, there remains no central guide for the visual conventions used in Drupal’s core admin theme, Seven. We need something to help us maintain visual consistency when changing and extending the UI. We need a style guide for Drupal’s default admin theme.

Ry5n, Yoroy and Bojhan have been collaborating on IRC to create such style guide for the Seven theme. After a lot of iterations, where ry5n took a leading role with reviews and proposals from Bojhan and Yoroy going back and forth many times, we now have an initial proposal.

The goals of this draft style guide are:

  1. Identify Drupal core values that we can use to determine the look & feel for the Seven theme.
  2. Unify the visual language in Seven and ensure the overall look-and-feel supports the core values.
  3. Identify the visual and UI patterns used by Drupal core so that they form a conscious, shared language for us to built upon.
  4. Provide guidelines and rationale for others (e.g., contrib) to build upon as new interactions, styles and platforms emerge.

Although the guide presents as much rationale as possible for each design decision, it is not polished; design details are still in flux. But at this point we wanted to get it out for more feedback.

Seven theme is a special case that has to cover a lot of ground:

  • It has to be completely accessible.
  • Mobile friendly.
  • Provide consistency across 20.000 modules.
  • Stand the test of time – as it is often the main way people interact with Drupal and one of the main ways people come to understand the Drupal brand.

This is a proposal, so we hope to receive loads of feedback.

Basic principles

The development of the Drupal brand has come a long way in the past few years. With the introduction of an administration theme and toolbar we now have important places where people interact with Drupal visually. For a lot of people who use Drupal but don’t visit, the administrative interface is their only interaction with our brand.

We looked into words that describe Drupal’s brand:

powerful, adaptable, empathetic, direct, democratic, accessible, clear, concise, natural.

Part is this brand is also the community values we express:

welcoming/respectful, open, informal, collaborative, transparent, responsive, credible.

How should we express these principles? #

Having a set of adjectives to describe Drupal, we tried to give those terms visual expression using basic design elements and principles. First, we mapped each adjective to a set of possible visual characteristics:

  • powerful: confident, precise shapes and strong contrast, especially for user-controllable elements.
  • empathetic, responsive: choose calming colors and rounded forms; give emphasis to what matters;
  • clear, direct, concise: use crisp lines and simple, decisive shapes; avoid patterns, texture, and ornamentation; each element should serve a clear purpose; make measured use of whitespace: room to breathe, but avoid sterility and emptiness; use rules/boxes sparingly.
  • accessible, transparent: appeal to the greatest possible number of people; choose a legible typeface; set text for optimal readability; emphasize what matters; use consistent visual cues for affordances.
  • natural: desaturated tones: avoid neon/artificial colors; organic rather than geometric forms; choose a typeface that retains a trace of the human hand.
  • friendly, collaborative, democratic, respectful: choose cheerful colours; avoid high contrast at large scales (too bold/aggressive); prefer well-known design patterns, iconography and affordances; avoid visual indulgence, ensure visual style is extensible and flexible.

Some of these design elements would be in conflict with one another: powerful shapes and too much contrast might make the UI unfriendly or even disrespectful. In these cases, a careful balance is needed. In other cases, there is a clear common thread.

Summary: the Seven Graphic Style

  • A primarily light tone to appear bright and open.
  • A neutral, desaturated color palette, both friendly and calming.
  • Legible, readable typography. Employs a typeface with some humanist characteristics in a few weights and styles.
  • Crisp lines and sufficient contrast, but not jarring. No large areas of bold colour.
  • Bold shapes reserved for headings and action elements.
  • Some rounded forms to communicate friendliness and naturalness.
  • Little or no ornamentation: no patterns, textures, gradients or shadow/emboss effects – except to communicate affordances.
  • Borders and background tone as grouping devices only: to clarify relationships and emphasize important elements.
  • Generous and consistent use of whitespace.
  • Aesthetically appealing, though minimal graphic style; should appeal simple but not sterile; gracious rather than opinionated; confident without overspeaking.

On Contrib

In addition to articulating the foundation and expression of the Seven theme and core modules, this style guide aspires to be a help to Drupal’s contrib developers and themers as well.

For contrib module developers, this guide hopes to provide design patterns and styles that can be used as templates for a module’s administrative UI, creating consistency beyond the default Drupal install.

We also hope to inspire theme developers with a consistent, beautiful, well-thought-out administration theme.

Color Palette

The proposed guide makes few changes to the existing Seven color palette while still supporting the principles and graphic elements we identified above.

Seven uses three primary colors: white, “burlap” and “Drupal blue”. White provides openness and serves as the ground for other elements. Burlap is a yellow-tinted gray, providing friendliness and energy while maintaining neutrality. Drupal blue associated the theme with the Drupal graphic identity as well as being a naturally calming color.

Drupal blue is used for links, primary buttons, and other interactive elements such as the labels on tabs. Interactive elements that use Drupal blue and have an active state use a darker shade of that colour (#004f80). Burlap is used for background tints and fills in several shades (always at 51° hue).

Red is used sparingly, and only to communicate an error state or danger action (e.g. delete). A strong yellow-orange is used for warning messages and a grass green for success messages.

We chose colour combinations that pass WCAG 2 AA contrast guidelines for accessibility, so that text can be read and elements distinguished by everyone who uses Drupal. Some challenges in finding contrasting colors for different states remain, we still have to further tune a few of these.


In Drupal 7, the core icon set makes use of multiple colors per icon, gradients and other effects. In accordance with our new updated graphic style, we propose replacing core’s existing icons with simpler, more definitively iconic versions. Not only is this more stylistically consistent, it enables us to use a webfont for scalable, re-colorable icons.

Please note: most icons in the current design mockups are not from the admin icons project. Some are from the Symbolset (SS Standard) icon font and some are custom-drawn. Symbolset was used for convenience during development, but cannot be used with Drupal since it is not open-source. The Symbolset icons would need to be replaced with alternates during implementation.

Individual Components

Content Header

header showing, title, and a star like icon for shortcuts

In D7, the “add to shortcuts” icon is a circled plus symbol. This symbol is commonly associated with an add or create action, but there is nothing to indicate the connection to shortcuts. We propose using the star icon globally for shortcuts in Seven to make it more recognizable and understandable to a wide audience. Most people will be familiar with the use of the star icon for bookmarks/favourites from their web browser (IE, Chrome, Firefox) and from popular services such as Twitter.

The various states for the shortcut add/remove component are shown inset, from left to right: inactive, inactive:hover, activated, activated:hover and finally inactive again.

Here, the header background is #ebeae4 or hsl(51, 15%, 91%).


Showing different heading levels set in Source Sans Pro

This guide proposes all text be set in Source Sans Pro from Adobe. Similar in character to Lucida Sans (the existing typeface specified by Seven), Source Sans is a professionally designed, fully open-source type family that falls into the general category of “humanist sans-serif”. Fonts of this type combine the modern geometric and industrial-age characteristics of sans-serif typefaces with the calligraphic and handwritten qualities of Renaissance letterforms. This balance of the engineered and the human matches well with the Drupal brand.

Seven’s original choice of Lucida was a good one for those same reasons, but also for a very practical one: legibility in UI. Source Sans is arguably even better in this respect, with glyphs such as lowercase L and upper/lower I all easily distinguishable from one another, even at small sizes. This is one of many details to consider when choosing a typeface for UI work, and where some common choices – like Helvetica – fare poorly.

Source sans also provides a versatile set of weights, including a semibold.

  • Body text is 16px/24px Regular. All text is 90% black (#1a1a1a) unless otherwise noted. A baseline grid of 24px is used throughout, relatively strictly for running text and for spacing between elements, less strictly within some UI components where other requirements come into play.
  • Four heading levels are proposed, set semibold to provide some solidity. There is also a greater range of type sizes than currently in D7, allowing for a clearer visual hierarchy. Heading levels (using the font-size/line-height shorthand) are:
    • 26px/30px Semibold, 80% black (#333); suggested exclusively for page titles.
    • 21px/24px Semibold, #333; suggested for subheads, modal dialog titles, etc.
    • 15px/24px Semibold all caps with ~0.1em letterspacing; suggested for fieldset legends and small subheads.
    • 13px/18px Semibold, all caps with ~0.1em letterspacing; suggested for table headers, primary tabs and other tight spaces.
    • Caption text is 14px/18px Regular, and can be further de-empahsized by lightening to 67% black or #555. This guide recommends text not be set smaller than 14px (or 13px all caps).
  • Links and are colored #0074bd and lightened slightly on hover. In running text links should always be underlined. When contained within bordered elements where the underline adds visual clutter, it is usually omitted).

License issue

Finally, Source Sans is one of the few professionally-designed typefaces that is not only free but open source, available under the SIL Open Font License (OFL). However, it is unclear whether the OFL would allow it to be included as part of Drupal core. The Wikipedia page on OFL states that it is not GPL-compatible. However, SIL’s own FAQ states, under a question about bundling with GNU/Linux that “Fonts licensed under the OFL can be freely included alongside other software under FLOSS (Free/Libre and Open Source Software) licenses. Since fonts are typically aggregated with, not merged into, existing software, there is little need to be concerned about incompatibility with existing software licenses.”

Provided the OFL license is compatible and the community supports it, this guide proposes that a webfont version of Source Sans Pro be included with the Seven theme. To keep file size and HTTP requests down as well as to simplify the design system, not all of the fonts that make up the complete type family would need to be included. This guide uses the Regular, Italic, Semibold and Bold fonts.

Text fields

text fields disabled (grayed out), a blue outline onfocus, and dropdown for autocomplete

“Title” field, top to bottom: 1) normal text input; 2) hover state; 3) invalid state with inline error message; 4) disabled.

“Tags” field, top to bottom: 1) autocomplete input with help text; 2) autocomplete in use, showing “tokenized” input, active spinner and dropdown menu.Text inputs are styled to be recognizable but not garish, with a subtle background tint (#fcfcfa). A slight softening of text inputs is achieved with a 2px border-radius; this is a subtle refinement that we use throughout form elements to subtly soften otherwise harsh corners. For consistency, we propose changing the D7 “throbber” to a “spinner” styled similarly to the progress bar component (see below) for consistency. To reduce UI clutter, the spinner would appear only while awaiting a response from the server.

Note that the required field marker is no longer red, both to reduce UI clutter (without removing information) and to allow red to be reserved exclusively for error states and danger actions.

Search field

showing search field, with button attached to the field and full rounded corners

Top to bottom:

  1. Search input with placeholder text and attached submit button.
  2. Search input with active autocomplete results.
  3. Search input with a user-supplied value, showing non-italic text and “clear” button.

The search field is rounded both as another opportunity to introduce friendliness into the UI, but also follows a tendency for search fields to be rounded in some browsers and operating systems.

The dropdown menu is intentionally designed as a distinct component (see the section Dropdowns and Popovers) for modularity of the design and code reusability. Visually and in terms of implementation, merging or joining the search field with the dropdown is both awkward and not strictly necessary for usability.

Basic Form Controls

showing select box with slightly rounded corners, checkbox and radio options with blue background

Customized controls for <select>, <input type="checkbox"> and <input type="radio"> (disabled state on the right)

There are challenges associated with customizing these particular form controls, especially around accessibility. However, we feel there are a number of ascetic gains that can be made if we choose to implement this.

Similar to the text fields we use slightly rounded corners on these form elements to capture the softness we wish to express. We additionally styled the checkbox/radio’s somewhat special to accommodate the idea of brand consistency across platforms.


buttons with fully rounded corners, showing the different states from normal, focus, hover, to active - using Drupal blue

Row 1: standard button;
Row 2: primary button;
Row 3: danger button

Buttons should be clearly identifiable as such, with normal and primary actions inviting interaction. At the same time – for visual conciseness – graphic effects are limited to a subtle gradient (and border, where necessary for contrast with a background). For an informal, friendly appearance, identifiability among other UI controls, and for continuity with Drupal 7, discrete buttons have a fully rounded “pill” shape.

As with input fields, focus is communicated with a blue halo. The hover state brightens the button (optically, light colours ‘advance’) and adds a small shadow beneath, causing it to ‘stand up’ and invite a click. Primary buttons – the save button on a node form, for example – are emphasized using Drupal blue. This carries through the main brand colour, and, since blue is a calming colour, the added emphasis remains respectful, not yelling or rushing the action.

Delete buttons – those that perform a destructive action such as deleting a node – are colored red, since they must call attention and signal caution. However, they should not draw the eye away from more common actions, so their border and background is removed, appearing instead as a plain link. An underline provides an affordance, since danger buttons have neither the standard link colour nor the standard button style.

Note that all button colours pass WCAG 2.0, except for the primary button’s hover state, which warrants some consideration.

Split Buttons and Dropbuttons

showing buttons who are merged with dropdowns for save states (e.g. save as draft)

Additional button styles allow for variants whose appearance remains consistent with the normal button style. Shown here:

  • A proposed “split button’ (rows 1 and 2) would replace the current core dropbutton. There are several advantages to the proposed design:
    1. Style is consistent with standard buttons;
    2. Position and size of the button does not change when a dropdown menu is disclosed (a problem with the current dropbutton, which causes the mouse pointer to require re-positioning to close the menu);
    3. The dropdown menu itself is not custom (see the next section “dropdowns and popovers”). This decouples the menu from the button component, allowing for more maintainable and re-usable front-end code.
  • A proposed “dropbutton” (row 3): a single button that discloses a dropdown menu.

Note that the split button configuration is really nothing more than a 'button group' of two, comprised of 1) a standard button and 2) a dropbutton with an icon label. Button groups of 3 or more buttons could be implemented identically to the split button.

showing dropdown options on link, button and autocomplete

Left to right: popover, dropdown and “attached” dropdown.

This guide proposes an independent UI component for disclosable menus.

Please note: The selected menu item background does not pass WCAG standards for contrast against white; the type is bolded to provide an accessible visual queue. This design decision needs accessibility review.

Small Controls

large buttons minified with primarily less height

Left to right: small button (with icon); small split button; small select element (with left-aligned label).

Sometimes tight spaces recommend the use of smaller controls. Such situations include WYSIWYG toolbars, filter forms and table rows.
When touch support is detected, this guide proposes small controls revert to their full-size counterparts to improve touch-target sizes.


progress bar using the iconic scrolling bar, with a cancel on the top right, activity in the bottom left and percentage in the bottom right

To appear more cheerful – for the same reason a lobby or waiting room should make an extra effort to be pleasant – progress bars are fully rounded. The progress bar retain much of its current values, e.g. always animated to be scrolling and clearly outlined activity and percentage on each side of the horizontal axis.

File Field

showing file field, with border around it and buttons, also with a icon to provide a visual landmark to which each row is aligned

In terms of interaction, file fields could be a lot more accessible. This guide proposes both a new appearance and a new interaction design:

  1. Files can be added from the local filesystem using drag-and-drop, or using the traditional click-browse-attach workflow (which hands the action off to the OS and back)
  2. Files upload automatically once added by dropping or browsing.
  3. Uploaded files provide a preview where possible (images) or a file-type-specific icon where not.
  4. File fields with multiple attachments use progressive disclosure to reveal each additional slot in turn. They should support dropping multiple files onto a single dropzone to upload multiple files at once.
  5. The “Browse Library” functionality is speculative at this time, but designed to accommodate contrib.

An important reason to encapsulate much of this functionality, is that it tends to scale much better amongst many items and especially if placed between forms it can serve as a clear visual landmark.

Image Field

showing filefield with image attachment thumbmail

We made a design for the image upload field, we imagine a small version of the image can be rendered as thumbnail. We also styled a “drop-in” style, depending on how far WYSIWYG goes this could be part of that initiative.


fieldset with a slight background shade

Details and Accordion

details and accordion with styling per tab

The file and image fields, fieldset, details and accordion are all container elements to some degree, having a number of sub-elements in relation to one another. They all use a background tone and slightly darker border to contain these sub-elements and visually signal their grouping. They do this with as light a touch as possible while remaining distinguishable. To soften them slightly, a 2px border-radius is applied to the outer corners.

This is a style that would require more real-world prototyping, to see the impact on various forms.

showing tabs aligned to the left and secondary tabs with an underline

Horizontal tabs include a number of proposed changes:

  1. Left-align both primary and secondary tabs, including those attached to the overlay (see below). This is intended to resolve issue #763720 (Visibility of primary & secondary navigation) by placing all tabs on the primary scan line (left margin).
  2. The negative space created where two rounded tabs are joined can be a visual distraction. The proposed style retains the border radius but removes the negative space by “extending” the tabs underneath one another.
  3. Secondary tabs are re-styled in an attempt to create a better connection between them and the primary tabs, while both linking them to and separating them from the content below.

The primary rationale for this redesign is the large disconnect we created by the right alignment of tabs, which were often missed. Similarly the secondary tabs because of their decreased visual prominence were missed even more. With a redesign of the overlay and modal, we can now accommodate a different style and placement of tabs.

Vertical Tabs

vertical tabs pretty much the same as D7, only difference is more darker background on inactive tray

Vertical tabs use essentially the same design as D7, just updated for consistency of details.


showing table, with hover upon row, underline on table column selection and lines between rows

To improve the ratio of information to UI chrome, this guide recommends removing zebra striping and using thin rules to separate table rows. A progressive enhancement creates a subtle highlight on the hovered table row, allowing the eye to more easily move horizontally along the row, even when large stretches of whitespace appear between cells contents. (Note that this effect, being an enhancement, has no planned touchscreen equivalent and does not pass WCAG contrast standards.) For similar reasons, this style also removes left and right borders from the table and table cells.

The style used here for the sort-active table header cell is a motif carried through to other elements, such as secondary tabs and pagination. This consistency is both good for usability and for Drupal’s credibility (part of the brand).


Showing pagination with the active page underlined and arrows to move between pages

To simplify the UI and focus on the 80% use case, this guide envisions removing the “first” and “last” links from the pagination component and also the text labels for “previous” and “next” links. This change is contingent on positive user testing.

The Nav List is used on “hub” pages to provide an on-page navigation menu with help text. This component is not greatly changed from D7, with only minor typographic finessing and a rounding of the “fancy bullet” used to mark the list items, in keeping with the friendliness of the brand.


showing (error) messages, with a line on the left with the warning color and icons
Messages are proposed to follow closely from a style proposed for D7. This style attempts to make messages very noticeable (with a bright colour bar and icon(s) at the left margin) while preventing them from being visually overwhelming (avoiding a full border). Message colors are slightly modified from current values, both for contrast with white and to distinguish one from another.

The messages also propose simplified (one-color) versions of the existing icons and the theme-wide 2px border-radius.


Showing overlay with new tabs styling

The overlay has been removed from Drupal 8

Drupal’s existing overlay style has a number of drawbacks:
  1. The overlay title floats above the overlay container itself, which creates a certain amount of disconnect between the overlay content and the page title.
  2. Tabs – especially secondary tabs – are placed on the right side of the overlay and not styled very prominently, which can cause the eye to miss them when scanning the page.
  3. The overlay’s close button sticks out the right side of the overlay, which forces extra margin to be allotted one the right of the viewport. Because the overlay already requires additional margin on the left and right to hint at the origin page below, this leads to significant loss of layout space overall.

The proposed changes address these drawbacks by positioning both the overlay title and the overlay close control on a semitransparent panel joined to the main overlay content, and by maintaining the new tab style of left-aligned tabs (see Tabs section above).

In additional to usability improvements, this arrangement also simplifies the visual elements themselves, specifically the close button and the silhouette of the overlay panel itself.

Showing modal style with cross on far right and title bar with dark background
We currently have no real styling for the modal in core, it was placed in with little to no styling. We propose to align this styling with the overlay, because conceptually they are not very different. Users often interact with the overlay just like a modal, and the modal is often something placed on top of the overlay (e.g., views).

The only difference is the use of heading style B rather than A for the header.

Case Study: Mobile Screen

To demonstrate the proposed styles in-use, and to help visualise what they might look like for small and narrow screens, this is what the page at /admin/structure/types/manage/article might look like:

showing mobile screen with toolbar on top

Authored by Ryan Frederick, Roy Scholten and Bojhan Somers

Recent articles

The Drupal core product needs to become more engaging and useful right out of the box. Usability testing has shown why. Here, we want to look at how we can change our process to be more efficient and effective.
We tested Views in Drupal 8 at BADCamp 2012 and this uncovered a large number of usability issues. Since then we have been hard at work resolving them.
Drupal Seven needs to be continuously reinvented. We developed a proposal after much discussion, that set to change how Drupal 8 administration looks out-of-the-box.