In our Devportal Design Guide series, you will read about common design patterns, get an insight into our project work related experiences, and learn how we tackle the design of a developer portal user interface.

Why did we start researching design on devportals?

We found that dedicated research can help us to write more objectively about design patterns, and decide what the common practices are —based on statistics.

We examined 70+ developer portals from different industry fields, but also pulled in DevPortal Awards 2018 nominees and winners. We gathered information about various design aspects, like layout, responsiveness, color schemes, typography and the usage of graphical elements.

We will stay away from the most basic design principles but focus on devportal specific advice instead, and give related examples.

Part 4: Basic graphical elements that support functionality

FAQ

  • What kind of icons can you use on your developer portal and where can you apply them?
  • How do colors and typography affect and improve the usability and transparency of a developer portal?
  • What kind of images and illustrations can support and visually improve dry technical content?
  • What if you don’t have a brand font, an image bank or an own icon pack? Where can you find these and which viewpoints should you consider when selecting the elements that are right for you?
  • How can you make code sections prominent and handy?

Experience and advice

Icons

Icons play an important role in the UI of websites and of developer portals.

Functional, UI icons

Functional icons, commonly known as system icons or UI icons, visualize different functions and information in a simple way, such as search, profile, login, logout, open and close sections, pager and dropdown arrows, edit, view, delete, warnings, etc.

Some advice regarding UI icons:

  • These system icons are usually smaller (24+ px) and functional thus we advice to choose an icon pack that contains simple but noticeable icons.
  • Colorize them consistently on every page. E.g. If they are clickable choose a different color for their normal, selected, or hover state, and a utility color if they express a warning or error, etc.
  • Try to find common, easy to understand icons that are meaningful for everyone.
  • If you think that the meaning of an icon is not obvious, combine it with a textual description. For example, use tooltips if the user hovers over them. Note that on touch devices you don’t have a hover-over effect and you’ll need to figure out a different solution. Of course it is also likely that users will figure out the meaning of these icons after repeated use.
  • Don’t forget that the hover effect of the functional icons (e.g. color change) gives visual feedback about their interactivity.



UI icons (Feather icon pack) with hover effect and tooltip.

Content icons

Icons are not only for navigation, interactions and buttons: you can also use them as visual elements in content sections to break the monotony and highlight the main content.

Content icons can appear in benefit sections, on cards and overview pages.



Icons supporting the content on the Twilio site.



The icons reflect the brand and support the content on Android Developers.



We can also use a unique icon (or image) to represent an API but don’t forget that this solution is feasible only in case you have a small amount of APIs. If you have a lot of APIs it might not be worth the effort to find and draw a genuine icon for each and every one of them.



Different icons and colors for every API on Typeform’s Developer Portal.



Different icons for each API on the Twilio site. Here the colors indicate the categories.



If you have a lot of APIs, it might become hard —after a while— to find a meaningful icon for each one and most probably your users won't be able to identify the APIs with their icons. In this case, we suggest using icons only for the API categories, not for each separate API.



Different icons for the API categories on Worldpay Developers.



Different icons for the API categories on the Fourth developer hub.



Some advice regarding content icons:

  • You can use bigger, stylish and more complex or colorful icons and icon packs to express the meaning of a complete paragraph. While some icons are well-known (e.g. an X for closing something or a + for adding things), others are not that common and easier to understand if they are more detailed.
  • Color icons consistently on every page according to the brand colors.
  • Try to find icons that visualize the content of the text.
  • Handle the icons as explanatory illustrations: the description itself explains them, so you don’t need a tooltip or any additional information.

Resources

Summarizing, we suggest to use 2 icon types/icon packs. A simpler one for the functional UI icons and a more complex, visually appealing one for the content icons. Of course, if only one pack is available it can be used for both.

If you don’t have a brand icon pack at all, you can find beautiful free and premium icons and complete icon packs here:

Some UI icon packs:

Choose a style, shape, thickness, fill-type, size that is consistent and fits your brand guide; always download them in vector format. If available, download the icon font as well.

Colors

Brand and secondary colors

The color palette of a developer portal should be consistent with the company’s brand and follow the brand guidelines’ suggestions. Besides the main brand colors, you can add secondary colors if necessary and use them on the developer portal. Try to find a secondary color that matches the main colors and use them in smaller amounts only: it shouldn’t dominate over the main colors.

Neutral colors

Use neutral colors (black, white, grey shades) for simple descriptions and secondary information that shouldn’t be prominent, for example disabled button statuses, inactive icons or form fields, and hints.

Interaction color

Define a prominent link color and use it consistently on every page in case of interactive elements and links (unless you need to define another color because it looks bad over a certain background color or the link would disappear on a background with a similar color). This helps the user to distinguish clickable (or tappable) elements from the non-interactive ones.



Color usage on Twitter Developer. High-contrast colors, dark grey and black are used for text and non-clickable headlines, neutral grey and white for section backgrounds and a bright purple for the interactive elements, like buttons and links.



Clean, minimal design and bright red link colors on Worldpay developers.



If you don’t want to use the link color too often, you can follow a common practice in which the clickable element itself has the color of your choice and the link color is revealed only in its hover state. For example, the link color can be used on the primary buttons’ normal state and the secondary buttons would, then, have a different, moderate color and only their hover state would have the link color. Of course, it is just a solution for using the link color in a hidden way, the secondary buttons can have a totally different style and color.



Texts in the footer use the same font color and style as the body text in the upper section on DNB Developer. To emphasize that these are clickable links, the link color is used to highlight the background in hover-over state.



When you use clickable elements, we suggest defining a different look for their normal, hover, selected or disabled states and use it consistently on all pages. The difference can be another background or text color, but sometimes an underline (texts), a drop shadow, a border or size change (for example in case of buttons) is enough. E.g. neutral grey indicates the normal state of a pager chevron UI icon, the hover and selected items have the link color, and the disabled state shows a lighter grey.

Utility colors

On developer portals, it’s useful to define utility colors and use them on various elements. Utility colors can give visual feedback emphasizing the element’s meaning and helps the cognitive processing of the information we see.

E.g.:

  • Version numbers, releases,
  • Messages (errors, warnings, updates),
  • API statuses (e.g. prototype, beta, new, in progress, etc.),
  • APP statuses (approved, new, revoked, pending, etc.),
  • HTTP method types (GET, POST, DELETE, PUT, PATCH, OPTIONS, HEAD),
  • Progress bars.



Utility colors on the stylesheet of the developer portal theme by Pronovix.



API status indicator ribbons in the top right corner of the API cards on the ABN-AMRO developer portal.



The API cards have colorful, tag-like API status indicators with their description in the left sidebar on the Deutsche Bank API Program site.



Colors affect human behavior, so choose them carefully: always think about possible meanings:

  • Red is used for errors, potential danger, awareness (e.g. wrong input) If the brand color is red, we suggest choosing a markedly different color or shade as an error color to avoid misunderstanding.
  • Yellow can be used for warnings and notifications.
  • Green is the color of endorsement (e.g. valid input, approved status).
  • Grey is used in neutral cases, on disabled elements or to communicate secondary information.
  • You can use bright brand colors in Call-To-Action sections that you would like to stand out.



Utility colors used as border colors of text fields (developer portal theme by Pronovix).

White space

Although white space is not an exact color, with proper white space usage you can visualize relations, separate / connect sections, or make specific sections more prominent. You can use an additional background color for every second landing page section to make it clear where a section starts and ends. E.g. in tables it is a common practice to choose a different background color for the even and odd rows.

White space is an option. Some alternatives: section the content with divider lines, use box borders or shadows.



Alternating white and light grey background colors for the even and odd sections on Facebook for developers.



Prominent CTA section with harsh background color and button on the ABN-AMRO developer portal.

Accessibility

Accessibility is about more than colors, but you cannot create an accessible devportal without thinking about users with vision impairments.

  • Choose the proper contrast ratio.
  • Focus on the variation between background and foreground colors.
  • Choose colors that will reach the contrast ratio minimums defined in the Web Content Accessibility Guidelines (WCAG) 2.0 standards.
  • Look for Plugins for your designer tools that can help to make your devportal accessible.
  • Use online accessibility checking tools, such as WebAIM.

Resources

If you don’t have a color palette yet, you can find tools and websites that offer aesthetic color combinations here:

With the HEX color tool, you can easily generate lighter or darker shades from a HEX color:

Imagery

Although developer portals are technical sites with a lot of documentation and text, there are plenty of ways to use imagery — you just need to keep a balanced visual-content-functionality ratio. Here are some samples which can improve the look-and-feel of your devportal.

Photos

If we talk about imagery, the first things that usually come to mind are photos. Most companies have an image bank or a smaller stock photo collection. The simplest solution to make the site more appealing is using these aesthetic, brand-friendly photos.



Photo in the Hero section of Telia Developer Portal.



We suggest choosing a theme first and then collecting the images that fit in. Some devportals use IT-related images that clearly refer to the keyword ‘development’: people sitting in front of a computer screen or in a meeting room. In this case, we suggest using images that look natural and not constrained. Other devportals use more playful, not directly work and IT-related images to break the monotony and give the site a fresh, friendly look.



A playful, space related background image used on the 404 page of the Pronovix developer portal product.

Illustrations

You can make your site eye-catching with custom-made or purchased illustrations as well. Their main advantage is that you can easily adjust the colors to the brand color palette. The size of an svg animation is smaller than the size of a png or jpg image. svg animations are therefore perfect for web or mobile use and can be recoloured from code source files. If you prefer unique illustrations, you might think about hiring a proficient designer or professional illustrator with the experience required for the job.



Illustrations on Nordea for Developers.



Check our article: Overall Design Style (Actual design trend) for more illustration samples.



Matching illustrations appear in several sections of the Postman developer portal. They all harmonize with the graphical style of the site and they use the red brand color.



If you are satisfied with premade illustrations, you can purchase packs like these on the Shutterstock site.

Abstract images, patterns

Nowadays, it is also popular for developer portals to use abstract images or patterns. These can be used prominently (in the Hero section) and/or in smaller amounts (in header or page title backgrounds, footer, on cards).



Prominent abstract graphics with micro animation in the Hero section of Shopify developers.



Moderate pattern behind the page title of the ABN-AMRO developer portal.



If you use a pattern as background it needs to be moderate: the textual content should be readable even when the size of the browser window changes.



Patterns used in the Hero section and as the background of the API cards on the Facebook Artificial Intelligence site.



Whichever type of imagery you use, don’t overwhelm your developer portal with graphics. Try to find a harmony in the amount and the arrangement. For example, insert a section with text to follow a section with images or use images on the left and images on the right alternately.



Images on the left side in odd rows and right side in even rows on the Slack API site.

Resources

Useful articles about illustrations:

If you don’t have an image bank or brand image collection, you can find beautiful free or premium images, illustrations and patterns here:

Download:

  • the photos in high resolution,
  • the illustrations and patterns in vector format
    so that they can be modified later.

Typography

Font pairing - Headings and main text

When we create the design of a developer portal —and we are not tied to a strict brand guide— we follow the “keep it simple” rule and use 3 font-families only. One for the headlines, one for the main, body text and one for the code samples.

Dóra Jankai, designer at Pronovix:

Aesthetical font-pairing can highly improve your design. We suggest choosing an easily legible and simple typeface for your main text (e.g. Montserrat, Open Sans, Roboto) and select a noticeable, more special one for your headings. Don't forget, legibility is always the main goal! This method can help to distribute your content and to create a nice visual structure.



The well-chosen Headline, text and link formattings on Rackspace give the site a clean and transparent look.

Codes

For the code text we advise to choose a well-readable code font (e.g. Anonymous pro, Source code pro, Droid sans, Menlo, Consolas) and a prominent background color that stands out from the text. Our goal is to enable developers to scan pages: it is a must to find code snippets quickly. Other solutions that help the visual processing of code snippets are row numbering and a syntax highlighter that colors the code according to syntax, which makes it easier to read and understand it.



Code sample with syntax highlighter in the Stripe docs.



A copy button can help to copy the code easily.



A code block on Twilio Docs that visualizes all our suggestions: it uses a well-chosen font type and a prominent background color, a syntax highlighter, row numberings and an icon with a red tooltip to copy the code to the clipboard.



On Aevi developer the Copy button appears only when we hover over the code part.

Basic typography rules

Consider:

  • Choose a font-family with different weights. It can be beneficial to vary the font-weights to create a hierarchy in the text.
  • Use different font sizes to give structure to the text.
    Use a bigger, bolder font size for titles and headlines, a smaller but easily readable font size for the main text (around 16 px), and a small (12+ px) font size for the less important side information, like metadata, dates, breadcrumbs, etc.
  • A well-chosen line height improves readability,making it easier for the eye to follow the text rows.
  • Avoid long rows and wide sections: they make it harder to find which row comes next.
  • A right contrast ratio between text and text background improves readability.
    The tool Colorable helps to try out how a text color looks on a certain background color.

The following devportal specific suggestions can help to establish a transparent text structure and improve readability:

  • Provide users with the possibility to change the font size when needed (e.g. while reading the documentation).
  • Use different text formatting on content-heavy pages. Style the basic text elements, such as links, lists, quotes, code samples, etc.
  • Avoid typefaces that contain indistinguishable letterforms in code sections that appear frequently, e.g. take care of using the number 1 and capital "i" or number 0 and letter O.
  • Image overlays and text shadows help to make the text more readable when the background is a crowded or colorful.



Colorful overlays over the images in the Pronovix Developer portal product theme.



  • Highlight the keywords in the text on a search results page.


Highlighted keywords in the search results of Worldpay Developers.



  • Add a day and night mode switcher. This allows users to choose between a light or dark background color according to light conditions around them or according to their taste. The dark background will put less strain on the eyes at night, while the light version improves the readability during daytime.



Day and night mode switcher on the Stripe API site.



Day and night mode switcher on the Deutsche Bank API Program devportal.



Resources

If there is no brand font, we suggest choosing a well-readable, free Google font which has at least a Regular and Bold font-weight version and can be used as a web-font. These Google fonts can be easily embedded into your webpage.

An other option is to purchase a unique font and use that:



What is next? In our next article we’ll give some tips that help to improve the developer experience and the usability of your developer portal. How can you make a devportal more transparent and understandable but also friendly and playful at the same time?



Pronovix Logo

Are you building a developer portal? Interested in a shortcut? As a devportal specialist, Pronovix has developed 30+ page templates specifically designed for devportals. Talk with us to learn how our MVP package can accelerate and simplify your devportal launch.

Contact us >



About the author

Gyöngy Gora

Senior Designer

Gyöngy is a Senior Designer. She enjoys working with UX researchers, developers and content writers to find the best visual interpretation of an idea. Although she is passionate about design, she likes to maintain balance between design, functionality and content.

She graduated as a computer program designer and specialized in image processing. This IT background helps her establish an efficient workflow between the design and development phases of projects.

Before entering the company she has worked as a webdesigner and mobile application designer, so she has been working as a designer altogether for 10 years now.