# Color adjust lightness

`color-adjust-lightness` · version 1.0.0 · Geometry, location & color · free, no key needed

Lightens or darkens a CSS color by percentage points of HSL lightness and returns a hex color.

**Use when you need to: lighten a hex color by 20 percent · darken a CSS color by 10 percent · increase HSL lightness.**

## Decide before calling

Read the [versioned contract](/v1/tools/color-adjust-lightness/versions/1.0.0) and the supported scope below. Reuse `color-adjust-lightness@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `color-adjust-lightness@1.0.0` for lighten a hex color by 20 percent. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- lighten a hex color by 20 percent
- darken a CSS color by 10 percent
- increase HSL lightness
- make #336699 lighter
- reduce color lightness
- adjust color brightness in HSL
- lighten an rgb color

## Not supported

- convert named colors
- color name lookup
- rgba and hsla function aliases
- mix colors in perceptual spaces
- adjust CSS relative colors

## Behavior

- Converts sRGB to HSL by CSS Color 4 section 7, adds percentage/100 to lightness, clamps to [0,1], then converts back.
- The percentage is an absolute percentage-point change, not multiplication of current lightness.
- Returns lowercase hex, retaining alpha when it is below one, plus standard_version.
- Accepted function names are rgb(), hsl(), and hwb(); rgba(), hsla(), and CSS named colors are unsupported. Alpha channels are accepted inside the supported function names or hex notation.

## Input

- `color` (string, required): min length 1; max length 128
- `percentage` (number, required): min -100; max 100

## Output

- `standard_version` (string, required)
- `format` (one of "hex", "rgb", "hsl", "hwb", required)
- `value` (string, required)

## Limits

- max input bytes: 256
- max color bytes: 128
- max items: 2
- max iterations: 1
- max output bytes: 256

## Example

Request input:

```json
{
  "color": "#336699",
  "percentage": 20
}
```

Response:

```json
{
  "result": {
    "standard_version": "CSS Color 4 (2024-02-14); WCAG 2.2",
    "format": "hex",
    "value": "#6699cc"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "color-adjust-lightness",
  "version": "1.0.0",
  "input": {
    "color": "#336699",
    "percentage": 20
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/color-adjust-lightness/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"color":"#336699","percentage":20}'
```

The machine-readable contract is at [/v1/tools/color-adjust-lightness/versions/1.0.0](/v1/tools/color-adjust-lightness/versions/1.0.0).

### CLI

```sh
node cli.mjs run color-adjust-lightness 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Color convert](/tools/color-convert): Converts hex, rgb(), hsl(), or hwb() colors and returns the requested normalized notation.
- [Geo destination point](/tools/geo-destination-point): Compute the spherical destination from a start point, initial bearing, and distance; return latitude and longitude.
- [Geo initial bearing](/tools/geo-initial-bearing): Compute the initial spherical bearing from point A to point B and return degrees clockwise from true north.
- [Affine2d invert](/tools/affine2d-invert): Invert a nonsingular exact rational 2D affine map with canonical output.
- [Color contrast wcag](/tools/color-contrast-wcag): Compute WCAG 2.x relative luminance, contrast ratio, and AA/AAA pass flags for two opaque sRGB colors.
- [Geo haversine distance](/tools/geo-haversine-distance): Compute the spherical great-circle distance between two latitude/longitude points and return it in the requested unit.