Upgrade Guide: v2.0.0-alpha.x - v2.0.0

Upgrade the packages

Run npm install --save-dev @northeastern-web/kernl-ui@latest postcss@latest autoprefixer@latest to install the latest version of the package.

If you're using Laravel Mix, follow the upgrade instructions here.

If you're using Jigsaw, run npm install --save-dev laravel-mix-jigsaw@latest.

If you're using the Tailwind Custom Forms plugin we recommend migrating to the Tailwind Forms plugin.

If you're using the Tailwind typography plugin, run npm install --save-dev @tailwindcss/typography@latest.

Switch to using Tailwind presets to extend the kernl(ui) default configuration

We are now using Tailwind's preset feature to extend the kernl(ui) default configuration instead of the base plugin.

First, remove the base plugin from your configuration, then extend the kernl(ui) configuration using the presets key.

// tailwind.config.js
const defaultConfig = require('@northeastern-web/kernl-ui/defaultConfig');

module.exports = {
+   presets: [defaultConfig],
    // ... other modifications
    plugins: [
-       require('@northeastern/kernl-ui/plugins/base.js'),
        // ... other plugins
    ]
}

Update PurgeCss configuration

Tailwind now uses PurgeCss v3 under the hood, so we've made a few changes to the way it's configured in kernl(ui).

Use object destructuring to merge the kernl-ui default PurgeCSS configuration with your own. In most cases, you should only need to customize the content key.

// tailwind.config.js
const defaultConfig = require('@northeastern-web/kernl-ui/defaultConfig');

module.exports = {
    presets: [defaultConfig],
-   purge: {
-       content: [
-           ...defaultConfig.purge.content,
-           // ... paths to your project's content
-       ],
-   },
+   purge: {
+       ...defaultConfig.purge,
+       ...{
+           content: [
+               ...defaultConfig.purge.content,
+               // ... paths to your project's content
+           ],
+           // If you didn't previously whitelist anything, the safelist option can be omitted
+           safelist: {
+               ...defaultConfig.purge.safelist,
+               standard: [
+                  // ... what was previously in your whitelist
+              ],
+           },
+        },
+    },
    // ... other modifications
}

Update color palette

We've updated the color palette to be more UI friendly. The biggest changes are listed below.

• The tan color was removed completely.
• The purple colors have been replaced with indigo colors.
• gold-500 and silver-500 were renamed to gold and silver respectively.
• red-700 (the brand red) is now red-600. Anywhere you were using red-700 should be updated to red-600. If those elements had a hover state, it should be updated from red-800 to red-700.
• The green colors are now much more usable for success states.
• The yellow colors were pretty significantly updated, so check to make sure anywhere those were still looks appropriate. You will likely need to lighten the colors from yellow-500 to yellow-400 for example.
• The semi-transparent colors were removed (black-semi-* and white-semi-*). Instead, use bg-black or bg-white and use the Tailwind bg-opacity and border-opacity utilities to set the transparency to one of the values from the kernl(ui) opacity scale.

Replace kernl(ui) Aspect Ratios Plugin With Official Tailwind Plugin

We've removed the kernl(ui) aspect ratio plugin in favor of the official Tailwind Aspect Ratio plugin. If you're using the kernl(ui) aspect ratio plugin, remove it from your tailwind.config.js and replace it with the official plugin. Run npm install --save-dev @tailwindcss/aspect-ratio to install the plugin, then update any usages in your HTML following the new plugin's documentation.

// tailwind.config.js
module.exports = {
    plugins: [
-       require('@northeastern-web/kernl-ui/plugins/aspectRatios.js'),
+       require('@tailwindcss/aspect-ratio'),
    ]
}

- <div class="relative ar-16x9">
-     <img class="absolute w-full h-full object-cover" src="/example-image.jpg" />
- </div>
+ <div class="aspect-w-16 aspect-h-9">
+     <img class="object-cover" src="/example-image.jpg" />
+ </div>

Replace Tailwind Custom Forms Plugin With Tailwind Forms Plugin

We now recommend using the Tailwind Form plugin instead of the Custom Forms plugin. This is an optional update if you're using the custom forms plugin, but recommended. To update, npm uninstall @tailwindcss/custom-forms && npm install @tailwindcss/forms. Next, replace the custom forms plugin in your tailwind.config.js file.

// tailwind.config.js
module.exports = {
    plugins: [
-       require('@tailwindcss/custom-forms'),
+       require('@tailwindcss/forms'),
    ]
}

Recompile, then make the following changes:

• Add type="text" to any text inputs.
• Replace the new class lists for each respective input you've used from the Form Controls page.
• You may need to replace anywhere focus:shadow-none focus:border-red-600 is used on form controls in your project with focus:ring-0 focus:border-blue-500
• Remove any form-input, form-checkbox, form-radio, form-select, and form-multiselect classes from your markup.

Remove focus:shadow-outline class in favor of focus:ring focus:ring-blue-500

A simple find and replace should fix this in most cases, but we recommend just removing the focus:shadow-outline class from form inputs if you're using the Tailwind Forms plugin. The focus:ring focus:ring-blue-500 class is not necessary.

Update Typography plugin configuration

If you're using the typography plugin, update to the latest version and move your configuration from the theme.typography key to the theme.extend.typography key in your tailwind.config.js file.

Remove undocumented gradient plugin

We've removed the undocumented kernl(ui) gradient plugin. If you were using it anywhere, remove those usages and use the official Tailwind gradients instead.

Remove the loader class

We've removed the loader class previously included with kernl(ui) in favor of using the Tailwind animate-spin class on a feather icon. Copy the changes from the loader components to your project.

Use Tailwind's default line height feature

We're now using Tailwind's default line height feature, so elements that don't explicitly have a line height set will now have a default line height dependent on their font size. Check to make sure there aren't any significant line height changes in your project.

Switch to Tailwind's composable transforms

Tailwind has now removed the IE11 compatibility mode, so the transform classes work slightly different. Anywhere we were previously just using translate-* or scale-*, we are now required to also add the transform class. A few notable places to check for this are local headers, modals, and carousels.

Rename whitespace-no-wrap class to whitespace-nowrap and flex-no-wrap class to flex-nowrap

A simple find and replace should fix this.

Read through the Tailwind v2 Upgrade Guide

We also recommend reading through the Tailwind v1 Upgrade Guide to see if there are any additional changes that affect your project.