Patterns

2.3.2

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 and flexible for UI development.

A Utility class, such as .inline { display: inline }, allows the developer to reuse this attribute without creating a different pattern type. 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.

Tailwindcss

tailwindcss

NYCO Patterns integrates tailwindcss, a CSS utility-first framework processed by PostCSS that supports custom configuration. The NYCO Patterns configuration lives in config/tailwind.js and below is a table describing the current configuration.

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.

.p-1 {
  padding: 8px
}

<div class="p-1"></div>

Configuration

There are three parts to the NYCO Patterns tailwindcss configuration.

  • Theme: This object contains customizations for particular utilities such as font families, colors, margin, padding, etc. Source documentation.
  • Variants: This object contains variants that represent different states that the utilities appear in such as media queries, :hover, and :focus states. Source documentation.
  • 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.

Theme

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>

Colors are part of the theme configuration but are described in more detail in the NYCO Patterns Color Utility documentation.

Variants

Example; to have padding only appear for desktop screens within NYCO Patterns the prefix screen-desktop: is added to the .p-1 utility.

<div class="screen-desktop:p-1"></div>

The plugin table below describes the available variants for each utility. An empty array [] means only the default state is available. The screens theme configuration describes the avaliable break points for the responsive variants.

Core Plugins

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.

NYCO × tailwindcss configuration

Theme

Plugin (link to docs)
border width
border radius
box shadow
colors
font family
font weight
font size
line height
margin
max width
padding
screens
width

Variants and Core Plugins

Plugin (link to docs)
Variants
Configuration
accessibility
[responsive]
Default
background color
[hover, focus]
Default
border color
[hover, focus]
Default
border style
[]
Default
border width
[responsive]
cursor
[]
Default
display
[responsive]
Default
flex direction
[responsive]
Default
flex wrap
[responsive]
Default
align items
[responsive]
Default
align self
[responsive]
Default
justify content
[responsive]
Default
align content
[responsive]
Default
flex
[responsive]
Default
flex grow
[responsive]
Default
flex shrink
[responsive]
Default
order
[responsive]
Default
height
[]
Default
list style type
[]
Default
margin
[responsive]
max height
[]
Default
max width
[responsive]
min height
[responsive]
Default
min width
[]
Default
overflow
[responsive]
Default
padding
[responsive]
pointer events
[]
Default
position
[]
Default
inset
[]
Default
box shadow
[responsive]
fill
[]
Default
stroke
[]
Default
text align
[]
Default
text color
[hover, focus]
Default
font size
[responsive]
font style
[]
Default
text transform
[]
Default
text decoration
[]
Default
font smoothing
[]
Default
user select
[]
Default
vertical align
[]
Default
visibility
[]
Default
whitespace
[]
Default
width
[responsive]
z index
[]
Default

Installation

tailwindcss is not imported the same way as other patterns. All utilities are compiled to a Sass file…

/dist/utilities/tailwindcss/_tailwindcss.scss

(which can be imported in a Sass project)…

@import 'node_modules/@nycopportunity/nyco-patterns/dist/utilities/tailwindcss/_tailwindcss.scss';

… and a CSS file in the /dist folder:

/dist/utilities/tailwindcss/tailwindcss.css

The CSS file can be included through a CDN. Replace {{ version }} with the latest release in the top right corner of this page.

<link href="https://cdn.jsdelivr.net/gh/cityofnewyork/nyco-patterns@v{{ version }}/dist/utilities/tailwindcss/tailwindcss.css" rel="stylesheet" type="text/css">