User Interface Specification

This document is under development, and might not completely fit into the functional specification category.

*NOTE:* All features are in priority order, but the categories or work are not prioritized.


User interfaces are often judged on consistency, as a lack of consistency can indicate un-maintainable code and become problematic for users. Maintaining consistency requires coordination between business requirements and the development team. "Broken window theory" encourages prioritizing fixing inconsistency, as it will discourage additional inconsistent work. 



Button text and colors through the OpenLMIS-UI are inconsistent. 

Most buttons on the openlmis-ui should be a simple gray, but we have many instances where there are too many "primary" (blue) buttons.


Icons can create visual inconsistencies very easily, and should be avoided in the OpenLMIS-UI as much as possible.

When icons are need, they must be added in an extendable way so the icon can be universally changed though the entire UI by an implementer quickly, or removed entirely.

Better integrate and socialize OpenLMIS-UI Styleguide into design and development processes

A reason that inconsistencies come up is because the OpenLMIS styleguide is hidden away and needs simplification to be useful for business analysis, not frontend developers. The first step in this process is getting design and workflow agreement in our prototyping tools, and then moving that language into the OpenLMIS-UI Styleguide.


Current performance issues are badly understood and are not consistently detected by manual testing. The best way to improve performance is by adding automated tests to understand which areas need improvement, and then use those same tests to ensure that the work done to improve those areas is actually improving performance.


Automated Memory Tracking

By tracking memory usage for a browser while using the OpenLMIS-UI application, we can:

  • Detect memory leaks while tickets are in development
  • Determine the root cause of performance drops more quickly
  • Create baselines for memory consumption, which can be strategically improved

NOTE: This work could be done in manual testing, but automation makes long term tracking and "human variabilities" out of the problem.

Automated Crash Reports

Currently the OpenLMIS-UI hardly uses google analytics. Getting data from the client to detect error situations in production will help detect and determine the cause of bad performance on a system level.

Minimizing File Downloads

Many of the large libraries that are used within the OpenLMIS-UI can either be avoided or built "modularly" such that only the features we use are included. By making the OpenLMIS filesize smaller, we will increase download and start-up time of the OpenLMIS-UI.

Webpack code-splitting and lazy load

The OpenLMIS-UI code base will bloat as more features and logic are added, and it doesn't make sense for a user to wait for files to download that they might never use. Lazy-loading is a term that refers to loading the application logic that a user needs only when they actually need it. Lazy-loading will make the OpenLMIS-UI load faster.

The best way to implement this is with webpack. Other libraries are able to manage code-splitting, but they often create more configuration work which becomes unmaintainable as the application continues to grow.


Creating easy and intuitive experiences for people who use software is difficult, but extremely important to building a platform that will actually be used. The following features either look to make specific changes or help understand what would make logistics management "easy and intuitive".


Error finding component

Many forms in OpenLMIS are multiple pages, and users have trouble finding an error if the input element isn't on a visible part of the page. To make fixing errors easier for users, we can add a control to guide users to the next visible error.

OLMIS-3792 - Getting issue details... STATUS

Responsive Layout

Currently the OpenLMIS-UI is built for two browser screen sizes, but the layout becomes problematic (and ugly) when the screen size gets much larger or smaller.

Responsive layouts generally include mobile layouts, and most developers approach a responsive layout using a mobile first design. The design approach for our responsive layout will follow a "Desktop first" design process, as the design of OpenLMIS workflows focused around data entry that wouldn't translate well to a mobile device.

  • Tablet  layout (800px wide)
  • Large layout (1,800px+ wide)

Sort order is documented

For users, being able to understand how a large list is sorted makes  navigating that list (ie not searching/filtering) possible.

OLMIS-2661 - Getting issue details... STATUS

In-App Documentation

Creating and maintaining user documentation in a separate workflow than application development an expensive and error prone process. In-App Documentation is useful because:

  • Creating and updating documentation is cheaper when a feature is developed
  • Most user documentation is used infrequently and has a tendency to be lost – if the documentation is built in, it can't be lost
  • Low-literacy or infrequent users are aided by documentation or usage hints being included in the application
  • Users who know the program well have a tendency to not notice documentation or instructional text
OLMIS-3391 - Getting issue details... STATUS

Usability Values Documentation

Creating workflows that are 'easy,' 'simple,' or 'intuitive' is extremely difficult because there is no specific guidance for what a user would find 'useful'. The OpenLMIS community should develop consensus around values that promote usability.  

User Research

Without user research there isn't information that can be used to make value based decisions about how to structure workflows or form elements for users. The user research process is also not a feature that can be done once, iterative testing and re-testing is necessary. Ideally, this body of work includes capacity building within the OpenLMIS community to carry-out research and present actionable outcomes.

User research would help answer the following questions:

  • What information is needed to make managerial decisions about public health logistics?
  • Does the UI work well for data entry?
  • Where are new features or integrations that would be useful for logistics management?

Reusable Business Logic

Reuseable code is maintainable and well documented code. Supporting a reusable code base is a good practice.


UI Architecture v7

Add better structures to UI logic, and start using them in new application code. This will add support for ES6 and webpack.

Read about the architecture documentation here.

OLMIS-3390 - Getting issue details... STATUS

Update UI Coding Conventions

The OpenLMIS-UI has a long coding conventions document, that needs to be updated for the v7 architecture, but also needs to be shortened as its too long to be useful.

Update existing UI logic to use UI Architecture v7

As there is time available, existing OpenLMIS-UI modules built before the v7 architecture was designed need to be incrementally updated. This work can proceed slowly, as removing AngularJS support is not a priority.

Move openlmis-ui modules to NPM

Its all Javascript, it should live in NPM. Publishing in a public repository will allow other developers to reuse our application code in ways we can't expect.

Remove AngularJS specific mark-up from HTML files

UI Architecture v7 doesn't include updating or changing logic within HTML files, as there is less value in making our HTML reusable than creating a framework for reusable business logic.

HTML is useful for simple configuration of design, and is generally treated as an item that doesn't need specific unit tests. Unfortunately, the OpenLMIS-UI incorperates some complex UI logic within the HTML; which is enabled by AngularJS.

Removing AngularJS mark-up from forms, and using standardized HTML5 syntax will make sections of our code easier to maintain. Additionally, if the HTML is standard, we will be able to use linters to enforce code quality in development which further increases maintainability.

Remove AngularJS Completely

AngularJS is going to stop being supported by Google at an unknown point in the future, and while AngularJS still adds lots of value to the OpenLMIS-UI, there will be a time when the library will need to be removed and a replacement for the core features that the OpenLMIS-UI uses will need to be replaced.

Extention and Branding

The OpenLMIS-UI needs to support implementers being able to change the presentation and business logic that is provided by the OpenLMIS-UI. A simple example of this would be changing brand colors and logos, while more complex extensions could be changing the scrolling direction of a single page or adding additional validation to a form.


OpenLMIS Branding as a module

During the Malawi implementation of OpenLMIS, there was confusion about how to brand OpenLMIS to meet Malawi's requirements. This was caused primarily by the simplicity of changing fonts, colors, and icons within the OpenLMIS-UI application - all you need to do is set a variable or add a little CSS. To make sure these changes were still available, there were discussion of adding unit tests - but these approaches were more complicated and brittle than the actual implementation or customization.

A more maintainable way of supporting and documenting these customizations is to seperate OpenLMIS's own branding into a forkable library. This will force the core openlmis team to dogfood their own branding system, and force a seperation of content and presentation for developers contributing to OpenLMIS.

  • OLMIS-1804 - Getting issue details... STATUS
  • Move openlmis specific assests into openlmis-ui-branding repository
  • Remove OpenLMIS logo from ui-components
  • Remove login branding image
  • Remove homepage

Extension Documentation

The OpenLMIS-UI is very extendable, but meaningful documentation and code samples don't exist. Creating code samples and documentation will help prove to implementers and funders that the OpenLMIS-UI is extendable.

The v7 Architecture is designed to allow more grainular extension than what was available with AngularJS. The documentation for these methods needs to be clear and well documented. Ideally additional work in OpenLMIS-UI will use existing extension stragedgies.

Features Under Discussion

The following are features that could be built into the OpenLMIS-UI, but don't support a specific area and need to be broken down before work is started.


Progressive Web Application

Two of the major web browsers (Chrome and Edge) and many web developers have started to build progressive web applications as an alternative to building native mobile or desktop applications. The reason for this switch 

Native Mobile Application

Using application frameworks like Cordova or React Native, its possible to build applications that act like native applications, but use the same logic and design as the OpenLMIS-UI. This saves lots of development and maintenance cost.

Native Desktop Application

ElectronJS enables web applications to act like a native application.

Peer-to-peer document sync

The OpenLMIS-UI could either have a small companion application or independently network with other OpenLMIS-UI instances on the same local network, so that multiple users can work on the same documents in real time without an internet connection.

There are issues with version control that could become problematic.

OpenLMIS: the global initiative for powerful LMIS software