Colour Filters

Colour filters let you manipulate colour values directly in your templates. You can lighten, darken, saturate, or desaturate a colour, mix two colours together, or calculate whether a combination provides sufficient contrast for readability. These filters work best inside {% style %} blocks, where section settings provide a base colour and your template generates a complete palette from that single value.

All colour filters take CSS colour values as input. You can use hex codes like #ff0000, RGB like rgb(255, 0, 0), or HSL like hsl(0, 100%, 50%).

Making colours lighter or darker

color_lighten

Make a colour lighter. Pass a number from 0 to 100:

{{ '#336699' | color_lighten: 20 }}

Output: #5c85ad

A higher percentage produces a progressively lighter result. Zero leaves the colour unchanged, while 100 produces pure white.

color_darken

Make a colour darker. Works the same way as lighten, but in the other way:

{{ '#336699' | color_darken: 20 }}

Output: #1f3d5c

color_saturate

Make a colour more bold and vivid:

{{ '#336699' | color_saturate: 30 }}

A value of 100 gives the most vivid form of that colour.

color_desaturate

Make a colour more dull and grey:

{{ '#336699' | color_desaturate: 30 }}

At the far end, the colour becomes a flat grey tone.

color_modify

Change one part of a colour by name. Pass the part name and a new value:

{{ '#336699' | color_modify: 'alpha', 0.5 }}

Output: rgba(51, 102, 153, 0.5)

You can change red, green, blue, hue, lightness, or alpha. This is the most fine-grained way to tweak a colour.

Mixing colours

color_mix

Blend two colours into one. The last number sets how much of the first colour to use:

{{ '#ff0000' | color_mix: '#0000ff', 50 }}

Output: #800080 (a mix of red and blue in equal parts)

A weight of 75 means 75% red and 25% blue. This is especially useful for generating intermediate tones between two brand colours.

Changing the format

color_to_rgb

Turn any colour into its RGB form:

{{ '#336699' | color_to_rgb }}

Output: rgb(51, 102, 153)

color_to_hsl

Turn any colour into its HSL form:

{{ '#336699' | color_to_hsl }}

Output: hsl(210, 50%, 40%)

color_to_hex

Turn any colour into a hex code:

{{ 'rgb(51, 102, 153)' | color_to_hex }}

Output: #336699

These conversion filters are useful when you need a specific representation for CSS custom properties or for passing to other colour filters.

Reading parts of a colour

color_extract

Pull one part out of a colour as a number:

{{ '#336699' | color_extract: 'red' }}

Output: 51

You can read red, green, blue, hue, lightness, or alpha. This is handy for making choices based on how light or dark a colour is:

{% assign light = section.settings.bg_colour | color_extract: 'lightness' %}
{% if light > 50 %}
  {% assign text_colour = '#000000' %}
{% else %}
  {% assign text_colour = '#ffffff' %}
{% endif %}

Checking contrast

These filters help you make sure text is easy to read on a coloured background.

color_brightness

Get how bright a colour looks, as a number from 0 to 255:

{{ '#336699' | color_brightness }}

Output: 89.16

Below 128 is dark. Above 128 is light. Use this to pick white or black text.

color_contrast

Get the contrast ratio between two colours:

{{ '#336699' | color_contrast: '#ffffff' }}

Output: 5.43

The WCAG rule says you need at least 4.5 for normal text and 3.0 for large text. This filter tells you if your pair of colours meets that bar.

brightness_difference

Get the gap in brightness between two colours:

{{ '#336699' | brightness_difference: '#ffffff' }}

color_difference

Get the total gap across all colour channels between two colours:

{{ '#336699' | color_difference: '#ffffff' }}

A higher number means the two colours are more distinct from each other.

Putting it all together

This pattern reads a colour from section settings, picks a text colour that will be easy to read, and builds hover and link styles from the same base value:

{% assign bg = section.settings.background_colour %}
{% assign ratio = bg | color_contrast: '#ffffff' %}

{% if ratio > 4.5 %}
  {% assign text = '#ffffff' %}
{% else %}
  {% assign text = '#000000' %}
{% endif %}

{% style %}
  .section-{{ section.id }} {
    background-color: {{ bg }};
    color: {{ text }};
  }
  .section-{{ section.id }} a {
    color: {{ bg | color_lighten: 30 }};
  }
  .section-{{ section.id }}:hover {
    background-color: {{ bg | color_darken: 10 }};
  }
{% endstyle %}

One colour from the merchant, and your theme does the rest.