Introduction

LowCSS is a utility-first CSS framework that uses a PostCSS plugin to generate utility classes. This guide will help you customize LowCSS to fit your project's needs.

Build Process

PostCSS is required to process the custom @utility and @theme rules, as these are not standard CSS syntax and won't work without the LowCSS plugin.

Before you start customizing LowCSS, ensure you have the necessary PostCSS setup in place.

$ npm install postcss postcss-cli postcss-import lowcss

You can use either a postcss.config.js file or run PostCSS directly from the command line. Both methods will allow you to compile your LowCSS stylesheets.

Option 1: Using postcss.config.js

You can create a postcss.config.js file in your project root to define your PostCSS plugins, including the LowCSS plugin.

module.exports = {
    plugins: [
        require("postcss-import"),
        require("lowcss"),
        // ... add any other PostCSS plugins you need
    ],
};

Then, create an index.css file where you will import your theme and utility definitions.

@import "theme.css"; /* Your theme definitions */
@import "utilities.css"; /* Your utility definitions */
/* Import other utility files as needed */

Finally, you can run PostCSS using the CLI to process your stylesheets. Make sure you have the necessary PostCSS plugins installed, such as postcss-import.

$ npx postcss index.css -o low.css

This command will process your index.css file, applying the LowCSS plugin and any other PostCSS plugins you have configured, and output the compiled CSS to low.css.

Option 2: Using PostCSS CLI

You can run PostCSS directly from the command line without a config file:

$ npx postcss index.css --use postcss-import --use lowcss --no-map -o low.css

This command processes index.css, applying the postcss-import and lowcss plugins, and outputs the result to low.css. The --no-map option disables source maps, which is useful for production builds.

Theme Customization

LowCSS uses the @theme rule to define CSS variables that can be used throughout your stylesheets and to generate utility classes. This allows you to create a consistent design system for your project.

Basic Theme Usage

You can define your theme variables using the @theme rule. This is where you set your colors, fonts, spacing, and other design tokens.

@theme {
    /* Your custom colors */
    --color-primary: #3b82f6;
    --color-secondary: #10b981;

    /* Your custom font family */
    --font-family-base: "Inter", sans-serif;
    
    /* Your custom spacing */
    --spacing-0: 0;
    --spacing-1: 0.25rem;
    --spacing-2: 0.5rem;
    --spacing-4: 1rem;
    --spacing-8: 2rem;
}

These variables will be used to generate utility classes, but you can also use them directly in your stylesheets as needed. For example, you can use var(--color-primary) to apply the primary color to an element.

.button {
    background-color: var(--color-primary);
    color: white;
    font-family: var(--font-family-base);
    padding: var(--spacing-2) var(--spacing-4);
}

Refer to the theme namespaces page to see how variables map to utility classes.

Breakpoints

You can define responsive breakpoints in your theme to create responsive utility classes.

@theme {
    --breakpoint-sm: 640px;
    --breakpoint-md: 768px;
    --breakpoint-lg: 1024px;
    --breakpoint-xl: 1280px;
}

These breakpoints can be used to create responsive utility classes that apply styles at different screen sizes.

Creating Custom Utilities

LowCSS uses the @utility rule to define utility classes. Utility classes are single-purpose CSS classes that can be applied to elements to control their styling without writing custom CSS.

Static Utilities

You can create custom utility classes using the @utility rule.

@utility {
    opacity-50 {
        opacity: 0.5;
    }
    opacity-75 {
        opacity: 0.75;
    }
    opacity-100 {
        opacity: 1;
    }
}

This will generate utility classes like .opacity-50, .opacity-75, and .opacity-100 that you can apply to elements in your HTML.

Dynamic Utilities

You can create dynamic utilities using the * wildcard and value() function. This allows you to generate utility classes for all available values in your theme.

@utility {
    p-* {
        padding: value(--spacing-*);
    }
    px-* {
        padding-left: value(--spacing-*);
        padding-right: value(--spacing-*);
    }
    py-* {
        padding-top: value(--spacing-*);
        padding-bottom: value(--spacing-*);
    }
}

This will generate utility classes for all available spacing values: p-1 to apply a padding of 0.25rem, p-2 for 0.5rem, px-4 for 1rem on left and right, etc.

You can also combine static and dynamic utilities in the same @utility block.

@utility {
    m-* {
        margin: value(--spacing-*);
    }
    ml-* {
        margin-left: value(--spacing-*);
    }
    mr-* {
        margin-right: value(--spacing-*);
    }
    ml-auto {
        margin-left: auto;
    }
    mr-auto {
        margin-right: auto;
    }
}

Working with Variants

Variants allow you to generate utility classes that only apply under certain conditions, like hover states or at specific breakpoints. This is useful for creating responsive designs and interactive elements without writing custom CSS.

Basic Variants

Use the @variant rule inside a utility to define variants. This allows you to create utility classes that apply styles under specific conditions, such as hover or focus states.

@utility {
    @variant default,hover,focus {
        bg-red-500 {
            background-color: var(--color-red-500);
        }
        bg-blue-500 {
            background-color: var(--color-blue-500);
        }
    }
}

This will generate utility classes for the background colors with variants: .bg-red-500 for the default state, .hover\:bg-red-500:hover for the hover state, and .focus\:bg-red-500:focus for the focus state.

You can also combine multiple @variant rules to create more complex utilities that apply under different conditions.

@utility {
    @variant default,hover {
        text-blue-500 {
            color: var(--color-blue-500);
        }
    }
    @variant focus {
        text-red-500 {
            color: var(--color-red-500);
        }
    }
}

Available Variants

LowCSS supports a variety of variants that can be used to generate utility classes for different states and conditions. These variants allow you to create responsive and interactive designs without writing custom CSS.