Treat alpha as part of the color value when opacity must travel through parsing, transformation, storage, and output. Keep opacity outside the color only when another layer, component, or rendering system owns it independently.
Choose where opacity belongs
Alpha describes how a foreground participates in compositing. It does not make a color intrinsically lighter or darker, and it has no visible result until the foreground is placed over a backdrop.
| Situation | Useful representation | Why |
|---|---|---|
| A stored overlay token | Alpha on the color | The color and opacity form one reusable value |
| A component fades as a whole | Component opacity | Text, borders, and children fade together |
| Contrast must be measured | Color plus actual backdrop | The visible color depends on compositing order |
| A CSS token crosses systems | A syntax with explicit alpha | The receiving system can preserve the same value |
Supply alpha in the input syntax, constructor, or an immutable adjustment:
use PhpColor\Color\Color;
$parsed = Color::parse('#3b82f680');
$constructed = Color::rgb(0.23, 0.51, 0.96, 0.5);
$adjusted = Color::parse('#3b82f6')->withAlpha(0.5);
echo $parsed->getAlpha().PHP_EOL;
echo $constructed->toCss().PHP_EOL;
echo $adjusted->toHex(withAlpha: true).PHP_EOL;
The output is:
0.50196078431373
rgb(59 130 245 / 0.5)
#3b82f680
The hexadecimal alpha byte 80 represents 128 / 255, not exactly 0.5. Decimal and byte-based formats can therefore describe slightly different stored values.
Preserve alpha deliberately
withAlpha() returns a new color in the same concrete color space. Conversions and PHPColor's immutable color transformations preserve the current alpha unless the operation explicitly replaces it.
Concrete constructors clamp alpha to the range from 0.0 to 1.0. This prevents an invalid stored channel, but it does not validate whether transparency is appropriate for the component.
Eight-digit hexadecimal uses CSS #rrggbbaa order. Native CSS functions place alpha after /, as in oklch(0.65 0.18 264 / 0.5). Choose the representation required by the consumer rather than converting every translucent value to hexadecimal.
Evaluate the visible result
Contrast algorithms need the color viewers receive after compositing. A translucent foreground checked as if it were opaque produces the wrong ratio. Use Check contrast after compositing when readability is the decision.
Continue with Adjust color alpha, Create a translucent overlay token, or ColorInterface for the exact alpha methods.