Color Wheel

An Elixir library for color palette generation and harmonious color schemes.

• 🔺 Triadic palettes: Three colors equally spaced on the color wheel
• 🔲 Tetradic palettes: Four colors forming a rectangle on the color wheel
• ↔️ Complementary palettes: Two opposite colors for high contrast
• 🌈 Analogous palettes: Adjacent colors for harmonious schemes
• 🔱 Split-complementary palettes: Base color with adjacent complements
• 🌓 Monochromatic palettes: Variations of the same hue
• 🔄 Color space conversions: RGB ↔ HSL
• #️⃣ Hex support: Hex string ↔ RGB conversions

Installation

Add color_wheel to your list of dependencies in mix.exs:

def deps do
  [
    {:color_wheel, "~> 0.3.0"}
  ]
end

Then run mix deps.get.

Usage

Color Palette Generation

# Rotation-based: three colors equally spaced on the color wheel
ColorWheel.triadic_palette({120, 50, 50})
# => {:ok, [{120.0, 50, 50}, {240.0, 50, 50}, {0.0, 50, 50}]}

# Variation-based: one hue across five saturation/lightness steps
ColorWheel.monochromatic_palette({240, 80, 60})
# => {:ok, [{240.0, 48, 36}, {240.0, 64, 48}, {240.0, 80, 60},
#          {240.0, 96, 72}, {240.0, 100, 84}]}

Every palette generator returns {:ok, colors}, or {:error, reason} when the input is not a valid HSL tuple, so palette generation never raises.

The conversions below are stricter. rgb_to_hsl/1, hsl_to_rgb/1 and rgb_to_hex/1 raise ArgumentError for out-of-range values, while hex_to_rgb/1 returns {:error, :invalid_hex_format} because unparseable hex is a data error rather than a programming error.

Color Space Conversions

# RGB to HSL (returns a bare tuple)
ColorWheel.rgb_to_hsl({255, 0, 0})
# => {0.0, 100.0, 50.0}

# Hex to RGB (returns an :ok/:error tuple)
ColorWheel.hex_to_rgb("#FF0000")
# => {:ok, {255, 0, 0}}

API Reference

The ColorWheel module is the public entry point, and every function is documented there with tested examples. The remaining palette generators (tetradic_palette/1, complementary_palette/1, analogous_palette/1, split_complementary_palette/1), the remaining conversions (hsl_to_rgb/1, rgb_to_hex/1) and the color-space helpers live in ColorWheel.Palettes and ColorWheel.Color.

Build the docs locally with mix docs and open doc/index.html.

Development

mix deps.get                          # install dependencies
mix test                              # run the test suite
mix format                            # format the code
mix compile --warnings-as-errors      # compile without warnings
mix credo --strict                    # static analysis
mix dialyzer                          # type analysis (builds a PLT)
mix docs                              # build HTML docs into doc/

Continuous integration runs mix format --check-formatted, mix compile --warnings-as-errors, mix test, mix credo --strict and mix dialyzer on both Elixir 1.18/OTP 27 and Elixir 1.20/OTP 29, then builds the docs and the package on the development toolchain. Run them all before opening a pull request.

Changelog

See CHANGELOG.md for notable changes in each release.

Contributing

Contributions are welcome! Run the checks in Development before submitting a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.