tincture 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e3102199850ecef6f4276a6316c9766db75a90aa362db1b3bb06bcd8e476ec40
+  data.tar.gz: 149c2ce8a9cdfa7a3c35a223d7bcc9404b38711aa1bc4f8205617d6e71106466
+SHA512:
+  metadata.gz: 31cf7ada2b2bae78a4bb0d6052fc2efcf438c3e21c4f885e5e237c3cec8327cce22174e49b9c42fa87b7861cac7b79f084e15dd6fb07449996d759ac3336af96
+  data.tar.gz: 0726bfdc5a709161d2b6adb92749a9e69d7acebb38cd9a916e75d20392d05500cc6c455d1f5651042fa166b456dcd1430f1e3e10ea6e3cde1d7fb9679a104fd4

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 1.0.0 (2026-10-21)
+
+- `Tincture::Color` parses CSS hex, named, `rgb()`, `hsl()`, `hwb()`, `oklab()` and `oklch()` colours, and converts between them and HSV.
+- WCAG 2 contrast: `contrast_ratio`, `readable_on?`, `contrast_level`, `contrast_color` and `nearest_readable_on`.
+- Colour difference with ΔE OK and CIEDE2000.
+- An optional Active Model `:color` attribute type and `color:` validator, loaded automatically in Rails.
+- UK spelling aliases for every name.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Andy Croll
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,174 @@
+# Tincture
+
+[![CI](https://github.com/andycroll/tincture/actions/workflows/ci.yml/badge.svg)](https://github.com/andycroll/tincture/actions/workflows/ci.yml)
+
+Colour values for plain Ruby, with an optional Active Model attribute type
+
+- Parse CSS hex, named, `rgb()`, `hsl()`, `hwb()`, `oklab()` and `oklch()` colours into one immutable value
+- Convert between them, plus HSV
+- Check WCAG 2 contrast, pick black or white text, and find readable brand colours
+- Measure colour difference with ΔE OK or CIEDE2000
+- Cast model attributes with `attribute :accent, :color`, loaded automatically in Rails
+
+## Installation
+
+Add this line to your Gemfile:
+
+```ruby
+gem "tincture"
+```
+
+The colour code is plain Ruby with no dependencies. In a Rails app, the attribute type and validator load when the app boots. Elsewhere, require them yourself:
+
+```ruby
+require "tincture/active_model"
+```
+
+## Colors
+
+Parse any CSS colour, legacy or modern syntax
+
+```ruby
+Tincture::Color.parse("#ff8800")
+Tincture::Color.parse("rebeccapurple")
+Tincture::Color.parse("rgb(255 136 0 / 50%)")
+Tincture::Color.parse("hsl(32deg 100% 50%)")
+Tincture::Color.parse("hwb(32 0% 0%)")
+Tincture::Color.parse("oklch(0.7442 0.1812 56.46)")
+```
+
+Anything else raises `Tincture::InvalidColor`. Colours outside sRGB clip to the nearest channel values.
+
+Or build one
+
+```ruby
+Tincture::Color.rgb(255, 136, 0)
+Tincture::Color.hsl(32, 100, 50, 0.5)
+Tincture::Color.hsv(32, 100, 100)
+Tincture::Color.oklch(0.7442, 0.1812, 56.46)
+```
+
+Convert it
+
+```ruby
+color.hex        # "#ff8800"
+color.rgb        # [255, 136, 0]
+color.hsl        # [32.0, 100.0, 50.0]
+color.hsv        # [32.0, 100.0, 100.0]
+color.css_rgb    # "rgb(255 136 0)"
+color.css_hsl    # "hsl(32 100% 50%)"
+color.css_hwb    # "hwb(32 0% 0%)"
+color.css_oklch  # "oklch(0.7442 0.1812 56.46)"
+```
+
+Every output comes from the 8-bit channels, so hex round-trips through any of them.
+
+## Contrast
+
+Pick black or white text for a background colour
+
+```ruby
+background.contrast_color                # WCAG 2, the default
+background.contrast_color(method: :apca) # APCA, needs tincture-apca
+background.contrast_color(method: :oklab)
+```
+
+Each returns `Tincture::Color::BLACK` or `WHITE`, like CSS `contrast-color()`. `contrast_colour` is the UK alias. WCAG 2 always passes AA for body text, but picks black on bright blues and reds where most people would use white. APCA judges by how contrast looks. Oklab compares lightness against APCA's black/white crossover: it agrees with APCA on about 98% of colours and has no licence restriction. APCA and Oklab picks fail WCAG 2 AA on about 29% of colours, so keep the default where WCAG 2 audits apply.
+
+Check a pairing against WCAG 2
+
+```ruby
+text.contrast_ratio("#ffffff")                     # 1 to 21
+text.readable_on?("#ffffff")                       # AA, normal text
+text.readable_on?("#ffffff", level: :aaa, large: true)
+text.contrast_level("#ffffff")                     # :aaa, :aa, :aa_large or nil
+color.luminance                                    # 0 to 1
+```
+
+Find the closest readable version of a brand colour
+
+```ruby
+Tincture::Color.parse("#ff8800").nearest_readable_on("white").hex # "#b66000"
+```
+
+It moves the colour toward black or white in Oklab, keeping its hue, and returns `nil` when no colour can reach the level.
+
+Or pick the best of your own text colours, by WCAG 2 or APCA
+
+```ruby
+Tincture::Color.parse("#ffd166").contrast_color(among: ["#1f2937", "white"]).hex # "#1f2937"
+```
+
+> [!NOTE]
+> Custom candidates can fail WCAG 2 AA, even with the default `:wcag` method: it returns the best candidate, not a passing one. On `#0a7cff`, `among: ["#1f2937", "white"]` returns white at 3.93:1. Check the result with `readable_on?`, or adjust it with `nearest_readable_on`.
+
+## APCA
+
+APCA contrast lives in a separate gem, `tincture-apca`, because its licence only allows web content in support of WCAG. Add it and `require "tincture/apca"` to get `apca_contrast` and `contrast_color(method: :apca)`.
+
+## Difference
+
+Measure how different two colours look
+
+```ruby
+color.difference("#ff8000")                      # ΔE OK, under about 0.02 is hard to see
+color.difference("#ff8000", formula: :ciede2000) # ΔE00, about 1 is just visible
+```
+
+CIEDE2000 matches all 34 of Sharma's reference pairs.
+
+## Attributes
+
+Declare the type on any model with `ActiveModel::Attributes` or Active Record. Outside Rails, `require "tincture/active_model"` first.
+
+```ruby
+class Branding < ApplicationRecord
+  attribute :accent_color, :color
+end
+
+branding.accent_color = "rgb(255 136 0)"
+branding.accent_color.hex # "#ff8800"
+```
+
+Blank or unparseable input casts to `nil`. Another spelling of the same colour does not mark the attribute as changed, and queries accept any CSS form. Colours render as hex in JSON.
+
+Store bare hex for columns that hold `ff8800`
+
+```ruby
+attribute :accent_color_hex, :color, prefix: false
+```
+
+## Validation
+
+Reject input the type could not parse (Active Record only)
+
+```ruby
+validates :accent_color, color: true
+```
+
+Blank input passes, so add `presence: true` to require a colour. Do not pass `allow_nil` or `allow_blank`: unparseable input casts to `nil`, so they skip it.
+
+## UK spelling
+
+Every name has a UK alias
+
+```ruby
+Tincture::Colour.parse("#ff8800")
+attribute :accent_colour, :colour
+validates :accent_colour, colour: true # "is not a valid colour"
+background.contrast_colour
+```
+
+`Tincture::InvalidColour` is the same class as `Tincture::InvalidColor`.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake        # tests and RuboCop
+bundle exec rake rdoc   # API docs in doc/
+```
+
+To release, set the version in `lib/tincture/version.rb`, date the changelog entry, commit, and push a `vX.Y.Z` tag. GitHub Actions runs the checks and publishes the gem to rubygems.org through trusted publishing.
+
+Comments are Markdown. Method types are inline RBS (`#: (String) -> Color`), which RDoc shows on each method.

data/lib/tincture/active_model.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# The Active Model integration: the `:color` and `:colour` attribute types and
+# the `color:` and `colour:` validators. Rails apps load it when they boot;
+# elsewhere, `require "tincture/active_model"`.
+
+require 'active_model'
+require 'tincture'
+require_relative 'type'
+require_relative 'color_validator'
+
+ActiveModel::Type.register(:color, Tincture::Type)
+ActiveModel::Type.register(:colour, Tincture::Type)
+
+ActiveSupport.on_load(:active_record) do
+  ActiveRecord::Type.register(:color, Tincture::Type)
+  ActiveRecord::Type.register(:colour, Tincture::Type)
+end

data/lib/tincture/color/comparison.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Tincture
+  class Color
+    # How different two colours look. The formulas live in
+    # Tincture::Difference. Mixed into Color.
+    module Comparison
+      D65_WHITE = [0.95047, 1.0, 1.08883].freeze # :nodoc:
+
+      # How different two colours look (ΔE). `formula: :oklab` (the default)
+      # is ΔE OK, where under about 0.02 is hard to see. `formula:
+      # :ciede2000` is ΔE00, where about 1 is just visible. See
+      # Tincture::Difference.
+      #
+      #     Tincture::Color.parse("red").difference("white") # => 0.4526…
+      #
+      #: (String | Color other, ?formula: :oklab | :ciede2000) -> Float
+      def difference(other, formula: :oklab)
+        other = Color.parse(other)
+
+        case formula
+        when :oklab then Difference.oklab(oklab_components, other.oklab_components)
+        when :ciede2000 then Difference.ciede2000(lab_components, other.lab_components)
+        else raise ArgumentError, "unknown formula #{formula.inspect}, use :oklab or :ciede2000"
+        end
+      end
+
+      protected
+
+      # CIELAB against the D65 white point, as sRGB tools usually report it.
+      def lab_components # :nodoc:
+        red, green, blue = linear_rgb
+
+        x, y, z = [
+          ((0.4124564 * red) + (0.3575761 * green) + (0.1804375 * blue)) / D65_WHITE[0],
+          ((0.2126729 * red) + (0.7151522 * green) + (0.0721750 * blue)) / D65_WHITE[1],
+          ((0.0193339 * red) + (0.1191920 * green) + (0.9503041 * blue)) / D65_WHITE[2]
+        ].map { it > (6 / 29.0)**3 ? Math.cbrt(it) : (it / (3 * ((6 / 29.0)**2))) + (4 / 29.0) }
+
+        [(116 * y) - 16, 500 * (x - y), 200 * (y - z)]
+      end
+    end
+
+    include Comparison
+  end
+end

data/lib/tincture/color/contrast.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Tincture
+  class Color
+    # WCAG 2 minimum contrast ratios.
+    WCAG_RATIOS = { aa: { normal: 4.5, large: 3.0 }, aaa: { normal: 7.0, large: 4.5 } }.freeze
+
+    # Oklab lightness of the grey where black and white text have equal APCA
+    # contrast. #contrast_color with `method: :oklab` picks black above it.
+    OKLAB_CONTRAST_THRESHOLD = 0.716
+
+    # The dark default for #contrast_color.
+    BLACK = NAMED.fetch('black')
+
+    # The light default for #contrast_color.
+    WHITE = NAMED.fetch('white')
+
+    # WCAG 2 contrast, and picking text colours that read on a background.
+    # Mixed into Color.
+    module Contrast
+      # Added to Color itself.
+      module ClassMethods
+        # Scores for #contrast_color methods other than `:oklab`, keyed by
+        # name. Each takes a candidate and the background and returns a
+        # score, higher is better. Extensions such as tincture-apca add to it.
+        #
+        #: () -> Hash[Symbol, ^(Color, Color) -> Numeric]
+        def contrast_scorers
+          @contrast_scorers ||= { wcag: ->(text, background) { text.contrast_ratio(background) } }
+        end
+      end
+
+      # WCAG 2 relative luminance, from 0 (black) to 1 (white). Ignores
+      # alpha.
+      #
+      #: () -> Float
+      def luminance
+        red, green, blue = linear_rgb
+        (0.2126 * red) + (0.7152 * green) + (0.0722 * blue)
+      end
+
+      # WCAG 2 contrast ratio against another colour, from 1 to 21. WCAG AA
+      # asks for 4.5 for body text. Ignores alpha.
+      #
+      #     Tincture::Color.parse("#767676").contrast_ratio("white") # => 4.54…
+      #
+      #: (String | Color other) -> Float
+      def contrast_ratio(other)
+        darker, lighter = [luminance, Color.parse(other).luminance].minmax
+        (lighter + 0.05) / (darker + 0.05)
+      end
+
+      # The colour for text set on this colour, like CSS `contrast-color()`:
+      # BLACK or WHITE by default, or the best of the colours given in
+      # `among:`. Ties go to the earlier candidate.
+      #
+      # Custom `among:` candidates can return a colour that fails WCAG 2 AA,
+      # even with `method: :wcag`: it picks the best candidate, not a
+      # passing one. On `#0a7cff`, `among: ["#1f2937", "white"]` returns
+      # white at 3.93:1. Check the result with #readable_on?, or use
+      # #nearest_readable_on to adjust it.
+      #
+      # - `method: :wcag` (the default) picks the higher WCAG 2 contrast
+      #   ratio. Between black and white that always passes AA. It picks
+      #   black on bright blues, where most people would use white.
+      # - `method: :apca` picks the larger APCA contrast. It needs the
+      #   tincture-apca gem, whose licence restricts it to web content.
+      # - `method: :oklab` picks black when Oklab lightness is above
+      #   OKLAB_CONTRAST_THRESHOLD, so it only takes black and white. It
+      #   needs no extra gem, and agrees with APCA on about 98% of sRGB
+      #   colours, where WCAG 2 agrees on about 71%. Its pick fails WCAG 2
+      #   AA on about 29% of colours, so audits flag it.
+      #
+      #     blue = Tincture::Color.parse("#0a7cff")
+      #     blue.contrast_color                 # => BLACK
+      #     blue.contrast_color(method: :oklab) # => WHITE
+      #
+      #     amber = Tincture::Color.parse("#ffd166")
+      #     amber.contrast_color(among: ["#1f2937", "white"]).hex # => "#1f2937"
+      #
+      #: (?among: Array[String | Color], ?method: Symbol) -> Color
+      def contrast_color(among: [BLACK, WHITE], method: :wcag)
+        candidates = among.map { Color.parse(it) }
+
+        if method == :oklab
+          oklab_contrast_color(candidates)
+        else
+          candidates.max_by { contrast_scorer(method).call(it, self) }
+        end
+      end
+
+      alias contrast_colour contrast_color
+
+      # Whether text in this colour on `background` meets a WCAG 2 level:
+      # `level: :aa` (the default) or `:aaa`, with `large: true` for text at
+      # least 18pt, or 14pt bold.
+      #
+      #: (String | Color background, ?level: :aa | :aaa, ?large: bool) -> bool
+      def readable_on?(background, level: :aa, large: false)
+        contrast_ratio(background) >= WCAG_RATIOS.fetch(level).fetch(large ? :large : :normal)
+      end
+
+      # The highest WCAG 2 level text in this colour reaches on
+      # `background`: `:aaa`, `:aa` (also AAA for large text), `:aa_large`,
+      # or `nil`.
+      #
+      #: (String | Color background) -> (:aaa | :aa | :aa_large | nil)
+      def contrast_level(background)
+        ratio = contrast_ratio(background)
+
+        if ratio >= WCAG_RATIOS[:aaa][:normal] then :aaa
+        elsif ratio >= WCAG_RATIOS[:aa][:normal] then :aa
+        elsif ratio >= WCAG_RATIOS[:aa][:large] then :aa_large
+        end
+      end
+
+      # The closest colour to this one that is #readable_on? `background`:
+      # this colour if it already is, otherwise this colour moved in Oklab
+      # toward black or white, keeping its hue. `nil` when even black or
+      # white cannot reach the level.
+      #
+      #     Tincture::Color.parse("#ff8800").nearest_readable_on("white").hex # => "#b66000"
+      #
+      #: (String | Color background, ?level: :aa | :aaa, ?large: bool) -> Color?
+      def nearest_readable_on(background, level: :aa, large: false)
+        background = Color.parse(background)
+        extreme = background.contrast_color
+
+        if readable_on?(background, level:, large:)
+          self
+        elsif extreme.readable_on?(background, level:, large:)
+          nearest_mix_toward(extreme) { it.readable_on?(background, level:, large:) }
+        end
+      end
+
+      private
+
+      # The smallest mix toward `extreme` that passes the block. Assumes the
+      # block fails here and passes at `extreme`.
+      def nearest_mix_toward(extreme)
+        amount = (0.0..1.0).bsearch { |candidate| yield mixed_toward(extreme, candidate) }
+        mixed_toward(extreme, amount)
+      end
+
+      def contrast_scorer(method)
+        Color.contrast_scorers.fetch(method) do
+          hint = method == :apca ? ' (add the tincture-apca gem and require "tincture/apca")' : ''
+          raise ArgumentError, "unknown method #{method.inspect}#{hint}"
+        end
+      end
+
+      def oklab_contrast_color(candidates)
+        if candidates.sort_by(&:luminance) == [BLACK, WHITE]
+          oklab_components.first > OKLAB_CONTRAST_THRESHOLD ? BLACK : WHITE
+        else
+          raise ArgumentError, 'method: :oklab picks between black and white only'
+        end
+      end
+    end
+
+    include Contrast
+    extend Contrast::ClassMethods
+  end
+end

data/lib/tincture/color/hsl.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Tincture
+  class Color
+    # HSL and its relatives HWB and HSV, which share its hue angle. Mixed into
+    # Color.
+    module Hsl
+      # Added to Color itself.
+      module ClassMethods
+        # Builds a colour from a hue in degrees, and saturation and lightness
+        # percentages (0–100).
+        #
+        #: (Numeric hue, Numeric saturation, Numeric lightness, ?Numeric alpha) -> Color
+        def hsl(hue, saturation, lightness, alpha = 1.0)
+          channels = hsl_channels(hue, saturation / 100.0, lightness / 100.0)
+          rgb(*channels.map { it * 255 }, alpha)
+        end
+
+        # Builds a colour from a hue in degrees, and whiteness and blackness
+        # percentages (0–100). Whiteness and blackness that sum past 100%
+        # give a grey.
+        #
+        #: (Numeric hue, Numeric whiteness, Numeric blackness, ?Numeric alpha) -> Color
+        def hwb(hue, whiteness, blackness, alpha = 1.0)
+          whiteness = whiteness.clamp(0, 100) / 100.0
+          blackness = blackness.clamp(0, 100) / 100.0
+
+          channels =
+            if whiteness + blackness >= 1
+              [whiteness / (whiteness + blackness)] * 3
+            else
+              hsl_channels(hue, 1, 0.5).map { (it * (1 - whiteness - blackness)) + whiteness }
+            end
+
+          rgb(*channels.map { it * 255 }, alpha)
+        end
+
+        # Builds a colour from a hue in degrees, and saturation and value
+        # percentages (0–100), as colour pickers use. Not a CSS format.
+        #
+        #: (Numeric hue, Numeric saturation, Numeric value, ?Numeric alpha) -> Color
+        def hsv(hue, saturation, value, alpha = 1.0)
+          hwb(hue, (100 - saturation) * value / 100.0, 100 - value, alpha)
+        end
+
+        private
+
+        def hsl_channels(hue, saturation, lightness)
+          saturation = saturation.clamp(0, 1)
+          lightness = lightness.clamp(0, 1)
+          amount = saturation * [lightness, 1 - lightness].min
+
+          [0, 8, 4].map do |offset|
+            k = (offset + (hue / 30.0)) % 12
+            lightness - (amount * [-1, [k - 3, 9 - k, 1].min].max)
+          end
+        end
+      end
+
+      # Hue in degrees, saturation and lightness as percentages, to one
+      # decimal place.
+      #
+      #: () -> [Float, Float, Float]
+      def hsl
+        max, min = channel_fractions.minmax.reverse
+        lightness = (max + min) / 2
+        saturation = max == min ? 0 : (max - lightness) / [lightness, 1 - lightness].min
+
+        [hue, rounded(saturation * 100, 1), rounded(lightness * 100, 1)]
+      end
+
+      # Hue in degrees, whiteness and blackness as percentages, to one
+      # decimal place.
+      #
+      #: () -> [Float, Float, Float]
+      def hwb
+        max, min = channel_fractions.minmax.reverse
+        [hue, rounded(min * 100, 1), rounded((1 - max) * 100, 1)]
+      end
+
+      # Hue in degrees, saturation and value as percentages, to one decimal
+      # place.
+      #
+      #: () -> [Float, Float, Float]
+      def hsv
+        max, min = channel_fractions.minmax.reverse
+        saturation = max.zero? ? 0 : (max - min) / max
+
+        [hue, rounded(saturation * 100, 1), rounded(max * 100, 1)]
+      end
+
+      # `"hsl(32 100% 50%)"` or `"hsl(32 100% 50% / 0.5)"`.
+      #
+      #: () -> String
+      def css_hsl = css_function('hsl', hsl, percentages: true)
+
+      # `"hwb(32 0% 0%)"` or `"hwb(32 0% 0% / 0.5)"`.
+      #
+      #: () -> String
+      def css_hwb = css_function('hwb', hwb, percentages: true)
+
+      private
+
+      def hue
+        red, green, blue = channel_fractions
+        max, min = channel_fractions.minmax.reverse
+        delta = max - min
+
+        sector =
+          if delta.zero? then 0
+          elsif max == red then ((green - blue) / delta) % 6
+          elsif max == green then ((blue - red) / delta) + 2
+          else ((red - green) / delta) + 4
+          end
+
+        rounded(sector * 60, 1) % 360
+      end
+    end
+
+    include Hsl
+    extend Hsl::ClassMethods
+  end
+end

data/lib/tincture/color/oklab.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Tincture
+  class Color
+    # Oklab and its cylindrical form Oklch, where equal steps look equally
+    # different. Mixed into Color.
+    module Oklab
+      # Added to Color itself.
+      module ClassMethods
+        # Builds a colour from Oklab lightness (0–1) and its `a` (green–red)
+        # and `b` (blue–yellow) axes.
+        #
+        #: (Numeric lightness, Numeric green_red, Numeric blue_yellow, ?Numeric alpha) -> Color
+        def oklab(lightness, green_red, blue_yellow, alpha = 1.0)
+          lightness = lightness.clamp(0, 1)
+
+          l, m, s = [
+            lightness + (0.3963377774 * green_red) + (0.2158037573 * blue_yellow),
+            lightness - (0.1055613458 * green_red) - (0.0638541728 * blue_yellow),
+            lightness - (0.0894841775 * green_red) - (1.2914855480 * blue_yellow)
+          ].map { it**3 }
+
+          linear = [
+            (4.0767416621 * l) - (3.3077115913 * m) + (0.2309699292 * s),
+            (-1.2684380046 * l) + (2.6097574011 * m) - (0.3413193965 * s),
+            (-0.0041960863 * l) - (0.7034186147 * m) + (1.7076147010 * s)
+          ]
+
+          rgb(*linear.map { gamma_encoded(it) * 255 }, alpha)
+        end
+
+        # Builds a colour from Oklab lightness (0–1), chroma and a hue in
+        # degrees.
+        #
+        #: (Numeric lightness, Numeric chroma, Numeric hue, ?Numeric alpha) -> Color
+        def oklch(lightness, chroma, hue, alpha = 1.0)
+          chroma = [chroma, 0].max
+          radians = hue * Math::PI / 180
+          oklab(lightness, chroma * Math.cos(radians), chroma * Math.sin(radians), alpha)
+        end
+
+        private
+
+        def gamma_encoded(linear)
+          linear = linear.clamp(0.0, 1.0)
+          linear <= 0.0031308 ? linear * 12.92 : (1.055 * (linear**(1 / 2.4))) - 0.055
+        end
+      end
+
+      # Oklab lightness (0–1) and its `a` and `b` axes, to four decimal
+      # places.
+      #
+      #: () -> [Float, Float, Float]
+      def oklab = oklab_components.map { rounded(it, 4) }
+
+      # Oklab lightness (0–1), chroma to four decimal places, and hue in
+      # degrees to two.
+      #
+      #: () -> [Float, Float, Float]
+      def oklch
+        lightness, a, b = oklab_components
+        chroma = rounded(Math.hypot(a, b), 4)
+        angle = chroma.zero? ? 0 : Math.atan2(b, a) * 180 / Math::PI
+
+        [rounded(lightness, 4), chroma, rounded(angle, 2) % 360]
+      end
+
+      # `"oklab(0.628 0.2249 0.1258)"`, with `/ alpha` when translucent.
+      #
+      #: () -> String
+      def css_oklab = css_function('oklab', oklab)
+
+      # `"oklch(0.628 0.2577 29.23)"`, with `/ alpha` when translucent.
+      #
+      #: () -> String
+      def css_oklch = css_function('oklch', oklch)
+
+      protected
+
+      def oklab_components # :nodoc:
+        red, green, blue = linear_rgb
+
+        l, m, s = [
+          (0.4122214708 * red) + (0.5363325363 * green) + (0.0514459929 * blue),
+          (0.2119034982 * red) + (0.6806995451 * green) + (0.1073969566 * blue),
+          (0.0883024619 * red) + (0.2817188376 * green) + (0.6299787005 * blue)
+        ].map { Math.cbrt(it) }
+
+        [
+          (0.2104542553 * l) + (0.7936177850 * m) - (0.0040720468 * s),
+          (1.9779984951 * l) - (2.4285922050 * m) + (0.4505937099 * s),
+          (0.0259040371 * l) + (0.7827717662 * m) - (0.8086757660 * s)
+        ]
+      end
+
+      private
+
+      def mixed_toward(other, amount)
+        lightness, a, b = oklab_components.zip(other.oklab_components).map do |mine, theirs|
+          mine + ((theirs - mine) * amount)
+        end
+        Color.oklab(lightness, a, b, alpha)
+      end
+    end
+
+    include Oklab
+    extend Oklab::ClassMethods
+  end
+end

data/lib/tincture/color/parsing.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Tincture
+  class Color
+    # Reads CSS colour strings: hex, named colours and the `rgb()`, `hsl()`,
+    # `hwb()`, `oklab()` and `oklch()` functions. Extends Color, so its
+    # methods are called on the class: `Tincture::Color.parse`.
+    module Parsing
+      HEX = /
+        \A
+        \#?                   # optional leading hash
+        (?<digits>
+          \h{3,4}             # rgb or rgba shorthand
+          | \h{6}             # rrggbb
+          | \h{8}             # rrggbbaa
+        )
+        \z
+      /x # :nodoc:
+
+      FUNCTION = /
+        \A
+        (?<name>[a-z]+)       # rgb, hsla, oklch…
+        \(
+        (?<arguments>[^)]*)   # everything between the parentheses
+        \)
+        \z
+      /xi # :nodoc:
+
+      TOKEN = /
+        \A
+        (?<number>
+          [+-]?               # optional sign
+          (?:
+            \d+(?:\.\d*)?     # integer, optional decimals: 1, 1., 1.5
+            | \.\d+           # bare decimals: .5
+          )
+          (?:e[+-]?\d+)?      # optional exponent: 1e3
+        )
+        (?<unit>%|deg|grad|rad|turn)?
+        \z
+      /xi # :nodoc:
+
+      CHANNEL = { nil => 1, '%' => 255r / 100 }.freeze # :nodoc:
+      FRACTION = { nil => 1, '%' => 1r / 100 }.freeze # :nodoc:
+      PERCENTAGE = { nil => 1, '%' => 1 }.freeze # :nodoc:
+      HUE = { nil => 1, 'deg' => 1, 'grad' => 0.9, 'rad' => 180 / Math::PI, 'turn' => 360 }.freeze # :nodoc:
+      OK_AXIS = { nil => 1, '%' => 4r / 1000 }.freeze # :nodoc:
+
+      UNITS = {
+        'rgb' => [CHANNEL, CHANNEL, CHANNEL, FRACTION],
+        'hsl' => [HUE, PERCENTAGE, PERCENTAGE, FRACTION],
+        'hwb' => [HUE, PERCENTAGE, PERCENTAGE, FRACTION],
+        'oklab' => [FRACTION, OK_AXIS, OK_AXIS, FRACTION],
+        'oklch' => [FRACTION, OK_AXIS, HUE, FRACTION]
+      }.freeze # :nodoc:
+
+      # Only rgb() and hsl() take the comma syntax and the rgba()/hsla() names.
+      LEGACY = { 'rgb' => 'rgb', 'rgba' => 'rgb', 'hsl' => 'hsl', 'hsla' => 'hsl' }.freeze # :nodoc:
+
+      # Parses a CSS colour string. Returns a Color unchanged.
+      #
+      #     Tincture::Color.parse("#ff8800")
+      #     Tincture::Color.parse("rebeccapurple")
+      #     Tincture::Color.parse("oklch(0.7 0.18 50 / 50%)")
+      #
+      # Raises InvalidColor for anything else.
+      #
+      #: (String | Color input) -> Color
+      def parse(input)
+        return input if input.is_a?(Color)
+
+        string = input.to_s.strip
+        color = hex_color(string) || NAMED[string.downcase] || function_color(string)
+        color || raise(InvalidColor, "#{input.inspect} is not a CSS color")
+      end
+
+      private
+
+      def hex_color(string)
+        digits = HEX.match(string)&.[](:digits)
+        return unless digits
+
+        digits = digits.chars.map { it * 2 }.join if digits.length <= 4
+        red, green, blue, alpha = digits.scan(/../).map(&:hex)
+        rgb(red, green, blue, (alpha || 255) / 255.0)
+      end
+
+      def function_color(string)
+        match = FUNCTION.match(string)
+        return unless match
+
+        name = match[:name].downcase
+        constructor = LEGACY.fetch(name, name)
+        units = UNITS[constructor]
+        values = units && function_values(match[:arguments], units, legacy: LEGACY.key?(name))
+        public_send(constructor, *values) if values
+      end
+
+      def function_values(arguments, units, legacy:)
+        tokens = function_tokens(arguments, legacy:)
+        return unless tokens
+
+        values = tokens.zip(units).map { |token, scale| number(token, scale) }
+        values unless values.include?(nil)
+      end
+
+      # Legacy syntax separates with commas and takes alpha fourth; modern
+      # syntax separates with spaces and takes alpha after a slash.
+      def function_tokens(arguments, legacy:)
+        if arguments.include?(',')
+          legacy_tokens(arguments) if legacy
+        else
+          modern_tokens(arguments)
+        end
+      end
+
+      def legacy_tokens(arguments)
+        tokens = arguments.split(',', -1).map(&:strip)
+        tokens if tokens.size.between?(3, 4)
+      end
+
+      def modern_tokens(arguments)
+        channels, alpha, *extra = arguments.split('/')
+        tokens = channels.to_s.split
+        [*tokens, *alpha&.strip] if tokens.size == 3 && extra.empty?
+      end
+
+      def number(token, scale)
+        match = TOKEN.match(token)
+        return unless match
+
+        unit = match[:unit]&.downcase
+        match[:number].to_r * scale[unit] if scale.key?(unit)
+      end
+    end
+
+    extend Parsing
+
+    # CSS named colours, keyed by lowercase name.
+    NAMED = YAML.load_file(File.expand_path('../named_colors.yml', __dir__)).transform_values { parse(it) }.freeze
+  end
+end

data/lib/tincture/color.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Tincture
+  # Raised by Color.parse for input that is not a CSS colour.
+  class InvalidColor < ArgumentError; end
+
+  # An sRGB colour: 8-bit `red`, `green` and `blue` channels and an `alpha`
+  # from 0 to 1. Immutable.
+  #
+  # Parses CSS hex, named, `rgb()`, `hsl()`, `hwb()`, `oklab()` and `oklch()`
+  # colours. Every output is derived from the 8-bit channels, so a colour
+  # stored as hex round-trips through any of them. Colours outside sRGB, such
+  # as a high-chroma `oklch()`, clip to the nearest channel values.
+  #
+  #     color = Tincture::Color.parse("orange")
+  #     color.css_hsl        # => "hsl(38.8 100% 50%)"
+  #     color.contrast_color # => Tincture::Color::BLACK
+  #
+  # Each part lives in a module mixed into this class: Parsing (`parse`), Hsl
+  # (HSL, HWB, HSV), Oklab (Oklab, Oklch), Contrast (WCAG, black or white
+  # text) and Comparison (ΔE).
+  #
+  # Conversions follow [CSS Color 4](https://www.w3.org/TR/css-color-4/) and
+  # [Oklab](https://bottosson.github.io/posts/oklab/).
+  class Color < Data.define(:red, :green, :blue, :alpha)
+    # Builds a colour from 0–255 channels and a 0–1 alpha. Out-of-range
+    # values clamp, as they do in CSS.
+    #
+    #: (Numeric red, Numeric green, Numeric blue, ?Numeric alpha) -> Color
+    def self.rgb(red, green, blue, alpha = 1.0)
+      red, green, blue = [red, green, blue].map { it.clamp(0, 255).round }
+      new(red:, green:, blue:, alpha: alpha.clamp(0.0, 1.0).to_f)
+    end
+
+    # `"#ff8800"`, or `"#ff880080"` when translucent.
+    #
+    #: () -> String
+    def hex
+      bytes = opaque? ? rgb : [*rgb, alpha_byte]
+      "##{bytes.map { format('%02x', it) }.join}"
+    end
+
+    alias to_s hex
+
+    # JSON renders a colour as its hex string.
+    #
+    #: (*untyped) -> String
+    def as_json(*) = hex
+
+    # Red, green and blue, each 0–255.
+    #
+    #: () -> [Integer, Integer, Integer]
+    def rgb = [red, green, blue]
+
+    # `"rgb(255 136 0)"` or `"rgb(255 136 0 / 0.5)"`.
+    #
+    #: () -> String
+    def css_rgb = css_function('rgb', rgb)
+
+    # Whether the colour has no transparency at 8-bit precision.
+    #
+    #: () -> bool
+    def opaque? = alpha_byte == 255
+
+    private
+
+    def alpha_byte = (alpha * 255).round
+
+    def channel_fractions = rgb.map { it / 255.0 }
+
+    def linear_rgb
+      channel_fractions.map { it <= 0.04045 ? it / 12.92 : ((it + 0.055) / 1.055)**2.4 }
+    end
+
+    # Adding 0.0 turns -0.0 into 0.0, so CSS never shows "-0".
+    def rounded(number, digits) = number.round(digits) + 0.0
+
+    def css_function(name, components, percentages: false)
+      first, *rest = components.map { css_number(it) }
+      rest = rest.map { "#{it}%" } if percentages
+      alpha = " / #{css_number(self.alpha.round(3))}" unless opaque?
+
+      "#{name}(#{[first, *rest].join(' ')}#{alpha})"
+    end
+
+    def css_number(number) = number.to_s.delete_suffix('.0')
+  end
+end

data/lib/tincture/color_validator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ActiveModel # :nodoc:
+  module Validations # :nodoc:
+    # `validates :accent, color: true` adds an error when a `:color` attribute
+    # was given input it could not parse. The type casts that input to `nil`,
+    # so this reads the raw value back, which only Active Record keeps.
+    #
+    # Blank input passes; pair with `presence: true` to require a colour. Do
+    # not pass `allow_nil` or `allow_blank`: unparseable input casts to `nil`,
+    # so they would skip it.
+    class ColorValidator < EachValidator
+      # The error message unless the validation passes `message:`.
+      MESSAGE = 'is not a valid color'
+
+      def validate_each(record, attribute, value) # :nodoc:
+        if value.nil? && record.read_attribute_before_type_cast(attribute).present?
+          record.errors.add(attribute, :invalid_color, message: options.fetch(:message, self.class::MESSAGE))
+        end
+      end
+    end
+
+    # `validates :accent, colour: true`, with the error in UK spelling.
+    class ColourValidator < ColorValidator
+      MESSAGE = 'is not a valid colour' # :nodoc:
+    end
+  end
+end

data/lib/tincture/difference.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Tincture
+  # Colour difference (ΔE) formulas. Color#difference is the usual way in;
+  # these take colour space coordinates directly.
+  module Difference
+    module_function
+
+    # ΔE OK: straight-line distance between two Oklab colours, as CSS Color 4
+    # measures it. Differences under about 0.02 are hard to see.
+    #
+    #: ([Float, Float, Float] first, [Float, Float, Float] second) -> Float
+    def oklab(first, second)
+      Math.sqrt(first.zip(second).sum { |a, b| (a - b)**2 })
+    end
+
+    # CIEDE2000 (ΔE00) between two CIELAB colours, the print and paint
+    # standard. A difference of about 1 is just visible.
+    #
+    # Follows [Sharma, Wu and Dalal](https://hajim.rochester.edu/ece/sites/gsharma/ciede2000/ciede2000noteCRNA.pdf),
+    # with the weighting factors kL, kC and kH all 1.
+    #
+    #: ([Float, Float, Float] first, [Float, Float, Float] second) -> Float
+    def ciede2000(first, second)
+      (l1, a1, b1), (l2, a2, b2) = first, second
+
+      chroma_mean = (Math.hypot(a1, b1) + Math.hypot(a2, b2)) / 2
+      g = 0.5 * (1 - chroma_weight(chroma_mean))
+      a1 *= 1 + g
+      a2 *= 1 + g
+
+      c1 = Math.hypot(a1, b1)
+      c2 = Math.hypot(a2, b2)
+      h1 = hue_angle(a1, b1)
+      h2 = hue_angle(a2, b2)
+      chromatic = c1 * c2 != 0
+
+      delta_l = l2 - l1
+      delta_c = c2 - c1
+      delta_h = 2 * Math.sqrt(c1 * c2) * Math.sin(radians(hue_difference(h1, h2, chromatic) / 2))
+
+      l_mean = (l1 + l2) / 2
+      c_mean = (c1 + c2) / 2
+      h_mean = hue_mean(h1, h2, chromatic)
+
+      t = 1 - (0.17 * Math.cos(radians(h_mean - 30))) + (0.24 * Math.cos(radians(2 * h_mean))) +
+          (0.32 * Math.cos(radians((3 * h_mean) + 6))) - (0.20 * Math.cos(radians((4 * h_mean) - 63)))
+
+      s_l = 1 + (0.015 * ((l_mean - 50)**2) / Math.sqrt(20 + ((l_mean - 50)**2)))
+      s_c = 1 + (0.045 * c_mean)
+      s_h = 1 + (0.015 * c_mean * t)
+      rotation = -Math.sin(radians(60 * Math.exp(-((h_mean - 275) / 25)**2))) * 2 * chroma_weight(c_mean)
+
+      lightness = delta_l / s_l
+      chroma = delta_c / s_c
+      hue = delta_h / s_h
+      Math.sqrt((lightness**2) + (chroma**2) + (hue**2) + (rotation * chroma * hue))
+    end
+
+    def chroma_weight(chroma) # :nodoc:
+      Math.sqrt((chroma**7) / ((chroma**7) + (25.0**7)))
+    end
+
+    def hue_angle(green_red, blue_yellow) # :nodoc:
+      green_red.zero? && blue_yellow.zero? ? 0 : Math.atan2(blue_yellow, green_red) * 180 / Math::PI % 360
+    end
+
+    def hue_difference(first_hue, second_hue, chromatic) # :nodoc:
+      difference = second_hue - first_hue
+
+      if !chromatic then 0
+      elsif difference > 180 then difference - 360
+      elsif difference < -180 then difference + 360
+      else difference
+      end
+    end
+
+    def hue_mean(first_hue, second_hue, chromatic) # :nodoc:
+      sum = first_hue + second_hue
+
+      if !chromatic then sum
+      elsif (first_hue - second_hue).abs <= 180 then sum / 2
+      elsif sum < 360 then (sum + 360) / 2
+      else (sum - 360) / 2
+      end
+    end
+
+    def radians(degrees) = degrees * Math::PI / 180 # :nodoc:
+
+    private_class_method :chroma_weight, :hue_angle, :hue_difference, :hue_mean, :radians
+  end
+end

data/lib/tincture/named_colors.yml

@@ -0,0 +1,150 @@
+# CSS Color 4 named colors: https://www.w3.org/TR/css-color-4/#named-colors
+aliceblue: "#f0f8ff"
+antiquewhite: "#faebd7"
+aqua: "#00ffff"
+aquamarine: "#7fffd4"
+azure: "#f0ffff"
+beige: "#f5f5dc"
+bisque: "#ffe4c4"
+black: "#000000"
+blanchedalmond: "#ffebcd"
+blue: "#0000ff"
+blueviolet: "#8a2be2"
+brown: "#a52a2a"
+burlywood: "#deb887"
+cadetblue: "#5f9ea0"
+chartreuse: "#7fff00"
+chocolate: "#d2691e"
+coral: "#ff7f50"
+cornflowerblue: "#6495ed"
+cornsilk: "#fff8dc"
+crimson: "#dc143c"
+cyan: "#00ffff"
+darkblue: "#00008b"
+darkcyan: "#008b8b"
+darkgoldenrod: "#b8860b"
+darkgray: "#a9a9a9"
+darkgreen: "#006400"
+darkgrey: "#a9a9a9"
+darkkhaki: "#bdb76b"
+darkmagenta: "#8b008b"
+darkolivegreen: "#556b2f"
+darkorange: "#ff8c00"
+darkorchid: "#9932cc"
+darkred: "#8b0000"
+darksalmon: "#e9967a"
+darkseagreen: "#8fbc8f"
+darkslateblue: "#483d8b"
+darkslategray: "#2f4f4f"
+darkslategrey: "#2f4f4f"
+darkturquoise: "#00ced1"
+darkviolet: "#9400d3"
+deeppink: "#ff1493"
+deepskyblue: "#00bfff"
+dimgray: "#696969"
+dimgrey: "#696969"
+dodgerblue: "#1e90ff"
+firebrick: "#b22222"
+floralwhite: "#fffaf0"
+forestgreen: "#228b22"
+fuchsia: "#ff00ff"
+gainsboro: "#dcdcdc"
+ghostwhite: "#f8f8ff"
+gold: "#ffd700"
+goldenrod: "#daa520"
+gray: "#808080"
+green: "#008000"
+greenyellow: "#adff2f"
+grey: "#808080"
+honeydew: "#f0fff0"
+hotpink: "#ff69b4"
+indianred: "#cd5c5c"
+indigo: "#4b0082"
+ivory: "#fffff0"
+khaki: "#f0e68c"
+lavender: "#e6e6fa"
+lavenderblush: "#fff0f5"
+lawngreen: "#7cfc00"
+lemonchiffon: "#fffacd"
+lightblue: "#add8e6"
+lightcoral: "#f08080"
+lightcyan: "#e0ffff"
+lightgoldenrodyellow: "#fafad2"
+lightgray: "#d3d3d3"
+lightgreen: "#90ee90"
+lightgrey: "#d3d3d3"
+lightpink: "#ffb6c1"
+lightsalmon: "#ffa07a"
+lightseagreen: "#20b2aa"
+lightskyblue: "#87cefa"
+lightslategray: "#778899"
+lightslategrey: "#778899"
+lightsteelblue: "#b0c4de"
+lightyellow: "#ffffe0"
+lime: "#00ff00"
+limegreen: "#32cd32"
+linen: "#faf0e6"
+magenta: "#ff00ff"
+maroon: "#800000"
+mediumaquamarine: "#66cdaa"
+mediumblue: "#0000cd"
+mediumorchid: "#ba55d3"
+mediumpurple: "#9370db"
+mediumseagreen: "#3cb371"
+mediumslateblue: "#7b68ee"
+mediumspringgreen: "#00fa9a"
+mediumturquoise: "#48d1cc"
+mediumvioletred: "#c71585"
+midnightblue: "#191970"
+mintcream: "#f5fffa"
+mistyrose: "#ffe4e1"
+moccasin: "#ffe4b5"
+navajowhite: "#ffdead"
+navy: "#000080"
+oldlace: "#fdf5e6"
+olive: "#808000"
+olivedrab: "#6b8e23"
+orange: "#ffa500"
+orangered: "#ff4500"
+orchid: "#da70d6"
+palegoldenrod: "#eee8aa"
+palegreen: "#98fb98"
+paleturquoise: "#afeeee"
+palevioletred: "#db7093"
+papayawhip: "#ffefd5"
+peachpuff: "#ffdab9"
+peru: "#cd853f"
+pink: "#ffc0cb"
+plum: "#dda0dd"
+powderblue: "#b0e0e6"
+purple: "#800080"
+rebeccapurple: "#663399"
+red: "#ff0000"
+rosybrown: "#bc8f8f"
+royalblue: "#4169e1"
+saddlebrown: "#8b4513"
+salmon: "#fa8072"
+sandybrown: "#f4a460"
+seagreen: "#2e8b57"
+seashell: "#fff5ee"
+sienna: "#a0522d"
+silver: "#c0c0c0"
+skyblue: "#87ceeb"
+slateblue: "#6a5acd"
+slategray: "#708090"
+slategrey: "#708090"
+snow: "#fffafa"
+springgreen: "#00ff7f"
+steelblue: "#4682b4"
+tan: "#d2b48c"
+teal: "#008080"
+thistle: "#d8bfd8"
+tomato: "#ff6347"
+transparent: "#00000000"
+turquoise: "#40e0d0"
+violet: "#ee82ee"
+wheat: "#f5deb3"
+white: "#ffffff"
+whitesmoke: "#f5f5f5"
+yellow: "#ffff00"
+yellowgreen: "#9acd32"

data/lib/tincture/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Tincture
+  # Loads the Active Model integration when a Rails app boots, before the
+  # app's own initializers and models.
+  class Railtie < Rails::Railtie
+    initializer 'tincture.active_model' do
+      require 'tincture/active_model'
+    end
+  end
+end

data/lib/tincture/type.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Tincture
+  # The `:color` (and `:colour`) attribute type. Casts input to a Color, and
+  # blank or unparseable input to `nil`.
+  #
+  # Stores `"#ff8800"`, or `"ff8800"` with `prefix: false`:
+  #
+  #     attribute :accent_color_hex, :color, prefix: false
+  class Type < ActiveModel::Type::Value
+    # `prefix: false` stores hex without the leading `#`.
+    #
+    #: (?prefix: bool, **untyped) -> void
+    def initialize(prefix: true, **)
+      @prefix = prefix
+      super(**)
+    end
+
+    def type = :color # :nodoc:
+
+    # The hex string to store, or `nil` for blank or unparseable input.
+    #
+    #: (untyped value) -> String?
+    def serialize(value)
+      hex = cast(value)&.hex
+      @prefix ? hex : hex&.delete_prefix('#')
+    end
+
+    private
+
+    def cast_value(value)
+      Color.parse(value)
+    rescue InvalidColor
+      nil
+    end
+  end
+end

data/lib/tincture/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tincture
+  VERSION = '1.0.0' # :nodoc:
+end

data/lib/tincture.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'tincture/version'
+require_relative 'tincture/difference'
+require_relative 'tincture/color'
+require_relative 'tincture/color/parsing'
+require_relative 'tincture/color/hsl'
+require_relative 'tincture/color/oklab'
+require_relative 'tincture/color/contrast'
+require_relative 'tincture/color/comparison'
+
+# Colour values for plain Ruby, with an optional Active Model integration.
+#
+# - Tincture::Color parses, converts and compares colours.
+# - Tincture::Type casts model attributes declared `:color` or `:colour`.
+# - ActiveModel::Validations::ColorValidator rejects input the type could not
+#   parse.
+#
+# The type and validator need `require "tincture/active_model"`. Rails apps
+# load it automatically.
+#
+# Every name has a UK alias: `Colour`, `InvalidColour`, `:colour`.
+module Tincture
+  Colour = Color
+  InvalidColour = InvalidColor
+end
+
+require_relative 'tincture/railtie' if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: tincture
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Andy Croll
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Parse hex, rgb() and hsl() colours into one value object, convert between
+  them, and cast model attributes to it with `attribute :accent, :color`.
+email:
+- andy@goodscary.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/tincture.rb
+- lib/tincture/active_model.rb
+- lib/tincture/color.rb
+- lib/tincture/color/comparison.rb
+- lib/tincture/color/contrast.rb
+- lib/tincture/color/hsl.rb
+- lib/tincture/color/oklab.rb
+- lib/tincture/color/parsing.rb
+- lib/tincture/color_validator.rb
+- lib/tincture/difference.rb
+- lib/tincture/named_colors.yml
+- lib/tincture/railtie.rb
+- lib/tincture/type.rb
+- lib/tincture/version.rb
+homepage: https://github.com/andycroll/tincture
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/andycroll/tincture
+  changelog_uri: https://github.com/andycroll/tincture/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Colour values for Ruby, with an optional Active Model attribute type
+test_files: []