SaaS Theme Core

Core theming engine for multi-tenant SaaS applications with enhanced modern CSS features.

Features

• 🎨 Multi-tenant theming with JSON-based design tokens
• 🔧 Modern CSS support including Container Queries, CSS Layers, Logical Properties
• ♿ Accessibility validation with WCAG AA/AAA compliance
• 🌈 Advanced color functions with harmony generation and color space conversion
• 📱 Responsive design with container-aware grids and utilities
• 🌍 Internationalization with RTL/LTR support and writing mode detection
• ⚡ TypeScript support with comprehensive type definitions

Installation

npm install saas-theme-core

Quick Start

import { ThemeBuilder } from "saas-theme-core";

const builder = new ThemeBuilder();

// Load and build a theme
const theme = await builder.loadTheme("./my-theme.json");
const resolvedTheme = await builder.resolveTheme(theme);
const css = await builder.buildCSS(resolvedTheme, {
  outputDir: "./dist",
  format: "css",
  minify: true,
});

console.log(css);

Theme Structure

{
  "metadata": {
    "name": "My SaaS Theme",
    "version": "1.0.0",
    "tenant": "client-a"
  },
  "tokens": {
    "colors": {
      "primary": "#007bff",
      "secondary": "#6c757d",
      "background": {
        "light": "#ffffff",
        "dark": "#1a1a1a"
      }
    },
    "typography": {
      "fontFamily": {
        "sans": ["Inter", "system-ui", "sans-serif"]
      },
      "fontSize": {
        "sm": "0.875rem",
        "base": "1rem",
        "lg": "1.125rem"
      }
    },
    "spacing": {
      "xs": "0.25rem",
      "sm": "0.5rem",
      "md": "1rem",
      "lg": "1.5rem"
    }
  }
}

Modern CSS Features

Container Queries

import { EnhancedContainerQueryManager } from "saas-theme-core";

const containerManager = new EnhancedContainerQueryManager();
const css = containerManager.generateContainerQueries({
  sidebar: {
    containerName: "sidebar",
    queries: {
      "(min-width: 300px)": {
        ".widget": { display: "block" },
      },
    },
  },
});

CSS Layers

import { AdvancedCSSLayerManager } from "saas-theme-core";

const layerManager = new AdvancedCSSLayerManager();
layerManager.createLayer("reset", { priority: 1 });
layerManager.createLayer("base", { priority: 2 });
layerManager.createLayer("components", { priority: 3 });

Color Harmony

import { ColorHarmonyGenerator } from "saas-theme-core";

const colorGen = new ColorHarmonyGenerator();
const palette = colorGen.generateHarmony("#007bff", "complementary", {
  count: 5,
  wcagLevel: "AA",
});

API Reference

ThemeBuilder

Main class for building themes.

Methods

• loadTheme(filePath: string): Promise<Theme> - Load theme from file
• resolveTheme(theme: Theme): Promise<ResolvedTheme> - Resolve theme inheritance
• validateTheme(theme: Theme, config?: AccessibilityConfig): Promise<ValidationResult> - Validate theme
• buildCSS(theme: ResolvedTheme, options: BuildOptions): Promise<string> - Generate CSS

CSSGenerator

CSS generation utilities.

Methods

• generateVariables(theme: ResolvedTheme, prefix?: string) - Generate CSS variables
• buildModernCSS(theme: EnhancedTheme, options: ModernBuildOptions) - Build with modern features

ThemeValidator

Theme validation and accessibility checking.

Methods

• validateTheme(theme: Theme, config?: AccessibilityConfig): Promise<ValidationResult>
• calculateContrast(foreground: string, background: string): ContrastResult
• analyzeColor(color: string): ColorAnalysis

Configuration

Build Options

interface BuildOptions {
  outputDir: string;
  format: "css" | "scss" | "less";
  minify?: boolean;
  sourceMaps?: boolean;
  prefix?: string;
}

Modern Build Options

interface ModernBuildOptions extends BuildOptions {
  modern?: boolean;
  containerQueries?: boolean;
  cssLayers?: boolean;
  logicalProperties?: boolean;
  colorFunctions?: boolean;
  polyfills?: boolean;
}

Accessibility Config

interface AccessibilityConfig {
  wcagLevel?: "AA" | "AAA";
  contrastRatios?: {
    normal?: number;
    large?: number;
  };
  validation?: {
    enforceContrast?: boolean;
    strictMode?: boolean;
  };
}

Examples

See the examples directory for complete usage examples:

• Modern CSS Demo
• Enhanced Features Demo
• React Integration

License

MIT © SaaS Theme Team