In our Developer Portal 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, and 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 developer portal specific advice instead, and give related examples.

The article series will cover the following topics:

  1. Developer portals on different devices; responsiveness.
  2. Common devportal layouts: advantages, disadvantages. Navigation solutions and suggestions regarding layout.
  3. Actual devportal design trends; brand consistency. The balance between aesthetics, content, and functionality.
  4. Basic graphical elements that support functionality, like icons, colors, imagery, and typography.
  5. Other visual solutions to improve the user experience: animation, onboarding, process and data visualization, and social media elements.

Part 1: Responsiveness

FAQ

  • Should my developer portal be optimized for mobile devices?
  • Should we have a separate design for mobile devices or one design that works responsively on every screen resolution?

Experience and advice

Desktop and tablet

In case of developer portals, mobiles are mostly used for browsing, reading documentation or watching tutorials. Most portals are optimized for desktop and tablet, which means that they look and work the best on these devices. When you are working with code it is handier to use a display, keyboard and a mouse than tapping a small screen, so it is not surprising that for developers the first choice of tool is a desktop computer: they can copy the code snippets or try them out instantly.

Internal portals - which make up a huge part of all developer portals - can usually be reached only from the secure network of the company. This again implies that users mostly work on their usual workplaces and the work device is mainly a desktop.

The Zero Gravity Developer Portal Theme by Pronovix on various devices

Usability

Despite all this, we should always consider users working on a touchscreen. Every interactive graphical element should be tappable and not just clickable. We suggest using at least 44px x 44 px sized interactive elements throughout the portal consistently because this is the minimal size that is easily tappable with 1 finger. Also, thinking about readability and visibility, the body texts should be around 15px and the images optimized for retina screens to obtain a good user experience. But let’s talk about these later.

Suggested minimum size for interactive elements.

Responsive, dynamic layout

Regarding the structure of the developer portal, we suggest using a responsive, dynamic layout, where the components rearrange themselves and adapt to the different screen resolutions, filling in all the space. These fluid layouts look great on every device and browser.

The dynamic layout allows a highly flexible display of the content. It helps to deal with the different content lengths/amounts and provides an opportunity to easily add more content, such as:

  • textual content (e.g. blog posts or API releases),
  • elements (e.g. images, tables, code snippets),
  • sections (e.g. a CTA section),
  • boxes, cards (e.g. more API cards),
  • pages (e.g. a new API summary or a documentation page).

Layers of a developer portal on desktop. On smaller devices, the background image, the overlay and the menu bar stay the same full-width and spread across the whole page width (however, we use a hamburger menu instead of the menu texts) but the 3 content boxes with the icons drop under each other.



Responsiveness of the ABN-AMRO developer portal built in Drupal 7 by Pronovix. (Best Website of the Year, Dutch Splash Awards 2018 and First prize in the Corporate Category, European Splash Awards 2018).



Responsiveness of the PayPal developer portal.

Page Builder Kit

Visual page builders in a CMS (for Drupal: Paragraphs, Layout Builder, for Wordpress: Divi, Visual Composer page builder, etc.) also help you to reach the desired look of a certain page and create a responsive layout. You don’t even need programming skills, just add the predefined page sections and elements, and adjust their appearance. If set properly, the portal will be responsive and look good on different screen resolutions. In some page builders you can even set how a section should behave and look like on various devices.

With a visual page builder you can usually:

  • Change the appearance of the sections.
  • Change section order.
  • Add new sections.
  • Temporarily hide sections.
  • Delete sections or cards.
  • Duplicate sections.
  • Change the splitting of sections (e.g. use 2 cards instead of 3).

Rearranged landing page layout using the Page Builder Kit.

Mobile version

When we use a responsive, dynamic layout, the mobile version will look similar to the desktop one, but the content, the different boxes and sections will be rearranged. When the screen width passes a breakpoint, they drop under one another.

However, there are solutions that we need to re-think completely. For example, the look and usage of the header, menu bar and the sidebar navigation (if there is a sidebar menu) should be totally different on mobile.

Because of the lack of space, we suggest creating a unique header for mobile, where the menu points are combined and appear inside a hamburger menu dropdown. We often use meaningful icons on the mobile version instead of the longer texts and big buttons (e.g. login, logout, profile, search) to spare space.

Some examples on great solutions:

Changes in the header bar and Search solution on the Instagram Platform site. The menu is replaced with a hamburger menu on mobile.



Changes in the header bar and Search solution on the Collinson site. On mobile the position of the logo changes the menu texts are replaced by a hamburger menu. Note the great solution for the placement of the search bar.



Menu and Search solution on Spotify for Developers. On mobile the menu texts are replaced by a hamburger menu and a similar search solution.



Icons in the mobile header bar instead of longer texts on Square Developer.



The sidebar also needs modifications because on mobile we can’t use a 2 (or more) column layout. In most cases, the mobile version of the sidebar navigation can look almost the same as the desktop version but it should work differently. For example, it can be hidden by default and opened up by clicking on an icon.

On desktop the portal has a fixed sidebar on the left. But an openable-closable sidebar slides in from the left side on smaller devices on Material Design portal.



Sidebar menu relocated over the content on smaller devices on the ABN-AMRO developer portal (Best Website of the Year, Dutch Splash Awards 2018 and First prize in the Corporate Category, European Splash Awards 2018).



Stripe uses a select dropdown field instead of the sidebar navigation on mobile.



The mobile version of large, multi-column tables and the swagger UI can also be improved as the whole data table won’t fit into the small screen width. The easiest solution is to keep the data table as it is and use swipe gestures to scroll through the table horizontally or simply just shorten the table.

You can read about other solutions for responsive data tables in this article.

If there is no mobile support at all (e.g. in case of internal developer portals), don’t forget to make a page that informs the users about this.

We hope that this article post provided you with useful thoughts and samples about the behavior of developer portal interfaces on different devices and explained why we prefer a fluid, flexible layout.

What comes next? In the upcoming article, we will dive deeper into the structure of developer portals: we will show examples for 3-column and centered layouts, and talk about navigation solutions and common industry patterns regarding developer portal page types.

If you have questions or would like to work with us, 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.