IPUMS Style Guide

Welcome to the IPUMS Style Guide. This guide documents how elements are formatted using the new style sheets, and provides detailed information on how to customize your webpages by leveraging the underlying CSS classes. The new style guide is not set in stone, and will inevitably evolve as we attempt to roll it out to our various projects. Code samples and their respective results are displayed using JSFiddle. If you have any questions, chat with Jason or Alex. You can usually find us in our cubes opposite the lounge, or alternatively, shoot us an email at goray@umn.edu or amcwhinn@umn.edu

We recommend running all new webpages through the W3C Markup Validation Service. You can check your code by either a file upload or by direct input (pasting)

Page structure

Full width page

For content that does not fit in the standard narrow column layout, the page width can be switched to a full screen layout. To have a page display this way, add class="width-full" to the <body> tag. For an example, see the DHS Sample Descriptions

No menu

The side menu should ideally appear on every page, although due to the complexity of some tables, we understand that it may not always possible to accomodate it. As such, there is an option to turn menus off by adding class="no-menu" to the <body> tag.

NOTE: We encourage you to attempt to get your content to fit using full width before resorting to removing the menu.

Headings

Heading Hierarchy

Headings should always be used in order of hierarchy. For example, an h4 heading should not be used after an h2 heading until an h3 heading is first used.

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6

Heading Examples

H1 Headings

h1 headings are used as page headings, and should only appear once, at the top of each page. In order to give Back to top links an anchor to link to, h1 headings should have id="page-title" added to them.

Attributes

H2 Headings

h2 headings are to be used as section headings.

Attributes

H3 Headings

h3 headings are to be used as sub-section headings.

Attributes

NOTE: We use javascript to exclude the Capitalization of short words. The following is the list of words that don't get capitalized. This can be edited, so let us know if we are missing anything.

H4 Headings

h4 headings are to used to denote blocks of content within subsections. The content will be kept close to the heading.

Attributes

H5 Headings

h5 headings will generally only be used to denote a following paragraph. The content will be kept close to the heading.

Attributes

H6 Headings

h6 headings will generally only be used to denote the following paragraph. The content will be kept close to the heading.

Attributes

Lists

List Examples

Numbered Lists

To be used for ordered lists. An ordered list can be numerical or alphabetical

Bulleted Lists

To be used for unordered lists

Nesting Lists

Any type of list can be nested. The following example shows a nested unordered list. You will notice that a second list is nested inside the first list, which renders indented with a different bullet.

Unmarked Lists

This has been moved to the more generic No Embellishment section.

Columnar Terms

To create a definition list where the terms line up in a column, add the class class="list-fixed-dt" to the <dl> tag.

000
Meaning of first code
010
Meaning of second code
020
Meaning of third code
9999
Other code

If you need a column width that is wider or narrower than the default, you can add the following embedded css with the width of your choice where 1 rem ~= 10 pixels and the dd measurement is 0.5rem wider than the dt:

<style>
	dl.list-fixed-dt dt { min-width: XXrem; }
	dl.list-fixed-dt dd { margin-left: XX.5rem; }
</style>
Banana
Meaning of first code
Orange
Meaning of second code
Pomegranant
Meaning of third code
Some other fruit
Other code

Finally, if you have multiple lists which need different width columns, you can add an additional class to both the style block and the tag:

<style>
	dl.list-fixed-dt.table2 dt { min-width: XXrem; }
	dl.list-fixed-dt.table2 dd { margin-left: XX.5rem; }
</style>

<dl class="list-fixed-dt table2">
	<dt> ...

Spaced Lists

This has been moved to the more generic Spaced section.

Tabular Lists

Tabular lists are lists design to display tabular data. Grids of menu links, etc.

Use class="list-tabular col-#" where # is a number between 2 and 10. Additional column counts can be added on request. If the column count is omitted, it will default to 5.

5-column example using class="list-tabular col-5"
We also support centered columns using additional class align-center.
10-column centered example using class="list-tabular col-10 align-center"
Note: Column Flow Issue

There is unusual behavor with CSS columns in that the column count is the maximum number of columns, but fewer columns are allowed. This sometimes results in one fewer column than you would expect.

This can be reliably triggered when the number of items in the list are the square of the number of columns - 1: for instance 4 items in a 3 column table, 9 items in a 4 column table, etc, but occurs at other times as well. According to this article, there are other times where it will show an extra row in lieu of filling out the last column.

If this is happening in a way that is too disconcerting, try changing your column count or you can use the left-to-right class="list-tabular left-to-right" style list.

Tables in column flows

If we like this, we should write some notes on it and document issues like two short tables followed by a long table in a 3 column possibly only wrapping into two columns.

Menu Lists

Menu lists are used in horizontal menus and designed to show a list of links side-by-side, and are created by adding the following class class="list-menu"

Definition Lists

Definition lists are used when you wish to pair items that have a direct relationship with each other (name/value sets). Definition lists consists of two parts; a term and a description. To create a definition list, you need three HTML elements; a container <dl>, a definition term <dt>, and a definition description <dd>. For example:

Definition lists can also be floated, or floated with floated children (DDs). This is particularly useful for codes pages.

Tabular Definition Lists

Coming soon. We suspect you will be able to leverage these by adding a class, like tabular to the <dl> tag. This will float the <dd>'s next to the <dt>'s. Users might need control over the number of columns and column widths. The sample information list on IPUMSI is a good example of something that will need to be a definition list.

Text Formatting

Typeface

IPUMS uses a family of fonts called Cabrito Sans. In order to reduce filesize, we have subsetted the typeface to only use the following Cabrito Sans fonts and glyphs:

The fonts are hosted on assets.ipums.org, and are loaded progressivly, beginning with a very lightweight version of Normal Regular that contains only the critical characters. When visiting an IPUMS site for the first time, you may notice a flash as the critical font is replaced by the larger, more comprehensive glyph sets.

Let us know if you wish to include additional glyphs and we will add them.

Implementing the font (for developers)

Add the following code to the header of your application:

<style>
	@font-face {
    	font-family: ‘cabrito_subset’;
    }
    @font-face {
    	font-family: ‘cabrito_sans_norm_regular’;
    }
    @font-face {
    	font-family: ‘cabrito_sans_cond_demi’;
    }
    @font-face {
    	font-family: ‘cabrito_sans_cond_bold’;
    }
</style>

<link type=“text/css” rel=“stylesheet” href=“//assets.ipums.org/_css/font-faces.css” media=“all” />

<!-- scripts to load immediately -->
<script src=“//assets.ipums.org/_js/ffo/fontfaceobserver.js”></script>
<script src=“//assets.ipums.org/_js/load-fonts.js”></script>

<link type=“text/css” rel=“stylesheet” href=“//assets.ipums.org/_css/ipums.1.3.css” media=“all” />

Paragraph Text

Tabular Numbers

Tabular numbers are applied to all Ordered lists <ol>, Unordered lists <ul>, Definition lists <dl>, and Tables by default. To override instances of these defaults, add class="no-tnum". To manually make numbers tabular elsewhere, use class="tnum".

Emphasis

Emphasis, or italicizing, can be applied to individual characters, words, or groups of words by wrapping them in <em> </em> tags.

Bolding

Like emphasis, Bolding can be used anywhere in a paragraph. It is achieved by wrapping individual characters, words, or groups of words in <strong> </strong> tags.

Note: If you wish to emphasize a line of text above a paragraph, it may be more appropriate to use an <h4>, <h5>, or <h6> heading

Code Snippets

Code snippets should be nested inside <pre> and <code> tags.


<pre>
	<code>
		Code goes here
	</code>
</pre>

We use the Prism Javascript library to automatically add syntax highlighting. In order to minimize size, we have subsetted Prism to only use the following languages and settings:

Theme
Okaidia (1.73KB)
Languages
Markup (0.91KB) class="language-markup"
CSS (0.99KB) class="language-css"
C-like (0.69KB) class="language-clike"
JavaScript (1.35KB) class="language-javascript"
Java (0.72KB) class="language-java"
JSON (0.28KB) class="language-json"
Python (0.75KB) class="language-python"
R (0.49KB) class="language-r"
SAS (0.64KB) class="language-sas"
SASS (1.01) class="language-sass"
Plugins
None
Total Size Minified
19.13KB

If you wanted to define a code snippet as python, your code would look something like this:


<pre>
	<code class="language-python">
		Code goes here
	</code>
</pre>

A complete list of supported languages and their respective classes can be found here.

Note that your indentation will be preserved, so if you want code left aligned as in the examples, you'll need to put the code starting at column 0 (Remove all the tabs/indents from the code inside the <pre> tags).

Examples

STATA Example (class="language-stata")

svyset psu [pweight=perweight], strata(strata)
svy: mean var1
SAS Example (class="language-sas")

proc sort data = datasetname;
by strata psu;
run;
proc surveymeans data = datasetname;
weight perweight;
strata strata ;
cluster psu;
var var1;
run;
R Example (class="language-r")

print(sample(1:3))
print(sample(1:3, size=3, replace=FALSE))  # same as previous line
print(sample(c(2,5,3), size=4, replace=TRUE)
print(sample(1:2, size=10, prob=c(1,3), replace=TRUE))

You may also run into problems using carets in your code snippets. Carets might need to be replaced with character entities. Replace any < characters with &lt; and > characters with &gt;

Blockquotes

The <blockquote> tag specifies a section that is quoted from another source. This tag will cause the content to become indented.

Content nested inside a <p> tag that is within the <blockquote> tag will be formatted with a left border and italicized, in addition to the indent.

Footnotes

There is no good HTML5 convention for doing footnotes. w3c suggests wrapping tables in figure tags, then using figcaption for footnote. Alternatively, using article/sections/asides. We'll need to come back to this.

Addresses

The contact information belonging to the site should be wrapped in <address> tags. This might include an address, email address, and phone number

NOTE: We may also wish to include something about hCard Microformats...possibly 'encouraging' the use of them, but not requiring it. I found a few online generators that might help with their creation, but I am uncomfortable with the code they generate (They use div instead of section tags, attributions tacked onto the bottom, and even inline CSS for some dumb reason). We could quite easily write our own generator in javascript.

Citations

Citations should be wrapped in <cite> tags

Superscript

Superscript can be added to text by wrapping it in <sup> tags

Links colors are displayed using the project's primary color, although in some instances, a darker variant of it. Hover color is IPUMS NAVY (#00263A), with visited color being IPUMS BLUE/GREY (#7A99AC)

Internal links make up most of the links on our webpages. They are created by wrapping your intended link in <a href="#"> </a> tags, where # is the url you wish to navigate to.

External links are links that take a user offsite. A link to our bibliography on IPUMS USA, or a link to the DHS Program from IPUMS DHS are examples. External links should ideally open in a new tab, thereby, not navigating the user away from our site, as this is not always the users intention.

This can be done by adding the target="_blank" attribute to the <a> tag. A link to the DHS program that opens in a new tab would look like this:
<a href="http://www.dhsprogram.com" target="_blank">THE DHS PROGRAM</a>

External links should also be followed by an icon that conveys their behavior to the user. The icon is automatically added to the right of text links by checking the beginning of the destination url for "HTTP", since internal links almost always omit this.

Suppressing external link icons

If an icon needs to be manually suppressed, the class="no-link-icon" class can be added to the <a> tag. This class can also be added to a container of links (table, list, etc) to suppress all external links inside.

Anchor links are used to link to inpage elements. For instance, a 'Return to top' link might take the user back to the top of the page using an anchor link, or a superscript link might take the user to its corresponding reference at the bottom of the page or table.

Anchors are broken into two components, the link, and the anchor (destination). A link is created much the same way as a regular link, but a # sign needs to be placed at the begining of the url to let the page know that it is linking to an anchor, for example <a href="#reference-1">Click me</a>. The anchor name will need to match this, but without the # sign. Anchors should be defined using an ID and placed on the element you wish to link to. id="reference-1"

ID vs Name

In the past, anchors were designated by using the name attribute <a name="#reference-1"> </a>. HTML5 has declared this no longer valid, with anchors now needed to be declared using an ID on the HTML element. For instance, if you want you link to jump to a particular <h3>, you would place the ID on the <h3> so that it becomes <h3 id="reference-1">Heading</h3>

Users should know that a link is going to open as a PDF, ZIP, XLS/XLSX, DOC/DOCX, before they click on it. As such, links that open or download files should be followed by an icon that lets the user know that it is not a regular page link. These icons are automatically added to text links by checking the end of the destination url for a file extension. If an icon needs to be manually suppressed, the class="no-file-icon" class can be added to the <a> tag. Alternatively, if you had a reason to suppress an entire table or list of file icons, you can add class="no-file-icon" to the <table> or <ul> tags.

We strongly encourage these links to also open in a new tab, by adding the target="_blank" attribute to the <a> tag.

PDFs can also have size information attached to the link. This needs to be manually added by adding the data-size=" " attribute to the <a> tag

Examples

Links can also be defined as an email address or phone number. Doing so allows the browser to know that it needs to open an email client, or dial a phone number (on a phone-capable device). The following example shows how a mailto: or tel: attribute can be added to a link.

Coming soon

Coming soon

Back to top links are anchor links that take the user back to the page title (h1). These links should be titled Back to top rather than Return to top or just Top. Back to top links need to point at the pages title (h1) by having the following anchor link <a href="#page-title">Back to top</a>

Back to top links will automatically receive a small upwards pointing arrow to the left, provided their anchor destination is properly set as #page-title. If it doesn't appear or work, you will want to make sure your h1 has the appropriate page-title ID

While we don't have any strict quidelines on where to place your Back to Top links, we suggest placing them at the bottom of sections of content, or in a table header (if that is the content you are working with). Do not place them between a paragraph and it's respective heading.

A button link can be useful for bringing attention to a call to action by using <a href="" class="button">Button Text</a>:

Button Text

Tables

Note: We need to also include information about top and bottom margins.

Column and Row headings

Column and row headings are defined by using the <th> tag in place of <td>. Column and row headers are formatted to have a shaded background and bolded text.

Column and Row Main Headings

Column and row headings appear with a navy background and white text. Table cells should be nested inside <thead></thead> tags in order to take on this appearance. The <thead></thead> tags should go immediately after the opening <table> tag.

Table Captions

Table captions are to be used as figure (table) headings, they appear above a table, and are not to be confused with table footnotes or figure captions, which typically appear below. To use a table caption correctly, insert your <caption> tags following the opening <table> tag. For optimal accessibility, use table captions rather than <h#> tags.

Condensed Content

The content in tables can be condensed by adding class="condensed" to the <table> tag. Condensed tables reduce both the size of the text, the line height, and the padding within each cell.

Back to Top Links

A standard for using these in tables has not been established yet. This section will provide some guidelines so that it is consistent between projects. There will need to be a link to the main section in Links.

Regular links in table cells are much the same as links anywhere else. Note that links that open PDFs, Zipped file, and external URLS have icons indicating this behavior. (need to add this)

Links that follow text should be in square brackets []

Zebra Striping

Zebra striping is an optional feature, and can be added to any table by adding class="striping" to the <table> tag.

Borderless Tables

To remove the borders on a table, add class="no-border" to the <table> tag.

Multiple classes can be concatenated. Below, we can see how a table looks with both the no-border, and striping classes applied to the <table> tag. Multiple classes are applied by leaving a space between the class names.

Alignment and Padding

Column alignment can be configured by adding alignment classes to the <table> tag. Column alignment takes 2 parameters; the type of alignment, and the column number that you wish to be aligned.

Individual Column Alignment

All Column Alignment

The following example centers the content of columns 4 and 5, and right aligns the counts in column 6. Note that three classes have been concatenated.

Default padding of Top: 5px, Right: 10px, Bottom: 5px, and Left: 10px, is added to all <td> and <th> cells.

Table Rowspans and Colspans

Table cells can also span multiple columns or rows using colspans and rowspans. The above example is a good candidate for using rowspans, since a lot of the same information is duplicated across cells. Borders have been made visible so you can see the true effect of the rowspans.

In the example below, we tell the first cell in each row to span 3 rows by adding rowspan="3" to the <td> tag.

The same can be done with columns using colspans. The following table shows how the Questionnaire cell can span three columns by adding colspan="3" to the <td> tag.

The following table shows the underlying structure

<th> <th colspan="3"> <th>
<th> <th> <th> <th> <th>
<th colspan="5">
<td rowspan="2"> <td> <td> <td> <td rowspan="2">
<td> <td> <td>
<td rowspan="2"> <td> <td> <td> <td rowspan="2">
<td> <td> <td>
<td rowspan="2"> <td> <td> <td> <td rowspan="2">
<td> <td> <td>

Table Widths

By default, the tables will take the full content width. To override this, add the <table class="width-auto"> class to the table.

Table Column Widths

The <col> tag allows you to apply a style to an entire column rather than specifying it for each row. It must be wrapped inside <colgroup> tags. Column widths are set using the inline style tag on each of the <col> tags, and are specified using either percentages or rems.

The example below sets the width of column 1 to be 50%, and the remaining columns to each be 10%.

A careful eye might notice that the first column of this particular example isn't quite at 50%. This is due to the text (Record, Year(s), etc) in columns 2 through 6 being too large to shrink the widths to 10%.

Note that the old way of specifying width (<col width="200">) has been deprecated.

Column Wrapping

By default, a table will attempt to size all of its columns to be equal width. Concequently, content may end up wrapping undesirably. While the previous technique of specifying column widths could address the issue, there are often times where you may never want the content to wrap. Setting a fixed width to achieve this may work today, but the addition of new (longer) content into the table tomorrow might require tweaking the column widths yet again.

Columns can be forced not to wrap by adding class="no-wrap-col-#" to the <table> tag. Where # is the column number. The following example shows us forcing column 1 not to wrap.

NOTE: Forcing columns not to wrap can cause the table to break the page column

Responsive/Folding Tables

Responsive/Folding Tables can be created by applying class="folding-table" to the table tag. <tbody> and <thead> elements must also be used to differentiate the table header and table body rows. Cells in the table's body also need to have a data-title="" attribute assigned to them, which is then used as the row header when the table hits the single-column breakpoint (< 850 pixels).

The HTML code in the following example should make folding tables a bit clearer. Currently the JSfiddle is displaying the folded version of the table, due to the narrow width of this webpage. I suggest opening the JSFiddle in a new tab in order to experiment with dragging the window smaller and larger

Table Footnotes

To place footnotes below a table, inset the <tfoot></tfoot> tags at the end of the table, but before the closing </table> tag. Footnotes can be linked to by using anchor tags on a superscript reference mark. (discuss anchors in more detail under links section, and superscript elsewhere too)

Indicating No Data in a Cell

On Hold. Background: Some tables have cells that are empty. Others have a hyphen -, some have two hyphens --, some have NA, and others have N/A. We need to find out whether there there needs to be multiple types of symbols for no data, but ultimately we should have as much consistency as possible between projects

Table Row Hover

The row hover appears as a default behavior on table <td> cells, excluding those in <tfooter> tags. The hover uses a tint of the project's primary color. For applications that don't fall within one of the 9 project colors, we use a light version of IPUMS navy (as seen within this style guide). We may add a class that can be applied to a table to disable it.

The row hover behavior can be suppressed by adding class="no-hover" class to the <table> tag.

Types of Tables

The following two tables contain the same information yet are formatted differently. Both styles are acceptable.

When Not to Use Tables

Tables are excellent ways to arrange tabular data, yet there are several situations where we urge you not to use tables. If an element could be described as a list or menu, semantically, it probably makes sense to build this as a list. Not only does this improve the accessibility of the page, it will be easier to edit, and it will look better.

Examples of content that should probably be built as lists include, staff lists and dataset lists. If you want a list to flow into a specific number of columns (like a table), take a look at tabular lists.

Other

No Embellishment

Use the this class to make a less dressed up version of something.

Currently, this is only implemented for the <ul> and <ol> tags. To create a list without bullets or numbers, start with an unordered/bulletted list and add class="no-embellishment" to the list tag.

Test Example

Spaced

Use the this class to give a tag a bit more space.

Currently, this is only implemented for the <ul>, <ol>, and <dl> tags. To create a list with a bit more space between the list items, start with an ordered/unordered/definition list and add class="spaced" to the list tag.

Test Example

Floated

Use the this class when there is a variant that benefits from being made inline.

Currently, this is only implemented for the <dl> tag. To create a definition list where the items float behind the term, start with a definition list and add class="floated" to the list tag.

Test Example

Item 1
Thing 1.1
Thing 1.2
Thing 1.3
Item 2
Thing 2.1
Thing 2.2
Thing 2.3
Item 3
Thing 3.1
Thing 3.2
Thing 3.3

Floated Image/Figure

You can also use class="floated" when you have an image that should have the text floated around it.

If you have an image you want to have floated on the left, use class="floated align-left" and if you have an image you want to have float on the right, use class="floated align-right".

If you have an image and it's respective caption inside <figure> tags, you can float the entire figure too, by placing the class in the <figure> tag.

Floated Child

Use the this class when there is a variant that benefits from child aspects being made inline.

Currently, this is only implemented for the <dl> tag. To create a definition list where the items float behind the term, start with a definition list and add class="floated-child" to the list tag.

Test Example

Item 1
Thing 1.1
Thing 1.2
Thing 1.3
Item 2
Thing 2.1
Thing 2.2
Thing 2.3
Item 3
Thing 3.1
Thing 3.2
Thing 3.3

Bulleted

Use the this class when you want it to be bulleted like a list.

Currently, this is only implemented for the <dl> tag. To create a definition list with bullets, start with a definition list and add class="bulleted" to the list tag.

Test Example

Item 1
Thing 1.1
Thing 1.2
Thing 1.3
Item 2
Thing 2.1
Thing 2.2
Thing 2.3
Item 3
Thing 3.1
Thing 3.2
Thing 3.3

No Indent

Use the this class when you wish to remove indenting from something that normally has it.

Currently, this is only implemented for the <dl> tag. To create a definition list without indents, start with a definition list and add class="no-indent" to the list tag.

Test Example

Item 1
Thing 1.1
Thing 1.2
Thing 1.3
Item 2
Thing 2.1
Thing 2.2
Thing 2.3
Item 3
Thing 3.1
Thing 3.2
Thing 3.3

Figures and Captions

The figure element represents a unit of self-contained content that is typically referenced as a single unit from the main flow of the document. Figure elements can be used to group any number of different things together, including, but not limited to images and code blocks. In fact, a figure can contain multiple things.

Figures are created using the <figure> tag, which can contain an optional <figcaption> tag to define the caption.

Figures can only have a single caption, that should be placed before or after the content.

Figures have no unique formatting beyond a bolding of their caption.

Coming soon.

Accordions

Accordions can aid in creating pages that are shorter and require less scrolling. Often refered to as a 'drawer', accordions allow visitors to click on a header, which then expands or contracts to reveal or hide the content within a drawer.

Accordions can also be nested by placing another accordion inside the content area of the first accordion

Accordions need to be inside a container, such as <div class="accordion"> </div>. Accordion headers can be any level of heading. The nested example above uses H2 and H3, but this could just as easily be H3 and H4. Just make sure you rank headings (H1, H2, H3, H4, etc) appropriately. The W3C has more information on headings

Project Colors

RGB/HEX colors should be used for all digital applications, while CMYK and Pantone should be reserved for print. A library of the IPUMS color swatches can be accessed via Adobe Creative Cloud by following these links: RGB CMYK

Instructions on how to save a library of these color swatches to your Adobe account can be found here

IPUMS General

USA Colors

International Colors

Health Surveys Colors

Terra Colors

NHGIS Colors

DHS Colors

Time Use Colors

CPS Colors

Higher Ed Colors

IPUMS Graphics

It is important that graphic standards are maintained. Email Alex McWhinnie at amcwhinn@umn.edu for additional information about accessing and using graphic assets.

Alerts and Prompts

There are four different flavors of alerts to choose from. Info, Success, Warning, and Error. These can be enabled by adding the following classes to a block-level container (p, div ,etc)

class="alert alert-info"
class="alert alert-success"
class="alert alert-warning"
class="alert alert-danger"

Supported By Section

Order and sizing of supported by logos. I'm not sure of the best way to add this. They won't fit in that column without wrapping. Perhaps there could just be a link to a separate page where they are all listed, along with any links to their own respective style guides.

Stock Content

The University of Minnesota provides free stock images, video clips, and audio clips to students, faculty, and staff as well as vendors working on University projects. If you need stock content for a presentation, blog, etc, try this source before exploring other 'pay' sites.

UMN Stock Content