npm package: @nitesh6690/stellar-ui-themes
Description: Design tokens and theming system for Stellar UI
Author: Stellar UI Team
Latest version: 0.1.0

# @stellar-ui/themes

Design tokens and theme management for Stellar UI.

## Installation

```bash
npm install @stellar-ui/themes react
```

## Usage

### 1. Import CSS

Import the base styles and theme definitions in your app:

```tsx
import '@stellar-ui/themes/base.css';
import '@stellar-ui/themes/themes.css';
```

### 2. Wrap your app with ThemeProvider

```tsx
import { ThemeProvider } from '@stellar-ui/themes';

function App() {
  return (
    <ThemeProvider defaultTheme="light" storageKey="my-app-theme">
      <YourApp />
    </ThemeProvider>
  );
}
```

### 3. Use the theme

```tsx
import { useTheme } from '@stellar-ui/themes';

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

  return (
    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
      {themes.map((t) => (
        <option key={t} value={t}>
          {t}
        </option>
      ))}
    </select>
  );
}
```

## Available Themes

- **light** - Clean, modern light theme (default)
- **dark** - Comfortable dark theme
- **corporate** - Professional business theme
- **nature** - Earth-toned, organic theme

## Design Tokens

### Colors

All themes provide consistent color tokens:

```css
/* Background */
--color-background
--color-background-subtle
--color-background-muted

/* Text */
--color-text-primary
--color-text-secondary
--color-text-tertiary
--color-text-inverse

/* Borders */
--color-border
--color-border-strong
--color-border-subtle

/* Semantic Colors */
--color-primary
--color-secondary
--color-accent
--color-destructive
--color-success
--color-warning
--color-info
--color-muted

/* Each semantic color has variants */
--color-primary-hover
--color-primary-active
--color-primary-foreground
--color-primary-subtle
```

### Typography

```css
/* Font Families */
--font-sans
--font-mono

/* Font Sizes */
--font-size-xs   /* 12px */
--font-size-sm   /* 14px */
--font-size-base /* 16px */
--font-size-lg   /* 18px */
--font-size-xl   /* 20px */
--font-size-2xl  /* 24px */
--font-size-3xl  /* 30px */
--font-size-4xl  /* 36px */
--font-size-5xl  /* 48px */

/* Font Weights */
--font-weight-normal
--font-weight-medium
--font-weight-semibold
--font-weight-bold

/* Line Heights */
--line-height-none
--line-height-tight
--line-height-normal
--line-height-relaxed
--line-height-loose
```

### Spacing

```css
--space-0   /* 0 */
--space-1   /* 4px */
--space-2   /* 8px */
--space-3   /* 12px */
--space-4   /* 16px */
--space-6   /* 24px */
--space-8   /* 32px */
--space-12  /* 48px */
--space-16  /* 64px */
```

### Border Radius

```css
--radius-none
--radius-sm   /* 2px */
--radius-base /* 4px */
--radius-md   /* 6px */
--radius-lg   /* 8px */
--radius-xl   /* 12px */
--radius-2xl  /* 16px */
--radius-full /* 9999px */
```

### Shadows

```css
--shadow-sm
--shadow-base
--shadow-md
--shadow-lg
--shadow-xl
--shadow-2xl
```

### Z-Index

```css
--z-index-dropdown
--z-index-sticky
--z-index-modal-backdrop
--z-index-modal
--z-index-tooltip
--z-index-notification
```

## Using Design Tokens

```css
.my-button {
  background-color: var(--color-primary);
  color: var(--color-primary-foreground);
  padding: var(--space-3) var(--space-6);
  border-radius: var(--radius-md);
  font-size: var(--font-size-sm);
  font-weight: var(--font-weight-medium);
  box-shadow: var(--shadow-sm);
  transition: background-color var(--transition-base);
}

.my-button:hover {
  background-color: var(--color-primary-hover);
}
```

## System Theme Detection

```tsx
import { useSystemTheme, getSystemTheme } from '@stellar-ui/themes';

// Hook to listen to system theme changes
function MyComponent() {
  const systemTheme = useSystemTheme();
  return <div>System preference: {systemTheme}</div>;
}

// One-time check
const currentSystemTheme = getSystemTheme();
```

## Creating Custom Themes

Create your own theme by defining the color tokens:

```css
[data-theme="custom"] {
  color-scheme: light;
  
  --color-background: hsl(0 0% 100%);
  --color-foreground: hsl(0 0% 9%);
  --color-primary: hsl(280 90% 50%);
  --color-primary-foreground: hsl(0 0% 100%);
  /* ... define all required tokens ... */
}
```

Then add it to your theme type:

```tsx
type CustomTheme = Theme | 'custom';
```

## Features

✅ **Multiple Themes** - Light, Dark, Corporate, Nature  
✅ **Design Tokens** - Consistent variables across all themes  
✅ **React Integration** - Provider and hooks for theme management  
✅ **LocalStorage** - Persists theme selection  
✅ **System Theme Detection** - Respects user's OS preference  
✅ **Type-Safe** - Full TypeScript support  
✅ **CSS Variables** - Native CSS custom properties  
✅ **No Runtime** - Pure CSS, minimal JS overhead