init

2026-02-04 06:23:04 -05:00
commit efe206a589
22 changed files with 4107 additions and 0 deletions
--- a/CUSTOMIZATION.md
+++ b/CUSTOMIZATION.md
@@ -0,0 +1,361 @@
+# Theme Customization Cookbook
+
+Quick recipes for common customization tasks in your Xibo CMS theme.
+
+## 1. Change Primary Brand Color
+
+**File:** `css/override.css`
+
+Find the `:root` selector and update:
+
+```css
+:root {
+  --color-primary: #006bb3;        /* Change from blue #2563eb to custom blue */
+  --color-primary-dark: #004c80;   /* Darker shade for hover/active states */
+  --color-primary-light: #1a9ad1;  /* Lighter shade for backgrounds */
+  --color-primary-lighter: #d4e6f1; /* Very light for highlights */
+}
+```
+
+This single change affects:
+- Header bar background
+- Sidebar primary colors
+- Buttons, links, and focus states
+- Widget title bars
+
+## 2. Use a Custom Font
+
+**File:** `css/override.css`
+
+Replace the `--font-family-base` variable:
+
+```css
+:root {
+  /* Option A: Google Font (add to <head> in Twig override) */
+  --font-family-base: "Inter", "Segoe UI", sans-serif;
+  
+  /* Option B: Local font file */
+  @font-face {
+    font-family: "MyCustomFont";
+    src: url('../fonts/my-font.woff2') format('woff2');
+  }
+  --font-family-base: "MyCustomFont", sans-serif;
+}
+```
+
+To use Google Fonts, add this line to a Twig template (e.g., in a view override):
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+```
+
+## 3. Implement a Company Logo in Header
+
+**Files:** `css/override.css` (styling), `img/` (asset)
+
+1. Replace logo files in `custom/otssignange/img/`:
+   - `xibologo.png` (header logo, ~40x40px)
+   - `192x192.png` (app icon for app manifest)
+   - `512x512.png` (splash/bookmarklet icon)
+
+2. If you need to style the logo more prominently, add to `override.css`:
+
+```css
+.navbar-brand {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding-left: var(--space-4);
+}
+
+.navbar-brand img {
+  height: 40px;
+  width: auto;
+}
+```
+
+## 4. Darken the Sidebar
+
+**File:** `css/override.css`
+
+Update sidebar color tokens:
+
+```css
+:root {
+  --color-surface: #2d3748;        /* Darker gray instead of light */
+  --color-text-primary: #ffffff;   /* White text on dark background */
+}
+
+#sidebar-wrapper {
+  background-color: #1a202c;       /* Even darker for contrast */
+}
+
+ul.sidebar .sidebar-list a {
+  color: #cbd5e1;                  /* Light gray text */
+}
+
+ul.sidebar .sidebar-list a:hover {
+  background-color: #2d3748;       /* Slightly lighter on hover */
+  color: #ffffff;
+}
+```
+
+## 5. Increase Widget Spacing & Padding
+
+**File:** `css/override.css`
+
+Modify spacing tokens to make everything roomier:
+
+```css
+:root {
+  /* Scale up all spacing */
+  --space-4: 1.25rem;  /* was 1rem (16px → 20px) */
+  --space-6: 2rem;     /* was 1.5rem (24px → 32px) */
+  --space-8: 2.75rem;  /* was 2rem (32px → 44px) */
+}
+
+.widget {
+  padding: var(--space-8);  /* Uses new token value */
+}
+```
+
+## 6. Remove Shadows (Flat Design)
+
+**File:** `css/override.css`
+
+Set all shadows to none:
+
+```css
+:root {
+  --shadow-xs: none;
+  --shadow-sm: none;
+  --shadow-base: none;
+  --shadow-md: none;
+  --shadow-lg: none;
+  --shadow-xl: none;
+}
+```
+
+## 7. Customize Button Styles
+
+**File:** `css/override.css`
+
+Make buttons larger with more rounded corners:
+
+```css
+button,
+.btn {
+  padding: var(--space-4) var(--space-6);    /* Increase from var(--space-3) var(--space-4) */
+  border-radius: var(--radius-xl);           /* Make more rounded */
+  font-weight: var(--font-weight-semibold);  /* Make text bolder */
+  text-transform: uppercase;                 /* OPTIONAL: Uppercase labels */
+  letter-spacing: 0.05em;                    /* OPTIONAL: Wider letter spacing */
+}
+```
+
+## 8. Force Light Mode (Disable Dark Mode)
+
+**File:** `css/override.css`
+
+Remove the dark mode media query or override it:
+
+```css
+/* Delete or comment out this section: */
+/*
+@media (prefers-color-scheme: dark) {
+  :root { ... }
+}
+*/
+
+/* OR force light mode explicitly: */
+:root {
+  color-scheme: light;  /* Tells browser to not apply dark UI elements */
+}
+
+/* Force light colors even if system prefers dark */
+@media (prefers-color-scheme: dark) {
+  :root {
+    /* Keep all light mode values, don't override */
+  }
+}
+```
+
+## 9. Add a Custom Alert Style
+
+**File:** `css/override.css`
+
+Append a new alert variant (e.g., for secondary notifications):
+
+```css
+.alert-secondary {
+  background-color: #e2e8f0;
+  border-color: #cbd5e1;
+  color: #334155;
+}
+
+.alert-secondary a {
+  color: #2563eb;
+  font-weight: var(--font-weight-semibold);
+}
+```
+
+Use in Xibo: Apply `.alert alert-secondary` class to a notification element.
+
+## 10. Improve Form Focus States
+
+**File:** `css/override.css`
+
+Make focused form inputs more prominent:
+
+```css
+input[type="text"]:focus,
+input[type="email"]:focus,
+input[type="password"]:focus,
+textarea:focus,
+select:focus {
+  outline: none;
+  border-color: var(--color-primary);
+  box-shadow: 0 0 0 4px var(--color-primary-lighter),   /* Outer glow */
+              0 0 0 1px var(--color-primary);             /* Inner border */
+  background-color: #fafbff;                             /* Subtle highlight */
+}
+```
+
+## 11. Create a Compact Theme Variant
+
+**File:** `css/override.css`
+
+Add a utility class for a denser layout:
+
+```css
+.theme-compact {
+  --space-4: 0.75rem;
+  --space-6: 1rem;
+  --font-size-base: 0.875rem;  /* Slightly smaller text */
+}
+
+/* Apply to body or any container */
+body.theme-compact {
+  /* All tokens inherit new values */
+}
+```
+
+Then toggle with a Twig override or JS:
+```javascript
+document.body.classList.toggle('theme-compact');
+```
+
+## 12. Modify Widget Title Bar Colors
+
+**File:** `css/override.css`
+
+Make widget titles more distinctive:
+
+```css
+.widget .widget-title {
+  background: linear-gradient(135deg, var(--color-primary), var(--color-primary-dark));
+  color: var(--color-text-inverse);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  font-size: var(--font-size-sm);
+  padding: var(--space-6);
+  border-bottom: 2px solid var(--color-primary-dark);
+}
+```
+
+## 13. Style Table Headers Distinctly
+
+**File:** `css/override.css`
+
+Make tables look more modern:
+
+```css
+thead {
+  background: linear-gradient(to bottom, var(--color-primary-lighter), var(--color-gray-100));
+}
+
+th {
+  color: var(--color-primary);
+  font-weight: var(--font-weight-bold);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  font-size: var(--font-size-sm);
+  padding: var(--space-6) var(--space-4);
+  border-bottom: 2px solid var(--color-primary);
+}
+
+tbody tr:nth-child(odd) {
+  background-color: var(--color-gray-50);
+}
+
+tbody tr:hover {
+  background-color: var(--color-primary-lighter);
+}
+```
+
+## 14. Enable Full Dark Mode in Browser
+
+Some users may have `prefers-color-scheme: dark` set. To test locally:
+
+**Chrome DevTools:**
+1. Open DevTools (F12)
+2. Ctrl+Shift+P (or Cmd+Shift+P on Mac)
+3. Type "rendering"
+4. Select "Show Rendering"
+5. Scroll to "Prefers color scheme" and select "dark"
+6. Refresh page
+
+**Firefox:**
+1. about:config
+2. Search for `ui.systemUsesDarkTheme`
+3. Set to `1` for dark mode
+
+## 15. Add Custom Utility Classes
+
+**File:** `css/override.css`
+
+Extend the theme with custom utilities at the end:
+
+```css
+/* Custom utilities */
+.text-primary {
+  color: var(--color-primary);
+}
+
+.bg-primary {
+  background-color: var(--color-primary);
+  color: var(--color-text-inverse);
+}
+
+.border-primary {
+  border-color: var(--color-primary);
+}
+
+.opacity-50 {
+  opacity: 0.5;
+}
+
+.cursor-pointer {
+  cursor: pointer;
+}
+
+.no-wrap {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.flex-center {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+```
+
+---
+
+**Pro Tips:**
+- Always test changes in a staging Xibo instance before deploying to production
+- Use browser DevTools to inspect elements and live-edit CSS before making permanent changes
+- Keep a backup of your original CSS before making large modifications
+- Document any custom changes you make in comments within the CSS file for future reference