3rd Party Style Guides & Design Sytems: Update and Next Steps

tl;dr: The MFE Squad has reached consensus that a 3rd party Design System is the way forward, and so far this is also the resounding feedback we’re hearing from others in the community. The MFE Squad commits to reviewing some Design Guides (definitely including Bootstrap) and coming back with pros, cons, and screenshots/visual examples, and then we’ll come back together to evaluate which one to use. Then we can discuss implementation considerations.

Updates This Week

Thanks to all who joined the open MFE Squad Design Call on Monday, where we had a special presentation from UX Designer Ciarán Duffy. Highly recommend seeing the short presentation at the start of the video here, or simply check out the slides here.

Since Monday, I was able to get a hold of both @bistenes and Joel Denning to update them on the discussion and hear any concerns. We also saw a couple conversations in the public #microfrontends channel in slack, and we covered the topic again today in the public weekly Micro Frontends squad meeting.

Summary of Current Thinking

I’m summarizing on behalf of the Micro Frontend squad, but very much recognizing this is a wider conversation too.

  1. Our Goals: A shared, clear Design System will help us have consistency among contributors w.r.t. how things should look. This is especially important given we don’t have dedicated long-term UX resources. We want it to be fast for devs to contribute meaningful work. And, it’s much better to figure out our design framework and styling sooner rather than later!
  1. We don’t have the resources to build/maintain our own design system. Group consensus is a 3rd party Design System makes the most sense in our case.

  2. Where there is debate: There is debate about the risk of future API-endpoint-breaking upgrades in third party systems.

    • On the one hand: Keeping the styling working after an upgrade could require a ton of variable replacement. Upgrading a styleguide generally has to be done all at once, which is a huge pain point for a distributed project like OpenMRS. One possible approach to address the API concern is use the existing storybook styleguide like a facade: Pull in/copy-paste the components we want from the Design System we choose (e.g. Bootstrap) into our own styleguide, so we can protect the API endpoints. (With a secondary benefit being reduced bloat.) So for new (especially transient) UX designers that join us, we can still very much say “we use [3rd party design system]”, but we maintain our own light-weight guide.
    • However, as @florianrappl pointed out, 3rd party systems (like Bootstrap) generally keep their recent old versions pretty well-patched, so we are unlikely to be forced onto a new version. Wrapping would also mean the effort of maintaining a fork of the 3rd party library. @florian had some ideas on how we could use the Component Library to achieve similar goals. The good news is this is not “this or that ASAP” - we could chose the wrapping/forking path later.

We don’t need to solve the “To Copy-Paste, or To Pull Directly” debate right now.

What We Need to Do Next

Pick a couple Design Systems to compare against each other. This will include how well the Design System meets a number of criteria, pros/cons, and visual examples like this one Ciaran put together:

Here’s the evaluation list we’re thinking of:

  • All necessary components are already there (compare what’s available with a Base Set of Components we rely on, e.g. date pickers, form field behavior, etc)
  • Default style is acceptable (Can be adjusted with minimum effort)
  • Framework agnostic - usable without framework lock-in (e.g. Bootstrap is not coupled to any frameworks)
  • Configurable (can style easily for RefApp or whatever org/branding you want to have)
  • Implementation considerations

I’ll be asking for feedback on the component list over the next week, and we’ll be sharing our findings for further input as we go. Happy to discuss further! (@bistenes @burke @dkayiwa @florianrappl and others - I welcome your additions/corrections here as well.)


Tagging a few people who others have suggested will be especially interested in this topic: @ssmusoke @sanjayap @ggomez @aojwang @michaelbontyes @pradiptakundu @angshuonline @mogoodrich @mseaton

As promised I’ll keep this topic updated in Talk over the next week or so; in the meantime if you have any thoughts to share or suggestions for things that should be included in the analysis, I’m all ears.

Update on progress re. next steps with Design System analysis:

Here’s the analysis framework we’ve set up in Confluence to compare different Design Systems. If you have any feedback on criteria etc I’m all ears. :slightly_smiling_face: https://wiki.openmrs.org/display/docs/Design+Systems+Analysis+-+July+2020

In particular, people might want to skim the Base Set of Components list and let me know if I’ve missed anything that you think we should check how it would look in the 3rd party style guide. It’s already a fairly exhaustive list but worth checking.

1 Like

There are very different stakes depending on whether we choose to continue with our own style library as a façade or switch to using a 3rd party library out of the box.

I am an advocate of the former approach: that we maintain our own style library, but that it simply imitates the components from a 3rd party library. Reasons for this were discussed at length in the MF RFC (for those who are new to the conversation, please read the comments on that PR before weighing in).

If we continue with our own style library as façade, then the question of which 3rd party style library to refer to is merely about style itself, and we should defer to Ciaran.

If we want to use a 3rd party style library out of the box, then we have a much more wide-reaching decision to make. Questions about responsiveness, maintenance, library size, feature support, etc., all become relevant.

Hopefully this won’t really derail things, but I just want to point out that

Wrapping would also mean the effort of maintaining a fork of the 3rd party library.

is simply untrue. Maybe the confusion arises with the word “wrapping”? We shouldn’t “wrap” a 3rd party style library. We should either steal from it into our own style library, or use it outright. I prefer the former.

1 Like

EDIT: I misunderstood the analysis document. But I still want to point out:

3rd party systems (like Bootstrap) generally keep their recent old versions pretty well-patched, so we are unlikely to be forced onto a new version

Looks like BS4 is scheduled to be EOLed in November. BS5 isn’t even out yet.

1 Like

Hi Brandon, So glad you’re back and so happy to have you in the conversation. There’s a lot in your comments to unpack. For starters I agree with your re-framing the term “wrapping” to instead a “facade/copy-paste” from a 3rd party guide. Sorry if I’ve caused confusion with that term. I’ll edit the description above.

Also FYI for others; Brandon and I just clarified with each other that the Components list isn’t a ticky-sheet but is instead where we’ll place screenshots of examples of these features between systems for rapid visual side-by-side comparison. :slight_smile: :yin_yang: Now this makes sense.

Further comments from Brandon (posting w/ his permission):

As engineers, we’re centrally concerned about the API—how usable is it, how familiar is it. We’re secondarily concerned about other technical questions, like maintainability and weight. With an independent style guide, all the technical and API questions are mooted. The only meaningful difference between 3rd party libraries to imitate becomes “how should it look.” In that case, if the designer says they like a particular look (ie Carbon), I’m happy to follow that. But if we don’t keep an independent style guide, then all of the devs’ concerns about API etc become very important, and we should choose according to the prevailing preference on those grounds, which is Bootstrap.

@florianrappl I know you’re away but I’m exercising your offer to weigh-in - can you weigh-in here? @bistenes there was also a good back-and-forth between Ciaran and Florian in the #microfrontend slack channel here: https://openmrs.slack.com/archives/CHP5QAE5R/p1594652626283700. Can you look through that and help me/us understand why this doesn’t address your concerns?

100% agreed with this :slight_smile: Hence sharing the evaluation criteria above for feedback.