@vodailoc/kilo-kit-mcp 1.1.0 → 1.2.0

package/skills/design/ui-styling/references/tailwind-customization.md

@@ -1,483 +1,483 @@
-# Tailwind CSS Customization
-
-Config file structure, custom utilities, plugins, and theme extensions.
-
-## @theme Directive
-
-Modern approach to customize Tailwind using CSS:
-
-```css
-@import "tailwindcss";
-
-@theme {
-  /* Custom colors */
-  --color-brand-50: oklch(0.97 0.02 264);
-  --color-brand-500: oklch(0.55 0.22 264);
-  --color-brand-900: oklch(0.25 0.15 264);
-
-  /* Custom fonts */
-  --font-display: "Satoshi", "Inter", sans-serif;
-  --font-body: "Inter", system-ui, sans-serif;
-
-  /* Custom spacing */
-  --spacing-18: calc(var(--spacing) * 18);
-  --spacing-navbar: 4.5rem;
-
-  /* Custom breakpoints */
-  --breakpoint-3xl: 120rem;
-  --breakpoint-tablet: 48rem;
-
-  /* Custom shadows */
-  --shadow-glow: 0 0 20px rgba(139, 92, 246, 0.3);
-
-  /* Custom radius */
-  --radius-large: 1.5rem;
-}
-```
-
-**Usage:**
-```html
-<div class="bg-brand-500 font-display shadow-glow rounded-large">
-  Custom themed element
-</div>
-
-<div class="tablet:grid-cols-2 3xl:grid-cols-6">
-  Custom breakpoints
-</div>
-```
-
-## Color Customization
-
-### Custom Color Palette
-
-```css
-@theme {
-  /* Full color scale */
-  --color-primary-50: oklch(0.98 0.02 250);
-  --color-primary-100: oklch(0.95 0.05 250);
-  --color-primary-200: oklch(0.90 0.10 250);
-  --color-primary-300: oklch(0.85 0.15 250);
-  --color-primary-400: oklch(0.75 0.18 250);
-  --color-primary-500: oklch(0.65 0.22 250);
-  --color-primary-600: oklch(0.55 0.22 250);
-  --color-primary-700: oklch(0.45 0.20 250);
-  --color-primary-800: oklch(0.35 0.18 250);
-  --color-primary-900: oklch(0.25 0.15 250);
-  --color-primary-950: oklch(0.15 0.10 250);
-}
-```
-
-### Semantic Colors
-
-```css
-@theme {
-  --color-success: oklch(0.65 0.18 145);
-  --color-warning: oklch(0.75 0.15 85);
-  --color-error: oklch(0.60 0.22 25);
-  --color-info: oklch(0.65 0.18 240);
-}
-```
-
-```html
-<div class="bg-success text-white">Success message</div>
-<div class="border-error">Error state</div>
-```
-
-## Typography Customization
-
-### Custom Fonts
-
-```css
-@theme {
-  --font-sans: "Inter", system-ui, sans-serif;
-  --font-serif: "Merriweather", Georgia, serif;
-  --font-mono: "JetBrains Mono", Consolas, monospace;
-  --font-display: "Playfair Display", serif;
-}
-```
-
-```html
-<h1 class="font-display">Display heading</h1>
-<p class="font-sans">Body text</p>
-<code class="font-mono">Code block</code>
-```
-
-### Custom Font Sizes
-
-```css
-@theme {
-  --font-size-xs: 0.75rem;
-  --font-size-sm: 0.875rem;
-  --font-size-base: 1rem;
-  --font-size-lg: 1.125rem;
-  --font-size-xl: 1.25rem;
-  --font-size-2xl: 1.5rem;
-  --font-size-3xl: 1.875rem;
-  --font-size-4xl: 2.25rem;
-  --font-size-5xl: 3rem;
-  --font-size-jumbo: 4rem;
-}
-```
-
-## Spacing Customization
-
-```css
-@theme {
-  /* Add custom spacing values */
-  --spacing-13: calc(var(--spacing) * 13);
-  --spacing-15: calc(var(--spacing) * 15);
-  --spacing-18: calc(var(--spacing) * 18);
-
-  /* Named spacing */
-  --spacing-header: 4rem;
-  --spacing-footer: 3rem;
-  --spacing-section: 6rem;
-}
-```
-
-```html
-<div class="p-18">Custom padding</div>
-<section class="py-section">Section spacing</section>
-```
-
-## Custom Utilities
-
-Create reusable utility classes:
-
-```css
-@utility content-auto {
-  content-visibility: auto;
-}
-
-@utility tab-* {
-  tab-size: var(--tab-size-*);
-}
-
-@utility glass {
-  background: rgba(255, 255, 255, 0.1);
-  backdrop-filter: blur(10px);
-  border: 1px solid rgba(255, 255, 255, 0.2);
-}
-```
-
-**Usage:**
-```html
-<div class="content-auto">Optimized rendering</div>
-<pre class="tab-4">Code with 4-space tabs</pre>
-<div class="glass">Glassmorphism effect</div>
-```
-
-## Custom Variants
-
-Create custom state variants:
-
-```css
-@custom-variant theme-midnight (&:where([data-theme="midnight"] *));
-@custom-variant aria-checked (&[aria-checked="true"]);
-@custom-variant required (&:required);
-```
-
-**Usage:**
-```html
-<div data-theme="midnight">
-  <div class="theme-midnight:bg-navy-900">
-    Applies in midnight theme
-  </div>
-</div>
-
-<input class="required:border-red-500" required />
-```
-
-## Layer Organization
-
-Organize CSS into layers:
-
-```css
-@layer base {
-  h1 {
-    @apply text-4xl font-bold tracking-tight;
-  }
-
-  h2 {
-    @apply text-3xl font-semibold;
-  }
-
-  a {
-    @apply text-blue-600 hover:text-blue-700 underline-offset-4 hover:underline;
-  }
-
-  body {
-    @apply bg-background text-foreground antialiased;
-  }
-}
-
-@layer components {
-  .btn {
-    @apply px-4 py-2 rounded-lg font-medium transition-colors;
-  }
-
-  .btn-primary {
-    @apply bg-blue-600 text-white hover:bg-blue-700;
-  }
-
-  .btn-secondary {
-    @apply bg-gray-200 text-gray-900 hover:bg-gray-300;
-  }
-
-  .card {
-    @apply bg-white rounded-xl shadow-md p-6 hover:shadow-lg transition-shadow;
-  }
-
-  .input {
-    @apply w-full px-4 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent;
-  }
-}
-
-@layer utilities {
-  .text-balance {
-    text-wrap: balance;
-  }
-
-  .scrollbar-hide {
-    -ms-overflow-style: none;
-    scrollbar-width: none;
-  }
-  .scrollbar-hide::-webkit-scrollbar {
-    display: none;
-  }
-}
-```
-
-## @apply Directive
-
-Extract repeated utility patterns:
-
-```css
-.btn-primary {
-  @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;
-}
-
-.input-field {
-  @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;
-}
-
-.section-container {
-  @apply container mx-auto px-4 sm:px-6 lg:px-8 max-w-7xl;
-}
-```
-
-**Usage:**
-```html
-<button class="btn-primary">Click me</button>
-<input class="input-field" />
-<div class="section-container">Content</div>
-```
-
-## Plugins
-
-### Official Plugins
-
-```bash
-npm install -D @tailwindcss/typography @tailwindcss/forms @tailwindcss/container-queries
-```
-
-```javascript
-// tailwind.config.js
-export default {
-  plugins: [
-    require('@tailwindcss/typography'),
-    require('@tailwindcss/forms'),
-    require('@tailwindcss/container-queries'),
-  ],
-}
-```
-
-**Typography plugin:**
-```html
-<article class="prose lg:prose-xl">
-  <h1>Styled article</h1>
-  <p>Automatically styled prose content</p>
-</article>
-```
-
-**Forms plugin:**
-```html
-<!-- Automatically styled form elements -->
-<input type="text" />
-<select></select>
-<textarea></textarea>
-```
-
-### Custom Plugin
-
-```javascript
-// tailwind.config.js
-const plugin = require('tailwindcss/plugin')
-
-export default {
-  plugins: [
-    plugin(function({ addUtilities, addComponents, theme }) {
-      // Add utilities
-      addUtilities({
-        '.text-shadow': {
-          textShadow: '2px 2px 4px rgba(0, 0, 0, 0.1)',
-        },
-        '.text-shadow-lg': {
-          textShadow: '4px 4px 8px rgba(0, 0, 0, 0.2)',
-        },
-      })
-
-      // Add components
-      addComponents({
-        '.card-custom': {
-          backgroundColor: theme('colors.white'),
-          borderRadius: theme('borderRadius.lg'),
-          padding: theme('spacing.6'),
-          boxShadow: theme('boxShadow.md'),
-        },
-      })
-    }),
-  ],
-}
-```
-
-## Configuration Examples
-
-### Complete Tailwind Config
-
-```javascript
-// tailwind.config.ts
-import type { Config } from 'tailwindcss'
-
-const config: Config = {
-  darkMode: ["class"],
-  content: [
-    './pages/**/*.{ts,tsx}',
-    './components/**/*.{ts,tsx}',
-    './app/**/*.{ts,tsx}',
-  ],
-  theme: {
-    container: {
-      center: true,
-      padding: "2rem",
-      screens: {
-        "2xl": "1400px",
-      },
-    },
-    extend: {
-      colors: {
-        border: "hsl(var(--border))",
-        input: "hsl(var(--input))",
-        ring: "hsl(var(--ring))",
-        background: "hsl(var(--background))",
-        foreground: "hsl(var(--foreground))",
-        primary: {
-          DEFAULT: "hsl(var(--primary))",
-          foreground: "hsl(var(--primary-foreground))",
-        },
-        brand: {
-          50: '#f0f9ff',
-          500: '#3b82f6',
-          900: '#1e3a8a',
-        },
-      },
-      fontFamily: {
-        sans: ['Inter', 'system-ui', 'sans-serif'],
-        display: ['Playfair Display', 'serif'],
-      },
-      spacing: {
-        '18': '4.5rem',
-        '88': '22rem',
-        '128': '32rem',
-      },
-      borderRadius: {
-        lg: "var(--radius)",
-        md: "calc(var(--radius) - 2px)",
-        sm: "calc(var(--radius) - 4px)",
-      },
-      keyframes: {
-        "slide-in": {
-          "0%": { transform: "translateX(-100%)" },
-          "100%": { transform: "translateX(0)" },
-        },
-      },
-      animation: {
-        "slide-in": "slide-in 0.5s ease-out",
-      },
-    },
-  },
-  plugins: [require("tailwindcss-animate")],
-}
-
-export default config
-```
-
-## Dark Mode Configuration
-
-```javascript
-// tailwind.config.js
-export default {
-  darkMode: ["class"],  // or "media" for automatic
-  // ...
-}
-```
-
-**Usage:**
-```html
-<!-- Class-based -->
-<html class="dark">
-  <div class="bg-white dark:bg-gray-900">
-    Responds to .dark class
-  </div>
-</html>
-
-<!-- Media query-based -->
-<div class="bg-white dark:bg-gray-900">
-  Responds to system preference automatically
-</div>
-```
-
-## Content Configuration
-
-Specify files to scan for classes:
-
-```javascript
-// tailwind.config.js
-export default {
-  content: [
-    "./src/**/*.{js,jsx,ts,tsx}",
-    "./app/**/*.{js,jsx,ts,tsx}",
-    "./components/**/*.{js,jsx,ts,tsx}",
-    "./pages/**/*.{js,jsx,ts,tsx}",
-  ],
-  // ...
-}
-```
-
-### Safelist
-
-Preserve dynamic classes:
-
-```javascript
-export default {
-  safelist: [
-    'bg-red-500',
-    'bg-green-500',
-    'bg-blue-500',
-    {
-      pattern: /bg-(red|green|blue)-(100|500|900)/,
-    },
-  ],
-}
-```
-
-## Best Practices
-
-1. **Use @theme for simple customizations**: Prefer CSS-based customization
-2. **Extract components sparingly**: Use @apply only for truly repeated patterns
-3. **Leverage design tokens**: Define custom tokens in @theme
-4. **Layer organization**: Keep base, components, and utilities separate
-5. **Plugin for complex logic**: Use plugins for advanced customizations
-6. **Test dark mode**: Ensure custom colors work in both themes
-7. **Document custom utilities**: Add comments explaining custom classes
-8. **Semantic naming**: Use descriptive names (primary not blue)
+# Tailwind CSS Customization
+
+Config file structure, custom utilities, plugins, and theme extensions.
+
+## @theme Directive
+
+Modern approach to customize Tailwind using CSS:
+
+```css
+@import "tailwindcss";
+
+@theme {
+  /* Custom colors */
+  --color-brand-50: oklch(0.97 0.02 264);
+  --color-brand-500: oklch(0.55 0.22 264);
+  --color-brand-900: oklch(0.25 0.15 264);
+
+  /* Custom fonts */
+  --font-display: "Satoshi", "Inter", sans-serif;
+  --font-body: "Inter", system-ui, sans-serif;
+
+  /* Custom spacing */
+  --spacing-18: calc(var(--spacing) * 18);
+  --spacing-navbar: 4.5rem;
+
+  /* Custom breakpoints */
+  --breakpoint-3xl: 120rem;
+  --breakpoint-tablet: 48rem;
+
+  /* Custom shadows */
+  --shadow-glow: 0 0 20px rgba(139, 92, 246, 0.3);
+
+  /* Custom radius */
+  --radius-large: 1.5rem;
+}
+```
+
+**Usage:**
+```html
+<div class="bg-brand-500 font-display shadow-glow rounded-large">
+  Custom themed element
+</div>
+
+<div class="tablet:grid-cols-2 3xl:grid-cols-6">
+  Custom breakpoints
+</div>
+```
+
+## Color Customization
+
+### Custom Color Palette
+
+```css
+@theme {
+  /* Full color scale */
+  --color-primary-50: oklch(0.98 0.02 250);
+  --color-primary-100: oklch(0.95 0.05 250);
+  --color-primary-200: oklch(0.90 0.10 250);
+  --color-primary-300: oklch(0.85 0.15 250);
+  --color-primary-400: oklch(0.75 0.18 250);
+  --color-primary-500: oklch(0.65 0.22 250);
+  --color-primary-600: oklch(0.55 0.22 250);
+  --color-primary-700: oklch(0.45 0.20 250);
+  --color-primary-800: oklch(0.35 0.18 250);
+  --color-primary-900: oklch(0.25 0.15 250);
+  --color-primary-950: oklch(0.15 0.10 250);
+}
+```
+
+### Semantic Colors
+
+```css
+@theme {
+  --color-success: oklch(0.65 0.18 145);
+  --color-warning: oklch(0.75 0.15 85);
+  --color-error: oklch(0.60 0.22 25);
+  --color-info: oklch(0.65 0.18 240);
+}
+```
+
+```html
+<div class="bg-success text-white">Success message</div>
+<div class="border-error">Error state</div>
+```
+
+## Typography Customization
+
+### Custom Fonts
+
+```css
+@theme {
+  --font-sans: "Inter", system-ui, sans-serif;
+  --font-serif: "Merriweather", Georgia, serif;
+  --font-mono: "JetBrains Mono", Consolas, monospace;
+  --font-display: "Playfair Display", serif;
+}
+```
+
+```html
+<h1 class="font-display">Display heading</h1>
+<p class="font-sans">Body text</p>
+<code class="font-mono">Code block</code>
+```
+
+### Custom Font Sizes
+
+```css
+@theme {
+  --font-size-xs: 0.75rem;
+  --font-size-sm: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-lg: 1.125rem;
+  --font-size-xl: 1.25rem;
+  --font-size-2xl: 1.5rem;
+  --font-size-3xl: 1.875rem;
+  --font-size-4xl: 2.25rem;
+  --font-size-5xl: 3rem;
+  --font-size-jumbo: 4rem;
+}
+```
+
+## Spacing Customization
+
+```css
+@theme {
+  /* Add custom spacing values */
+  --spacing-13: calc(var(--spacing) * 13);
+  --spacing-15: calc(var(--spacing) * 15);
+  --spacing-18: calc(var(--spacing) * 18);
+
+  /* Named spacing */
+  --spacing-header: 4rem;
+  --spacing-footer: 3rem;
+  --spacing-section: 6rem;
+}
+```
+
+```html
+<div class="p-18">Custom padding</div>
+<section class="py-section">Section spacing</section>
+```
+
+## Custom Utilities
+
+Create reusable utility classes:
+
+```css
+@utility content-auto {
+  content-visibility: auto;
+}
+
+@utility tab-* {
+  tab-size: var(--tab-size-*);
+}
+
+@utility glass {
+  background: rgba(255, 255, 255, 0.1);
+  backdrop-filter: blur(10px);
+  border: 1px solid rgba(255, 255, 255, 0.2);
+}
+```
+
+**Usage:**
+```html
+<div class="content-auto">Optimized rendering</div>
+<pre class="tab-4">Code with 4-space tabs</pre>
+<div class="glass">Glassmorphism effect</div>
+```
+
+## Custom Variants
+
+Create custom state variants:
+
+```css
+@custom-variant theme-midnight (&:where([data-theme="midnight"] *));
+@custom-variant aria-checked (&[aria-checked="true"]);
+@custom-variant required (&:required);
+```
+
+**Usage:**
+```html
+<div data-theme="midnight">
+  <div class="theme-midnight:bg-navy-900">
+    Applies in midnight theme
+  </div>
+</div>
+
+<input class="required:border-red-500" required />
+```
+
+## Layer Organization
+
+Organize CSS into layers:
+
+```css
+@layer base {
+  h1 {
+    @apply text-4xl font-bold tracking-tight;
+  }
+
+  h2 {
+    @apply text-3xl font-semibold;
+  }
+
+  a {
+    @apply text-blue-600 hover:text-blue-700 underline-offset-4 hover:underline;
+  }
+
+  body {
+    @apply bg-background text-foreground antialiased;
+  }
+}
+
+@layer components {
+  .btn {
+    @apply px-4 py-2 rounded-lg font-medium transition-colors;
+  }
+
+  .btn-primary {
+    @apply bg-blue-600 text-white hover:bg-blue-700;
+  }
+
+  .btn-secondary {
+    @apply bg-gray-200 text-gray-900 hover:bg-gray-300;
+  }
+
+  .card {
+    @apply bg-white rounded-xl shadow-md p-6 hover:shadow-lg transition-shadow;
+  }
+
+  .input {
+    @apply w-full px-4 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent;
+  }
+}
+
+@layer utilities {
+  .text-balance {
+    text-wrap: balance;
+  }
+
+  .scrollbar-hide {
+    -ms-overflow-style: none;
+    scrollbar-width: none;
+  }
+  .scrollbar-hide::-webkit-scrollbar {
+    display: none;
+  }
+}
+```
+
+## @apply Directive
+
+Extract repeated utility patterns:
+
+```css
+.btn-primary {
+  @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;
+}
+
+.input-field {
+  @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;
+}
+
+.section-container {
+  @apply container mx-auto px-4 sm:px-6 lg:px-8 max-w-7xl;
+}
+```
+
+**Usage:**
+```html
+<button class="btn-primary">Click me</button>
+<input class="input-field" />
+<div class="section-container">Content</div>
+```
+
+## Plugins
+
+### Official Plugins
+
+```bash
+npm install -D @tailwindcss/typography @tailwindcss/forms @tailwindcss/container-queries
+```
+
+```javascript
+// tailwind.config.js
+export default {
+  plugins: [
+    require('@tailwindcss/typography'),
+    require('@tailwindcss/forms'),
+    require('@tailwindcss/container-queries'),
+  ],
+}
+```
+
+**Typography plugin:**
+```html
+<article class="prose lg:prose-xl">
+  <h1>Styled article</h1>
+  <p>Automatically styled prose content</p>
+</article>
+```
+
+**Forms plugin:**
+```html
+<!-- Automatically styled form elements -->
+<input type="text" />
+<select></select>
+<textarea></textarea>
+```
+
+### Custom Plugin
+
+```javascript
+// tailwind.config.js
+const plugin = require('tailwindcss/plugin')
+
+export default {
+  plugins: [
+    plugin(function({ addUtilities, addComponents, theme }) {
+      // Add utilities
+      addUtilities({
+        '.text-shadow': {
+          textShadow: '2px 2px 4px rgba(0, 0, 0, 0.1)',
+        },
+        '.text-shadow-lg': {
+          textShadow: '4px 4px 8px rgba(0, 0, 0, 0.2)',
+        },
+      })
+
+      // Add components
+      addComponents({
+        '.card-custom': {
+          backgroundColor: theme('colors.white'),
+          borderRadius: theme('borderRadius.lg'),
+          padding: theme('spacing.6'),
+          boxShadow: theme('boxShadow.md'),
+        },
+      })
+    }),
+  ],
+}
+```
+
+## Configuration Examples
+
+### Complete Tailwind Config
+
+```javascript
+// tailwind.config.ts
+import type { Config } from 'tailwindcss'
+
+const config: Config = {
+  darkMode: ["class"],
+  content: [
+    './pages/**/*.{ts,tsx}',
+    './components/**/*.{ts,tsx}',
+    './app/**/*.{ts,tsx}',
+  ],
+  theme: {
+    container: {
+      center: true,
+      padding: "2rem",
+      screens: {
+        "2xl": "1400px",
+      },
+    },
+    extend: {
+      colors: {
+        border: "hsl(var(--border))",
+        input: "hsl(var(--input))",
+        ring: "hsl(var(--ring))",
+        background: "hsl(var(--background))",
+        foreground: "hsl(var(--foreground))",
+        primary: {
+          DEFAULT: "hsl(var(--primary))",
+          foreground: "hsl(var(--primary-foreground))",
+        },
+        brand: {
+          50: '#f0f9ff',
+          500: '#3b82f6',
+          900: '#1e3a8a',
+        },
+      },
+      fontFamily: {
+        sans: ['Inter', 'system-ui', 'sans-serif'],
+        display: ['Playfair Display', 'serif'],
+      },
+      spacing: {
+        '18': '4.5rem',
+        '88': '22rem',
+        '128': '32rem',
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+      keyframes: {
+        "slide-in": {
+          "0%": { transform: "translateX(-100%)" },
+          "100%": { transform: "translateX(0)" },
+        },
+      },
+      animation: {
+        "slide-in": "slide-in 0.5s ease-out",
+      },
+    },
+  },
+  plugins: [require("tailwindcss-animate")],
+}
+
+export default config
+```
+
+## Dark Mode Configuration
+
+```javascript
+// tailwind.config.js
+export default {
+  darkMode: ["class"],  // or "media" for automatic
+  // ...
+}
+```
+
+**Usage:**
+```html
+<!-- Class-based -->
+<html class="dark">
+  <div class="bg-white dark:bg-gray-900">
+    Responds to .dark class
+  </div>
+</html>
+
+<!-- Media query-based -->
+<div class="bg-white dark:bg-gray-900">
+  Responds to system preference automatically
+</div>
+```
+
+## Content Configuration
+
+Specify files to scan for classes:
+
+```javascript
+// tailwind.config.js
+export default {
+  content: [
+    "./src/**/*.{js,jsx,ts,tsx}",
+    "./app/**/*.{js,jsx,ts,tsx}",
+    "./components/**/*.{js,jsx,ts,tsx}",
+    "./pages/**/*.{js,jsx,ts,tsx}",
+  ],
+  // ...
+}
+```
+
+### Safelist
+
+Preserve dynamic classes:
+
+```javascript
+export default {
+  safelist: [
+    'bg-red-500',
+    'bg-green-500',
+    'bg-blue-500',
+    {
+      pattern: /bg-(red|green|blue)-(100|500|900)/,
+    },
+  ],
+}
+```
+
+## Best Practices
+
+1. **Use @theme for simple customizations**: Prefer CSS-based customization
+2. **Extract components sparingly**: Use @apply only for truly repeated patterns
+3. **Leverage design tokens**: Define custom tokens in @theme
+4. **Layer organization**: Keep base, components, and utilities separate
+5. **Plugin for complex logic**: Use plugins for advanced customizations
+6. **Test dark mode**: Ensure custom colors work in both themes
+7. **Document custom utilities**: Add comments explaining custom classes
+8. **Semantic naming**: Use descriptive names (primary not blue)