M3 Tailwind Colors

M3 Tailwind Colors is a utility package that generates Material 3 color based on the Material 3 color system for use with Tailwind CSS and NativeWind.

Tailwind CSS v4 Support Now Available

• using Tailwind v4? Check out our CLI and CSS theme generation below.
• Migrating from v3 to v4? Check out our migration guide.

Demo

View Live Demo

Why M3 Tailwind Colors?

Material 3 offers a robust color system, but manually generating and managing these tonal palettes for Tailwind CSS can be overwhelming.

This package solves that by:

• Automating Palette Creation: Generates all required tonal palettes (primary, secondary, error, surface, etc.) from a single color.
• Ensuring Accessibility: Uses the official Material Color Utilities for accessible contrast ratios.
• Type Safety: Provides TypeScript support for React Native (NativeWind) and Tailwind config.
• Consistency: Guarantees your Light and Dark modes are perfectly synchronized.

Simply pick a primary color, and let the tool handle the complex color science.

Features

• Generate a full palette of Material 3 colors based on a primary color.
• NEW: Tailwind CSS v4 support with native @theme CSS variables
• NEW: CLI tool for easy theme generation
• Easily integrate with Tailwind CSS or NativeWind projects.
• Supports both light and dark color schemes.
• Hex and OKLCH color format support.

Read more about how it works here

How it works: When only a primary color is provided, it is used as a seed color to generate the entire Material 3 palette including secondary, tertiary, surface, and all other color tokens according to Material Design 3 guidelines.

Installation

Install the package via npm:

npm install m3-tailwind-colors

This will automatically install the necessary dependencies, including @material/material-color-utilities.

Note: Tailwind CSS must already be set up in your project before using this package.

Quick Start

For Tailwind v4

# Initialize configuration
npx m3-tailwind-colors init --primary "#0062A8"

# Generate CSS theme
npx m3-tailwind-colors generate

# Import in your main CSS file
# @import "./src/m3-theme.css";

For Tailwind v3

// tailwind.config.js
const { M3TailwindConfigColors } = require("m3-tailwind-colors");

module.exports = {
  theme: {
    extend: {
      colors: M3TailwindConfigColors({ primary: "#0062A8" })
    }
  }
};

Tailwind v4 Usage

CLI Commands

Initialize Configuration

Creates a m3-colors.config.json file with default values:

npx m3-tailwind-colors init --primary "#0062A8"

Options:

• --primary <color> - Primary color (hex format)
• --secondary <color> - Secondary color (optional)
• --tertiary <color> - Tertiary color (optional)
• --scheme <name> - Color scheme (content, expressive, etc.)
• --contrast <number> - Contrast level (-1 to 1)
• --format <format> - Color format (hex or oklch)
• --mode <mode> - Output mode (combined, light, or dark)
• --output <path> - Output CSS file path
• --config <path> - Config file path

Generate Theme

Generates the CSS theme file:

npx m3-tailwind-colors generate

Options:

• --include-tailwind-import - Include @import "tailwindcss" in output
• --dark-mode <strategy> - Dark mode strategy: media (default), class, or none
• --target <platform> - Target platform: web (default) or nativewind
• --colors-output <path> - Output path for the TypeScript colors file (NativeWind only)

This reads your m3-colors.config.json and outputs CSS like this (default media strategy):

@theme {
  --color-primary: #3b82f6;
  --color-on-primary: #ffffff;
  --color-surface: #fafafa;
  /* ... all Material 3 color tokens */
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-primary: #60a5fa;
    /* ... dark mode colors */
  }
}

With --dark-mode class, dark colors apply when a .dark class is on an ancestor element:

@custom-variant dark (&:where(.dark, .dark *));

@theme {
  --color-primary: #3b82f6;
  /* ... */
}

@variant dark {
  --color-primary: #60a5fa;
  /* ... */
}

With --dark-mode none, only the light @theme block is output.

Programmatic API

import { generateM3ThemeCSS } from 'm3-tailwind-colors/v4';
import fs from 'fs';

const css = generateM3ThemeCSS({
  colors: {
    primary: "#0062A8",
    secondary: "#CBF7ED",
    tertiary: "#F98948"
  },
  format: "hex",      // or "oklch"
  mode: "combined",   // or "light" or "dark"
  scheme: "content",  // Material scheme type
  contrast: 0,        // -1 to 1
  includeTailwindImport: false, // Include @import "tailwindcss"
  darkModeStrategy: "media"     // or "class" or "none"
});

fs.writeFileSync('./src/theme.css', css);

Configuration File

Example m3-colors.config.json:

{
  "colors": {
    "primary": "#0062A8",
    "secondary": "#CBF7ED",
    "tertiary": "#F98948",
    "success": "#16A34A",
    "error": "#EF4444",
    "warning": "#D14700",
    "info": "#0055D1"
  },
  "scheme": "content",
  "contrast": 0,
  "format": "hex",
  "mode": "combined",
  "output": "src/m3-theme.css"
}

Note: You can add any custom color key (like success, warning, info) and it will generate a full tonal palette for that color.

NativeWind Usage (React Native)

Generate Material 3 colors for NativeWind projects with the --target nativewind flag.

Quick Start

npx m3-tailwind-colors generate --target nativewind --primary "#0062A8"

This generates two files:

• global.css - CSS variables in NativeWind format
• theme/m3-colors.ts - TypeScript colors for React Native

Generated CSS Format

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --primary: 0 74 129;
    --on-primary: 255 255 255;
    --android-primary: 0 74 129;
  }
  @media (prefers-color-scheme: dark) {
    :root {
      --primary: 160 201 255;
    }
  }
}

Generated TypeScript Colors

export const COLORS = {
  light: {
    primary: 'rgb(0, 74, 129)',
    onPrimary: 'rgb(255, 255, 255)',
  },
  dark: {
    primary: 'rgb(160, 201, 255)',
  },
} as const;

Custom Output Paths

npx m3-tailwind-colors generate \
  --target nativewind \
  --primary "#0062A8" \
  --output "src/global.css" \
  --colors-output "src/theme/colors.ts"

Configuration File

Add target to your m3-colors.config.json:

{
  "colors": { "primary": "#0062A8" },
  "target": "nativewind",
  "colorsOutput": "theme/m3-colors.ts"
}

Migrating from NativeWindUI Starter

If you're using the NativeWindUI starter template, the generated M3 colors use different names. Update your theme/index.ts:

// theme/index.ts
import { Theme, DefaultTheme, DarkTheme } from '@react-navigation/native';
import { COLORS } from './colors';

const NAV_THEME: { light: Theme; dark: Theme } = {
  light: {
    dark: false,
    colors: {
      background: COLORS.light.background,
      border: COLORS.light.outlineVariant,     // was: grey5
      card: COLORS.light.surface,               // was: card
      notification: COLORS.light.error,         // was: destructive
      primary: COLORS.light.primary,
      text: COLORS.light.onBackground,          // was: COLORS.black
    },
    fonts: DefaultTheme.fonts,
  },
  dark: {
    dark: true,
    colors: {
      background: COLORS.dark.background,
      border: COLORS.dark.outlineVariant,       // was: grey5
      card: COLORS.dark.surfaceContainer,       // was: grey6
      notification: COLORS.dark.error,          // was: destructive
      primary: COLORS.dark.primary,
      text: COLORS.dark.onBackground,           // was: COLORS.white
    },
    fonts: DarkTheme.fonts,
  },
};

export { NAV_THEME };

Color name mappings:

Tailwind v3 Usage

To use the generated colors in your Tailwind CSS configuration, follow these steps:

• Import and Generate Colors: Use the M3TailwindConfigColors function to generate your Material 3 color palette based on a primary color.

• Extend Tailwind's Colors: Add the generated colors to the extend.colors section of your Tailwind configuration.

Example Tailwind Configuration:

/** @type {import('tailwindcss').Config} */

const { M3TailwindConfigColors } = require("m3-tailwind-colors");

const generatedColors = M3TailwindConfigColors({
  primary: "#CE7E00", // Replace with your primary color
  otherCustomColor: "#65ff34", //optional
});

module.exports = {
  content: ["./app/**/*.{js,jsx,ts,tsx}", "./components/**/*.{js,jsx,ts,tsx}"],
  presets: [require("nativewind/preset")],
  theme: {
    extend: {
      colors: {
        ...generatedColors,
      },
    },
  },
  plugins: [],
};

Usage with React Native Styling

The package exports a function that can be used to generate colors for React Native:

import { M3TailwindRNColors } from "m3-tailwind-colors";

const M3colors = M3TailwindRNColors(
  { primary: "#CE7E00" },
  {
    scheme: "content",
    contrast: 0,
  }
);

export const Colors = M3colors;

Then use in your React Native files:

<View
  style={{
    backgroundColor:
      colorScheme === "dark" ? Colors.dark.surface : Colors.light.surface,
  }}
>
  {children}
</View>

Migrating to v4

Prerequisites

npm install tailwindcss@next

Step-by-step Migration

1. Generate v4 theme:

npx m3-tailwind-colors init --primary "#0062A8"
npx m3-tailwind-colors generate

2. Update your CSS entry file:

/* Add to your main CSS file */
@import "./m3-theme.css";

3. Remove Tailwind config (optional):

# tailwind.config.js can be deleted if only used for colors
rm tailwind.config.js

4. No class name changes needed!

Your existing utility classes continue to work:

• bg-primary - Still works
• text-on-primary - Still works
• All Material 3 color tokens remain the same

Generated Colors

The generated color palette includes all Material 3 color tokens:

• Primary: primary, on-primary, primary-container, on-primary-container, inverse-primary
• Secondary: secondary, on-secondary, secondary-container, on-secondary-container
• Tertiary: tertiary, on-tertiary, tertiary-container, on-tertiary-container
• Fixed: primary-fixed, primary-fixed-dim, on-primary-fixed, on-primary-fixed-variant, and the same four for secondary and tertiary
• Error: error, on-error, error-container, on-error-container
• Surface: surface, on-surface, surface-variant, on-surface-variant, surface-dim, surface-bright, surface-container-lowest, surface-container-low, surface-container, surface-container-high, surface-container-highest, inverse-surface, on-inverse-surface, surface-tint
• Background: background, on-background
• Outline: outline, outline-variant
• Other: scrim, shadow

Fixed colors

Fixed colors keep the same value in light and dark mode. Use them for elements that should not change appearance when the theme switches, such as a brand banner or a chip on a photo:

<div class="bg-primary-fixed text-on-primary-fixed">Same in light and dark</div>

At the default contrast (0) the light and dark values are identical. At higher contrast levels, Material 3 may adjust them slightly per mode to keep text readable.

Custom colors

Each custom color (e.g. success) generates eight tokens:

• success, on-success, success-container, on-success-container
• success-fixed, success-fixed-dim, on-success-fixed, on-success-fixed-variant

In camelCase output the names are success, onSuccess, successContainer, onSuccessContainer, successFixed, successFixedDim, onSuccessFixed and onSuccessFixedVariant.

Parameters

The M3TailwindConfigColors and M3TailwindRNColors functions accept:

M3TailwindRNColors(
  {
    primary: '#ff0000', // Required: Primary color in hex format
    secondary: '#ffff00', // Optional: Auto-generated if not provided
    tertiary: '#0000ff', // Optional: Auto-generated if not provided
    customname: '#00ff00', // Optional: Any custom colors
  },
  {
    scheme: 'content', // Optional: 'content', 'expressive', 'fidelity', 'monochrome', 'neutral', 'tonalSpot', 'vibrant'
    contrast: 0, // Optional: -1 (less contrast) to 1 (more contrast)
  },
  true // Optional: Use kebab-case (default: false)
)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.