app.color - Color Utility API

Color format conversion, blending, contrast calculation, and color picking.

Methods

app.color.parse(str)

Parses a color string.

Parameters:

• str (string) - Color string, supported formats:
  • "#RGB" - 3-digit hex
  • "#RRGGBB" - 6-digit hex
  • "#RRGGBBAA" - 8-digit hex (with alpha)
  • "rgb(r, g, b)" - RGB function
  • "rgba(r, g, b, a)" - RGBA function

Returns: table, error - {r, g, b, a, hex}

local c = app.color.parse("#FF6600")
-- c = {r=255, g=102, b=0, a=1.0, hex="#FF6600"}

local c = app.color.parse("rgb(100, 200, 50)")
-- c = {r=100, g=200, b=50, a=1.0, hex="#64C832"}

app.color.hex(r, g, b)

Converts RGB values to a hex string.

Parameters:

• r (number) - Red (0-255)
• g (number) - Green (0-255)
• b (number) - Blue (0-255)

Returns: string - e.g. "#FF6600"

local hex = app.color.hex(255, 102, 0)  -- "#FF6600"

app.color.rgb(hex)

Converts a hex string to RGB.

Parameters:

• hex (string) - Hex color

Returns: table, error - {r, g, b, a}

local c = app.color.rgb("#FF6600")
-- c = {r=255, g=102, b=0, a=1.0}

app.color.hsl(r, g, b)

Converts RGB to HSL.

Parameters:

• r, g, b (number) - RGB values (0-255)

Returns: table, error - {h, s, l} (h: 0-360, s: 0-100, l: 0-100)

local hsl = app.color.hsl(255, 0, 0)
-- hsl = {h=0, s=100, l=50}

app.color.hsv(r, g, b)

Converts RGB to HSV.

Parameters:

• r, g, b (number) - RGB values (0-255)

Returns: table, error - {h, s, v} (h: 0-360, s: 0-100, v: 0-100)

local hsv = app.color.hsv(255, 0, 0)
-- hsv = {h=0, s=100, v=100}

app.color.fromHSL(h, s, l)

Converts HSL to RGB.

Parameters:

• h (number) - Hue (0-360)
• s (number) - Saturation (0-100)
• l (number) - Lightness (0-100)

Returns: table - {r, g, b, hex}

local c = app.color.fromHSL(0, 100, 50)
-- c = {r=255, g=0, b=0, hex="#FF0000"}

app.color.fromHSV(h, s, v)

Converts HSV to RGB.

Parameters:

• h (number) - Hue (0-360)
• s (number) - Saturation (0-100)
• v (number) - Value (0-100)

Returns: table - {r, g, b, hex}

local c = app.color.fromHSV(120, 100, 100)
-- c = {r=0, g=255, b=0, hex="#00FF00"}

app.color.blend(color1, color2, ratio?)

Blends two colors.

Parameters:

• color1 (string) - First color (hex)
• color2 (string) - Second color (hex)
• ratio (number, optional) - Blend ratio (0-100), default 50

Returns: table, error - {r, g, b, hex}

local c = app.color.blend("#FF0000", "#0000FF")
-- 50% blend → purple

local c = app.color.blend("#FF0000", "#0000FF", 25)
-- 25% toward blue

app.color.lighten(hex, amount?)

Lightens a color.

Parameters:

• hex (string) - Hex color
• amount (number, optional) - Lightening amount (0-100), default 10

Returns: string, error - New hex color

local lighter = app.color.lighten("#336699", 20)

app.color.darken(hex, amount?)

Darkens a color.

Parameters:

• hex (string) - Hex color
• amount (number, optional) - Darkening amount (0-100), default 10

Returns: string, error - New hex color

local darker = app.color.darken("#336699", 20)

app.color.contrast(hex1, hex2)

Calculates the WCAG 2.0 contrast ratio.

Parameters:

• hex1 (string) - First color
• hex2 (string) - Second color

Returns: number, error - Contrast ratio (1.0-21.0)

local ratio = app.color.contrast("#000000", "#FFFFFF")
-- ratio = 21.0 (maximum contrast)

local ratio = app.color.contrast("#336699", "#FFFFFF")
-- Use to check if WCAG AA standard is met (>= 4.5)

app.color.isLight(hex)

Determines whether a color is light.

Parameters:

• hex (string) - Hex color

Returns: boolean, error

app.color.isLight("#FFFFFF")  -- true
app.color.isLight("#000000")  -- false

app.color.pick()

Opens the system color picker.

Returns: table - {hex, r, g, b, a}, returns nil if the user cancels

local c = app.color.pick()
if c then
    app.log.info("Selected color: " .. c.hex)
end

Examples

Generate a color palette

function MyPlugin:handlePalette(context)
    local baseHex = "#3366CC"
    local palette = {baseHex}

    -- Generate 5 lighter shades
    for i = 1, 5 do
        table.insert(palette, app.color.lighten(baseHex, i * 10))
    end

    -- Generate 5 darker shades
    for i = 1, 5 do
        table.insert(palette, app.color.darken(baseHex, i * 10))
    end

    local result = "Palette:\n"
    for _, hex in ipairs(palette) do
        local c = app.color.rgb(hex)
        result = result .. hex .. "  rgb(" .. c.r .. "," .. c.g .. "," .. c.b .. ")\n"
    end

    app.dialog.alert("Palette", result)
end

Check text readability

function MyPlugin:handleCheckContrast(context)
    local bg = app.color.pick()
    if not bg then return end

    local fg = app.color.pick()
    if not fg then return end

    local ratio = app.color.contrast(bg.hex, fg.hex)
    local level = "Fail"
    if ratio >= 7 then level = "AAA"
    elseif ratio >= 4.5 then level = "AA"
    elseif ratio >= 3 then level = "AA (Large Text)"
    end

    app.dialog.alert("Contrast Check",
        "Foreground: " .. fg.hex .. "\n" ..
        "Background: " .. bg.hex .. "\n" ..
        "Contrast: " .. ratio .. ":1\n" ..
        "WCAG Level: " .. level
    )
end