Getting Started

Basic usage

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

Set up your project

Sfumato works by reading a source CSS file and generating an output CSS file which is what your project should actually use. 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)

Sfumato can create a sample file for you. Navigate to the folder where you want the file created, and run the init command:

> sfumato init

This will create a reference file named sfumato-example.css with all the configuration options and examples for custom colors, variants, etc. You should rename the file to something more appropriate, like `source.css` and make changes to suit your project.

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!

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 a sample source CSS file in the current path
build
Build the specified file(s)
watch
Build then watch specified project paths for changes and rebuild the output CSS file(s)

> sfumato build /projects/website/css/source.css --minify

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

Installation

Styling with utility classes

Getting Started

Basic usage

Set up your project

Using Sfumato

Command Options

Sfumato

Community