Color Library

Comprehensive color and theme management system for the Lilia framework.

---

Overview

The color library provides comprehensive functionality for managing colors and themes in the Lilia framework. It handles color registration, theme management, color manipulation, and smooth theme transitions. The library operates primarily on the client side, with theme registration available on both server and client. It includes predefined color names, theme switching capabilities, color adjustment functions, and smooth animated transitions between themes. The library ensures consistent color usage across the entire gamemode interface and provides tools for creating custom themes and color schemes.

---

lia.color.register(name, color)

Register a named color so string-based Color() calls can resolve it.

During client initialization or when adding palette entries at runtime.

Parameters:

string name Identifier stored in lowercase.

table|Color color Table or Color with r, g, b, a fields.

Example Usage:

    lia.color.register("warning", Color(255, 140, 0))
    local c = Color("warning")

---

lia.color.adjust(color, aOffset)

Apply additive offsets to a color to quickly tint or shade it.

While building UI states (hover/pressed) or computing theme variants.

Parameters:

Color color Base color.

number aOffset optional Optional alpha offset; defaults to 0.

Returns:

Color Adjusted color.

Example Usage:

    local base = lia.color.getMainColor()
    button:SetTextColor(lia.color.adjust(base, -40, -20, -60))

---

lia.color.darken(color, factor)

Darken a color by a fractional factor.

Deriving hover/pressed backgrounds from a base accent color.

Parameters:

Color color Base color to darken.

number factor optional Amount between 0-1; defaults to 0.1 and is clamped.

Returns:

Color Darkened color.

Example Usage:

    local accent = lia.color.getMainColor()
    local pressed = lia.color.darken(accent, 0.2)

---

lia.color.getCurrentTheme()

Get the active theme id from config in lowercase.

Before looking up theme tables or theme-specific assets.

Returns:

string Lowercased theme id (default "teal").

Example Usage:

    if lia.color.getCurrentTheme() == "dark" then
        panel:SetDarkMode(true)
    end

---

lia.color.getCurrentThemeName()

Get the display name of the currently selected theme.

Showing UI labels or logs about the active theme.

Returns:

string Theme name from config with original casing.

Example Usage:

    chat.AddText(Color(180, 220, 255), "Theme: ", lia.color.getCurrentThemeName())

---

lia.color.getMainColor()

Fetch the main color from the current theme with sensible fallbacks.

Setting accent colors for buttons, bars, and highlights.

Returns:

Color Main theme color, falling back to the default theme or teal.

Example Usage:

    local accent = lia.color.getMainColor()
    button:SetTextColor(accent)

---

lia.color.applyTheme(themeName, useTransition)

Apply a theme immediately or begin a smooth transition toward it, falling back to Teal/default palettes and firing OnThemeChanged after updates.

On config changes, theme selection menus, or client startup.

Parameters:

string themeName optional Target theme id; defaults to the current config value.

boolean useTransition optional If true, blends colors over time instead of swapping instantly.

Example Usage:

    concommand.Add("lia_theme_preview", function(_, _, args)
        lia.color.applyTheme(args[1] or "Teal", true)
    end)

---

lia.color.isTransitionActive()

Check whether a theme transition is currently blending.

To avoid overlapping transitions or to gate UI animations.

Returns:

boolean True if a transition is active, otherwise false.

Example Usage:

    if lia.color.isTransitionActive() then return end
    lia.color.applyTheme("Dark", true)

---

lia.color.testThemeTransition(themeName)

Convenience wrapper to start a theme transition immediately.

From theme preview buttons to animate a swap.

Parameters:

string themeName Target theme id.

Example Usage:

    vgui.Create("DButton").DoClick = function()
        lia.color.testThemeTransition("Red")
    end

---

lia.color.startThemeTransition(name)

Begin blending from the current palette toward a target theme, falling back to Teal when missing and finishing by firing OnThemeChanged once applied.

Inside applyTheme when transitions are enabled or via previews.

Parameters:

string name Theme id to blend toward.

Example Usage:

    lia.color.transition.speed = 1.5
    lia.color.startThemeTransition("Ice")

---

lia.color.isColor(v)

Determine whether a value resembles a Color table.

While blending themes to decide how to lerp entries.

Parameters:

any v Value to test.

Returns:

boolean True when v has numeric r, g, b, a fields.

Example Usage:

    if lia.color.isColor(entry) then
        panel:SetTextColor(entry)
    end

---

lia.color.calculateNegativeColor(mainColor)

Build a readable contrasting color (alpha 255) based on a main color.

Choosing text or negative colors for overlays and highlights.

Parameters:

Color mainColor optional Defaults to the current theme main color when nil.

Returns:

Color Contrasting color tuned for readability.

Example Usage:

    local negative = lia.color.calculateNegativeColor()
    frame:SetTextColor(negative)

---

lia.color.returnMainAdjustedColors()

Derive a suite of adjusted colors from the main theme color, including brightness-aware text and a calculated negative color.

Building consistent palettes for backgrounds, accents, and text.

Returns:

table Contains background, sidebar, accent, text, hover, border, highlight, negative.

Example Usage:

    local palette = lia.color.returnMainAdjustedColors()
    panel:SetBGColor(palette.background)
    panel:SetTextColor(palette.text)

---

lia.color.lerp(frac, col1, col2)

FrameTime-scaled color lerp helper.

Theme transitions or animated highlights needing smooth color changes.

Parameters:

number frac Multiplier applied to FrameTime for lerp speed.

Color col1 Source color; defaults to white when nil.

Color col2 Target color; defaults to white when nil.

Returns:

Color Interpolated color.

Example Usage:

    local blink = lia.color.lerp(6, Color(255, 0, 0), Color(255, 255, 255))
    panel:SetBorderColor(blink)

---

lia.color.registerTheme(name, themeData)

Register a theme table by name for later selection.

During initialization to expose custom palettes.

Parameters:

string name Theme name/id; stored in lowercase.

table themeData Map of color keys to Color values or arrays.

Example Usage:

    lia.color.registerTheme("MyStudio", {
        maincolor = Color(120, 200, 255),
        background = Color(20, 24, 32),
        text = Color(230, 240, 255)
    })

---

lia.color.getAllThemes()

Return a sorted list of available theme ids.

To populate config dropdowns or theme selection menus.

Returns:

table Sorted array of theme ids.

Example Usage:

    local options = {}
    for _, id in ipairs(lia.color.getAllThemes()) do
        options[#options + 1] = id
    end

---