User Interface Design Style Guide - The Beginnings

Hi everyone!

I’d like to start a thread to discuss an idea that I have for maintaining consistent UIs throughout future feature development within OpenEMR. In this post, I will propose the ideas for a Design System and outline the steps I will be taking to document the “current state” of the OpenEMR UI and how we might be able to incorporate a cohesive set of UI components and interactions into this year’s OpenEMR Project Core Roadmap .

The problem

As a designer who’d like to contribute ideas on how new features can fit into OpenEMR, I find myself not knowing exactly what types of components are used throughout the site. In my recent work on Units Support I spent some time going through the Patient Flow board and intake procedures that currently exist within the platform. What I found was modals that did not look like each other, buttons that did the opposite of what I expected and disconnected UIs that were difficult to string together within a single workflow.

This is expected, given the way that open source software is developed, that features do not necessarily fit together all “neat and tidy”. Since each feature contributor(s) has their own set of goals and method of implementing any particular interaction, some workflows may utilize a “radio button” where others might end up using a “dropdown” (for example).

Without a consistent method of implementing a certain user interaction, however, users are left with a less-usable experience and the risk that future features may end up copying the same patterns that lead to user error. In addition developers who may not care about the “front end” end up getting stuck on choosing the right interaction instead of spending their time on the parts they’d rather work on.

The pattern

One way to combat this problem is to develop a “Design System”:

A design system is a collection of documentation on principles and best practices, that helps guide a team to build digital products. They are often embodied in UI libraries and pattern libraries, but can extend to include guides on other areas such as ‘Voice and Tone’.
Quote from: GitHub - alexpate/awesome-design-systems: 💅🏻 ⚒ A collection of awesome design systems

Similar to a code style guide, a project’s design system can provide the basis for collaborative development by establishing a set of patterns that designers, developers and users can point to and say “that’s the way we do X”.

The best way to bring this to life within a community as vibrant and long-running as this one would be for someone to jump into the existing platform and catalog all of the UI/UX patterns that currently exist. I was thinking I could do this in a google doc and get others to contribute their own screenshots of interface elements to create an “interface inventory” - an introspective document that allows for (the community / those who care) to comment on what is “the best way” to:

  1. Display a patient to user
  2. Allow the user to check a person in
  3. Edit global admin settings
    … etc.

Most applications end up with a lot of different ways of doing the same thing… here’s an example from a “major bank website”:

The goal of this process is to “Lay the groundwork to a sound interface design system”:

the interface inventory is an important first step for setting up a comprehensive pattern library. It’s essential to capture all existing UI patterns to determine which patterns will make the final cut in the living design system. The interface audit exercise also helps teams establish a shared vocabulary, which will be crucial for the success of the eventual design system.
Quote from:

How you can help

If you’re working on the Bootstrap Standard project, please let me know how I can check out the current stage of your work and follow your progress. I have read through the themes readme and don’t quite have a feel for what’s changed and will have changed by the end of the bootstrap reskin.

I think this work can run in parallel to the re-theming of OpenEMR with bootstrap so if others who aren’t involved in that effort want to contribute to this conversation, please do chime in here! The purpose of this effort is not to tie the Design of the platform to any particular technology, but rather understand how we present the system to its users…

Once we’ve analyzed the patterns that make up the OpenEMR interface, it will be straightforward to decide what elements, components, or workflows need to change to meet user’s expectations of a consistent and usable electronic health records system.


@d3sandoval Can’t wait to review this. It’s on my list. I didn’t forget about you :smiley:

Great work


1 Like

On the subject of ui design and frameworks, check out this css I am going to be experimenting with for forms development.

It makes developing forms in html look better when printed, but also makes the UI for data entry more compact. Like bootstrap, it is responsive to changes in screen size.


1 Like

Agree with Daniel.
I think is very important issue for our project.


Hi @d3sandoval ,

Agree this is super important and in the end will both make development easier and the UI better. There is a extremely minimalist beginnings of a theme guide here (which you already have linked in your above post):

Looking very forward to your recommendations. Once your done with that, will make sense to attack a couple easy scripts to “seed” the process. Will need developers; are you able to develop in php? :slight_smile:


1 Like

I can do PHP :slight_smile: happy to provide some example PRs once I get the beginnings of a style library off the ground. I’ve been on vacation the last week, so I’m hoping to dive back into this once I catch up on my FT work.

Happy to hear that others are also looking toward consistency in the UI!


I have done a first pass through the entire UI for v5.0.1-dev and came up with an outline of the global components, navigational elements, icons, forms, buttons, messaging and lists/tables currently in use.

You can find this inventory on google drive:

All those who are interested should definitely check out the sheer number of ways we do the same thing in this project and leave comments on those they love (or loathe)!

In addition, I need some help discerning what is modifiable in the code base and what is not. For example, if we have 3rd party components that we cannot modify easily (or do not wish to for copyright/other reasons), then their screenshots should go in the 3rd Party page.

Finally, for those who know the code base better than I do, I’d like to direct your attention to the Image Types, Headings, and Color pages. In these pages, I’d like to capture the different ways that images are represented (both user uploaded and embedded in the code), how headings are used throughout the application (including text elements that look like headings, but are really just cleverly-styled divs), and every single color that is used (including those not necessarily specified within a theme.

With this inventory, I hope we can better understand the variances between implementation of common elements throughout OpenEMR. With just the screenshots that are currently captured, for instance, it’s easy to see that we have way too many types of buttons.

Feel free to add any screenshots I may have missed or leave comments on ones I may have captured incorrectly :slight_smile:


hi @d3sandoval ,

Very nice work! So many buttons to choose from :smile:


1 Like

hi @d3sandoval

Great to see your effort in getting the UI standardized. I have tried to get a unified look and feel to openEMR. Please look at the result of my efforts at There are several pages where I have tried to make the UI easier to use including easy to access help files.

I am excited and hopeful that the UI will come to reflect the underlying beauty of this amazing open source effort.


Thanks for sharing that! Great to see the direction you’re going - especially regarding table and text/button hierarchy. Do you have a branch/fork anywhere that might hint at what changes you’ve made to achieve the look?

I especially like that you pulled the patient search out of the top header and moved it into its own distinct header.

Given the work that you’ve already done, I’d love to go off and build a style guide around your implementation! This will make it easier to keep the UX consistent as we modify existing features and develop new ones.

Fork: GitHub - zbig01/openemr: Official OpenEMR repository
Current PR: Zbig01 new encounter improvements by bradymiller · Pull Request #1257 · openemr/openemr · GitHub
Old PR: #1076 , #993, #838

Please read comments in previous closed PR

I’ve spent the weekend putting together the first outline of the living style guide here: - it’s pretty barebones but it shows how most standard web components are affected by our themes :slight_smile:

As a byproduct of having to integrate our css files with fabricator’s build system, I standardized the composition of the three different “theme” types and their “rtl” variants: openemr/interface/themes/src/assets/toolkit/styles at styleguide · d3sandoval/openemr · GitHub

This is all done through gulp and scss. For more info, feel free to dig through the gulpfile or checkout the README!

My current todo list is as follows:

  • Add a lot of documentation on current component usage (including migrating the “buttons at the bottom of form” sections, below)
  • Migrate style dependencies in the php code to use the /dist directory
  • Migrate component css still left in the /themes directory into scss in /src/assets

I think I’m going to need @robert.down’s help to replicate the themeBuilder.php in scss and probably @brady.miller’s assistance in the epic find-and-replace that will have to occur to get the code to look for css files in /interface/themes/dist instead of just in the root /interface/themes directory.

I spent a bit of time attempting to get all the files to end up in their original place but it led to a mess and made it difficult for Fabricator to share nicely. It’s best practice to not commit generated css files if you’re using a preprocessor like scss/less/etc. anyway… since developers should have one source of truth when changing style sheets. This will most likely mean adding a build step to run a prod version of the gulpfile so that servers/containers running openEMR have the generated css files they need to serve up pages :slight_smile:

So I feel like this is off to a great start! I can’t wait to dive into breaking down the interface into navigable pieces for contributors to explore. As always, please do send along any feedback you may have or ideas for how to make this thing better.

1 Like

wow, this is some really neat stuff. I ran through the commands above and some really neat stuff happened. So, if I needed to update a style, where would I do this?(I hope this isn’t too stupid of a question :slight_smile: )

Not a stupid question at all. I’ve filmed a video that shows how you would make changes the style sheets and see those changes propagate across the style guide:

One thing I did not cover is how to update the src/materials/components .html files to document the styles themselves. This is because I’m still working out a few kinks with the dependencies in the /public folder. I think I’ll have to document a few existing interface components before I get the hang of using all of our external libraries… I’m trying not to move any files I don’t have to…

@d3sandoval, the other week when I visited Google Cloud Platform’s console for the first time, I was so stunned with how modern/polished the UI I was talking to myself (e.g.: “this is amazing!”, “this is from the future…”).

Had a similar moment clicking on your demo just now. Great work!


1 Like

been having a similar question so i am super thankful for answering it! also lots of thanks for the drive link, found some really useful things. can i ask you questions in case i would have some? thanks!

Bring on the questions! This is definitely still a work in progress and I have a feeling I’ll learn a lot when I start integrating demos of our PHP components from the /interface directory :slight_smile:

1 Like

hi @d3sandoval ,

Very nice!

Does it make sense to get this into the codebase soon(would go to 5.0.2-dev and not the 5.0.1 since will be released soon) or is more work needed so it doesn’t break anything. Then would force developers to start learning how to use this.

Also, I know this is against all standard procedures, but would be far easier for a multitude of reasons to actually include the css scripts in the same places they are now (and we would have a hard rule that these css can not be touched unless done the correct way via scss changes).


@brady.miller only a bit more work is needed to get this working. Once I get a basic component working in the Fabricator view, I’ll dive into getting a “production” build working that outputs the files into their original location.

I think one natural deterrent to editing css directly will be to minify the generated css so the only logical place to edit it would be in the scss versions. We can also add a comment to the top of the generated filed that points devs to the right place to edit the styles…

I’ll create a proof-of-concept this weekend and run through the golden paths to verify I didn’t break anything.

I’ll have time to really delve into this over the weekend. School is almost done for the semester, can’t wait to get to work on this. Super exciting times!