This guideline will give comprehensive insights on how to develop a consistent, user friendly and accessible new openIMIS frontend module.
Content
01 Introduction to OpenIMIS’s Design
The following section will give you a short overview of the as-is situation of openIMIS’s user experience (UX) and user interface (UI). Therefore, we will introduce you to the current situation of openIMIS’s frontend, the found potentials and problems as well as the objectives of having this Design Guideline in place.
Current Situation (Release 2024-10):
Based on the Project Student Project 2024 UI/UX the UI and UX of openIMIS were evaluated. The approach included three different methods to collect information about the usability of the software. The first method which was applied was a user survey to get direct, anonymous feedback on the overall frontend. Secondly, a usability testing phase was done, including three attendees. Lastly, the current state of the UI/UX were checked against standardized heuristics.
The outcome of the evaluation can be found here: 02 Potentials & Problems.
As a result of the analysis it can be said, that openIMIS does already implement several design elements to enhance the user experience. With a moreover consistent UI and “Material Design” as a baseline framework, it isn’t mandatory to completely implement a new design strategy. That’s why the following design guideline will help developers to implement new frontend modules, still based on the current openIMIS design-
Potentials and Problems:
As mentioned in the section before, potentials and problems were found during the analysis. All possible enhancements were documented (List of findings). All findings were checked against an evidence or observation. Lastly, recommendations to solve those problems were invented and documented as well.
Objectives:
The following Guideline will have the objectives mentioned below:
Ensure a consistent UX/UI of openIMIS
Introduce the design principles of the software to new developers
Providing information to develop new frontend modules
Enhance accessibility and efficiency of the openIMIS platform
02 General principles
The general principle section will introduce concepts and frameworks which should be used overall in openIMIS UI, whether you create a new module or just change the existing components.
Material Design Framework:
The openIMIS frontend uses Googles “Material Design” design system as backbone. Therefore, it is useful to go through their official documentary to get familiar with the concepts. As the detailed documentation includes all needed information, this guideline will not provide any deep-dive into the system. You can find the documents at https://m3.material.io/.
User-Centered-Design (UCD):
By applying UCD to the development process it enhances the acceptance of an application as well as minimizes the amount of needed UI/UX changes after the release. Implementing UCD means to involve the user at a early development stage already, to discuss for example about the page navigation or needed controls. Thats why, including a design review into the development of a new frontend module with a current openIMIS user would be useful!
To dive deeper into user-centered-design you can find a comprehensive article here:
https://usabilitygeek.com/user-centered-design-introduction/#:~:text=User%2Dcentred%20design%20(UCD),user%27s%20requirements%2C%20objectives%20and%20feedback.
Usability best-practices:
Getting familiar with usability is crucial to develop a user friendly interface. As the subject includes several areas and a lot of topics to cover, it is good to know the basics. Thats why getting familiar with the basic heuristics is recommended. One possible source can be the 10 UX Heuristics by Nielsen https://www.nngroup.com/articles/ten-usability-heuristics/. Those cover topics like consistency, visibility, user controls or error prevention.
Responsive Web Design:
As the amount of different devices and therefore screen ratios varies between the users of openIMIS the layout of the application should comply with responsive design. Hence, all implemented components should scale in a way, that they still provide an acceptable user experience (no overlapping of components, readable labels and font size, etc.)
If you want to know more about “Responsive Web Design” then look at the following article. You will find a introduction into the topic as well as some solution concepts in HTML and CSS.
https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Responsive_Design
03 Branding overview
The openIMIS initiative already established a corporate identity which introduces colors, fonts, logos, icons and texts. Hence, taking a closer look at the following documentations is really helpful to develop frontend components. Most of the already developed UI-Components will already include the colors and icons, but if you want to introduce a new one, you should check, whether a suitable icon exists or which colors to use.
OpenIMIS Colors & Logos | |
OpenIMIS Icons |
You can find all existing documentation to the branding of OpenIMIS here: https://openimis.atlassian.net/wiki/x/BwCrCw
04 Navigation Guide
Navigation between different screens inside the application is a core part of the user experience. The following principles set a baseline for a consistent and intuitive user experience across OpenIMIS.
The navigation system overall should rather be build more broad then going into depth. Means, it is better for users to have many menu items on one navigation level rather then building a structure where they have to drill-down into several levels. To provide an overview of the navigation system you can take a look at the following navigation model.
Navigation Model
The model includes several Screens, Triggers and Actions. All those will be described in the sections below. It is based on Material Design best-practices. With a depth of three levels and also just 4 different screens it provides a easy understandable but also comprehensive approach to build a consistent, user-friendly navigation. As the user does not need to recognize all the time, how to open the list of entries or how to add one, it will make it easier to navigate through the app.
The developed navigation model is shown below:
Within the shown model it is possible to add another navigation level. As some entities (e.g. policy holders) do have direct related entities (e.g. policy holder insurees) it is possible to add a List Screen to an existing Detail Screen. This would result in the following navigation path:
Home Screen
→ List Screen (e.g. Policy Holders)
→ Detail Screen (e.g. one Policy Holder)
→ List Screen (e.g. Policy Holder Insurees)
→ Detail Screen (e.g. Insuree)
Screens and Menus
For OpenIMIS the following navigation principles and components should be used:
Home Screen
This screen is always the first one to show after entering the application (after the login). It does provide the user as a starting point into the different menus. From here is it crucial, that already a lot of menu items are available, in best case grouped into logical segments. The Home Screen as described is already a core component of OpenIMIS and is used as the starting point of the application.
Besides the menu items, the Home Screen should also provide a search component to give the user the chance to navigate to List Screen alternatively. The search should not redirect the user to the Detail Screen.
The above described tasks of the Home Screen also include that other operations (like Add, Update, Delete) should not be accessible directly. Therefore, the user should be redirected to the foreseen screen. The following overview will describe what the do’s and dont’s for the development of the Home Screen are.
Do:
Add many menu items on the this level to reduce deep levels of navigation
Provide a search to the users with that they can navigate into a List Screen directly by searching an entry
Dont:
Add possibilities for the users to directly jump into the Detail Screen
List Screen
On the second navigation layer we use lists to show the users multiple entries to a specific entity/topic. Therefore, the screen includes two main components, first the search query grid and secondly the list of entries. At this screen the users will have the most possible control over an entry. They could: add a new one, delete an existing one, select one or multiple ones as well as show one in detail (redirect to Detail Page).
Add new entry:
To add a new entry to the list the user has the the possibility to click on the existing “Add-Button”. If no added context (e.g. Family for Insuree) is needed, then the user gets redirected to the empty Detail Page to insert the needed data for creating an entry.
If more context is needed to add an entry, the user will get prompted a modal/pop-up requesting for the additional information before redirecting to the needed Detail Page.
Delete existing entry:
To delete an existing entry the user needs to click onto the trash-bin icon in the designated data row. Afterwards it needs to be confirmed or rejected, through the Context Screen, whether the user really wants to delete the entry. The deletion does not lead the user onto another screen!
Show entry:
If a user wants to know more about one entry in the list, they can click anywhere in the data row to get redirected to the Detail Screen. There they will have the opportunity to check all the related data elements as well as to update them if needed.
Select entry:
A list entry should always have a selection property like a checkbox in the beginning. With a click, the user should be possible to select the entry. By selecting one or more of the entries the user will have the choice to use one operation (e.g. delete) for all of them.
Do:
Always use the existing “Add” Button to trigger the “add” action.
Redirect the user to the Detail Screen by clicking once on the data row.
Add operations for multiple rows if a selection is possible
Dont:
Add your own or a second “Add” Button on the List Screen
Delete any entry without letting the user confirm if they are sure to delete it.
Let the user add needed additional context into the search query rather than showing a modal/pop-up
Detail Screen
The aim of the detail screen is to provide the user with all information OpenIMIS has about the entry. As the Detailed page can be used in two operations (read or add) it is useful to show the user rather they just read the displayed data or if they are about to add new values. If the user are reading an existing entry, they should be able to update the shown information. After changing a data field the Detailed Screen will show a “Save” Button which saves the current changes from the user into the database. Same will happen if the user is about to add a new entry. For both operations the same “Save” Button will be used.
As this screen will be in most cases the lowest level of navigation, it will only be possible to go back into the List Screen or use the OpenIMIS Logo to directly jump onto the Home Screen.
After saving a change the user should directly get redirected to the List Screen to show that the new entry is now in the list of them.
Another possibility will be that another List Screen will be shown in the Detail Screen. That can happen if an Entity is directly related. This will be shown to the user as in the screenshot below:
The “Add” Button in this navigation layer should also look the same as in the List Screen which is not embedded into a Detail Screen. It also should appear at the same location.
Do:
Show the user if they add a new entry or read/update a existing one
Redirect the user after saving a change to the List Screen
Dont:
Refresh the page without prompting the user if they want to leave the screen or not
Insert more “Add” Buttons in different places which are not known by the users.
Context Screen
Lastly the Context Screen is used as a add-on component to the navigation system. Therefore, its only used in two cases. First, if a user deletes an entry in the List Screen. Secondly, if a user adds a new entry into the list which needs additional context. For example, if a new policy shall be created from the “Policy” List Screen. An user needs to add the information for which “Family/Group” the Policy shall be created. The Context Screen would therefore prompt the user a search component inside a Modal/Pop-Up to select the wanted Family/Group.
The Context Screen will look like the following example and only be shown on top of the actual Screen:
Do:
Give the user the possibility to cancel the current action
Use informative header titles where the user knows what kind of action they are about to do.
Dont:
Put all data fields into the Screen. It should only provide the needed additional information, nothing more.
05 UI-Component Guide
OpenIMIS uses several Material UI components which are customized to a certain level. The components are available in the frontend core module of OpenIMIS (https://github.com/openimis/openimis-fe-core_js/tree/main). As they all are based on MUI it is recommended to go through the official documentation and to learn how to use them. You can find the description here: https://m3.material.io/components.
To maximize the user experience as well as to make the user interface more accessible the following recommendation will help you to develop new OpenIMIS frontend modules.
Lists
List components are heavily used in the frontend of OpenIMIS. As the navigation model suggest, every second level navigation layer of OpenIMIS should be a List Screen. Thats why the list component should have a consistent and easy to consume layout.
The following rules should be considered using the list component:
List components do always come with a search component. Using the search, the user will find the needed element much faster as the list could include hundreds of entries .
Lists should be sorted straight as they were rendered. Its recommended to sort them per default in an order that the newest created or modified entry is shown on top. As many users go through the list after they added a new entry to check, whether it was created successfully it would be best for them to see, that the element is shown right on top.
Lists should have a checkbox at the beginning of the row. This will allow the users to select single or multiple entries and gives them a visual feedback, whether a row is selected or not. Using a checkbox will comply to the standard as lists usually include them, also in other applications.
Lists should only contains buttons and the checkbox as input components. Text inputs, Selections and other components should not be used in list entries. Therefore, all list attributes should be shown as labels. Otherwise the user will be confused why its not possible to interact with them.
If a list item includes buttons then they should all be placed together at the end of the row. This will help the user to see that all these icons are buttons to click and trigger any action.
By selecting a list item with a single mouse click or by hitting “enter” on the keyboard, the selected entry should be opened in the Detailed Screen. Users will benefit as this the standard behavior for list items. They therefore do not need to learn a new concept.
More specific details about list components can be found here: https://m3.material.io/components/lists/overview
Search
Search components do always come with a list in OpenIMIS. Furthermore, they can be used without them to find a specific information. The typical search component from Material UI is a single search bar which is capable to search for any kind of information. Inside OpenIMIS its more common to have a search which includes multiple input fields to make the search more specific. Hence, the official documentation is only helpful if you want to use a single search bar: https://m3.material.io/components/search/guidelines.
The following rules should be considered using the search component:
Search component should always be shown on top of the screen. This enhances the user experience as they are able to filter the shown information directly to get faster to the needed entries.
The Search should not have pre-selected filters. Or if any filter value is already defined then it should be highlighted to make the users aware of.
If a search grid does have multiple fields to enter different criteria, it is recommended to show a “light” and an “advanced” form. The light search should only include fields which are used most often. On the other hand, the advanced form should include all possible criteria if the users need to find a specific entry by using multiple filters. With that approach it will be easier for the user to use the search grid as its not to complex and easy to consume. Also the search will not use half of the screen size which supports the users to scroll less on the shown content.
Search components should not include read-only values. This will not help the users as they cannot change anything about it and they wont have any other benefit out of it.
The query should be executed either by clicking on the “search” button or by hitting the “enter” key on the keyboard. The search button should be highlighted and easy to find for the users.
Inside a search component should no field be populated which does not act as a filter input. If additional context for an action is needed, then it should be used inside a Context Screen.
Text Input
The Text Input is one of the most used components which needs to be used in every screen. As all users interact a lot with this component it should work always the same way and have also the standard behavior known from other application.
The following rules should be considered using the text input component:
If a label text is included in a text input it should be short and informative rather then long and with a uncertainty in the meaning.
If the text input requires a specific syntax then the placeholder label should already show an example of the expected values.
Extending the previous rule, text input fields should always have a validation which checks the input against the expected syntax. Using validation increases the data quality and helps to avoid errors during the processing of the data. (e.g. if the API expects a specific syntax or data type).
More specific details about text input component can be found here: https://m3.material.io/components/text-fields/guidelines
Buttons
Placing buttons inside a screen is always a difficult procedure. As the user expects certain behaviors over all screens it is mandatory to follow standards and best practices. The most important action on a screen should always be triggered by the most highlighted button. Therefore Material UI introduces the “Floating action button” (https://m3.material.io/components/floating-action-button/overview). This button is also used in OpenIMIS to add entries or save changes.
The following rules should be considered using the buttons:
On a screen should always only one “Floating action button” be shown. This button should trigger the “main” action of the actual screen (e.g. Add or Save).
Buttons should include icons which have a clear definition to make it easy for the users to recognize what action will be triggered.
If a screen needs to have multiple primary buttons than show one bigger then the others and always bring them together (most likely on the bottom right of the screen).
Buttons always should show a label if you hover over them. The label should explain the action of an button.
To make buttons better visible use a different background as the application. Also show the user the area they can select. Differentiate between links and buttons. Links will only redirect you while buttons will trigger an action. Links usually should have any kind of visible information that they will redirect you somewhere.
More specific details about Buttons can be found here: https://m3.material.io/components/all-buttons
Notifications
After users save any change they did on a entry OpenIMIS should reply with an notification. Additionally, the best case would be, that the user is always notified if any state changes while using the application. Therefore, it is mandatory to show appropriate text messages to the users. The newest version of Material UI uses so called “Snackbars” to implement notifications https://m3.material.io/components/snackbar/guidelines. Inside OpenIMIS it is implemented through a notification bar which shows a tick or a exclamation mark after a change was saved.
The following rules should be considered using the notifications:
The notification should indicate through color or icons whether a change was successful or failed.
Any shown notification should include easy to consume messages which will inform the user what the system did after saving a change.
Best case would be, that a notifications have a selectable link, which redirects the user to the Detail Screen. Implementing that behavior would help the user to navigate fast and without searching to their latest changes. In case a change failed, it would be recommended to pre-fill all input fields with the bevor entered data. Then the user do not need to re-enter all information.
Date Pickers
As a lot of needed date inside OpenIMIS
06 Accessibility Guide
As OpenIMIS should be easy to use for all people, it is recommended to implement standardized accessibility principles. W3C mentions why it should bother us developers to include accessibility features and functions into the application.
“Accessibility is essential for developers and organizations that want to create high-quality websites and web tools, and not exclude people from using their products and services.” - W3C
The topic itself combines a lot of strategies, technologies as well as processes. As already discussed in “user-centered-design” (https://openimis.atlassian.net/wiki/spaces/OP/pages/4141252716/OpenIMIS+Design+guidelines#02-General-principles) it is mandatory to add a requirements gathering and accessibility review step into the actual development process. Users should have the opportunity to participate early in the development of the module. Together it will be possible to engineer needed, user-friendly and accessible features for the frontend of OpenIMIS.
Since the World Wide Web Consortium (W3C) published a comprehensive guideline about the development of accessible software, this guide will only introduce some concepts which can easily be applied with not to much effort. The whole guide can be found here: https://www.w3.org/TR/WCAG22/
Color & Contrast
The WCAG guideline introduces a topic about color and contrasts. To make most of the texts visible on a colorful background it is recommended to use at least a 3:1 contrast or even higher. This will make it more readable for all users. https://www.w3.org/TR/WCAG22/#contrast-minimum
Tool Tips
Using tool tips provides the opportunity to display additional information to the users. It could be used in situations where specific language is needed or related icons not clearly communicate the underlying action/information. But be aware, tool tips need to have the correct process when hovering over an element, they should also not disturb the user. A more comprehensive view about the management of content displayed after hovering over an element can be found here https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html
Language
Web applications should provide content which is understandable. Therefore, it is recommended to use terms and descriptions which comply to the real-world. Check menu items, input labels, error messages and user information whether they are understandable and easy to consume.
Also use abbreviations whenever possible. Lastly, you should try to avoid using language and characters that don't get read out clearly by the screen reader. Check out Mozilla - Accessibility Text content.
Keyboard controls
To make the application available for people who are only able to use the keyboard it is recommended to check whether all components can be reached without using a computer mouse. Better than this is also to implement standardized keyboard actions like ctrl+z to revoke a action. https://www.w3.org/TR/WCAG22/#keyboard-accessible