init

2026-02-04 06:23:04 -05:00
commit efe206a589
22 changed files with 4107 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,266 @@
+# OTS Signage - Modern Xibo CMS Theme
+
+A modernized theme for Xibo CMS that brings contemporary UI/UX patterns, improved accessibility, and a comprehensive design token system.
+
+## What's New
+
+### 🎨 Design Tokens System
+- **Color palette**: 10 semantic colors + 9-step gray scale with light/dark mode support
+- **Typography**: System font stack, 8-step type scale, 5 font weights
+- **Spacing**: 8px-based scale (0–80px) for consistent margins and padding
+- **Elevation**: Shadow system with 6 levels for depth perception
+- **Radius**: Border radius scale from sharp to full-rounded
+- **Transitions**: Predefined animation durations for consistency
+
+### 🌙 Dark Mode Support
+- Automatic dark mode via `prefers-color-scheme` media query
+- Token overrides for dark theme built-in
+- No additional JavaScript required for system preference
+
+### 📱 Responsive Layout
+- Mobile-first responsive grid system
+- Sidebar collapses into hamburger on screens ≤768px
+- Flexible widget containers with auto-fit grid
+- Optimized breakpoints (sm: 640px, md: 768px, lg: 1024px, xl: 1280px)
+
+### 🎯 Modern Components
+- **Cards**: Widgets styled as elevated cards with shadows and hover effects
+- **Typography**: Improved hierarchy with modern font sizing
+- **Forms**: Refined input styling with focus ring system
+- **Buttons**: Consistent button styles with proper color variants
+- **Alerts**: Color-coded alerts (success, danger, warning, info)
+- **Tables**: Clean table styling with hover states
+
+### ♿ Accessibility Improvements
+- WCAG AA compliant color contrasts (verified on primary palette)
+- Focus-visible outlines for keyboard navigation
+- Semantic HTML structure preserved
+- Proper heading hierarchy support
+- Form labels and ARIA attributes maintained
+
+### 📊 Widget Styling
+- Card-based widget design with consistent shadows
+- Hover lift effect for interactivity feedback
+- Proper spacing and padding via tokens
+- Title bars with semantic color distinction
+- Dashboard grid with responsive columns
+
+## File Structure
+
+```
+custom/otssignange/
+├── config.php                 # Theme configuration (unchanged)
+├── css/
+│   ├── override.css          # Main theme styles + design tokens (UPDATED)
+│   ├── html-preview.css      # Preview splash screen (UPDATED)
+│   └── client.css            # Widget embedding styles (NEW)
+├── img/
+│   ├── favicon.ico
+│   ├── 192x192.png
+│   ├── 512x512.png
+│   └── xibologo.png
+├── layouts/
+│   └── default-layout.zip
+└── views/
+    └── index.html            # Empty - ready for Twig overrides if needed
+```
+
+## CSS Variables Reference
+
+### Colors
+```css
+/* Brand Colors */
+--color-primary: #2563eb
+--color-primary-dark: #1d4ed8
+--color-primary-light: #3b82f6
+--color-secondary: #7c3aed
+
+/* Semantic Colors */
+--color-success: #10b981
+--color-warning: #f59e0b
+--color-danger: #ef4444
+--color-info: #0ea5e9
+
+/* Grays (50–900) */
+--color-gray-50, 100, 200, 300, 400, 500, 600, 700, 800, 900
+
+/* Semantic Semantic */
+--color-background: #ffffff (dark: #0f172a)
+--color-surface: #f9fafb (dark: #1e293b)
+--color-text-primary: #1f2937 (dark: #f1f5f9)
+--color-text-secondary: #6b7280 (dark: #cbd5e1)
+--color-border: #e5e7eb (dark: #475569)
+```
+
+### Typography
+```css
+--font-family-base: System font stack
+--font-size-xs to 4xl: 0.75rem → 2.25rem
+--font-weight-normal/medium/semibold/bold: 400–700
+--line-height-tight/snug/normal/relaxed/loose: 1.25–2
+```
+
+### Spacing (8px base)
+```css
+--space-1 through --space-20: 0.25rem → 5rem
+```
+
+### Elevation & Borders
+```css
+--shadow-none/xs/sm/base/md/lg/xl
+--radius-none/sm/base/md/lg/xl/2xl/full
+--transition-fast/base/slow: 150ms–300ms
+```
+
+## Customization Guide
+
+### Change Brand Color
+Edit `override.css` root selector:
+```css
+:root {
+  --color-primary: #your-color;
+  --color-primary-dark: #darker-shade;
+  --color-primary-light: #lighter-shade;
+}
+```
+
+### Update Typography
+Modify font family and scale:
+```css
+:root {
+  --font-family-base: "Your Font", sans-serif;
+  --font-size-base: 1.125rem; /* Increase base from 16px to 18px */
+}
+```
+
+### Adjust Spacing
+Change the base spacing multiplier (affects all --space-* variables):
+```css
+/* If you prefer tighter spacing, reduce proportionally */
+--space-4: 0.75rem; /* was 1rem */
+--space-6: 1.125rem; /* was 1.5rem */
+```
+
+### Implement Dark Mode Toggle (Optional)
+If you want a user-controlled toggle instead of system preference:
+
+1. Add a button to toggle theme in a Twig view override
+2. Store preference in localStorage
+3. Add to `override.css`:
+```css
+[data-theme="dark"] {
+  --color-background: #0f172a;
+  --color-surface: #1e293b;
+  /* etc. */
+}
+```
+
+## Files Modified
+
+### `css/override.css`
+**Changes:**
+- Replaced empty CSS hooks with comprehensive design token system
+- Added global styles using tokens
+- Implemented responsive header/sidebar with mobile hamburger
+- Added widget card styling with elevation effects
+- Included form, button, table, and alert component styles
+- Added responsive grid utilities and spacing classes
+
+**Size:** ~800 lines (was ~50 lines)
+
+### `css/html-preview.css`
+**Changes:**
+- Updated splash screen with gradient background matching brand color
+- Added preview widget styling for consistency
+- Improved visual fidelity with shadows and spacing
+
+### `css/client.css` (NEW)
+**Purpose:**
+- Styles HTML/embedded widgets on displays
+- Uses mirrored design tokens for consistency
+- Includes typography, form, button, and alert styles
+- Supports dark mode with prefers-color-scheme
+
+## Deployment Notes
+
+### Before Deploying to Production
+
+1. **Test in your Xibo CMS instance:**
+   - Log in and verify admin UI appearance
+   - Check sidebar navigation, widgets, and forms
+   - Test on mobile (resize browser or use device)
+   - Verify color contrast with a tool like WAVE or aXe
+
+2. **Verify Asset Paths:**
+   - Ensure `preview/img/xibologo.png` is accessible
+   - Check that logo files in `img/` are served correctly
+   - Validate CSS paths resolve in your installation
+
+3. **Browser Compatibility:**
+   - CSS variables supported in all modern browsers (Chrome 49+, Firefox 31+, Safari 9.1+, Edge 15+)
+   - For legacy browser support, add CSS fallbacks (not included)
+
+4. **Backup:**
+   - Keep a backup of original `override.css` before deployment
+
+### Installation
+
+1. Copy the updated theme files to `/web/theme/custom/otssignange/`
+2. Clear Xibo CMS cache if applicable
+3. Reload the CMS in your browser
+4. No database changes or CMS restart required
+
+### Rollback
+
+If issues occur, revert to backup:
+```bash
+cp override.css.backup override.css
+# Refresh browser cache
+```
+
+## Responsive Breakpoints
+
+| Breakpoint | Width | Use Case |
+|-----------|-------|----------|
+| **Mobile** | < 640px | Single column layout |
+| **Tablet** | 640–768px | Sidebar collapse |
+| **Desktop** | 768–1024px | 2–3 column grids |
+| **Large** | 1024–1280px | Multi-column dashboards |
+| **Ultra** | ≥ 1280px | Full-width content |
+
+## Accessibility Checklist
+
+- [x] WCAG AA color contrast (4.5:1 text, 3:1 components)
+- [x] Focus visible outlines (2px solid primary color)
+- [x] Keyboard navigation preserved
+- [x] Semantic HTML maintained
+- [x] Form labels and ARIA attributes respected
+- [x] No color-only information conveyed
+- [x] Sufficient touch target sizes (≥44px)
+
+## Future Enhancements
+
+Suggested follow-ups:
+- Create Twig view overrides for `authed.twig` and `authed-sidebar.twig` for DOM-level layout improvements
+- Add SVG icon sprite for consistent iconography across CMS
+- Implement animated transitions for sidebar collapse
+- Add data visualization component styles (charts, graphs)
+- Create documentation portal in Xibo for custom branding
+
+## Support & Questions
+
+For documentation on Xibo CMS theming:
+- [Xibo Developer Docs](https://account.xibosignage.com/docs/developer/)
+- Theme config reference: `config.php`
+- Available Twig overrides: Check `/web/theme/default/views/` in your Xibo installation
+
+## License
+
+This theme extends Xibo CMS and is subject to AGPLv3 license per Xibo requirements.
+Xibo is © 2006–2021 Xibo Signage Ltd.
+
+---
+
+**Theme Version:** 1.0.0 (Modern)  
+**Last Updated:** February 2026  
+**Xibo CMS Compatibility:** 3.x and above