@bug-on/m3-tailwind

Material Design 3 Expressive utility class bridge for Tailwind CSS v4. Automatically registers MD3 @theme token variables, elevations, dynamic colors (including 2025 fixed palettes), corner shapes, typography scales, icon variable font axis controls, Shiki syntax highlighter styling, and expressive spring transitions.

📦 Installation

pnpm add @bug-on/m3-tailwind
# or
npm install @bug-on/m3-tailwind

Peer Dependencies

| Package | Version Requirement | Description | | :--- | :--- | :--- | | tailwindcss | >=4.0.0 | Tailwind CSS v4 CSS-first framework |

🛠️ Configuration (Tailwind CSS v4)

[!NOTE] Tailwind CSS v4 uses a CSS-first architecture. You do NOT need a tailwind.config.js file or JS @plugin configurations.

Add the @import directive directly to your root CSS entrypoint (globals.css or index.css):

/* 1. Core Tailwind CSS v4 */
@import "tailwindcss";

/* 2. MD3 Tailwind Utility System */
@import "@bug-on/m3-tailwind";

/* 3. (Optional) Shiki Syntax Highlighter Token Theme */
@import "@bug-on/m3-tailwind/shiki";

Once imported, all MD3 design tokens and utility classes become available immediately across your project.

🎨 Supported Utility Classes

1. Dynamic Colors (bg-m3-*, text-m3-*, border-m3-*)

Mapped directly to MD3 system color tokens:

• Primary: bg-m3-primary, text-m3-on-primary, bg-m3-primary-container, text-m3-on-primary-container
• Secondary: bg-m3-secondary, text-m3-on-secondary, bg-m3-secondary-container, text-m3-on-secondary-container
• Tertiary: bg-m3-tertiary, text-m3-on-tertiary, bg-m3-tertiary-container, text-m3-on-tertiary-container
• Fixed Accent Colors (2025 Spec):
  • Primary: bg-m3-primary-fixed, text-m3-on-primary-fixed, bg-m3-primary-fixed-dim, text-m3-on-primary-fixed-variant
  • Secondary: bg-m3-secondary-fixed, text-m3-on-secondary-fixed, bg-m3-secondary-fixed-dim, text-m3-on-secondary-fixed-variant
  • Tertiary: bg-m3-tertiary-fixed, text-m3-on-tertiary-fixed, bg-m3-tertiary-fixed-dim, text-m3-on-tertiary-fixed-variant
• Error: bg-m3-error, text-m3-on-error, bg-m3-error-container, text-m3-on-error-container
• Surfaces: bg-m3-surface, bg-m3-surface-dim, bg-m3-surface-bright, bg-m3-surface-container-lowest, bg-m3-surface-container-low, bg-m3-surface-container, bg-m3-surface-container-high, bg-m3-surface-container-highest
• Outline: border-m3-outline, border-m3-outline-variant

2. Corner Radius & Shapes (rounded-m3-*)

Expressive shape corner radii following Material Design specifications:

• rounded-m3-none (0px)
• rounded-m3-xs (4px)
• rounded-m3-sm (8px)
• rounded-m3-md (12px)
• rounded-m3-lg (16px)
• rounded-m3-lg-inc (20px)
• rounded-m3-xl (28px)
• rounded-m3-xl-inc (32px)
• rounded-m3-xxl (48px)
• rounded-m3-full (9999px)

3. Depth & Elevation (shadow-m3-elevation-*)

6 levels of ambient and key depth shadows:

• shadow-m3-elevation-0: Flat surface
• shadow-m3-elevation-1: Cards, text fields
• shadow-m3-elevation-2: Extended FAB, menus
• shadow-m3-elevation-3: Dialogs, side sheets
• shadow-m3-elevation-4: Navigation drawers
• shadow-m3-elevation-5: Modal pickers

4. Typography Scale (text-m3-*)

Standardized text style tokens:

• Display: text-m3-display-large, text-m3-display-medium, text-m3-display-small
• Headline: text-m3-headline-large, text-m3-headline-medium, text-m3-headline-small
• Title: text-m3-title-large, text-m3-title-medium, text-m3-title-small
• Body: text-m3-body-large, text-m3-body-medium, text-m3-body-small
• Label: text-m3-label-large, text-m3-label-medium, text-m3-label-small

5. Icon Axis Controls (icon-fill-*, icon-wght-*, icon-grad-*, icon-opsz-*)

Utilities for variable font axes on Material Symbols:

• icon-fill-0 / icon-fill-1: Outline vs Filled icon state
• icon-wght-100 to icon-wght-700: Variable font weight
• icon-grad--25 to icon-grad-200: Fine-tuned font grade
• icon-opsz-20 to icon-opsz-48: Optical size adjustment

6. Transitions & Easing

• transition-m3-spatial: Spatial layout transitions
• transition-m3-effects: Opacity and color transitions
• ease-m3-emphasized, ease-m3-standard, ease-m3-emphasized-decelerate, ease-m3-emphasized-accelerate

📖 Complete Documentation

To explore component usage, dynamic theming APIs, and visual guides:
👉 Official Documentation & Live Demos
👉 GitHub Repository

⚖️ License

MIT