> ## 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.
# Admin Dashboard Custom CSS
Spree Admin Dashboard uses [Tailwind CSS v4](https://tailwindcss.com/) for styling. The stylesheet system is designed to be easily customizable while maintaining consistency with the Spree design system.
## How It Works
When you install Spree Admin, the installer creates a file at `app/assets/tailwind/spree_admin.css` in your application. This file:
1. Imports the base Spree Admin styles from the gem
2. Scans your custom admin views, helpers, and JavaScript for Tailwind classes
3. Allows you to add custom styles and override theme variables
## Using Tailwind Utility Classes
You can use any Tailwind CSS utility class in your custom admin views, helpers, or JavaScript files. The build process automatically scans these locations:
* `app/views/spree/admin/**/*.erb`
* `app/helpers/spree/admin/**/*.rb`
* `app/javascript/spree/admin/**/*.js`
Example usage in a view:
```erb theme={"theme":"night-owl"}
Custom Section
Your content here
```
## Customizing the Theme
### Overriding Theme Colors
To override Tailwind theme values, add a `@theme` block in your `app/assets/tailwind/spree_admin.css` file after the import:
```css app/assets/tailwind/spree_admin.css theme={"theme":"night-owl"}
/* Import Spree Admin base styles from the gem */
@import "$SPREE_ADMIN_PATH/app/assets/tailwind/spree/admin/index.css";
/* Override theme colors */
@theme {
--color-primary: #4F46E5; /* Change primary color to indigo */
--color-success: #059669; /* Custom success color */
--color-danger: #DC2626; /* Custom danger color */
}
```
### Available Theme Variables
The Spree Admin theme defines these customizable variables:
| Variable | Default | Description |
| ----------------- | ------------------------- | ------------------------ |
| `--color-primary` | `var(--color-zinc-950)` | Primary brand color |
| `--color-success` | `var(--color-green-900)` | Success state color |
| `--color-danger` | `var(--color-red-600)` | Error/danger state color |
| `--color-warning` | `var(--color-yellow-900)` | Warning state color |
| `--color-info` | `var(--color-blue-900)` | Info state color |
### Overriding Layout Variables
You can also customize layout-related CSS variables:
```css app/assets/tailwind/spree_admin.css theme={"theme":"night-owl"}
:root {
--spacing-sidebar-width: 280px; /* Default: 220px */
--spacing-sidebar-collapsed: 70px; /* Default: 59px */
--spacing-header-height: 64px; /* Default: 58px */
}
```
## Adding Custom Components
Use Tailwind's `@layer` directive to add custom component styles that work seamlessly with the existing design:
```css app/assets/tailwind/spree_admin.css theme={"theme":"night-owl"}
@layer components {
/* Custom card style */
.my-custom-card {
@apply bg-white rounded-lg shadow-sm border border-zinc-200 p-4;
}
/* Custom button variant */
.btn-custom {
@apply inline-flex items-center px-4 py-2 rounded-md;
@apply bg-indigo-600 text-white font-medium;
@apply hover:bg-indigo-700 transition-colors;
}
/* Custom status badge */
.status-badge {
@apply inline-flex items-center px-2 py-1 rounded-full text-xs font-medium;
}
.status-badge-active {
@apply status-badge bg-green-100 text-green-800;
}
.status-badge-inactive {
@apply status-badge bg-zinc-100 text-zinc-600;
}
}
```
## Adding Custom Utilities
For reusable utility classes, use the utilities layer:
```css app/assets/tailwind/spree_admin.css theme={"theme":"night-owl"}
@layer utilities {
.text-gradient {
@apply bg-clip-text text-transparent bg-gradient-to-r from-indigo-500 to-purple-500;
}
.scrollbar-hidden {
-ms-overflow-style: none;
scrollbar-width: none;
}
.scrollbar-hidden::-webkit-scrollbar {
display: none;
}
}
```
## Scanning Additional Paths
If you have admin-related code in non-standard locations, add additional `@source` directives:
```css app/assets/tailwind/spree_admin.css theme={"theme":"night-owl"}
/* Scan host app's custom admin code for Tailwind classes */
@source "../../views/spree/admin/**/*.erb";
@source "../../helpers/spree/admin/**/*.rb";
@source "../../javascript/spree/admin/**/*.js";
/* Add your custom paths */
@source "../../components/admin/**/*.erb";
@source "../../views/admin/**/*.erb";
```
## Development Workflow
### Starting the CSS Watcher
During development, run the Tailwind CSS watcher to automatically rebuild styles when you make changes:
```bash theme={"theme":"night-owl"}
bin/rails spree:admin:tailwindcss:watch
```
Or if you're using `Procfile.dev` with foreman:
```bash theme={"theme":"night-owl"}
bin/dev
```
The watcher monitors:
* Your host app's CSS files in `app/assets/tailwind/`
* The Spree Admin engine's CSS files
* All files matching your `@source` patterns
### Building for Production
CSS is automatically compiled during asset precompilation:
```bash theme={"theme":"night-owl"}
bin/rails assets:precompile
```
## Common Customization Examples
### Custom Primary Color Scheme
```css app/assets/tailwind/spree_admin.css theme={"theme":"night-owl"}
@theme {
/* Use blue as the primary color */
--color-primary: #2563EB;
}
@layer components {
/* Ensure buttons use the new primary color */
.btn-primary {
@apply bg-blue-600 hover:bg-blue-700;
}
}
```
### Dark Mode Adjustments
```css app/assets/tailwind/spree_admin.css theme={"theme":"night-owl"}
@layer base {
/* Custom dark mode overrides */
.dark {
--color-primary: #60A5FA;
}
}
```
### Custom Form Styling
```css app/assets/tailwind/spree_admin.css theme={"theme":"night-owl"}
@layer components {
/* Custom input style */
.input-custom {
@apply block w-full rounded-md border-zinc-300 shadow-sm;
@apply focus:border-indigo-500 focus:ring-indigo-500;
}
/* Custom select style */
.select-custom {
@apply block w-full rounded-md border-zinc-300 py-2 pl-3 pr-10;
@apply focus:border-indigo-500 focus:outline-none focus:ring-indigo-500;
}
}
```
## Troubleshooting
### Changes Not Appearing
1. Ensure the watcher is running: `bin/rails spree:admin:tailwindcss:watch`
2. Check that your files are in paths covered by `@source` directives
3. Hard refresh the browser (Cmd+Shift+R or Ctrl+Shift+R)
### Missing Utility Classes
If a Tailwind class isn't working, ensure:
1. The class is used in a file that's scanned by `@source`
2. The class name is complete (not dynamically constructed)
3. Run a fresh build: `bin/rails spree:admin:tailwindcss:build`
### Listen Gem Required
The watch task requires the `listen` gem. Add it to your Gemfile:
```ruby Gemfile theme={"theme":"night-owl"}
group :development do
gem 'listen', '>= 3.0'
end
```