Installation and Usage

kernl(ui) is built upon an atomic CSS system called Tailwind CSS and PostCSS. It will be helpful to reference Tailwind CSS documentation. Northeastern also has a team license for Tailwind UI, an additional set of responsive HTML components for use on Northeastern web projects.

Package Version

When possible, we recommend using the fully customizable packaged version of the design system. Using this version requires using NPM to install the package and a build step to compile the CSS and/or JavaScript included.

This version of the package has several benefits over the CDN versions including:

• A fully customizable config file
• The ability to use Tailwind's directives like @apply, @variants, etc.
• The ability to use PurgeCss achieve file sizes around 10kb instead of 500kb+
• The ability to install our pre-built plugins for form elements, transitions, transforms, aspect ratios, etc.

To install the package in your project, make sure you have npm and Node.js installed, then use the following steps:

1. Add <link href="https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,300;0,400;0,700;0,900;1,300;1,400;1,700;1,900" rel="stylesheet"> to the head of your HTML file.
2. Run npm install @northeastern-web/kernl-ui in your terminal inside your project.
3. Install Tailwind and add it to your build step using one of the methods in the Tailwind installation documentation.
4. Extend the kernl(ui) preset in your tailwind.config.js file. This sets some default font sizes and font families.

                           const defaultConfig = require('@northeastern-web/kernl-ui/defaultConfig');
   
   module.exports = {
       presets: [defaultConfig],
   }
                       

5. Optionally add the other kernl(ui) plugins to your tailwind.config.js file.

                           module.exports = {
       plugins: [
           require('@northeastern-web/kernl-ui/plugins/buttons.js'),
           require('@northeastern-web/kernl-ui/plugins/columns.js'),
           // To use this plugin, run `npm install @tailwindcss/aspect-ratio`
           require('@tailwindcss/aspect-ratio'),
           // To use this plugin, run `npm install @tailwindcss/custom-forms`
           require('@tailwindcss/custom-forms'),
           // To use this plugin, run `npm install @tailwindcss/typography`
           require('@tailwindcss/typography'),
       ],
   };
                       

To learn how to use and configure the kernl(ui) plugins, read the plugins documentation.

PurgeCss is automatically enabled in full kernl(ui) builds to remove any unused classes when you CSS is processed. This can result in a very significant reduction in file size. It is very important that you configure the paths to your site's content so PurgeCss can scan the content for classes. To do so, follow the PurgeCss configuration documentation below.

To set up the JavaScript portion of the kernl(ui) (Alpine.js and Feather icons), simply add the following code to your pre-compiled JavaScript file or use the CDN method below.

require('@northeastern-web/kernl-ui');

If you prefer to use imports and your build system is set up to support them, you may do so instead.

import '@northeastern-web/kernl-ui';

Browser Support

kernl(ui) does not natively support IE11, so we highly recommend loading the following script before loading the kernl(ui) script. It will load a custom Browser Update notification to prompt users using older browsers to upgrade their browser.

                <script src="https://global-packages.cdn.northeastern.edu/kernl-ui/dist/js/browser-update.js"></script>
            

Configuring PurgeCss

To configure PurgeCss, add the following purge configuration to your tailwind.config.js file and add paths to your site's content to the content array. Paths should be relative and can include wildcards i.e. 'resources/views/**/*.blade.php'.

                const defaultConfig = require('@northeastern-web/kernl-ui/defaultConfig');

module.exports = {
    purge: {
        ...defaultConfig.purge,
        ...{
            content: [
                ...defaultConfig.purge.content,
                // Paths to your site content
            ],
            // If you need to provide safelist options, always use the object syntax
            // options: {
            //     ...defaultConfig.purge.options,
            //     safelist: {
            //         ...defaultConfig.purge.safelist,
            //         standard: [
            //             ...defaultConfig.purge.safelist.standard,
            //         ]
            //     },
            // },
        },
    },
    // Other config options
};
            

CDN Version

There is a CDN version of the package available for experimentation and prototypes, but it's not recommended for large production applications for the same reasons Tailwind's CDN version is not recommended:

• You can't customize the default theme
• You can't use any directives like @apply, @variants, etc.
• You can't enable variants or plugins like group-hover
• You can't install plugins for form elements, aspect ratios, etc.

To use the CDN version of kernl-ui, there are a couple of steps:

1. Add <link href="https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,300;0,400;0,700;0,900;1,300;1,400;1,700;1,900" rel="stylesheet"> to the head of your HTML file.
2. Add <link href="https://global-packages.cdn.northeastern.edu/kernl-ui/dist/css/index.css" rel="stylesheet"> to the head of your HTML file.
3. If you plan to create Alpine.js components or plan to use Feather icons, add <script src="https://global-packages.cdn.northeastern.edu/kernl-ui/dist/js/index.umd.js"></script> to the bottom of your HTML file above the </body> tag, and finally load the browser update script.