Emma.css Utility Classes

0.16.1 · active · verified Sun Apr 19

Emma.css provides a comprehensive set of Emmet-like utility classes, designed for accelerating front-end development by integrating directly into Sass projects. This library is not a standalone CSS framework but rather a collection of SCSS partials that compile into highly configurable utility classes. Currently at version 0.16.1, it maintains an active release cadence with regular updates and dependency management. Its key differentiators include its tight integration with Sass, allowing for custom prefixes and the toggling of `!important` declarations, and its commitment to modern Sass practices, having recently migrated to `@use`/`@forward` syntax. It focuses on providing atomic CSS classes that map closely to common CSS declarations, similar to how Emmet abbreviations work.

Common errors

```
SassError: Can't find stylesheet to import.
```
cause The Sass compiler cannot locate the `emma.css` stylesheet, often due to an incorrect import path or using an outdated directory name.

fix Ensure the import path is correct and uses the `scss/` directory: `@use 'emma.css/scss/all';`. Also, verify `emma.css` is installed in `node_modules`.
```
SassError: Expected ';' or '}'.
```
cause This error typically occurs when attempting to use `@import` with modern Dart Sass which expects `@use` syntax for modules, or if configuration variables are declared in the wrong order.

fix Switch to the `@use` syntax: `@use 'emma.css/scss/all';`. If you are setting configuration variables like `$emma-prefix` or `$emma-important`, ensure they are declared *before* the `@use` statement.

Warnings

breaking Since v0.16.0, Emma.css has migrated its internal Sass syntax from `@import` to `@use`/`@forward` for Dart Sass 3.0 compatibility. While `@import` may still function in some setups, it's considered deprecated by Sass, and the recommended approach for new projects is to transition to `@use`.
Fix: Update your Sass entry files from `@import 'emma.css/scss/all';` to `@use 'emma.css/scss/all' as emma;`. Remember that configuration variables like `$emma-prefix` must be declared *before* the `@use` rule.
gotcha Starting with v0.16.0, the `engines` field in `package.json` specifies a minimum Node.js version of `20.0.0`. Installing or building `emma.css` with older Node.js versions may lead to compatibility issues or errors.
Fix: Ensure your Node.js environment is updated to version 20.0.0 or higher. Use `nvm` or a similar tool to manage Node.js versions, e.g., `nvm install 20 && nvm use 20`.
breaking In v0.15.0, several font-related snippets were changed. The snippets `ff-a`, `ff-t`, `ff-v`, `ff-l`, `ff-ja` were removed, and new generic snippets `fx0`, `fx1`, `fx2`, `fx3` were introduced. This requires manual updates for projects using the older font snippets.
Fix: Review your stylesheets for usages of the removed font snippets and update them to the new equivalent snippets or custom font declarations as needed.
breaking Version 0.12.0 changed the main directory name for Sass files from `sass/` to `scss/`. This alters the path required to import the library into your project.
Fix: Update your Sass import paths from `@import "emma.css/sass/all";` to `@import "emma.css/scss/all";` (or the `@use` equivalent for modern Sass).
breaking Version 0.10.0 introduced two significant breaking changes: the root Sass file moved from `./emma.scss` to `./sass/all.scss` (later `scss/all.scss`), and the default `u-` prefix for utility classes was removed.
Fix: Adjust your import path to `emma.css/scss/all`. If you relied on the default `u-` prefix, you must now explicitly set `$emma-prefix: "u-";` before the `@use` statement to reintroduce it.

Install

npm install emma.css npm
yarn add emma.css yarn
pnpm add emma.css pnpm

Imports

emma.css/scss/all
wrong:
```
@import 'emma.css/scss/all';
```
correct:
```
@use 'emma.css/scss/all' as emma;
```
For modern Dart Sass environments (v0.16.0+), it is recommended to use `@use` for importing. The `as emma` clause namespaces the utility classes, e.g., `emma.d-b`. If `as` is omitted, classes are global.
$emma-prefix
wrong:
```
@use 'emma.css/scss/all';
$emma-prefix: "u-";
```
correct:
```
$emma-prefix: "u-";
@use 'emma.css/scss/all';
```
To add a prefix to all generated utility classes (e.g., `.u-d-b`), declare the `$emma-prefix` variable *before* the `@use` statement. Variables declared after `@use` will not take effect.
$emma-important
wrong:
```
@use 'emma.css/scss/all';
$emma-important: false;
```
correct:
```
$emma-important: false;
@use 'emma.css/scss/all';
```
By default, Emma.css classes use `!important`. To remove these annotations from all generated classes, set `$emma-important: false;` *before* the `@use` statement.

Quickstart

This quickstart demonstrates how to include Emma.css in a Sass project, configure a custom prefix, and disable `!important` flags in the generated utility classes using modern `@use` syntax.

/* your-project.scss */

// 1. Configure Emma.css variables BEFORE the @use statement
$emma-prefix: "u-"; // Add a 'u-' prefix to all utility classes (e.g., .u-d-b)
$emma-important: false; // Remove !important from generated utility classes

// 2. Import Emma.css using the modern @use syntax
// This will compile all utility classes into your CSS output
@use 'emma.css/scss/all';

// You can then use the generated classes in your HTML, e.g.:
// <div class="u-d-fx u-m-a u-p-md">Hello Emma!</div>

view raw JSON →