nyc-planning-style-guide

<!doctype 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="getting-started" class="large-margin-bottom">Getting Started</h1> <section> <p>There are a few ways to incorporate the NYC Planning Digital Style Guide into your project, depending on your tech stack and requirements:</p> <ul class="menu expanded text-center xlarge-margin-bottom"> <li><a href="#cdn" data-smooth-scroll> <i class="fas fa-server fa-4x" style="transform:scale(0.6);"></i> <span class="display-block">**Use a CDN-hosted version**</span> </a></li> <li><a href="#installation" data-smooth-scroll> <span class="text-weight-normal"><i class="fab fa-npm fa-4x"></i></span> <span class="display-block">**Install with package manager**</span> </a></li> <li><a href="#ember-and-labs-ui" data-smooth-scroll> <span class="text-weight-normal"><i class="fab fa-ember fa-4x"></i></span> <span class="display-block">**Use the Ember addon**</span> </a></li> </ul> <p><em>Note: This Style Guide uses the Foundation framework. However, a <a href="#bootstrap" data-smooth-scroll>Bootstrap template</a> is also available.</em></p> </section> <section> <h2 id="cdn">CDN <sup><a href="#cdn" class="silver"><i class="fas fa-link"></i></a></sup></h2> <p>The simplest way to incorporate the Style Guide into your project is to use the files hosted on the <a href="https://unpkg.com/browse/nyc-planning-style-guide/">unpkg.com CDN <i class="fas fa-external-link-alt"></i></a>.</p> <h5 id="1-place-this-link-in-the-head-of-your-html-code">1. Place this link in the head of your HTML code:</h5> <div class="code-example"><pre><code class="html hljs"><span class="hljs-tag"><<span class="hljs-title">link</span> <span class="hljs-attribute">rel</span>=<span class="hljs-value">"stylesheet"</span> <span class="hljs-attribute">href</span>=<span class="hljs-value">"https://unpkg.com/nyc-planning-style-guide@1.0.7/dist/assets/css/nyc-planning.css"</span> /></span></code></pre></div><h5 id="2-and-place-this-script-at-the-end-of-your-code-just-before-the-closing-body-tag">2. And place this script at the end of your code, just before the closing <code></body></code> tag:</h5> <div class="code-example"><pre><code class="html hljs"><span class="hljs-tag"><<span class="hljs-title">script</span> <span class="hljs-attribute">src</span>=<span class="hljs-value">"https://unpkg.com/nyc-planning-style-guide@1.0.7/dist/assets/js/nyc-planning.js"</span>></span><span class="undefined"></span><span class="hljs-tag"></<span class="hljs-title">script</span>></span></code></pre></div><p>That's it! You're all set to start using our CSS classes and JavaScript components.</p> <h4 id="upgrading">Upgrading</h4> <p>If you want to upgrade to a newer release of the Style Guide, update the version number in your CSS and JavaScript URLs — see the <a href="https://unpkg.com/browse/nyc-planning-style-guide/">list of the available releases</a>. If you don't specify a specific version, it will default to the latest version. So be sure to use (and test!) an explicit version in your application to avoid breaking changes.</p> <h4 id="still-need-help">Still need help?</h4> <p>Here's a boilerplate HTML starter template which has everything you need — including the CSS, JavaScript, and the <a href="/icons">FontAwesome icon set</a>:</p> <div class="code-example"><pre><code class="html hljs"><span class="hljs-doctype"><!doctype html></span> <span class="hljs-tag"><<span class="hljs-title">html</span> <span class="hljs-attribute">class</span>=<span class="hljs-value">"no-js"</span> <span class="hljs-attribute">lang</span>=<span class="hljs-value">"en"</span>></span> <span class="hljs-tag"><<span class="hljs-title">head</span>></span> <span class="hljs-tag"><<span class="hljs-title">meta</span> <span class="hljs-attribute">charset</span>=<span class="hljs-value">"utf-8"</span> /></span> <span class="hljs-tag"><<span class="hljs-title">meta</span> <span class="hljs-attribute">http-equiv</span>=<span class="hljs-value">"x-ua-compatible"</span> <span class="hljs-attribute">content</span>=<span class="hljs-value">"ie=edge"</span>></span> <span class="hljs-tag"><<span class="hljs-title">meta</span> <span class="hljs-attribute">name</span>=<span class="hljs-value">"viewport"</span> <span class="hljs-attribute">content</span>=<span class="hljs-value">"width=device-width, initial-scale=1.0"</span> /></span> <span class="hljs-tag"><<span class="hljs-title">title</span>></span>NYC Planning [application name]<span class="hljs-tag"></<span class="hljs-title">title</span>></span> <span class="hljs-tag"><<span class="hljs-title">link</span> <span class="hljs-attribute">rel</span>=<span class="hljs-value">"stylesheet"</span> <span class="hljs-attribute">href</span>=<span class="hljs-value">"https://use.fontawesome.com/releases/v5.8.2/css/all.css"</span> <span class="hljs-attribute">integrity</span>=<span class="hljs-value">"sha384-oS3vJWv+0UjzBfQzYUhtDYW+Pj2yciDJxpsK1OYPAYjqT085Qq/1cq5FLXAZQ7Ay"</span> <span class="hljs-attribute">crossorigin</span>=<span class="hljs-value">"anonymous"</span>></span> <span class="hljs-tag"><<span class="hljs-title">link</span> <span class="hljs-attribute">rel</span>=<span class="hljs-value">"stylesheet"</span> <span class="hljs-attribute">href</span>=<span class="hljs-value">"https://unpkg.com/nyc-planning-style-guide@1.0.7/dist/assets/css/nyc-planning.css"</span>></span> <span class="hljs-tag"></<span class="hljs-title">head</span>></span> <span class="hljs-tag"><<span class="hljs-title">body</span>></span> <span class="hljs-tag"><<span class="hljs-title">h1</span>></span>Hello, world! <span class="hljs-tag"><<span class="hljs-title">i</span> <span class="hljs-attribute">class</span>=<span class="hljs-value">"fas fa-rocket"</span>></span><span class="hljs-tag"></<span class="hljs-title">i</span>></span><span class="hljs-tag"></<span class="hljs-title">h1</span>></span> <span class="hljs-tag"><<span class="hljs-title">script</span> <span class="hljs-attribute">src</span>=<span class="hljs-value">"https://unpkg.com/nyc-planning-style-guide@1.0.7/dist/assets/js/nyc-planning.js"</span>></span><span class="undefined"></span><span class="hljs-tag"></<span class="hljs-title">script</span>></span> <span class="hljs-tag"></<span class="hljs-title">body</span>></span> <span class="hljs-tag"></<span class="hljs-title">html</span>></span></code></pre></div><p><em>Note: Be sure to include the <code>.no-js</code> class on your <code>html</code> tag. Adding this class prevents flash of unstyled content for a number of components.</em></p> <h4 id="download-static-assets">Download static assets</h4> <p>If you'd like the CSS and JavaScript as static assets for your project, you can download the latest files here:</p> <ul> <li><strong>Style</strong>: <a href="../assets/css/nyc-planning.css">nyc-planning.css <i class="fas fa-download"></i></a></li> <li><strong>JavaScript</strong>: <a href="../assets/js/nyc-planning.js">nyc-planning.js <i class="fas fa-download"></i></a></li> </ul> </section> <section> <h2 id="installation">Installation <sup><a href="#installation" class="silver"><i class="fas fa-link"></i></a></sup></h2> <p>This package is available at <a href="https://www.npmjs.com/package/nyc-planning-style-guide">npmjs.com</a>, and includes all of the source Sass and JavaScript files and the compiled CSS and JavaScript. It requires <a href="https://nodejs.org/">Node.js</a> (with <a href="https://www.npmjs.com/">npm</a> or <a href="https://yarnpkg.com/">Yarn</a>) and a <a href="https://sass-lang.com/">Sass</a> compiler (Ruby Sass 3.4+ or libsass 3.3.2+).</p> <h4 id="1-install-the-package">1. Install the package</h4> <div class="code-example"><pre><code class="html hljs">$ npm install nyc-planning-style-guide $ # or $ yarn add nyc-planning-style-guide</code></pre></div><h4 id="2-configure-sass-load-paths">2. Configure Sass load paths</h4> <p>Add Sass load paths for this package and Foundation. How you do this depends on your build process—for example, <code>node-sass</code> can declare load paths by adding a <code>SASS_PATH</code> variable to your <code>.env</code> file:</p> <div class="code-example"><pre><code class="html hljs">SASS_PATH=node_modules:node_modules/foundation-sites/scss:node_modules/nyc-planning-style-guide/src/assets/scss</code></pre></div><p>Regardless of your build process, the load paths are the same:</p> <ul> <li><code>node_modules/</code></li> <li><code>node_modules/foundation-sites/scss</code></li> <li><code>node_modules/nyc-planning-style-guide/src/assets/scss</code></li> </ul> <h4 id="3-set-up-your-scss">3. Set up your <code>.scss</code></h4> <p>Edit your project's Sass file to import/include variables, mixins, and modules in the following order:</p> <ul class="no-margin-bottom"> <li> <div class="grid-x grid-margin-x"> <div class="cell large-5"> <p>Import Foundation's utilities that help us work with colors, units, selectors, and more.</p> </div> <div class="cell large-7"> <div class="code-example"><pre><code class="html hljs">@import 'foundation-sites/scss/util/util';</code></pre></div> </div> </div> </li> <li> <div class="grid-x grid-margin-x"> <div class="cell large-5"> <p>Import the variables file from this package, which includes NYC Planning color palettes and Foundation's utilities and settings.</p> </div> <div class="cell large-7"> <div class="code-example"><pre><code class="html hljs">@import 'nyc-planning-variables';</code></pre></div> </div> </div> </li> <li> <div class="grid-x grid-margin-x"> <div class="cell large-5"> <p>Import Foundation, which includes Sass functions and mixins but does not output any CSS rule-sets.</p> </div> <div class="cell large-7"> <div class="code-example"><pre><code class="html hljs">@import 'foundation';</code></pre></div> </div> </div> </li> <li> <div class="grid-x grid-margin-x"> <div class="cell large-5"> <p>Include Foundation components, which outputs CSS rule-sets for those components. If you don't need everything, you can output a subset of components by including them individually.</p> </div> <div class="cell large-7"> <ul class="tabs" data-tabs id="example-tabs"> <li class="tabs-title is-active"><a data-tabs-target="foundation-include-all" href="#foundation-include-all" aria-selected="true">Everything</a></li> <li class="tabs-title"><a data-tabs-target="foundation-include-some" href="#foundation-include-some">Individually</a></li> </ul> <div class="tabs-content" data-tabs-content="example-tabs"> <div class="tabs-panel is-active" id="foundation-include-all"> <div class="code-example"><pre><code class="html hljs">@include foundation-everything;</code></pre></div> </div> <div class="tabs-panel" id="foundation-include-some"> <div class="code-example"><pre><code class="html hljs">// Global styles @include foundation-global-styles; @include foundation-forms; @include foundation-typography; // Grids (choose one) @include foundation-xy-grid-classes; // @include foundation-grid; // @include foundation-flex-grid; // Generic components @include foundation-button; @include foundation-button-group; @include foundation-close-button; @include foundation-label; @include foundation-progress-bar; @include foundation-slider; @include foundation-switch; @include foundation-table; // Basic components @include foundation-badge; @include foundation-breadcrumbs; @include foundation-callout; @include foundation-card; @include foundation-dropdown; @include foundation-pagination; @include foundation-tooltip; // Containers @include foundation-accordion; @include foundation-media-object; @include foundation-orbit; @include foundation-responsive-embed; @include foundation-tabs; @include foundation-thumbnail; // Menu-based containers @include foundation-menu; @include foundation-menu-icon; @include foundation-accordion-menu; @include foundation-drilldown-menu; @include foundation-dropdown-menu; // Layout components @include foundation-off-canvas; @include foundation-reveal; @include foundation-sticky; @include foundation-title-bar; @include foundation-top-bar; // Helpers @include foundation-float-classes; // @include foundation-flex-classes; @include foundation-visibility-classes; // @include foundation-prototype-classes;</code></pre></div> </div> </div> </div> </li> <li> <div class="grid-x grid-margin-x"> <div class="cell large-5"> <p>Import NYC Planning Sass modules, which outputs CSS rule-sets for our custom components. If you don't need everything, you can output a subset of modules by including them individually.</p> </div> <div class="cell large-7"> <ul class="tabs" data-tabs id="example-tabs"> <li class="tabs-title is-active"><a data-tabs-target="nycplanning-include-all" href="#nycplanning-include-all" aria-selected="true">Everything</a></li> <li class="tabs-title"><a data-tabs-target="nycplanning-include-some" href="#nycplanning-include-some">Individually</a></li> </ul> <div class="tabs-content" data-tabs-content="example-tabs"> <div class="tabs-panel is-active" id="nycplanning-include-all"> <div class="code-example"><pre><code class="html hljs">@import 'modules/nyc-planning-all-modules';</code></pre></div> </div> <div class="tabs-panel" id="nycplanning-include-some"> <div class="code-example"><pre><code class="html hljs">@import 'nyc-planning-m-box-model'; @import 'nyc-planning-m-color'; @import 'nyc-planning-m-layer-groups-menu'; @import 'nyc-planning-m-site-header'; @import 'nyc-planning-m-typography';</code></pre></div> </div> </div> </div> </div> </li> <li> <p>Finally, any custom app modules and styles should come after the files above. Your <code>.scss</code> file should look something like this:</p> <div class="code-example"><pre><code class="html hljs">@import 'foundation-sites/scss/util/util'; @import 'nyc-planning-variables'; @import 'foundation'; @include foundation-everything; @import 'modules/nyc-planning-all-modules'; // My custom app styles @import 'my-app-module'; .peanut-butter { color: Burlywood; }</code></pre></div> </li> </ul> <h4 id="4-javascript-optional">4. JavaScript <small class="text-weight-normal">(optional)</small></h4> <p>This package can be used for its styles alone. However, some interactive components require JavaScript for behaviors such as toggling element class names. There are a few methods for including JavaScript in your project:</p> <ul> <li><p><strong>Use the compiled JavaScript:</strong> Simply load the JavaScript file (<code>/dist/assets/js/nyc-planning.js</code>), which is a compiled combination of Foundation's JavaScript and its dependencies. This is the easiest method but may include unnecessary code.</p> </li> <li><p><strong>Use specific JavaScript components:</strong> Individually load jQuery, What Input, and the specific Foundation JavaScript components and then initialize Foundation. For more information on setting up custom JavaScript, see the <a href="https://foundation.zurb.com/sites/docs/javascript.html">Foundation JavaScript documentation <i class="fas fa-external-link-alt"></i></a>.</p> </li> <li><p><strong>Handle behavior/state yourself:</strong> If you're using a framework that handles state for you (e.g. JavaScript MVCs), it's best to avoid the dependencies of jQuery and Foundation's custom JavaScript. You should instead use your own custom methods to change class names in interactive components. This is how the <a href="#ember-and-labs-ui" data-smooth-scroll>Labs UI</a> addon works, as state is handled by EmberJS.</p> </li> </ul> </section> <section> <h2 id="ember-and-labs-ui">Ember and Labs UI <sup><a href="#ember-and-labs-ui" class="silver"><i class="fas fa-link"></i></a></sup></h2> <p>Labs UI is an EmberJS addon that contains common components used in NYC Planning digital products. It consumes Sass files from this package to style its components. Since Ember handles behavior and state management, Labs UI does not include any JavaScript from this package.</p> <p>For more information, see the <strong><a href="https://ui.planninglabs.nyc/">Labs UI documentation</a></strong>.</p> </section> <section> <h2 id="bootstrap">Bootstrap <sup><a href="#bootstrap" class="silver"><i class="fas fa-link"></i></a></sup></h2> <p>This Style Guide is built upon the Foundation front-end framework. However, if your project requires the <a href="https://getbootstrap.com/">Bootstrap</a> framework, the settings used for Foundation have been translated into a Bootstrap template.</p> <p>Although the code samples in this Style Guide use Foundation's syntax (which differs from Bootstrap's defaults), this Bootstrap template attempts to port over as much of Foundation as possible so that either syntax can be used. For example, using either Bootstrap's or Foundation's button syntax will work:</p> <div class="code-example"> <pre><code class="html"><a class="btn" href="#">Bootstrap Button</a> <a class="button" href="#">Foundation Button</a></code></pre> </div> <div class="callout"> <button class="button no-margin">Bootstrap Button</button> <button class="button no-margin">Foundation Button</button> </div> <p>There are two ways to incorporate the Bootstrap template into your project, depending on your tech stack and requirements:</p> <h4>1. Download static assets</h4> <p>If you'd like the CSS and JavaScript as static assets for your project, you can download the latest files here:</p> <ul> <li><strong>Style</strong>: <a href="../assets/bootstrap/custom.css">custom.css <i class="fas fa-download"></i></a></li> <li><strong>JavaScript</strong>: <a href="../assets/bootstrap/bootstrap.bundle.js">bootstrap.bundle.js <i class="fas fa-download"></i></a></li> </ul> <h4 id="custom-installation">2. Build Bootstrap yourself</h4> <p>If you'd prefer to customize your Bootstrap installation:</p> <ol> <li class="medium-margin-bottom">Download the <a href="https://github.com/twbs/bootstrap" target="_blank">latest version of Bootstrap <i class="fas fa-external-link-alt"></i></a></li> <li class="medium-margin-bottom">Run <code>npm install</code> to install the Node.js dependencies</li> <li class="medium-margin-bottom">Run <code>npm install what-input</code> to install what-input</li> <li class="medium-margin-bottom">Add the statement <code>import 'what-input'</code> to <code>/js/src/index.js</code></li> <li class="medium-margin-bottom">Replace <code>/scss/_variables.scss</code> with <a href="../assets/bootstrap/_variables.scss">_variables.scss <i class="fas fa-download"></i></a></li> <li class="medium-margin-bottom">Replace <code>/scss/utilities/_background.scss</code> with <a href="../assets/bootstrap/_background.scss">_background.scss <i class="fas fa-download"></i></a></li> <li class="medium-margin-bottom">Add <a href="../assets/bootstrap/custom.scss">custom.scss <i class="fas fa-download"></i></a> to the <code>/scss/</code> directory</li> <li class="medium-margin-bottom">Make any desired changes</li> <li class="medium-margin-bottom">Run <code>npm run dist</code> to rebuild your CSS and JavaScript files</li> </ol> </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">  <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 active">Getting Started</a> <ul class="medium-margin-bottom text-small"> <li><a href="#cdn">CDN</a></li> <li><a href="#installation">Installation</a></li> <li><a href="#ember-and-labs-ui">Ember and Labs UI</a></li> <li><a href="#bootstrap">Bootstrap</a></li> </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 ">Voice & Language</a> <ul class="medium-margin-bottom text-small"> </ul> </li> </ul> </div> </div> </div> </div> <script src="../assets/js/nyc-planning.js"></script> </body> </html>