Elements logo

Using with stylesheet

A guide to using Elements CSS the pre generated element.css stylesheet

Install Elements CSS

Get started by installing Elements CSS.

# Using npm
npm install @qctrl/elements-css

# Using Yarn
yarn add @qctrl/elements-css

Add Elements CSS to you project

Link to Elements CSS in the <head> of your document. Depending on your setup you’ll either want to link directly to the npm stylesheet or, in your build process, copy that file to your local assets folder and reference it there.

Note: Elements CSS is a utility class framework that ships with thousands of classes resulting in a very large file size and is intended to be used with a tool like PurgeCSS to ensure minimal file size in production.

<!-- npm -->
<link rel="stylesheet" href="node_modules/@qctrl/elements-css/dist/elements.css">

<!-- assets -->
<link rel="stylesheet" href="/assets/css/elements.css">

Set up fonts

Elements uses makes use of specific fonts, read more about how to setup the fonts.

Additional styling (optional)

Elements CSS is intended to be a one stop solution for styling Q-CTRL products and attempts to covers many possibilities (hence the large pre-build file size). However, as great as utility classes are, they aren’t always able to cover every requirement, there are a few stand out exceptions like @keyframes and animation.

For the most part you should ONLY use elements.css, but if the project does require additional styling that’s outside the scope of Elements CSS it should be added to a seperate stylesheet.

<!-- Elements CSS -->
<link rel="stylesheet" href="/assets/css/elements.css">
<!-- Custom styles -->
<link rel="stylesheet" href="/assets/css/styles.css">

Processing Elements CSS

Elements CSS ships as a large file that’s not recommended for production. The correct way to use Elements CSS is to use PurgeCSS when building/deploying your project. This will run through any .html and .js files (you may specify other file types if needed), match any CSS selectors and remove any unused styles from your production code. This can result in elements.css being reduced from 11mb to 38kb depending on the complexity of your project. Doing this ensures you’re only shipping what you use.

Example build setup

The following example shows how to implement PurgeCSS via PostCSS to serve and deploy your project. It’s not required to use PostCSS, however it’s a nice way to use purge as you can also autoprefix and minify your CSS along with some other benifits if you’re using a secondary stylesheet.

To get started, add postcss.config.js to the root of your project.

// postcss.config.js
const purgecss = require('@fullhuman/postcss-purgecss')({

  // Add additional file types `.liquid, .njk, .ts`
  content: [
    './dist/assets/js/**/*.js',
    './dist/**/*.html',
    // etc.
  ],

  // This is the function used to extract class names from your templates
  defaultExtractor: content => {
    // Capture as liberally as possible, including things like `h-(screen-1.5)`
    const broadMatches = content.match(/[^<>"'`\s]*[^<>"'`\s:]/g) || []

    // Capture classes within other delimiters like .block(class="w-1/2") in Pug
    const innerMatches = content.match(/[^<>"'`\s.()]*[^<>"'`\s.():]/g) || []

    return broadMatches.concat(innerMatches)
  }
})

// Minify production code.
const cssnano = require('cssnano')({
  preset: 'default',
})

module.exports = {
  plugins: [
    require('postcss-import'),
    require('postcss-nested'),
    require('autoprefixer'),
    ...(process.env.NODE_ENV === 'production' ? [purgecss, cssnano] : []),
  ],
}

In package.json we’ll use Yarn to build and serve our project.

"scripts": {
  "copy:src": "ncp node_modules/@qctrl/elements-css/dist/elements.css ./assets/assets/css/elements.css",
  "copy:dist": "ncp node_modules/@qctrl/elements-css/dist/elements.css ./dist/assets/css/elements.css",
  "watch": "cross-env NODE_ENV=development postcss ./src/assets/css/styles.css --dir ./dist/assets/css --no-map --watch",
  "serve": "run-s copy:* && run-p watch",
  "build:css": "cross-env NODE_ENV=production postcss ./src/assets/css/**/*.css --dir ./dist/assets/css --no-map",
  "build": "run-s copy:src build:*"
},

This is a basic setup that only runs PostCSS on the styles.css file during development and then runs PostCSS on elements.css and styles.css when building the project. Running PostCSS on elements.css whenever a file is changed can slow down your workflow so it’s recommended to only run it when building/deploying your project.