SaaS Theme Tailwind Preset

Tailwind CSS preset for SaaS theme tokens with enhanced modern CSS features.

Features

• 🎨 Design token integration with SaaS Theme Core
• 🔧 Modern CSS support including Container Queries, CSS Layers, Logical Properties
• 📱 Responsive utilities with container-aware breakpoints
• 🌈 Advanced color system with automatic palette generation
• ♿ Accessibility-first utilities with WCAG compliance
• 🌍 RTL/LTR support with logical property utilities
• ⚡ TypeScript support with comprehensive type definitions

Installation

npm install saas-theme-tailwind-preset saas-theme-core tailwindcss

Quick Start

Add the preset to your tailwind.config.js:

const saasThemePreset = require("saas-theme-tailwind-preset");

module.exports = {
  presets: [
    saasThemePreset({
      theme: "./path/to/your/theme.json",
    }),
  ],
  content: ["./src/**/*.{html,js,ts,jsx,tsx}"],
};

Configuration

Basic Configuration

const saasThemePreset = require("saas-theme-tailwind-preset");

module.exports = {
  presets: [
    saasThemePreset({
      theme: "./theme.json",
      prefix: "saas-",
      modern: true,
    }),
  ],
};

Advanced Configuration

const saasThemePreset = require("saas-theme-tailwind-preset");

module.exports = {
  presets: [
    saasThemePreset({
      // Theme configuration
      theme: "./theme.json",
      fallbackTheme: "./fallback-theme.json",

      // Output options
      prefix: "saas-",
      important: false,

      // Modern CSS features
      modern: {
        containerQueries: true,
        cssLayers: true,
        logicalProperties: true,
        colorFunctions: true,
      },

      // Accessibility options
      accessibility: {
        wcagLevel: "AA",
        enforceContrast: true,
        generateA11yUtilities: true,
      },

      // Custom utilities
      utilities: {
        spacing: true,
        colors: true,
        typography: true,
        shadows: true,
        borders: true,
      },
    }),
  ],
};

Generated Utilities

Color Utilities

Based on your theme's color tokens:

<!-- Background colors -->
<div class="bg-primary">Primary background</div>
<div class="bg-secondary">Secondary background</div>
<div class="bg-surface-light">Light surface</div>

<!-- Text colors -->
<p class="text-primary">Primary text</p>
<p class="text-on-surface">Surface text</p>

<!-- Border colors -->
<div class="border-primary">Primary border</div>

Typography Utilities

<!-- Font families -->
<h1 class="font-heading">Heading font</h1>
<p class="font-body">Body font</p>

<!-- Font sizes -->
<h1 class="text-display-lg">Large display</h1>
<h2 class="text-heading-md">Medium heading</h2>
<p class="text-body-sm">Small body text</p>

<!-- Font weights -->
<p class="font-light">Light weight</p>
<p class="font-medium">Medium weight</p>
<p class="font-bold">Bold weight</p>

Spacing Utilities

<!-- Margins -->
<div class="m-xs">Extra small margin</div>
<div class="m-sm">Small margin</div>
<div class="m-md">Medium margin</div>

<!-- Padding -->
<div class="p-lg">Large padding</div>
<div class="px-xl">Extra large horizontal padding</div>

<!-- Gaps -->
<div class="gap-2xs">Extra extra small gap</div>

Modern CSS Utilities

Container Queries

<!-- Container query utilities -->
<div class="container-sidebar">
  <div class="@sm:block @md:flex @lg:grid">
    Responsive based on container size
  </div>
</div>

Logical Properties

<!-- Logical spacing -->
<div class="mis-4 mie-6">Inline start/end margins</div>
<div class="pbs-2 pbe-4">Block start/end padding</div>

<!-- Logical borders -->
<div class="border-is border-ie-2">Inline borders</div>

CSS Layers

<!-- Layer-aware utilities -->
<div class="layer-base:bg-primary">Base layer background</div>
<div class="layer-components:text-white">Component layer text</div>

Theme Integration

Theme File Structure

Your theme JSON should follow this structure:

{
  "metadata": {
    "name": "My SaaS Theme",
    "version": "1.0.0"
  },
  "tokens": {
    "colors": {
      "primary": "#007bff",
      "secondary": "#6c757d",
      "surface": {
        "light": "#ffffff",
        "dark": "#1a1a1a"
      }
    },
    "typography": {
      "fontFamily": {
        "heading": ["Inter", "system-ui"],
        "body": ["Inter", "system-ui"]
      },
      "fontSize": {
        "xs": "0.75rem",
        "sm": "0.875rem",
        "base": "1rem",
        "lg": "1.125rem"
      }
    },
    "spacing": {
      "2xs": "0.125rem",
      "xs": "0.25rem",
      "sm": "0.5rem",
      "md": "1rem"
    }
  }
}

Dynamic Theme Loading

// Load theme dynamically
const saasThemePreset = require("saas-theme-tailwind-preset");
const { ThemeBuilder } = require("saas-theme-core");

const builder = new ThemeBuilder();

module.exports = async () => {
  const theme = await builder.loadTheme("./theme.json");
  const resolvedTheme = await builder.resolveTheme(theme);

  return {
    presets: [
      saasThemePreset({
        theme: resolvedTheme,
        modern: true,
      }),
    ],
  };
};

Multi-Tenant Support

Tenant-Specific Themes

const saasThemePreset = require("saas-theme-tailwind-preset");

// Generate different builds for different tenants
const tenants = ["client-a", "client-b", "client-c"];

module.exports = tenants.map((tenant) => ({
  presets: [
    saasThemePreset({
      theme: `./themes/${tenant}.json`,
      prefix: `${tenant}-`,
    }),
  ],
  content: [`./src/${tenant}/**/*.{html,js,ts,jsx,tsx}`],
}));

Runtime Theme Switching

<!-- Use CSS custom properties for runtime switching -->
<div class="bg-[var(--color-primary)]">Dynamic primary background</div>

<div class="text-[var(--color-on-surface)]">Dynamic surface text</div>

Accessibility Features

WCAG Compliant Utilities

<!-- High contrast utilities -->
<div class="bg-primary text-on-primary-high-contrast">High contrast text</div>

<!-- Focus utilities -->
<button class="focus-visible:ring-focus focus-visible:ring-2">
  Accessible focus
</button>

<!-- Screen reader utilities -->
<span class="sr-only">Screen reader only text</span>

Color Contrast Validation

The preset automatically validates color combinations and generates warnings for insufficient contrast ratios.

Examples

Basic Usage

<!DOCTYPE html>
<html>
  <head>
    <link href="./dist/tailwind.css" rel="stylesheet" />
  </head>
  <body class="bg-surface-light text-on-surface">
    <header class="bg-primary text-on-primary p-md">
      <h1 class="text-heading-lg font-bold">My SaaS App</h1>
    </header>

    <main class="container mx-auto p-lg">
      <div class="bg-surface-elevated rounded-md p-md shadow-sm">
        <h2 class="text-heading-md font-medium mb-sm">Welcome</h2>
        <p class="text-body-base">This is styled with SaaS theme tokens.</p>
      </div>
    </main>
  </body>
</html>

React Component

import React from "react";

const Card = ({ title, children }) => {
  return (
    <div className="bg-surface-elevated rounded-lg p-md shadow-sm border border-outline">
      <h3 className="text-heading-sm font-semibold text-on-surface mb-xs">
        {title}
      </h3>
      <div className="text-body-sm text-on-surface-variant">{children}</div>
    </div>
  );
};

export default Card;

Modern CSS Features

<!-- Container queries -->
<div class="container-card">
  <div class="@sm:flex @md:grid @md:grid-cols-2 gap-md">
    <div>Content adapts to container size</div>
    <div>Not viewport size</div>
  </div>
</div>

<!-- Logical properties for RTL support -->
<div class="mis-md mie-lg pis-sm pie-md">
  Margin/padding that adapts to text direction
</div>

<!-- Advanced color functions -->
<div class="bg-primary/80 text-on-primary">
  Semi-transparent background with proper contrast
</div>

Build Integration

Webpack

// webpack.config.js
const path = require("path");

module.exports = {
  // ... other config
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [require("tailwindcss"), require("autoprefixer")],
              },
            },
          },
        ],
      },
    ],
  },
};

Vite

// vite.config.js
import { defineConfig } from "vite";

export default defineConfig({
  css: {
    postcss: {
      plugins: [require("tailwindcss"), require("autoprefixer")],
    },
  },
});

Troubleshooting

Common Issues

Theme not loading

# Verify theme file exists and is valid JSON
npx saas-theme-cli validate ./theme.json

Utilities not generating

// Ensure content paths include your files
module.exports = {
  content: [
    "./src/**/*.{html,js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",
  ],
};

Modern CSS features not working

// Enable modern features explicitly
saasThemePreset({
  theme: "./theme.json",
  modern: {
    containerQueries: true,
    cssLayers: true,
    logicalProperties: true,
  },
});

License

MIT © SaaS Theme Team