Branding & Theming - Nudj Platform Documentation

Overview

The Nudj platform provides extensive branding and theming capabilities that enable complete visual customization of your community platform. From colors and logos to fonts and layouts, you can create a fully white-labeled experience that aligns with your brand identity.

Key Capabilities

Visual Identity - Complete logo, color, and typography control
Dual-Mode Theming - Full light and dark mode support
Component Customization - Granular control over UI elements
Mobile Optimization - Responsive design considerations
Real-Time Preview - Live theme updates without page refresh
Version Management - Theme versioning and rollback capabilities

Accessing Branding Settings

Navigate to your branding configuration:

Go to Admin → Settings → Organisation
Click the Branding tab
Configure your visual identity settings

Theme changes apply immediately across your platform. The system uses real-time updates via React context for instant preview without page refresh.

Core Branding Elements

Logo Management

Configure your organization’s visual identity:

Primary Logo
Dark Mode Logo
Favicon

Main Logo Configuration:

Format: SVG, PNG, JPG (SVG recommended)
Max Size: 5MB per file
Dimensions: Recommended 200x50px minimum
Usage: Header, login page, emails

{
  primaryLogo: {
    url: string;
    alt: string;
    width?: number;
    height?: number;
  }
}

Color Schemes

Define your brand’s color palette:

{
  light: {
    primary: "#1e40af",        // Primary brand color
    secondary: "#64748b",      // Secondary actions
    accent: "#f59e0b",         // Highlights/CTAs
    background: "#ffffff",     // Main background
    surface: "#f8fafc",        // Card backgrounds
    text: {
      primary: "#0f172a",      // Main text
      secondary: "#64748b",    // Muted text
      inverse: "#ffffff"       // Text on dark backgrounds
    },
    border: "#e2e8f0",         // Border colors
    error: "#dc2626",          // Error states
    warning: "#f59e0b",        // Warning states
    success: "#16a34a",        // Success states
    info: "#0ea5e9"            // Info states
  }
}

Typography

Customize fonts and text styles:

{
  typography: {
    fonts: {
      heading: "Inter, system-ui, sans-serif",
      body: "Inter, system-ui, sans-serif",
      mono: "JetBrains Mono, monospace"
    },
    sizes: {
      xs: "0.75rem",     // 12px
      sm: "0.875rem",    // 14px
      base: "1rem",      // 16px
      lg: "1.125rem",    // 18px
      xl: "1.25rem",     // 20px
      "2xl": "1.5rem",   // 24px
      "3xl": "1.875rem", // 30px
      "4xl": "2.25rem",  // 36px
      "5xl": "3rem"      // 48px
    },
    weights: {
      normal: 400,
      medium: 500,
      semibold: 600,
      bold: 700
    },
    lineHeights: {
      tight: 1.2,
      normal: 1.5,
      relaxed: 1.75
    }
  }
}

Advanced Customization

Component Styling

Override specific component styles:

Button Styles

{
  buttons: {
    borderRadius: "0.375rem",
    padding: {
      sm: "0.5rem 1rem",
      md: "0.625rem 1.25rem",
      lg: "0.75rem 1.5rem"
    },
    transitions: "all 0.2s ease-in-out"
  }
}

Card Styles

{
  cards: {
    borderRadius: "0.5rem",
    shadow: "0 1px 3px rgba(0,0,0,0.1)",
    padding: "1.5rem",
    border: "1px solid var(--border)"
  }
}

Navigation Styles

Form Elements

{
  forms: {
    inputBorderRadius: "0.375rem",
    inputPadding: "0.625rem 0.75rem",
    labelMarginBottom: "0.5rem",
    focusRingColor: "var(--primary)"
  }
}

Custom CSS

Add custom CSS for advanced styling:

/* Custom CSS Editor */
.custom-class {
  /* Your custom styles */
}

/* Override existing styles */
:root {
  --custom-variable: value;
}

/* Target specific components */
[data-component="challenge-card"] {
  /* Component-specific overrides */
}

Custom CSS is powerful but use sparingly. Excessive custom CSS can break responsive design and cause maintenance issues.

Icon Customization

Configure custom icons using Iconify:

{
  icons: {
    // Custom icon mappings
    achievement: "mdi:trophy",
    challenge: "mdi:target",
    reward: "mdi:gift",
    leaderboard: "mdi:podium",
    
    // Override system icons
    chevronDown: "custom:chevron-down",
    close: "custom:close-icon",
    menu: "custom:hamburger"
  }
}

Theme Application

Where Themes Apply

Your branding configuration affects:

User Interface

Main application
Login/signup pages
User profiles
Community pages

Communications

Email templates
Push notifications
In-app messages
PDF exports

Mobile Experience

Responsive web
PWA appearance
Mobile navigation
Touch interfaces

Embedded Content

Widgets
Iframe embeds
API responses
Share cards

Theme Inheritance

Understanding theme cascading:

Implementation Guide

Setting Up Your Brand

Upload Assets

Upload logos, favicon, and any custom images

Define Colors

Set primary, secondary, and accent colors for both light and dark modes

Configure Typography

Choose fonts and set size scales

Test Responsiveness

Preview on different screen sizes

Apply Custom CSS

Add any additional styling requirements

Save and Publish

Save configuration and publish to all users

Best Practices

Contrast Ratios

Maintain WCAG AA compliance (4.5:1 for normal text)

Brand Consistency

Use your brand guidelines for color and typography

Performance

Optimize images and limit custom fonts

Testing

Test themes across devices and browsers

Theme Management

Version Control

Track and manage theme versions:

{
  version: "2.1.0",
  createdAt: "2024-01-15T10:00:00Z",
  updatedAt: "2024-01-20T14:30:00Z",
  author: "admin@company.com",
  changelog: "Updated primary colors and navigation styles"
}

Import/Export

Share themes across organizations:

curl -X GET https://your-subdomain.nudj.cx/api/v2/admin/themes/export \
  -H "x-api-token: YOUR_API_TOKEN" \
  -o theme-export.json

Theme Preview

Test themes before publishing:

// Enable preview mode
{
  previewMode: true,
  previewUsers: ["user1@example.com", "user2@example.com"],
  previewExpiry: "2024-02-01T00:00:00Z"
}

Performance Considerations

Optimization Tips

Aspect	Recommendation	Impact
Images	Use SVG for logos, optimize PNGs	Faster load times
Fonts	Limit to 2-3 font families	Reduced bandwidth
Colors	Use CSS variables	Efficient theming
Custom CSS	Minimize specificity	Better maintainability
Icons	Use icon fonts or SVGs	Smaller file sizes

Caching Strategy

Theme assets are cached with these policies:

Static Assets: 1 year cache with versioning
Theme Config: 5 minute cache for updates
Custom CSS: Real-time updates
Fonts: Browser cache with preloading

Troubleshooting

Logo not appearing

Check file format and size limits
Verify URL is accessible
Clear browser cache
Check console for loading errors

Colors not updating

Ensure valid hex color codes
Check for CSS specificity conflicts
Verify theme is published
Try hard refresh (Ctrl+Shift+R)

Dark mode issues

Verify dark mode colors are configured
Check system theme detection
Test manual theme toggle
Ensure sufficient contrast ratios

Custom CSS not working

Check CSS syntax validity
Avoid !important unless necessary
Use specific selectors
Test in browser dev tools first

Font loading problems

Verify font URLs are valid
Check CORS headers for external fonts
Use web-safe fallback fonts
Consider self-hosting fonts

API Reference

Theme Endpoints

curl -X GET https://your-subdomain.nudj.cx/api/v2/admin/themes \
  -H "x-api-token: YOUR_API_TOKEN"

Security Considerations

SVG Sanitization

All SVG uploads are sanitized to prevent XSS attacks:

Script tags removed
Event handlers stripped
External references blocked
Safe attributes whitelist applied

Permission Controls

Theme management requires admin permissions:

View: All authenticated users
Edit: Admin role required
Publish: Organization owner only
Custom CSS: Super admin approval

Feature Flags

Control feature visibility

White Label Guide

Complete white-label setup

Email Templates

Customize email branding

Custom Domains

Set up custom domains

Getting Started

Dashboard & People

Core Engagement Features

Gamification System

Organization Settings

Advanced Features & Workflows

​Overview

Key Capabilities

​Accessing Branding Settings

​Core Branding Elements

​Logo Management

​Color Schemes

​Typography

​Advanced Customization

​Component Styling

​Custom CSS

​Icon Customization

​Theme Application

​Where Themes Apply

User Interface

Communications

Mobile Experience

Embedded Content

​Theme Inheritance

​Implementation Guide

​Setting Up Your Brand

​Best Practices

Contrast Ratios

Brand Consistency

Performance

Testing

​Theme Management

​Version Control

​Import/Export

​Theme Preview

​Performance Considerations

​Optimization Tips

​Caching Strategy

​Troubleshooting

​API Reference

​Theme Endpoints

​Security Considerations

​SVG Sanitization

​Permission Controls

​Related Resources

Feature Flags

White Label Guide

Email Templates

Custom Domains

Overview

Accessing Branding Settings

Core Branding Elements

Logo Management

Color Schemes

Typography

Advanced Customization

Component Styling

Custom CSS

Icon Customization

Theme Application

Where Themes Apply

Theme Inheritance

Implementation Guide

Setting Up Your Brand

Best Practices

Theme Management

Version Control

Import/Export

Theme Preview

Performance Considerations

Optimization Tips

Caching Strategy

Troubleshooting

API Reference

Theme Endpoints

Security Considerations

SVG Sanitization

Permission Controls

Related Resources