Using this resource
We use this lookbook to document the use and adaptation of the Primer Design System at OpenProject. You will find defined styles, components and patterns in the relevant sections.
About this lookbook
Components
On the left side you see a list of available components. You can click on them for more details such as anatomy, code examples, options and implementation details.
Please note that these the documentation on this LookBook contains components and patterns that are unique to or have been modified for OpenProject, and previews for all Primer available components. However, we do not duplicate documentation for base Primer components; if you want more details on components that do not have specific pages in our LookBook, please refer to the GitHub Primer documentation instead.
If you are looking for a specific object you know by name, you can also use the search bar under Previews to go directly to that component.
Patterns
In the lower left, there is a section called "Patterns". In here, we will document specific decisions and patterns concerning how we approach the use of certain components, or how certain things (like dialogs or flash banners) work in OpenProject.
This includes behaviour and patters that explicitly do not follow the Primer approach, as well as specific UX patterns that are unique to OpenProject.
Icons
Please use the Octicons provided by Primer. You can find a list of all icons here. There is also a preview example on how to use the Octicons in Primer/Beta.
Approach
OpenProject is a complex, powerful tool. One of its key strengths is its customisability and its ability to adapt to a range of different needs. This includes complex filtering options, custom types and statuses, custom fields and a wide range of options to configure views and work package forms.
Nevertheless, it is very important that OpenProject be intuitive for new users who might not necessarily need that complexity, or indeed be overwhelmed by it.
Our design approach aims to strike the right balance between powerful and accessible with a two-tiered approach: apply sane defaults and present the most common options, and allow advanced users the option (via an additional click) to customise and fine-tune.
The UX of Open Source
As an open source project with a considerably long history and a large number of contributors, different parts of OpenProject have evolved at different paces, sometimes with completely different technology. Similar components are sometimes implemented somewhat differently in different parts of the software, and there are even multiple implementations of the same basic design.
This is quite normal for a large open-source project that has not had a dedicated design team for most of its conception.
One of the goals of the design system is to introduce more coherence and introduce a more modern design language. Whilst we would naturally prefer to be able to update everything at the same time and push the new design system to the entire software, we recognise the need for a more pragmatic approach. The design system will be rolled out in phases, with a careful study of the consequences of updating each component or pattern, and the potential dependencies that will be affected.
We recognise that UI/UX has not always been the highest priority for open-source projects. This is somewhat understandable given how open source projects have relatively fewer design resources dedicated to it than commercial products. Our goal is to do our part to improve that situation as much as we can and document our process.