docs: add postcss.config.js solution for CSS import issues

Tailwind CSS v3 with npx tailwindcss CLI fails to resolve npm subpath
exports like 'activeadmin-tom_select/css' because postcss-import doesn't
support them by default.

Added recommended solution: create postcss.config.js with path: ['node_modules']
to enable clean imports without ugly ../../../node_modules/ paths.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: glebtv

docs/activeadmin-4-asset-setup.md

@@ -153,9 +153,39 @@ From ActiveAdmin's upgrade guide:
 - Run `bundle binstubs tailwindcss-ruby --force`.
 - Confirm `bin/tailwindcss` exists.
 
+### CSS Import Fails: "Failed to find 'activeadmin-tom_select/css'"
+
+This error occurs when using Tailwind CSS v3 with `npx tailwindcss` CLI because postcss-import doesn't support npm subpath exports.
+
+**Solution 1: Configure postcss-import to resolve from node_modules (recommended)**
+
+Create `postcss.config.js` in your project root:
+
+```javascript
+module.exports = {
+  plugins: {
+    'postcss-import': {
+      path: ['node_modules']
+    },
+    'tailwindcss': {},
+    'autoprefixer': {},
+  }
+}
+```
+
+Then use clean imports in your CSS:
+
+```css
+@import "activeadmin-tom_select/src/tom-select-tailwind.css";
+```
+
+**For Tailwind v4:** Use `@import "activeadmin-tom_select/css"` with the `@config` directive.
+
 ### ActiveAdmin styles not loading
 - Verify `app/assets/builds/active_admin.css` exists.
-- Check that `active_admin.tailwind.css` imports `activeadmin-tom_select/css`.
+- Check that CSS imports are correct (see above).
+- Run `npm install` to ensure packages are installed.
+- Ensure `postcss.config.js` exists if using Tailwind v3.
 
 ### Tom Select not initializing
 - Verify `window.TomSelect` in the console.

docs/guide-update-your-app.md

@@ -170,13 +170,58 @@ end
 
 ## Troubleshooting
 
+### CSS Import Fails: "Failed to find 'activeadmin-tom_select/css'"
+
+This error occurs when using Tailwind CSS v3 with `npx tailwindcss` CLI because postcss-import doesn't support npm subpath exports.
+
+**Solution 1: Configure postcss-import to resolve from node_modules (recommended)**
+
+Create `postcss.config.js` in your project root:
+
+```javascript
+module.exports = {
+  plugins: {
+    'postcss-import': {
+      path: ['node_modules']
+    },
+    'tailwindcss': {},
+    'autoprefixer': {},
+  }
+}
+```
+
+Then use clean imports in your CSS:
+
+```css
+/* app/assets/stylesheets/active_admin.tailwind.css */
+@import "tailwindcss/base";
+@import "tailwindcss/components";
+@import "tailwindcss/utilities";
+
+@import "activeadmin-tom_select/src/tom-select-tailwind.css";
+```
+
+**Solution 2: Tailwind CSS v4 with bin/tailwindcss**
+
+Tailwind v4's CLI has better module resolution. Use the `@config` directive:
+
+```css
+@import "tailwindcss";
+@config "../../../tailwind-active_admin.config.mjs";
+
+@import "activeadmin-tom_select/css";
+```
+
 ### Styles missing
 - Confirm `app/assets/builds/active_admin.css` exists.
-- Verify `active_admin.tailwind.css` imports `activeadmin-tom_select/css`.
+- Verify `active_admin.tailwind.css` imports are correct (see above).
+- Run `npm install` to ensure packages are installed.
+- Ensure `postcss.config.js` exists if using Tailwind v3.
 
 ### Tom Select not initializing
 - Ensure `window.TomSelect` is set.
 - Ensure `setupAutoInit()` runs.
+- Check browser console for JavaScript errors.
 
 ## ActiveAdmin 4.0.0.beta20 Notes (from upgrade guide)