New Human Interface Guidelines

Today I’d like to share a new set of Human Interface Guidelines (HIG) for KDE’s software that I’ve written, replacing the old one. This work was done over the past several months in consultation with many KDE designers and developers; the merge request says 42 people were CCd, and almost 500 comments were posted during the 2+ month review process.

You can read the document at https://develop.kde.org/hig.

Wait, why does anyone need this at all?

Strictly speaking, we don’t need a HIG. Developers with an excellent eye for design can usually produce good results even without one. But for most of us, it’s useful to have guidelines to follow so you don’t have to think about the design side too much. Even for design-oriented developers, it’s useful to be able to have a quick reference for common patterns and rules.

And having a HIG is a good idea for any organization that wants for its software to share a similar look-and-feel and mode of operation, or any small individual developer who wants their software to match fit in well with a specific target platform (ours, in this case). When software fits into the visual and functional conventions of the platform with which it wants to integrate most closely, people already familiar with that platform learn to use it faster and like using it more. It feels at home to them. Comfortable, familiar, appealing.

Having and following a HIG makes all of this possible. And besides, we already had one anyway! But it needed major work.

Ok, so what was wrong with the old one?

To be honest, it wasn’t very good. I say this as a contributor to the old one! But it suffered from multiple problems that demanded a total rewrite:

• It was hard to find anything because the basic structure was confused, with excessive segmentation.
• Content was severely outdated and reflected design paradigms that KDE developers haven’t used in years, and that the industry in general has moved away from. It was also missing a lot of information relevant to how we write apps today.
• Far too wordy; hard to find the actionable recommendations amid all the filler text!
• Full of old mockups and screenshots that weren’t even needed to illustrate the point, and which would become out of date again quickly if we took the time to update them.
• Many basic style errors: misspellings, incorrect English grammar, awkwardly phrased sentences, etc.

For these reasons, very few KDE developers or designers still paid any attention to the old HIG, besides of a small number of pages that did still have a reasonably high threshold of information density. And for the same reason, the HIG got very few contributions. I think when something is in a sufficiently poor state, it can even discourage people from contributing, because any small improvement seems like a raindrop in the ocean of urgent need. It’s demoralizing.

How is this new one any better?

The new one was informed by research into how KDE apps look and work today. Some inspiration for structure and organization was taken from the ElementaryOS, GNOME, Apple, and Google HIGs — but not content! The content is all KDE.

The new HIG had the following design goals:

• Make 100% of the content actionable. No filler text, no rambling philosophy, no redundancy — just actionable recommendations for how to design your app. Short and sweet, and to the point!
• Reflect how KDE designs software today. For example we’ve seen a huge growth in new Kirigami-based apps using QtQuick as their UI technology (including some older KDE apps getting their UIs ported to Kirigami), and Kirigami is the UI platform that’s improving most quickly in KDE. So I made the decision to focus the recommendations on Kirigami as a platform. There’s still some content about QtWidgets, but it’s a Kirigami-focused document.
• Have flat navigation, so it’s easy to find everything. No deeply nested sub-pages and awkward categorization that makes you wonder why a page is in this category and not that one.
• Get the new content into good enough shape that people feel comfortable contributing. Hopefully people will start to submit tweaks, improvements, bug-fixes, and maintenance!

Is it 100% finished?

No, absolutely not! The HIG is intended to be a living document that evolves over time to better describe KDE’s design goals and software development paradigms.

Like any rewrite, there are bound to be rough edges and omissions compared to the old version. Maybe I missed a piece of useful information in the old HIG that had been buried somewhere but retained some value. Maybe there’s low-hanging fruit for improvement. Help out by contributing! It’s just some text with markdown styling; contributing to the HIG is waaaaaaay easier then contributing code.

In particular, there are some known omissions and limitations that you can help with:

• It needs more images. Multiple pages have embedded TODO comments where it would be nice to add a relevant image to illustrate a point.
• There’s nothing at all about visual style in general, simply delegating those decisions to the system’s active theme. To a certain extent this is intentional because we support visual theming, but it would also be good to add content about KDE’s default Breeze theme. I deliberately omitted this for now because a bunch of KDE’s designers are working on a fancy new style, and developers are working on a whole new theming engine to apply it. So the world around the HIG is in a state of flux. But if anyone wanted to add more about the current Breeze style anyway, that would be nice. Just know that it may be replaced once the new style is released.
• …With one exception: the entire section on Breeze icon design. This was kept from the old HIG content because it remains useful. Still, the presentation could use an overhaul to improve information density and collapse needless sub-pages into one parent page.
• The recommendation to use Kirigami is awkward for powerful apps that use features not currently available in Kirigami-based apps, such as dockable sidebars/panes, customizable toolbars, customizable keyboard shortcuts, and more. If you’re a developer, help add these features!

Ok cool, how do I contribute?

That’s great, it’s super duper appreciated! See these two links to learn how to contribute changes:

• https://develop.kde.org/hig/#contributing
• https://invent.kde.org/documentation/develop-kde-org/-/blob/master/README.md

If that’s too scary, we can help you get set up! Contact folks and we’ll see what we can do.

Still too scary? Then you can donate to KDE. Our budget is tiny, so your money genuinely does have an impact!