# Tailwind Patterns

> Tailwind CSS v4 principles for Angular 21.x — CSS-first @theme configuration, container queries, OKLCH color system, Bento layout patterns, dark mode strategies, and v3→v4 migration reference. Load alongside angular-spa for full Tailwind v4 coverage.

- Skill: `kumaran-is/tailwind-patterns` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kumaran-is/tailwind-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kumaran-is/tailwind-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: kumaran-is (https://skillmd.com/u/kumaran-is)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kumaran-is/tailwind-patterns

---


## Triggers

Load this skill when: configuring Tailwind v4, writing Angular templates with utility classes, migrating from Tailwind v3, implementing dark mode with daisyUI, or designing container-query-based layouts.

---

## Iron Law

**NO TAILWIND STYLING WITHOUT CHECKING THE PROJECT'S @theme CONFIGURATION FIRST — read the global CSS theme file before applying utility classes**

Load the project's CSS `@theme` configuration and verify daisyUI semantic tokens before writing any template classes.

# Tailwind CSS Patterns (v4 - 2025)

> Modern utility-first CSS with CSS-native configuration.

## When to Use

Use this skill when configuring Tailwind v4, using CSS-first theme and design tokens, implementing container queries, or applying modern Tailwind patterns in Angular 21.x templates.

---

## 1. Tailwind v4 Architecture

### What Changed from v3

| v3 (Legacy) | v4 (Current) |
|-------------|--------------|
| `tailwind.config.js` | CSS-based `@theme` directive |
| PostCSS plugin | Oxide engine (10x faster) |
| JIT mode | Native, always-on |
| Plugin system | CSS-native features |
| `@apply` directive | Still works, discouraged |

### v4 Core Concepts

| Concept | Description |
|---------|-------------|
| **CSS-first** | Configuration in CSS, not JavaScript |
| **Oxide Engine** | Rust-based compiler, much faster |
| **Native Nesting** | CSS nesting without PostCSS |
| **CSS Variables** | All tokens exposed as `--*` vars |

---

## 2. CSS-Based Configuration

### Theme Definition

```css
@theme {
  /* Colors - use semantic names */
  --color-primary: oklch(0.7 0.15 250);
  --color-surface: oklch(0.98 0 0);
  --color-surface-dark: oklch(0.15 0 0);

  /* Spacing scale */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 2rem;

  /* Typography */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}
```

### When to Extend vs Override

| Action | Use When |
|--------|----------|
| **Extend** | Adding new values alongside defaults |
| **Override** | Replacing default scale entirely |
| **Semantic tokens** | Project-specific naming (primary, surface) |

---

## 3. Container Queries (v4 Native)

### Breakpoint vs Container

| Type | Responds To |
|------|-------------|
| **Breakpoint** (`md:`) | Viewport width |
| **Container** (`@container`) | Parent element width |

### Container Query Usage

| Pattern | Classes |
|---------|---------|
| Define container | `@container` on parent |
| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |
| Named containers | `@container/card` for specificity |

### Angular Example

```html
<!-- Angular component template -->
<div class="@container">
  <div class="card @sm:card-side @lg:grid @lg:grid-cols-2">
    <!-- Responds to parent width, not viewport -->
    <!-- Use when same component appears in sidebar AND full-width page -->
  </div>
</div>
```

### When to Use

| Scenario | Use |
|----------|-----|
| Page-level layouts | Viewport breakpoints |
| Component-level responsive | Container queries |
| Reusable Angular components | Container queries (context-independent) |

---

## 4. Responsive Design

### Breakpoint System

| Prefix | Min Width | Target |
|--------|-----------|--------|
| (none) | 0px | Mobile-first base |
| `sm:` | 640px | Large phone / small tablet |
| `md:` | 768px | Tablet |
| `lg:` | 1024px | Laptop |
| `xl:` | 1280px | Desktop |
| `2xl:` | 1536px | Large desktop |

### Mobile-First Principle

1. Write mobile styles first (no prefix)
2. Add larger screen overrides with prefixes
3. Example: `w-full md:w-1/2 lg:w-1/3`

---

## 5. Dark Mode

### Configuration Strategies

| Method | Behavior | Use When |
|--------|----------|----------|
| `class` | `.dark` class toggles | Manual theme switcher |
| `media` | Follows system preference | No user control |
| `selector` | Custom selector (v4) | Complex theming |
| **daisyUI `data-theme`** | Semantic token swap | **Angular workspace standard** |

### daisyUI Dark Mode (Angular Workspace Standard)

```typescript
// theme.service.ts — daisyUI approach (workspace standard)
@Injectable({ providedIn: 'root' })
export class ThemeService {
  setTheme(theme: 'light' | 'dark'): void {
    document.documentElement.setAttribute('data-theme', theme);
    localStorage.setItem('theme', theme);
  }
}
```

```html
<!-- All daisyUI semantic classes switch automatically — no per-component CSS needed -->
<div class="bg-base-100 text-base-content">
  <!-- bg-base-100 is white in light, dark in dark theme automatically -->
</div>
```

### Raw Tailwind Dark Mode Pattern (non-daisyUI)

| Element | Light | Dark |
|---------|-------|------|
| Background | `bg-white` | `dark:bg-zinc-900` |
| Text | `text-zinc-900` | `dark:text-zinc-100` |
| Borders | `border-zinc-200` | `dark:border-zinc-700` |

---

## 6. Modern Layout Patterns

### Flexbox Patterns

| Pattern | Classes |
|---------|---------|
| Center (both axes) | `flex items-center justify-center` |
| Vertical stack | `flex flex-col gap-4` |
| Horizontal row | `flex gap-4` |
| Space between | `flex justify-between items-center` |
| Wrap grid | `flex flex-wrap gap-4` |

### Grid Patterns

| Pattern | Classes |
|---------|---------|
| Auto-fit responsive | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |
| Asymmetric (Bento) | `grid grid-cols-3 grid-rows-2` with spans |
| Sidebar layout | `grid grid-cols-[auto_1fr]` |

> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.

---

## 7. Modern Color System

### OKLCH vs RGB/HSL

| Format | Advantage |
|--------|-----------|
| **OKLCH** | Perceptually uniform, better gradients and hover states |
| **HSL** | Intuitive hue/saturation |
| **RGB** | Legacy compatibility |

### OKLCH for daisyUI Custom Themes

```css
/* Custom daisyUI theme using OKLCH — produces better hover gradients */
@plugin "daisyui" {
  themes: [{
    mytheme: {
      "primary": "oklch(0.65 0.20 280)",   /* Brand purple */
      "secondary": "oklch(0.70 0.15 200)", /* Teal */
      "accent": "oklch(0.75 0.18 160)",
      "base-100": "oklch(0.98 0 0)",
      "base-content": "oklch(0.20 0 0)",
    }
  }]
}
```

### Color Token Architecture

| Layer | Example | Purpose |
|-------|---------|---------|
| **Primitive** | `--blue-500` | Raw color values |
| **Semantic** | `--color-primary` | Purpose-based naming |
| **Component** | `--button-bg` | Component-specific |

> In Angular: use daisyUI semantic classes (`bg-primary`, `text-base-content`) — never primitives directly.

---

## 8. Typography System

### Font Stack Pattern

| Type | Recommended |
|------|-------------|
| Sans | `'Inter', 'SF Pro', system-ui, sans-serif` |
| Mono | `'JetBrains Mono', 'Fira Code', monospace` |
| Display | `'Outfit', 'Poppins', sans-serif` |

### Type Scale

| Class | Size | Use |
|-------|------|-----|
| `text-xs` | 0.75rem | Labels, captions |
| `text-sm` | 0.875rem | Secondary text |
| `text-base` | 1rem | Body text |
| `text-lg` | 1.125rem | Lead text |
| `text-xl`+ | 1.25rem+ | Headings |

---

## 9. Animation & Transitions

### Built-in Animations

| Class | Effect |
|-------|--------|
| `animate-spin` | Continuous rotation |
| `animate-ping` | Attention pulse |
| `animate-pulse` | Subtle opacity pulse |
| `animate-bounce` | Bouncing effect |

### Transition Patterns

| Pattern | Classes |
|---------|---------|
| All properties | `transition-all duration-200` |
| Specific | `transition-colors duration-150` |
| With easing | `ease-out` or `ease-in-out` |
| Hover effect | `hover:scale-105 transition-transform` |

---

## 10. Component Extraction

### When to Extract

| Signal | Action |
|--------|--------|
| Same class combo 3+ times | Extract component |
| Complex state variants | Extract component |
| Design system element | Extract + document |

### Extraction Methods

| Method | Use When |
|--------|----------|
| **Angular component / daisyUI component variant** | Dynamic, needs Angular bindings or daisyUI variant classes |
| **@apply in CSS** | Static, no JS needed |
| **Design tokens** | Reusable values |

---

## 11. Anti-Patterns

| Don't | Do |
|-------|-----|
| Arbitrary values everywhere | Use design system scale |
| `!important` | Fix specificity properly |
| Inline `style=` | Use utilities |
| Duplicate long class lists | Extract component |
| Mix v3 config with v4 | Migrate fully to CSS-first |
| Use `@apply` heavily | Prefer components |
| Use `tailwind.config.js` in v4 | Use `@theme {}` in CSS |
| Copy v3 Stack Overflow examples | Verify against v4 docs |

---

## 12. Performance Principles

| Principle | Implementation |
|-----------|----------------|
| **Purge unused** | Automatic in v4 |
| **Avoid dynamism** | No template string classes |
| **Use Oxide** | Default in v4, 10x faster |
| **Cache builds** | CI/CD caching |

---

## Related Skills

- `angular-spa` — Angular 21.x implementation with full daisyUI v5.5.5 and Tailwind v4 reference files
- `angular-best-practices` — OnPush, Signals, bundle optimization, `@defer`
- `design-system` — token enforcement (Angular + Flutter)
- `web-performance-optimization` — bundle size, CSS purging, LCP

## Additional Resources

- [Tailwind CSS v4 Docs](https://tailwindcss.com/docs)
- [daisyUI v5 Theming](https://daisyui.com/docs/themes/)
- [Container Queries MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries)
- [OKLCH Color Tool](https://oklch.com/)

---

## Verify Step

Before delivering any Tailwind changes:
1. Confirm no `tailwind.config.js` was created — v4 uses `@theme {}` in CSS only
2. Grep changed templates: `grep -n "bg-blue-\|text-blue-\|bg-red-" <file>` — zero raw primitive colors in Angular templates
3. Grep for arbitrary values: `grep -c "\[" <file>` — minimize; each must be justified
4. Confirm dark mode uses `data-theme` attribute swap (daisyUI), not `dark:` prefixes, unless project explicitly uses raw Tailwind dark mode
5. Run `ng build` to confirm the Oxide compiler picks up all classes (no purged classes)

---

> **Remember:** Tailwind v4 is CSS-first. Use `@theme {}` not `tailwind.config.js`. Use daisyUI semantic tokens in Angular templates — never raw Tailwind primitives like `bg-blue-500`.