moai-lang-tailwind-css

Tailwind CSS: Utility-First Framework for Rapid UI Development

Primary Agent: frontend-expert
Secondary Agent: ui-ux-expert
Version: 1.0.0 (Tailwind CSS v4.0+)
Keywords: tailwind, tailwind css, utility-first, css framework, responsive, customization, design tokens, performance

📖 Progressive Disclosure

Level 1: Quick Reference (Core Concepts)

Tailwind CSS is a utility-first CSS framework that enables building custom designs directly in HTML:

Installation (v4.0+):

npm install -D tailwindcss

# Create config file
npx tailwindcss init

Basic Setup:

/* app.css */
@import "tailwindcss";

Key Breakpoints (mobile-first):

Level 2: Practical Implementation (Common Patterns)

Pattern 1: Basic Tailwind Setup with Design Tokens

/* app.css */
@import "tailwindcss";

@theme {
  /* Colors - semantic naming */
  --color-primary: #0ea5e9;
  --color-primary-dark: #0284c7;
  --color-success: #10b981;
  --color-warning: #f59e0b;
  --color-error: #ef4444;

  --color-neutral-50: #f9fafb;
  --color-neutral-100: #f3f4f6;
  --color-neutral-900: #111827;

  /* Typography */
  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  --font-mono: "Monaco", "Menlo", "Ubuntu Mono", monospace;

  /* Spacing - 8px base unit */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
  --spacing-2xl: 3rem;

  /* Breakpoints */
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
}

Pattern 2: Responsive Component with Tailwind

// React component using Tailwind
function Card({ title, description, image }) {
  return (
    <div className="rounded-lg shadow-md overflow-hidden hover:shadow-lg transition-shadow">
      {/* Image - responsive sizing */}
      <img
        src={image}
        alt={title}
        className="w-full h-48 md:h-64 object-cover"
      />

      {/* Content - responsive padding */}
      <div className="p-4 md:p-6">
        <h3 className="text-lg md:text-xl font-bold text-gray-900 mb-2">
          {title}
        </h3>

        <p className="text-gray-600 text-sm md:text-base mb-4">
          {description}
        </p>

        {/* Button */}
        <button className="px-4 py-2 bg-blue-500 text-white rounded-md hover:bg-blue-600 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-500 transition-colors">
          Learn More
        </button>
      </div>
    </div>
  );
}

Pattern 3: Tailwind Configuration with Custom Theme

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./index.html",
  ],
  theme: {
    extend: {
      colors: {
        primary: {
          50: "#f0f9ff",
          100: "#e0f2fe",
          500: "#0ea5e9",
          600: "#0284c7",
          900: "#0c2d4a",
        },
        semantic: {
          success: "#10b981",
          warning: "#f59e0b",
          error: "#ef4444",
        },
      },
      spacing: {
        xs: "0.25rem",
        sm: "0.5rem",
        md: "1rem",
        lg: "1.5rem",
        xl: "2rem",
        "2xl": "3rem",
      },
      fontFamily: {
        sans: [
          "-apple-system",
          "BlinkMacSystemFont",
          '"Segoe UI"',
          "sans-serif",
        ],
        mono: ["Monaco", "Menlo", "monospace"],
      },
      fontSize: {
        xs: ["0.75rem", { lineHeight: "1rem" }],
        sm: ["0.875rem", { lineHeight: "1.25rem" }],
        base: ["1rem", { lineHeight: "1.5rem" }],
        lg: ["1.125rem", { lineHeight: "1.75rem" }],
        xl: ["1.25rem", { lineHeight: "1.75rem" }],
      },
      borderRadius: {
        sm: "0.25rem",
        md: "0.375rem",
        lg: "0.5rem",
        xl: "0.75rem",
      },
      boxShadow: {
        sm: "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
        md: "0 4px 6px 0 rgba(0, 0, 0, 0.1)",
        lg: "0 10px 15px 0 rgba(0, 0, 0, 0.1)",
      },
    },
  },
  plugins: [
    require("@tailwindcss/forms"),
    require("@tailwindcss/typography"),
  ],
};

Pattern 4: Dark Mode Toggle

function DarkModeToggle() {
  const [isDark, setIsDark] = React.useState(false);

  return (
    <div className={isDark ? "dark" : ""}>
      <button
        onClick={() => setIsDark(!isDark)}
        className="px-4 py-2 bg-gray-200 dark:bg-gray-800 text-gray-900 dark:text-gray-100 rounded-lg"
      >
        {isDark ? "🌙" : "☀️"}
      </button>

      {/* Component that respects dark mode */}
      <div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white p-6">
        <h1 className="text-2xl font-bold">Dark Mode Example</h1>
        <p className="text-gray-600 dark:text-gray-400 mt-2">
          This text changes color in dark mode.
        </p>
      </div>
    </div>
  );
}

Pattern 5: Responsive Grid Layout

// Responsive grid: 1 column mobile, 2 columns tablet, 3 columns desktop
function ProductGrid({ products }) {
  return (
    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 md:gap-6">
      {products.map((product) => (
        <div
          key={product.id}
          className="rounded-lg border border-gray-200 overflow-hidden hover:shadow-lg transition-shadow"
        >
          <img
            src={product.image}
            alt={product.name}
            className="w-full h-40 object-cover"
          />
          <div className="p-4">
            <h3 className="font-bold text-gray-900">{product.name}</h3>
            <p className="text-gray-600 text-sm mt-1">{product.description}</p>
            <div className="mt-4 flex justify-between items-center">
              <span className="font-bold text-primary-600">${product.price}</span>
              <button className="px-3 py-1 bg-primary-500 text-white rounded-md hover:bg-primary-600 text-sm">
                Add to Cart
              </button>
            </div>
          </div>
        </div>
      ))}
    </div>
  );
}

Level 3: Advanced Patterns (Expert Reference)

Advanced Pattern 1: Custom Variants and Plugins

// tailwind.config.js - Custom variant plugin
const plugin = require("tailwindcss/plugin");

module.exports = {
  theme: {
    extend: {},
  },
  plugins: [
    // Custom variant: group-hover-children
    plugin(function ({ addVariant }) {
      addVariant("group-hover-children", ":where(.group:hover) & > *");
    }),

    // Custom utility: safe area
    plugin(function ({ matchUtilities, theme }) {
      matchUtilities(
        {
          safe: (value) => ({
            paddingLeft: `max(${value}, env(safe-area-inset-left))`,
            paddingRight: `max(${value}, env(safe-area-inset-right))`,
          }),
        },
        {
          values: theme("spacing"),
        }
      );
    }),
  ],
};

Usage in HTML:

<!-- Custom variant -->
<div class="group">
  <div class="group-hover-children:text-blue-500">Text changes on parent hover</div>
</div>

<!-- Custom utility -->
<div class="safe-4">Safe area padding</div>

Advanced Pattern 2: Dynamic Color System with CSS Variables

// Create dynamic color system
const generateColorShades = (hex) => {
  // Convert hex to HSL, generate shades
  const shades = {
    50: lighten(hex, 0.95),
    100: lighten(hex, 0.9),
    500: hex,
    900: darken(hex, 0.9),
  };
  return shades;
};

module.exports = {
  theme: {
    colors: {
      primary: generateColorShades("#0ea5e9"),
      secondary: generateColorShades("#8b5cf6"),
    },
  },
};

Advanced Pattern 3: Container Queries (Modern Approach)

/* app.css */
@import "tailwindcss";

@theme {
  --container-sm: 24rem;
  --container-md: 28rem;
  --container-lg: 32rem;
  --container-xl: 36rem;
}

// Usage
function ResponsiveCard() {
  return (
    <div className="@container">
      {/* Responsive to container, not viewport */}
      <div className="@sm:grid @sm:grid-cols-2 @md:grid-cols-3">
        {/* Content */}
      </div>
    </div>
  );
}

🎯 Performance Best Practices

1. Purging Unused CSS

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    // Include all files that may contain Tailwind classes
    "./components/**/*.{js,jsx}",
    "./pages/**/*.{js,jsx}",
  ],
};

2. Avoid Dynamic Class Names

// ❌ BAD - Tailwind can't scan this
const padding = "p-4"; // Dynamic string
className={`p-${size}`}

// ✅ GOOD - Static class names
className={size === "sm" ? "p-2" : "p-4"}

3. Extract Reusable Components

/* Instead of repeating classes, use @layer components */
@layer components {
  .btn-primary {
    @apply px-4 py-2 bg-blue-500 text-white rounded-md hover:bg-blue-600 transition-colors;
  }

  .card {
    @apply rounded-lg shadow-md p-6 bg-white;
  }
}

4. Tree-Shaking and Code Splitting

// Webpack config - enable tree-shaking
mode: "production", // Automatically enables minification
optimization: {
  usedExports: true,
}

📚 Official References

• Tailwind CSS Docs: https://tailwindcss.com/docs
• Tailwind UI: https://tailwindui.com/ (Component examples)
• Tailwind IntelliSense: VS Code extension for autocomplete
• Tailwind CSS Plugins: https://tailwindcss.com/docs/plugins
• Headless UI: https://headlessui.com/ (Unstyled, accessible components)

🔗 Related Skills

• Skill("moai-lang-html-css") – Semantic HTML & CSS foundations
• Skill("moai-lib-shadcn-ui") – Pre-built Tailwind components
• Skill("moai-domain-frontend") – Full frontend architecture with Tailwind