Use relative colors

Use a concrete relative color when the origin is known now. Use a deferred relative expression when the origin comes from a variable or currentColor. The channel expressions can be identical; the availability of the origin chooses the API.

Origin	Entry point	Result
Concrete CSS color	`Color::parse()`	Concrete color immediately
Variable or contextual expression	`CssColor::relative()`	Deferred expression
Deferred origin plus complete context	`CssColor::resolve()`	Concrete color

Create a relative color expression

Use CssColor::relative() to defer a relative color until its origin resolves:

use PhpColor\Color\Css\CssColor;
use PhpColor\Color\Css\CssContext;

$expression = CssColor::relative(
    targetSpace: 'oklch',
    origin: 'var(--brand)',
    channels: [
        'l' => 'calc(l + 0.08)',
        'c' => 'c',
        'h' => 'h',
    ],
    alpha: 'alpha',
);

$color = CssColor::resolve(
    $expression,
    new CssContext(['--brand' => '#2563eb']),
);

echo $expression->toCss().PHP_EOL;
echo $color->toHex().PHP_EOL;

The output is:

oklch(from var(--brand) calc(l + 0.08) c h / alpha)
#3d7dff

The array’s insertion order determines the emitted channel order. Supply exactly the channels expected by the target function and keep them in canonical order. For Oklch that is lightness, chroma, then hue.

After resolving the origin, RelativeColor constructs relative CSS syntax and passes it to PHPColor’s concrete CSS parser. Missing channels, unsupported spaces, invalid channel expressions, and invalid calc() expressions are wrapped in PhpColor\Color\Css\Exception\CssResolutionException.

CssColor::from() is an alias of relative().

Parse an immediately resolvable relative color

When the origin is already concrete, Color::parse() can evaluate relative color syntax directly:

use PhpColor\Color\Color;

$lighter = Color::parse(
    'oklch(from #2563eb calc(l + 0.08) c h)',
);

Within calc(), PHPColor supports numeric arithmetic with +, -, *, /, parentheses, percentages, and the source channel names. Division by zero, unknown variables, malformed expressions, and an incorrect channel count cause a parse exception.

Use the concrete form when all inputs are known now. Use CssColor::relative() when the origin depends on var() or currentColor.

Relative colors preserve a relationship, not an accessibility guarantee. Recheck gamut and contrast after resolving and serializing the result.

Continue with Build resolution contexts, Build CSS relative colors, or RelativeColor.