Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: "Custom CSS for Spree Storefront"
sidebarTitle: "Custom CSS"
description: "Add custom CSS to the Spree Rails Storefront by editing the Tailwind CSS application file, generating it when missing, and overriding theme styles."
canonical: "https://spreecommerce.org/docs/v5/developer/storefront/rails/custom-css"
---
Spree Storefront is built on top of [Tailwind CSS 4](https://tailwindcss.com/). After installing Spree you should find a main CSS file:
* [app/assets/tailwind/application.css](https://github.com/spree/spree/blob/main/storefront/lib/generators/spree/storefront/install/templates/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:
<CodeGroup>
```bash Spree CLI (Docker)
spree generate spree:storefront:install
```
```bash Without Spree CLI
bin/rails g spree:storefront:install
```
</CodeGroup>
<Info>
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.
</Info>
## Basic Structure
Your [application.css](https://github.com/spree/spree/blob/main/storefront/lib/generators/spree/storefront/install/templates/application.css) file should look something like this:
```css 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:
```bash
touch app/assets/tailwind/my_custom_styles.css
```
In the `my_custom_styles.css` file, add your styles:
```css
.my-custom-class {
color: red;
}
```
Then import it in your `application.css` file:
```css app/assets/tailwind/application.css
@import "tailwindcss";
@import "my_custom_styles.css"; /* [!code ++] */
```
## Importing 3rd Party CSS Libraries
You can import a 3rd party CSS library directly from a CDN:
```css app/assets/tailwind/application.css
@import "tailwindcss";
@import url("https://esm.sh/[email protected]/swiper-bundle.min.css"); /* [!code ++] */
```
## 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:
```css 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](https://github.com/spree/spree/blob/main/storefront/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:
```css 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:
```erb
<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:
```css
/* 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:
```erb
<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:
```erb
<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:
```erb
<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:
```css
@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:
```erb
<div class="content-auto scrollbar-hidden">
<!-- Content -->
</div>
```
## Adding Custom Variants
Create custom variants with the `@variant` directive:
```css
@import "tailwindcss";
@variant pointer-coarse (@media (pointer: coarse));
@variant theme-dark (&:where([data-theme="dark"], [data-theme="dark"] *));
```
Use them in your templates:
```erb
<button class="p-2 pointer-coarse:p-4 theme-dark:bg-gray-800">
Touch-friendly button
</button>
```
## Related Documentation
- [Themes](/v5/developer/storefront/rails/themes) - Theme settings and colors
- [Custom JavaScript](/v5/developer/storefront/rails/custom-javascript) - Adding interactivity
- [Tailwind CSS 4 Documentation](https://tailwindcss.com/docs) - Official Tailwind docs