@ithaka/bonsai/documentation/pages/styles/typography.md

ITHAKA core styling

---
title: Typography
description: We use typography to create a clear hierarchy on the page. Font size, weight, height and spacing is used to show emphasis.
foundation: http://foundation.zurb.com/sites/docs/typography-base.html
sass: ./scss/_typography.scss
---

## Typeface

We use Arial for all text on the site and Arial Black for large headings for emphasis.

## Headings
Headers are meant to visually and semantically break down a page into hierarchical sections.

### How to Use

The heading styles are applied directly to the `<h#>` tags by default, setting the font size,
  font weight, and spacing of the text. Styling has been designed for h1-h4. `<h5>`, `<h6>`, etc. should be avoided if possible.

#### h1 or .xlarge-heading

`<h1>` should be used as page headers. There should only ever be one `<h1>` element per page.  A 'special' version of the `<h1>` element can be seen on the [Hero](/styleguide/hero.html) page 
  and is used as a 'Photographic header'. 

```html_example
<h1 class="upper">H1 upper - This is an h1 with  'upper' class.</h1>
<h1>H1 - This is a regular h1 header.</h1>
```

#### h2 or .large-heading

`<h2>` elements are predominantly used as Subheaders (e.g. 'Journals, Book, Primary Sources' on [whats-in-jstor](http://about.jstor.org/whats-in-jstor/)). They are also used as module labels on the About site (e.g. the News Module ('NEWS' on [about.jstor.org](http://about.jstor.org/))).

```html_example
<h2 class="upper">H2 upper - This is an h2 tag with 'upper' class.</h2>
<h2>H2 - This is a regular h2 header.</h2>
```

#### h3 or .medium-heading

`<h3>` elements are used as intro text (e.g. "The first of JSTOR's Thematic Collections..." on [whats-in-jstor/sustainability](http://about.jstor.org/whats-in-jstor/sustainability/)). They are also used as news and events module headlines on [about.jstor.org/news](http://about.jstor.org/news/) and [about.jstor.org/events/](http://about.jstor.org/events/). 

```html_example
<h3 class="upper">H3 upper - This is an h3 tag with 'upper' class.</h3>
<h3>H3 - This is a regular h3 header.</h3>
```

#### h4 | .small-heading

`<h4>` elements are used within `<h3>` headers in the bodies of text containing hierarchical information. Beyond this, there are no other special uses. `<h4>` should not generally be capitalized (do not use `.upper`).

```html_example
<h4>H4 - A common space to discover resources</h4>
```

### Using the Heading Utilities

You can also use the `.*-heading` classes to mimic the styling for the `<h>` tags or in a `<span>` or `<div>`. This affords you better control over spacing, while maintaining the same font size and weight. It also allows you to display headings (or other text) at a size different from the default for that heading type:

```html_example 
<h2>I'm a plain jane 'h2'</h2>
<h4>I'm a joe schmoe 'h4'</h4>
<h2 class="small-heading">I look like an 'h4' because i have a .small, but i'm secretly an 'h2'</h2>

<div class="xlarge-heading">I'm a 'div' with '.xlarge-heading'</div>
<div class="large-heading">I'm a 'div' with '.large-heading'</div>
<div class="medium-heading">I'm a 'div' with '.medium-heading'</div>
<div class="small-heading">I'm a 'div' with '.small-heading'</div>
```

On the platform, pages with titles we supply (ex. Search Results, Advanced Search, Browse by Title, etc) have a regular h1 heading. On pages where someone else supplies the heading text (ex. a publisher's page, a journal page, a book table of contents), use `.large-heading`. On pages where someone else supplies the heading text <em>and</em> the heading text is part of a metadata content block (ex. article, chapter, research report, etc), use `.medium-heading`.

## Accessibility 

1. Heading tags on any given page should maintain a semantic structure visible and interpretable 
  by primarily-visual users and by screen readers as well. 
2. Headings should descend in order--there should not be a `h3` tag before a `h2` tag on a page. 
3. Please refer to w3.org's notes on [using h1-h6 to identify headings](https://www.w3.org/TR/WCAG20-TECHS/H42.html)
4. Note that the use of the heading classes is invisible to screenreader's intepretations of the DOM, and 
  the screenreader will interpret all `<h2>`s and `<h4>`s as just that.
5. You can (and should) leverage the heading classes to support optimal visual readability while
  maintaining a semantic structure with the heading hierarchy.

<hr />

## Body Text

There are four main "sizes" of text outside of `title` and `h` tags in two categories:
- "Regular" text 
  - paragraph
  - list item
  - 'free' text
- `<small>` text


### Regular Text 

The size of regular 'body' text is heavily influenced by which html element it's in (`<p>`, `<li>`, `free`).

```html_example
<ul>
    <li>I'm a list item</li>
    <li><p>I'm a 'p' inside of a 'li', but i still just get the 'li' styling</p></li>
</ul>
<p>
    I'm the kind of text you always see hanging out in a 'p' tag.
</p>
Lonely text - I'M Lonely text - OH SO LONELY - I'm 'free' text that doesn't have the spacing and line-height and margins that 'p' text gets!
```

<br />

### Small Text 

You can specify extra small text by surrounding it in a `<small>` tag.

```html_example
<small>I'm some really small text inside a 'small' tag!</small>
```

<br />

### Text Transforms

```html_example
<div class='upper'>I'm all uppercase!</div>
<div class='lower'>I'm all lowercase!</div>
<div class='capitalize'>I have each word capitalized!</div>
```