# NOSTR_LOGIN_LITE Theme System

A comprehensive theming system supporting CSS custom properties, JSON metadata, and runtime theme switching.

## Architecture Overview

The theme system consists of:

- **CSS Custom Properties**: Dynamic styling variables
- **JSON Metadata**: Theme descriptions and configurations
- **Theme Manager**: Runtime loading and switching
- **Directory Organization**: Structured theme packages

## Directory Structure

```
themes/
├── README.md                 # This documentation
├── theme-manager.js          # Theme management system
├── default/                  # Default monospace theme
│   ├── theme.json           # Theme metadata
│   ├── theme.css            # CSS custom properties
│   └── assets/              # Theme assets (fonts, images)
├── dark/                     # Dark cyberpunk theme
│   ├── theme.json
│   ├── theme.css
│   └── assets/
└── community/                # Community contributed themes
    └── [theme-name]/
        ├── theme.json
        ├── theme.css
        └── assets/
```

## CSS Custom Properties

All themes use standardized CSS custom properties with the `--nl-` prefix:

### Colors
- `--nl-primary-color`: Main text/border color
- `--nl-secondary-color`: Background color
- `--nl-accent-color`: Hover/active accent color

### Typography
- `--nl-font-family`: Base font family
- `--nl-font-size-base`: Base font size (14px)
- `--nl-font-size-title`: Title font size (24px)
- `--nl-font-size-heading`: Heading font size (18px)
- `--nl-font-size-button`: Button font size (16px)
- `--nl-font-weight-normal`: Normal weight (400)
- `--nl-font-weight-medium`: Medium weight (500)
- `--nl-font-weight-bold`: Bold weight (600)

### Layout
- `--nl-border-radius`: Border radius (15px)
- `--nl-border-width`: Border thickness (3px)
- `--nl-border-style`: Border style (solid)
- `--nl-padding-button`: Button padding (12px 16px)
- `--nl-padding-container`: Container padding (20px 24px)

### Effects
- `--nl-transition-duration`: Animation duration (0.2s)
- `--nl-transition-easing`: Animation easing (ease)
- `--nl-shadow`: Box shadow effects
- `--nl-backdrop-filter`: Backdrop filter effects

### Component States
- `--nl-button-bg`: Button background
- `--nl-button-color`: Button text color
- `--nl-button-border`: Button border
- `--nl-button-hover-border-color`: Button hover border
- `--nl-button-active-bg`: Button active background
- `--nl-button-active-color`: Button active text

## Theme Metadata (theme.json)

Each theme must include a `theme.json` file with the following structure:

```json
{
  "name": "Theme Display Name",
  "version": "1.0.0",
  "author": "Author Name/Email",
  "description": "Theme description",
  "preview": "preview.png",
  "compatibility": "1.0+",
  "license": "MIT",
  "variables": {
    "--nl-primary-color": "#000000",
    "--nl-secondary-color": "#ffffff",
    "--nl-accent-color": "#ff0000"
  },
  "assets": ["fonts/", "images/"],
  "tags": ["monospace", "dark", "accessibility"]
}
```

### Required Fields
- `name`: Human-readable theme name
- `version`: Semantic version number
- `variables`: CSS custom property values

### Optional Fields
- `author`: Theme creator information
- `description`: Theme description
- `preview`: Preview image filename
- `compatibility`: Minimum library version
- `license`: License identifier (MIT, GPL, etc.)
- `assets`: Additional asset directories
- `tags`: Theme categorization tags

## Creating a New Theme

### 1. Create Theme Directory

```bash
mkdir themes/my-theme
cd themes/my-theme
```

### 2. Create theme.json

```json
{
  "name": "My Custom Theme",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A custom theme for NOSTR_LOGIN_LITE",
  "variables": {
    "--nl-primary-color": "#your-color",
    "--nl-secondary-color": "#your-bg-color", 
    "--nl-accent-color": "#your-accent-color",
    "--nl-font-family": "\"Your Font\", monospace"
  },
  "tags": ["custom"]
}
```

### 3. Create theme.css

```css
:root {
  /* Colors */
  --nl-primary-color: #your-color;
  --nl-secondary-color: #your-bg-color;
  --nl-accent-color: #your-accent-color;
  
  /* Typography */
  --nl-font-family: "Your Font", monospace;
  
  /* Layout - inherit defaults or customize */
  --nl-border-radius: 15px;
  --nl-border-width: 3px;
  
  /* Add custom variables */
  --nl-custom-shadow: 0 0 10px rgba(0,0,0,0.3);
}

/* Optional: Custom component styles */
.nl-button {
  /* Theme-specific enhancements */
  box-shadow: var(--nl-custom-shadow);
}
```

### 4. Add Assets (Optional)

```
my-theme/
├── theme.json
├── theme.css
└── assets/
    ├── fonts/
    │   └── custom-font.woff2
    └── images/
        └── pattern.png
```

### 5. Register Theme

Update `theme-manager.js` to include your theme:

```javascript
this.availableThemes.set('my-theme', {
  name: 'My Custom Theme',
  path: 'my-theme',
  description: 'A custom theme for NOSTR_LOGIN_LITE'
});
```

## Using Themes

### Initialization

```javascript
await NOSTR_LOGIN_LITE.init({
  theme: 'default',
  themePath: './themes/'
});
```

### Runtime Switching

```javascript
// Switch theme
await NOSTR_LOGIN_LITE.switchTheme('dark');

// Get current theme
const current = NOSTR_LOGIN_LITE.getCurrentTheme();

// List available themes
const available = NOSTR_LOGIN_LITE.getAvailableThemes();
```

### Custom Variables

```javascript
// Set custom variable
NOSTR_LOGIN_LITE.setThemeVariable('--nl-accent-color', '#ff00ff');

// Get variable value
const value = NOSTR_LOGIN_LITE.getThemeVariable('--nl-accent-color');
```

### Theme Export

```javascript
// Export current theme configuration
const themeData = NOSTR_LOGIN_LITE.exportTheme();
console.log(JSON.stringify(themeData, null, 2));
```

## Theme Guidelines

### Accessibility
- Ensure sufficient color contrast (4.5:1 minimum)
- Test with screen readers
- Support high contrast mode
- Use semantic color names

### Performance
- Minimize CSS file size
- Optimize asset files
- Use web-safe fonts as fallbacks
- Consider loading performance

### Compatibility
- Test across browsers
- Ensure mobile responsiveness
- Validate CSS custom property support
- Test with different font sizes

### Best Practices
- Use consistent naming conventions
- Provide clear documentation
- Include preview images
- Tag themes appropriately
- Test thoroughly before submission

## Community Contributions

### Submission Process
1. Fork the repository
2. Create theme in `themes/community/your-theme/`
3. Follow all guidelines above
4. Test thoroughly
5. Submit pull request with:
   - Theme files
   - Preview screenshot
   - Documentation updates

### Review Criteria
- Code quality and organization
- Accessibility compliance
- Cross-browser compatibility
- Unique design contribution
- Proper documentation

## Built-in Themes

### Default Theme
- **Colors**: Black/white/red
- **Typography**: Courier New monospace
- **Style**: Clean, minimalist, accessible
- **Use Case**: General purpose, high readability

### Dark Theme  
- **Colors**: Green/black/magenta
- **Typography**: Courier New monospace
- **Style**: Cyberpunk, terminal-inspired
- **Use Case**: Low light environments, developer aesthetic

## API Reference

### ThemeManager Class

```javascript
const themeManager = new NostrThemeManager();

// Load theme
await themeManager.loadTheme('theme-name');

// Switch theme
await themeManager.switchTheme('theme-name');

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

// Set/get variables
themeManager.setThemeVariable('--nl-accent-color', '#ff0000');
const value = themeManager.getThemeVariable('--nl-accent-color');

// Export current theme
const exported = themeManager.exportCurrentTheme();
```

### NOSTR_LOGIN_LITE Integration

```javascript
// Initialize with theme
await NOSTR_LOGIN_LITE.init({ theme: 'dark' });

// Theme management
await NOSTR_LOGIN_LITE.switchTheme('theme-name');
const current = NOSTR_LOGIN_LITE.getCurrentTheme();
const available = NOSTR_LOGIN_LITE.getAvailableThemes();

// Variable management
NOSTR_LOGIN_LITE.setThemeVariable('--nl-primary-color', '#000000');
const color = NOSTR_LOGIN_LITE.getThemeVariable('--nl-primary-color');

// Export functionality
const themeData = NOSTR_LOGIN_LITE.exportTheme();
```

## Events

The theme system dispatches events for integration:

```javascript
// Theme change event
window.addEventListener('nlThemeChanged', (event) => {
  console.log('New theme:', event.detail.theme);
  console.log('Theme data:', event.detail.data);
});
```

## Troubleshooting

### Theme Not Loading
- Check theme.json syntax
- Verify file paths
- Check browser console for errors
- Ensure CSS custom properties are supported

### Variables Not Applying  
- Verify CSS custom property names (--nl- prefix)
- Check CSS specificity
- Ensure theme CSS is loaded after base styles
- Validate variable values

### Performance Issues
- Optimize CSS file size
- Compress assets
- Use efficient selectors
- Consider lazy loading for large themes

## License

The theme system is open source under the MIT license. Individual themes may have their own licenses as specified in their theme.json files.