typography.md

Opendoor Typography

(Market Side / Non-Bootstrap)

The problem

Headers and paragraphs have margins.

We use p for everything, to keep styles consistent, even if those things aren't "paragraphs".

In fact, many things that look like a header/paragraph, but aren't, are forced to use the actual h1/p/b tags, then use .no-margin and other overrides liberally, to make them consistent with our brand style.

For example, let's say we want to make a table with a header row. We want the header row to look like a bold, gray, version of a bold paragraph.

The only/best way to do this now is:

th: p.no-margin.text-muted: b Text here

There are a few problems with this:

1. It's not a paragraph (p), it's a table header (th).
2. We had to add .no-margin almost everywhere. We'll end up doing it throughout the table.
3. We had to use an extra b or strong element just for styling.

Separately, we might want to use p for actual paragraph-style, readable, text (for example, the blog or FAQ). To make it super-readable, we might want to fiddle with the line height, paragraph spacing (p + p rules?), paragraph-header interaction, etc. We don't want all this readability stuff to affect the rest of our UI.

Another way to think of this problem

Usually, when we are making a UI, we don't want margins.

However, when we are writing prose, we do want margins, and we want everything to "just work" and be well-spaced.

So in a sense, we are reusing our h1, h2, p tags (etc) for both UI and prose. We haven't really committed to one or the other. For example, our tags come with margins by default, so when in UI land we are constantly using .no-margin. Similarly, in prose-land, we want to override line-height, change header/paragraph interaction, and have margins.

Proposal

We make the separation between UI and prose explicit, and favor UI by default.

This means removing margins from h1, h2, p, etc tags.

We might set up our typography stylesheet like this:

.h1, .h2, .h3, .h4, .h5, .h6, .p {
  margin: 0;
}

.h1, .h2, .h3, .h4, .h5, .h6 {
  font-family: @header-font-family;
}

.p {
  font-family: @body-font-family;
}

h1 {
  @extend .h1;
}

// In UI land, p is the same as a div. Everything should look like our brand by
// default, without having to add extra p tags everywhere.
//
// Since .p only specifies font styles, this won't mess with layout.
p, div, span {
  @extend .p;
}

// h2, h3 ...

.prose {
  h1 {
    margin-top: 2em;
    margin-bottom: 1em;
  }

  // h2, h3 ...
}

UI work is easier out of the box. To add a prose section, like in an FAQ, we would do this:

.prose
  h1 Header
  p Body text

As a little bonus, if you hit a place where using the actual h1/h2/etc tag is very un-semantic (like in the table example above), you can just do:

td {
  @extend h5;
}

Implementation

1. Create the above stylesheet
2. Make sure everything looks ok. Keep .no-margin for now, it's not hurting anything.
3. Wrap prose with .prose as needed. This should be the only breaking change.
4. Document the new behaviors in the styleguide, so we can slowly move toward them.

Dangers

Adding .prose at a high level by mistake will screw up your UI.

It will be important to use .prose as close to the actual text as possible, so that you don't have to un-override the typography settings.