CSS to Tailwind Converter

A powerful utility library for bidirectional conversion between CSS properties and Tailwind CSS class names.

Features

• 🔄 Bidirectional Conversion: CSS properties ↔ Tailwind class names
• 🎨 Complete Color Support: Supports OKLCH, RGB, HEX, and other color formats
• 📏 Spacing Handling: Automatic handling of margin, padding, and other spacing properties
• 🎯 Type Safe: Complete TypeScript type definitions
• 🚀 Lightweight: No external dependencies (except for Tailwind to CSS conversion)
• 🔧 Extensible: Supports custom configuration and extensions
• ⚙️ Flexible Configuration: Supports custom color mappings and style mappings

Installation

npm install @metagptx/css-to-tailwind

Usage

CSS to Tailwind Conversion

import { cssToTailwind } from '@metagptx/css-to-tailwind';

// Basic usage
const cssProps = {
  backgroundColor: '#3b82f6',
  color: '#ffffff',
  padding: '16px',
  margin: '8px',
  borderRadius: '8px',
  fontSize: '1rem',
  fontWeight: '600',
  textDecoration: 'underline',
  fontVariantNumeric: 'tabular-nums',
};

const tailwindClasses = cssToTailwind(cssProps);
console.log(tailwindClasses);
// Output: "bg-[#3b82f6] text-[#ffffff] p-[16px] m-[8px] rounded-[8px] text-base font-semibold underline tabular-nums"

Using Custom Configuration

import { cssToTailwind } from '@metagptx/css-to-tailwind';
import type { ConverterConfig } from '@metagptx/css-to-tailwind';

// Custom color mappings
const customConfig: ConverterConfig = {
  colorMaps: {
    background: {
      '#ff0000': 'bg-red-custom',
      '#00ff00': 'bg-green-custom',
      '#3b82f6': 'bg-blue-500', // Override default mapping
    },
    text: {
      '#ffffff': 'text-white-custom',
      '#000000': 'text-black-custom',
    },
  },
  styleMaps: {
    fontSize: {
      '1rem': 'text-custom-base',
      '2rem': 'text-custom-xl',
    },
    fontWeight: {
      '600': 'font-custom-semibold',
      '700': 'font-custom-bold',
    },
    textAlign: {
      center: 'text-custom-center',
      left: 'text-custom-left',
    },
    display: {
      flex: 'flex-custom',
      block: 'block-custom',
    },
    position: {
      relative: 'relative-custom',
      absolute: 'absolute-custom',
    },
    borderRadius: {
      '8px': 'rounded-custom',
    },
    fontFamily: {
      'ui-sans-serif': 'font-custom-sans',
    },
  },
};

const cssProps = {
  backgroundColor: '#ff0000',
  color: '#ffffff',
  fontSize: '1rem',
  fontWeight: '600',
  textAlign: 'center',
  textDecoration: 'underline',
  display: 'flex',
  position: 'relative',
};

const tailwindClasses = cssToTailwind(cssProps, customConfig);
console.log(tailwindClasses);
// Output: "bg-red-custom text-white-custom text-custom-base font-custom-semibold text-custom-center underline-custom flex-custom relative-custom"

Validating Tailwind Classes

import { validateTailwindClasses } from '@metagptx/css-to-tailwind';

const classes = 'bg-blue-500 text-white invalid-class';
const validation = validateTailwindClasses(classes);

console.log(validation);
// Output: {
//   isValid: false,
//   invalidClasses: ['invalid-class']
// }

Color Conversion Utilities

import { oklchToHex, rgbToHex } from '@metagptx/css-to-tailwind';

// OKLCH to HEX
const hexColor = oklchToHex('oklch(0.637 0.237 25.331)');
console.log(hexColor); // "#ef4444"

// RGB to HEX
const hexFromRgb = rgbToHex('rgb(239, 68, 68)');
console.log(hexFromRgb); // "#ef4444"

API Reference

cssToTailwind(cssProps, config?)

Converts a CSS properties object to a Tailwind class name string.

Parameters:

• cssProps: CSS properties object, supports the following properties:
  • backgroundColor: Background color
  • color: Text color
  • margin, marginTop, marginRight, marginBottom, marginLeft, marginX, marginY: Margins
  • padding, paddingTop, paddingRight, paddingBottom, paddingLeft, paddingX, paddingY: Padding
  • borderRadius: Border radius
  • fontSize, fontWeight, fontFamily, textAlign, textDecoration, fontVariantNumeric: Font-related properties
  • width, height: Dimensions
  • display, flexDirection, justifyContent, alignItems, gap: Layout properties
  • position: Positioning
  • opacity: Opacity
  • className: Custom class names
• config?: Optional converter configuration object

Returns: string - Tailwind class name string

validateTailwindClasses(classes)

Validates whether Tailwind class names are valid.

Parameters:

• classes: string - Class name string to validate

Returns: ValidationResult - Validation result object

Utility Functions

• oklchToHex(oklchString): Converts OKLCH color to HEX
• rgbToHex(color): Converts RGB color to HEX
• parseColorsConfig(config): Parses color configuration
• getSpacingClass(type, value): Generates spacing class names

Configuration Types

ConverterConfig

interface ConverterConfig {
  colorMaps?: ColorMapsConfig;
  styleMaps?: StyleMapsConfig;
}

ColorMapsConfig

interface ColorMapsConfig {
  background: Record<string, string>; // Color value -> Background class name
  text: Record<string, string>;       // Color value -> Text class name
}

StyleMapsConfig

interface StyleMapsConfig {
  borderRadius: Record<string, string>;
  fontSize: Record<string, string>;
  fontWeight: Record<string, string>;
  fontFamily: Record<string, string>;
  textAlign: Record<string, string>;
  textDecoration: Record<string, string>;
  fontVariantNumeric: Record<string, string>;
  display: Record<string, string>;
  position: Record<string, string>;
}

Supported CSS Properties

Colors

• backgroundColor: Supports HEX, RGB, OKLCH formats
• color: Supports HEX, RGB, OKLCH formats

Spacing

• margin, marginTop, marginRight, marginBottom, marginLeft, marginX, marginY
• padding, paddingTop, paddingRight, paddingBottom, paddingLeft, paddingX, paddingY

Typography

• fontSize: Supports rem, px, and other units
• fontWeight: 100-900
• fontFamily: Supports system fonts
• textAlign: left, center, right, justify
• textDecoration: underline, overline, line-through, none
• fontVariantNumeric: tabular-nums, oldstyle-nums, lining-nums, proportional-nums, diagonal-fractions, stacked-fractions, ordinal, slashed-zero, normal

Layout

• display: block, flex, grid, hidden, etc.
• flexDirection: row, column, etc.
• justifyContent: flex-start, center, space-between, etc.
• alignItems: flex-start, center, stretch, etc.
• gap: Spacing values

Others

• borderRadius: Border radius values
• width, height: Dimension values
• position: Positioning methods
• opacity: Opacity values

Development

Install Dependencies

npm install

Build

npm run build

Test

npm test

Format Code

npm run format

Lint Code

npm run lint

License

MIT

Contributing

Issues and Pull Requests are welcome!

Changelog

1.0.0

• Initial release
• Support for CSS to Tailwind conversion
• Support for Tailwind to CSS conversion
• Complete color support
• TypeScript type definitions
• Support for custom configuration