# @bug-on/m3-tailwind

[![npm version](https://img.shields.io/npm/v/@bug-on/m3-tailwind.svg)](https://www.npmjs.com/package/@bug-on/m3-tailwind)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tailwind CSS v4](https://img.shields.io/badge/Tailwind_CSS-v4-38bdf8.svg)](https://tailwindcss.com/)

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

```bash
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`):

```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-extra-small` (4px)
- `rounded-m3-small` (8px)
- `rounded-m3-medium` (12px)
- `rounded-m3-large` (16px)
- `rounded-m3-extra-large` (28px)
- `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](https://bug-on-md3.vercel.app)**  
👉 **[GitHub Repository](https://github.com/nguyentruongton/bug-on-md3-expressive)**

---

## ⚖️ License

[MIT](./LICENSE)