🚀 SaaS Theme Toolkit

Multi-tenant theming with modern CSS features

A comprehensive toolkit for multi-tenant SaaS theming with JSON tokens, modern CSS features, and powerful CLI tools. This toolkit provides everything you need to manage client-specific styles at scale while maintaining developer velocity and ensuring accessibility compliance.

✨ Modern CSS Features

🎨 Container Queries - Component-based responsive design with automatic polyfills
🎭 CSS Layers (@layer) - Better cascade control and style organization
🌍 Logical Properties - Internationalization-ready spacing and positioning
🌈 Modern Color Functions - OKLCH, color-mix(), and advanced color manipulation
🔍 Feature Detection - Runtime browser capability detection with fallbacks
📦 Polyfill Management - Automatic loading and configuration of polyfills

🎯 Features

Core Features

🎨 JSON-based theme tokens with inheritance support
🔍 Schema validation with strict property and unit enforcement
♿ Accessibility validation with WCAG compliance checking
🛠️ Powerful CLI for building, validating, and linting themes
🎯 Runtime theme loading with zero dynamic injection
🌈 Tailwind CSS integration via dynamic preset generation
🚀 Performance optimized with prebuilt CSS files

🆕 Next-Generation Features

📱 Container Queries for component-based responsive design
🎭 CSS Layers for better style organization and cascade control
🌍 CSS Logical Properties for internationalization support
📚 Complete Storybook Addon with React components and TypeScript
⚡ CLI Watch Mode with hot reload and debounced rebuilding
🎨 Pre-built Templates (minimal, corporate, healthcare, fintech, glassmorphism, dark-mode)
Interactive Demo showcasing all modern capabilities

🚀 Quick Start

Installation

npm install @saas-theme/core @saas-theme/cli @saas-theme/storybook-addon

Create Your First Theme

Use a pre-built template:

npx saas-theme init --tenant my-client --template corporate

Or initialize with custom settings:

npx saas-theme init --tenant my-client --brand-color "#007bff"

Create a theme file (themes/my-client.json):

{
  "$schema": "../schemas/theme.schema.json",
  "metadata": {
    "name": "My Client Theme",
    "version": "2.0.0",
    "tenant": "my-client"
  },
  "tokens": {
    "colors": {
      "primary": {
        "50": "#eff6ff",
        "100": "#dbeafe",
        "500": "#007bff",
        "900": "#1e3a8a"
      },
      "semantic": {
        "success": "#10b981",
        "warning": "#f59e0b",
        "error": "#ef4444"
      }
    },
    "typography": {
      "fontFamily": {
        "sans": ["Inter", "system-ui", "sans-serif"],
        "mono": ["JetBrains Mono", "Consolas", "monospace"]
      },
      "fontSize": {
        "xs": "0.75rem",
        "sm": "0.875rem",
        "base": "1rem",
        "lg": "1.125rem",
        "xl": "1.25rem",
        "2xl": "1.5rem"
      }
    },
    "spacing": {
      "xs": "0.25rem",
      "sm": "0.5rem",
      "md": "1rem",
      "lg": "1.5rem",
      "xl": "2rem"
    },
    "modernFeatures": {
      "containerQueries": true,
      "cssLayers": true,
      "logicalProperties": true,
      "colorFunctions": true
    }
  }
}

Build with modern features:

npx saas-theme build --input ./themes --output ./dist/themes --modern

Start watch mode for development:

npx saas-theme watch --input ./themes --output ./dist/themes

🏗️ Architecture

Core Components

@saas-theme/core - Theme engine with modern CSS support
@saas-theme/cli - Enhanced CLI with watch mode and templates
@saas-theme/tailwind-preset - Tailwind CSS integration with modern features
@saas-theme/storybook-addon - Complete React-based Storybook integration

Modern Theme Structure

themes/
├── base.json              # Base theme with modern features
├── templates/             # Pre-built theme templates
│   ├── minimal.json
│   ├── corporate.json
│   ├── healthcare.json
│   ├── fintech.json
│   ├── glassmorphism.json
│   └── dark-mode.json
├── client-a.json          # Client A theme
└── client-b.json          # Client B theme with modern CSS

dist/themes/
├── base.css               # Generated CSS with modern features
├── client-a.css           # Client A theme CSS
└── client-b.css           # Modern CSS with Container Queries

examples/
├── modern-features-demo/  # Interactive demo showcase
├── vanilla-css/           # Basic implementation
├── tailwind-example/      # Tailwind integration
└── react-saas-ui/         # Complete React example

🛠️ CLI Commands

Modern Build System

# Build with modern CSS features
saas-theme build --modern --container-queries --css-layers --logical-properties --color-functions

# Build with polyfills for unsupported browsers
saas-theme build --modern --polyfills --feature-detection

# Watch mode with hot reload
saas-theme watch --input ./themes --output ./dist

Modern CSS Command

# Detect browser support for modern CSS features
saas-theme modern --detect

# Build with specific modern features
saas-theme modern -i themes -o dist --container-queries --css-layers

# Build with all modern features and polyfills
saas-theme modern -i themes -o dist --container-queries --css-layers --logical-properties --color-functions --polyfills

Standard Commands

# Validate themes
saas-theme validate themes/*.json --wcag AA --strict

# Lint codebase for hardcoded styles
saas-theme lint --dir ./src --extensions js,jsx,ts,tsx

# Compare theme versions
saas-theme diff themes/old.json themes/new.json

# Initialize new theme project
saas-theme init --dir . --template basic --tenant my-client

# Preview themes in development server
saas-theme preview --port 3000 --dir ./themes

🎨 Modern CSS Features

Container Queries

/* Generated CSS with Container Queries */
.card {
  container-type: inline-size;
  container-name: card;
}

@container card (min-width: 400px) {
  .card-content {
    padding: var(--spacing-lg);
    display: grid;
    grid-template-columns: 1fr 1fr;
  }
}

CSS Layers

/* Organized with CSS Layers */
@layer base, components, utilities;

@layer base {
  :root {
    --primary-500: #007bff;
    --spacing-md: 1rem;
  }
}

@layer components {
  .button {
    background: var(--primary-500);
    padding: var(--spacing-md);
  }
}

Logical Properties

/* Internationalization-ready */
.content {
  margin-inline-start: var(--spacing-md);
  padding-block: var(--spacing-sm);
  border-inline-end: 1px solid var(--border-color);
}

📚 Complete Storybook Integration

Setup

// .storybook/main.js
module.exports = {
  addons: ["@saas-theme/storybook-addon"],
  features: {
    modernInlineRender: true,
  },
};

Features

Real-time Theme Switching - Live preview with instant updates
Client Approval Workflow - Share themes and collect feedback
Theme Validation - Built-in accessibility and design checks
Export Functionality - Generate production-ready CSS
Modern CSS Preview - Container Queries and CSS Layers support

// stories/Button.stories.js
export default {
  title: "Components/Button",
  component: Button,
  parameters: {
    themes: {
      default: "corporate",
      list: [
        { name: "corporate", value: "corporate" },
        { name: "healthcare", value: "healthcare" },
        { name: "fintech", value: "fintech" },
      ],
    },
  },
};

⚡ Enhanced Runtime Usage

Modern Theme Loading

import { loadTheme, switchTheme, enableModernFeatures } from "@saas-theme/core";

// Enable modern CSS features
enableModernFeatures({
  containerQueries: true,
  cssLayers: true,
  logicalProperties: true,
});

// Load theme with modern features
await loadTheme("client-a", { modern: true });

// Switch themes dynamically
await switchTheme("client-b", { modern: true });

Container Queries Integration

import { ContainerQueryManager } from "@saas-theme/core";

const cqManager = new ContainerQueryManager();

// Register container queries
cqManager.register("card", {
  small: "(max-width: 300px)",
  medium: "(min-width: 301px) and (max-width: 600px)",
  large: "(min-width: 601px)",
});

// Apply responsive styling
cqManager.applyStyles("card", {
  small: { padding: "var(--spacing-sm)" },
  medium: { padding: "var(--spacing-md)" },
  large: { padding: "var(--spacing-lg)" },
});

🎯 Interactive Demo

Experience all features in the comprehensive demo:

# Open the modern features demo
open examples/modern-features-demo/index.html

The demo showcases:

Container Queries - Responsive components based on container size
CSS Layers - Organized styling with proper cascade control
Theme Switching - Real-time theme changes with smooth transitions
Modern CSS Features - All latest CSS capabilities in action

🌈 Advanced Color Science

Color Harmony Generation

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

const harmonyGen = new ColorHarmonyGenerator();

// Generate complementary colors
const complementary = harmonyGen.generateComplementary("#007bff");

// Generate triadic harmony
const triadic = harmonyGen.generateTriadic("#007bff");

// Generate analogous colors
const analogous = harmonyGen.generateAnalogous("#007bff", 5);

// Generate monochromatic palette
const monochromatic = harmonyGen.generateMonochromatic("#007bff", 9);

Accessibility-First Color Generation

import { AccessibilityColorGenerator } from "@saas-theme/core";

const accessGen = new AccessibilityColorGenerator();

// Generate WCAG AAA compliant palette
const palette = await accessGen.generateAccessiblePalette("#007bff", {
  wcagLevel: "AAA",
  colorBlindnessSupport: true,
  highContrast: true,
});

// Validate color combinations
const validation = await accessGen.validateColorCombination(
  "#007bff", // foreground
  "#ffffff", // background
  { wcagLevel: "AA", fontSize: "16px" }
);

🎨 Pre-built Templates

Available Templates

Minimal - Clean, simple design with essential elements
Corporate - Professional business theme with trust-building colors
Healthcare - Calming, accessible theme optimized for medical applications
Fintech - Secure, modern theme for financial services
Glassmorphism - Modern glass-effect design with backdrop filters
Dark Mode - Elegant dark theme with proper contrast ratios

Using Templates

# Initialize with template
saas-theme init --template healthcare --tenant medical-client

# Apply template to existing theme
saas-theme template apply --template glassmorphism --theme themes/client-a.json

# Customize template
saas-theme template customize --template corporate --primary-color "#e74c3c"

📊 Performance & Analytics

Build Performance

import { PerformanceAnalyzer } from "@saas-theme/core";

const analyzer = new PerformanceAnalyzer();

// Analyze theme performance
const metrics = await analyzer.analyzeTheme("themes/client-a.json");
console.log(metrics);
// {
//   cssSize: "45.2kb",
//   gzippedSize: "12.1kb",
//   variableCount: 156,
//   buildTime: "234ms",
//   optimizationSuggestions: [...]
// }

Runtime Performance

// Enable performance monitoring
import { enablePerformanceMonitoring } from "@saas-theme/core";

enablePerformanceMonitoring({
  trackThemeSwitching: true,
  trackCSSLoading: true,
  reportMetrics: true,
});

🔧 Configuration

Modern Features Config

{
  "modernFeatures": {
    "containerQueries": {
      "enabled": true,
      "polyfill": "auto"
    },
    "cssLayers": {
      "enabled": true,
      "layerOrder": ["base", "components", "utilities"]
    },
    "logicalProperties": {
      "enabled": true,
      "fallbacks": true
    },
    "colorFunctions": {
      "enabled": true,
      "oklch": true,
      "colorMix": true
    }
  },
  "performance": {
    "monitoring": true,
    "optimization": "aggressive",
    "caching": true
  }
}

Accessibility Config

{
  "accessibility": {
    "wcagLevel": "AA",
    "contrastRatios": {
      "normal": 4.5,
      "large": 3.0,
      "enhanced": 7.0
    },
    "colorBlindness": {
      "simulate": true,
      "types": ["protanopia", "deuteranopia", "tritanopia"]
    },
    "validation": {
      "enforceContrast": true,
      "checkFocusIndicators": true,
      "validateTouchTargets": true
    }
  }
}

📚 Examples & Demos

Modern Features Demo

Location: examples/modern-features-demo/
Features: Container Queries, CSS Layers, theme switching, interactive demo
Run: open examples/modern-features-demo/index.html

React SaaS UI

Location: examples/react-saas-ui/
Features: Complete React app with modern theming
Run: cd examples/react-saas-ui && npm start

Vanilla CSS Implementation

Location: examples/vanilla-css/
Features: Basic HTML/CSS usage with multiple themes
Run: open examples/vanilla-css/index.html

Tailwind Integration

Location: examples/tailwind-example/
Features: Tailwind CSS with dynamic theme presets
Run: cd examples/tailwind-example && npm run dev

🚀 API Reference

ModernCSSGenerator

class ModernCSSGenerator {
  generateContainerQueries(breakpoints: Breakpoints): string;
  generateCSSLayers(layers: LayerDefinition[]): string;
  generateLogicalProperties(properties: Properties): string;
  generateModernColors(palette: ColorPalette): string;
}

Enhanced ThemeBuilder

class ThemeBuilder {
  // Existing methods
  loadTheme(filePath: string): Promise<Theme>;
  buildCSS(theme: ResolvedTheme, options: BuildOptions): Promise<string>;

  // New modern methods
  buildModernCSS(
    theme: ResolvedTheme,
    options: ModernBuildOptions
  ): Promise<string>;
  generateContainerQueries(theme: ResolvedTheme): Promise<string>;
  optimizeForPerformance(css: string): Promise<OptimizedCSS>;
  validateModernFeatures(theme: Theme): Promise<ModernValidationResult>;
}

🎯 Migration Guide

From 1.x to 2.0

Update dependencies:

npm update @saas-theme/core @saas-theme/cli @saas-theme/storybook-addon

Enable modern features:

{
  "modernFeatures": {
    "containerQueries": true,
    "cssLayers": true,
    "logicalProperties": true
  }
}

Update build commands:

# Old
saas-theme build

# New
saas-theme build --modern

Migrate themes:

saas-theme migrate --from 1.x --to 2.0 --themes ./themes/

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run the test suite: npm test
Submit a pull request

Development Setup

git clone https://github.com/yourusername/saas-theme-toolkit.git
cd saas-theme-toolkit
npm install
npm run build
npm test

📄 License

MIT License - see LICENSE file for details.

🆘 Support & Community

🏆 Acknowledgments

Special thanks to:

The CSS Working Group for modern CSS features
The accessibility community for WCAG guidelines
All contributors and beta testers
The open-source community for inspiration and feedback

SaaS Theme Toolkit 2.0 - Powering the next generation of multi-tenant theming with modern CSS and developer-first tooling.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
examples		examples
packages		packages
schemas		schemas
.gitignore		.gitignore
README.md		README.md
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Uh oh!

vinerya/saas-theme

Folders and files

Latest commit

History

Repository files navigation

🚀 SaaS Theme Toolkit

✨ Modern CSS Features

🎯 Features

Core Features

🆕 Next-Generation Features

🚀 Quick Start

Installation

Create Your First Theme

🏗️ Architecture

Core Components

Modern Theme Structure

🛠️ CLI Commands

Modern Build System

Modern CSS Command

Standard Commands

🎨 Modern CSS Features

Container Queries

CSS Layers

Logical Properties

📚 Complete Storybook Integration

Setup

Features

⚡ Enhanced Runtime Usage

Modern Theme Loading

Container Queries Integration

🎯 Interactive Demo

🌈 Advanced Color Science

Color Harmony Generation

Accessibility-First Color Generation

🎨 Pre-built Templates

Available Templates

Using Templates

📊 Performance & Analytics

Build Performance

Runtime Performance

🔧 Configuration

Modern Features Config

Accessibility Config

📚 Examples & Demos

Modern Features Demo

React SaaS UI

Vanilla CSS Implementation

Tailwind Integration

🚀 API Reference

ModernCSSGenerator

Enhanced ThemeBuilder

🎯 Migration Guide

From 1.x to 2.0

🤝 Contributing

Development Setup

📄 License

🆘 Support & Community

🏆 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages