tailwind-patterns

name	tailwind-patterns
description	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.
risk	low
source	community (adapted for Angular 21.x)
date_added	2026-02-27
updated	2026-03-15
last-reviewed	2026-03-15
allowed-tools	["Read","Grep","Glob","Edit","Write"]

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

@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

<!-- 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)

// 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);
  }
}

<!-- 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

/* 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
• daisyUI v5 Theming
• Container Queries MDN
• OKLCH Color Tool

---

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.