Add gamut checker for palettes

Author: kipcole9

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to this project are documented here. The format is based on
 
 ### Added
 
+* Palette gamut checks. `Color.Palette.in_gamut?/2` and `Color.Palette.gamut_report/2` answer "is every stop in this palette inside the chosen RGB working space?", with `gamut_report/2` returning a per-stop breakdown listing exactly which stops failed.
+
 * Public APIs for designer-tool integrations. `Color.Palette.Tonal.to_css/2` and `Color.Palette.ContrastScale.to_css/2` emit CSS custom-property blocks (selector and name prefix configurable). `Color.Palette.Tonal.to_tailwind/2` and `Color.Palette.ContrastScale.to_tailwind/2` emit `theme.extend.colors` fragments ready for `tailwind.config.js`. `Color.Gamut.SVG.render/1` renders a complete chromaticity-diagram SVG — projection, gamut overlays, Planckian locus, seed / palette overlays, sizing, and colour overrides all under a single keyword-list API. 
 
 * `Color.Gamut.Diagram` — pure-data module for chromaticity diagrams.

guides/integrations.md

@@ -13,6 +13,7 @@ Everything the visualizer does is reachable programmatically. The visualizer is
 | Export as Tailwind config | `Color.Palette.Tonal.to_tailwind/2`, `Color.Palette.ContrastScale.to_tailwind/2` |
 | Export as W3C DTCG tokens | `Color.Palette.Tonal.to_tokens/2`, `Color.Palette.Theme.to_tokens/2`, `Color.Palette.Contrast.to_tokens/2`, `Color.Palette.ContrastScale.to_tokens/2` |
 | Encode JSON | `:json.encode/1` (Erlang built-in) |
+| Check if a palette is inside a gamut | `Color.Palette.in_gamut?/2`, `Color.Palette.gamut_report/2` |
 | Render a gamut diagram as SVG | `Color.Gamut.SVG.render/1` |
 | Get raw gamut geometry | `Color.Gamut.Diagram.spectral_locus/2`, `triangle/2`, `planckian_locus/2`, `chromaticity/2` |
 | Encode / decode individual colours as DTCG | `Color.DesignTokens.encode/2`, `decode/1` |
@@ -232,6 +233,72 @@ sRGB_triangle = Color.Gamut.Diagram.triangle(:SRGB, :uv)
 {:ok, blue_point} = Color.Gamut.Diagram.chromaticity("#3b82f6", :uv)
 ```
 
+## Gamut audits — CI checks for palette accessibility
+
+When a palette is generated, our algorithms gamut-map every stop into the working space passed via `:gamut` (default `:SRGB`). But palettes often travel — generated against sRGB on a designer's MacBook, hand-edited by a colourist in Display P3, re-imported through a DTCG file, then deployed to users on devices that span every display gamut. A CI check that "this palette is still legal sRGB after every transformation" is exactly the kind of guard you want in a design-system pipeline.
+
+`Color.Palette.in_gamut?/2` answers a single yes/no across every stop:
+
+```elixir
+palette = Color.Palette.tonal("#3b82f6")
+
+if Color.Palette.in_gamut?(palette, :SRGB) do
+  :ok
+else
+  raise "Brand palette has escaped sRGB"
+end
+```
+
+Need to know **which** stops failed? Use `gamut_report/2`:
+
+```elixir
+report = Color.Palette.gamut_report(palette, :SRGB)
+# %{
+#   working_space: :SRGB,
+#   in_gamut?: false,
+#   stops: [%{label: 50, color: ..., in_gamut?: true}, ...],
+#   out_of_gamut: [%{label: 700, color: ..., in_gamut?: false}, ...]
+# }
+
+for %{label: l, color: c} <- report.out_of_gamut do
+  IO.puts("Stop #{l} (#{Color.to_hex(c)}) is outside sRGB")
+end
+```
+
+Both functions dispatch on palette type — they work uniformly across `Tonal`, `Theme`, `Contrast`, and `ContrastScale`. For `Theme`, `gamut_report/2` returns the breakdown per sub-palette under `:sub_palettes` plus a flat `:out_of_gamut` list with `:sub_palette` keys for actionable failures.
+
+A complete Mix task you can wire into CI:
+
+```elixir
+defmodule Mix.Tasks.Brand.Audit do
+  use Mix.Task
+
+  @shortdoc "Fails the build if the brand palette has escaped a target gamut"
+
+  def run([hex | rest]) do
+    target = case rest do
+      [name] -> String.to_existing_atom(name)
+      _ -> :SRGB
+    end
+
+    report = Color.Palette.tonal(hex) |> Color.Palette.gamut_report(target)
+
+    if report.in_gamut? do
+      Mix.shell().info("✓ Palette is fully inside #{target}")
+    else
+      bad = Enum.map(report.out_of_gamut, fn %{label: l, color: c} ->
+        "  - stop #{l} (#{Color.to_hex(c)})"
+      end)
+
+      Mix.raise("✗ Palette has #{length(report.out_of_gamut)} stops outside #{target}:\n" <>
+                Enum.join(bad, "\n"))
+    end
+  end
+end
+```
+
+Run it in CI as `mix brand.audit "#3b82f6" SRGB`. Non-zero exit on failure with a clear list of which stops broke.
+
 ## Decoding external Design Tokens
 
 If you're importing a DTCG token file from Figma, Style Dictionary, or another tool, decode individual colour tokens back into `Color.*` structs:
@@ -317,7 +384,7 @@ Run it with `mix brand.generate "#3b82f6"` and you have four coordinated artefac
 | A live theme editor for a customer-branded SaaS | `to_css/2` + LiveView |
 | A Tailwind-only site with generated brand colours | `to_tailwind/2` + a Mix task |
 | A documentation site for a design system | `Color.Gamut.SVG.render/1` for gamut plots + `to_tokens/2` for reference |
-| A CI check that a palette stays inside sRGB | `Color.Gamut.Diagram.chromaticity/2` + a triangle containment test |
+| A CI check that a palette stays inside sRGB | `Color.Palette.in_gamut?/2` + `gamut_report/2` |
 | A custom diagram renderer (PDF, PostScript, Canvas) | `Color.Gamut.Diagram.spectral_locus/2` + `triangle/2` |
 | Ingesting a DTCG file from Figma | `Color.DesignTokens.decode/1` |
 

lib/color/palette.ex

@@ -172,4 +172,76 @@ defmodule Color.Palette do
   """
   @spec contrast_scale(Color.input(), keyword()) :: ContrastScale.t()
   defdelegate contrast_scale(seed, options \\ []), to: ContrastScale, as: :new
+
+  @doc """
+  Returns `true` if every stop in the given palette is inside
+  the chosen RGB working space.
+
+  Dispatches on the palette struct type, so works uniformly for
+  `Color.Palette.Tonal`, `Color.Palette.Theme`,
+  `Color.Palette.Contrast`, and `Color.Palette.ContrastScale`.
+
+  Intended primarily for CI checks — call once per palette and
+  fail the build if the result is `false`.
+
+  ### Arguments
+
+  * `palette` is any palette struct produced by this module.
+
+  * `working_space` is an RGB working-space atom. Defaults to
+    `:SRGB`.
+
+  ### Returns
+
+  * A boolean.
+
+  ### Examples
+
+      iex> palette = Color.Palette.tonal("#3b82f6")
+      iex> Color.Palette.in_gamut?(palette)
+      true
+
+      iex> theme = Color.Palette.theme("#3b82f6")
+      iex> Color.Palette.in_gamut?(theme, :SRGB)
+      true
+
+  """
+  @spec in_gamut?(struct(), Color.Types.working_space()) :: boolean()
+  def in_gamut?(palette, working_space \\ :SRGB)
+  def in_gamut?(%Tonal{} = p, ws), do: Tonal.in_gamut?(p, ws)
+  def in_gamut?(%Theme{} = p, ws), do: Theme.in_gamut?(p, ws)
+  def in_gamut?(%Contrast{} = p, ws), do: Contrast.in_gamut?(p, ws)
+  def in_gamut?(%ContrastScale{} = p, ws), do: ContrastScale.in_gamut?(p, ws)
+
+  @doc """
+  Returns a detailed gamut report on the given palette.
+
+  Dispatches on palette type — see each palette module's
+  `gamut_report/2` for the returned map's exact shape.
+
+  ### Arguments
+
+  * `palette` is any palette struct produced by this module.
+
+  * `working_space` defaults to `:SRGB`.
+
+  ### Returns
+
+  * A map. The top-level `:in_gamut?` key is present on every
+    palette type.
+
+  ### Examples
+
+      iex> palette = Color.Palette.tonal("#3b82f6")
+      iex> report = Color.Palette.gamut_report(palette, :SRGB)
+      iex> report.in_gamut?
+      true
+
+  """
+  @spec gamut_report(struct(), Color.Types.working_space()) :: map()
+  def gamut_report(palette, working_space \\ :SRGB)
+  def gamut_report(%Tonal{} = p, ws), do: Tonal.gamut_report(p, ws)
+  def gamut_report(%Theme{} = p, ws), do: Theme.gamut_report(p, ws)
+  def gamut_report(%Contrast{} = p, ws), do: Contrast.gamut_report(p, ws)
+  def gamut_report(%ContrastScale{} = p, ws), do: ContrastScale.gamut_report(p, ws)
 end

lib/color/palette/contrast.ex

@@ -183,6 +183,86 @@ defmodule Color.Palette.Contrast do
     end
   end
 
+  @doc """
+  Returns `true` when every reachable stop in the palette is
+  inside the given RGB working space.
+
+  Unreachable stops (`:unreachable` sentinel) are ignored — they
+  have no colour to check.
+
+  ### Arguments
+
+  * `palette` is a `Color.Palette.Contrast` struct.
+
+  * `working_space` is an RGB working-space atom. Defaults to
+    `:SRGB`.
+
+  ### Returns
+
+  * A boolean.
+
+  ### Examples
+
+      iex> palette = Color.Palette.Contrast.new("#3b82f6", targets: [4.5, 7.0])
+      iex> Color.Palette.Contrast.in_gamut?(palette, :SRGB)
+      true
+
+  """
+  @spec in_gamut?(t(), Color.Types.working_space()) :: boolean()
+  def in_gamut?(%__MODULE__{stops: stops}, working_space \\ :SRGB) do
+    Enum.all?(stops, fn
+      %{color: :unreachable} -> true
+      %{color: color} -> Color.Gamut.in_gamut?(color, working_space)
+    end)
+  end
+
+  @doc """
+  Returns a detailed gamut report on a contrast palette.
+
+  Each reachable stop becomes a `%{target, color, in_gamut?}`
+  entry; unreachable stops become `%{target, color: :unreachable}`.
+
+  ### Arguments
+
+  * `palette` is a `Color.Palette.Contrast` struct.
+
+  * `working_space` is an RGB working-space atom. Defaults to
+    `:SRGB`.
+
+  ### Returns
+
+  * A map with `:working_space`, `:in_gamut?`, `:stops`, and
+    `:out_of_gamut`.
+
+  ### Examples
+
+      iex> palette = Color.Palette.Contrast.new("#3b82f6", targets: [4.5, 7.0])
+      iex> %{in_gamut?: true} = Color.Palette.Contrast.gamut_report(palette, :SRGB)
+
+  """
+  @spec gamut_report(t(), Color.Types.working_space()) :: map()
+  def gamut_report(%__MODULE__{stops: stops}, working_space \\ :SRGB) do
+    entries =
+      Enum.map(stops, fn
+        %{color: :unreachable} = stop ->
+          %{target: stop.target, color: :unreachable, in_gamut?: true}
+
+        %{color: color, target: target} ->
+          %{
+            target: target,
+            color: color,
+            in_gamut?: Color.Gamut.in_gamut?(color, working_space)
+          }
+      end)
+
+    %{
+      working_space: working_space,
+      in_gamut?: Enum.all?(entries, & &1.in_gamut?),
+      stops: entries,
+      out_of_gamut: Enum.reject(entries, & &1.in_gamut?)
+    }
+  end
+
   @doc """
   Emits the palette as a W3C [Design Tokens Community Group](https://www.designtokens.org/)
   color-token group.

lib/color/palette/contrast_scale.ex

@@ -319,6 +319,54 @@ defmodule Color.Palette.ContrastScale do
     Map.put(token, "$extensions", ext)
   end
 
+  @doc """
+  Returns `true` when every stop in the palette is inside the
+  given RGB working space. See `Color.Palette.Tonal.in_gamut?/2`
+  for details.
+
+  ### Examples
+
+      iex> palette = Color.Palette.ContrastScale.new("#3b82f6")
+      iex> Color.Palette.ContrastScale.in_gamut?(palette, :SRGB)
+      true
+
+  """
+  @spec in_gamut?(t(), Color.Types.working_space()) :: boolean()
+  def in_gamut?(%__MODULE__{stops: stops}, working_space \\ :SRGB) do
+    Enum.all?(stops, fn {_label, color} ->
+      Color.Gamut.in_gamut?(color, working_space)
+    end)
+  end
+
+  @doc """
+  Returns a detailed per-stop gamut report. See
+  `Color.Palette.Tonal.gamut_report/2` for the shape.
+
+  ### Examples
+
+      iex> palette = Color.Palette.ContrastScale.new("#3b82f6")
+      iex> %{in_gamut?: true} = Color.Palette.ContrastScale.gamut_report(palette, :SRGB)
+
+  """
+  @spec gamut_report(t(), Color.Types.working_space()) :: map()
+  def gamut_report(%__MODULE__{} = palette, working_space \\ :SRGB) do
+    stops =
+      palette
+      |> labels()
+      |> Enum.map(fn label ->
+        color = Map.fetch!(palette.stops, label)
+        in_gamut? = Color.Gamut.in_gamut?(color, working_space)
+        %{label: label, color: color, in_gamut?: in_gamut?}
+      end)
+
+    %{
+      working_space: working_space,
+      in_gamut?: Enum.all?(stops, & &1.in_gamut?),
+      stops: stops,
+      out_of_gamut: Enum.reject(stops, & &1.in_gamut?)
+    }
+  end
+
   @doc """
   Emits the palette as a block of **CSS custom properties**. See
   `Color.Palette.Tonal.to_css/2` for option details.