@poupe/tailwindcss

TailwindCSS v4 plugin for Material Design 3 themes with automatic dark mode, elevation shadows, scrim overlays, and component utilities.

Table of Contents

• Features
• Installation
• Usage
  • Basic Configuration
  • Using Flat Plugin Bridge
  • CSS Import with @plugin
  • Creating Themes Programmatically
• Color System
• Shadow System
• Scrim Utilities
• Surface Components
• Dark Mode
• Configuration Options
• API Reference
• Integration with Poupe Ecosystem
• Requirements
• License

Features

• 🎨 Material Design 3 color system with automatic dark themes
• 🌓 Built-in dark mode support (class or media query)
• ✨ Elevation shadows with z-level utilities (z1-z5)
• 🎭 Scrim overlays with Material Design z-index layering
• 🛠️ Surface component utilities with proper contrast
• 📦 Lightweight, tree-shakable API
• 🧩 CSS variables for external customization

Installation

1# npm
2npm install -D @poupe/tailwindcss tailwindcss@4
3
4# yarn
5yarn add -D @poupe/tailwindcss tailwindcss@4
6
7# pnpm
8pnpm add -D @poupe/tailwindcss tailwindcss@4

Usage

Basic Configuration

tailwind.config.ts:

1import { themePlugin } from '@poupe/tailwindcss'
2
3export default {
4  plugins: [
5    themePlugin({
6      colors: {
7        primary: '#1976d2',
8        secondary: '#9c27b0',
9      }
10    }),
11  ],
12}

Flat Plugin API

More concise configuration:

1import flatPlugin from '@poupe/tailwindcss'
2
3export default {
4  plugins: [
5    flatPlugin({
6      primary: '#6750A4',
7      secondary: '#958DA5',
8      error: '#B3261E',
9
10      // Custom shades: [color, harmonize, ...shades]
11      neutral: ['#E4E1F6', true, 50, 100, 200, 300, 400, 500,
12                600, 700, 800, 900]
13    }),
14  ],
15}

CSS @plugin

Direct CSS integration:

1@import 'tailwindcss';
2
3@plugin '@poupe/tailwindcss' {
4  primary: #6750A4;
5  secondary: #958DA5;
6}

CSS Assets

The package provides two pre-built CSS files that extend TailwindCSS v4:

style.css

Minimal theme-agnostic utilities and components:

• Surface component utilities
• Shadow system utilities (z1-z5)
• Scrim overlay utilities
• Material Design z-index system
• No color values - bring your own theme

Usage with TailwindCSS:

1/* Import together with TailwindCSS base */
2@import 'tailwindcss';
3@import '@poupe/tailwindcss';  /* or '@poupe/tailwindcss/style.css' */

default.css

Complete example with Material Design 3 theme:

• Full set of Material Design 3 CSS custom properties
• Default color values for all theme colors
• Complete shadow and elevation system
• All surface and scrim utilities
• Fixed color surface combinations
• Ready-to-use example theme

Usage:

1/* Import together with TailwindCSS base */
2@import 'tailwindcss';
3@import '@poupe/tailwindcss/default.css';
4/* Override any variables as needed */

Note: These CSS files contain TailwindCSS v4 directives (@theme, @utility) and must be used together with TailwindCSS base styles.

Shadow utilities:

1<div class="shadow-z1">Level 1</div>
2<div class="shadow-z2">Level 2 (default)</div>
3<div class="shadow-z3">Level 3</div>
4<div class="shadow-z4">Level 4</div>
5<div class="shadow-z5">Level 5</div>
6<div class="inset-shadow">Inset Shadow</div>

Scrim Utilities

Modal backdrop overlays with Material Design z-index layering:

1<!-- Semantic z-index levels -->
2<div class="scrim-modal">Modal backdrop</div>
3<div class="scrim-drawer">Drawer backdrop</div>
4<div class="scrim-elevated">High priority overlay</div>
5
6<!-- With opacity modifiers -->
7<div class="scrim-modal/50">Modal with 50% opacity</div>
8<div class="scrim-drawer/75">Drawer with 75% opacity</div>
9<div class="scrim-content/25">Content overlay with 25% opacity</div>
10
11<!-- Arbitrary z-index values with opacity -->
12<div class="scrim-[1250]">Custom z-index</div>
13<div class="scrim-[1250]/40">Custom z-index with 40% opacity</div>
14<div class="scrim-[var(--custom-z)]/60">CSS variable with 60% opacity</div>

Material Design z-index scale:

1--md-z-navigation-persistent: 1000;  /* Mobile stepper, bottom nav */
2--md-z-navigation-floating: 1050;    /* FAB, speed dial */
3--md-z-navigation-top: 1100;         /* App bar, top navigation */
4--md-z-drawer: 1200;                 /* Navigation drawer */
5--md-z-modal: 1300;                  /* Modal dialogs */
6--md-z-snackbar: 1400;               /* Snackbars, toasts */
7--md-z-tooltip: 1500;                /* Tooltips */

Scrim variants (simplified naming):

• scrim-base (950) - Basic overlay, below navigation
• scrim-content (975) - Content overlay
• scrim-drawer (1250) - Drawer overlays
• scrim-modal (1275) - Modal preparation
• scrim-elevated (1350) - High-priority overlays
• scrim-system (1450) - System-level scrims

Opacity Support

All scrim utilities support Tailwind's opacity modifier syntax:

• Default opacity: 32% (when no modifier is used)
• Custom opacity: scrim-modal/50, scrim-drawer/75, etc.
• Arbitrary z-index with opacity: scrim-[100]/25

Technical Implementation:

• Uses --md-scrim-rgb variable (following the same pattern as --md-shadow-rgb)
• TailwindCSS v4 --modifier([percentage]) for capturing modifier values
• CSS custom properties enable dynamic opacity: var(--md-scrim-opacity, 32%)
• Automatic theme switching for scrim colors in dark/light modes
• Bridge pattern converts v4 syntax to v3 matchUtilities for broad compatibility

Shape System

Material Design 3 shape utilities with extensible architecture:

Shape Scale

1<!-- Shape scale utilities -->
2<div class="shape-none">No rounding (0px)</div>
3<div class="shape-extra-small">Extra small (4px)</div>
4<div class="shape-small">Small (8px)</div>
5<div class="shape-medium">Medium (12px)</div>
6<div class="shape-large">Large (16px)</div>
7<div class="shape-extra-large">Extra large (28px)</div>
8<div class="shape-full">Full rounding (999px)</div>

Shape Families

1<!-- Default rounded corners -->
2<div class="shape-medium shape-rounded">Rounded corners</div>
3
4<!-- iOS-style squircle (smooth corners) -->
5<div class="shape-medium shape-squircle">Squircle shape</div>

CSS Variables

All shapes use CSS variables for customization:

1:root {
2  --md-shape-none: 0px;
3  --md-shape-extra-small: 4px;
4  --md-shape-small: 8px;
5  --md-shape-medium: 12px;
6  --md-shape-large: 16px;
7  --md-shape-extra-large: 28px;
8  --md-shape-full: 999px;
9}

Component-Specific Shapes

Material Design 3 component shape tokens with sensible defaults:

1<!-- Component shapes with default values -->
2<button class="shape-button">Pill button (full rounding)</button>
3<div class="shape-card">Card with medium rounding</div>
4<button class="shape-fab">FAB with large rounding</button>
5<input class="shape-text-field" placeholder="Text field">
6<div class="shape-dialog">Dialog with extra-large rounding</div>
7<span class="shape-chip">Chip with small rounding</span>
8
9<!-- Squircle variants for smooth corners -->
10<button class="shape-squircle-button">Smooth pill button</button>
11<div class="shape-squircle-card">Smooth card</div>

Component shapes cascade through CSS variables:

• --md-shape-button → --md-shape-full → 999px
• --md-shape-card → --md-shape-medium → 12px
• --md-shape-fab → --md-shape-large → 16px
• --md-shape-text-field → --md-shape-extra-small → 4px
• --md-shape-dialog → --md-shape-extra-large → 28px
• --md-shape-chip → --md-shape-small → 8px

Squircle Implementation

• Uses SVG masks for true iOS-style smooth corners
• Graceful fallback to border-radius for unsupported browsers
• Configurable corner smoothing via --md-shape-corner-smooth
• Future-ready for additional shape families (cut corners, diamonds, etc.)

Programmatic Theme Generation

Generate CSS themes programmatically:

1import { makeThemeFromPartialOptions, formatTheme } from
2  '@poupe/tailwindcss'
3
4const theme = makeThemeFromPartialOptions({
5  colors: {
6    primary: { value: '#6750A4' },
7    secondary: { value: '#958DA5' },
8  },
9})
10
11const css = formatTheme(theme, 'class', '  ')
12console.log(css.join('\n'))

Color System

Comprehensive color palette with Tailwind CSS and CSS named colors:

• Tailwind Colors: Modern palette (slate, gray/grey, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose)
• CSS Named Colors: Complete CSS specification fallback (149 colors)
• Color Priority: Tailwind colors take precedence over CSS named colors
• Material Design 3: Semantic colors with automatic dark themes
• Color Shades: Automatic shade variants (50-900)
• CSS Variables: All colors accessible as --md-*

1:root {
2  --md-primary: 103, 80, 164;
3  --md-primary-50: 244, 242, 250;
4  --md-primary-500: 103, 80, 164;
5  --md-primary-900: 30, 27, 38;
6}

Color Resolution

Colors are resolved with priority order:

1import { withKnownColor } from '@poupe/tailwindcss'
2
3// Tailwind colors (highest priority)
4withKnownColor('blue')     // '#3b82f6' (Tailwind blue)
5withKnownColor('red')      // '#ef4444' (Tailwind red)
6withKnownColor('gray')     // '#6b7280' (Tailwind gray)
7withKnownColor('grey')     // '#6b7280' (British spelling alias)
8
9// CSS named colors (fallback)
10withKnownColor('crimson')  // '#dc143c' (CSS named color)
11withKnownColor('navy')     // '#000080' (CSS named color)
12
13// Unknown colors (unchanged)
14withKnownColor('#custom')  // '#custom' (unchanged)

Color Customization

Various color definition formats:

1flatPlugin({
2  primary: '#6750A4',                      // Basic color
3  secondary: ['#958DA5', false],           // No harmonization
4  neutral: [50, 100, 200, 300, 400, 500], // Custom shades
5  tertiary: ['#B58392', true, 50, 500],    // Harmonize + shades
6})

Shadow System

Material Design 3 elevation system with 5 z-levels:

• z1: Subtle elevation
• z2/DEFAULT: Standard floating elements
• z3: Prominent UI elements
• z4: Important modal windows
• z5: Critical/focused elements

Shadow utilities use --md-shadow-rgb variable for customization, while scrim utilities use --md-scrim-rgb:

1--shadow-z1: 0 1px 4px 0 rgba(var(--md-shadow-rgb), 0.37);
2--shadow-z2: 0 2px 2px 0 rgba(var(--md-shadow-rgb), 0.20),
3             0 6px 10px 0 rgba(var(--md-shadow-rgb), 0.30);

1<div class="shadow-z1">Level 1</div>
2<div class="drop-shadow-z3">Drop shadow</div>
3<div class="inset-shadow">Inset effect</div>

Surface Components

Component utilities with background + text color and proper contrast:

1<div class="surface-primary">Primary Surface</div>
2<div class="surface-secondary">Secondary Surface</div>
3<div class="surface-secondary-container">Secondary Container</div>
4
5<div class="surface-container-lowest">Lowest</div>
6<div class="surface-container-low">Low</div>
7<div class="surface-container">Standard</div>
8<div class="surface-container-high">High</div>
9<div class="surface-container-highest">Highest</div>
10
11<!-- Fixed color combinations -->
12<div class="surface-primary-fixed">Fixed background with on-fixed text</div>
13<div class="surface-primary-fixed-variant">
14  Fixed background with variant text
15</div>
16<div class="surface-primary-fixed-dim">
17  Dim fixed background with on-fixed text
18</div>
19<div class="surface-primary-fixed-dim-variant">
20  Dim fixed with variant text
21</div>

Interactive Surface Components

Interactive surface utilities combine surface styling with Material Design 3 state layer support. They automatically include hover, focus, and pressed states with proper transition timing:

1<!-- Interactive surfaces with built-in state layers -->
2<button class="interactive-surface-primary">Primary Interactive</button>
3<button class="interactive-surface-secondary">Secondary Interactive</button>
4<button class="interactive-surface-tertiary">Tertiary Interactive</button>
5
6<!-- Container variants with interaction states -->
7<div class="interactive-surface-container-lowest">Interactive Lowest</div>
8<div class="interactive-surface-container">Interactive Standard</div>
9<div class="interactive-surface-container-highest">Interactive Highest</div>
10
11<!-- Special interactive surfaces -->
12<button class="interactive-surface-inverse-primary">Inverse Primary</button>
13<button class="interactive-surface-error">Error Interactive</button>
14
15<!-- Fixed color interactive surfaces -->
16<button class="interactive-surface-primary-fixed">Fixed Interactive</button>

Interactive surfaces include:

• Automatic state layers: hover, focus, and pressed states
• Smooth transitions: Uses --md-state-transition-duration CSS variable
• Proper contrast: Maintains accessible text/background combinations
• All surface variants: Available for every standard surface utility

Animation Utilities

Material Design animation effects:

Ripple Effect

The .ripple-effect utility class provides Material Design ripple animations:

1<button class="relative overflow-hidden">
2  Click me
3  <span class="ripple-effect"></span>
4</button>

Features:

• Circular animation: Expands from center with 50% border-radius
• Configurable duration: Use --md-ripple-duration (default: 600ms)
• Configurable opacity: Use --md-ripple-opacity (default: 0.12)
• Color matching: Uses currentColor to match parent text color
• Performance: Optimized with will-change: transform, opacity

1/* Customize ripple properties */
2.custom-ripple {
3  --md-ripple-duration: 800ms;
4  --md-ripple-opacity: 0.2;
5}

Dark Mode

Automatic dark mode variants using .dark class (default):

1<html class="dark"><!-- Dark mode active --></html>

Customize dark mode strategy:

1themePlugin({
2  darkMode: 'class',        // Default: .dark class
3  // darkMode: 'media',     // Use @media (prefers-color-scheme)
4  // darkSuffix: '-dark',   // Custom dark selector
5})

Configuration Options

themePlugin() - structured options:

1{
2  themePrefix: 'md-',
3  surfacePrefix: 'surface-',
4  omitTheme: false,
5  darkSuffix: '',
6  shades: [50,100,200,300,400,500,600,700,800,900],
7  colors: { primary: { value: '#6750A4' } }
8}

flatPlugin() - flat color properties:

1{
2  themePrefix: 'md-',
3  surfacePrefix: 'surface-',
4  primary: '#6750A4',              // Direct color definition
5  secondary: ['#958DA5', false],   // [color, harmonize]
6  neutral: [50, 100, 200, 500]     // Custom shades
7}

API Reference

1// Main exports
2import flatPlugin, {
3  themePlugin,
4  makeThemeFromPartialOptions,
5  formatTheme,
6  colorFormatter
7} from '@poupe/tailwindcss'
8
9// Color system
10import { defaultColors, withKnownColor } from
11  '@poupe/tailwindcss/theme'
12
13// Theme utilities
14import { makeTheme, makeShadows, makeShades } from
15  '@poupe/tailwindcss/theme'
16
17// Color formatters: 'rgb' | 'hsl' | 'hex' | 'numbers'
18const formatter = colorFormatter('rgb')

Ecosystem

• @poupe/theme-builder - MD3 token generation
• @poupe/vue - Vue components
• @poupe/nuxt - Nuxt integration

Requirements

• Node.js >=20, TailwindCSS ^4.1

License

MIT