Adding Theming Support to 3.X


Adoption of 3.x is at the door, OHRI is live example of it - born in the 3.X era.

We see many people interested in using 3.X and OHRI. This is really great and a common question when we do a show case, during the last conference (and hackathon) is how can I customisable 3.X is. Apart from just customising forms and components in general, implementors will are also interested to know: how do I make the new to match my country or organisation branding? Basically how can they change the current theme of OpenMRS 3.X

This question is also one of the questions that the @OHRI team have and we looked at the architecture and we found no easy way to do it. The good thing we found is that the logos can be changed but not the color pallet. We also know that @PIH did some work around this but it’s not abstract enough to be reused - but I have a strong feeling that we can borrow a lot of ideas from that work.

I know that this is part of the 3.X roadmap and some design work already exists so, am writing this post to bring back this conversation and see what you all think about this and how best we can tackle this.

CC: @grace @bistenes @jdick @burke @ssmusoke @pirupius


Thanks @eudson, I guess that theming in the context of 3.x would be intended to in fact be 1) re-colouring + 2) white labelling?

1 Like

Good one @eudson thank you.

This is something we’ve intended to implement for a while. There may even be some designs already. I have a clear idea of how it should be implemented:

esm-styleguide should have configuration variables like “primary color.” It should override the global CSS variable definitions based on the values provided.


1 Like

Thanks so much @eudson for kicking this off!! Very grateful; I agree that making branding relatively easy will help with a sense of ownership for folks as they experiment with and adopt 3.x and OHRI. So a useful product move :slight_smile:

Re. Design Status: Complete. @bistenes the visual in Eudson’s message above is actually a design from Ciaran. He presented this along with the proposed approach for Theming back in Jan 2021 (1 yr ago). Design overview/presentation here: OpenMRS White Labelling (You can see how Ciaran was trying to show the idea of how to correctly use a main theme color with two-tonedness, vs what colors need to stay consistent, like the alerts colors or the abnormal range warnings.)

image image

So I believe the Design stage is complete, unless Ciaran or Paul Adams feel otherwise (they’re not on talk but I’ve also cross-posted this in our UX slack channel with them so they can confirm when back from vacation).

Thank you @bistenes. I’m assuming you mean this one? GitHub - openmrs/openmrs-esm-refapp-styleguide

Is there a particular location under /src where you imagine this config living?

Update: Heard back from UX Leads Ciaran and Paul in the #ux-design-advisory channel this week. Here’s what Ciaran said:

yep we’re both still happy with that guidance on theming. We’re also looking now at how we can enable easy theming of components at the Design System level using Figma. This should make it easy for design teams in the future to quickly mock-up on-brand screens for their implementation of OpenMRS

So FWIW @bistenes and @eudson, the guidance in this presentation is still what they recommend we follow: Pitch

@grace thanks for the update. Hope we can get the ball rolling soon.

Agreed :slight_smile: @eudson @bistenes what do you think we need next - some more detailed modelling ideas perhaps?

Sorry, I didn’t check Talk for a while and forgot about this. I can lay the groundwork by adding configuration for the primary color. Once that’s there it should be clear to others how to add support for configuring other style elements.

It’s on my radar now.

1 Like

Wow, thank you Brandon! :bouquet: :bouquet: @eudson does this work for you?

I also created an Epic for this work to live: [O3-1016] Theming Support for 3.x - OpenMRS Issues @eudson I made you the owner since my understanding is that UCSF is going to own the rest of this work, but feel free to re-assign to another team member as you feel appropriate :slight_smile:

I’ve implemented this: O3-1015 Implementer should be able to configure primary color by brandones · Pull Request #272 · openmrs/openmrs-esm-core · GitHub . Please see the gif at that link (gifs don’t work on Talk, apparently).

1 Like

Super fun update!

  1. @bistenes has added ability to configure the primary color - I’ll add a demo for this below.

  2. Ampath is already using this new config! Check out these screenshots from their production set up of 3.x:

Here is a demo as promised of how to set up this config:

Demo: Using the current Implementer Tools UI:

Demo: Using code:

Next Steps?

@eudson where would you like to go from here? Perhaps the next step is for this esm-styleguide to be incorporated into the OHRI demo and for you to experiment with it with implementers…? What do you think?

Thanks for the update @grace and for the good work @bistenes, this looks amazing. I believe it suits very well our use case and will also do for other implementers.


OK, to wrap this up: We’ve closed the epic as we’ll leave the work as-is for now. I’ve added the loom video above to a new 3.x Onboarding playlist: 3.x White Labelling and Theming - YouTube