OTSSignsTheme/QUICK_REFERENCE.md

OTS Signs Xibo Theme - Quick Reference Card

🚀 Quick Start (2 minutes)

Step 1: Deploy Theme

# Copy to your Xibo installation (if you have it)
cp -r ~/dev/otssignstheme/custom/otssignange /path/to/xibo-cms/web/theme/custom/

Step 2: Enable in Xibo

1. Login to Xibo CMS
2. Settings → Preferences → Themes
3. Select "OTS Signs"
4. Click Save
5. Refresh page

Step 3: Verify

• Dashboard shows 3 KPI cards (Displays, Schedules, Users)
• Sidebar has organized menu sections
• Dark theme applied (navy background)
• Mobile sidebar toggle works on narrow screens

---

📂 File Map

Path	Size	Purpose
css/override.css	20 KB	Dark theme + all components
js/theme.js	4.6 KB	Sidebar toggle, dropdowns
views/authed.twig	3.4 KB	Main layout shell
views/authed-sidebar.twig	5.9 KB	Left navigation sidebar
views/dashboard.twig	4.9 KB	Dashboard page
views/displays.twig	5.1 KB	Displays management
views/media.twig	5.2 KB	Media library

---

🎨 Color Reference

--color-primary: #3b82f6              Blue (buttons, accents)
--color-background: #0f172a           Navy (main background)
--color-surface: #1e293b              Slate (cards)
--color-surface-elevated: #334155     Darker slate (headers)
--color-text-primary: #f1f5f9         Off-white (text)
--color-text-secondary: #cbd5e1       Gray (labels)
--color-success: #10b981              Green (online status)
--color-danger: #ef4444               Red (offline status)

---

🔧 Quick Customization

Change Primary Color

File: css/override.css (line ~19)

--color-primary: #3b82f6;        /* Change me! */
--color-primary-dark: #1d4ed8;
--color-primary-light: #60a5fa;

Suggested colors:

• Purple: #8b5cf6 / #7c3aed / #6d28d9
• Red: #ef4444 / #dc2626 / #b91c1c
• Green: #10b981 / #059669 / #047857
• Orange: #f97316 / #ea580c / #c2410c

Change Sidebar Width

File: css/override.css (line ~58)

.ots-sidebar {
  width: 250px;  /* Change to 280px, 300px, etc. */
}
.ots-main {
  margin-left: 250px;  /* Must match sidebar width */
}

Add Company Logo

File: views/authed-sidebar.twig (line ~7)

<!-- Replace: -->
<span class="brand-icon">🎯</span>

<!-- With: -->
<img src="{{ baseUrl }}/theme/custom/otssignange/img/logo.png" 
     alt="{{ app_name }}" style="width: 28px; height: 28px;" />

---

✅ Component Classes

Layout

• .ots-shell - Main wrapper
• .ots-sidebar - Left navigation
• .ots-topbar - Top header
• .ots-content - Main content area
• .ots-footer - Footer

Dashboard

• .kpi-section - KPI cards container
• .kpi-card - Single KPI card
• .dashboard-panels - Panel grid
• .panel - Card component
• .action-cards - Quick actions grid

Displays/Media

• .two-column-layout - Layout wrapper
• .left-panel - Sidebar panel
• .content-panel - Main content
• .folder-tree - Folder list
• .media-grid - Image grid

Common

• .btn, .btn-primary, .btn-outline, .btn-sm
• .badge, .badge-success, .badge-danger
• .table, .table-striped
• .text-muted, .text-xs

---

🐛 Common Issues

Issue	Solution
Dark theme not showing	Clear cache: Settings → Maintenance → Purge Cache
Sidebar toggle not working	Check browser console (F12) for errors
Images not showing in media grid	Verify image URLs are accessible, check permissions
Mobile sidebar stuck off-screen	Test in new browser tab, clear localStorage
CSS not loading	Check file exists at web/theme/custom/otssignange/css/override.css

---

📱 Responsive Breakpoints

Mobile: max-width: 640px
Tablet: 641px - 768px
Desktop: 769px+

Key behavior:
- Sidebar: hidden/drawer on mobile, fixed on desktop
- Topbar: flex-column on mobile, flex-row on desktop
- Grids: 1 column on mobile, 2+ columns on desktop

---

🎯 CSS Variables Quick Edit

File: css/override.css top section

Change any of these to customize the entire theme:

--color-primary: #3b82f6;              /* Primary brand color */
--color-background: #0f172a;           /* Main background */
--color-surface: #1e293b;              /* Card background */
--color-border: #475569;               /* Divider lines */
--color-text-primary: #f1f5f9;         /* Main text */
--color-text-secondary: #cbd5e1;       /* Secondary text */
--color-text-tertiary: #94a3b8;        /* Muted text */

---

🔗 Important Paths

Relative to Xibo root:

/web/theme/custom/otssignange/
├── config.php
├── css/override.css                 ← Main styling
├── js/theme.js                      ← Interactions
└── views/
    ├── authed.twig                  ← Main shell
    ├── authed-sidebar.twig          ← Sidebar nav
    ├── dashboard.twig
    ├── displays.twig
    └── media.twig

---

📊 File Sizes

• override.css: 20 KB
• theme.js: 4.6 KB
• authed.twig: 3.4 KB
• authed-sidebar.twig: 5.9 KB
• dashboard.twig: 4.9 KB
• displays.twig: 5.1 KB
• media.twig: 5.2 KB

Total theme size: ~49 KB

---

🎓 Code Examples

Use in Twig

<!-- KPI Card -->
<div class="kpi-card">
  <div class="kpi-header">
    <h3 class="kpi-label">Displays</h3>
  </div>
  <div class="kpi-body">
    <div class="kpi-number">{{ count }}</div>
  </div>
</div>

<!-- Button -->
<a href="{{ baseUrl }}/display" class="btn btn-primary">Add Display</a>

<!-- Badge -->
<span class="badge badge-success">Online</span>

CSS Variables in Custom Styles

.my-component {
  background: var(--color-surface);
  color: var(--color-text-primary);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-md);
  padding: var(--space-4);
  transition: all var(--transition-base);
}

---

🚨 Before Modifying

1. Backup original: cp override.css override.css.backup
2. Test locally: Use browser DevTools to test changes
3. Clear cache: After any CSS/JS change, purge Xibo cache
4. Check mobile: Test responsive changes at 375px width

---

📞 Need Help?

Check these files in order:

1. IMPLEMENTATION_COMPLETE.md - What was changed
2. THEME_IMPLEMENTATION.md - Full documentation
3. views/authed.twig - Template structure
4. css/override.css - Component styling
5. js/theme.js - Interactivity

---

Last Updated: February 4, 2026
Theme Version: 1.0.0
Xibo Compatibility: v4.0+