*/
/* ❌ WRONG: Hardcoding values in config (Tailwind 4+) */
tailwind.config.js:
module.exports = {
theme: {
colors: { primary: '#4f46e5' } // Use @theme instead
}
}
```
### ✅ ALLOWED: Use @apply for Custom Component Classes
```css
/* ✅ CORRECT: @apply for reusable component patterns */
.bg-custom-screen {
@apply bg-slate-100 transition-colors duration-300;
&:hover {
@apply bg-blue-500;
}
}
.card-base {
@apply rounded-lg shadow-md p-6 bg-white;
}
/* Use when: Multiple components share the same utility pattern */
/* ❌ AVOID: Single-use classes (use utilities directly instead) */
```
---
## Conventions
Refer to conventions for:
- Code organization
Refer to a11y for:
- Color contrast
- Focus indicators
Refer to css for:
- Custom CSS when needed
### Tailwind Specific
- Use utility classes over custom CSS
- Configure theme in tailwind.config
- Use @apply for component classes sparingly
- Leverage JIT mode for performance
- Use responsive modifiers (sm:, md:, lg:)
- **Enable dark mode** with `class` or `media` strategy
- **Configure content paths** properly to avoid purging used classes
- **Use arbitrary values** `[value]` only when necessary (prefer theme extension)
- **Combine utilities** with `@apply` for reusable component patterns
- **Optimize bundle size** with proper content configuration
---
## Decision Tree
**Tailwind class exists?** → Use utility class: `className="bg-blue-500"`.
**Dynamic value?** → Use inline style: `style={{ width: `${percent}%` }}` or arbitrary values: `w-[${value}px]`.
**Conditional styles?** → Use clsx/cn helper: `cn("base", condition && "variant")`.
**Reusable component style?** → Create component with utilities, avoid @apply.
**Custom color/spacing?** → Add to `theme.extend` in tailwind.config.js.
**Responsive design?** → Use breakpoint prefixes: `md:flex lg:grid`.
**Dark mode?** → Enable in config, use `dark:` prefix: `dark:bg-gray-800`.
**Production build?** → Ensure all template paths in `content` array or classes will be purged. Check for dynamic class names.
**Custom animations?** → Extend `theme.animation` and `theme.keyframes` in tailwind.config rather than custom CSS.
**Complex component style?** → Use `@apply` with `@layer components` for reusable patterns, but keep most styles as utilities in HTML.
---
## Example
```html
Title
```
tailwind.config.js:
```javascript
module.exports = {
content: ["./src/**/*.{astro,html,js,jsx,ts,tsx,vue,svelte}"], // ⚠️ CRITICAL
darkMode: "class", // or 'media'
theme: {
extend: {
colors: {
brand: "#1976d2",
},
},
},
};
```
### Dark Mode
```html
Content adapts to dark mode
```
```javascript
// Toggle dark mode
document.documentElement.classList.toggle("dark");
```
---
## Edge Cases
**Arbitrary values:** Use square brackets for one-off values: `w-[137px]`, `top-[117px]`. Avoid overuse—extend theme instead.
**Specificity conflicts:** Tailwind utilities have same specificity. Order in HTML matters. Use `!` prefix for important: `!mt-0`.
**Purge/content configuration:** Ensure all template paths are in `content` array or classes will be purged in production.
**Third-party component styling:** Some libraries use inline styles that override Tailwind. Use `!important` sparingly or wrapper divs.
**@layer directive:** Use `@layer components` for custom component styles, `@layer utilities` for custom utilities. Ensures proper ordering.
---
## References
- https://tailwindcss.com/docs
- https://tailwindcss.com/docs/configuration