Core Concepts

Styling with utility classes

Using simple utility classes to style complex component layouts.

Overview

In Sfumato you style markup using one or more single-purpose utility classes on your HTML elements.

You run the sfumato tool in the background in a terminal or other command window, and it will watch as you make changes to your code and build a tiny output CSS file that "just works".

Sfumato Rocks!

Using only utility classes, you can quickly create complex layouts and effects.

<div class="bg-[url(/images/alien-world.jpg)] bg-cover bg-center p-12">
    <div class="mx-auto w-72 rounded-xl backdrop-blur-md bg-white/40 border-2 border-white/20 shadow-lg text-black select-none">
        <div class="animate-small-ping rounded-2xl absolute w-full h-full outline-6 outline-white/15"></div>
        <div class="p-8 space-y-3 text-center">
            <h3 class="text-xl font-bold">Sfumato Rocks!</h3>
            <p>Using only utility classes, you can quickly create complex layouts and&nbsp;effects.</p>
        </div>
        <i class="absolute top-4 right-4 fa-light fa-times"></i>
    </div>
</div>

In the example above, some of the utility classes we used includes:

The background-image and padding utilities (e.g. bg-cover and p-12) to style the background container
The margin and width utilities (e.g. mx-auto and w-72) to set the panel size and position.
We used a blur filter to help with the frosted glass appearance (e.g. backdrop-blur-md).

At first it may seem excessive to use stacks of classes on your HTML elements. But once you get used to it you'll realize that there are practical benefits:

Creating and remediating layouts is faster
You can save time by not creating bespoke classes in one or more separate CSS files. And you don't have to worry about a deleted class breaking other layouts where you may have used it.
Code maintenance is easier
When you need to make a change to a project all you need to do is find the code for the component and change the classes. You don't have to also dig through one or more CSS files and try to figure out where the styles are or if a CSS change will break something else.
Separation of concerns is a myth
Those of us who remember CSS Zen Garden have been told to keep HTML structure and styles separate so that we can redesign our web apps with only CSS changes. Keeping HTML structure static is not an option for modern designs, which is why most of us have never used this approach.
Layouts are now portable
Since the styles of a component are embedded, you can easily move the component around without breaking its appearance.
CSS takes a back seat
Sfumato handles generating CSS for you. It shares classes, inherently resolves conflicts, and keeps the CSS tidy and compact.

These and other benefits are valuable and apply to projects of any size.

Why not use inline styles?

There are practical benefits to using Sfumato utility classes over inline style attributes. Here are some drawbacks to that approach:

Does not enforce consistency
Utility classes enforce a kind of design system that keeps things more consistent, especially with regard to color, spacing, and sizing.
Does not target element states
Inline styles can't target states like hover and focus.
Can not use media queries
Inline styles can't use media queries, like responsive design breakpoints and dark theme.
Verbosity
Using inline styles is verbose, requiring more code and creating less readable markup.

Class-first mindset

Styling hover and other states

To style an element based on states like hover or focus, prefix any utility class with the state, for example hover:bg-sky-500:

Learn more

<div class="w-fit mx-auto grid">
    <span class="bg-sky-700 hover:shadow-md hover:bg-sky-500 text-white cursor-pointer rounded-md px-5 py-2">Learn more</span>
</div>

These prefixes are called variants in Sfumato and they only apply the utility class styles when the condition for the variant matches.

The generated CSS for the hover style hover:bg-sky-500 looks like this:

.hover\:bg-sky-500:hover {
    background-color: var(--color-sky-500);
}

You can learn more about available state variants by visiting hover and other states.

Media queries and breakpoints

Similar to states like hover, you can also style elements at different breakpoints by prefixing any utility class with the breakpoint:

<div id="media-breakpoint-example" class="@container mx-auto p-3 md:p-6 overflow-auto rounded-lg outline-dashed outline-black/25 dark:outline-white/25 w-full">
    <div class="grid grid-cols-2 gap-3 md:gap-4 @xs:grid-cols-3">
        <div class="rounded bg-sky-300 p-4"></div>
        <div class="rounded bg-sky-400 p-4"></div>
        <div class="rounded bg-sky-500 p-4"></div>
        <div class="rounded bg-sky-600 p-4"></div>
        <div class="rounded bg-sky-700 p-4"></div>
        <div class="rounded bg-sky-800 p-4"></div>
    </div>
</div>
<div class="mt-6 text-center">
    <button onclick="document.getElementById(`media-breakpoint-example`).classList.toggle(`w-1/3!`);">Toggle Width</button>
</div>

This example uses container queries to simulate a page-level media query, but is still helpful for showing how they work. In this case the toggle changes the container width between 100% and 33%. At 100% width the "xs" media breakpoint is valid, changing the grid to 3 columns.

The generated CSS for the container breakpoint is:

@container (width >= 20rem) {
    .\@xs\:grid-cols-3 {
        grid-template-columns: repeat(3, minmax(0, 1fr));
    }
}

Using breakpoints outside containers is the more common scenario. The example below shows the same example but based on the viewport width, not a container. Resize your web browser to see this one in action.

Mobile (2-column) Tablet+ (3-column)

<div class="mx-auto p-3 md:p-6 overflow-auto rounded-lg outline-dashed outline-black/25 dark:outline-white/25 w-full text-center space-y-4">
    <div class="grid grid-cols-2 sm:grid-cols-3 gap-3 md:gap-4">
        <div class="rounded bg-sky-300 p-4"></div>
        <div class="rounded bg-sky-400 p-4"></div>
        <div class="rounded bg-sky-500 p-4"></div>
        <div class="rounded bg-sky-600 p-4"></div>
        <div class="rounded bg-sky-700 p-4"></div>
        <div class="rounded bg-sky-800 p-4"></div>
    </div>
    <div>
        <span class="md:hidden">Mobile (2-column)</span>
        <span class="max-md:hidden">Tablet+ (3-column)</span>
    </div>
</div>

The generated CSS for the media breakpoints is:

@media (width >= 40rem) {
    .sm\:grid-cols-3 {
        grid-template-columns: repeat(3, minmax(0, 1fr));
    }
}

Dark themes

Styling an element for dark themes uses a variant prefix (dark:), like element state and media queries:

<div class="w-fit mx-auto grid grid-cols-2 gap-x-4 text-center">
    <span class="bg-fuchsia-700 dark:bg-sky-700 text-white rounded-md px-5 py-2"><span light="Fuchsia" dark="Sky" class="after:content-[attr(light)] dark:after:content-[attr(dark)]"></span></span>
    <span class="bg-sky-700 dark:bg-fuchsia-700 text-white rounded-md px-5 py-2"><span light="Sky" dark="Fuchsia" class="after:content-[attr(light)] dark:after:content-[attr(dark)]"></span></span>
</div>

Try the theme switcher widget above and watch how the buttons appear to switch positions as the color and text change based on the dark/light theme.

Class composition

Some classes work together to style a single CSS property. One example of this are the various filter options that all use the CSS filter property.

Sfumato uses CSS variables so that these effects can be composed together:

<div class="blur-lg saturate-150">
  <!-- ... -->
</div>

.blur-lg {
    --sf-blur: blur(var(--blur-lg));
    filter: var(--sf-blur, ) var(--sf-brightness, ) var(--sf-contrast, ) var(--sf-grayscale, ) var(--sf-hue-rotate, ) var(--sf-invert, ) var(--sf-saturate, ) var(--sf-sepia, ) var(--sf-drop-shadow, );
}
.grayscale {
    --sf-grayscale: grayscale(100%);
    filter: var(--sf-blur, ) var(--sf-brightness, ) var(--sf-contrast, ) var(--sf-grayscale, ) var(--sf-hue-rotate, ) var(--sf-invert, ) var(--sf-saturate, ) var(--sf-sepia, ) var(--sf-drop-shadow, );
}

Arbitrary values

Many Sfumato utility classes like bg-sky-500, text-lg, and shadow-sm map to default values and your configured color library, type scale, shadows, etc.

When you need to specify a different, one-off value, use the square bracket syntax for specifying arbitrary values:

<button class="bg-[#ab2525] text-white">
    Cancel Task
</button>

These are especially useful for specifying complex styles, like a very specific grid configuration:

<div class="grid grid-cols-[1fr_min-content_calc(100vw_-_50%)] gap-x-8">
    <!-- ... -->
</div>

Important: utility classes cannot have spaces, so use underscores in place of spaces

You can also define entirely custom CSS, including user-defined property names—something that’s especially handy when working with CSS variables.

<div class="[tab-size:2] [--item-gap:0.5rem] lg:[--item-gap:1rem]">
  <!-- ... -->
</div>

How does this work?

Unlike traditional CSS frameworks that come as a large, fixed stylesheet, Sfumato builds your styles on demand. It identifies only the classes you use in your project.

To achieve this, it scans your entire codebase for anything resembling a class name in a string delimiter. This works across languages and platforms, from HTML and JavaScript, to hybrid mobile app frameworks, and more.

Here is an example ASP.NET Razor component:

@{
    var buttonText = Content.Value("buttonText");
    var buttonLink = Content.Value<Link>("buttonLink");
    var buttonStyles = Content.Value("buttonStyle") switch
    {
        "Small" => "rounded px-4 py-2.5",
        "Large" => "rounded-lg px-6 py-4",
        "Pill" => "rounded-full px-5 py-3",
        _ => "rounded-md px-5 py-3"
    };
}
<button class="@(buttonStyles) leading-none font-semibold text-white bg-sky-600 hover:bg-sky-500" href="@(buttonLink?.Url)" title="@(buttonLink?.Name)" target="@(buttonLink?.Target)">
    <span>@Html.Raw(buttonText)</span><i class="fa-light fa-arrow-right ml-1.5"></i>
</button>

Advanced selectors

There are cases where you need to apply styles based on multiple conditions—like being in dark mode, hitting a certain screen size, on hover, and when a particular data attribute is present.

Here’s a simplified example of how you can handle that scenario:

<button class="dark:tabp:hover:bg-fuchsia-600">
  <!-- ... -->
</button>

@media (prefers-color-scheme: dark) {
    @media (min-aspect-ratio: 0.625) {
        button:hover {
            background-color: var(--color-fuchsia-600);
        }
    }
}

Sfumato also includes support for features like group-hover, allowing you to apply styles to an element when a specific parent element is being hovered.

Most other pseudo classes (e.g. states like "focus") also work using this group-* syntax.

<a href="#" class="group inline-block rounded-full px-6 py-3 bg-sky-600 text-white">
  <!-- ... -->
  <span class="group-hover:underline">Learn More</span>
</a>

.group:hover .group-hover\:underline {
    text-decoration-line: underline;
}

When to use inline styles

Inline styles remain valuable in Sfumato projects, especially when styling needs to be driven by dynamic data from sources like APIs or databases.

You may also choose to use an inline style when dealing with complex arbitrary values that become hard to interpret when written as class names.

Managing duplication

What about duplication?

When using only utility classes to build a full project, it’s common to repeat the same set of styles across multiple elements to maintain a consistent design.

Here's an example:

<ul>
    <li class="text-sm/5 font-weight-semibold mb-2">Alison James</li>
    <li class="text-sm/5 font-weight-semibold mb-2">Fred Johnson</li>
    <li class="text-sm/5 font-weight-semibold mb-2">Douglas Astrid</li>
    <li class="text-sm/5 font-weight-semibold mb-2">Turd Ferguson</li>
    <li class="text-sm/5 font-weight-semibold mb-2">Gwen Sargento</li>
</ul>

Using loops

Often, a design element that appears multiple times on the page is only written once in the code, since it’s typically generated within a loop.

For example, the repeated list items shown above would almost certainly be rendered using a loop in a real-world project.

<ul>
@foreach(var item in namesList)
{
    <li class="text-sm/5 font-weight-semibold mb-2">@(item.FullName)</li>
}</ul>

Using components

When you want to share styles across multiple files, the most effective approach is to create a component if you’re working with a front-end framework like React, Vue, or Svelte. You can also use this strategy with platforms like ASP.NET Razor/Blazor.

Below is an example of a news panel that would be reused across your application:

<div class="rounded-xl p-8 bg-white space-y-4">
    <h3 class="text-2xl">@(Model.Headline)</div>
    <p class="text-sm">@(Model.PublishDate)</p>
    <p>@(Model.Excerpt)</p>
</div>

Using constants

Another strategy for reducing duplication is using shared string constants or properties.

@using system;
public class SharedService
{
    public const string ButtonStyles => "rounded-xl px-6 py-3 text-center bg-sky-600 text-white";

    /* Rest of your code */
}

<button class="@(SharedService.ButtonStyles)">Learn More</button>

Managing conflicts

The important modifier

In CSS conflicting styles are resolved by selector specificity first, then placement in the CSS file second.

So if you need to ensure a specific utility class takes precedence and there’s no better way to handle specificity, you can append "!" to the class name to apply !important to all of its declarations.

<div class="bg-sky-400 bg-fuchsia-500!">
    <!-- ... -->
</div>

Components layer

You can also use CSS layers to isolate your classes such that utilities can override them, or not. Just wrap your classes in a @layer components and you will be able to override their styles with utilities. Otherwise your styles will always override utilities.

<div class="override-panel bg-fuchsia">
    <!-- background will be fuchsia -->
</div>
<div class="panel bg-fuchsia">
    <!-- background will be white -->
</div>

@layer components {
    .overide-panel {
        background-color: white;
    }
}
.panel {
    background-color: white;
}

Basic usage

Hover and other states