​
Theming Basics

Before diving into specific customization approaches, it’s important to understand the core concepts that power social.plus UIKit’s theming system. These fundamentals apply whether you’re using Dynamic UI, Component Styling, or Fork & Extend.

​
Understanding UIKit Customization Levels

1. Dynamic UI

Configuration-based
  • Single config.json file
  • Real-time updates
  • Perfect for brand consistency

2. Component Styling

Code-based styling
  • CSS and style overrides
  • Granular component control
  • Advanced theming options

3. Fork & Extend

Source code access
  • Complete customization freedom
  • Custom layouts and workflows
  • Full development control

​
Core Theming Concepts

All UIKit customization levels share these fundamental concepts:

​
1. Configuration-Driven Design

social.plus UIKit uses a JSON-based configuration system that controls appearance and behavior: 
{
  "preferred_theme": "default",
  "theme": {
    "light": {
      "primary_color": "#1054DE",
      "secondary_color": "#292B32",
      "base_color": "#292b32",
      "base_shade1_color": "#636878",
      "base_shade2_color": "#898e9e",
      "base_shade3_color": "#a5a9b5",
      "base_shade4_color": "#ebecef",
      "alert_color": "#FA4D30",
      "background_color": "#FFFFFF"
    },
    "dark": {
      "primary_color": "#1054DE",
      "secondary_color": "#292B32",
      "base_color": "#ebecef",
      "base_shade1_color": "#a5a9b5",
      "base_shade2_color": "#6e7487",
      "base_shade3_color": "#40434e",
      "base_shade4_color": "#292b32",
      "alert_color": "#FA4D30",
      "background_color": "#191919"
    }
  },
  "excludes": [],
  "customizations": {
    "select_target_page/*/*": {
      "page_theme": {
        "light_theme": {
          "primary_color": "#1D1234",
          "secondary_color": "#AB1234"
        }
      },
      "title": "Share to"
    }
  }
}

​
Theme Structure

The configuration file is organized into several key sections:

Theme Selection

preferred_theme - Sets the default theme mode

Color Schemes

theme - Defines light and dark color palettes

Exclusions

excludes - Components to exclude from the app

Customizations

customizations - Specific component modifications

​
Color System

The UIKit uses a systematic color approach with semantic naming:

​
Light and Dark Themes

The UIKit automatically supports both light and dark themes. Each theme has its own color palette: 
"light": {
  "primary_color": "#1054DE",
  "secondary_color": "#292B32",
  "base_color": "#292b32",
  "base_shade1_color": "#636878",
  "base_shade2_color": "#898e9e",
  "base_shade3_color": "#a5a9b5",
  "base_shade4_color": "#ebecef",
  "alert_color": "#FA4D30",
  "background_color": "#FFFFFF"
}
The color values automatically reverse between light and dark themes. For example, base_color is dark in light theme and light in dark theme.

​
Theme Selection

You can control which theme is used by default: 
{
  "preferred_theme": "default" // Uses system preference
  // or
  "preferred_theme": "light"   // Forces light theme
  // or
  "preferred_theme": "dark"    // Forces dark theme
}
Setting preferred_theme to "default" will respect the user’s system theme preference and automatically switch between light and dark modes.

​
Component Exclusions

Remove specific components from your app by adding them to the excludes array: 
{
  "excludes": [
    "story",
    "live_stream",
    "community_creation"
  ]
}
Excluding core components may affect the functionality of related features. Test thoroughly after excluding components.

​
Custom Component Styling

Target specific components for customization using the customizations object: 
{
  "customizations": {
    "social_home_page/*/*": {
      "page_theme": {
        "light_theme": {
          "background_color": "#F8F9FA"
        }
      }
    },
    "post_detail_page/*/reaction_button": {
      "config": {
        "reaction_enabled": false
      }
    }
  }
}

​
Targeting Components

Use the component path structure to target specific elements:
  • page_name/*/* - Target all instances of a page
  • page_name/*/component_name - Target specific components on a page
  • */*/* - Target all components globally

​
Best Practices

Consistency

Maintain color consistency between light and dark themes

Accessibility

Ensure sufficient contrast ratios for text readability

Testing

Test your themes on different devices and screen sizes

Branding

Align colors with your brand guidelines

​
Color Guidelines

1

Choose Your Primary Color

Select a primary color that represents your brand
2

Create Supporting Colors

Define secondary and accent colors that complement your primary
3

Test Accessibility

Ensure proper contrast ratios (4.5:1 for normal text, 3:1 for large text)
4

Create Dark Variants

Adapt your colors for dark theme compatibility

​
Next Steps

Dynamic UI

Learn about real-time customization updates

Component Styling

Explore specific component customization options