Tailwind Material 3

Tailwind Material 3

Production-ready Material Design 3 (Material You) components and tokens for Tailwind CSS v4.

✨ Features

• 🎨 Material Design 3 Spec: Full implementation of Google's Material 3 (Material You) design system.
• ⚡ Tailwind CSS v4 CSS-First: Native support for @import "tailwind-material-3"; and @theme tokens.
• 🌙 Dark Mode & Dynamic Colors: Built-in support for class-based dark mode (.dark) and CSS custom property themes.
• 🧩 18 Component Plugins & TS Helpers: Buttons, Cards, Inputs, Dialogs, Drawers, Tabs, Switches, Badges, and more.
• 📐 TypeScript Class Generators: Exported helper functions (getButtonClasses, getCardClasses, getTextFieldClasses, etc.) for type-safe framework components.
• ♿ Accessible: Follows Material 3 contrast standards and interactive accessibility rules.

---

📦 Component Catalog

Category	Components
Actions	Button, FAB, Icon Button
Communication	Badge, Snackbar, Tooltip, Progress (Linear & Circular)
Containment	Card, Dialog, Bottom Sheet
Navigation	Navigation Drawer, App Bar (Top & Bottom), Tabs
Selection & Inputs	Checkbox, Radio, Switch, Chip, Menu, Text Field
Data Display	List

---

🚀 Quick Start

1. Installation

Install tailwind-material-3 with your favorite package manager:

npm install tailwind-material-3

---

2. Configuration (Tailwind CSS v4)

Option A: CSS-First Configuration (Recommended for Tailwind v4)

In your main CSS file (e.g. src/index.css or src/app.css):

@import "tailwindcss";
@import "tailwind-material-3";

That's it! All @theme tokens (bg-md-primary, rounded-md-full, shadow-md-1, text-md-title-medium) and component utility classes (md-btn, md-card, md-text-field, etc.) are automatically registered.

Option B: JavaScript Plugin Configuration (Legacy / JS Config)

If you are using a JS/TS Tailwind config file (tailwind.config.ts):

import { tailwindMaterial3 } from 'tailwind-material-3';

export default {
  content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
  plugins: [
    tailwindMaterial3
  ]
};

---

💡 Usage Examples

Using HTML Utility Classes

<!-- Filled Button -->
<button class="md-btn md-btn-filled">
  Click Me
</button>

<!-- Outlined Card -->
<div class="md-card md-card-outlined p-4">
  <h3 class="text-md-title-medium">Card Title</h3>
  <p class="text-md-body-medium text-md-on-surface-variant">
    Material 3 card content with Tailwind v4 utilities.
  </p>
</div>

<!-- Outlined Text Field -->
<div class="md-text-field md-text-field-outlined">
  <input type="text" class="md-text-field-input" placeholder=" " />
  <label class="md-text-field-label">Username</label>
</div>

---

Using TypeScript Style Generators (React, Vue, Svelte)

You can import pure, type-safe class helper functions directly in JS/TS applications:

React Component Example:

import React from 'react';
import { getButtonClasses, getCardClasses, getTextFieldClasses } from 'tailwind-material-3';

export function MyCard() {
  const cardClasses = getCardClasses('elevated', 'medium', true);
  const buttonClasses = getButtonClasses('filled', 'primary', 'medium');

  return (
    <div className={cardClasses}>
      <h3 className="text-md-title-large">Elevated Card</h3>
      <p className="text-md-body-medium my-2">Using type-safe Material 3 style generators!</p>
      <button className={buttonClasses}>Confirm</button>
    </div>
  );
}

---

🌙 Dark Mode & Custom Themes

Tailwind Material 3 uses CSS custom properties (--md-sys-color-*). Dark mode is activated by adding the .dark class to your root element (<html class="dark">):

<html class="dark">
  <body class="bg-md-background text-md-on-background">
    <!-- UI automatically adapts to Material 3 Dark Palette -->
  </body>
</html>

Customizing Theme Colors

You can override Material 3 colors dynamically in CSS:

:root {
  --md-sys-color-primary: #0061a4;
  --md-sys-color-on-primary: #ffffff;
  --md-sys-color-primary-container: #d1e4ff;
  --md-sys-color-on-primary-container: #001d36;
}

---

🧪 Testing & Verification

Run tests and build the library locally:

# Typecheck
npm run typecheck

# Run Jest unit test suite
npm test

# Build production library bundle
npm run build

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.