Theme Color Customization

Converge provides built-in light and dark themes that you can customize by overriding CSS variables. The framework automatically handles theme switching and applies your customizations to both modes.

You may customize your docs design using the theme() function directly on the module:

use Converge\Module;
use Converge\Support\Themes;

public function module(Module $module): Module
{
    return $module
        ...
        ->theme(
            Themes::overrideDark([
                '--color-base-200' => 'black',
                '--text-base' => '.94rem',
            ]),
            Themes::overrideLight([
                '--color-base-200' => 'white',
                '--text-base' => '.94rem',
            ])
        )
        ...
}

Alternatively, you may extract your theme configuration into a separate method for better organization:

use Converge\Theme\Theme;
use Converge\Support\Themes;

public function module(Module $module): Module
{
    return $module
        ...
        ->theme(fn(Theme $theme) => $this->theme($theme))
        ...
}

private function theme(Theme $theme)
{
    return $theme
        ->theme(
            Themes::overrideDark([
                '--color-base-200' => 'black',
                '--text-base' => '.94rem',
                '--text-sm' => '.9rem',
            ]),
            Themes::overrideLight([
                '--color-base-200' => 'white',
                '--text-base' => '.94rem',
                '--text-sm' => '.9rem',
            ])
        );
}

Available CSS Variables

Converge theming is based on CSS custom properties. You may override any of the following variables to customize your documentation's appearance:

Available Override Methods

You have several options for customizing your theme configuration depending on your needs.

Dark Theme Only

When you need to customize only the dark mode appearance, use Themes::overrideDark() to maintain the default light theme while personalizing the dark experience:

->theme(
    Themes::overrideDark([
        '--color-base-100' => '#1a1a1a',
        '--color-primary' => '#00BCFF',
        '--text-base' => '1rem',
    ])
)

This approach is particularly useful when your brand colors work well with the default light theme but need adjustment for dark mode readability.

Light Theme Only

For projects that primarily use light mode or need specific light theme adjustments, you may customize only the light theme while preserving the dark theme defaults:

->theme(
    null, // Keep default dark theme
    Themes::overrideLight([
        '--color-base-100' => '#ffffff',
        '--color-primary' => '#2563eb',
        '--text-base' => '1rem',
    ])
)

This is especially effective for corporate documentation where light mode is predominant but you still want to offer a polished dark mode experience.

Both Themes

When you want consistent styling across both light and dark modes, use Themes::override() to apply the same customizations universally:

->theme(
    Themes::override([
        '--text-base' => '1rem',
        '--border' => '2px',
        '--radius-box' => '0.5rem',
    ])
)

This method is ideal for typography adjustments, spacing modifications, or border radius changes that should remain consistent regardless of the selected theme.

Practical Examples

Here are some real-world theme configurations that demonstrate common customization patterns.

Custom Brand Theme

Perfect for companies wanting to align their documentation with their brand identity. This configuration applies consistent brand colors while maintaining excellent readability across both themes:

->theme(
    Themes::overrideDark([
        '--color-primary' => '#ff6b35',
        '--color-accent' => '#f7931e',
        '--color-base-200' => '#0d1117',
        '--text-base' => '1rem',
    ]),
    Themes::overrideLight([
        '--color-primary' => '#d63384',
        '--color-accent' => '#fd7e14',
        '--color-base-200' => '#f8f9fa',
        '--text-base' => '1rem',
    ])
)

The different primary colors ensure optimal contrast in each mode while maintaining brand recognition.

Color Format Support

Converge supports multiple color formats:

• Hex: #00BCFF, #ffffff
• OKLCH: oklch(68% 0.169 237.323) (recommended for consistency)
• RGB: rgb(0, 188, 255)
• HSL: hsl(195, 100%, 50%)