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.

See the Bootstrap 5 Style Guide accessibility page.

Typography

Font choice can have a strong yet subtle effect on how users perceive content. HQ uses Nunito Sans as its default font. This is embdedded in our base template and is consistent with dimagi.com.

Further reading: The science behind fonts (and how they make you feel)

Colors

Use color for communication over decoration. Use of color should be purposeful, accessible, and help focus attention to what matters most.

We strive to establish recognizable patterns to guide users through the UI. CommCare uses similar palettes on both the mobile and server side. When combining colors, use white, light or bright text on a dark background. Use dark, black, or medium text on a light background. Use white or light text on a medium background.

As described above, many people are affected by various types of color blindness. It is important to make sure that colors are never the source of critical information. Also, when colors are used to compare information (legend of a bar or line chart) it is important that the colors used can be differentiated by people with each type of color blindness.

Colors for messaging and attention

Colors for interaction

Default and neutral colors

Colors for signup

The user signup and login flows use a slightly different color palette than the rest of HQ so that they better match dimagi.com. Do not use these colors once the user is logged in.

Legacy colors

Minimize use of these colors.

Icons

Visual communication can be essential in scanning and understanding for populations whose first language may not be English. Please be sympathetic with the goal of cohesion and don’t use an icon for a purpose it was not intended for.

Consistent iconography in any user interface is critical to creating a product that is highly accessible across all different levels of literacy. Icons may need to be localized for different cultures and languages.

Good icons use simple, graphic shapes so they can be understood even at a small size. They have little detail. They are as universal as possible, consistent with other platforms.

Primary vs Secondary Icons

Primary icons are used for navigation or interaction. Primary icons are interactive, they change the surround environment or data. They likely don’t need to be coupled with text.

Secondary icons provide clarity. Secondary icons are used before text to communicate topical information.

Most of HQ's icons come from FontAwesome. All icons in FontAwesome are already built into HQ. Other icons have been custom created for HQ.

Creating New Icons

The process for creating a new icon has been updated and can be found in the Bootstrap 5 styleguide, as the process is the same for both Bootstrap 3 and Bootstrap 5.

Code Guidelines

At the atomic level, coding is CSS and LESS. Good styling code, like any good code, is reusable, DRY, and semantic.

Overview

Most of us don’t write much CSS. HQ uses Bootstrap 3, which gives us a consistent and fairly comprehensive set of styles. Most of the "styling" we do is picking the appropriate Bootstrap (or HQ) classes and then troubleshooting anything unexpected.

We use LESS to write styles. LESS is a fairly simple extension of CSS that allows for more maintainable and reusable styling by supporting variables, mixins, etc.

Reusable CSS is good for the same reasons reusable code is good everywhere else. On the front end, reusable code is also correlated with visual consistency and generally better UX. To that end, when creating a new page or section:

• It should look very similar to related HQ pages.
• It should look fairly similar to other HQ pages.
• It should look somewhat like the rest of the internet.

Good styling is semantic, because that makes it easier for other developers to reuse. Ideally, a visual designer decides what an error looks like, or what a CRUD page looks like, and then developers only need to determine that they're displaying an error, or creating a CRUD page, and the look and feel is taken care of.

Classes like .bump-down { margin-top: 10px; } are problematic because it isn't clear when and why they should be used, so they get applied inconsistently and we end up with a site that looks a little bit...off...but it isn't obvious why. Bootstrap is a good example of a largely semantic system: classes have names like .btn-danger rather than .btn-red, to make it clear why you should use a particular class.

Style Hierarchy

Most styling should live in external LESS files.

Most HQ-specific styling lives in external LESS files, typically in corehq/apps/hqwebapp/static/hqwebapp/less.

App-specific styling can live in corehq/apps/style/static/APPNAME/less and then be included with <link> tags in the appropriate template.

Some pages use in-page <style> blocks. This isn't ideal for two reasons:

• In-page styles can't be reused by other pages - but for the sake of a consistent experience, most styling shouldn't be specific to a single page.
• In-page styles can't use LESS, so they tend to be less DRY and has to hard-code values like colors and dimensions, rather than using the standard values stored in LESS.

Handling Z-Index

Disorganized z-indices lead to highly visible bugs.

Z-index gives you control over the stacking order of elements. The challenge is that it acts like a global variable and, like any global variable, gets hard to keep track of. HQ deals with this as best as it can, by declaring numeric z-index values as variables in variables.less and using the variables in other LESS files. This isn't perfect, but it at least gives us one place to define HQ-specific absolute z-index values - which also need to play nicely with Bootstrap's z-index list.

Most z-index issues arise from not having a good handle on all of the different values used in an application, but there are a few other complexities that occasionally cause problems:

• Stacking levels: Z index isn't the only aspect of element stacking. Stacking is also affected by element positioning and floating. "Natural" stacking order, from top to bottom:
  • Positive z-index
  • z-index auto or 0
  • Inline elements
  • Floated elements
  • Block-level elements
  • Negative z-index
  • Background
• Stacking context: Z-index isn't strictly global, it acts within a stacking context. There's a global context but may also be sub-contexts within that. The most common of these is that an element with a non-auto z-index creates a stacking context. This is intuitive: if you set a modal to z-index: 9999, you don’t have to set the z-index on all of its children to 1000, they just come along for the ride. But there are other properties that also create new stacking contexts where you might not expect it. position: fixed is one, translucent elements is another. The others are pretty obscure.