v0.6.0

Theme Settings

Customize the appearance of your PteroCA panel including branding, colors, dark mode, and messaging.

Breadcrumb: System Configuration > Theme Settings

Overview

Theme Settings control the visual appearance and branding of your PteroCA panel:

  • Branding (logo and favicon)

  • Active theme selection

  • Color customization (light and dark modes)

  • Dark mode toggle options

  • Default color scheme

  • Customer dashboard messaging (MOTD)

These settings allow you to customize your panel's appearance to match your brand while providing users with theme preferences and important announcements.

Settings Overview

Setting
Type
CLI
Admin Panel
Description

Site Logo

Image

✓

Logo displayed in panel header

Site Favicon

Image

✓

Browser tab icon

Current Theme

Select

✓

Active theme template

Default Light Mode Color

Color

✓

Primary color for light mode

Default Dark Mode Color

Color

✓

Background color for dark mode

Disable Dark Mode

Boolean

✓

Hide dark mode toggle

Default Theme Mode

Select

✓

Default color scheme (light/dark/auto)

Customer MOTD Enabled

Boolean

✓

Enable Message of the Day banner

Customer MOTD Title

Text

✓

MOTD banner title

Customer MOTD Message

Twig

✓

MOTD content (supports Twig templates)

Note: Theme settings are only configurable via Admin Panel, not the CLI wizard.

Configuration via Admin Panel

All theme settings are managed through the Admin Panel.

Access Theme Settings

  1. Log in to the Admin Panel

  2. Navigate to Settings in the main menu

  3. Click Appearance

  4. Update values

  5. Click Save

  6. Refresh page to see changes

Setting Details

Setting Code: site_logo Field Type: Image Required: No Default: None (uses default PteroCA logo)

Logo image displayed in the panel header.

Recommended Specifications:

  • Format: PNG with transparency preferred (also supports JPG, SVG)

  • Dimensions: 200x50px (or similar aspect ratio 4:1)

  • File Size: < 500KB (smaller is better for performance)

  • Background: Transparent for best results

Upload Process:

  1. Navigate to Settings → Appearance

  2. Click "Choose File" for Site Logo

  3. Select image from your computer

  4. Click "Save"

  5. Logo appears immediately in header (refresh page)

Best Practices:

  • Use vector format (SVG) for scalability if supported

  • Export PNG at 2x resolution (400x100px) for HiDPI displays

  • Ensure good contrast with header background

  • Test on both light and dark modes

  • Keep file size small for faster loading

  • Use simple, clean design that scales well

Common Issues:

  • Logo too large/small: Adjust source image dimensions

  • Logo pixelated: Use higher resolution or vector format

  • Logo doesn't show: Clear browser cache (Ctrl+F5)

Site Favicon

Setting Code: site_favicon Field Type: Image Required: No Default: None (uses default PteroCA favicon)

Small icon displayed in browser tabs, bookmarks, and mobile home screens.

Recommended Specifications:

  • Format: ICO, PNG (32x32px or 16x16px)

  • Dimensions: 32x32px (standard) or 16x16px (minimal)

  • File Size: < 50KB

  • Design: Simple, recognizable at small size

Upload Process:

  1. Navigate to Settings → Appearance

  2. Click "Choose File" for Favicon

  3. Select favicon file

  4. Click "Save"

  5. Clear browser cache to see changes (Ctrl+F5)

Best Practices:

  • Use simple design (too much detail won't be visible)

  • Test at actual size (16x16px and 32x32px)

  • Use brand colors for recognition

  • Ensure visibility on light and dark browser themes

File Formats:

  • ICO: Traditional format, multi-size support

  • PNG: Modern, transparent background support

  • SVG: Scalable, not universally supported

Note: Browsers cache favicons aggressively. Users may need to hard refresh (Ctrl+Shift+R) or clear browser cache to see updated favicon.

Current Theme

Setting Code: current_theme Field Type: Select (Dropdown) Required: Yes Default: default

The active theme template for your panel.

Available Themes:

By default, PteroCA includes:

  • default - Standard PteroCA theme

Additional themes can be installed in the templates/themes/ directory.

Theme Structure:

Custom themes provide:

  • Layout templates (Twig files)

  • CSS stylesheets

  • JavaScript files

  • Asset files (images, fonts)

Installing Custom Themes:

  1. Download theme package

  2. Extract to templates/themes/[theme-name]/

  3. Ensure template.json exists

  4. Refresh this settings page

  5. Select theme from dropdown

  6. Save and refresh

Creating Custom Themes:

See Theme Development Guide for creating custom themes.

Theme Compatibility:

  • Themes must be compatible with current PteroCA version

  • Check theme documentation

  • Test thoroughly before deploying

Default Light Mode Color

Setting Code: theme_default_light_mode_color Field Type: Color Picker Required: Yes Default: #4e73df (blue)

Primary color used throughout the panel when in light mode.

Affects:

  • Buttons (primary action buttons)

  • Links

  • Active menu items

  • Progress bars

  • Badges

  • Icon highlights

  • Form focus states

Color Selection:

Click the color box to open color picker, or enter hex code directly:

Brand Matching:

To match your brand:

  1. Use your brand's primary color

  2. Test for sufficient contrast

  3. Verify readability on white backgrounds

  4. Check accessibility (WCAG guidelines)

Best Practices:

  1. Contrast:

    • Ensure text on colored backgrounds is readable

    • Use tools like WebAIM Contrast Checker

    • Aim for WCAG AA standard minimum

  2. Consistency:

    • Use similar hue for dark mode

    • Maintain brand identity

  3. Testing:

    • Test with different screen brightness

    • Check on multiple devices

    • Verify with color blindness simulators

Examples:

Brand Type
Color
Hex Code

Professional

Blue

#4e73df

Gaming

Red

#e74c3c

Eco-friendly

Green

#2ecc71

Creative

Purple

#9b59b6

Luxury

Gold

#f39c12

Default Dark Mode Color

Setting Code: theme_default_dark_mode_color Field Type: Color Picker Required: Yes Default: #2e59d9 (dark blue)

Background color for dark mode, affecting sidebar, content areas, and all backgrounds.

Affects:

  • Sidebar background

  • Content area backgrounds

  • Card backgrounds

  • Modal backgrounds

  • Dropdown backgrounds

  • All panel backgrounds in dark mode

Color Selection:

Relationship to Light Mode Color:

Typically a darker shade of your light mode color:

Best Practices:

  1. Not Too Bright:

    • Dark mode should reduce eye strain

    • Avoid pure colors

  2. Not Pure Black:

    • Pure black (#000000) can cause eye strain

    • Use dark grays or tinted blacks

    • Recommended: #1a1a1a to #2c3e50

  3. Sufficient Contrast:

    • Ensure text is readable

    • White text on dark backgrounds

    • Test with different brightness levels

  4. Brand Consistency:

    • Use shade of brand color

    • Maintains identity in dark mode

Testing:

  1. Enable dark mode

  2. Check readability of all text

  3. Verify contrast in different areas

  4. Test on multiple devices

Disable Dark Mode

Setting Code: theme_disable_dark_mode Field Type: Boolean (Toggle) Required: No Default: false

Hide the dark mode toggle from users, forcing light mode only.

When Enabled (Dark Mode Disabled):

  • Dark mode toggle hidden from UI

  • All users see light mode

  • No user preference saved

  • Simplified UI options

When Disabled (Dark Mode Enabled):

  • Users can toggle between light/dark

  • Preference saved per user

  • Sun/Moon icon visible in header

  • User choice respected

Use Cases for Disabling:

  1. Brand Consistency:

    • Brand guidelines require light mode

    • Dark theme not matching brand

    • Simplify visual identity

  2. Theme Limitations:

    • Custom theme lacks dark mode support

    • Dark mode has visual bugs

    • Incomplete dark mode implementation

  3. Accessibility:

    • Specific user requirements

    • Organization policy

    • Reduce UI complexity

User Impact:

  • Removes user choice

  • May impact user experience (some prefer dark mode)

  • Consider user feedback before disabling

Recommendation:

  • Keep dark mode enabled by default

  • Users appreciate choice

  • Dark mode reduces eye strain for many users

  • Modern expectation

Default Theme Mode

Setting Code: theme_default_mode Field Type: Select (Dropdown) Required: Yes Default: auto

Default color scheme for new users and guests.

Available Options:

Value
Description
Behavior

light

Always light

Force light mode for new users

dark

Always dark

Force dark mode for new users

auto

System preference

Match OS/browser dark mode setting

Option Details:

Light Mode:

Dark Mode:

Auto (Recommended):

Best Practices:

  1. Use Auto:

    • Respects user OS preference

    • Best user experience

    • Modern standard

  2. Force Light:

    • If dark mode has issues

    • Brand requires light mode

    • Temporary solution

  3. Force Dark:

    • Gaming/tech-focused audience

    • Dark-first branding

    • Specific use case

User Override:

Regardless of default:

  • Users can manually toggle mode

  • Preference saved in browser/account

  • Survives across sessions

Customer MOTD Enabled

Setting Code: customer_motd_enabled Field Type: Boolean (Toggle) Required: No Default: false

Enable or disable the Message of the Day banner on the customer dashboard.

When Enabled:

  • MOTD banner appears at top of client dashboard

  • Displays configured title and message

  • Visible to all logged-in users

  • Supports Twig templating for dynamic content

When Disabled:

  • No MOTD banner shown

  • Title and message still saved but not displayed

  • Clean dashboard without announcements

Use Cases:

  1. Announcements:

    • Maintenance windows

    • New features

    • System updates

    • Policy changes

  2. Promotions:

    • Special offers

    • Seasonal discounts

    • Referral programs

    • Limited-time deals

  3. Alerts:

    • Service disruptions

    • Emergency notifications

    • Important deadlines

    • Action required messages

  4. Information:

    • Support hours

    • Contact information

    • Documentation links

    • Community resources

Best Practices:

  • Update regularly to keep content fresh

  • Use for time-sensitive information

  • Keep messages concise and actionable

  • Test Twig templates before publishing

  • Disable when no active announcements

Customer MOTD Title

Setting Code: customer_motd_title Field Type: Text Required: Only if MOTD enabled Default: None Max Length: 255 characters

Title/heading displayed at the top of the MOTD banner.

Example Titles:

Best Practices:

  1. Be Clear and Direct:

    • Use action-oriented language

    • Indicate urgency if applicable

    • Be specific about topic

  2. Keep It Short:

    • Aim for 3-8 words

    • One line maximum

    • Mobile-friendly length

  3. Use Appropriate Tone:

    • Professional for business announcements

    • Friendly for welcome messages

    • Urgent for critical alerts

    • Exciting for promotions

Examples by Purpose:

Purpose
Title

Maintenance

Scheduled Maintenance - Dec 15

Feature

New Server Control Panel Released

Promotion

20% Off All Servers This Week

Alert

Action Required: Verify Email

Welcome

Welcome to GameHost Pro!

Customer MOTD Message

Setting Code: customer_motd_message Field Type: Twig Template (Textarea) Required: Only if MOTD enabled Default: None

The main content of the MOTD banner. Supports HTML formatting for rich content display.

HTML Example:

HTML Formatting:

Use standard HTML tags for formatting:

Best Practices:

  1. Keep It Concise:

    • 2-4 sentences maximum

    • One main message or call-to-action

    • Use bullet points for multiple items

  2. Make It Actionable:

    • Include clear next steps

    • Provide relevant links

    • Set expectations for timing

  3. Test Templates:

    • Verify Twig syntax before saving

    • Test with different user scenarios

    • Check HTML rendering

    • Ensure links work

  4. Accessibility:

    • Use semantic HTML

    • Provide alt text for images

    • Ensure sufficient color contrast

    • Keep language clear and simple

  5. Security:

    • Never include sensitive information

    • Avoid hardcoded credentials

    • Sanitize user-generated content

    • Use HTTPS for all links

Common Use Cases:

Maintenance Window:

Limited Promotion:

Feature Announcement:

Support Information:

Troubleshooting:

If MOTD not displaying:

  1. Ensure "Customer MOTD Enabled" is ON

  2. Clear application cache: php bin/console cache:clear

  3. Check for HTML syntax errors in message

  4. Verify user has access to dashboard

  5. Clear browser cache (Ctrl+F5)

Customization Guide

Brand Color Matching

To match your brand colors:

  1. Identify Brand Colors:

    • Primary: Your main brand color

    • Secondary: Accent color

    • Backgrounds: Light and dark variants

  2. Set Light Mode Color:

    • Use primary brand color

    • Must work on white/light backgrounds

    • Test contrast

  3. Set Dark Mode Color:

    • Use darker shade of brand color

    • Background, not accent

    • Test with white text

  4. Preview:

    • Toggle between modes

    • Check all pages

    • Verify consistency

Example Configurations

Professional Blue (Default):

Gaming Red:

Corporate Green:

Monochrome:

CSS Variable Customization

Theme colors are applied via CSS variables. Advanced users can further customize by adding CSS:

  1. Create custom CSS file

  2. Override CSS variables:

  1. Load custom CSS via theme or plugin

Best Practices

Color Selection

  1. Accessibility:

    • Use WCAG contrast checker

    • Aim for AA level minimum (4.5:1)

    • AAA level preferred (7:1)

  2. Brand Alignment:

    • Match official brand guidelines

    • Maintain visual identity

    • Use brand color palette

  3. User Testing:

    • Get feedback from users

    • Test with different demographics

    • Consider color blindness

Dark Mode

  1. Keep Enabled:

    • User preference matters

    • Improves accessibility

    • Modern standard

  2. Test Thoroughly:

    • Check all pages and components

    • Verify readability

    • Look for contrast issues

  3. Use Auto Default:

    • Respects OS preference

    • Better UX

    • Seamless experience

Theme Management

  1. Backup Before Changes:

    • Note current colors

    • Take screenshots

    • Document settings

  2. Test in Staging:

    • Test theme changes before production

    • Get team feedback

    • Verify compatibility

  3. Communicate Changes:

    • Notify users of major theme updates

    • Provide changelog

    • Allow feedback period

Troubleshooting

Colors Not Applying

Problem: Changed colors but panel looks the same

Causes:

  • Browser cache

  • CSS cache not cleared

  • Application cache

Solutions:

  1. Clear Browser Cache:

    • Hard refresh: Ctrl+Shift+R (Windows/Linux)

    • Hard refresh: Cmd+Shift+R (Mac)

    • Or use incognito mode

  2. Clear Application Cache:

  3. Clear CSS Cache:

    • If using CDN, purge cache

    • Wait a few minutes

Dark Mode Not Working

Problem: Dark mode toggle not appearing or not working

Causes:

  • Dark mode disabled in settings

  • JavaScript error

  • Theme incompatibility

Solutions:

  1. Check Settings:

    • Ensure "Disable Dark Mode" is OFF

    • Save settings

  2. Check Browser Console:

    • F12 → Console

    • Look for JavaScript errors

  3. Test Different Theme:

    • Switch to default theme

    • Check if dark mode works

  4. Clear Cache:

Contrast Issues

Problem: Text hard to read on colored backgrounds

Causes:

  • Insufficient contrast

  • Color choice

  • Accessibility issue

Solutions:

  1. Check Contrast:

    • Use WebAIM Contrast Checker

    • https://webaim.org/resources/contrastchecker/

  2. Adjust Colors:

    • Darken light mode color

    • Lighten dark mode color

    • Increase contrast ratio

  3. Test with Users:

    • Get feedback

    • Test with accessibility tools

    • Consider color blind users

Theme Installation Errors

Problem: Custom theme not appearing in dropdown

Causes:

  • Theme not in correct directory

  • Missing template.json

  • Permission issues

Solutions:

  1. Verify Directory:

  2. Check template.json:

  3. Check Permissions:

  4. Clear Cache:

Related Settings

Additional Resources

PreviousGeneral SettingsNextSecurity Settings

Last updated