Style Guide / Design System at OpenMRS: Discussion thread

Are you interested in Style Guides and where we’re going as a community?

Let’s use this Talk thread for discussion

There have been many threads so far but we needed one single one for virtual discussion.

(Note: Call Today: :calling: Please join the Style Guides deep-dive wrap-up call if you can: Call 2020-08-25: Community review of Style Guides v Design Systems work - last call before TAC recommendation!)

New Documentation: Summary of Style Guides at OpenMRS

Before joining the discussion here, please just check out this summary page, where we’ve tried to summarize :tada: New: All about Style Guides & Design Systems documentation page:

This is meant to help make sure we can all be on the same page. If you see anything that needs updating or clarification in the documentation, please let me know here or feel free to edit this shared documentation yourself as well :slight_smile:

@dkayiwa @burke @mseaton @mogoodrich @angshuonline @ssmusoke @michaelbontyes @mksd @florianrappl @mksrom @pradiptakundu @jdick @bistenes @herbert24 @insookwa @tendomart @dkigen @dkibet @jwnasambu @gracebish @cioan

1 Like

Updates and Notes from today’s deep-dive:

  • We saw visual examples of the patient dashboard in Lightning Design and Carbon Design, and a number of pros and cons. There were more cons than expected for Lightning.
  • We discussed the appeal of Bootstrap because it’s something more devs are familiar with, and we want our system to be easy for Implementations to set up and resource; however, Bootstrap doesn’t offer the full Design System guidance that’s baked in to Carbon Design. The idea of using Bootstrap’s components combined with Carbon’s framework was also raised, with the recognized limitation that it would be more difficult to use a combo than to use a single source that links effectively to its own guidance.
  • Result: We reached group consensus to try out Carbon Design as a Design System. JJ and Brandon will bring this recommendation forward to the TAC squad on Friday. The MFE squad will keep the community updated on their experience trying it out, and will let us know how easy it was to get going with in comparison to Bootstrap.

Link to slides

@ayesh, @ssmusoke, @mseaton - are there other points or questions you’d like to raise here that I missed?




Great quote in there Daniel. Added as an intro to the Documentation page :slight_smile:

It seems clear from viewing the recording of the discussion that, unless our plan is to build an EMR platform within Salesforce :wink:, Carbon is a better fit for our needs.

We’ve been using design system and style guide interchangeably at times and I think there’s an important difference. Here’s my mental model:

  • Design system - defines the framework in which things are designed (the strategy)
  • Components - the actual pieces used to implement the user interface (the tactics)
  • Style Guide - sample implementations providing practical (copy-and-paste) guidance to devs on how components can be combined in a way that follows the design system (the operations)

Considering the things we’ve reviewed using my mental model:

  • Bootstrap provides components and a little style guidance, but not a design system.
  • Carbon provides a design system and its own components. While it’s probably easiest to follow the design system using Carbon components, but it’s possible to implement aspects of the design system using non-Carbon components (Bootstrap, custom, etc.).
  • Lightning provides a design system for building application within the Salesforce framework.

Personally, I think we want all three:

  • A design system so we can look up decisions/guidance on how to implement most aspects of our user interface rather than having to make all of these decisions ourselves.
  • Components as the building blocks we’ll use to build our user interface.
  • A style guide as a library of best practice examples covering the common high level aspects of the UI that devs can (in at least 80% of cases) copy/mimic/adapt rather than having to figure it out on their own

Here are a couple of questions & answers using my mental model:

  • How does a bright young Ugandan developer just hired by @ssmusoke deliver the new functionality needed in a month?
    • For parts of the user interface without an immediate solution evident in existing code, browse the style guide and copy the solution from there.
    • For areas not covered by the style guide and not obvious from existing code, a custom solution might be needed. Follow the design system when creating any new/custom user interface features.
  • Why do we need a style guide?
    • To the extent that developers new to Carbon need to wade through a lot of guidance Carbon’s design guide to find an answer, a style guide can quickly get them to a working example.
    • We don’t have to re-document every component or feature. A style guide can refer people to the design system documentation in cases where certain user interface features are already sufficiently explained there. The goal is to fill the gap of real-world examples relevant to an OpenMRS frontend developer and to protect the average developer from having to learn the entire design system to solve a common problem.
    • A design system is unlikely to provide a concise example of how to implement patient search or how to render clinical observations. A style guide can fill this gap by providing practical examples relevant to OpenMRS developers.
    • Where the design system has some ambiguity/flexibility, a style guide can provide an opinion that most people will follow because it’s the path of least resistance.

Does this align with what others are thinking?

1 Like