Getting Started

There are a few ways to incorporate the NYC Planning Digital Style Guide into your project, depending on your tech stack and requirements:

Note: This Style Guide uses the Foundation framework. However, a Bootstrap template is also available.

CDN

The simplest way to incorporate the Style Guide into your project is to use the files hosted on the unpkg.com CDN .

1. Place this link in the head of your HTML code:

<link rel="stylesheet" href="https://unpkg.com/nyc-planning-style-guide@1.0.7/dist/assets/css/nyc-planning.css" />

2. And place this script at the end of your code, just before the closing `</body>` tag:

<script src="https://unpkg.com/nyc-planning-style-guide@1.0.7/dist/assets/js/nyc-planning.js"></script>

That's it! You're all set to start using our CSS classes and JavaScript components.

Upgrading

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 list of the available releases. 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.

Still need help?

Here's a boilerplate HTML starter template which has everything you need — including the CSS, JavaScript, and the FontAwesome icon set:

<!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 [application name]</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="https://unpkg.com/nyc-planning-style-guide@1.0.7/dist/assets/css/nyc-planning.css">
  </head>
  <body>
    <h1>Hello, world! <i class="fas fa-rocket"></i></h1>

    <script src="https://unpkg.com/nyc-planning-style-guide@1.0.7/dist/assets/js/nyc-planning.js"></script>
  </body>
</html>

Note: Be sure to include the .no-js class on your html tag. Adding this class prevents flash of unstyled content for a number of components.

Download static assets

If you'd like the CSS and JavaScript as static assets for your project, you can download the latest files here:

Style: nyc-planning.css
JavaScript: nyc-planning.js

Installation

This package is available at npmjs.com, and includes all of the source Sass and JavaScript files and the compiled CSS and JavaScript. It requires Node.js (with npm or Yarn) and a Sass compiler (Ruby Sass 3.4+ or libsass 3.3.2+).

1. Install the package

$ npm install nyc-planning-style-guide
$ # or
$ yarn add nyc-planning-style-guide

2. Configure Sass load paths

Add Sass load paths for this package and Foundation. How you do this depends on your build process—for example, node-sass can declare load paths by adding a SASS_PATH variable to your .env file:

SASS_PATH=node_modules:node_modules/foundation-sites/scss:node_modules/nyc-planning-style-guide/src/assets/scss

Regardless of your build process, the load paths are the same:

node_modules/
node_modules/foundation-sites/scss
node_modules/nyc-planning-style-guide/src/assets/scss

3. Set up your `.scss`

Edit your project's Sass file to import/include variables, mixins, and modules in the following order:

Import Foundation's utilities that help us work with colors, units, selectors, and more.
```
@import 'foundation-sites/scss/util/util';
```
Import the variables file from this package, which includes NYC Planning color palettes and Foundation's utilities and settings.
```
@import 'nyc-planning-variables';
```
Import Foundation, which includes Sass functions and mixins but does not output any CSS rule-sets.
```
@import 'foundation';
```

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.

Everything
Individually

@include foundation-everything;

// 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;

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.

Everything
Individually

@import 'modules/nyc-planning-all-modules';

@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';

Finally, any custom app modules and styles should come after the files above. Your .scss file should look something like this:

@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;
}

4. JavaScript (optional)

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:

Use the compiled JavaScript: Simply load the JavaScript file (/dist/assets/js/nyc-planning.js), which is a compiled combination of Foundation's JavaScript and its dependencies. This is the easiest method but may include unnecessary code.
Use specific JavaScript components: 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 Foundation JavaScript documentation .
Handle behavior/state yourself: 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 Labs UI addon works, as state is handled by EmberJS.

Ember and Labs UI

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.

For more information, see the Labs UI documentation.

Bootstrap

This Style Guide is built upon the Foundation front-end framework. However, if your project requires the Bootstrap framework, the settings used for Foundation have been translated into a Bootstrap template.

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:

<a class="btn" href="#">Bootstrap Button</a>
<a class="button" href="#">Foundation Button</a>

There are two ways to incorporate the Bootstrap template into your project, depending on your tech stack and requirements:

1. Download static assets