Installation

Elements CSS is a utility framework for building Q-CTRL products. It’s built upon Tailwind and designed to match the Element Design Library by using the design tokens. It also introduces several base, component, and utility classes to make working with Elements CSS easier and more versatile. As such our documentation builds upon the Tailwind’s docs to include these differences.

# Installation Guides

Depending on your project you may be using a specific framework that requires some additional setup. In this case we recommend you follow one of Tailwind’s framework guides and then jump ahead to Adding Elements CSS plugin.

Next.js

Install Tailwind

Vue 3

Install Tailwind

Laravel

Install Tailwind

Nuxt.js

Install Tailwind

Create React App

Install Tailwind

Gatsby

Install Tailwind

# Installing Elements CSS as a Tailwind Plugin

Tailwind CSS requires Node.js 12.13.0 or higher.

For most projects, we recommend installing Elements CSS as a Tailwind plugin with PostCSS.

If you are unable to use Tailwind, you can use the stylesheet elements.css however you will still need to use PurgeCSS to preduce the file size in production.

If you are looking to make a quick demo/prototype you can install it using Elements via CDN version.

# Install Elements CSS

Get started by installing Elements CSS.

# Using npm
npm install -D @qctrl/elements-css@latest tailwindcss@latest postcss@latest autoprefixer@latest

# Using Yarn
yarn add -D @qctrl/elements-css@latest tailwindcss@latest postcss@latest autoprefixer@latest

Autoprefixer is required to automatically add vendor prefixes.

# Add Tailwind as a PostCSS plugin

Add tailwindcss and autoprefixer to your PostCSS configuration. Most of the time this is a postcss.config.js file at the root of your project, but it could also be a .postcssrc file, or postcss key in your package.json file.

// postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  }
}

# Create your configuration file

To use the Elements CSS plugin you need to create a Tailwind config file and pass it as a plugin. You can generate the config file by using the Tailwind CLI utility included when you install the taliwindcss npm package.

npx tailwindcss init

This will create a minimal tailwind.config.js file at the root of your project:

// tailwind.config.js
module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

# Adding Elements CSS plugin

To use the Elements CSS include it as a plugins, you should also configure darkMode to class

// tailwind.config.js
module.exports = {
  purge: [],
+  darkMode: "class",
  theme: {
    extend: {},
  },
  variants: {},
+  plugins: plugins: [require("@qctrl/elements-css")],,
}

# Include Tailwind in your CSS

Create a CSS file if you don’t already have one, and use the @tailwind directive to inject Tailwind’s base, components, and utilities styles:

/* ./your-css-folder/styles.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

Tailwind will swap these directives out at build-time with all of the styles it generates based on your configured design system.

If you’re using postcss-import (or a tool that uses it under the hood, such as Webpacker for Rails), use our imports instead of the @tailwind directive to avoid issues when importing any of your own additional files:

@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

# Building your CSS

How you actually build your project will depend on the tools that you’re using. Your framework may include a command like npm run dev to start a development server that compiles your CSS in the background, you may be running webpack yourself, or maybe you’re using postcss-cli and running a command like postcss styles.css -o compiled.css.

When building for production, be sure to configure the purge option to remove any unused classes for the smallest file size:

// tailwind.config.js
module.exports = {
+  purge: {
+    content: [
+      './dist/assets/js/**/*.js',
+      './dist/**/*.html',
+    ],
+    options: {
+      safelist: [],
+      blocklist: [/^debug-/],
+      keyframes: true,
+      fontFace: true,
+    },
+  },
  darkMode: "class",
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [require("@qctrl/elements-css/elements")],,
}

To learn more about tree-shaking unused styles for best performance read Tailwind’s guide on Optimizing for Production.

# Setting up fonts

Element’s uses several third-party fonts as per Typography – Elements Design Library. You may the fonts in your project using the following or a similar configuration.

<!-- Preconnect sources -->
<link rel="preconnect" href="https://use.typekit.net" crossorigin>
<link rel="preconnect" href="https://p.typekit.net" crossorigin>
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>

<!-- Preload Google Fonts -->
<link rel="preload" as="style" href="https://fonts.googleapis.com/css2?family=Roboto+Mono&family=Roboto:ital,wght@0,300;0,400;0,500;0,700;1,300;1,400;1,500&display=swap">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto+Mono&family=Roboto:ital,wght@0,300;0,400;0,500;0,700;1,300;1,400;1,500&display=swap" media="print" onload="this.media='all'">
<noscript>
  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto+Mono&family=Roboto:ital,wght@0,300;0,400;0,500;0,700;1,300;1,400;1,500&display=swap">
</noscript>