> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom CSS for Spree Storefront

> Add custom CSS to the Spree Rails Storefront by editing the Tailwind CSS application file, generating it when missing, and overriding theme styles.

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) theme={"theme":"night-owl"}
  spree generate spree:storefront:install
  ```

  ```bash Without Spree CLI theme={"theme":"night-owl"}
  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 theme={"theme":"night-owl"}
@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 theme={"theme":"night-owl"}
touch app/assets/tailwind/my_custom_styles.css
```

In the `my_custom_styles.css` file, add your styles:

```css theme={"theme":"night-owl"}
.my-custom-class {
  color: red;
}
```

Then import it in your `application.css` file:

```css app/assets/tailwind/application.css theme={"theme":"night-owl"}
@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 theme={"theme":"night-owl"}
@import "tailwindcss";
@import url("https://esm.sh/swiper@11.2.2/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 theme={"theme":"night-owl"}
: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 theme={"theme":"night-owl"}
@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 theme={"theme":"night-owl"}
<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 theme={"theme":"night-owl"}
/* 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 theme={"theme":"night-owl"}
<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 theme={"theme":"night-owl"}
<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 theme={"theme":"night-owl"}
<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 theme={"theme":"night-owl"}
@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 theme={"theme":"night-owl"}
<div class="content-auto scrollbar-hidden">
  <!-- Content -->
</div>
```

## Adding Custom Variants

Create custom variants with the `@variant` directive:

```css theme={"theme":"night-owl"}
@import "tailwindcss";

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

Use them in your templates:

```erb theme={"theme":"night-owl"}
<button class="p-2 pointer-coarse:p-4 theme-dark:bg-gray-800">
  Touch-friendly button
</button>
```

## Related Documentation

* [Themes](/developer/storefront/rails/themes) - Theme settings and colors
* [Custom JavaScript](/developer/storefront/rails/custom-javascript) - Adding interactivity
* [Tailwind CSS 4 Documentation](https://tailwindcss.com/docs) - Official Tailwind docs