npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@hursey013/tailwindcss-uswds

v1.2.0

Published

U.S. Tailwind Design System

Downloads

49

Readme

U.S. Tailwind Design System

A TailwindCSS plugin for adding U.S. Web Design System design tokens to supported Tailwind utilities. For use in utility-first projects that favor a JavaScript based configuration and do not require USWDS provided components or page templates out of the box.

Install

  1. Install the plugin:
# Using npm
npm install @hursey013/tailwindcss-uswds --save-dev

# Using Yarn
yarn add @hursey013/tailwindcss-uswds -D
  1. Add it to your tailwind.config.js file:
// tailwind.config.js
module.exports = {
  // ...
  plugins: [require("@hursey013/tailwindcss-uswds")]
};

Options

fontPath (optional)

tailwindcss-uswds provides the necessary font files in order to generate the required USWDS @font-face rules. If you would prefer to copy the font files directly into your project folder you can update the path to the font directory:

// tailwind.config.js
module.exports = {
  // ...
  plugins: [
    require("@hursey013/tailwindcss-uswds")({
      fontPath: "../path/to/fonts"
    })
  ]
};

overrides (optional)

By default, all supported utilities use the standard set of design tokens provided by USWDS:

// tailwind.config.js
module.exports = {
  // ...
  plugins: [
    require("@hursey013/tailwindcss-uswds")({
      // ...
      overrides: {
        borderRadius: "standard",
        borderWidth: "standard",
        boxShadow: "standard",
        colors: "standard",
        cursor: "standard",
        flex: "standard",
        fontFamily: "standard",
        fontFeatureSettings: "standard",
        fontSize: "standard",
        fontWeight: "standard",
        gap: "standard",
        height: "standard",
        letterSpacing: "standard",
        lineHeight: "standard",
        margin: "standard",
        maxHeight: "standard",
        maxWidth: "standard",
        measure: "standard",
        minHeight: "standard",
        minWidth: "standard",
        opacity: "standard",
        order: "standard",
        padding: "standard",
        screens: "standard",
        textIndent: "standard",
        width: "standard",
        zIndex: "standard"
      }
    })
  ]
};

To prevent USWDS design tokens from overriding the default Tailwind values, pass a value of false:

// tailwind.config.js
module.exports = {
  // ...
  plugins: [
    require("@hursey013/tailwindcss-uswds")({
      // ...
      overrides: {
        // ..
        flex: false
        // ...
      }
    })
  ]
};

To use an extended set of USWDS design tokens for a particular utility, pass a value of extended :

// tailwind.config.js
module.exports = {
  // ...
  plugins: [
    require("@hursey013/tailwindcss-uswds")({
      // ...
      overrides: {
        // ..
        color: "extended"
        // ...
      }
    })
  ]
};

Currently color, borderRadius, fontSize, fontWeight, letterSpacing, and lineHeight support extended.

Usage

Utilities

Generated utility classes follow the default naming conventions provided by Tailwind with USWDS design tokens as values. This creates shorter class names and may also change the utility classname itself:

/* .border-bottom-1 becomes: */
.border-b-1 {
  border-bottom: 0.75rem solid;
}

/* .margin-bottom-neg-2px becomes: */
.-mb-2px {
  margin-bottom: -2px;
}

/* .radius-right-lg becomes: */
.rounded-r-lg {
  border-top-right-radius: 0.5rem;
  border-bottom-right-radius: 0.5rem;
}

Out of the box, tailwindcss-uswds provides the following USWDS design tokens to each specific utility:

| Key | Classes | Reference | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | borderRadius | .rounded-{t\|r\|b\|l\|tl\|tr\|br\|bl}-{0, sm, md, lg, pill} | TW | USWDS | | borderWidth | .border-{t\|r\|b\|l}-{0, 1px, 2px, 05, 1, 105, 2, 205, 3} | TW | USWDS | | boxShadow | .shadow-{none, 1, 2, 3, 4, 5} | TW | USWDS | | colors | See colors section | | cursor | .cursor-{auto, default, move, not-allowed, pointer, wait} | TW | | flex | .flex-{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, auto, fill} | TW | USWDS | | fontFamily | .font-{alt, body, code, heading, mono, sans, serif, ui} | TW | USWDS | | fontSize | .text-{alt, body, code, heading, mono, sans, serif, ui}-{3xs, 2xs, xs, sm, md, lg, xl, 2xl, 3xl} | TW | USWDS | | fontWeight | .font-{light, normal, bold} | TW | USWDS | | gap | .gap-{0, 2px, 05, 1, 2, 3, 4, 5, 6, sm, md, lg} | TW | USWDS | | height | .h-{auto, 0, 1px, 2px, 05, 1, 105, 2, 205, 3, 4, 5, 6, 7, 8, 9, 10, 15, card, card-lg, mobile, full, viewport} | TW | USWDS | | letterSpacing | .tracking-{-3, -2, -1, auto, 1, 2, 3} | TW | USWDS | | lineHeight | .leading-{alt, body, code, heading, mono, sans, serif, ui}-{1, 2, 3, 4, 5, 6} | TW | USWDS | | margin | .m{t\|r\|b\|l\|x\|y}-{-1px, -2px, -05, -1, -105, -2, -205, -3, 0, 1px, 2px, 05, 1, 105, 2, 205, 3, 4, 5, 6, 7, 8, 9, 10, 15, auto, card, card-lg, mobile} | TW | USWDS | | maxHeight | .max-h-{none, 05, 1, 105, 2, 205, 3, 4, 5, 6, 7, 8, 9, 10, 15, card, card-lg, mobile, mobile-lg, tablet, tablet-lg, viewport} | TW | USWDS | | maxWidth | .max-w-{none, 05, 1, 105, 2, 205, 3, 4, 5, 6, 7, 8, 9, 10, 15, card, card-lg, mobile, mobile-lg, tablet, tablet-lg, desktop, desktop-lg, widescreen, full} | TW | USWDS | | minHeight | .min-h-{none, 0, 05, 1, 105, 2, 205, 3, 4, 5, 6, 7, 8, 9, 10, 15, card, card-lg, mobile, mobile-lg, tablet, tablet-lg, viewport} | TW | USWDS | | minWidth | .min-w-{none, 0, 05, 1, 105, 2, 205, 3, 4, 5, 6, 7, 8, 9, 10, 15} | TW | USWDS | | opacity | .opacity-{0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100} | TW | USWDS | | order | .order-{first, last, initial, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11} | TW | USWDS | | padding | .p{t\|r\|b\|l\|x\|y}-{0, 1px, 2px, 05, 1, 105, 2, 205, 3, 4, 5, 6, 7, 8, 9, 10, 15} | TW | USWDS | | screens | See screens section | | width | .w-{auto, 0, 05, 1, 105, 2, 205, 3, 4, 5, 6, 7, 8, 9, 10, 15, card, card-lg, mobile, mobile-lg, tablet, tablet-lg, desktop, desktop-lg, widescreen, full} | TW | USWDS | | zIndex | .z-{auto, bottom, top, 0, 100, 200, 300, 400, 500} | TW | USWDS |

Unless mentioned above, all other utilities provided by Tailwind will be available with their default Tailwind values.

Do note that some Tailwind utilities inherit values defined elsewhere in the config file. For example, the USWDS design tokens defined in opacity will also be provided to Tailwind's borderOpacity, backgroundOpacity, placeholderOpacity, and textOpacity utilities. Similar functionality is provided for color based utilities.

Additional utilities

Several USWDS-specific utilities are available in addition to the defaults provided by Tailwind:

| Key | Classes | Reference | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | measure | .measure-{none, 1, 2, 3, 4, 5, 6} | USWDS | | fontFeatureSettings | .text-{tabular, no-tabular, } | USWDS | | textIndent | .text-indent-{-9, -8, -7, -6, -5, -4, -3, -205, -2, -105, -1, -05, -2px, -1px, 0, 1px, 2px, 05, 1, 105, 2, 205, 3, 4, 5, 6, 7, 8, 9 } | USWDS |

Colors

By default, tailwindcss-uswds provides theme, state, and basic color tokens to all color based Tailwind utilities (.bg-{color}, .border-{color}, and .text-{color}). By using the value of extended as outlined in the overrides section, system tokens can be included as well. Do note that including system color tokens will add hundreds of additional colors (and thousands of Tailwind generated utilities), so be sure to use the purge option provided by Tailwind to remove unused CSS.

Default color tokens

// tailwind.config.js
module.exports = {
  theme: {
    // ...
    colors: {
      transparent: "rgba(0, 0, 0, 0)",
      black: "rgb(0, 0, 0)", // #000000
      white: "rgb(255, 255, 255)", // #FFFFFF

      // Theme color tokens
      base: {
        lightest: "rgb(240, 240, 240)", // #f0f0f0
        lighter: "rgb(223, 225, 226)", // #dfe1e2
        light: "rgb(169, 174, 177)", // #a9aeb1
        default: "rgb(113, 118, 122)", // #71767a
        dark: "rgb(86, 92, 101)", // #565c65
        darker: "rgb(61, 69, 81)", // #3d4551
        darkest: "rgb(27, 27, 27)" // #1b1b1b
      },
      ink: "rgb(27, 27, 27)", // #1b1b1b

      primary: {
        lighter: "rgb(217, 232, 246)", // #d9e8f6
        light: "rgb(115, 179, 231)", // #73b3e7
        default: "rgb(0, 94, 162)", // #005ea2
        vivid: "rgb(0, 80, 216)", // #0050d8
        dark: "rgb(26, 68, 128)", // #1a4480
        darker: "rgb(22, 46, 81)" // #162e51
      },
      secondary: {
        lighter: "rgb(243, 225, 228)", // #f8dfe2
        light: "rgb(242, 147, 140)", // #f2938c
        default: "rgb(216, 57, 51)", // #d83933
        vivid: "rgb(228, 29, 61)", // #e41d3d
        dark: "rgb(181, 9, 9)", // #b50909
        darker: "rgb(139, 10, 3)" // #8b0a03
      },
      "accent-cool": {
        darker: "rgb(7, 100, 141)", // #e1f3f8
        dark: "rgb(40, 160, 203)", // #97d4ea
        default: "rgb(0, 189, 227)", // #00bde3
        light: "rgb(151, 212, 234)", // #28a0cb
        lighter: "rgb(225, 243, 248)" // #07648d
      },
      "accent-warm": {
        lighter: "rgb(242, 228, 212)", // #f2e4d4
        light: "rgb(255, 188, 120)", // #ffbc78
        default: "rgb(250, 148, 65)", // #fa9441
        dark: "rgb(192, 86, 0)", // #c05600
        darker: "rgb(119, 85, 64)", // #775540
      },

      // State color tokens
      info: {
        lighter: "rgb(231, 246, 248)", #e7f6f8
        light: "rgb(153, 222, 234)", // #99deea
        default: "rgb(0, 189, 227)", // #00bde3
        dark: "rgb(0, 158, 193)", // #009ec1
        darker: "rgb(46, 98, 118)" // #2e6276
      },
      error: {
        lighter: "rgb(244, 227, 219)", // #f4e3db
        light: "rgb(243, 146, 104)", // #f39268
        default: "rgb(213, 67, 9)", // #d54309
        dark: "rgb(181, 9, 9)", // #b50909
        darker: "rgb(111, 51, 49)" // #6f3331

      },
      warning: {
        lighter: "rgb(250, 243, 209)", // #faf3d1
        light: "rgb(254, 230, 133)", // #fee685
        default: "rgb(255, 190, 46)", // #ffbe2e
        dark: "rgb(229, 160, 0)", // #e5a000
        darker: "rgb(147, 111, 56)" // #936f38
      },
      success: {
        lighter: "rgb(236, 243, 236)", // #ecf3ec
        light: "rgb(112, 225, 123)", // #70e17b
        default: "rgb(0, 169, 28)", // #00a91c
        dark: "rgb(77, 128, 85)", // #4d8055
        darker: "rgb(68, 100, 67)" // #446443
      },
      disabled: {
        light: "rgb(230, 230, 230)", // #e6e6e6
        default: "rgb(201, 201, 201)", // #c9c9c9
        dark: "rgb(173, 173, 173)" // #adadad
      },

      // Basic color tokens
      red: "rgb(229, 34, 7)", // #e52207
      orange: "rgb(230, 111, 14)", // #e66f0e
      gold: "rgb(255, 190, 46)", // #ffbe2e
      yellow: "rgb(254, 230, 133)", // #fee685
      green: "rgb(83, 130, 0)", // #538200
      mint: "rgb(4, 197, 133)", // #04c585
      cyan: "rgb(0, 158, 193)", // #009ec1
      blue: "rgb(0, 118, 214)", // #0076d6
      indigo: "rgb(103, 108, 200)", // #676cc8
      violet: "rgb(129, 104, 179)", // #8168b3
      magenta: "rgb(215, 45, 121)" // #d72d79
    }
    // ...
  },
  plugins: [require("@hursey013/tailwindcss-uswds")]
};

Customizing colors

The USWDS based theme can be customized by using your project's tailwind.config.js file and following the process outlined in the customizing colors docs.

To reference system color tokens directly by name (without needing to use the extended option) you can import the JSON file generated by tailwindcss-uswds:

// tailwind.config.js
const colors = require("@hursey013/tailwindcss-uswds/dist/colors");

module.exports = {
  theme: {
    // ...
    extend: {
      colors: {
        // ...
        "primary-vivid": colors["blue-warm"].50v
        // ...
      }
    }
  },
  plugins: [require("@hursey013/tailwindcss-uswds")]
};

Breakpoints

The default breakpoints provided by USWDS are as follows:

// tailwind.config.js
module.exports = {
  theme: {
    // ...
    screens: {
      card: "10rem"
      card-lg: "15rem"
      desktop: "64rem"
      desktop-lg: "75rem"
      mobile: "20rem"
      mobile-lg: "30rem"
      tablet: "40rem"
      tablet-lg: "55rem"
      widescreen: "87.5rem"
    }
    // ...
  },
  plugins: [require("@hursey013/tailwindcss-uswds")]
};

These breakpoints can be used with most utility classes by adding the corresponding prefix:

<img class="w-5 tablet:w-10 widescreen:w-15" src="..." />

// ...

Icons

As an added convenience, all icons provided by USWDS are included in tailwindcss-uswds.

import flag from "@hursey013/tailwindcss-uswds/dist/img/us_flag_small.png";

// ...