feat(tailwind): enable Tailwind utility and component classes (#675)

* feat(tailwind): enable utility classes and add tw- prefix

* feat(tailwind): introduces script to add tw- prefix in css files

* feat(tailwind): process components css to add tw- prefixes

* revert prefixing script and prefixes

* revert tw- prefix for tailwind utility classes

* feat(tailwind): enable tailwind component classes

* docs(tailwind): describe tailwind class usage

* docs(tailwind): revise tailwind utility class usage

* feat(tailwind): enable tailwind purge

* feat(tailwind): enable tailwind jit mode

* feat(tailwind): broaden TW purge scope to incl js jsx ts

* feat(tailwind): move import tailwind utilities for storybook only

* chore(tailwind): move properties to top f tailwind config object

* docs(tailwind): update tw custom class with example

* docs(tailwind): update tw conflict description

Co-authored-by: Annie Hu <[email protected]>

* docs(tailwind): udpate tw example

* fix(tailwind): specify tailwind purge and add related doc

Co-authored-by: Annie Hu <[email protected]>

packages/components/.storybook/preview.tsx

@@ -1,6 +1,7 @@
 import "@chanzuckerberg/eds-tokens/lib/css/variables.css";
 import "../src/styles/fonts.css";
 import "../src/styles/global.css";
+import "../src/styles/tailwindUtilities.css";
 
 import React from "react";
 

packages/components/README.md

@@ -99,3 +99,46 @@ declare var x: AbstractComponent<Props, HTMLElement>;
 ```
 
 - Preserve exact-typed objects when possible. If you must make them inexact, add an explicit `...` at the end of the object.
+
+## Tailwind Utility Classes
+EDS Components is configured for TW utility class use in Storybook only. Please configure downstream Tailwind config purge to include app files if necessary.
+
+Tailwind utility classes can be used with either `@apply` in CSS files such as 
+```css
+div {
+  @apply rounded border-2;
+  /* border-radius: 0.25 rem;
+     border-width: 2px; */
+}
+```
+or used directly as class names such as
+```jsx
+<div className="rounded border-2">
+```
+Use the [docs](https://tailwindcss.com/docs) to search for appropriate classes.
+
+### Potential conflicts with other styling libraries (e.g. Bootstrap)
+
+If you're also using styles from a separate library, conflicts may arise rarely between utility class names. Here are some conflicts we're aware of for **Bootstrap** specifically:
+  - Most annoying, `.hidden`
+    - Both Tailwind and Bootstrap have the same styling for `.hidden` but Bootstrap applies the  `!important ` property, which can be annoying when trying to utilize Tailwind breakpoints, e.g.:
+    ```html
+    <div class="hidden md:block lg:inline">
+    ```
+    - Where the expectation is `display: none ` for breakpoints smaller than 768px, `display: block `for 768px - 1023px, and `display: inline ` for >= 1024px. However since Bootstrap applies the `!important` property, all screen sizes show `display: none`.
+    - This can be circumvented with the `@apply` directive and/or using custom CSS with regular media queries to scope styling into a different class name, e.g.:.
+    ```jsx
+    <div className="responsive-display">
+    ```
+    ```css
+    .responsive-display {
+      display: none;
+      @apply md:block lg:inline;
+      /* or use traditional @media queries */
+    }
+    ```
+  - `.invisible` and `.text-` alignment
+    - These classes have the same styling in both Tailwind and Bootstrap, and therefore can be used without issues. Tailwind responsive states (such as breakpoints, hover, etc.) will have higher specificity so no issues will be caused there.
+  - Other unfound conflicts
+    - If the conflict is due to Bootstrap using `!important`, follow similar strategy above as `.hidden`.
+  - Bootstrap [styling](https://github.com/twbs/bootstrap-sass/tree/master/assets/stylesheets/bootstrap) and mentioned conflicts in [_utilities.scss](https://github.com/twbs/bootstrap-sass/blob/master/assets/stylesheets/bootstrap/_utilities.scss#L46) and [_type.scss](https://github.com/twbs/bootstrap-sass/blob/master/assets/stylesheets/bootstrap/_type.scss#L90) for reference

packages/components/src/styles/global.css

@@ -12,4 +12,8 @@
   --tw-ring-shadow: 0 0 #0000;
 }
 
+/**
+ * This injects Tailwind's base styles and any base styles registered by
+ * plugins.
+ */
 @tailwind base;

packages/components/src/styles/tailwindUtilities.css

@@ -0,0 +1,11 @@
+/**
+* This injects Tailwind's component classes and any component classes
+* registered by plugins.
+*/
+@tailwind components;
+
+/**
+* This injects Tailwind's utility classes and any utility classes registered
+* by plugins.
+*/
+@tailwind utilities;

packages/components/tailwind.config.js

@@ -1,6 +1,11 @@
 const variableTokens = require("@chanzuckerberg/eds-tokens/lib/json/css-variables-nested.json");
 const staticTokens = require("@chanzuckerberg/eds-tokens/lib/json/variables-nested.json");
 module.exports = {
+  mode: "jit",
+  /*The main value in TW utility classes is in Storybook stories.
+    We avoid using them in component styles to reduce chance of conflict with other libraries.
+    Please configure downstream Tailwind config purge to include app files if necessary*/
+  purge: ["./src/**/*.stories.{js,jsx,ts,tsx}"],
   theme: {
     colors: {
       transparent: "transparent",