Custom CSS for Spree Storefront - Spree Commerce documentation

Spree Storefront is built on top of Tailwind CSS 4. After installing Spree you should find a main CSS file:

app/assets/tailwind/application.css - This is the main CSS file that imports Tailwind and adds storefront styles

If you’re missing this file, or migrating from a previous version of Spree, you can generate it using the following command:

spree generate spree:storefront:install

bin/rails g spree:storefront:install

Tailwind 4 uses a CSS-first configuration approach. There’s no tailwind.config.js file - all configuration is done directly in CSS using the @theme directive.

Basic Structure

Your application.css file should look something like this:

app/assets/tailwind/application.css

@import "tailwindcss";

@theme {
  /* Theme customizations go here */
}

/* Your custom styles */

Importing Additional CSS Files

Create a new CSS file in the app/assets/stylesheets directory:

touch app/assets/tailwind/my_custom_styles.css

In the my_custom_styles.css file, add your styles:

.my-custom-class {
  color: red;
}

Then import it in your application.css file:

app/assets/tailwind/application.css

@import "tailwindcss";
@import "my_custom_styles.css"; 

Importing 3rd Party CSS Libraries

You can import a 3rd party CSS library directly from a CDN:

app/assets/tailwind/application.css

@import "tailwindcss";
@import url("https://esm.sh/swiper@11.2.2/swiper-bundle.min.css"); 

CSS Variables

Spree Storefront uses CSS variables that are automatically injected into the page. This allows store owners to change colors, fonts, etc. from the admin dashboard via Page Builder. The default variables look like this:

app/assets/tailwind/application.css

:root {
  --primary: #000000;
  --accent: #F0EFE9;
  --danger: #C73528;
  --success: #00C773;
  --neutral: #999999;

  --background: #FFFFFF;
  --text: #000000;

  --border-default-color: #E9E7DC;
  --border-default-width: 1px;
  --border-default-radius: 6px;

  --button: #000000;
  --button-rgb: 0, 0, 0;
  --button-text: #ffffff;
  --button-border-radius: 100px;
  --button-border-width: 1px;
  --button-border-color: ;

  --button-hover: #000000;
  --button-hover-text: #ffffff;

  --secondary-button: #FFFFFF;
  --secondary-button-text: #000000;
  --secondary-button-hover: #000000;
  --secondary-button-hover-text: #FFFFFF;

  --input: #E9E7DC;
  --input-bg: #ffffff;
  --input-text: #6b7280;
  --input-focus-bg: #ffffff;
  --input-border-radius: 8px;

  --neutral-50: #F3F3F3;
  --neutral-100: #EAEAEA;
  --neutral-200: #D4D4D4;
  --neutral-300: #B3B3B3;
  --neutral-400: #999999;
  --neutral-500: #808080;
  --neutral-600: #666666;
  --neutral-700: #4D4D4D;
  --neutral-800: #333333;
  --neutral-900: #1A1A1A;
  --accent-100: #FBFAF8;
}

They are defined in the app/views/themes/default/spree/shared/_css_variables.html.erb file which should be present in your theme.

Customizing with @theme

Tailwind 4 uses the @theme directive for customizations. You can extend or override the default theme:

app/assets/tailwind/application.css

@import "tailwindcss";

@theme {
  /* Add custom colors using Spree's CSS variables */
  --color-primary: var(--primary);
  --color-accent: var(--accent);
  --color-danger: var(--danger);
  --color-success: var(--success);

  /* Add custom fonts */
  --font-display: "Playfair Display", serif;

  /* Add custom spacing */
  --spacing-18: 4.5rem;

  /* Add custom border radius */
  --radius-button: var(--button-border-radius);
}

Then use them in your templates:

<div class="bg-primary text-white font-display p-18 rounded-button">
  Custom styled content
</div>

Overriding Section Styles

Each section has CSS classes you can target to customize its appearance:

/* Section container classes follow the pattern: section-{section-type} */
.section-image-with-text {
  /* Custom styles for Image with Text section */
}

.section-featured-taxon {
  /* Custom styles for Featured Taxon section */
}

/* Block-specific styles within sections */
.image-with-text--heading {
  font-family: serif;
}

.rich-text--text {
  line-height: 1.8;
}

Using Tailwind Utility Classes

You can use Tailwind utility classes directly in your templates:

<div class="flex items-center gap-4 p-6 bg-accent rounded-lg">
  <%= product.name %>
</div>

Arbitrary Values

Tailwind 4 supports arbitrary values for one-off customizations:

<div class="p-[17px] bg-[#1a1a1a] text-[13px] grid-cols-[1fr_2fr]">
  Custom values
</div>

Variant Modifiers

Use variant modifiers for responsive and state-based styles:

<div class="p-4 md:p-6 lg:p-8 hover:bg-accent active:scale-95">
  Responsive and interactive
</div>

Adding Custom Utilities

You can add custom utilities using standard CSS with the @utility directive:

@import "tailwindcss";

@utility content-auto {
  content-visibility: auto;
}

@utility scrollbar-hidden {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

Then use them like any other utility:

<div class="content-auto scrollbar-hidden">
  <!-- Content -->
</div>

Adding Custom Variants

Create custom variants with the @variant directive:

@import "tailwindcss";

@variant pointer-coarse (@media (pointer: coarse));
@variant theme-dark (&:where([data-theme="dark"], [data-theme="dark"] *));

Use them in your templates:

<button class="p-2 pointer-coarse:p-4 theme-dark:bg-gray-800">
  Touch-friendly button
</button>

Themes - Theme settings and colors
Custom JavaScript - Adding interactivity
Tailwind CSS 4 Documentation - Official Tailwind docs

​Basic Structure

​Importing Additional CSS Files

​Importing 3rd Party CSS Libraries

​CSS Variables

​Customizing with @theme

​Overriding Section Styles

​Using Tailwind Utility Classes

​Arbitrary Values

​Variant Modifiers

​Adding Custom Utilities

​Adding Custom Variants

​Related Documentation

Basic Structure

Importing Additional CSS Files

Importing 3rd Party CSS Libraries

CSS Variables

Customizing with @theme

Overriding Section Styles

Using Tailwind Utility Classes

Arbitrary Values

Variant Modifiers

Adding Custom Utilities

Adding Custom Variants

Related Documentation