Bad:
To learn more about ZoLa, click here.
Typography
Type basics
Be consistent with font styles and hierarchies to ensure that UI elements are clear and easily recognizable when scanning the page.
- Avoid using too many font styles
- Size type with relative units (
rem) - Check how your type flows at various screen sizes
Inline formatting
- Use
<b>for bold text, without any extra importance - Use
<strong>for bold text, with added semantic "strong" importance - Use
<i>for italic text, without any extra importance - Use
<em>for italicize text, with added semantic importance - Use
<small>for smaller text - Use
<mark>for marked or highlighted text - Use
<del>fordeleted(removed) text - Use
<ins>for inserted (added) text - Use
<sub>for subscripted text - Use
<sup>for superscripted text
Fonts
NYC Planning products use a system font stack. This ensures that UIs are optimized to be highly legible, boosts performance, and are frictionless as you move between our products and the rest of the operating system. One exception to system fonts is when displaying code. In this case, you should use the monospace font stack.
Use the .font-default and .font-mono classes to explicitly set the font for a particular element. These classes can be used to override the font inherited from a parent element. But be aware that further nested elements may inherit their font from these classes.
// Sans-serif font stack
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;// Monospaced font stack
font-family: Consolas, 'Liberation Mono', Courier, monospace;The default font size of the <body> element is set to 100%, which is 16 pixels on most browsers. This ensures compatibility with browser-based text zoom and preferences set by the user. Explicit font sizes should be set with relative units, preferably rem. Setting the font size with px can break browser zoom functionality.
Headers
Since search engines use headers to index structure and content, and users skim content by its headers, it's important to use headers semantically. <h1> through <h6> elements represent six levels of hierarchy, <h1> being the highest and <h6> the lowest. Avoiding using <h1> more than once on a page, and avoid skipping heading levels.
<h1>Header Level 1</h1>
<h2>Header Level 2</h2>
<h3>Header Level 3</h3>
<h4>Header Level 4</h4>
<h5>Header Level 5</h5>
<h6>Header Level 6</h6>Header Level 1
Header Level 2
Header Level 3
Header Level 4
Header Level 5
Header Level 6
Paragraphs
Paragraphs inherit the font size of their containing element, which defaults to 1rem/16px inherited from the body element. Paragraphs are styled with line-height: 1.6 and margin-bottom: 1rem for a vertical rhythm that's easy to read.
<p>This is a paragraph...</p>Wide lines of text are difficult to read and make it harder for people to focus. While there's no perfect line length, a good goal fewer than 120 characters per line (including spaces). It's good practice to use responsive design techniques to create layouts with optimal line lengths.
Custom font size
The .text-[size] classes let you adjust the font size of elements.
.text-xxlarge | 2.125rem (≈ 34 pixels) | This is giant. |
.text-xlarge | 1.5625rem (≈ 25 pixels) | This is really big. |
.text-large | 1.25rem (≈ 20 pixels) | This is larger than average. |
.text-medium | 1rem (≈ 16 pixels) | This is medium (default size). |
.text-small | 0.8125rem (≈ 13 pixels) | This is small. Make sure it's accessible. |
.tiny | 0.625rem (≈ 10 pixels) | Be careful with text this tiny. ALL CAPS HELPS. |
Use appropriate, semantic element tags
Do not use <h3> instead of <p> just to make the larger.
Although header tags make fonts bigger and bolder, text should not be inside a header tag if it is not a heading. Header classes are used to give elements a particular header style, regardless of their tag. This allows for both semantic page structure and versatile design.
For example, an <h2> or <p> may be the proper element choice, but they default to specific sizes. You can style an element larger or smaller by adding a .header-[size] class.
<h5 class="header-xxlarge">XXL Heading</h5>
<h5 class="header-xlarge">XL Heading</h5>
<p class="header-large">Large Heading</p>
<p class="header-medium">Medium Heading</p>
<h1 class="header-small">Small Heading</h1>
<h1 class="header-tiny">Tiny Heading</h1>
<p class="lead">This is lead paragraph...</p>XXL Heading
XL Heading
Large Heading
Medium Heading
Small Heading
Tiny Heading
This is lead paragraph. It's larger than a regular paragraph, which makes it noticeably stand out. If you add class="lead" to a paragraph you'll make it a lead paragraph.
Text alignment
Change the text alignment of an element by adding .text-left, .text-right, .text-center or .text-justify.
Adding a breakpoint to the front of a text alignment class will cause it to only be applied on that size screen or larger. For example, .medium-text-center will keep text left-aligned on the smallest screens, but switch to center-aligned on medium screens and larger.
<p class="text-left">This text is left-aligned. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
<p class="text-right">This text is right-aligned. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
<p class="text-center">This text is centered. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
<p class="text-justify">This text is justified. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>This text is left-aligned. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
This text is right-aligned. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
This text is centered. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
This text is justified. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Links
Inline text links are styled as orange text, as orange implies clickability in NYC Planning products. For more information on indicating clickability in the UI, go to the Color section.
<a href="url">link text</a>Never tell users to click here!
There are two reasons why links should never say click here:
"Click" puts too much focus on mouse mechanics. People know what links are and how to use a mouse. Telling them to click is unnecessary, diminishes their experience, and can be even demeaning (they may be using a touch device or assistive technology).
"Here" conceals the content that they are clicking on. You shouldn't have to read a paragraph to understand a link's context. When links communicate more than "here," you can easily scan content to find the link you're looking for.
Good:
Learn more about ZoLa.
Here are some tips for writing proper links:
- Links should provide information when read out of context
- Do not talk about mechanics (clicking)
- A link should be the subject of its sentence (avoid linking verb phrases)
- Placing links at the end of sentences can help users to act more quickly
- When linking to documents, include the filetype in the link text—e.g. Important File (PDF)
Note: Proper link text also has the benefit of being more SEO-friendly.
The target attribute
The target attribute can be used to open a linked document in a new window. This should be used sparingly. Avoid opening new windows for internal links.
<a href="url" target="_blank">link text</a>External links
When linking to external websites and documents, use an icon that indicates to the user that they will be leaving the current website. For example: “Follow NYC Planning on GitHub.” For more information on adding icons, go to the Font Awesome section.
Lists
Unordered lists
Use the <ol> tag to list things if the order of the items doesn't matter.
<ul>
<li>List item</li>
<li>List item</li>
<li>This list item contains another list
<ul>
<li>Nested list item</li>
<li>Another nested list item</li>
</ul>
</li>
<li>List item with a much longer description or more content. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. </li>
</ul>- List item
- List item
- This list item contains another list
- Nested list item
- Another nested list item
- List item with a much longer description or more content. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ordered lists
The <ol> tag defines lists with an explicit order, marked with numbers by default.
The optional type="[1,A,a,I,i]" attribute defines the type of the list item marker.
<ol>
<li>Bicycles</li>
<li>Bike racks</li>
<li>Bike lanes
<ol type="a">
<li>Sharrows</li>
<li>Striped</li>
<li>Buffered</li>
<li>Protected</li>
</ol>
</li>
</ol>- Bicycles
- Bike racks
- Bike lanes
- Sharrows
- Striped
- Buffered
- Protected
Un-bulleted lists
The <ul> is a bulleted list and <ol> is a numbered list by default, but you can add the class .no-bullet to remove the bullets or numbers. This allows lists to have semantic markup and custom styles so they do not look like lists (useful for lists such as menu items).
<ul class="no-bullet">
<li>List item</li>
<li>List item
<ul>
<li>Nested list item</li>
<li>Nested list item</li>
</ul>
</li>
<li>List item</li>
</ul>- List item
- List item
- Nested list item
- Nested list item
- List item
Definition lists
The <dl> tag is used to display name-value pairs, like metadata or a dictionary definition. Each term (<dt>) is paired with one or more definitions (<dd>).
<dl>
<dt>Time</dt>
<dd>The indefinite continued progress of existence and events in the past, present, and future regarded as a whole.</dd>
<dt>Space</dt>
<dd>A continuous area or expanse that is free, available, or unoccupied.</dd>
<dd>The dimensions of height, depth, and width within which all things exist and move.</dd>
</dl>- Time
- The indefinite continued progress of existence and events in the past, present, and future regarded as a whole.
- Space
- A continuous area or expanse that is free, available, or unoccupied.
- The dimensions of height, depth, and width within which all things exist and move.
Blockquotes
<blockquote>
Cities have the capability of providing something for everybody, only because, and only when, they are created by everybody.
<cite>Jane Jacobs</cite>
</blockquote>Cities have the capability of providing something for everybody, only because, and only when, they are created by everybody. Jane Jacobs
Abbreviations
Use the <abbr> tag to annotate a shortened term. Always include a title attribute which clarifies the full term.
<abbr title="Department of Information Technology & Telecommunications">DoITT</abbr> provides infrastructure...
DoITT provides infrastructure...
Note: Abbreviations should be used mindfully. See the acronyms and abbreviations section for more information.
Code
Format references to code with the <code> tag.
Remember to escape angle brackets: <code><div></code>
Remember to escape angle brackets:
<div>
Keystrokes
Use the <kbd> element to annotate a key stroke or combination.
Press <kbd>-</kbd> / <kbd>+</kbd> to zoom the map.
Press - / + to zoom the map.
Dividers
Use the <hr> tag to define a thematic change in the content (a shift of topic). This creates a 1-pixel tall, gray horizontal rule that spans 100% of the width of its container.
<hr />This is a paragraph about apples. This is a paragraph about apples. This is a paragraph about apples. This is a paragraph about apples. This is a paragraph about apples.
This is a paragraph about oranges. This is a paragraph about oranges. This is a paragraph about oranges. This is a paragraph about oranges. This is a paragraph about oranges.