1# Tailwind CSS Customization
2 
3Config file structure, custom utilities, plugins, and theme extensions.
4 
5## @theme Directive
6 
7Modern approach to customize Tailwind using CSS:
8 
9```css
10@import "tailwindcss";
11 
12@theme {
13  /* Custom colors */
14  --color-brand-50: oklch(0.97 0.02 264);
15  --color-brand-500: oklch(0.55 0.22 264);
16  --color-brand-900: oklch(0.25 0.15 264);
17 
18  /* Custom fonts */
19  --font-display: "Satoshi", "Inter", sans-serif;
20  --font-body: "Inter", system-ui, sans-serif;
21 
22  /* Custom spacing */
23  --spacing-18: calc(var(--spacing) * 18);
24  --spacing-navbar: 4.5rem;
25 
26  /* Custom breakpoints */
27  --breakpoint-3xl: 120rem;
28  --breakpoint-tablet: 48rem;
29 
30  /* Custom shadows */
31  --shadow-glow: 0 0 20px rgba(139, 92, 246, 0.3);
32 
33  /* Custom radius */
34  --radius-large: 1.5rem;
35}
36```
37 
38**Usage:**
39```html
40<div class="bg-brand-500 font-display shadow-glow rounded-large">
41  Custom themed element
42</div>
43 
44<div class="tablet:grid-cols-2 3xl:grid-cols-6">
45  Custom breakpoints
46</div>
47```
48 
49## Color Customization
50 
51### Custom Color Palette
52 
53```css
54@theme {
55  /* Full color scale */
56  --color-primary-50: oklch(0.98 0.02 250);
57  --color-primary-100: oklch(0.95 0.05 250);
58  --color-primary-200: oklch(0.90 0.10 250);
59  --color-primary-300: oklch(0.85 0.15 250);
60  --color-primary-400: oklch(0.75 0.18 250);
61  --color-primary-500: oklch(0.65 0.22 250);
62  --color-primary-600: oklch(0.55 0.22 250);
63  --color-primary-700: oklch(0.45 0.20 250);
64  --color-primary-800: oklch(0.35 0.18 250);
65  --color-primary-900: oklch(0.25 0.15 250);
66  --color-primary-950: oklch(0.15 0.10 250);
67}
68```
69 
70### Semantic Colors
71 
72```css
73@theme {
74  --color-success: oklch(0.65 0.18 145);
75  --color-warning: oklch(0.75 0.15 85);
76  --color-error: oklch(0.60 0.22 25);
77  --color-info: oklch(0.65 0.18 240);
78}
79```
80 
81```html
82<div class="bg-success text-white">Success message</div>
83<div class="border-error">Error state</div>
84```
85 
86## Typography Customization
87 
88### Custom Fonts
89 
90```css
91@theme {
92  --font-sans: "Inter", system-ui, sans-serif;
93  --font-serif: "Merriweather", Georgia, serif;
94  --font-mono: "JetBrains Mono", Consolas, monospace;
95  --font-display: "Playfair Display", serif;
96}
97```
98 
99```html
100<h1 class="font-display">Display heading</h1>
101<p class="font-sans">Body text</p>
102<code class="font-mono">Code block</code>
103```
104 
105### Custom Font Sizes
106 
107```css
108@theme {
109  --font-size-xs: 0.75rem;
110  --font-size-sm: 0.875rem;
111  --font-size-base: 1rem;
112  --font-size-lg: 1.125rem;
113  --font-size-xl: 1.25rem;
114  --font-size-2xl: 1.5rem;
115  --font-size-3xl: 1.875rem;
116  --font-size-4xl: 2.25rem;
117  --font-size-5xl: 3rem;
118  --font-size-jumbo: 4rem;
119}
120```
121 
122## Spacing Customization
123 
124```css
125@theme {
126  /* Add custom spacing values */
127  --spacing-13: calc(var(--spacing) * 13);
128  --spacing-15: calc(var(--spacing) * 15);
129  --spacing-18: calc(var(--spacing) * 18);
130 
131  /* Named spacing */
132  --spacing-header: 4rem;
133  --spacing-footer: 3rem;
134  --spacing-section: 6rem;
135}
136```
137 
138```html
139<div class="p-18">Custom padding</div>
140<section class="py-section">Section spacing</section>
141```
142 
143## Custom Utilities
144 
145Create reusable utility classes:
146 
147```css
148@utility content-auto {
149  content-visibility: auto;
150}
151 
152@utility tab-* {
153  tab-size: var(--tab-size-*);
154}
155 
156@utility glass {
157  background: rgba(255, 255, 255, 0.1);
158  backdrop-filter: blur(10px);
159  border: 1px solid rgba(255, 255, 255, 0.2);
160}
161```
162 
163**Usage:**
164```html
165<div class="content-auto">Optimized rendering</div>
166<pre class="tab-4">Code with 4-space tabs</pre>
167<div class="glass">Glassmorphism effect</div>
168```
169 
170## Custom Variants
171 
172Create custom state variants:
173 
174```css
175@custom-variant theme-midnight (&:where([data-theme="midnight"] *));
176@custom-variant aria-checked (&[aria-checked="true"]);
177@custom-variant required (&:required);
178```
179 
180**Usage:**
181```html
182<div data-theme="midnight">
183  <div class="theme-midnight:bg-navy-900">
184    Applies in midnight theme
185  </div>
186</div>
187 
188<input class="required:border-red-500" required />
189```
190 
191## Layer Organization
192 
193Organize CSS into layers:
194 
195```css
196@layer base {
197  h1 {
198    @apply text-4xl font-bold tracking-tight;
199  }
200 
201  h2 {
202    @apply text-3xl font-semibold;
203  }
204 
205  a {
206    @apply text-blue-600 hover:text-blue-700 underline-offset-4 hover:underline;
207  }
208 
209  body {
210    @apply bg-background text-foreground antialiased;
211  }
212}
213 
214@layer components {
215  .btn {
216    @apply px-4 py-2 rounded-lg font-medium transition-colors;
217  }
218 
219  .btn-primary {
220    @apply bg-blue-600 text-white hover:bg-blue-700;
221  }
222 
223  .btn-secondary {
224    @apply bg-gray-200 text-gray-900 hover:bg-gray-300;
225  }
226 
227  .card {
228    @apply bg-white rounded-xl shadow-md p-6 hover:shadow-lg transition-shadow;
229  }
230 
231  .input {
232    @apply w-full px-4 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent;
233  }
234}
235 
236@layer utilities {
237  .text-balance {
238    text-wrap: balance;
239  }
240 
241  .scrollbar-hide {
242    -ms-overflow-style: none;
243    scrollbar-width: none;
244  }
245  .scrollbar-hide::-webkit-scrollbar {
246    display: none;
247  }
248}
249```
250 
251## @apply Directive
252 
253Extract repeated utility patterns:
254 
255```css
256.btn-primary {
257  @apply bg-blue-600 hover:bg-blue-700 active:bg-blue-800 text-white font-semibold px-6 py-3 rounded-lg shadow-md hover:shadow-lg transition-all duration-200 focus:outline-none focus:ring-4 focus:ring-blue-300;
258}
259 
260.input-field {
261  @apply w-full px-4 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent disabled:bg-gray-100 disabled:cursor-not-allowed;
262}
263 
264.section-container {
265  @apply container mx-auto px-4 sm:px-6 lg:px-8 max-w-7xl;
266}
267```
268 
269**Usage:**
270```html
271<button class="btn-primary">Click me</button>
272<input class="input-field" />
273<div class="section-container">Content</div>
274```
275 
276## Plugins
277 
278### Official Plugins
279 
280```bash
281npm install -D @tailwindcss/typography @tailwindcss/forms @tailwindcss/container-queries
282```
283 
284```javascript
285// tailwind.config.js
286export default {
287  plugins: [
288    require('@tailwindcss/typography'),
289    require('@tailwindcss/forms'),
290    require('@tailwindcss/container-queries'),
291  ],
292}
293```
294 
295**Typography plugin:**
296```html
297<article class="prose lg:prose-xl">
298  <h1>Styled article</h1>
299  <p>Automatically styled prose content</p>
300</article>
301```
302 
303**Forms plugin:**
304```html
305<!-- Automatically styled form elements -->
306<input type="text" />
307<select></select>
308<textarea></textarea>
309```
310 
311### Custom Plugin
312 
313```javascript
314// tailwind.config.js
315const plugin = require('tailwindcss/plugin')
316 
317export default {
318  plugins: [
319    plugin(function({ addUtilities, addComponents, theme }) {
320      // Add utilities
321      addUtilities({
322        '.text-shadow': {
323          textShadow: '2px 2px 4px rgba(0, 0, 0, 0.1)',
324        },
325        '.text-shadow-lg': {
326          textShadow: '4px 4px 8px rgba(0, 0, 0, 0.2)',
327        },
328      })
329 
330      // Add components
331      addComponents({
332        '.card-custom': {
333          backgroundColor: theme('colors.white'),
334          borderRadius: theme('borderRadius.lg'),
335          padding: theme('spacing.6'),
336          boxShadow: theme('boxShadow.md'),
337        },
338      })
339    }),
340  ],
341}
342```
343 
344## Configuration Examples
345 
346### Complete Tailwind Config
347 
348```javascript
349// tailwind.config.ts
350import type { Config } from 'tailwindcss'
351 
352const config: Config = {
353  darkMode: ["class"],
354  content: [
355    './pages/**/*.{ts,tsx}',
356    './components/**/*.{ts,tsx}',
357    './app/**/*.{ts,tsx}',
358  ],
359  theme: {
360    container: {
361      center: true,
362      padding: "2rem",
363      screens: {
364        "2xl": "1400px",
365      },
366    },
367    extend: {
368      colors: {
369        border: "hsl(var(--border))",
370        input: "hsl(var(--input))",
371        ring: "hsl(var(--ring))",
372        background: "hsl(var(--background))",
373        foreground: "hsl(var(--foreground))",
374        primary: {
375          DEFAULT: "hsl(var(--primary))",
376          foreground: "hsl(var(--primary-foreground))",
377        },
378        brand: {
379          50: '#f0f9ff',
380          500: '#3b82f6',
381          900: '#1e3a8a',
382        },
383      },
384      fontFamily: {
385        sans: ['Inter', 'system-ui', 'sans-serif'],
386        display: ['Playfair Display', 'serif'],
387      },
388      spacing: {
389        '18': '4.5rem',
390        '88': '22rem',
391        '128': '32rem',
392      },
393      borderRadius: {
394        lg: "var(--radius)",
395        md: "calc(var(--radius) - 2px)",
396        sm: "calc(var(--radius) - 4px)",
397      },
398      keyframes: {
399        "slide-in": {
400          "0%": { transform: "translateX(-100%)" },
401          "100%": { transform: "translateX(0)" },
402        },
403      },
404      animation: {
405        "slide-in": "slide-in 0.5s ease-out",
406      },
407    },
408  },
409  plugins: [require("tailwindcss-animate")],
410}
411 
412export default config
413```
414 
415## Dark Mode Configuration
416 
417```javascript
418// tailwind.config.js
419export default {
420  darkMode: ["class"],  // or "media" for automatic
421  // ...
422}
423```
424 
425**Usage:**
426```html
427<!-- Class-based -->
428<html class="dark">
429  <div class="bg-white dark:bg-gray-900">
430    Responds to .dark class
431  </div>
432</html>
433 
434<!-- Media query-based -->
435<div class="bg-white dark:bg-gray-900">
436  Responds to system preference automatically
437</div>
438```
439 
440## Content Configuration
441 
442Specify files to scan for classes:
443 
444```javascript
445// tailwind.config.js
446export default {
447  content: [
448    "./src/**/*.{js,jsx,ts,tsx}",
449    "./app/**/*.{js,jsx,ts,tsx}",
450    "./components/**/*.{js,jsx,ts,tsx}",
451    "./pages/**/*.{js,jsx,ts,tsx}",
452  ],
453  // ...
454}
455```
456 
457### Safelist
458 
459Preserve dynamic classes:
460 
461```javascript
462export default {
463  safelist: [
464    'bg-red-500',
465    'bg-green-500',
466    'bg-blue-500',
467    {
468      pattern: /bg-(red|green|blue)-(100|500|900)/,
469    },
470  ],
471}
472```
473 
474## Best Practices
475 
4761. **Use @theme for simple customizations**: Prefer CSS-based customization
4772. **Extract components sparingly**: Use @apply only for truly repeated patterns
4783. **Leverage design tokens**: Define custom tokens in @theme
4794. **Layer organization**: Keep base, components, and utilities separate
4805. **Plugin for complex logic**: Use plugins for advanced customizations
4816. **Test dark mode**: Ensure custom colors work in both themes
4827. **Document custom utilities**: Add comments explaining custom classes
4838. **Semantic naming**: Use descriptive names (primary not blue)
484