Tailwindcss

About Utilities

Utilities allow the flexibility to change specific properties of every Pattern in certain views. For example, if a Pattern is set to display: block in one view but in another it needs to be set to display: inline, one solution would be to create another type of the Pattern. However, a UI developer may need to repeat this process for other Patterns. Writing alternate versions of Patterns is less efficient for UI development.

A utility class, such as .inline { display: inline }, allows the developer to reuse this attribute without creating a different pattern type or writing more CSS. This use case can be extended to every possible CSS attribute, such as color, position, font-families, margin, padding, etc. In addition, they can be bundled within media queries so certain utilities can work for specific screen sizes.

A simple example for using a utility to add padding to an element would be to use the utility .p-1. This will add 8px of padding on all sides of an element.

CSS 

.py-1 { padding: 8px }
.px-2 { padding: 16px }
.border { border: 1px }

HTML 

<div class="border py-1 px-2">
  An element styled with utilities
</div>

Renders

An element styled with utilities

Utilities and Design Tokens

Utilities can also be used to create new components that are not readily available in a pattern library. This enables scale of the design system but maintains the relationship with the design through it’s tokens. While some utilities are very CSS centric for front-end development purposes (display, accessibility, position, etc.) others are programmatic implementations of the design tokens that make the system unique (colors, typography, grid, etc.).

CSS 

.p-2 { padding: 16px }
.bg-blue { background-color: #284CCA }
.shadow-up { box-shadow: 8px 8px 0px 0px }
.text-base-white { color: #FFF }

HTML 

<div class="bg-blue shadow-up rounded p-2">
  <div class="text-base-white">An element styled with utilities.</div>
</div>

Renders

An element styled with utilities.

Tailwindcss

Working NYC Patterns integrates Tailwindcss, a CSS utility-first framework that is customized with Working NYC Patterns design tokens. There are three parts to the Tailwindcss configuration.

  • Core Plugins: This array is a white list of utility plugins that defines what sets of utilities will be compiled in the final stylesheet distribution. Source documentation. Example; the core plugin for padding is padding. Adding or removing it to the array will determine wether those utilities are compiled to the global stylesheet.

  • Variants: This object contains variants that represent different states that the utilities appear in such as media queries, :hover, and :focus states. Source documentation. Example; to have padding only appear for desktop screens within Working NYC Patterns the variant desktop: is added to the .p-1 utility: <div class="desktop:p-1"></div>.

  • Theme: This object contains Working NYC Patterns tokens for particular utilities such as font families, colors, margin, padding, etc. Source documentation. Example; the padding plugin is customized to use 8px as the basis for all padding increments. .p-2 would add 8px × 2 = 16px padding on all sides of an element: <div class="p-2"></div>.

The current configuration source describes which core plugins are enabled, what variants they use, and if they are themed with the Working NYC Patterns design tokens.

Tailwindcss Logical

The Tailwindcss Logical plugin extends the utility set with CSS logical properties. Working NYC Patterns includes this plugin in its Tailwindcss implementation. This particularly useful for languages that use right-to-left reading directions. Supported properties are described in the plugin’s readme file.

Installation

As a stylesheet

Tailwindcss is not imported the same way as other patterns. All utilities are compiled to a Sass file /dist/styles/_tailwindcss.scss which can be imported in a Sass project.

@import 'node_modules/@nycopportunity/working-patterns/dist/styles/_tailwindcss.scss';

They are also available as compiled a CSS file in the /dist folder:

/dist/styles/tailwindcss.css

The CSS file can be included through a CDN with the latest release (0.0.1-60).

<link href="https://cdn.jsdelivr.net/gh/cityofnewyork/working-nyc-patterns@v0.0.1-60/dist/styles/tailwindcss.css" rel="stylesheet" type="text/css">

As a dependency

It is also possible to install Tailwindcss as a dependency in your project and import the Working NYC Patterns tailwindcss.js configuration into your project. See the Tailwindcss integration guides for various projects. Below is the full path to the configuration file.

node_modules/@nycopportunity/working-patterns/config/tailwindcss.js

Production distributions

It is highly recommended to remove unused CSS classes in your stylesheet. The output of Tailwindcss produces a very large stylesheet with many utilities that won’t be used in your project.

Tailwind UI

Tailwind UI is a secondary product from the creators of Tailwindcss. It includes some examples of complete components built using the default Tailwindcss utility library. For the most part these examples could be built using the Working NYC Patterns Tailwindcss implementation. There will be some differences in colors, drop shadows, type, dimensions, etc.