Epic CSS / Documentation

Installation

Use Epic CSS in an existing Node project, or start with the Eleventy theme. The output is ordinary CSS that you can load in your own site.

Install the package

From a project with a package manifest, install the library and Sass:

npm install epic-css sass

Version 0.14.1 preserves palette values assigned before importing the library. If your configured corporate registry does not expose a newly published version, wait for it to become available through that registry; do not change network policy or disable TLS verification.

Create your Sass entry point

Create src/my-epic-css/index.scss and import the installed library. Relative paths below assume this folder structure:

my-project/
  package.json
  node_modules/
  src/
    my-epic-css/
      index.scss
    _includes/

// src/my-epic-css/index.scss
@import "../../node_modules/epic-css/src/index";

To customize the palette, import your own custom partial before the library. See Colors and palettes.

Compile full CSS

npx --no-install sass src/my-epic-css/index.scss src/_includes/style.css

Make sure the output folder exists. For a conventional site, choose a public CSS output path and load it with a stylesheet link. The Eleventy starter instead minifies and embeds src/_includes/style.css in its base template. A one-time full compile is enough to start using Flexbox, Grid, and Colors.

Use the Eleventy starter

git clone https://github.com/jeremyfaucher/epic-css-11ty-theme.git
cd epic-css-11ty-theme
npm ci
npm start

Follow the local URL printed by the server. The starter compiles Sass before starting its Eleventy and Sass watchers. Customize src/my-epic-css/_custom.scss and put your content under src.

Your files in the starter

src/my-epic-css/
  _custom.scss    // your palette overrides and custom styles
  index.scss      // imports custom first, then the installed library
  pre-light.css   // generated full CSS baseline

You do not need to copy all the library partials into this folder. They remain in the installed npm package. Edit _custom.scss for your overrides and index.scss to choose imports. Rebuild pre-light.css with the build command rather than editing generated CSS by hand. The provided Epic config points at these folders and the CSS include output.

Import selected parts

The Sass is split into variables, base, font ramp, colors, images, grid, and spacers. You can import selected partials instead of the complete entry point. Load variables first, after your custom overrides, because the other partials use them.

// Example: color utilities with your own base styles
@import "custom";
@import "../../node_modules/epic-css/src/variables";
@import "../../node_modules/epic-css/src/colors";

Importing only colors does not add the library's body text, link, or code styling. Those come from the base partial. Add the partials needed by the markup you copy; the examples in these docs assume the complete stylesheet.

Full pre-light CSS and filtered CSS

Pre-light is the full compiled stylesheet. The optional light command then compares literal class names in project source with that baseline and writes a project-specific filtered stylesheet. It does not compile Sass or infer new utilities on demand.

Add epicConfig.js beside your package manifest:

module.exports = {
  projectDir: './src',
  epicThemeDir: './src/my-epic-css',
  projectStyleDir: './src/_includes',
  outputFileName: 'style.css'
};

Add these scripts to the consuming project's manifest:

"epic-build": "node ./node_modules/epic-css/src/epic-build.js",
"epic-light": "node ./node_modules/epic-css/src/epic-light.js"

npm run epic-build
npm run epic-light

Run them sequentially from the project root. Rebuild pre-light after changing Sass. The full-build copy uses style.css; the filter honors the configured output filename. A missing or empty pre-light file is not a useful baseline.

Source coverage

The generated CSS can be used in WordPress, PHP, and other sites. The current light script scans files ending in .html, .njk, and .md beneath the configured source directory. It does not currently scan .php files or evaluate template code. For a PHP-based site, full CSS works independently of that scan; verify filtering against the actual HTML source or output you choose to scan.

The filter uses substring matches, retains whole matching media blocks, and does not provide a configured safelist. Dynamically assembled classes and other at-rule structures need careful checking. Preview your affected pages and responsive layouts after filtering; a successful build alone does not prove every dynamic state was retained.

Build the maintained site or starter

Stop the watchers first:

npm run validate
npm run build

validate checks the full Sass/filter/Eleventy pipeline using temporary output and restores the prior CSS files. build writes the deployable site to _site. The legacy build-production script runs only Eleventy, so it does not refresh CSS itself.