From e6185eed50cd10f8f2bf7955739e59822eca902f Mon Sep 17 00:00:00 2001
From: Jin Lee <86632227+jinlee93@users.noreply.github.com>
Date: Fri, 22 Oct 2021 11:44:39 -0700
Subject: [PATCH] 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 <annie.hu@chanzuckerberg.com>

* docs(tailwind): udpate tw example

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

Co-authored-by: Annie Hu <annie.hu@chanzuckerberg.com>
---
 packages/components/.storybook/preview.tsx    |  1 +
 packages/components/README.md                 | 43 +++++++++++++++++++
 packages/components/src/styles/global.css     |  4 ++
 .../src/styles/tailwindUtilities.css          | 11 +++++
 packages/components/tailwind.config.js        |  5 +++
 5 files changed, 64 insertions(+)
 create mode 100644 packages/components/src/styles/tailwindUtilities.css

diff --git a/packages/components/.storybook/preview.tsx b/packages/components/.storybook/preview.tsx
index 011501bb91..2dee9558c4 100644
--- a/packages/components/.storybook/preview.tsx
+++ b/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";
 
diff --git a/packages/components/README.md b/packages/components/README.md
index 2caeef104b..2bf922f195 100644
--- a/packages/components/README.md
+++ b/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
\ No newline at end of file
diff --git a/packages/components/src/styles/global.css b/packages/components/src/styles/global.css
index 91478fb71c..92602c9de4 100644
--- a/packages/components/src/styles/global.css
+++ b/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;
diff --git a/packages/components/src/styles/tailwindUtilities.css b/packages/components/src/styles/tailwindUtilities.css
new file mode 100644
index 0000000000..34a19b3b99
--- /dev/null
+++ b/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;
diff --git a/packages/components/tailwind.config.js b/packages/components/tailwind.config.js
index 511ace113e..bca90d8647 100644
--- a/packages/components/tailwind.config.js
+++ b/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",