OTSSignsTheme/README.md

# 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