362 lines
7.7 KiB
Markdown
362 lines
7.7 KiB
Markdown
# 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
|