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
[Skip CI] update admin docs around custom CSS
Damian Legawiec2dd74e0dac80
diff --git a/docs/developer/admin/admin.mdx b/docs/developer/admin/admin.mdxindex e3c993e555..bc089c24b6 100644--- a/docs/developer/admin/admin.mdx+++ b/docs/developer/admin/admin.mdx@@ -62,10 +62,8 @@ app/│ └── admin/│ └── products_helper.rb # View helpers└── assets/- └── stylesheets/- └── spree/- └── admin/- └── custom.css # Custom styles+ └── tailwind/+ └── spree_admin.css # Custom Tailwind styles```## Key Concepts@@ -137,22 +135,22 @@ Spree Admin uses [Hotwire](https://hotwire.dev/) (Turbo + Stimulus) for interact### Styling-The Admin Dashboard uses Bootstrap 5 with custom Spree styling. You can:+The Admin Dashboard uses [Tailwind CSS v4](https://tailwindcss.com/) for styling. You can:-- Add custom CSS files-- Override Bootstrap variables-- Use Tailwind-style utility classes+- Use Tailwind utility classes directly in your views+- Override theme variables (colors, spacing, typography)+- Add custom components using `@layer components`-```css-/* app/assets/stylesheets/spree/admin/custom.css */-.my-custom-card {- border-radius: 12px;- box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);-}+```erb+<%# Using Tailwind utility classes in views %>+<div class="bg-white rounded-lg shadow-sm border border-zinc-200 p-4">+ <h3 class="text-lg font-bold text-zinc-900">My Custom Card</h3>+ <p class="text-sm text-zinc-600 mt-2">Card content here</p>+</div>```<Info>- Learn how to add custom styles in [Custom CSS](/developer/admin/custom-css).+ Learn how to customize styles in [Custom CSS](/developer/admin/custom-css).</Info>## Quick Referencediff --git a/docs/developer/admin/custom-css.mdx b/docs/developer/admin/custom-css.mdxindex 07e5f474a7..6064d94639 100644--- a/docs/developer/admin/custom-css.mdx+++ b/docs/developer/admin/custom-css.mdx@@ -3,64 +3,241 @@ title: Admin Dashboard Custom CSSsidebarTitle: Custom CSS----<Warning>- This guide is still work in progress!-</Warning>+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.-Spree Admin Dashboard stylesheet system is built in top [Bootstrap](https://getbootstrap.com/) and uses [SASS](https://sass-lang.com/) preprocessor to compile custom stylesheets. To be precise we're using DART-SASS (so you don't need to install Node.js).+## How It Works-You can find the stylesheets files in [app/assets/stylesheets/spree/admin](https://github.com/spree/spree/tree/main/admin/app/assets/stylesheets/spree/admin) directory.+When you install Spree Admin, the installer creates a file at `app/assets/tailwind/spree_admin.css` in your application. This file:-The main entry point file is [application.scss](https://github.com/spree/spree/blob/main/admin/app/assets/stylesheets/spree/admin/application.scss) which uses SASS `@import` directive to include other stylesheets.+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-## Overriding existing SASS code+## Using Tailwind Utility Classes-<Warning>- This section will be added soon!-</Warning>+You can use any Tailwind CSS utility class in your custom admin views, helpers, or JavaScript files. The build process automatically scans these locations:-## Adding custom CSS+- `app/views/spree/admin/**/*.erb`+- `app/helpers/spree/admin/**/*.rb`+- `app/javascript/spree/admin/**/*.js`-Besides SASS you can still include standard CSS files. To do so:+Example usage in a view:+```erb+<div class="bg-zinc-100 p-4 rounded-lg shadow-sm">+ <h2 class="text-lg font-bold text-zinc-900">Custom Section</h2>+ <p class="text-sm text-zinc-600 mt-2">Your content here</p>+</div>+```-1. Create a new file in your application `app/assets/stylesheets` directory:+## Customizing the Theme- ```bash- touch app/assets/stylesheets/custom_spree_admin.css- ```-2. Add some CSS rules to the file:+### Overriding Theme Colors- ```css- .custom-class {- color: red;- }- ```-3. Create a template file in your application `app/views/spree/admin/shared` directory:+To override Tailwind theme values, add a `@theme` block in your `app/assets/tailwind/spree_admin.css` file after the import:- ```bash- touch app/views/spree/admin/shared/custom_spree_admin_stylesheets.html.erb- ```+```css app/assets/tailwind/spree_admin.css+/* Import Spree Admin base styles from the gem */+@import "$SPREE_ADMIN_PATH/app/assets/tailwind/spree/admin/index.css";-4. Use standard Ruby on Rails [stylesheet_link_tag](https://api.rubyonrails.org/v8.0/classes/ActionView/Helpers/AssetTagHelper.html#method-i-stylesheet_link_tag)+/* Override theme colors */+@theme {+ --color-primary: #4F46E5; /* Change primary color to indigo */+ --color-success: #059669; /* Custom success color */+ --color-danger: #DC2626; /* Custom danger color */+}+```- ```erb app/views/spree/admin/shared/custom_spree_admin_stylesheets.html.erb- <%= stylesheet_link_tag 'custom_spree_admin' %>- ```+### Available Theme Variables-5. Register this template in the Spree initializer (`config/initializers/spree.rb`):+The Spree Admin theme defines these customizable variables:- <Tabs>- <Tab title="Spree 5.2+">- ```ruby config/initializers/spree.rb- Spree.admin.partials.head << 'spree/admin/shared/custom_spree_admin_stylesheets'- ```- </Tab>- <Tab title="Spree 5.1 and below">- ```ruby config/initializers/spree.rb- Rails.application.config.spree_admin.head_partials << 'spree/admin/shared/custom_spree_admin_stylesheets'- ```- </Tab>- </Tabs>+| 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 |-That's it! Now your custom CSS code will be included after loading the standard Admin stylesheets.+### Overriding Layout Variables++You can also customize layout-related CSS variables:++```css app/assets/tailwind/spree_admin.css+: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+@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+@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+/* 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+bin/rails spree:admin:tailwindcss:watch+```++Or if you're using `Procfile.dev` with foreman:++```bash+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+bin/rails assets:precompile+```++## Common Customization Examples++### Custom Primary Color Scheme++```css app/assets/tailwind/spree_admin.css+@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+@layer base {+ /* Custom dark mode overrides */+ .dark {+ --color-primary: #60A5FA;+ }+}+```++### Custom Form Styling++```css app/assets/tailwind/spree_admin.css+@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+group :development do+ gem 'listen', '>= 3.0'+end+```diff --git a/docs/developer/admin/extending-ui.mdx b/docs/developer/admin/extending-ui.mdxindex f687efe344..3a55a35079 100644--- a/docs/developer/admin/extending-ui.mdx+++ b/docs/developer/admin/extending-ui.mdx@@ -267,7 +267,7 @@ Here's a list of all places you can inject your custom code:```<Tip>- * `dropdown-item` is a bootstrap class for styling the dropdown item+ * `dropdown-item` is a CSS class for styling the dropdown item* `target: "_blank"` is used to open the link in a new tab</Tip></Accordion>