How to Use This Guide

This is a communication and reference tool. It can be used to help make decisions that have already been thoughtfully made.

On this page

Atomic Design and how we organize stylistic concepts

Why all the biology-related terminology? It comes from the notion of atomic design. Atomic design relates design to the hierarchies and building processes of the natural world. It uses five stages: atoms, molecules, organisms, templates, and pages.

HQ doesn't completely follow this methodology, but the rough ideas can still make for a useful communication framework.

By taking similar, simplified base patterns, often called atoms, we can build cohesive molecules and then more complex organisms. This keeps code cleaner and lighter while also keeping things simpler for our users to understand.

Some general principles to keep in mind:

  • How much effort does a user have to expend on your design?
    Consider both the effort to understand it in the first place, and then the effort to use it on an ongoing basis.

  • Group related information together.
    Visually emphasize content according to its importance.
    If you were to step back and squint at your feature, or if you couldn't read the text, how well could you guess what to read first and what to click?

  • Consider multiple designs.
    Just the practice of making yourself consider alternatives can lead to better designs and stronger design rationale.

Atoms

This section discusses the most basic elements of design on HQ. Much of this information is a level of detail that developers don't deal with on a day-to-day basis: the fonts, colors, etc. that underlie the classes and widgets used to build pages.

  • Accessibility: what is it and why does it matter?
  • Typography: what fonts do we use and why?
  • Colors: why use one color or another?
  • Icons: how do you find an icon that enhances your content?
  • Code Guidelines: how does one write good CSS/SCSS?

Molecules

This section covers the most common components used in CommCare HQ and how to use them well. Additionally, it covers any modifications or additions that have been made to these components on top of what might be supported by Bootstrap's framework by default.

These "molecules" build on the base concepts like typography, colors, and accessibility introduced in the atoms section.

A key point of this section is to keep concepts and design focused in order to avoid the phenomenon of analysis paralysis.

  • Buttons
  • Selections
  • Checkboxes
  • Modals
  • Pagination
  • Searching and Filtering
  • Inline Editing
  • Feedback

Organisms

Molecules connect into organisms: even larger building blocks, the kind that make up a substantial portion of the design of a new feature or significant update to an existing feature.

It's often said that CommCare HQ is basically a site of forms and tables, as those are the biggest "organisms" that make their way to new features and pages.

Very rarely are other "organisms" introduced, and covering that is outside the scope of this guide and will likely be part of a greater Design Spec discussion.

  • Forms
  • Tables

Templates and Pages

Templates structure free-floating molecules and organisms into a context: a specific page.

  • Navigation
  • Class-Based Views
  • Functional Views