nostr_login_lite/themes/README.md

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:

{
  "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

mkdir themes/my-theme
cd themes/my-theme

2. Create theme.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

: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:

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

Using Themes

Initialization

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

Runtime Switching

// 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

// 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

// 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

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

// 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:

// 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.