Getting started - ExpressiveCSS

Download

Expressive comes in two different forms. You can select which version you want depending on your preference and expertise. The project is at version 0.9.1 and is still growing, so the usual path is to build from the repository.

Expressive

This is the standard version that comes with both the minified and unminified CSS and JavaScript files. After you build the project, copy the files from dist/. This option requires little to no setup. Use this if you are unfamiliar with Sass.

Sass

This version is the source SCSS in src/sass. By choosing this version you have more control over which layers to include. You will need a Sass compiler if you choose this option.

From source

Clone the repository and build the compiled CSS and JavaScript:

npm install
npm run build

The compiled assets are written to dist/:

dist/
├── css/
│   ├── expressive.css
│   └── expressive.min.css
├── js/
│   ├── expressive.cjs
│   ├── expressive.js
│   ├── expressive.min.js
│   └── expressive.mjs
└── types/

NPM

The package name is @expressivecss/expressive. This release contains source files as well as the compiled CSS and JavaScript files.

npm install @expressivecss/expressive

Yarn

Or you can add the package with yarn.

yarn add @expressivecss/expressive

Setup

Project Structure

After building, copy the compiled files into the directory where your website is located. Your directory will look something like this.

You'll notice that there are two sets of the files. The min means that the file is compressed to reduce load times. These minified files are usually used in production while it is better to use the unminified files during development.

MyWebsite/
  |--css/
  |  |--expressive.css
  |
  |--fonts/
  |  |--material-symbols-outlined.woff2
  |
  |--js/
  |  |--expressive.js
  |
  |--index.html

HTML Setup

Next you just have to make sure you link the files properly in your webpage. Generally it is wise to import JavaScript files at the end of the body to reduce page load time. Follow the example below on how to import Expressive into your webpage.

<!DOCTYPE html>
<html lang="en" theme="light">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="stylesheet" href="css/expressive.min.css">
  </head>
  <body>
    <script src="js/expressive.min.js"></script>
    <script>
      document.addEventListener('DOMContentLoaded', () => {
        Expressive.AutoInit();
      });
    </script>
  </body>
</html>

Initialize JavaScript

The browser bundle exposes the framework as the global Expressive object. Importing the JavaScript installs shared document behaviors (forms, chips, cards, and a few others), but it does not call AutoInit() automatically. Call it after the page has loaded so components such as sidenavs, tooltips, and tabs start themselves.

AutoInit() scans document.body by default. Pass a container to limit the scan, or add the no-autoinit class to an element that should be initialized manually.

Expressive.AutoInit();

Expressive.AutoInit(document.querySelector('#app'), {
  Tooltip: { position: 'top' }
});

ES modules

Import the framework or individual components from the module build:

import { AutoInit, Tooltip } from './js/expressive.mjs';

AutoInit();

const element = document.querySelector('.custom-tooltip');
Tooltip.init(element, { position: 'top' });

Themes

Expressive uses the theme attribute on the root element. light and dark lock the scheme; auto (or omitting the attribute) follows the OS.

<html lang="en" theme="auto">

document.documentElement.setAttribute('theme', 'dark');

Templates

Start from a documented layout instead of an empty page. These two pages show how Expressive structures content, and you can copy the markup they use.

Grid

The 12-column CSS Grid, containers, offsets, and responsive layouts. The first thing to learn after you link the stylesheet.

Open Grid

Helpers

Alignment, visibility, spacing, truncation, and other single-purpose classes you will use on every page.

Open Helpers

Sass Setup

This section is only relevant if you chose to use the Sass sources.

Compiling Sass

Instead of only a CSS folder, the repository contains many .scss files which contain the styles of individual layers and components. The browser cannot interpret Sass, so you must compile src/sass/expressive.scss into a regular CSS file. At this point you can link this newly outputted file in your HTML page.

From the repository, the npm script does that for you:

npm run build:css

In another Sass project, use the framework's Sass entry point:

@use "@expressivecss/expressive/src/sass/expressive";

When working directly in this repository, the entry point is src/sass/expressive.scss.

MyWebsite/
|--css/
|  |--expressive.css <-- compiled from scss/expressive.scss
|
|--js/
|  |--expressive.js
|
|--scss/
|  |--expressive.scss
|  |--abstracts/
|  |--tokens/
|  |--utilities/
|  |--base/
|  |--components/
|
|--index.html