Installation

NPM Install | CDN | Download | Usage

NPM Install

$ npm install @nycopportunity/access-patterns

CDN

Compiled styles and scripts in the /dist folder of the GitHub repository can be imported on the page using a CDN such as JsDelivr. The following global stylesheet link can be copied and pasted into the the <head> of your html document.

<link href="https://cdn.jsdelivr.net/gh/cityofnewyork/access-nyc-patterns@v0.16.1/dist/styles/site-default.css" rel="stylesheet">

The following global script source can copied and pasted before the closing </body> tag of your html document.

<script src="https://cdn.jsdelivr.net/gh/cityofnewyork/access-nyc-patterns@v0.16.1/dist/scripts/access-nyc.js"></script>

With the script integrated, SVG icons can be added with the following snippet.

<script>
  var patterns = new AccessNyc();

  patterns.icons('https://cdn.jsdelivr.net/gh/cityofnewyork/access-nyc-patterns@v0.16.1/dist/svg/icons.svg');
</script>

The following url is the base url for all distributed files available via a CDN.

https://cdn.jsdelivr.net/gh/cityofnewyork/access-nyc-patterns@v0.16.1/dist/

Visit the GitHub repository to browse all available files. All Patterns are distributed with their own styles and script dependencies in the /dist folder. For example, all of the “Accordion” dependencies would live in the /dist/components/accordion folder.

There are regular releases to the patterns which follow semantic versioning. You can keep up-to-date with new releases on each repository’s releases page.

Download

You may also download an archive of the repository to include in your project; Download v0.16.1.zip

Usage

Sass

Sass stylesheets for any pattern can be imported into a project from the source directory.

@use '@nycopportunity/access-patterns/src/components/accordion/accordion';

Specificity

The majority of patterns share the same filename for the Sass and JavaScript (if a pattern uses JavaScript). It may be necessary to specify that you need to import the Sass file for React (or other) applications.

@use '@nycopportunity/access-patterns/src/components/accordion/_accordion.scss';

tailwindcss

Importing tailwindcss is an exception because it is compiled to a Sass file in the dist directory…

@use 'node_modules/@nycopportunity/access-patterns/dist/styles/_tailwindcss.scss';

… and a CSS file in the distribution folder:

<link href="https://cdn.jsdelivr.net/gh/cityofnewyork/access-nyc-patterns@v0.16.1/dist/styles/tailwindcss.css" rel="stylesheet">

Asset Paths and CDN

The styles use the url() for loading webfonts, images, and svgs. By default, it is set to look for asset directories one directory up from the distributed stylesheet so the directory structure of your application is expected to look like so:

styles/site-default.scss
images/..
fonts/..
svg/..

However, you can set the path to a different path that includes all of these files using the $cdn variable.

// $cdn: '../'; (default)
$cdn: 'path/to/assets/';

This variable should be placed above all of your imports of the pattern Sass files. The CDN can be set to another local path (such as an absolute path), or, it can be set to the remote url within the $tokens map.

This default uses jsDelivr to pull the assets from the patterns GitHub repository and the tag of the installed version. ex;

@use 'config/tokens';
$cdn: map-get($tokens, 'cdn');

These are the default paths to the different asset types within the asset folder. Uncomment and set to override their defaults.

$path-to-fonts: 'fonts/';
$path-to-images: 'images/';
$path-to-svg: 'svg/';

This is recommended for Webpack projects using the css-loader because Webpack will try to import the asset into your distributed stylesheet. If you don’t want to change the $cdn variable it is recommended for to disable the url / image-set functions handling with a boolean.

Resolving Paths to Patterns

You can add the string 'node_modules/@nycopportunity/access-patterns/src' to your “resolve” or “include” paths which will allow you to write the shorthand path;

@use 'components/accordion/accordion';

or

@use 'components/accordion/_accordion.scss';

For example; the node-sass includePaths option which is array of paths that attempt to resolve your @use declarations. 

Sass.render({
    file: './src/scss/default.scss',
    outFile: 'site-default.css',
    includePaths: [
      './node_modules',
      './node_modules/@nycopportunity/access-patterns/src'
    ]
  }, (err, result) => {
    Fs.writeFile(`./dist/styles/default.css`, result.css);
  }
});

Similar to the the gulp-sass includePaths option. 

gulp.task('sass', () => {
  return gulp.src('./sass/**/*.scss')
    .pipe(sass.({includePaths: [
      'node_modules',
      'node_modules/@nycopportunity/access-patterns/src'
    ]})).pipe(gulp.dest('./css'));
});

Webpack can be configured with the resolve > modules option. 

module.exports = {
  //...
  resolve: {
    modules: [
      './node_modules',
      './node_modules/@nycopportunity/access-patterns/src'
    ]
  }
};

Scripts

The JavaScript source is written as ES Modules, and using Rollup.js, individual components with JavaScript dependencies are distributed as IFFE functions. Depending on your project, you can import either of these. Below are examples of importing only the accordion component and initializing it.

ES Module Import

import Accordion from 'src/components/accordion/accordion';

new Accordion();

IFFE

<script src="dist/components/accordion.iffe.js"></script>

<script type="text/javascript">
  new Accordion();
</script>

Note You can also use IFFE modules through the CDN installation method without needing using NPM to install in your project.

Global Pattern Script

You may also import the main patterns script with all of the dependencies in it. This script is exported as an IFFE function so it doesn’t need to be compiled but you may want to uglify it. Components must be initialized individually.

<script src="/dist/scripts/access-nyc.js"></script>

<script type="text/javascript">
  var patterns = new AccessNyc();

  patterns.accordion();
</script>

The main JavaScript import file in the source will show how each component needs to be initialized if it isn’t specified in the pattern’s documentation.

Polyfills

The Patterns include a polyfill bundle dist/scripts/polyfill.js using MDN Matches, MDN Closest, MDN Remove, whatwg-fetch and features from the Core JS Standard Libary (a dependency of @babel/preset-env). However, because this bundle includes all required polyfills so it is recommended to build your own polyfill based on your browser coverage requirements.

NYCO Patterns Framework

The ACCESS NYC Patterns are built using the NYCO Patterns Framework; a front-end stack, CLI, and cross-utility library for design systems. These installation instructions are automatically generated by the framework. For more details about the framework visit the GitHub repository.