# OTS Signs Xibo Theme - Quick Reference Card

## 🚀 Quick Start (2 minutes)

### Step 1: Deploy Theme
```bash
# 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)
```css
--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)
```css
.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)
```twig
<!-- 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

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

```css
--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
```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
```css
.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+