Upgrading Your App To Tailwind 2.1
You can read more about the Gem's relationship to Tailwind in the Tailwind Integration document
PMACS Frontend v1.1 bumps the included Tailwind utility file from v0.7.3 to v2.1. Any apps using Tailwind classes in their markup or helper modules should read through this guide to determine their upgrade path.
All upgrade information is included as references at the end of this document. Please note that most of these do not apply to us. As a result, we have collated the appropriate conversions required by typical PMACS apps below.
Find + Replace
| Find | Replace |
|---|---|
list-reset | list-none |
pin-{side} | {side}-0 |
flex-no-{grow/shrink} | flex-{grow/shrink}-0 |
whitespace-no-wrap | whitespace-nowrap |
flex-no-wrap | flex-nowrap |
grey used in bg-, border-, and text- utilities | gray |
New color palette grading
Tailwind color grading no longer conforms to the #{color}-lighter suffix pattern. Colors are now graded explicitly on a numerical scale that resembles the one used for font weights. The set of numerical weights is {50, 100, 200, ..., 900}.
This applies to the following color utilities and all variations:
bg-#{color}text-#{color}border-#{color}
The new palettes are shifted in addition to being expanded. As such, there aren't 1:1 conversions from the old to the new.
When upgrading an app, you can use the table below to determine how a color class in the old syntax maps to the new syntax. Please note that because there isn't a direct mapping for all weights, you may need to choose one that fits the color in context. Entries in the New column with multiple numbers separated by a / represent such subjective mappings. The first number listed is closer to the old color than the second.
| Old | New |
|---|---|
-lightest | -{100/50} |
-lighter | -{300/200} |
-light | -400 |
| No suffix | -500 |
-dark | -{600/700} |
-darker | -{800/900} |
-darkest | -900 |
Unopinionated base styles
Tailwind 0.x maintained some very light opinions about base HTML elements. For example, <ul> elements were effectively reset by Tailwind to have no list-style and no default whitespace. This is in contrast to browser vendor user agent stylesheets. To minimize developer surprise, Tailwind has removed all base HTML element opinions.
PMACS Frontend uses Bootstrap, an opinionated framework that resets and applies styles to base elements. As such, most of Tailwind's opinions were already overwritten by Bootstrap, which means you won't see anything different on those elements.
There are exceptions to this, however, such as the aforementioned <ul> element. Even with the list-none style added, there is whitespace applied by the user agent stylesheet in Chrome to <ul> and <ol> elements. To complete the upgrade, you would need to add a p-0 class to any <ul> that did not have explicit padding defined before.
These changes are very easy to spot by clicking around the app.
max-w- utilities have been expanded and modified
max-w- utilities were reworked in Tailwind 1.0. All usage of these utilities will require tweaking. For example, max-w-lg is now best represented by max-w-4xl.
xl variations dropped from our Tailwind build
After analyzing the current use of Tailwind classes by PMACS apps, we have decided to drop xl: variations from the utility file delivered with Frontend.
Our goal currently is to keep our build as light as possible. We could only locate a single use of xl: in our apps. However, if your app needs these utilities, please let us know.
In the future, JS tooling will allow us to add variations without affecting build weight.