SGH Theme Library v2.0.2

Modern, dynamic theming system for Angular applications with runtime theme switching, dark mode support, and comprehensive SCSS utilities.

Table of Contents

• Features
• What's New in v2.0.0
• Installation
• Quick Start
• Usage
  • ThemeService API
  • SCSS Functions
  • Available Themes
• Migration Guide (v1.x → v2.0.0)
• Examples
• Browser Compatibility
• API Reference
• Contributing
• Version History

Features

✨ v2.0.0 brings major improvements:

• 🎨 5 Built-in Themes - Default (Teal), Blue, Light, Dark, Cyan
• 🌓 Material Design 3 Dark Mode - With proper surface elevation (9 levels)
• 🔄 Runtime Theme Switching - Change themes without page reload (250ms transitions)
• 💾 localStorage Persistence - Themes persist across sessions
• 🌙 System Dark Mode Detection - Auto-detects OS dark mode preference
• 🎯 CSS Custom Properties - 100+ CSS variables for dynamic theming
• 📦 ThemeService - Complete Angular service with RxJS Observable support
• 🎨 Bootstrap 5 Integration - Pre-configured Bootstrap theme
• 📐 Flex Framework - Complete flexbox/grid utility classes
• 🎨 Material Component Customization - Theme-aware Material Design expansion panels
• ♿ WCAG AAA Compliant - Meets accessibility standards
• 🔧 TypeScript Support - Full type definitions included

What's New in v2.0.2

Latest Update (v2.0.2)

• ✅ Material Design expansion panel customization for all themes
• ✅ Added CSS variables for expansion panel backgrounds, text colors, and indicators
• ✅ Theme-specific colors for expansion panels across all 6 theme variants
• ✅ Enhanced visual consistency for Material components

Previous Update (v2.0.1)

• ✅ Angular 21 support added
• ✅ Backward compatible with Angular 19 and 20

Major Changes in v2.0.0

⚠️ Version 2.0.0 was a major version with breaking changes. See Migration Guide below.

Architecture Changes:

• From: Static SCSS with Angular Material M2 palettes
• To: CSS Custom Properties (CSS variables) with runtime switching

New Files:

• _themes.scss (617 lines) - Complete theme system with CSS variables
• _theme-transitions.scss - Smooth 250ms theme transitions
• bootstrap-theme.scss - Bootstrap 5 integration
• flex-framework.scss - Flexbox/Grid utilities

Updated Files:

• SghThemeService - Now includes full API (7 methods, was empty)
• _color-palette.scss - Added theme-aware functions

New Features:

• 5 themes (was 1 static theme)
• localStorage persistence
• System dark mode detection
• Material Design 3 dark mode
• Runtime theme switching
• Complete ThemeService API

Installation

npm install [email protected]

Peer Dependencies:

• Angular 19.2+, Angular 20+ or Angular 21+
• RxJS 7+

Quick Start

1. Import Theme Styles

In your src/styles.scss:

// Required imports
@use "sgh-theme/assets/_themes" as *;           // CSS variables & themes
@use "sgh-theme/assets/_theme-transitions" as *; // Smooth transitions
@use "sgh-theme/assets/_color-palette" as *;   // Color functions

// Optional but recommended
@use "sgh-theme/assets/bootstrap-theme" as *;   // Bootstrap integration
@use "sgh-theme/assets/flex-framework" as *;    // Flex utilities

2. Initialize ThemeService

In your app.component.ts:

import { Component, OnInit } from '@angular/core';
import { SghThemeService } from 'sgh-theme';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent implements OnInit {

  constructor(private themeService: SghThemeService) {}

  ngOnInit() {
    // Service auto-initializes
    // Loads theme from localStorage or system preference
  }
}

3. Use Theme Colors in Components

In your component SCSS:

.my-component {
  // Dynamic colors that change with theme
  background: sgh-theme-color(500);           // Primary color
  color: sgh-theme-font-color(PRIMARY);       // Primary text
  border: 1px solid sgh-theme-color(200);     // Border

  &:hover {
    background: sgh-theme-color(600);         // Darker on hover
  }
}

.status-badge {
  background: sgh-theme-status-color(SUCCESS); // Green
  color: white;
}

That's it! Your app now supports dynamic theming. 🎉

Usage

ThemeService API

The SghThemeService provides complete control over theme management.

Import and Inject

import { SghThemeService } from 'sgh-theme';

constructor(private themeService: SghThemeService) {}

Switch Theme

// Switch to dark theme
this.themeService.setTheme('dark');

// Switch and save to localStorage
this.themeService.setTheme('blue', true);

// Switch without marking as manual selection
this.themeService.setTheme('light', true, false);

Get Current Theme

// Get current theme name
const currentTheme = this.themeService.getCurrentTheme();
console.log(currentTheme); // 'default', 'blue', 'light', 'dark', or 'cyan'

Subscribe to Theme Changes

this.themeService.getTheme().subscribe(themeClass => {
  console.log('Theme changed to:', themeClass);
  // themeClass = 'sgh-default-theme', 'sgh-blue-theme', etc.
});

Reset to System Preference

// Clear manual selection and use OS dark mode preference
this.themeService.resetToSystemPreference();

Check Manual Selection

const isManual = this.themeService.hasManualSelection();
console.log('User manually selected theme:', isManual);

SCSS Functions

Static Functions (Fixed Colors)

Use these when you need a specific color that doesn't change:

// Primary colors (50-900 scale)
$teal-500: sgh-color(500);        // #006068
$teal-light: sgh-color(100);      // #b3dee2
$gold-accent: sgh-color(A700);    // #F3C300

// Status colors
$success: sgh-status-color(SUCCESS);  // #10b981
$danger: sgh-status-color(DANGER);    // #ef4444
$warning: sgh-status-color(WARNING);  // #f59e0b
$info: sgh-status-color(INFO);        // #3b82f6
$refund: sgh-status-color(REFUND);    // #8b5cf6

// Font colors
$text-primary: sgh-font-color(PRIMARY);    // #1a1a1a
$text-secondary: sgh-font-color(SECONDARY); // #525252

// Utility colors
$white: sgh-utility-color(WHITE);
$light-gray: sgh-utility-color(LIGHT_GRAY_200);

Dynamic Functions (Theme-Aware) ⭐ Recommended

Use these for colors that should change with the theme:

.my-component {
  // Primary colors
  background: sgh-theme-color(500);      // var(--sgh-color-500)
  border: 1px solid sgh-theme-color(200); // var(--sgh-color-200)

  // Contrast colors (for backgrounds)
  background: sgh-theme-contrast-color(900); // White in light, dark in dark mode

  // Font colors
  color: sgh-theme-font-color(PRIMARY);   // Main text color
  color: sgh-theme-font-color(SECONDARY); // Secondary text
  color: sgh-theme-font-color(TERTIARY);  // Muted text

  // Status colors
  &.success { background: sgh-theme-status-color(SUCCESS); }
  &.danger  { background: sgh-theme-status-color(DANGER); }
  &.warning { background: sgh-theme-status-color(WARNING); }
  &.info    { background: sgh-theme-status-color(INFO); }

  // Chart colors (14 available)
  .chart-series-1 { fill: sgh-theme-chart-color(CHART_COLOR_1); }
  .chart-series-2 { fill: sgh-theme-chart-color(CHART_COLOR_2); }

  // Background colors
  background: sgh-theme-bg-color(PRIMARY);   // Main background
  background: sgh-theme-bg-color(SECONDARY); // Card backgrounds

  // Code blocks
  pre {
    background: sgh-theme-code-color(BACKGROUND);
    color: sgh-theme-code-color(TEXT);
  }

  // Shadows
  box-shadow: 0 4px 8px sgh-theme-shadow-color(SHADOW_12);
  box-shadow: 0 0 20px sgh-theme-shadow-color(PRIMARY_20); // Teal glow
}

Available Themes

| Theme | Value | Primary Color | Description | |-------|-------|---------------|-------------| | Default | 'default' | #006068 (Teal) | Professional healthcare look with gold accents | | Blue | 'blue' | #1976d2 | Material Design blue theme | | Light | 'light' | #006068 (Teal) | Bright, minimal appearance (same as default) | | Dark | 'dark' | #4db6ac (Vibrant Teal) | Material Design 3 dark mode with surface elevation | | Cyan | 'cyan' | #00a4ba | Ocean-inspired cyan theme |

Usage:

this.themeService.setTheme('default'); // Teal theme
this.themeService.setTheme('blue');    // Blue theme
this.themeService.setTheme('dark');    // Dark mode
this.themeService.setTheme('cyan');    // Cyan theme
this.themeService.setTheme('light');   // Light theme

Migration Guide (v1.x → v2.0.0)

Breaking Changes

⚠️ Version 2.0.0 introduces breaking changes:

1. Theme Architecture: Changed from static SCSS to CSS Custom Properties
2. Color Values: Updated color palette (especially status colors)
3. ThemeService: Now has full API (was empty in v1.x)
4. New Files: Must import new SCSS files
5. SCSS Functions: New theme-aware functions added

Step-by-Step Migration

1. Update Package

npm install [email protected]

2. Update SCSS Imports

Remove old imports:

// ❌ Remove this (v1.x)
@use "sgh-theme/assets/_theme" as *;

Add new imports:

// ✅ Add these (v2.0+)
@use "sgh-theme/assets/_themes" as *;           // Required
@use "sgh-theme/assets/_theme-transitions" as *; // Required
@use "sgh-theme/assets/_color-palette" as *;   // Required

// Optional but recommended
@use "sgh-theme/assets/bootstrap-theme" as *;
@use "sgh-theme/assets/flex-framework" as *;

3. Initialize ThemeService

// app.component.ts
import { SghThemeService } from 'sgh-theme';

export class AppComponent implements OnInit {
  constructor(private themeService: SghThemeService) {}

  ngOnInit() {
    // Service auto-initializes and loads saved theme
  }
}

4. Update Component Styles

Option A: Keep Static Colors (Quick)

Your existing static color functions still work:

// Still works in v2.0+
background: sgh-color(500);

Option B: Use Dynamic Colors (Recommended)

Update to theme-aware functions for runtime switching:

// v1.x - Static
background: sgh-color(500);

// v2.0+ - Dynamic (recommended)
background: sgh-theme-color(500);

5. Update Status Colors

If you used old status colors, update the hex values:

// v1.x colors
SUCCESS: #447b55  → v2.0+: #10b981  ✅ Emerald green
DANGER:  #b44a4a  → v2.0+: #ef4444  ✅ Bright red
WARNING: #d9ae5b  → v2.0+: #f59e0b  ✅ Amber
INFO:    #61b0bc  → v2.0+: #3b82f6  ✅ Blue
REFUND:  (new)    → v2.0+: #8b5cf6  ✅ Purple (NEW)

6. Test Theme Switching

// Test in your component
switchToDark() {
  this.themeService.setTheme('dark');
}

Examples

Theme Switcher Component

// theme-switcher.component.ts
import { Component } from '@angular/core';
import { SghThemeService } from 'sgh-theme';

@Component({
  selector: 'app-theme-switcher',
  template: `
    <div class="theme-switcher">
      <button (click)="setTheme('default')">Default</button>
      <button (click)="setTheme('blue')">Blue</button>
      <button (click)="setTheme('dark')">Dark</button>
      <button (click)="setTheme('cyan')">Cyan</button>
    </div>
  `
})
export class ThemeSwitcherComponent {
  constructor(private themeService: SghThemeService) {}

  setTheme(theme: string) {
    this.themeService.setTheme(theme, true, true);
  }
}

Dynamic Card Component

// card.component.scss
.card {
  // Background changes with theme
  background: sgh-theme-contrast-color(900); // White in light, dark in dark mode
  color: sgh-theme-font-color(PRIMARY);
  border: 1px solid sgh-theme-color(200);
  border-radius: 8px;
  padding: 20px;

  // Smooth transition when theme changes (automatic via _theme-transitions.scss)

  .card-header {
    color: sgh-theme-color(500);  // Primary color
    font-weight: 600;
  }

  .card-footer {
    border-top: 1px solid sgh-theme-color(100);
    color: sgh-theme-font-color(SECONDARY);
  }

  &:hover {
    box-shadow: 0 4px 12px sgh-theme-shadow-color(SHADOW_15);
  }
}

Status Badge Component

// status-badge.component.scss
.status-badge {
  padding: 4px 12px;
  border-radius: 16px;
  font-size: 12px;
  font-weight: 600;

  &.success {
    background: sgh-theme-status-color(SUCCESS);
    color: white;
  }

  &.danger {
    background: sgh-theme-status-color(DANGER);
    color: white;
  }

  &.warning {
    background: sgh-theme-status-color(WARNING);
    color: #000;
  }

  &.info {
    background: sgh-theme-status-color(INFO);
    color: white;
  }
}

Using Flex Framework

<!-- Responsive layout using flex utilities -->
<div class="flex-container flex-row flex-justify-between flex-align-center">
  <div class="flex-grow-1">Content</div>
  <div>Actions</div>
</div>

<!-- Grid layout -->
<div class="grid-container grid-cols-3 grid-gap-md">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

<!-- Responsive flexbox -->
<div class="flex-container flex-xs-column flex-md-row">
  <div class="flex-xs-basis-100 flex-md-basis-50">Left</div>
  <div class="flex-xs-basis-100 flex-md-basis-50">Right</div>
</div>

Material Design Expansion Panel Customization

All themes include automatic customization for Material Design expansion panels. The following CSS variables are set per theme:

// Automatically applied when using mat-expansion-panel
--mat-expansion-container-background-color  // Panel background
--mat-expansion-header-text-color           // Header text
--mat-expansion-header-description-color    // Description text (matches theme primary)
--mat-expansion-header-indicator-color      // Expand/collapse indicator
--mat-expansion-container-text-color        // Panel content text

Theme-Specific Colors:

| Theme | Background | Primary Accent | Text Color | |-------|------------|---------------|------------| | Default | #f9fafb (subtle gray) | #006068 (teal) | #1a1a1a / #2e2e2e | | Blue | #f5f9fd (light blue tint) | #1976d2 (blue) | #1a1a1a / #2e2e2e | | Light | #f9fafb (subtle gray) | #006068 (teal) | #1a1a1a / #2e2e2e | | Dark | #444242 (elevated surface) | #4db6ac (vibrant teal) | #acacac | | Cyan | #f0fdfd (light cyan tint) | #00a4ba (cyan) | #1a1a1a / #2e2e2e |

Usage:

<mat-accordion>
  <mat-expansion-panel>
    <mat-expansion-panel-header>
      <mat-panel-title>Panel Title</mat-panel-title>
      <mat-panel-description>Description text</mat-panel-description>
    </mat-expansion-panel-header>
    <p>Panel content automatically styled with theme colors</p>
  </mat-expansion-panel>
</mat-accordion>

No additional configuration needed - expansion panels automatically adapt to the active theme!

Browser Compatibility

| Browser | Version | CSS Variables Support | Status | |---------|---------|----------------------|--------| | Chrome | 90+ | ✅ Full support | ✅ Supported | | Firefox | 88+ | ✅ Full support | ✅ Supported | | Safari | 14+ | ✅ Full support | ✅ Supported | | Edge | 90+ | ✅ Full support | ✅ Supported | | IE 11 | Any | ❌ No support | ❌ Not supported |

Note: CSS Custom Properties (CSS variables) are required for v2.0+. IE 11 is not supported.

API Reference

ThemeService Methods

setTheme(theme: string, saveToStorage?: boolean, isManual?: boolean): void

Switch to a different theme.

Parameters:

• theme - Theme name: 'default', 'blue', 'light', 'dark', or 'cyan'
• saveToStorage - Save to localStorage (default: true)
• isManual - Mark as manual user selection (default: true)

Example:

this.themeService.setTheme('dark', true, true);

getTheme(): Observable<string>

Subscribe to theme changes.

Returns: Observable of theme class name

Example:

this.themeService.getTheme().subscribe(themeClass => {
  console.log('Current theme:', themeClass); // 'sgh-dark-theme'
});

getCurrentTheme(): string

Get current theme name without prefix.

Returns: Theme name string

Example:

const theme = this.themeService.getCurrentTheme();
console.log(theme); // 'dark'

resetToSystemPreference(): void

Reset to OS dark mode preference. Clears manual selection and localStorage.

Example:

this.themeService.resetToSystemPreference();

hasManualSelection(): boolean

Check if user has manually selected a theme.

Returns: true if manually selected, false otherwise

Example:

if (!this.themeService.hasManualSelection()) {
  // Auto-switch with system preference
}

Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Building the Library

# Clone the repository
git clone https://github.com/synergenhealth/sgh-theme.git

# Install dependencies
npm install

# Build the library
npm run build sgh-theme

# Build output: dist/sgh-theme

Version History

| Version | Angular | Date | Description | |---------|---------|------|-------------| | 2.0.2 | 19-21 | 2026-07-27 | • Material Design expansion panel CSS variables for all themes• Enhanced visual consistency for Material components | | 2.0.1 | 19-21 | 2026-07-23 | • Angular 21 support | | 2.0.0 | 19-20 | 2026-07-06 | ⚠️ Major update with breaking changes• CSS Custom Properties system• Complete ThemeService API• 5 themes with runtime switching• Material Design 3 dark mode• localStorage persistence• System dark mode detection• Bootstrap 5 integration• Flex framework utilities | | 1.3.5 | 19-20 | 2024 | @use instead of @import, common variables, Angular 19-20 support | | 1.2.8 | 19 | 2024 | Added sgh-btn-outline | | 1.2.3 | 19 | 2024 | Angular 19 support | | 1.2.2 | 18 | 2023 | Angular 18 support | | 1.2.1 | 17 | 2023 | Angular 17 support | | 1.2.0 | 16 | 2023 | Angular 16 support | | 1.0.3 | 15 | 2023 | Initial release |

License

MIT License - See LICENSE file for details

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Documentation

Acknowledgments

• Built with Angular
• Follows Material Design 3 guidelines
• Inspired by modern theming best practices

Made with ❤️ by Synergen Health