Getting Started

Project setup and usage

How to set up your project and use the Sfumato CLI tool.

Overview

Sfumato works by reading one or more source CSS files and generating output CSS files that your project should actually use for styling. Typically the source file is named source.css but can be any valid CSS file name.

The source CSS file contains:

Sfumato configuration settings, like watch paths
Customizations, like colors, static utilities, and variants (optional)
Your own custom CSS (optional)

Set up & use

Folder structure

A typical folder structure would place the source stylesheet alongside the generated one, as in the example below. But the source can be anywhere in your project, and the generated CSS file location can be anywhere relative to the source CSS file location.

project/
    ...
    stylesheets/
        source.css  <-- source with settings and custom styles
        app.css     <-- generated by Sfumato
    ...

Create an example CSS file

Sfumato can create a sample CSS file for you. In a terminal, navigate to the folder where you want the file created, and run the init command. This will create a reference file named sfumato-example.css with all the configuration options and examples for custom colors, variants, etc.

sfumato init

Note: you should rename the sfumato-example.css file to something like source.css before making any changes.

Customize project settings

Once you have the example CSS file in place and renamed to your liking, customize the settings to match your project requirements. The example file is commented to guide you in tailoring it for your project needs.

Keep in mind that you may not even need any custom CSS if you style everything with utility classes.

PRO TIP: Settings not marked "REQUIRED" should be deleted if you're not changing their values. Settings marked "EXAMPLE" are just examples that should also be deleted.

/*
    SFUMATO Example CSS File
    ========================
    
    @import statements must be first; Sfumato imports them at build time so
    you can use Sfumato functions and directives in them (e.g. @apply).    
*/

/*
    EXAMPLE: @import styles that override any utilities.

    <div class="component-panel p-4">...</div>
    
    (e.g. p-4 will be ignored if component-panel sets padding)
*/
@import "sample/required.css";

/*
    EXAMPLE: @import styles into the components layer to allow utilities to override.
    
    <div class="component-panel p-4">...</div>
    
    (e.g. p-4 will override any padding set in component-panel)
*/
@import "sample/my-partial.css" components;

@layer sfumato {

    :root {

        /*
            Settings not marked "REQUIRED" should be deleted if you're not changing
            their values.
        
            Settings marked "EXAMPLE" are just examples that should also be deleted.
        */
        
        /* Inject the CSS reset */
        --use-reset: true;

        /* Inject form input styles */
        --use-forms: true;

        /* Compress the output CSS by default */
        --use-minify: false;

        /* Will use more compatible styles (e.g. avoid color-mix(), etc.) */
        --use-compatibility-mode: false;

        /*
            When true, dark mode is triggered by html.theme-auto
            (when prefers-color-scheme: dark) and html.theme-dark.
            
            When false, "prefers-color-scheme: dark" triggers dark mode.
        */
        --use-dark-theme-classes: false;

        /* REQUIRED: Paths for project scanning, relative to this CSS file */
        --paths: ["../example-1/", "../example-2/"];

        /* Paths to exclude from content scanning, relative to this CSS file */
        --not-paths: ["../example"];

        /* Folder names to exclude from content scanning */
        --not-folder-names: [".git", "bin", "log", "logs", "node_modules", "obj", "publish", "temp"];

        /* REQUIRED: Generated CSS file path, relative to this CSS file */
        --output-path: "sfumato.css";

        /* EXAMPLE: Add custom named colors */
        --color-primary: oklch(62.3% .214 259.815);
        --color-canvas: white;
        --color-dark-canvas: #0e1c29;
    }
        
    /* EXAMPLE: Add custom utility classes */
    @utility tab-4 {
        tab-size: 4;
    }

    /* EXAMPLE: Add custom @media or pseudo class variants */
    @custom-variant theme-midnight (&:where([data-theme="midnight"] *));
    @custom-variant widescreen (@media (width >= 96rem));
}

/* All styles within a components layer will be able to be overridden by utilities */
@layer components {

    /* EXAMPLE: sample class */
    .panel {
        @apply bg-canvas text-black;
    }
}

/* EXAMPLE: Use a variant in your CSS file */
@variant md {

    .body-text {

        /* EXAMPLE: Use utility classes in your CSS file */
        @apply text-base/6 text-black;

        /* EXAMPLE: Use --alpha() to use a named color with opacity */
        color: --alpha(var(--color-lime-500) / 15%);

        /*
            EXAMPLE: Use --spacing() for spacing lengths;
            equivalent to calc(var(--spacing) * 4)
        */
        padding-top: --spacing(4);
    }
}

/* The rest of your CSS goes here */

PRO TIP: Only configure project paths with files that will use Sfumato classes, like folders with HTML files, JavaScript files that will change element classes, etc. Use the exclusion options when appropriate. Don't scan folders unnecessarily!

Clean source CSS file example

Once you've configured your source CSS file and removed optional and example code, it may look a little more like this:

@layer sfumato {

    :root {

        --use-reset: true;
        --use-forms: true;
        --use-minify: false;
        --use-compatibility-mode: false;
        --use-dark-theme-classes: false;

        --paths: ["../Views/", "../wwwroot/"];
        --not-paths: ["../scripts/vendor/"];
        --output-path: "app.css";
    }
}

Using Sfumato

Once you have a source file established, you can try using the tool to watch project files for changes and build the output CSS file!

Command Options

The syntax for running the Sfumato CLI tool is:

sfumato {help|init|build|watch} {{css file path} {--minify} ...}

The commands are:

help
Get help on commands and usage
init
Create an example source CSS file named sfumato-example.css in the current path
build
Build the specified file(s) and exit
watch
Build the specified file(s) and watch for changes, rebuilding as necessary

sfumato watch /projects/website/css/source.css

You can append additional css file paths and minify flags to have Sfumato watch and build all of them.

sfumato build /projects/website1/css/source.css --minify /projects/website2/css/source.css

Compatibility

Styling with utility classes