370 lines
9.1 KiB
Markdown
370 lines
9.1 KiB
Markdown
# 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. |