CyberPanel/guides/CUSTOM_CSS_GUIDE.md

CyberPanel 2.5.5-dev Custom CSS Guide

A comprehensive guide for creating custom CSS that fully works with the new design system of CyberPanel 2.5.5-dev.

Table of Contents

1. Overview
2. Design System Architecture
3. CSS Variables Reference
4. Component Structure
5. Customization Examples
6. Best Practices
7. Troubleshooting
8. Advanced Techniques

Overview

CyberPanel 2.5.5-dev features a modern, CSS-variable-based design system that supports both light and dark themes. The system is built with:

• CSS Custom Properties (Variables) for consistent theming
• Modern CSS Grid and Flexbox layouts
• Responsive design principles
• Dark mode support with automatic theme switching
• Component-based architecture for easy customization

Design System Architecture

Core Structure

The design system is built around CSS custom properties defined in :root and [data-theme="dark"] selectors:

:root {
    /* Light Theme Variables */
    --bg-primary: #f0f0ff;
    --bg-secondary: white;
    --text-primary: #2f3640;
    --accent-color: #5856d6;
    /* ... more variables */
}

[data-theme="dark"] {
    /* Dark Theme Variables */
    --bg-primary: #0f0f23;
    --bg-secondary: #1a1a3e;
    --text-primary: #e4e4e7;
    --accent-color: #7c7ff3;
    /* ... more variables */
}

Key Components

1. Header (#header) - Top navigation bar
2. Sidebar (#sidebar) - Left navigation panel
3. Main Content (#main-content) - Page content area
4. Cards (.content-card) - Content containers
5. Buttons (.btn) - Interactive elements
6. Forms (.form-*) - Input elements

CSS Variables Reference

Color Variables

Background Colors

--bg-primary          /* Main background color */
--bg-secondary        /* Card/container background */
--bg-sidebar          /* Sidebar background */
--bg-sidebar-item     /* Sidebar menu item background */
--bg-hover            /* Hover state background */

Text Colors

--text-primary        /* Main text color */
--text-secondary      /* Secondary text color */
--text-heading        /* Heading text color */

Accent Colors

--accent-color        /* Primary accent color */
--accent-hover        /* Accent hover state */
--danger-color        /* Error/danger color */
--success-color       /* Success color */

Border & Shadow

--border-color        /* Default border color */
--shadow-color        /* Default shadow color */

Special Variables

Gradients

--warning-bg          /* Warning banner gradient */
--ai-banner-bg        /* AI scanner banner gradient */

Status Colors

--success-bg          /* Success background */
--success-border      /* Success border */
--danger-bg           /* Danger background */
--danger-border       /* Danger border */
--warning-bg          /* Warning background */
--info-bg             /* Info background */

Component Structure

Header Component

#header {
    background: var(--bg-secondary);
    height: 80px;
    display: flex;
    align-items: center;
    padding: 0 30px;
    box-shadow: 0 2px 12px var(--shadow-color);
    position: fixed;
    top: 0;
    left: 260px;
    right: 0;
    z-index: 1000;
}

Customization Example:

/* Change header height and add custom styling */
#header {
    height: 100px;
    background: linear-gradient(135deg, var(--accent-color), var(--accent-hover));
    border-bottom: 3px solid var(--accent-color);
}

#header .logo-text .brand {
    font-size: 32px;
    text-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

Sidebar Component

#sidebar {
    width: 260px;
    background: var(--bg-sidebar);
    height: 100vh;
    position: fixed;
    left: 0;
    top: 0;
    overflow-y: auto;
    z-index: 1001;
}

Customization Example:

/* Make sidebar wider with custom styling */
#sidebar {
    width: 300px;
    background: linear-gradient(180deg, var(--bg-sidebar), var(--bg-secondary));
    border-right: 2px solid var(--accent-color);
}

#sidebar .menu-item {
    margin: 4px 20px;
    border-radius: 12px;
    transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}

#sidebar .menu-item:hover {
    transform: translateX(5px);
    box-shadow: 0 4px 12px var(--shadow-color);
}

Content Cards

.content-card {
    background: var(--bg-secondary);
    border-radius: 12px;
    padding: 30px;
    box-shadow: 0 2px 8px var(--shadow-color);
    border: 1px solid var(--border-color);
    margin-bottom: 25px;
}

Customization Example:

/* Add glassmorphism effect to cards */
.content-card {
    background: rgba(255, 255, 255, 0.1);
    backdrop-filter: blur(10px);
    border: 1px solid rgba(255, 255, 255, 0.2);
    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
}

[data-theme="dark"] .content-card {
    background: rgba(26, 26, 62, 0.3);
    border: 1px solid rgba(255, 255, 255, 0.1);
}

Customization Examples

1. Complete Theme Override

/* Custom Purple Theme */
:root {
    --bg-primary: #f8f4ff;
    --bg-secondary: #ffffff;
    --bg-sidebar: #f3f0ff;
    --bg-hover: #e8e0ff;
    --text-primary: #2d1b69;
    --text-secondary: #6b46c1;
    --accent-color: #8b5cf6;
    --accent-hover: #7c3aed;
    --border-color: #e0d7ff;
    --shadow-color: rgba(139, 92, 246, 0.1);
}

[data-theme="dark"] {
    --bg-primary: #1a0b2e;
    --bg-secondary: #2d1b69;
    --bg-sidebar: #1e0a3e;
    --bg-hover: #3d2a7a;
    --text-primary: #f3f0ff;
    --text-secondary: #c4b5fd;
    --accent-color: #a78bfa;
    --accent-hover: #8b5cf6;
    --border-color: #4c1d95;
    --shadow-color: rgba(139, 92, 246, 0.3);
}

2. Custom Button Styles

/* Custom button variants */
.btn-custom {
    background: linear-gradient(135deg, var(--accent-color), var(--accent-hover));
    border: none;
    border-radius: 20px;
    padding: 12px 24px;
    color: white;
    font-weight: 600;
    text-transform: uppercase;
    letter-spacing: 0.5px;
    box-shadow: 0 4px 15px rgba(139, 92, 246, 0.3);
    transition: all 0.3s ease;
}

.btn-custom:hover {
    transform: translateY(-2px);
    box-shadow: 0 6px 20px rgba(139, 92, 246, 0.4);
}

.btn-custom:active {
    transform: translateY(0);
}

3. Custom Sidebar Menu Items

/* Animated sidebar menu items */
#sidebar .menu-item {
    position: relative;
    overflow: hidden;
}

#sidebar .menu-item::before {
    content: '';
    position: absolute;
    top: 0;
    left: -100%;
    width: 100%;
    height: 100%;
    background: linear-gradient(90deg, transparent, rgba(255,255,255,0.2), transparent);
    transition: left 0.5s;
}

#sidebar .menu-item:hover::before {
    left: 100%;
}

#sidebar .menu-item .icon-wrapper {
    position: relative;
    z-index: 1;
}

4. Custom Form Styling

/* Modern form inputs */
.form-control {
    border: 2px solid var(--border-color);
    border-radius: 12px;
    padding: 12px 16px;
    font-size: 14px;
    transition: all 0.3s ease;
    background: var(--bg-secondary);
}

.form-control:focus {
    border-color: var(--accent-color);
    box-shadow: 0 0 0 4px rgba(139, 92, 246, 0.1);
    transform: translateY(-1px);
}

.form-control::placeholder {
    color: var(--text-secondary);
    opacity: 0.7;
}

5. Custom Notifications

/* Custom notification banners */
.notification-banner {
    background: linear-gradient(135deg, var(--accent-color), var(--accent-hover));
    border-radius: 16px;
    padding: 20px;
    margin: 20px;
    box-shadow: 0 8px 32px rgba(139, 92, 246, 0.3);
    position: relative;
    overflow: hidden;
}

.notification-banner::before {
    content: '';
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    height: 4px;
    background: linear-gradient(90deg, #ff6b6b, #4ecdc4, #45b7d1, #96ceb4);
    animation: rainbow 3s linear infinite;
}

@keyframes rainbow {
    0% { background-position: 0% 50%; }
    50% { background-position: 100% 50%; }
    100% { background-position: 0% 50%; }
}

Best Practices

1. Use CSS Variables

Always use CSS variables instead of hardcoded values:

/* ✅ Good */
.custom-element {
    background: var(--bg-secondary);
    color: var(--text-primary);
    border: 1px solid var(--border-color);
}

/* ❌ Bad */
.custom-element {
    background: white;
    color: #2f3640;
    border: 1px solid #e8e9ff;
}

2. Support Both Themes

Always provide both light and dark theme support:

.custom-element {
    background: var(--bg-secondary);
    color: var(--text-primary);
}

/* Dark theme specific adjustments */
[data-theme="dark"] .custom-element {
    /* Additional dark theme styling if needed */
}

3. Use Semantic Class Names

/* ✅ Good */
.primary-button { }
.content-container { }
.navigation-item { }

/* ❌ Bad */
.red-button { }
.big-box { }
.item1 { }

4. Maintain Responsive Design

.custom-element {
    padding: 20px;
    font-size: 16px;
}

@media (max-width: 768px) {
    .custom-element {
        padding: 15px;
        font-size: 14px;
    }
}

5. Use Modern CSS Features

.custom-element {
    /* Use CSS Grid for layouts */
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
    gap: 20px;
    
    /* Use Flexbox for alignment */
    align-items: center;
    justify-content: space-between;
    
    /* Use CSS custom properties for calculations */
    --element-height: 60px;
    height: var(--element-height);
    
    /* Use modern selectors */
    &:hover { }
    &:focus-within { }
}

Troubleshooting

Common Issues

1. Custom CSS Not Applying

Problem: Custom CSS doesn't appear to be working.

Solution:

• Check CSS specificity - use more specific selectors
• Ensure CSS is placed after the base styles
• Use !important sparingly and only when necessary

/* Increase specificity */
#main-content .content-card .custom-element {
    background: var(--bg-secondary);
}

2. Dark Mode Not Working

Problem: Custom styles don't adapt to dark mode.

Solution:

• Always use CSS variables
• Test both light and dark themes
• Provide dark mode specific overrides when needed

.custom-element {
    background: var(--bg-secondary);
    color: var(--text-primary);
}

[data-theme="dark"] .custom-element {
    /* Dark mode specific adjustments */
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
}

3. Responsive Issues

Problem: Custom styles break on mobile devices.

Solution:

• Use relative units (rem, em, %)
• Test on different screen sizes
• Use CSS Grid and Flexbox for responsive layouts

.custom-element {
    width: 100%;
    max-width: 1200px;
    margin: 0 auto;
    padding: 1rem;
}

@media (max-width: 768px) {
    .custom-element {
        padding: 0.5rem;
    }
}

Advanced Techniques

1. CSS Animations

/* Smooth page transitions */
.page-transition {
    animation: fadeIn 0.3s ease-in-out;
}

@keyframes fadeIn {
    from { opacity: 0; transform: translateY(20px); }
    to { opacity: 1; transform: translateY(0); }
}

/* Hover animations */
.interactive-element {
    transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}

.interactive-element:hover {
    transform: translateY(-2px) scale(1.02);
    box-shadow: 0 8px 25px var(--shadow-color);
}

2. CSS Grid Layouts

/* Advanced grid layouts */
.dashboard-grid {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
    padding: 20px;
}

.dashboard-card {
    grid-column: span 1;
    background: var(--bg-secondary);
    border-radius: 12px;
    padding: 20px;
    box-shadow: 0 2px 8px var(--shadow-color);
}

.dashboard-card.featured {
    grid-column: span 2;
}

@media (max-width: 768px) {
    .dashboard-card.featured {
        grid-column: span 1;
    }
}

3. CSS Custom Properties with JavaScript

/* Dynamic theming with CSS variables */
:root {
    --custom-accent: #5856d6;
    --custom-accent-hover: #4644c0;
}

.custom-theme {
    --accent-color: var(--custom-accent);
    --accent-hover: var(--custom-accent-hover);
}

4. Advanced Selectors

/* Complex selectors for specific styling */
#sidebar .menu-item:not(.active):hover {
    background: var(--bg-hover);
    transform: translateX(5px);
}

.content-card > *:first-child {
    margin-top: 0;
}

.content-card > *:last-child {
    margin-bottom: 0;
}

/* Attribute selectors */
[data-status="success"] {
    border-left: 4px solid var(--success-color);
}

[data-status="error"] {
    border-left: 4px solid var(--danger-color);
}

5. CSS Functions and Calculations

/* Using CSS functions */
.responsive-text {
    font-size: clamp(14px, 2.5vw, 18px);
    line-height: calc(1.5em + 0.5vw);
}

.dynamic-spacing {
    padding: calc(1rem + 2vw);
    margin: calc(0.5rem + 1vw);
}

/* CSS custom properties with calculations */
:root {
    --base-size: 16px;
    --scale-factor: 1.2;
    --large-size: calc(var(--base-size) * var(--scale-factor));
}

Implementation Guide

Step 1: Access the Design Page

1. Log into CyberPanel
2. Navigate to Design in the sidebar
3. Scroll down to the Custom CSS section

Step 2: Add Your Custom CSS

1. Paste your custom CSS into the textarea
2. Click Save Changes
3. Refresh the page to see your changes

Step 3: Test Your Changes

1. Test in both light and dark modes
2. Test on different screen sizes
3. Verify all interactive elements work correctly

Step 4: Iterate and Refine

1. Make adjustments as needed
2. Test thoroughly before finalizing
3. Document your customizations

Example: Complete Custom Theme

Here's a complete example of a custom theme that you can use as a starting point:

/* Custom CyberPanel Theme - Ocean Blue */

/* Light Theme */
:root {
    --bg-primary: #f0f9ff;
    --bg-secondary: #ffffff;
    --bg-sidebar: #e0f2fe;
    --bg-sidebar-item: #ffffff;
    --bg-hover: #bae6fd;
    --text-primary: #0c4a6e;
    --text-secondary: #0369a1;
    --text-heading: #0c4a6e;
    --border-color: #bae6fd;
    --shadow-color: rgba(6, 105, 161, 0.1);
    --accent-color: #0284c7;
    --accent-hover: #0369a1;
    --danger-color: #dc2626;
    --success-color: #059669;
    --warning-bg: linear-gradient(135deg, #fef3c7 0%, #fde68a 100%);
    --ai-banner-bg: linear-gradient(135deg, #0284c7 0%, #0369a1 50%, #0c4a6e 100%);
}

/* Dark Theme */
[data-theme="dark"] {
    --bg-primary: #0c4a6e;
    --bg-secondary: #075985;
    --bg-sidebar: #0c4a6e;
    --bg-sidebar-item: #075985;
    --bg-hover: #0369a1;
    --text-primary: #e0f2fe;
    --text-secondary: #bae6fd;
    --text-heading: #f0f9ff;
    --border-color: #0369a1;
    --shadow-color: rgba(0, 0, 0, 0.3);
    --accent-color: #38bdf8;
    --accent-hover: #0ea5e9;
    --danger-color: #f87171;
    --success-color: #34d399;
    --warning-bg: linear-gradient(135deg, #78350f 0%, #92400e 100%);
    --ai-banner-bg: linear-gradient(135deg, #0c4a6e 0%, #075985 50%, #0369a1 100%);
}

/* Custom Header Styling */
#header {
    background: linear-gradient(135deg, var(--accent-color), var(--accent-hover));
    box-shadow: 0 4px 20px var(--shadow-color);
}

#header .logo-text .brand {
    color: white;
    text-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

/* Custom Sidebar Styling */
#sidebar {
    background: linear-gradient(180deg, var(--bg-sidebar), var(--bg-secondary));
    border-right: 3px solid var(--accent-color);
}

#sidebar .menu-item {
    border-radius: 12px;
    margin: 4px 20px;
    transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}

#sidebar .menu-item:hover {
    transform: translateX(8px);
    box-shadow: 0 4px 15px var(--shadow-color);
}

#sidebar .menu-item.active {
    background: linear-gradient(135deg, var(--accent-color), var(--accent-hover));
    box-shadow: 0 4px 15px rgba(2, 132, 199, 0.3);
}

/* Custom Content Cards */
.content-card {
    background: var(--bg-secondary);
    border-radius: 16px;
    box-shadow: 0 4px 20px var(--shadow-color);
    border: 1px solid var(--border-color);
    position: relative;
    overflow: hidden;
}

.content-card::before {
    content: '';
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    height: 4px;
    background: linear-gradient(90deg, var(--accent-color), var(--accent-hover));
}

/* Custom Buttons */
.btn {
    border-radius: 12px;
    font-weight: 600;
    text-transform: uppercase;
    letter-spacing: 0.5px;
    transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}

.btn-primary {
    background: linear-gradient(135deg, var(--accent-color), var(--accent-hover));
    box-shadow: 0 4px 15px rgba(2, 132, 199, 0.3);
}

.btn-primary:hover {
    transform: translateY(-2px);
    box-shadow: 0 6px 20px rgba(2, 132, 199, 0.4);
}

/* Custom Form Elements */
.form-control {
    border: 2px solid var(--border-color);
    border-radius: 12px;
    transition: all 0.3s ease;
}

.form-control:focus {
    border-color: var(--accent-color);
    box-shadow: 0 0 0 4px rgba(2, 132, 199, 0.1);
    transform: translateY(-1px);
}

/* Custom Animations */
@keyframes slideIn {
    from {
        opacity: 0;
        transform: translateY(20px);
    }
    to {
        opacity: 1;
        transform: translateY(0);
    }
}

.content-card {
    animation: slideIn 0.5s ease-out;
}

/* Responsive Design */
@media (max-width: 768px) {
    #sidebar {
        width: 100%;
        height: auto;
        position: relative;
    }
    
    #header {
        left: 0;
    }
    
    .content-card {
        margin: 10px;
        padding: 20px;
    }
}

This guide provides everything you need to create beautiful, functional custom CSS for CyberPanel 2.5.5+. Remember to always test your changes thoroughly and use the CSS variables for consistency across themes.