nyc-planning-style-guide
Version:
Base styles for NYC Department of City Planning (using Foundation for Sites)
389 lines (368 loc) • 22.1 kB
HTML
<html class="no-js" lang="en">
<head>
<meta charset="utf-8" />
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>NYC Planning Digital Style Guide</title>
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.8.2/css/all.css" integrity="sha384-oS3vJWv+0UjzBfQzYUhtDYW+Pj2yciDJxpsK1OYPAYjqT085Qq/1cq5FLXAZQ7Ay" crossorigin="anonymous">
<link rel="stylesheet" href="../assets/css/nyc-planning.css">
<style>
.header-logo {
max-height: 4.5rem;
}
.code-example code {
display: block;
padding: 1rem;
overflow-x: scroll;
margin-bottom: 1.5rem;
}
.is-stuck{
max-height: 100vh;
overflow: auto;
}
.code-example + .callout,
.code-example + table {
margin-top: calc(-1px - 1.5rem);
}
section + section {
margin-top: 3rem;
padding-top: 3rem;
border-top: 1px solid #d3d5d9;
}
section h4 {
margin-top: 1.5rem;
}
section .code-example + h4 {
margin-top: 0;
}
.callout.clear {
background-color: transparent;
border-color: transparent;
}
.color-swatch {
list-style: none;
margin: 0;
padding: 2.5rem 0.75rem 0.75rem;
line-height: 1.4;
}
</style>
</head>
<body id="top">
<header class="xlarge-padding-top large-padding-bottom bg-white-smoke">
<div class="grid-container">
<div class="grid-x text-center medium-text-left align-middle">
<div class="cell medium-shrink">
<img class="header-logo medium-margin-right medium-margin-bottom" src="https://raw.githubusercontent.com/NYCPlanning/dcp-logo/master/dcp_logo_772.png" alt="NYC Planning" />
</div>
<div class="cell medium-auto">
<h1 class="no-margin">Digital Style Guide</h1>
<p class="medium-margin-bottom">Standards, Code Snippets, & Assets</p>
</div>
<p class="cell medium-shrink no-margin show-for-medium">
<a href="https://github.com/NYCPlanning/nyc-planning-style-guide">
<i class="fab fa-github fa-2x small-margin text-light-gray"></i>
1.0.7
</a>
</p>
</div>
</div>
</header>
<div id="main-content" class="grid-container">
<div class="grid-x grid-margin-x">
<div class="medium-8 large-9 cell medium-order-2 large-padding-top large-padding-bottom">
<h1 id="voice-and-language" class="large-margin-bottom">Voice & Language</h1>
<section>
<p>Content that is clear, relevant, and reader-friendly helps provide a great user experience. Language that is concise and literal allows for more accurate automated translations and makes information more accessible. Focus on simple and succinct sentences. Avoid governmental jargon and legalese.</p>
<p>We aim to be clear and conversational, yet professional. To be as clear as possible, strip sentences down to the <strong>actors</strong> and <strong>actions</strong>. The use of active voice is preferred to <strong>passive voice</strong>.</p>
<ul>
<li><p>Be conscious of the placement of the subjects of sentences—e.g. say <u>the applicant proposed changes</u> instead of <u>the changes were proposed by the applicant</u>.</p>
</li>
<li><p>Be conscious of the use of the verb "to be." When the subject of your sentence comes after the verb, you are writing in <strong>passive voice</strong>.</p>
</li>
<li><p>Avoid citations. If needed, integrate into text—e.g. <u>according to the Department of Parks and Recreation</u>.</p>
</li>
<li><p>Alternate long and short sentences to help your writing flow better. Focus on one thought per sentence.</p>
</li>
<li><p><strong>Avoid repeating words</strong> in the same sentence, or beginning multiple sentences with the same word or phrase.</p>
</li>
</ul>
</section>
<section>
<h3 id="acronyms-and-abbreviations">Acronyms and abbreviations <sup><a href="#acronyms-and-abbreviations" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<ul>
<li><p><strong>Agencies</strong> and <strong>organizations</strong> should always be spelled out on first reference, followed by the common abbreviation or acronym in parenthesis. On following references, the abbreviated agency name is preferred to the agency acronym—e.g. on second reference, <u>Department of Parks & Recreation</u> should be referred to as <u>Parks</u> not <u>DPR</u>.</p>
</li>
<li><p><strong>Avoid the acronym <u>DCP</u>.</strong> Since users tend to scan content, acronyms can be read without the first defining instance having been seen. <u>New York City Department of City Planning</u> should instead be shortened to <u>NYC Planning</u> and never <u>DCP</u>.</p>
</li>
<li><p><strong>Ampersands</strong> (&) and <strong>percent signs</strong> (%) should be written out. However, it's acceptable to use the symbols in subheadings, charts, graphs, and web buttons if they're used consistently.</p>
</li>
<li><p><strong>Use the <code><abbr></code> tag</strong> to indicate abbreviations. See the <a href="#abbreviations" data-smooth-scroll>abbreviations</a> section for more information._</p>
</li>
</ul>
</section>
<section>
<h3 id="addresses">Addresses <sup><a href="#addresses" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<ul>
<li><p>Always use numerals when writing out building numbers in addresses.</p>
</li>
<li><p>In reference to specific street names, always spell out and capitalize words like <u>Boulevard</u>, <u>Avenue</u>, and <u>Street</u>. For street names that are also numbers, spell out and capitalize <u>First</u> through <u>Ninth</u> and use figures for <u>10th</u> and higher—e.g <u>Fifth Ave</u> and <u>11th Ave</u>.</p>
</li>
<li><p>If a street name includes a cardinal direction, abbreviate North, South, East and West only when referring to a specific building—e.g. <u>326 W. 17th Street</u> or <u>East 34th Street</u>. Do not capitalize cardinal directions when they indicate a general direction or location—e.g. <u>north of North 12th Street</u>.</p>
</li>
</ul>
</section>
<section>
<h3 id="phone-numbers">Phone numbers <sup><a href="#phone-numbers" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<ul>
<li>Phone numbers use hyphens between groups of numbers—e.g. <u>212-123-4567</u>. Do not use parentheses around area codes. Area codes and country codes get no special treatment and aren't preceded by a 1 or plus sign.</li>
</ul>
</section>
<section>
<h3 id="capitalization">Capitalization <sup><a href="#capitalization" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<ul>
<li><p><strong>Titles</strong> should always be capitalized when they appear before a person's name.</p>
</li>
<li><p>Follow sentence case for <strong>web buttons</strong> that include three or more words. Use title case for buttons with only one or two words. Using punctuation in buttons is up to the discretion of the writer.</p>
</li>
<li><p><strong>Charter</strong> should always be capitalized when used in reference to the New York City Charter.</p>
</li>
<li><p><strong>City</strong> should be capitalized when referring to New York City.</p>
</li>
<li><p><strong>District</strong> should be capitalized when referring to NYC Community Districts or Council Districts—e.g. <u>the 11th Council District</u>, or <u>within several Districts</u>).</p>
</li>
<li><p>Titles such as <strong>Chair</strong>, <strong>Mayor</strong>, and <strong>Speaker</strong> should always be capitalized when used in reference to their position—e.g. <u>Chair of the City Planning Commission</u> or <u>Mayor of New York City</u> or <u>Speaker of the New York City Council.</u></p>
</li>
<li><p>Capitalize the first word of a <strong>subheading</strong>. Punctuating subheadings is acceptable for questions. Other forms of subhead punctuation are up to the discretion of the writer.</p>
</li>
<li><p>Lowercase adjectives that describe status of a title—e.g. <u>the former Speaker Christine Quinn</u>.</p>
</li>
</ul>
</section>
<section>
<h3 id="compositions">Compositions <sup><a href="#compositions" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<ul>
<li>Use quotation marks around titles of works of art and compositions, like books, songs, television shows, video games, and poems—e.g. say <u>"The Grapes of Wrath"</u> not <u><i>The Grapes of Wrath</i></u>. Do not use quotations or italics for names of publications—e.g. <u>The New York Times</u>.</li>
</ul>
</section>
<section>
<h3 id="contractions">Contractions <sup><a href="#contractions" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<ul>
<li>Use common contractions like <strong>isn't</strong>, <strong>won't</strong>, and <strong>you'll</strong> when possible to set a more conversational tone.</li>
</ul>
</section>
<section>
<h3 id="names">Names <sup><a href="#names" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<ul>
<li>Always use a person's title, first and last name upon first reference. Use title and last name for following references. Do not use courtesy titles, unless needed to differentiate between people who have the same last name.</li>
</ul>
</section>
<section>
<h3 id="numbers">Numbers <sup><a href="#numbers" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<ul>
<li><p>Spell out numbers <strong>one</strong> through <strong>nine</strong>. Use numerals for numbers <strong>10 and greater</strong>. Always spell out numbers that begin sentences, unless it's a year—e.g. <u>2006 was a great year</u>. For numbers in the millions, billions or trillions, use a number and word—e.g. <u>1 billion</u> or <u>4.8 million</u>. Large numbers can be abbreviated in charts and graphs if they're used consistently—e.g. <u>1B</u> or <u>4.8M</u>.</p>
</li>
<li><p>When referring to <strong>money</strong>, always use numerals preceded with a dollar sign—e.g. <u>$400</u>. When referencing an amount of money less than $1, use numerals and spell out the word cents—e.g. <u>30 cents</u>.</p>
</li>
<li><p>For <strong>dates</strong>, avoid using ordinal numbers (1st, 2nd, 3rd). Instead use figures—e.g. <u>March 7, 1980</u>.</p>
</li>
<li><p>Always use numerals for <strong>units</strong>. Spell out words like pounds, feet, and ounces. Units can be abbreviated in charts and graphs if they're used consistently—e.g. <u>600 ft.</u></p>
</li>
<li><p>The word <strong>percent</strong> should almost always be written out. A percent sign (%) may be used for charts, graphs, and subheadings.</p>
</li>
<li><p>Always use numerals for percentages—e.g. <u>30 percent</u> or <u>6 percent</u>.</p>
</li>
<li><p>Use numerals in reference to <strong>age</strong>. Hyphenate ages when used as an adjective before a noun or in substitution for a noun—e.g. <u>the 20-year-old student</u> or <u>the 8-year-olds</u>). Don't use an apostrophe when describing a period of time—e.g. <u>in their 20s</u> or <u>the 1950s</u>.</p>
</li>
</ul>
</section>
<section>
<h3 id="hyperlinks">Hyperlinks <sup><a href="#hyperlinks" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<ul>
<li>Avoid hyperlinking <strong><a>read here</a></strong> or <strong><a>click here</a></strong>. Hyperlinked text should always be descriptive to give readers a solid understanding of the linked content. Learn more about writing links in the <a href="#links" data-smooth-scroll>links</a> section.</li>
</ul>
</section>
<section>
<h3 id="hashtags">Hashtags <sup><a href="#hashtags" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<p>Hashtags should be written in #CamelCase. Each word in the hashtag's phrase should begin with a capital letter. Acronyms within hashtags should be all capitals. Be careful when combining acronyms with other words—e.g. <u>#NYCHealth</u> reads as "New York City Health," whereas <u>#NYChealth</u> reads as "New York Chealth."</p>
</section>
<section>
<h3 id="pronouns">Pronouns <sup><a href="#pronouns" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<ul>
<li><p>Pronouns like <strong>you</strong> and <strong>ours</strong> should be used at the writer's discretion to address readers or services we are providing. This helps humanize the City Planning's voice and makes us seem much more conversational and approachable.</p>
</li>
<li><p>Always use the singular form of <strong>they</strong> when referring to an abstract person—e.g. say <u>when they contact the lead planner</u> not <u>when he/she contacts the lead planner</u>.</p>
</li>
</ul>
</section>
<section>
<h3 id="punctuation">Punctuation <sup><a href="#punctuation" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<ul>
<li><p><strong>Apostrophes</strong>: Add an apostrophe-s to all singular nouns, even if the noun ends in s. Use only an apostrophe with a singular noun if the following word begins with s—e.g. <u>the boss's hat</u> or <u>the boss' style</u>. Only use an apostrophe for a proper noun that ends in s—e.g. <u>Districts' residents</u>.</p>
</li>
<li><p><strong>Bullets</strong>: Capitalize the first word of every bullet. Include a period only when the bulleted item is a complete sentence.</p>
</li>
<li><p><strong>Colons</strong>: Capitalize the first word after a colon only if what follows makes a complete sentence.</p>
</li>
<li><p><strong>Commas</strong>: Always use the serial comma, also known as the Oxford comma.</p>
</li>
<li><p><strong>Dashes</strong>: Em dashes should be used—without spaces between them and adjacent words—to offset phrases. Avoid using en dashes when referring to ranges. Instead, spell out <u>to</u>, <u>and</u>, or <u>through</u>.</p>
</li>
<li><p><strong>Dates</strong>: Always use the full name of the month—e.g. say <u>March 3, 2016</u> not <u>Mar 3, 2016</u>.</p>
</li>
<li><p><strong>Quotation marks</strong>: Periods and commas go inside quotation marks.</p>
</li>
</ul>
</section>
<section>
<h3 id="words-to-avoid">Words to avoid <sup><a href="#words-to-avoid" class="silver"><i class="fas fa-link"></i></a></sup></h3>
<p>Figurative, or superfluous, language can be confusing. It also makes translation into additional languages difficult. Here are some examples of words to avoid:</p>
<ul>
<li><strong>Stand</strong> <small>(often used in social movements, but not inclusive of people with physical disabilities)</small></li>
<li><strong>Drive</strong> <small>(use a word like <u>lead</u> instead)</small></li>
<li><strong>Drive out</strong> <small>(use <u>eliminate</u> or <u>push away</u> instead)</small></li>
<li><strong>Going forward</strong> <small>(use <u>in the future</u> instead)</small></li>
<li><strong>In order to</strong> <small>(the words "in order" are unnnecessary; just say <u>to</u> instead)</small></li>
<li><strong>One-stop shop</strong> <small>(describe the item literally—e.g. <u>a tool with comprehensive services</u>)</small></li>
</ul>
<p>Strive to use as few words as possible, especially <strong>jargon</strong> and <strong>buzzwords</strong>, as their meanings are often lost on readers. Opt instead for words that are more specific and descriptive. Here's a list of words that are used idiomatically, along with more literal suggestions:</p>
<div class="grid-x grid-margin-x">
<div class="cell large-6">
<h4>Idioms and misnomers</h4>
<p>Use literal and specific nouns rather than expressions or objects in a metaphorical context. For example:</p>
<ul>
<li><u>Our office is low bandwidth due to a plumbing issue</u> is abstract</li>
<li><u>Our office hours will end early due to plumbing issues</u> is literal</li>
</ul>
<h6>Other examples:</h6>
<ul>
<li><strong>agenda</strong> <small>(use plan or intention)</small></li>
<li><strong>llegals/illegal aliens</strong> <small>(use undocumented immigrants or people without immigration status)</small></li>
<li><strong>thought leader</strong> <small>(describe person's specific accomplishments)</small></li>
<li><strong>touchpoint</strong> <small>(refer to actual components)</small></li>
<li><strong>user testing</strong> <small>(unless you're actually testing the users, use usability testing)</small></li>
</ul>
</div>
<div class="cell large-6">
<h4>Verbs</h4>
<p>Use the specific, literal action and sentence subject rather than a hard-to-understand abstraction of that action. For example:</p>
<ul>
<li><u>empowered the use of waterfront</u> is abstract</li>
<li><u>created public space on the waterfront</u> is literal</li>
</ul>
<h6>Other examples:</h6>
<div class="grid-x grid-margin-x">
<div class="cell large-5" style="margin-bottom:0;">
<ul>
<li><strong>collaborate</strong></li>
<li><strong>combating</strong></li>
<li><strong>countering</strong></li>
<li><strong>dialogue</strong></li>
<li><strong>facilitate</strong></li>
<li><strong>foster</strong></li>
<li><strong>impact</strong> <small>(as a verb)</small></li>
<li><strong>initiate</strong></li>
</ul>
</div>
<div class="cell large-7">
<ul>
<li><strong>land</strong> <small>(as verb)</small></li>
<li><strong>leverage</strong> <small>(implies financial)</small></li>
<li><strong>progress</strong> <small>(as a verb)</small></li>
<li><strong>promote</strong> <small>(implies advertising)</small></li>
<li><strong>streamline</strong></li>
<li><strong>tackle</strong> <small>(implies football)</small></li>
<li><strong>transform</strong></li>
<li><strong>utilize</strong></li>
</ul>
</div>
</div>
</div>
</div>
</section>
</div>
<div class="medium-4 large-3 cell medium-order-1" data-sticky-container>
<div class="sticky large-padding-top large-padding-bottom" data-sticky data-margin-top="0" data-anchor="main-content">
<!-- <input id="showCodesCheckbox" type="checkbox"><label for="showCodesCheckbox">Show Code Examples</label> -->
<ul class="no-bullet" data-smooth-scroll data-animation-easing="swing">
<li>
<a href="/" class="text-weight-bold display-inline-block ">Overview</a>
<ul class="medium-margin-bottom text-small">
</ul>
</li>
<li>
<a href="/getting-started" class="text-weight-bold display-inline-block ">Getting Started</a>
<ul class="medium-margin-bottom text-small">
</ul>
</li>
<li>
<a href="/logo" class="text-weight-bold display-inline-block ">Logo</a>
<ul class="medium-margin-bottom text-small">
</ul>
</li>
<li>
<a href="/color" class="text-weight-bold display-inline-block ">Color</a>
<ul class="medium-margin-bottom text-small">
</ul>
</li>
<li>
<a href="/icons" class="text-weight-bold display-inline-block ">Icons</a>
<ul class="medium-margin-bottom text-small">
</ul>
</li>
<li>
<a href="/typography" class="text-weight-bold display-inline-block ">Typography</a>
<ul class="medium-margin-bottom text-small">
</ul>
</li>
<li>
<a href="/forms" class="text-weight-bold display-inline-block ">Forms</a>
<ul class="medium-margin-bottom text-small">
</ul>
</li>
<li>
<a href="/navigation" class="text-weight-bold display-inline-block ">Navigation</a>
<ul class="medium-margin-bottom text-small">
</ul>
</li>
<li>
<a href="/accessibility" class="text-weight-bold display-inline-block ">Accessibility</a>
<ul class="medium-margin-bottom text-small">
</ul>
</li>
<li>
<a href="/layout" class="text-weight-bold display-inline-block ">Layout</a>
<ul class="medium-margin-bottom text-small">
</ul>
</li>
<li>
<a href="/maps" class="text-weight-bold display-inline-block ">Maps</a>
<ul class="medium-margin-bottom text-small">
</ul>
</li>
<li>
<a href="/voice-and-language" class="text-weight-bold display-inline-block active">Voice & Language</a>
<ul class="medium-margin-bottom text-small">
<li><a href="#acronyms-and-abbreviations">Acronyms and abbreviations</a></li>
<li><a href="#addresses">Addresses</a></li>
<li><a href="#phone-numbers">Phone numbers</a></li>
<li><a href="#capitalization">Capitalization</a></li>
<li><a href="#compositions">Compositions</a></li>
<li><a href="#contractions">Contractions</a></li>
<li><a href="#names">Names</a></li>
<li><a href="#numbers">Numbers</a></li>
<li><a href="#hyperlinks">Hyperlinks</a></li>
<li><a href="#hashtags">Hashtags</a></li>
<li><a href="#pronouns">Pronouns</a></li>
<li><a href="#punctuation">Punctuation</a></li>
<li><a href="#words-to-avoid">Words to avoid</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
<script src="../assets/js/nyc-planning.js"></script>
</body>
</html>