Atomix Theme System

Complete guide to customizing Atomix with CSS-based and JavaScript-based themes. Create custom themes programmatically, switch themes at runtime, and maintain full type safety.

Complete Theme System Guide

Version 2.1 - Last Updated: 2025-01-27. Atomix provides a powerful theme system that supports both CSS-based and JavaScript-based themes. Create custom themes programmatically, switch themes at runtime, and maintain full type safety throughout your application.

Quick Start

Installation

BASH

npm install @shohojdhara/atomix

1 line31 characters

Basic Setup (React)

TSX

import { ThemeProvider, useTheme, createTheme } from '@shohojdhara/atomix/theme';

// Create a theme
const myTheme = createTheme({
  name: 'My Theme',
  palette: {
    primary: { main: '#7AFFD7' },
    secondary: { main: '#FF5733' },
  },
});

function App() {
  return (
    <ThemeProvider defaultTheme={myTheme}>
      <YourApp />
    </ThemeProvider>
  );
}

// Use theme in components
function MyComponent() {
  const { theme, setTheme, availableThemes } = useTheme();
  
  return (
    <div>
      <p>Current theme: {theme}</p>
      <button onClick={() => setTheme('dark-theme')}>
        Switch Theme
      </button>
    </div>
  );
}

32 lines641 characters

Basic Setup (Vanilla JavaScript)

TYPESCRIPT

import { ThemeManager, createTheme } from '@shohojdhara/atomix/theme';

const themeManager = new ThemeManager({
  themes: {
    'light': { name: 'Light', type: 'css' },
    'dark': { name: 'Dark', type: 'css' },
  },
  defaultTheme: 'light',
});

// Switch theme
await themeManager.setTheme('dark');

12 lines299 characters

For External Developers

This section is for developers using Atomix in their own projects.

✅ What You Should Use

1. JavaScript Themes (Recommended)

The easiest way to create themes - no build step required:

TSX

import { createTheme, ThemeProvider } from '@shohojdhara/atomix/theme';

const myTheme = createTheme({
  name: 'My Brand Theme',
  palette: {
    primary: { main: '#7AFFD7' },
    secondary: { main: '#FF5733' },
  },
  typography: {
    fontFamily: 'Inter, sans-serif',
  },
});

function App() {
  return (
    <ThemeProvider defaultTheme={myTheme}>
      <YourApp />
    </ThemeProvider>
  );
}

20 lines396 characters

Why this is great:

No build step required
Works at runtime
TypeScript autocomplete
Generates all CSS variables automatically

2. Quick Theme Helper

Fastest way to get started:

TSX

import { quickTheme, ThemeProvider } from '@shohojdhara/atomix/theme';

// Create a theme from just brand colors
const myTheme = quickTheme('My Brand', '#7AFFD7', '#FF5733');

function App() {
  return (
    <ThemeProvider defaultTheme={myTheme}>
      <YourApp />
    </ThemeProvider>
  );
}

12 lines292 characters

3. CSS Theme Loading

Use your existing CSS files:

TSX

import { ThemeProvider } from '@shohojdhara/atomix/theme';
import './my-custom-theme.css';

const themes = {
  'my-theme': {
    type: 'css',
    name: 'My Theme',
    class: 'my-theme-class',
  },
};

function App() {
  return (
    <ThemeProvider themes={themes} defaultTheme="my-theme">
      <YourApp />
    </ThemeProvider>
  );
}

18 lines335 characters

4. Customize Design Tokens via Config (New!)

You can now customize design tokens using atomix.config.ts:

TYPESCRIPT

// atomix.config.ts (in your project root)
import { defineConfig } from '@shohojdhara/atomix/config';

export default defineConfig({
  prefix: 'atomix', // Optional: customize CSS variable prefix
  
  theme: {
    extend: {
      // Customize colors - generates full color scales automatically
      colors: {
        primary: { main: '#7AFFD7' }, // Generates primary-1 through primary-10
        secondary: { main: '#FF5733' },
        error: { main: '#ef4444' },
      },
      
      // Customize typography
      typography: {
        fontFamilies: {
          sans: ['Inter', 'sans-serif'],
        },
        fontSizes: {
          '2xl': '1.5rem',
        },
      },
      
      // Customize spacing
      spacing: {
        '18': '4.5rem',
        '72': '18rem',
      },
      
      // Customize border radius
      borderRadius: {
        'xl': '0.75rem',
      },
    },
  },
});

38 lines894 characters

After creating your config, run:

npm run sync:config

This generates CSS custom properties in src/styles/03-generic/_generated-root.css that you can import in your project.

❌ What You Should NOT Use

SCSS Theme Structure - Only needed if contributing themes to Atomix.
Build Scripts (sync:tokens, generate:tokens) - These are for library development only.

Common Use Cases

Brand Colors

TSX

const brandTheme = createTheme({
  palette: {
    primary: { main: '#YOUR_BRAND_COLOR' },
  },
});

5 lines98 characters

Dark Mode

TSX

const darkTheme = createTheme({
  palette: {
    background: { default: '#111827' },
    text: { primary: '#f9fafb' },
  },
});

6 lines127 characters

Multiple Themes with Switching

TSX

import { createTheme, ThemeProvider, useTheme } from '@shohojdhara/atomix/theme';

const lightTheme = createTheme({
  name: 'Light',
  palette: {
    primary: { main: '#3b82f6' },
    background: { default: '#ffffff' },
  },
});

const darkTheme = createTheme({
  name: 'Dark',
  palette: {
    primary: { main: '#60a5fa' },
    background: { default: '#111827' },
  },
});

function ThemeSwitcher() {
  const { setTheme } = useTheme();
  
  return (
    <div>
      <button onClick={() => setTheme(lightTheme)}>Light</button>
      <button onClick={() => setTheme(darkTheme)}>Dark</button>
    </div>
  );
}

function App() {
  return (
    <ThemeProvider defaultTheme={lightTheme}>
      <ThemeSwitcher />
      <YourApp />
    </ThemeProvider>
  );
}

37 lines753 characters

Quick Start Checklist

Install: npm install @shohojdhara/atomix
Import: import { createTheme, ThemeProvider } from '@shohojdhara/atomix/theme'
Create theme: const theme = createTheme({ palette: {...} })
Wrap app: <ThemeProvider defaultTheme={theme}>
Use CSS variables: var(--atomix-primary)

That's it! No config files needed, no build steps, no complexity.

For Library Developers

This section is for developers contributing themes to the Atomix library.

Configuration File

Create atomix.config.ts in the project root:

TYPESCRIPT

import { defineConfig } from '@shohojdhara/atomix/config';

export default defineConfig({
  // CSS variable prefix
  prefix: 'atomix',
  
  theme: {
    // Extend default tokens
    extend: {
      colors: {
        primary: { main: '#7AFFD7' },
        secondary: { main: '#FF5733' },
      },
      spacing: {
        '18': '4.5rem',
      },
      typography: {
        fontFamilies: {
          sans: ['Inter', 'sans-serif'],
        },
      },
    },
    
    // Register themes
    themes: {
      'my-theme': {
        type: 'css',
        name: 'My Theme',
        description: 'A custom theme',
        version: '1.0.0',
        status: 'stable',
      },
    },
  },
  
  // Build configuration (internal)
  build: {
    output: {
      directory: 'themes',
      formats: {
        expanded: '.css',
        compressed: '.min.css',
      },
    },
  },
});

46 lines868 characters

Build Process

BASH

# Sync configuration
npm run sync:config

# Generate tokens
npm run sync:tokens

# Validate configuration
npm run validate:config

# Build themes
npm run build:themes

11 lines166 characters

SCSS Theme Structure

For library developers creating SCSS themes:

BASH

src/themes/my-theme/
├── index.scss
├── 01-settings/
│   └── _settings.colors.scss
├── 06-components/
│   └── _components.button.scss
└── 99-utilities/

7 lines151 characters

Create index.scss:

SCSS

@use '01-settings/index' as *;
@use '../../styles/02-tools/index' as tools;
@use '../../styles/03-generic/index' as generic;
@use '../../styles/04-elements/index' as elements;
@use '../../styles/05-objects/index' as objects;
@use '../../styles/06-components/index' as components;
@use '../../styles/99-utilities/index' as utilities;

7 lines332 characters

Override settings:

SCSS

// 01-settings/_settings.colors.scss
@use '../../../styles/01-settings/settings.colors' with (
  $primary-6: #0ea5e9,
  $gray-1: #f9fafb,
);

5 lines140 characters

Theme Types

CSS Themes

Themes loaded from CSS files, applied via CSS classes:

TYPESCRIPT

// In atomix.config.ts (library developers)
export default defineConfig({
  theme: {
    themes: {
      'my-theme': {
        type: 'css',
        name: 'My Theme',
        class: 'my-theme-class',
        cssPath: '/themes/my-theme.css',
      },
    },
  },
});

13 lines264 characters

JavaScript Themes

Themes created programmatically using createTheme():

TYPESCRIPT

import { createTheme } from '@shohojdhara/atomix/theme';

const theme = createTheme({
  name: 'Custom Theme',
  palette: {
    primary: { main: '#7AFFD7' },
    secondary: { main: '#FF5733' },
  },
  typography: {
    fontFamily: 'Inter, sans-serif',
    fontSize: 16,
  },
});

13 lines277 characters

Note: JavaScript themes automatically generate all CSS variables including:

Color scales (1-10 steps)
RGB variants for transparency
Text emphasis variants
Background and border subtle variants
Gradient tokens
Hover state colors

API Reference

ThemeProvider

React context provider for theme state:

TSX

<ThemeProvider
  defaultTheme="my-theme"
  themes={themes}
  basePath="/themes"
  enablePersistence={true}
>
  {children}
</ThemeProvider>

8 lines138 characters

useTheme Hook

React hook for accessing theme context:

TYPESCRIPT

const {
  theme,              // Current theme name
  activeTheme,        // Active theme object (for JS themes)
  setTheme,           // Function to change theme
  availableThemes,    // List of available themes
  isLoading,          // Loading state
  error,              // Error state
  isThemeLoaded,      // Check if theme is loaded
  preloadTheme,       // Preload a theme
} = useTheme()

10 lines394 characters

ThemeManager

High-level API for theme management (vanilla JS):

TYPESCRIPT

import { ThemeManager } from '@shohojdhara/atomix/theme';

const themeManager = new ThemeManager({
  themes: {
    'light': { name: 'Light', type: 'css' },
    'dark': { name: 'Dark', type: 'css' },
  },
  defaultTheme: 'light',
  basePath: '/themes',
  enablePersistence: true,
});

// Set theme
await themeManager.setTheme('dark');

// Get current theme
const currentTheme = themeManager.getTheme();

// Get available themes
const themes = themeManager.getAvailableThemes();

20 lines476 characters

createTheme

Create a JavaScript theme:

TYPESCRIPT

import { createTheme } from '@shohojdhara/atomix/theme';

const theme = createTheme({
  name: 'My Theme',
  palette: {
    primary: {
      main: '#7AFFD7',
      light: '#9AFFE7',
      dark: '#5ADFC7',
    },
    secondary: {
      main: '#FF5733',
    },
    background: {
      default: '#FAFAFA',
      paper: '#FFFFFF',
    },
    text: {
      primary: '#111827',
      secondary: '#6B7280',
    },
  },
  typography: {
    fontFamily: 'Inter, sans-serif',
    fontSize: 16,
  },
  components: {
    Button: {
      styleOverrides: {
        root: {
          borderRadius: '8px',
        },
      },
    },
  },
});

36 lines623 characters

Theme Composition

Combine and extend themes:

TYPESCRIPT

import { extendTheme, mergeTheme, composeThemes } from '@shohojdhara/atomix/theme';

// Extend an existing theme
const extendedTheme = extendTheme(baseTheme, {
  palette: {
    primary: { main: '#FF0000' },
  },
});

// Merge multiple theme options
const merged = mergeTheme(
  { palette: { primary: { main: '#000' } } },
  { typography: { fontSize: 18 } }
);

// Compose multiple themes
const composed = composeThemes(theme1, theme2, theme3);

17 lines443 characters

Theme Utilities

Helper functions for theme management:

TYPESCRIPT

import { 
  quickTheme,
  createDarkVariant,
  validateTheme,
  generateCSSVariables,
} from '@shohojdhara/atomix/theme';

// Quick theme from colors
const theme = quickTheme('My Theme', '#7AFFD7', '#FF5733');

// Create dark variant
const darkTheme = createDarkVariant(lightTheme);

// Validate theme
const result = validateTheme(theme);
if (!result.valid) {
  console.error('Errors:', result.errors);
}

// Generate CSS variables
const css = generateCSSVariables(theme, {
  selector: ':root',
  prefix: 'atomix',
});

24 lines518 characters

ThemeErrorBoundary

React error boundary for theme errors:

TSX

import { ThemeErrorBoundary } from '@shohojdhara/atomix/theme';

<ThemeErrorBoundary
  fallback={(error, errorInfo) => <CustomErrorUI />}
  onError={(error, errorInfo) => {
    // Send to error tracking
  }}
>
  <ThemeProvider>
    <App />
  </ThemeProvider>
</ThemeErrorBoundary>

12 lines280 characters

RTL Support

Enable RTL for right-to-left languages:

TYPESCRIPT

import { RTLManager } from '@shohojdhara/atomix/theme';

const rtlManager = new RTLManager({
  enabled: true,
  autoDetect: true,
  locale: 'ar-SA',
});

// Set direction
rtlManager.setDirection('rtl');

// Get RTL-aware values
const margin = rtlManager.getValue('margin-left', 'margin-right');

13 lines294 characters

Or with ThemeProvider:

TSX

<ThemeProvider
  rtl={{
    enabled: true,
    autoDetect: true,
  }}
>
  <App />
</ThemeProvider>

8 lines98 characters

Configuration

atomix.config.ts

The central configuration file for customizing design tokens and registering themes:

TYPESCRIPT

import { defineConfig } from '@shohojdhara/atomix/config';

export default defineConfig({
  // CSS variable prefix (default: 'atomix')
  prefix: 'atomix',
  
  theme: {
    // Extend default tokens
    extend: {
      // Colors - generates full color scales (1-10) automatically
      colors: {
        primary: { main: '#3b82f6' }, // Generates:
        // --atomix-primary-1 through --atomix-primary-10
        // --atomix-primary (main color)
        // --atomix-primary-rgb (for transparency)
        // --atomix-primary-text-emphasis
        // --atomix-primary-bg-subtle
        // --atomix-primary-border-subtle
        // --atomix-primary-hover
        secondary: { main: '#10b981' },
        error: { main: '#ef4444' },
      },
      
      // Typography customization
      typography: {
        fontFamilies: {
          sans: ['Inter', 'sans-serif'],
        },
        fontSizes: {
          '2xl': '1.5rem',
        },
        fontWeights: {
          bold: 700,
        },
      },
      
      // Spacing customization
      spacing: {
        '18': '4.5rem',
        '72': '18rem',
      },
      
      // Border radius customization
      borderRadius: {
        'xl': '0.75rem',
      },
    },
    
    // Register themes
    themes: {
      'my-theme': {
        type: 'css',
        name: 'My Theme',
      },
    },
  },
});

57 lines1349 characters

Configuration Options

prefix: CSS variable prefix (default: 'atomix')
theme.extend: Extend default design tokens
theme.tokens: Override entire token system (advanced)
theme.themes: Register CSS or JS themes
build: Build configuration (internal)
runtime: Runtime configuration (internal)

Auto-Generated Files

From atomix.config.ts, these files are automatically generated:

src/themes/themes.config.js - Build-time theme configuration
- Theme metadata (name, description, version, status, etc.)
- Build settings (output directory, formats, SASS options)
- Runtime configuration (basePath, storage, persistence)
- Integration settings (CSS variables, class names)
- Theme dependencies
src/styles/03-generic/_generated-root.css - CSS custom properties from config
- Generated from theme.extend colors, typography, spacing, etc.
- Includes full color scales (1-10 steps) from a single color
- Includes semantic tokens (text-emphasis, bg-subtle, border-subtle, hover)
- Includes RGB variants for transparency support
- Typography, spacing, and border-radius tokens

Note: _settings.config.scss is NOT auto-generated - it's standalone for SCSS builds.

Token Generation Details

When you customize colors in theme.extend.colors, the sync script automatically generates:

For each color (e.g., primary: { main: '#3b82f6' }):

Full color scale: --atomix-primary-1 through --atomix-primary-10
Main color: --atomix-primary (maps to primary-6)
RGB variant: --atomix-primary-rgb (for rgba() usage)
Semantic tokens:
- --atomix-primary-text-emphasis (for text)
- --atomix-primary-bg-subtle (for backgrounds)
- --atomix-primary-border-subtle (for borders)
- --atomix-primary-hover (for hover states)

Example Output:

CSS

/* _generated-root.css */
:root {
  --atomix-primary-1: #eff6ff;
  --atomix-primary-2: #dbeafe;
  --atomix-primary-3: #bfdbfe;
  --atomix-primary-4: #93c5fd;
  --atomix-primary-5: #60a5fa;
  --atomix-primary-6: #3b82f6; /* main */
  --atomix-primary-7: #2563eb;
  --atomix-primary-8: #1d4ed8;
  --atomix-primary-9: #1e40af;
  --atomix-primary-10: #1e3a8a;
  --atomix-primary: #3b82f6;
  --atomix-primary-rgb: 59, 130, 246;
  --atomix-primary-text-emphasis: #1e40af;
  --atomix-primary-bg-subtle: rgba(59, 130, 246, 0.1);
  --atomix-primary-border-subtle: rgba(59, 130, 246, 0.2);
  --atomix-primary-hover: #2563eb;
}

19 lines616 characters

Sync Scripts

BASH

# Sync theme configuration (generates themes.config.js and _generated-root.css)
npm run sync:config

# Generate tokens (alternative token generation)
npm run sync:tokens

# Validate configuration sync
npm run validate:config

# Both sync and validate (runs automatically before build)
npm run prebuild

11 lines301 characters

What sync:config does:

Reads atomix.config.ts
Generates themes.config.js with theme metadata and configuration
Generates _generated-root.css with CSS custom properties from theme.extend
Updates package.json exports (if themes are registered)

CSS Variables & Tokens

Using CSS Variables

The theme system generates CSS variables you can use in your styles:

CSS

.my-component {
  background-color: var(--atomix-primary);
  color: var(--atomix-primary-contrast-text);
  padding: var(--atomix-spacing-4);
  border-radius: var(--atomix-border-radius);
  box-shadow: var(--atomix-box-shadow-md);
}

7 lines231 characters

Available CSS Variables

Color Tokens

Base Colors: --atomix-primary, --atomix-secondary, --atomix-error, etc.
RGB Variants: --atomix-primary-rgb (for transparency)
Color Scales: --atomix-primary-1 through --atomix-primary-10
Text Emphasis: --atomix-primary-text-emphasis
Background Subtle: --atomix-primary-bg-subtle
Border Subtle: --atomix-primary-border-subtle
Hover States: --atomix-primary-hover
Gradients: --atomix-primary-gradient

Typography Tokens

Font Families: --atomix-font-sans-serif, --atomix-font-monospace
Font Sizes: --atomix-font-size-xs through --atomix-font-size-2xl
Font Weights: --atomix-font-weight-light through --atomix-font-weight-bold
Line Heights: --atomix-line-height-base, --atomix-line-height-sm, --atomix-line-height-lg

Spacing Tokens

Spacing Scale: --atomix-spacing-0 through --atomix-spacing-200
Common Values: --atomix-spacing-1 (4px), --atomix-spacing-2 (8px), --atomix-spacing-4 (16px)

Border Radius Tokens

--atomix-border-radius, --atomix-border-radius-sm, --atomix-border-radius-md, --atomix-border-radius-lg, --atomix-border-radius-xl

Shadow Tokens

--atomix-box-shadow, --atomix-box-shadow-xs, --atomix-box-shadow-sm, --atomix-box-shadow-lg, --atomix-box-shadow-xl

Border Tokens

Border Radius: --atomix-border-radius, --atomix-border-radius-sm, --atomix-border-radius-lg, --atomix-border-radius-xl, --atomix-border-radius-xxl, --atomix-border-radius-pill
Border Colors: --atomix-border-color, --atomix-border-color-translucent

Other Tokens

Transitions: --atomix-transition-fast, --atomix-transition-base, --atomix-transition-slow
Z-Index: --atomix-z-dropdown, --atomix-z-modal, --atomix-z-tooltip, etc.
Breakpoints: --atomix-breakpoint-xs, --atomix-breakpoint-sm, etc.
Focus Ring: --atomix-focus-ring-width, --atomix-focus-ring-offset, --atomix-focus-ring-opacity

Importing Theme CSS Files

Individual theme CSS files can be imported separately:

TYPESCRIPT

// Import a specific theme CSS file
import '@shohojdhara/atomix/themes/light';
// or minified version
import '@shohojdhara/atomix/themes/light.min';

4 lines148 characters

Available Theme Imports:

@shohojdhara/atomix/themes/{theme-name} - Expanded CSS
@shohojdhara/atomix/themes/{theme-name}.min - Minified CSS

Note: Theme CSS files are only available if themes are registered in atomix.config.ts and built with npm run build:themes.

Using Generated Tokens

If you've customized tokens via atomix.config.ts, import the generated CSS:

TYPESCRIPT

// Import generated tokens
import '@shohojdhara/atomix/styles/03-generic/_generated-root.css';

2 lines94 characters

Or if using SCSS:

SCSS

@import '@shohojdhara/atomix/scss/generic';

1 line43 characters

The generated tokens will be available as CSS custom properties in your application.

Advanced Topics

Theme Composition

Combine and extend themes to create variations:

TYPESCRIPT

import { mergeTheme, extendTheme } from '@shohojdhara/atomix/theme';

// Merge two themes
const merged = mergeTheme(baseTheme, overrideTheme);

// Extend theme
const extended = extendTheme(baseTheme, {
  palette: {
    primary: { main: '#FF0000' },
  },
});

11 lines257 characters

Component Overrides

Customize component styles per theme:

TYPESCRIPT

const theme = createTheme({
  components: {
    Button: {
      styleOverrides: {
        root: {
          borderRadius: '8px',
          padding: '12px 24px',
        },
      },
      defaultProps: {
        variant: 'primary',
        size: 'lg',
      },
    },
  },
});

16 lines275 characters

Note: ComponentOverrideManager as a separate class is planned for a future release. For now, use createTheme() with components property.

RTL Support

Enable RTL for right-to-left languages:

TYPESCRIPT

import { RTLManager } from '@shohojdhara/atomix/theme';

const rtlManager = new RTLManager({
  enabled: true,
  autoDetect: true,
  locale: 'ar-SA',
});

// Set direction
rtlManager.setDirection('rtl');

10 lines202 characters

CSS Variable Generation

Generate CSS variables programmatically:

TYPESCRIPT

import { generateCSSVariables } from '@shohojdhara/atomix/theme';

const css = generateCSSVariables(myTheme, {
  selector: ':root',
  prefix: 'atomix',
});

// Inject into DOM
document.head.appendChild(
  Object.assign(document.createElement('style'), {
    textContent: css,
  })
);

13 lines283 characters

Theme Validation

Validate themes during development:

TYPESCRIPT

import { validateTheme } from '@shohojdhara/atomix/theme';

const result = validateTheme(myTheme);

if (!result.valid) {
  console.error('Theme validation errors:', result.errors);
}

7 lines182 characters

Development Tools

Preview and inspect themes:

TSX

import { ThemePreview, ThemeInspector } from '@shohojdhara/atomix/theme';

// Preview theme
<ThemePreview
  theme={myTheme}
  showPalette={true}
  showTypography={true}
/>

// Inspect theme
<ThemeInspector
  theme={myTheme}
  showValidation={true}
  showCSSVariables={true}
/>

15 lines276 characters

Troubleshooting

Theme Not Loading

Problem: Theme fails to load

Solutions:

Check theme exists in registry:
TYPESCRIPT
1const themes = themeManager.getAvailableThemes(); 2console.log(themes);
2 lines70 characters
Check for errors:
TYPESCRIPT
1themeManager.on('themeError', (error, themeName) => { 2 console.error('Theme error:', error, themeName); 3});
3 lines108 characters
Verify CSS path exists

CSS Variables Not Working

Problem: CSS variables not found

Solutions:

Ensure theme is loaded (SCSS or JS)
Check prefix matches config
Verify token name follows conventions
Check browser DevTools for actual CSS variable names
If using config-generated tokens, ensure _generated-root.css is imported

Token Generation Issues

Problem: Generated tokens don't match config

Solutions:

Run npm run sync:config to regenerate
Check atomix.config.ts syntax is correct
Verify color values are valid hex colors
Check src/styles/03-generic/_generated-root.css exists and has content
Ensure _generated-root.css is imported in your styles

Problem: Only 1 CSS variable generated instead of full scale

Solutions:

Ensure you're using theme.extend.colors (not theme.tokens.colors)
Check color format: { main: '#3b82f6' } (not just '#3b82f6')
Run npm run sync:config again
Check console output for errors during sync

Theme CSS Import Issues

Problem: Cannot import theme CSS files

Solutions:

Ensure themes are built: npm run build:themes
Check dist/themes/ directory exists
Verify package.json exports include theme paths
Use correct import path: @shohojdhara/atomix/themes/light
Check theme is registered in atomix.config.ts

TypeScript Errors

Problem: TypeScript errors with theme types

Solutions:

Import types correctly:
TYPESCRIPT
1import type { Theme, ThemeMetadata } from '@shohojdhara/atomix/theme';
1 line70 characters
Use type guards:
TYPESCRIPT
1if (isJSTheme(theme)) { 2 // theme is now typed as Theme 3}
3 lines58 characters

Configuration Not Syncing

Problem: Generated files don't match atomix.config.ts

Solution:

BASH

npm run sync:config
npm run sync:tokens
npm run validate:config

3 lines63 characters

Prefix Not Updating

Problem: Prefix changes in config but not in generated files

Solution:

Check atomix.config.ts has prefix field
Run npm run sync:config && npm run sync:tokens
Verify with npm run validate:config

Browser Environment Limitations

Important: The atomix.config.ts file cannot be dynamically loaded in browser environments.

In browser/client-side applications, themes must be explicitly provided to the ThemeManager or ThemeProvider.

TYPESCRIPT

// In browser environments, provide themes directly
import { ThemeProvider } from '@shohojdhara/atomix/theme';

const themes = {
  'my-theme': {
    type: 'css',
    name: 'My Theme',
    class: 'my-theme',
  },
};

function App() {
  return (
    <ThemeProvider 
      themes={themes}
      defaultTheme="my-theme"
      basePath="/themes"
    >
      <YourApp />
    </ThemeProvider>
  );
}

22 lines392 characters

Examples

Complete React Example

TSX

import React from 'react';
import {
  ThemeProvider,
  ThemeErrorBoundary,
  useTheme,
  createTheme,
} from '@shohojdhara/atomix/theme';

const lightTheme = createTheme({
  name: 'Light',
  palette: {
    primary: { main: '#3b82f6' },
    background: { default: '#ffffff' },
  },
});

const darkTheme = createTheme({
  name: 'Dark',
  palette: {
    primary: { main: '#60a5fa' },
    background: { default: '#111827' },
  },
});

function ThemeSelector() {
  const { theme, setTheme } = useTheme();

  return (
    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
      <option value={lightTheme}>Light</option>
      <option value={darkTheme}>Dark</option>
    </select>
  );
}

function App() {
  return (
    <ThemeErrorBoundary
      onError={(error, errorInfo) => {
        console.error('Theme error:', error);
      }}
    >
      <ThemeProvider
        defaultTheme={lightTheme}
        enablePersistence={true}
      >
        <ThemeSelector />
        <YourApp />
      </ThemeProvider>
    </ThemeErrorBoundary>
  );
}

52 lines1047 characters

Next.js Integration

TSX

// app/layout.tsx
import { ThemeProvider } from '@shohojdhara/atomix/theme';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ThemeProvider>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

14 lines266 characters

Best Practices

1. Always Use CSS Variables

✅ Good:

SCSS

.component {
  color: var(--atomix-primary);
  padding: var(--atomix-spacing-4);
}

4 lines82 characters

❌ Bad: Hardcoded values like color: #3b82f6; or padding: 16px;

2. Use ThemeProvider for React Apps

Always use ThemeProvider for React applications instead of direct ThemeManager usage.

3. Error Boundaries

Always wrap ThemeProvider with error boundary:

TSX

<ThemeErrorBoundary>
  <ThemeProvider>
    <App />
  </ThemeProvider>
</ThemeErrorBoundary>

5 lines91 characters

4. Type Safety

Use TypeScript types:

TYPESCRIPT

import type { Theme, ThemeMetadata } from '@shohojdhara/atomix/theme';

1 line70 characters

5. Performance

Enable caching (default: enabled)
Use lazy loading for themes
Preload critical themes
Use minified CSS in production

6. Accessibility

Validate themes for contrast ratios
Test with screen readers
Ensure keyboard navigation works
Check color blindness compatibility

Interactive Theme Creation

Use the Theme Studio to create and preview themes interactively. Visualize your theme in real-time and export it for use in your application.

Open Theme Studio

Atomix Theme System

Complete guide to customizing Atomix with CSS-based and JavaScript-based themes. Create custom themes programmatically, switch themes at runtime, and maintain full type safety.

Complete Theme System Guide

Quick Start

Installation

BASH

npm install @shohojdhara/atomix

1 line31 characters

Basic Setup (React)

TSX

import { ThemeProvider, useTheme, createTheme } from '@shohojdhara/atomix/theme';

// Create a theme
const myTheme = createTheme({
  name: 'My Theme',
  palette: {
    primary: { main: '#7AFFD7' },
    secondary: { main: '#FF5733' },
  },
});

function App() {
  return (
    <ThemeProvider defaultTheme={myTheme}>
      <YourApp />
    </ThemeProvider>
  );
}

// Use theme in components
function MyComponent() {
  const { theme, setTheme, availableThemes } = useTheme();
  
  return (
    <div>
      <p>Current theme: {theme}</p>
      <button onClick={() => setTheme('dark-theme')}>
        Switch Theme
      </button>
    </div>
  );
}

32 lines641 characters

Basic Setup (Vanilla JavaScript)

TYPESCRIPT

import { ThemeManager, createTheme } from '@shohojdhara/atomix/theme';

const themeManager = new ThemeManager({
  themes: {
    'light': { name: 'Light', type: 'css' },
    'dark': { name: 'Dark', type: 'css' },
  },
  defaultTheme: 'light',
});

// Switch theme
await themeManager.setTheme('dark');

12 lines299 characters

For External Developers

This section is for developers using Atomix in their own projects.

✅ What You Should Use

1. JavaScript Themes (Recommended)

The easiest way to create themes - no build step required:

TSX

import { createTheme, ThemeProvider } from '@shohojdhara/atomix/theme';

const myTheme = createTheme({
  name: 'My Brand Theme',
  palette: {
    primary: { main: '#7AFFD7' },
    secondary: { main: '#FF5733' },
  },
  typography: {
    fontFamily: 'Inter, sans-serif',
  },
});

function App() {
  return (
    <ThemeProvider defaultTheme={myTheme}>
      <YourApp />
    </ThemeProvider>
  );
}

20 lines396 characters

Why this is great:

No build step required
Works at runtime
TypeScript autocomplete
Generates all CSS variables automatically

2. Quick Theme Helper

Fastest way to get started:

TSX

import { quickTheme, ThemeProvider } from '@shohojdhara/atomix/theme';

// Create a theme from just brand colors
const myTheme = quickTheme('My Brand', '#7AFFD7', '#FF5733');

function App() {
  return (
    <ThemeProvider defaultTheme={myTheme}>
      <YourApp />
    </ThemeProvider>
  );
}

12 lines292 characters

3. CSS Theme Loading

Use your existing CSS files:

TSX

import { ThemeProvider } from '@shohojdhara/atomix/theme';
import './my-custom-theme.css';

const themes = {
  'my-theme': {
    type: 'css',
    name: 'My Theme',
    class: 'my-theme-class',
  },
};

function App() {
  return (
    <ThemeProvider themes={themes} defaultTheme="my-theme">
      <YourApp />
    </ThemeProvider>
  );
}

18 lines335 characters

4. Customize Design Tokens via Config (New!)

You can now customize design tokens using atomix.config.ts:

TYPESCRIPT

// atomix.config.ts (in your project root)
import { defineConfig } from '@shohojdhara/atomix/config';

export default defineConfig({
  prefix: 'atomix', // Optional: customize CSS variable prefix
  
  theme: {
    extend: {
      // Customize colors - generates full color scales automatically
      colors: {
        primary: { main: '#7AFFD7' }, // Generates primary-1 through primary-10
        secondary: { main: '#FF5733' },
        error: { main: '#ef4444' },
      },
      
      // Customize typography
      typography: {
        fontFamilies: {
          sans: ['Inter', 'sans-serif'],
        },
        fontSizes: {
          '2xl': '1.5rem',
        },
      },
      
      // Customize spacing
      spacing: {
        '18': '4.5rem',
        '72': '18rem',
      },
      
      // Customize border radius
      borderRadius: {
        'xl': '0.75rem',
      },
    },
  },
});

38 lines894 characters

After creating your config, run:

npm run sync:config

This generates CSS custom properties in src/styles/03-generic/_generated-root.css that you can import in your project.

❌ What You Should NOT Use

SCSS Theme Structure - Only needed if contributing themes to Atomix.
Build Scripts (sync:tokens, generate:tokens) - These are for library development only.

Common Use Cases

Brand Colors

TSX

const brandTheme = createTheme({
  palette: {
    primary: { main: '#YOUR_BRAND_COLOR' },
  },
});

5 lines98 characters

Dark Mode

TSX

const darkTheme = createTheme({
  palette: {
    background: { default: '#111827' },
    text: { primary: '#f9fafb' },
  },
});

6 lines127 characters

Multiple Themes with Switching

TSX

import { createTheme, ThemeProvider, useTheme } from '@shohojdhara/atomix/theme';

const lightTheme = createTheme({
  name: 'Light',
  palette: {
    primary: { main: '#3b82f6' },
    background: { default: '#ffffff' },
  },
});

const darkTheme = createTheme({
  name: 'Dark',
  palette: {
    primary: { main: '#60a5fa' },
    background: { default: '#111827' },
  },
});

function ThemeSwitcher() {
  const { setTheme } = useTheme();
  
  return (
    <div>
      <button onClick={() => setTheme(lightTheme)}>Light</button>
      <button onClick={() => setTheme(darkTheme)}>Dark</button>
    </div>
  );
}

function App() {
  return (
    <ThemeProvider defaultTheme={lightTheme}>
      <ThemeSwitcher />
      <YourApp />
    </ThemeProvider>
  );
}

37 lines753 characters

Quick Start Checklist

Install: npm install @shohojdhara/atomix
Import: import { createTheme, ThemeProvider } from '@shohojdhara/atomix/theme'
Create theme: const theme = createTheme({ palette: {...} })
Wrap app: <ThemeProvider defaultTheme={theme}>
Use CSS variables: var(--atomix-primary)

That's it! No config files needed, no build steps, no complexity.

For Library Developers

This section is for developers contributing themes to the Atomix library.

Configuration File

Create atomix.config.ts in the project root:

TYPESCRIPT

import { defineConfig } from '@shohojdhara/atomix/config';

export default defineConfig({
  // CSS variable prefix
  prefix: 'atomix',
  
  theme: {
    // Extend default tokens
    extend: {
      colors: {
        primary: { main: '#7AFFD7' },
        secondary: { main: '#FF5733' },
      },
      spacing: {
        '18': '4.5rem',
      },
      typography: {
        fontFamilies: {
          sans: ['Inter', 'sans-serif'],
        },
      },
    },
    
    // Register themes
    themes: {
      'my-theme': {
        type: 'css',
        name: 'My Theme',
        description: 'A custom theme',
        version: '1.0.0',
        status: 'stable',
      },
    },
  },
  
  // Build configuration (internal)
  build: {
    output: {
      directory: 'themes',
      formats: {
        expanded: '.css',
        compressed: '.min.css',
      },
    },
  },
});

46 lines868 characters

Build Process

BASH

# Sync configuration
npm run sync:config

# Generate tokens
npm run sync:tokens

# Validate configuration
npm run validate:config

# Build themes
npm run build:themes

11 lines166 characters

SCSS Theme Structure

For library developers creating SCSS themes:

BASH

src/themes/my-theme/
├── index.scss
├── 01-settings/
│   └── _settings.colors.scss
├── 06-components/
│   └── _components.button.scss
└── 99-utilities/

7 lines151 characters

Create index.scss:

SCSS

@use '01-settings/index' as *;
@use '../../styles/02-tools/index' as tools;
@use '../../styles/03-generic/index' as generic;
@use '../../styles/04-elements/index' as elements;
@use '../../styles/05-objects/index' as objects;
@use '../../styles/06-components/index' as components;
@use '../../styles/99-utilities/index' as utilities;

7 lines332 characters

Override settings:

SCSS

// 01-settings/_settings.colors.scss
@use '../../../styles/01-settings/settings.colors' with (
  $primary-6: #0ea5e9,
  $gray-1: #f9fafb,
);

5 lines140 characters

Theme Types

CSS Themes

Themes loaded from CSS files, applied via CSS classes:

TYPESCRIPT

// In atomix.config.ts (library developers)
export default defineConfig({
  theme: {
    themes: {
      'my-theme': {
        type: 'css',
        name: 'My Theme',
        class: 'my-theme-class',
        cssPath: '/themes/my-theme.css',
      },
    },
  },
});

13 lines264 characters

JavaScript Themes

Themes created programmatically using createTheme():

TYPESCRIPT

import { createTheme } from '@shohojdhara/atomix/theme';

const theme = createTheme({
  name: 'Custom Theme',
  palette: {
    primary: { main: '#7AFFD7' },
    secondary: { main: '#FF5733' },
  },
  typography: {
    fontFamily: 'Inter, sans-serif',
    fontSize: 16,
  },
});

13 lines277 characters

Note: JavaScript themes automatically generate all CSS variables including:

Color scales (1-10 steps)
RGB variants for transparency
Text emphasis variants
Background and border subtle variants
Gradient tokens
Hover state colors

API Reference

ThemeProvider

React context provider for theme state:

TSX

<ThemeProvider
  defaultTheme="my-theme"
  themes={themes}
  basePath="/themes"
  enablePersistence={true}
>
  {children}
</ThemeProvider>

8 lines138 characters

useTheme Hook

React hook for accessing theme context:

TYPESCRIPT

const {
  theme,              // Current theme name
  activeTheme,        // Active theme object (for JS themes)
  setTheme,           // Function to change theme
  availableThemes,    // List of available themes
  isLoading,          // Loading state
  error,              // Error state
  isThemeLoaded,      // Check if theme is loaded
  preloadTheme,       // Preload a theme
} = useTheme()

10 lines394 characters

ThemeManager

High-level API for theme management (vanilla JS):

TYPESCRIPT

import { ThemeManager } from '@shohojdhara/atomix/theme';

const themeManager = new ThemeManager({
  themes: {
    'light': { name: 'Light', type: 'css' },
    'dark': { name: 'Dark', type: 'css' },
  },
  defaultTheme: 'light',
  basePath: '/themes',
  enablePersistence: true,
});

// Set theme
await themeManager.setTheme('dark');

// Get current theme
const currentTheme = themeManager.getTheme();

// Get available themes
const themes = themeManager.getAvailableThemes();

20 lines476 characters

createTheme

Create a JavaScript theme:

TYPESCRIPT

import { createTheme } from '@shohojdhara/atomix/theme';

const theme = createTheme({
  name: 'My Theme',
  palette: {
    primary: {
      main: '#7AFFD7',
      light: '#9AFFE7',
      dark: '#5ADFC7',
    },
    secondary: {
      main: '#FF5733',
    },
    background: {
      default: '#FAFAFA',
      paper: '#FFFFFF',
    },
    text: {
      primary: '#111827',
      secondary: '#6B7280',
    },
  },
  typography: {
    fontFamily: 'Inter, sans-serif',
    fontSize: 16,
  },
  components: {
    Button: {
      styleOverrides: {
        root: {
          borderRadius: '8px',
        },
      },
    },
  },
});

36 lines623 characters

Theme Composition

Combine and extend themes:

TYPESCRIPT

import { extendTheme, mergeTheme, composeThemes } from '@shohojdhara/atomix/theme';

// Extend an existing theme
const extendedTheme = extendTheme(baseTheme, {
  palette: {
    primary: { main: '#FF0000' },
  },
});

// Merge multiple theme options
const merged = mergeTheme(
  { palette: { primary: { main: '#000' } } },
  { typography: { fontSize: 18 } }
);

// Compose multiple themes
const composed = composeThemes(theme1, theme2, theme3);

17 lines443 characters

Theme Utilities

Helper functions for theme management:

TYPESCRIPT

import { 
  quickTheme,
  createDarkVariant,
  validateTheme,
  generateCSSVariables,
} from '@shohojdhara/atomix/theme';

// Quick theme from colors
const theme = quickTheme('My Theme', '#7AFFD7', '#FF5733');

// Create dark variant
const darkTheme = createDarkVariant(lightTheme);

// Validate theme
const result = validateTheme(theme);
if (!result.valid) {
  console.error('Errors:', result.errors);
}

// Generate CSS variables
const css = generateCSSVariables(theme, {
  selector: ':root',
  prefix: 'atomix',
});

24 lines518 characters

ThemeErrorBoundary

React error boundary for theme errors:

TSX

import { ThemeErrorBoundary } from '@shohojdhara/atomix/theme';

<ThemeErrorBoundary
  fallback={(error, errorInfo) => <CustomErrorUI />}
  onError={(error, errorInfo) => {
    // Send to error tracking
  }}
>
  <ThemeProvider>
    <App />
  </ThemeProvider>
</ThemeErrorBoundary>

12 lines280 characters

RTL Support

Enable RTL for right-to-left languages:

TYPESCRIPT

import { RTLManager } from '@shohojdhara/atomix/theme';

const rtlManager = new RTLManager({
  enabled: true,
  autoDetect: true,
  locale: 'ar-SA',
});

// Set direction
rtlManager.setDirection('rtl');

// Get RTL-aware values
const margin = rtlManager.getValue('margin-left', 'margin-right');

13 lines294 characters

Or with ThemeProvider:

TSX

<ThemeProvider
  rtl={{
    enabled: true,
    autoDetect: true,
  }}
>
  <App />
</ThemeProvider>

8 lines98 characters

Configuration

atomix.config.ts

The central configuration file for customizing design tokens and registering themes:

TYPESCRIPT

import { defineConfig } from '@shohojdhara/atomix/config';

export default defineConfig({
  // CSS variable prefix (default: 'atomix')
  prefix: 'atomix',
  
  theme: {
    // Extend default tokens
    extend: {
      // Colors - generates full color scales (1-10) automatically
      colors: {
        primary: { main: '#3b82f6' }, // Generates:
        // --atomix-primary-1 through --atomix-primary-10
        // --atomix-primary (main color)
        // --atomix-primary-rgb (for transparency)
        // --atomix-primary-text-emphasis
        // --atomix-primary-bg-subtle
        // --atomix-primary-border-subtle
        // --atomix-primary-hover
        secondary: { main: '#10b981' },
        error: { main: '#ef4444' },
      },
      
      // Typography customization
      typography: {
        fontFamilies: {
          sans: ['Inter', 'sans-serif'],
        },
        fontSizes: {
          '2xl': '1.5rem',
        },
        fontWeights: {
          bold: 700,
        },
      },
      
      // Spacing customization
      spacing: {
        '18': '4.5rem',
        '72': '18rem',
      },
      
      // Border radius customization
      borderRadius: {
        'xl': '0.75rem',
      },
    },
    
    // Register themes
    themes: {
      'my-theme': {
        type: 'css',
        name: 'My Theme',
      },
    },
  },
});

57 lines1349 characters

Configuration Options

prefix: CSS variable prefix (default: 'atomix')
theme.extend: Extend default design tokens
theme.tokens: Override entire token system (advanced)
theme.themes: Register CSS or JS themes
build: Build configuration (internal)
runtime: Runtime configuration (internal)

Auto-Generated Files

From atomix.config.ts, these files are automatically generated:

src/themes/themes.config.js - Build-time theme configuration
- Theme metadata (name, description, version, status, etc.)
- Build settings (output directory, formats, SASS options)
- Runtime configuration (basePath, storage, persistence)
- Integration settings (CSS variables, class names)
- Theme dependencies
src/styles/03-generic/_generated-root.css - CSS custom properties from config
- Generated from theme.extend colors, typography, spacing, etc.
- Includes full color scales (1-10 steps) from a single color
- Includes semantic tokens (text-emphasis, bg-subtle, border-subtle, hover)
- Includes RGB variants for transparency support
- Typography, spacing, and border-radius tokens

Note: _settings.config.scss is NOT auto-generated - it's standalone for SCSS builds.

Token Generation Details

When you customize colors in theme.extend.colors, the sync script automatically generates:

For each color (e.g., primary: { main: '#3b82f6' }):

Full color scale: --atomix-primary-1 through --atomix-primary-10
Main color: --atomix-primary (maps to primary-6)
RGB variant: --atomix-primary-rgb (for rgba() usage)
Semantic tokens:
- --atomix-primary-text-emphasis (for text)
- --atomix-primary-bg-subtle (for backgrounds)
- --atomix-primary-border-subtle (for borders)
- --atomix-primary-hover (for hover states)

Example Output:

CSS

/* _generated-root.css */
:root {
  --atomix-primary-1: #eff6ff;
  --atomix-primary-2: #dbeafe;
  --atomix-primary-3: #bfdbfe;
  --atomix-primary-4: #93c5fd;
  --atomix-primary-5: #60a5fa;
  --atomix-primary-6: #3b82f6; /* main */
  --atomix-primary-7: #2563eb;
  --atomix-primary-8: #1d4ed8;
  --atomix-primary-9: #1e40af;
  --atomix-primary-10: #1e3a8a;
  --atomix-primary: #3b82f6;
  --atomix-primary-rgb: 59, 130, 246;
  --atomix-primary-text-emphasis: #1e40af;
  --atomix-primary-bg-subtle: rgba(59, 130, 246, 0.1);
  --atomix-primary-border-subtle: rgba(59, 130, 246, 0.2);
  --atomix-primary-hover: #2563eb;
}

19 lines616 characters

Sync Scripts

BASH

# Sync theme configuration (generates themes.config.js and _generated-root.css)
npm run sync:config

# Generate tokens (alternative token generation)
npm run sync:tokens

# Validate configuration sync
npm run validate:config

# Both sync and validate (runs automatically before build)
npm run prebuild

11 lines301 characters

What sync:config does:

Reads atomix.config.ts
Generates themes.config.js with theme metadata and configuration
Generates _generated-root.css with CSS custom properties from theme.extend
Updates package.json exports (if themes are registered)

CSS Variables & Tokens

Using CSS Variables

The theme system generates CSS variables you can use in your styles:

CSS

.my-component {
  background-color: var(--atomix-primary);
  color: var(--atomix-primary-contrast-text);
  padding: var(--atomix-spacing-4);
  border-radius: var(--atomix-border-radius);
  box-shadow: var(--atomix-box-shadow-md);
}

7 lines231 characters

Available CSS Variables

Color Tokens

Base Colors: --atomix-primary, --atomix-secondary, --atomix-error, etc.
RGB Variants: --atomix-primary-rgb (for transparency)
Color Scales: --atomix-primary-1 through --atomix-primary-10
Text Emphasis: --atomix-primary-text-emphasis
Background Subtle: --atomix-primary-bg-subtle
Border Subtle: --atomix-primary-border-subtle
Hover States: --atomix-primary-hover
Gradients: --atomix-primary-gradient

Typography Tokens

Font Families: --atomix-font-sans-serif, --atomix-font-monospace
Font Sizes: --atomix-font-size-xs through --atomix-font-size-2xl
Font Weights: --atomix-font-weight-light through --atomix-font-weight-bold
Line Heights: --atomix-line-height-base, --atomix-line-height-sm, --atomix-line-height-lg

Spacing Tokens

Spacing Scale: --atomix-spacing-0 through --atomix-spacing-200
Common Values: --atomix-spacing-1 (4px), --atomix-spacing-2 (8px), --atomix-spacing-4 (16px)

Border Radius Tokens

--atomix-border-radius, --atomix-border-radius-sm, --atomix-border-radius-md, --atomix-border-radius-lg, --atomix-border-radius-xl

Shadow Tokens

--atomix-box-shadow, --atomix-box-shadow-xs, --atomix-box-shadow-sm, --atomix-box-shadow-lg, --atomix-box-shadow-xl

Border Tokens

Border Radius: --atomix-border-radius, --atomix-border-radius-sm, --atomix-border-radius-lg, --atomix-border-radius-xl, --atomix-border-radius-xxl, --atomix-border-radius-pill
Border Colors: --atomix-border-color, --atomix-border-color-translucent

Other Tokens

Transitions: --atomix-transition-fast, --atomix-transition-base, --atomix-transition-slow
Z-Index: --atomix-z-dropdown, --atomix-z-modal, --atomix-z-tooltip, etc.
Breakpoints: --atomix-breakpoint-xs, --atomix-breakpoint-sm, etc.
Focus Ring: --atomix-focus-ring-width, --atomix-focus-ring-offset, --atomix-focus-ring-opacity

Importing Theme CSS Files

Individual theme CSS files can be imported separately:

TYPESCRIPT

// Import a specific theme CSS file
import '@shohojdhara/atomix/themes/light';
// or minified version
import '@shohojdhara/atomix/themes/light.min';

4 lines148 characters

Available Theme Imports:

@shohojdhara/atomix/themes/{theme-name} - Expanded CSS
@shohojdhara/atomix/themes/{theme-name}.min - Minified CSS

Note: Theme CSS files are only available if themes are registered in atomix.config.ts and built with npm run build:themes.

Using Generated Tokens

If you've customized tokens via atomix.config.ts, import the generated CSS:

TYPESCRIPT

// Import generated tokens
import '@shohojdhara/atomix/styles/03-generic/_generated-root.css';

2 lines94 characters

Or if using SCSS:

SCSS

@import '@shohojdhara/atomix/scss/generic';

1 line43 characters

The generated tokens will be available as CSS custom properties in your application.

Advanced Topics

Theme Composition

Combine and extend themes to create variations:

TYPESCRIPT

import { mergeTheme, extendTheme } from '@shohojdhara/atomix/theme';

// Merge two themes
const merged = mergeTheme(baseTheme, overrideTheme);

// Extend theme
const extended = extendTheme(baseTheme, {
  palette: {
    primary: { main: '#FF0000' },
  },
});

11 lines257 characters

Component Overrides

Customize component styles per theme:

TYPESCRIPT

const theme = createTheme({
  components: {
    Button: {
      styleOverrides: {
        root: {
          borderRadius: '8px',
          padding: '12px 24px',
        },
      },
      defaultProps: {
        variant: 'primary',
        size: 'lg',
      },
    },
  },
});

16 lines275 characters

Note: ComponentOverrideManager as a separate class is planned for a future release. For now, use createTheme() with components property.

RTL Support

Enable RTL for right-to-left languages:

TYPESCRIPT

import { RTLManager } from '@shohojdhara/atomix/theme';

const rtlManager = new RTLManager({
  enabled: true,
  autoDetect: true,
  locale: 'ar-SA',
});

// Set direction
rtlManager.setDirection('rtl');

10 lines202 characters

CSS Variable Generation

Generate CSS variables programmatically:

TYPESCRIPT

import { generateCSSVariables } from '@shohojdhara/atomix/theme';

const css = generateCSSVariables(myTheme, {
  selector: ':root',
  prefix: 'atomix',
});

// Inject into DOM
document.head.appendChild(
  Object.assign(document.createElement('style'), {
    textContent: css,
  })
);

13 lines283 characters

Theme Validation

Validate themes during development:

TYPESCRIPT

import { validateTheme } from '@shohojdhara/atomix/theme';

const result = validateTheme(myTheme);

if (!result.valid) {
  console.error('Theme validation errors:', result.errors);
}

7 lines182 characters

Development Tools

Preview and inspect themes:

TSX

import { ThemePreview, ThemeInspector } from '@shohojdhara/atomix/theme';

// Preview theme
<ThemePreview
  theme={myTheme}
  showPalette={true}
  showTypography={true}
/>

// Inspect theme
<ThemeInspector
  theme={myTheme}
  showValidation={true}
  showCSSVariables={true}
/>

15 lines276 characters

Troubleshooting

Theme Not Loading

Problem: Theme fails to load

Solutions:

Check theme exists in registry:
TYPESCRIPT
1const themes = themeManager.getAvailableThemes(); 2console.log(themes);
2 lines70 characters
Check for errors:
TYPESCRIPT
1themeManager.on('themeError', (error, themeName) => { 2 console.error('Theme error:', error, themeName); 3});
3 lines108 characters
Verify CSS path exists

CSS Variables Not Working

Problem: CSS variables not found

Solutions:

Ensure theme is loaded (SCSS or JS)
Check prefix matches config
Verify token name follows conventions
Check browser DevTools for actual CSS variable names
If using config-generated tokens, ensure _generated-root.css is imported

Token Generation Issues

Problem: Generated tokens don't match config

Solutions:

Run npm run sync:config to regenerate
Check atomix.config.ts syntax is correct
Verify color values are valid hex colors
Check src/styles/03-generic/_generated-root.css exists and has content
Ensure _generated-root.css is imported in your styles

Problem: Only 1 CSS variable generated instead of full scale

Solutions:

Ensure you're using theme.extend.colors (not theme.tokens.colors)
Check color format: { main: '#3b82f6' } (not just '#3b82f6')
Run npm run sync:config again
Check console output for errors during sync

Theme CSS Import Issues

Problem: Cannot import theme CSS files

Solutions:

Ensure themes are built: npm run build:themes
Check dist/themes/ directory exists
Verify package.json exports include theme paths
Use correct import path: @shohojdhara/atomix/themes/light
Check theme is registered in atomix.config.ts

TypeScript Errors

Problem: TypeScript errors with theme types

Solutions:

Import types correctly:
TYPESCRIPT
1import type { Theme, ThemeMetadata } from '@shohojdhara/atomix/theme';
1 line70 characters
Use type guards:
TYPESCRIPT
1if (isJSTheme(theme)) { 2 // theme is now typed as Theme 3}
3 lines58 characters

Configuration Not Syncing

Problem: Generated files don't match atomix.config.ts

Solution:

BASH

npm run sync:config
npm run sync:tokens
npm run validate:config

3 lines63 characters

Prefix Not Updating

Problem: Prefix changes in config but not in generated files

Solution:

Check atomix.config.ts has prefix field
Run npm run sync:config && npm run sync:tokens
Verify with npm run validate:config

Browser Environment Limitations

Important: The atomix.config.ts file cannot be dynamically loaded in browser environments.

In browser/client-side applications, themes must be explicitly provided to the ThemeManager or ThemeProvider.

TYPESCRIPT

// In browser environments, provide themes directly
import { ThemeProvider } from '@shohojdhara/atomix/theme';

const themes = {
  'my-theme': {
    type: 'css',
    name: 'My Theme',
    class: 'my-theme',
  },
};

function App() {
  return (
    <ThemeProvider 
      themes={themes}
      defaultTheme="my-theme"
      basePath="/themes"
    >
      <YourApp />
    </ThemeProvider>
  );
}

22 lines392 characters

Examples

Complete React Example

TSX

import React from 'react';
import {
  ThemeProvider,
  ThemeErrorBoundary,
  useTheme,
  createTheme,
} from '@shohojdhara/atomix/theme';

const lightTheme = createTheme({
  name: 'Light',
  palette: {
    primary: { main: '#3b82f6' },
    background: { default: '#ffffff' },
  },
});

const darkTheme = createTheme({
  name: 'Dark',
  palette: {
    primary: { main: '#60a5fa' },
    background: { default: '#111827' },
  },
});

function ThemeSelector() {
  const { theme, setTheme } = useTheme();

  return (
    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
      <option value={lightTheme}>Light</option>
      <option value={darkTheme}>Dark</option>
    </select>
  );
}

function App() {
  return (
    <ThemeErrorBoundary
      onError={(error, errorInfo) => {
        console.error('Theme error:', error);
      }}
    >
      <ThemeProvider
        defaultTheme={lightTheme}
        enablePersistence={true}
      >
        <ThemeSelector />
        <YourApp />
      </ThemeProvider>
    </ThemeErrorBoundary>
  );
}

52 lines1047 characters

Next.js Integration

TSX

// app/layout.tsx
import { ThemeProvider } from '@shohojdhara/atomix/theme';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ThemeProvider>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

14 lines266 characters

Best Practices

1. Always Use CSS Variables

✅ Good:

SCSS

.component {
  color: var(--atomix-primary);
  padding: var(--atomix-spacing-4);
}

4 lines82 characters

❌ Bad: Hardcoded values like color: #3b82f6; or padding: 16px;

2. Use ThemeProvider for React Apps

Always use ThemeProvider for React applications instead of direct ThemeManager usage.

3. Error Boundaries

Always wrap ThemeProvider with error boundary:

TSX

<ThemeErrorBoundary>
  <ThemeProvider>
    <App />
  </ThemeProvider>
</ThemeErrorBoundary>

5 lines91 characters

4. Type Safety

Use TypeScript types:

TYPESCRIPT

import type { Theme, ThemeMetadata } from '@shohojdhara/atomix/theme';

1 line70 characters

5. Performance

Enable caching (default: enabled)
Use lazy loading for themes
Preload critical themes
Use minified CSS in production

6. Accessibility

Validate themes for contrast ratios
Test with screen readers
Ensure keyboard navigation works
Check color blindness compatibility

Interactive Theme Creation

Use the Theme Studio to create and preview themes interactively. Visualize your theme in real-time and export it for use in your application.

Open Theme Studio

Getting Started

Documentation

Resources

Community

Atomix Theme System

Complete Theme System Guide

Quick Start

Installation

Basic Setup (React)

Basic Setup (Vanilla JavaScript)

For External Developers

✅ What You Should Use

1. JavaScript Themes (Recommended)

2. Quick Theme Helper

3. CSS Theme Loading

4. Customize Design Tokens via Config (New!)

❌ What You Should NOT Use

Common Use Cases

Brand Colors

Dark Mode

Multiple Themes with Switching

Quick Start Checklist

For Library Developers

Configuration File

Build Process

SCSS Theme Structure

Theme Types

CSS Themes

JavaScript Themes

API Reference

ThemeProvider

useTheme Hook

ThemeManager

createTheme

Theme Composition

Theme Utilities

ThemeErrorBoundary

RTL Support

Configuration

atomix.config.ts

Configuration Options

Auto-Generated Files

Token Generation Details

Sync Scripts

CSS Variables & Tokens

Using CSS Variables

Available CSS Variables

Color Tokens

Typography Tokens

Spacing Tokens

Border Radius Tokens

Shadow Tokens

Border Tokens

Other Tokens

Importing Theme CSS Files

Using Generated Tokens

Advanced Topics

Theme Composition

Component Overrides

RTL Support

CSS Variable Generation

Theme Validation

Development Tools

Troubleshooting

Theme Not Loading

CSS Variables Not Working

Token Generation Issues

Theme CSS Import Issues

TypeScript Errors

Configuration Not Syncing

Prefix Not Updating

Browser Environment Limitations

Examples

Complete React Example

Next.js Integration

Best Practices

1. Always Use CSS Variables

2. Use ThemeProvider for React Apps

3. Error Boundaries

4. Type Safety