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

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

Tailwindcss

NYCO Patterns integrates Tailwindcss, a CSS utility-first framework that is customized with NYCO 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 NYCO Patterns the variant desktop: is added to the .p-1 utility: <div class="desktop:p-1"></div>.

• Theme: This object contains NYCO 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>.

Below is a table describing the current configuration source that includes which core plugins are enabled, what variants they use, and if they are themed with NYCO Pattern design tokens.

NYCO Patterns × Tailwindcss configuration

Tailwindcss Logical

The Tailwindcss Logical plugin extends the utility set with CSS logical properties. NYCO Patterns includes this plugin in its Tailwindcss implementation. This particularly useful for languages that use right-to-left reading directions.

More supported properties are described in the plugin’s readme file.

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/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 with the latest release (2.6.15).

<link href="https://cdn.jsdelivr.net/gh/cityofnewyork/nyco-patterns@v2.6.15/dist/utilities/tailwindcss/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 NYCO 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/patterns/config/tailwindcss.js

Production distributions and PurgeCSS

It is highly recommended to use PurgeCSS to analyze the classnames used in your static markup files 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. See the Tailwindcss optimizing for production guide.

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 NYCO Patterns Tailwindcss implementation. There will be some differences in colors, drop shadows, type, dimensions, etc.

<div class="bg-base-white shadow-up rounded overflow-hidden">
  <div class="px-2 py-5 small:px-4">
    <h3 class="mt-0 mb-1">Applicant Information</h3>
    <p class="mb-0 text-grey">Personal details and application.</p>
  </div>
  <div class="border-t border-white">
    <dl>
      <div class="bg-white-50t px-2 py-3 small:grid small:grid-cols-3 small:gap-4 small:px-4">
        <dt class="font-bold">Full name</dt>
        <dd class="mt-1 small:mt-0 small:col-span-2">Margot Foster</dd>
      </div>
      <div class="px-2 py-3 small:grid small:grid-cols-3 small:gap-4 small:px-4">
        <dt class="font-bold">Application for</dt>
        <dd class="mt-1 small:mt-0 small:col-span-2">Backend Developer</dd>
      </div>
      <div class="bg-white-50t px-2 py-3 small:grid small:grid-cols-3 small:gap-4 small:px-4">
        <dt class="font-bold">Email address</dt>
        <dd class="mt-1 small:mt-0 small:col-span-2">margotfoster@example.com</dd>
      </div>
      <div class="px-2 py-3 small:grid small:grid-cols-3 small:gap-4 small:px-4">
        <dt class="font-bold">Salary expectation</dt>
        <dd class="mt-1 small:mt-0 small:col-span-2">$120,000</dd>
      </div>
      <div class="bg-white-50t px-2 py-3 small:grid small:grid-cols-3 small:gap-4 small:px-4">
        <dt class="font-bold">
          <About></About>
        </dt>
        <dd class="mt-1 small:mt-0 small:col-span-2">Fugiat ipsum ipsum deserunt culpa aute sint do nostrud anim incididunt cillum culpa consequat. Excepteur qui ipsum aliquip consequat sint. Sit id mollit nulla mollit nostrud in ea officia proident. Irure nostrud pariatur mollit ad adipisicing reprehenderit deserunt qui eu.</dd>
      </div>
      <div class="px-2 py-3 small:grid small:grid-cols-3 small:gap-4 small:px-4">
        <dt class="font-bold">Attachments</dt>
        <dd class="mt-1 small:mt-0 small:col-span-2">
          <ul class="p-0 border-white border border-solid rounded">
            <li class="px-2 py-2 flex items-center justify-between text-small border-b border-white">
              <div class="w-0 flex-1 flex items-center">
                <svg aria-hidden="true" class="icon-ui icon-3 text-gray">
                  <use xlink:href="#feather-paperclip"></use>
                </svg>
                <span class="text-grey ml-2 flex-1 w-0 truncate">resume_back_end_developer.pdf</span>
              </div>
              <div class="ml-4 flex-shrink-0">
                <a class="font-bold text-indigo-600 hover:text-indigo-500" href="#">
                  <Download></Download>
                </a>
              </div>
            </li>
            <li class="px-2 py-2 flex items-center justify-between text-small">
              <div class="w-0 flex-1 flex items-center">
                <svg aria-hidden="true" class="icon-ui icon-3 text-gray">
                  <use xlink:href="#feather-paperclip"></use>
                </svg>
                <span class="text-grey ml-2 flex-1 w-0 truncate">coverletter_back_end_developer.pdf</span>
              </div>
              <div class="ml-4 flex-shrink-0">
                <a class="font-bold text-indigo-600 hover:text-indigo-500" href="#">Download</a>
              </div>
            </li>
          </ul>
        </dd>
      </div>
    </dl>
  </div>
</div>

This is an implementation of the first description list example from the Tailwind UI preview.