utility-css-library

v1.0.0

Published

10 months ago

Modern utility CSS library with intelligent theming, automatic contrast calculation, and seamless dark/light mode support

Downloads

🎨 Intelligent Theming System

A modern, production-ready utility CSS library with intelligent theming, automatic contrast calculation, and seamless dark/light mode support.

✨ Features

🎯 Intelligent Theming

Automatic Contrast Calculation: Colors automatically generate optimal text colors for maximum readability
Semantic Color System: 7 carefully chosen semantic colors with intelligent foreground text
Smart Hover States: Automatic color darkening for interactive elements
Opacity Variants: Pre-generated opacity levels (10%, 20%, 30%, 50%, 70%) for each color

🌙 Dark/Light Mode Support

System Preference Detection: Automatically respects user's OS theme preference
Runtime Theme Switching: Toggle between modes with smooth transitions
Persistent Theme State: Remembers user's theme preference across sessions
CSS Custom Properties: All colors adapt automatically in both modes

🎨 Color Palette

Primary (#6C5CE7) - Purple for primary actions
Doom (#2B2B2B) - Dark gray for sophisticated elements
White (#FFFFFF) - Pure white with smart borders
Critical (#E62E5C) - Red for errors and warnings
Warning (#E6E35C) - Yellow for attention (uses black text automatically)
Success (#37B26C) - Green for positive actions
Interactive (#0984E3) - Blue for links and interactive elements

🏗️ TypeScript Architecture

Type-Safe Design Tokens: Complete TypeScript interfaces for all tokens
ThemeManager Class: Runtime theme management with event subscriptions
TokenManager Class: CSS custom property generation and management
Contrast Algorithms: Scientific luminance and contrast ratio calculations

🚀 Quick Start

Installation

npm install @organization/design-system

Basic Usage

<!DOCTYPE html>
<html lang="en">
<head>
    <link rel="stylesheet" href="node_modules/@organization/design-system/dist/main.css">
</head>
<body>
    <!-- Semantic color buttons with automatic contrast -->
    <button class="btn btn-primary">Primary Action</button>
    <button class="btn btn-warning">Warning (Black Text)</button>
    <button class="btn btn-success">Success Action</button>
    
    <!-- Theme toggle -->
    <button onclick="toggleMode()">Toggle Dark/Light</button>
    
    <script src="node_modules/@organization/design-system/dist/main.js"></script>
    <script>
        function toggleMode() {
            if (window.themeManager) {
                window.themeManager.toggleMode();
            }
        }
    </script>
</body>
</html>

TypeScript Usage

import { ThemeManager, TokenManager, DesignTokens } from '@organization/design-system';

// Initialize theme management
const themeManager = new ThemeManager();
const tokenManager = new TokenManager();

// Toggle theme programmatically
themeManager.toggleMode();

// Get current theme
const currentMode = themeManager.getCurrentMode(); // 'light' | 'dark'

// Subscribe to theme changes
themeManager.subscribe((mode) => {
    console.log(`Theme changed to: ${mode}`);
});

// Access design tokens
const primaryColor = DesignTokens.colors.primary.value; // #6C5CE7
const primaryForeground = DesignTokens.colors.primary.foreground; // #ffffff

🎨 Color System

Semantic Colors with Automatic Contrast

Each color automatically calculates the optimal foreground text color:

/* Yellow warning uses black text for readability */
.btn-warning {
    background-color: var(--color-warning, #E6E35C);
    color: var(--color-warning-foreground, #000000); /* Automatically black */
}

/* Dark colors use white text */
.btn-doom {
    background-color: var(--color-doom, #2B2B2B);
    color: var(--color-doom-foreground, #ffffff); /* Automatically white */
}

Opacity Variants

/* Available for all semantic colors */
.bg-primary-10 { background-color: var(--color-primary-10); } /* 10% opacity */
.bg-primary-20 { background-color: var(--color-primary-20); } /* 20% opacity */
.bg-primary-30 { background-color: var(--color-primary-30); } /* 30% opacity */
.bg-primary-50 { background-color: var(--color-primary-50); } /* 50% opacity */
.bg-primary-70 { background-color: var(--color-primary-70); } /* 70% opacity */

🌙 Dark Mode

Automatic Theme Detection

// Theme manager automatically detects system preference
const themeManager = new ThemeManager();
// Respects prefers-color-scheme: dark

Manual Theme Control

/* Light mode (default) */
:root {
    --color-background: #ffffff;
    --color-foreground: #09090b;
}

/* Dark mode */
:root.dark,
[data-mode="dark"] {
    --color-background: #09090b;
    --color-foreground: #fafafa;
}

🎯 Available Utility Classes

Color Classes

/* Background colors */
.bg-primary, .bg-doom, .bg-white, .bg-critical, .bg-warning, .bg-success, .bg-interactive

/* Text colors */
.text-primary, .text-doom, .text-white, .text-critical, .text-warning, .text-success, .text-interactive

/* Button styles */
.btn-primary, .btn-doom, .btn-white, .btn-critical, .btn-warning, .btn-success, .btn-interactive

Typography

/* Font sizes */
.text-xs, .text-sm, .text-base, .text-lg, .text-xl, .text-2xl, .text-3xl

/* Font weights */
.font-light, .font-normal, .font-medium, .font-semibold, .font-bold

Layout & Spacing

/* Spacing utilities */
.m-1, .m-2, .m-4, .p-1, .p-2, .p-4 /* etc. */

/* Flexbox */
.flex, .flex-col, .justify-center, .items-center /* etc. */

/* Grid */
.grid, .grid-cols-1, .grid-cols-2, .grid-cols-3 /* etc. */

🔧 Development

Build the Project

npm run build        # Production build
npm run build:dev    # Development build
npm run dev          # Development server
npm run watch        # Watch mode

Project Structure

src/
├── styles/           # SCSS utility classes
│   ├── abstracts/   # Variables and mixins
│   ├── base/        # Reset and base styles
│   └── utilities/   # Utility classes
├── tokens/          # Design token system
│   ├── design-tokens.ts    # Token definitions
│   ├── theme-manager.ts    # Theme management
│   └── token-manager.ts    # Token utilities
├── types/           # TypeScript type definitions
└── utils/           # Utility functions

📊 Performance

Bundle Size: ~240KB (CSS + JS)
Dependencies: Minimal, only build tools
Browser Support: Modern browsers (ES2020+)
Theme Switch: < 16ms transition time

🎨 Demo

Visit the live demo to see all features in action:

Interactive color demonstrations
Real-time theme switching
Typography system showcase
Responsive design examples

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by Tailwind CSS utility-first approach
Color contrast algorithms based on WCAG guidelines
Theme management patterns from modern design systems

Built with ❤️ for accessible, intelligent design systems.