# Tailwind Drupal

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-trebormc-drupal-ai-agents-tailwind-drupal`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [trebormc](https://agentstack.voostack.com/s/trebormc)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [trebormc](https://github.com/trebormc)
- **Source:** https://github.com/trebormc/drupal-ai-agents/tree/main/.claude/skills/tailwind-drupal

## Install

```sh
agentstack add skill-trebormc-drupal-ai-agents-tailwind-drupal
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## CRITICAL RULE

**Every time you add, modify, or remove Tailwind classes in ANY file (.twig,
.html.twig, .php, .module, .theme), you MUST recompile the CSS and clear
Drupal caches.** Tailwind only includes classes it finds in scanned files.
New classes that aren't compiled will NOT appear in the browser.

### Mandatory post-change sequence

```bash
# 1. Recompile Tailwind CSS (ALWAYS after class changes)
ssh web npm run build --prefix $DDEV_DOCROOT/themes/custom/

# 2. Clear Drupal cache (renders may reference old CSS)
ssh web drush cr

# 3. Verify in browser with hard refresh (Ctrl+Shift+R / Cmd+Shift+R)
#    Or use Playwright with cache disabled for testing
```

**If you skip step 1, new Tailwind classes will NOT render.** This is the
most common cause of "Tailwind classes not working."

## Installation in a Drupal theme

```bash
# Navigate to theme directory inside container
ssh web bash -c "cd $DDEV_DOCROOT/themes/custom/ && npm init -y"
ssh web bash -c "cd $DDEV_DOCROOT/themes/custom/ && npm install -D tailwindcss"
ssh web bash -c "cd $DDEV_DOCROOT/themes/custom/ && npx tailwindcss init"
```

## Configuration files

### package.json (in theme root)

```json
{
  "scripts": {
    "dev": "npx tailwindcss -i ./src/input.css -o ./css/styles.css --watch",
    "build": "npx tailwindcss -i ./src/input.css -o ./css/styles.css --minify"
  },
  "devDependencies": {
    "tailwindcss": "^3.4"
  }
}
```

| Script | Use | When |
|--------|-----|------|
| `npm run dev` | Watch mode, auto-recompile on file changes | During active development |
| `npm run build` | One-time compile + minify | Before commit, after changes |

### tailwind.config.js

```javascript
/** @type {import('tailwindcss').Config} */
module.exports = {
  // NOTE: all content paths are relative to the THEME directory (where this file lives)
  content: [
    // Drupal theme templates
    './templates/**/*.html.twig',
    './components/**/*.html.twig',
    // Custom modules that use Tailwind classes
    '../../modules/custom/**/*.html.twig',
    '../../modules/custom/**/*.php',
    '../../modules/custom/**/*.module',
    // Theme PHP files (preprocess functions with class arrays)
    './*.theme',
  ],
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          100: '#dbeafe',
          200: '#bfdbfe',
          300: '#93c5fd',
          400: '#60a5fa',
          500: '#3b82f6',
          600: '#2563eb',
          700: '#1d4ed8',
          800: '#1e40af',
          900: '#1e3a8a',
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
    },
  },
  plugins: [],
}
```

**CRITICAL**: The `content` array must include ALL file paths where Tailwind
classes appear. If a file is not scanned, its classes are purged from the
compiled CSS.

### src/input.css

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Custom component classes (use @apply sparingly) */
@layer components {
  .btn-primary {
    @apply inline-flex items-center px-4 py-2 text-sm font-medium text-white bg-primary-600 hover:bg-primary-700 rounded-lg transition-colors focus:outline-none focus:ring-2 focus:ring-primary-500 focus:ring-offset-2;
  }
}
```

### Drupal library definition (mytheme.libraries.yml)

```yaml
tailwind:
  css:
    theme:
      css/styles.css: { minified: true }
```

Attach in your base template (e.g., `html.html.twig` or `page.html.twig`):
```twig
{{ attach_library('mytheme/tailwind') }}
```

## Build commands

```bash
# Development: watch mode (auto-recompiles on save)
ssh web npm run dev --prefix $DDEV_DOCROOT/themes/custom/

# Production: one-time build with minification
ssh web npm run build --prefix $DDEV_DOCROOT/themes/custom/

# After build, ALWAYS clear Drupal cache
ssh web drush cr
```

## Responsive breakpoints

| Prefix | Min-width | Use for |
|--------|-----------|---------|
| (none) | 0px | Mobile first (default) |
| `sm:` | 640px | Small tablets |
| `md:` | 768px | Tablets |
| `lg:` | 1024px | Desktops |
| `xl:` | 1280px | Large screens |
| `2xl:` | 1536px | Extra large |

Always design **mobile-first**: write base styles without prefix, then add
breakpoint prefixes for larger screens.

## Troubleshooting

| Problem | Cause | Fix |
|---------|-------|-----|
| Classes not rendering | CSS not recompiled | `npm run build` → `drush cr` → hard refresh |
| Classes purged in prod | File path missing from `content` array | Add path to `tailwind.config.js` content |
| Styles cached in browser | Browser using old CSS | Hard refresh (Ctrl+Shift+R) or clear browser cache |
| Classes in PHP not found | `.php`/`.module`/`.theme` files not in content | Add `'../../modules/custom/**/*.php'` to content |
| Watch mode not detecting | File outside content paths | Add missing glob pattern to content array |
| `@apply` not working | Custom class not in @layer | Wrap in `@layer components { }` |
| `npm run build` fails | Missing node_modules | `ssh web npm install --prefix $DDEV_DOCROOT/themes/custom/` then rebuild |
| `npm: command not found` | Command run in wrong container | Prefix the command with `ssh web ` |

## Verification

After ANY Tailwind class change:

```bash
# 1. Build
ssh web npm run build --prefix $DDEV_DOCROOT/themes/custom/

# 2. Verify the compiled file exists AND contains the new class (replace CLASS):
ssh web test -f $DDEV_DOCROOT/themes/custom//css/styles.css && echo "FILE OK"
ssh web grep -c "CLASS" $DDEV_DOCROOT/themes/custom//css/styles.css
# Output 0 or "FILE OK" missing → build failed or class not in a scanned path (check content array)

# 3. Clear Drupal cache
ssh web drush cr

# 4. Test in browser (use Playwright or hard refresh)
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [trebormc](https://github.com/trebormc)
- **Source:** [trebormc/drupal-ai-agents](https://github.com/trebormc/drupal-ai-agents)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-trebormc-drupal-ai-agents-tailwind-drupal
- Seller: https://agentstack.voostack.com/s/trebormc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.