utility_palettes 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 34b5bd3eb2c8d5da22989e14983ccb8e47eb9978f10d50bd8e2b5bf77c15e3d5
+  data.tar.gz: 0ff299a1d1f60b7f05111496023a23ced487f06c2ec38fcf750c94dc4e9bd1a1
+SHA512:
+  metadata.gz: 04c3c7333c77242ce88fcc0cbdf4aef4bf7ce0bda9e1fcf3f2c55a15c541f6767038d69b6036689dcef17c59b43444ebd0f80b392236d58a99c11efb2e447234
+  data.tar.gz: 2c40080c0e2aa1eb7746eadfebefa661007864c095d393de758167573354fd67a8e1dcf539fdc2a7203fdb1e758abbdcf1c2b57f5a1ff82e76bac226f387f6a4

data/README.md

@@ -0,0 +1,123 @@
+# UtilityPalettes
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/utility_palettes`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+> Generate your own colour palettes in an instance.
+
+Utility Palettes is an ruby gem package for use in ruby or other projects that generates palettes and shades based on supplied colours.
+Take a single colour and generate a full tailwind-style set of "absolute" shades ranging from -50 to -900 where the given colour is inserted into the range where it suits best.
+Or generate "relative" shades that have the supplied colour at it's core and add a -light and -dark shade.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add utility_palettes
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install utility_palettes
+```
+
+## Usage
+
+To get the config full of
+
+```bash
+rails generate utility_palettes:config
+```
+
+to generate the palettes
+
+```bash
+rails generate utility_palettes:generate
+```
+
+### Environment
+
+Set the environment that the sub-data will be read in, meaning that the palette generator can only be run in certain environments.
+
+### Defaults
+
+Should the default colours be included for the palette generator. Even if they are included, they can be overwritten by the user's own colour of the same name:
+
+| Option     | Default | Possible Values |
+| :--------- | :-----: | :-------------: |
+| absolutes  | true    | true / false    |
+| relatives  | true    | true / false    |
+| singles    | true    | true / false    |
+
+### Output
+
+How the output file and values should be written:
+
+| Option  | Description                                                                             | Default | Possible Values                                         |
+| :------ | :-------------------------------------------------------------------------------------- | :-----: | :-----------------------------------------------------: |
+| dated   | Should a timestamp be included in the filenames                                         | false   | true / false                                            |
+| files   | The types of files the palette should be output in, written as a comma separated string | json    | json, scss, css                                         |
+| format  | The colour syntax the output colours should be written in                               | rgb     | rgb, hsl, hsv, hsb, cmyk, cielab, lab, cielch, lch, hex |
+| prefix  | A string that is appended to the start of all colour names, i.e. 'tw-'                  | ''      | <any string>                                            |
+| suffix  | A string that is appended to the end of all colour names, i.e. '-col'                   | ''      | <any string>                                            |
+
+The JSON output file will appear at the top-level of your project, while SCSS and CSS are defined to go to `app/assets/stylesheets`.
+
+### Method (WIP)
+
+It allos you to determine how you want the colours to be adjusted to create the variance in your palette, but for now all colour adjustments are made by changing the HSL values as it is the best combination of the simple yet effective and accurate method available.
+In the future you will be able to shift the colours by changing values for different colour models and colour spaces; like RGB, CieLAB, OkLCH and others.
+
+### Steps (WIP)
+
+Defines the percentage you want each colour to be adjusted by when moving through the colour palette. For now all steps are for the HSL method of adjusting colours
+In the future you will be able to shift the colours by changing values for different colour models and colour spaces; like RGB, CieLAB, OkLCH and others.
+
+| Option  | Description                          | Default | Possible Values |
+| :------ | :----------------------------------: | :-----: | :-------------: |
+| h       | How much to adjust the hue by        | 0       | 0 - 100         |
+| s       | How much to adjust the saturation by | 2       | 0 - 100         |
+| l       | How much to adjust the lightness by  | 9       | 0 - 100         |
+
+### Absolutes
+
+Here you would define colour names and values that you would like to create an "absolute palette"; where for each colour given, a range of colours are output with -50, -100, ..., -900 suffixes using that colour as the base.
+
+### Relatives
+
+Here you would define colour names and values that you would like to create an "relative palette"; where for each colour given, a -light and -dark colour are generated one step up and down from the base colour.
+If a colour is included in both the "absolutes" and "relatives" sections, then the -light and -dark colours will match with colours in the absolute palette.
+
+### Singles
+
+Here you would define colour names and values that you would like copied directly to the output as you have defined them.
+
+## Pipeline
+
+Things that will hopefully be added in future development:
+
+- Finishing the overall palette spec file
+- Migrate off the reliance of Rails Generators
+- Different colour model and space methods for adapting colours, and the steps to go with them
+- Add more defaults such as different Tailwind version colours
+- Have a view that can be copied to apps to allow users the ability to quickly review the colours generated
+- Finish the '$' copy functionality to use colours defined in the config for other colours later in the generation process
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/louiswdavis/utility_palettes>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/louiswdavis/utility_palettes/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the UtilityPalettes project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/louiswdavis/utility_palettes/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/generators/templates/config/utility_palettes.yml

@@ -0,0 +1,36 @@
+development:
+  utility_palettes:
+    defaults:
+      absolutes: true
+      relatives: true
+      singles: true
+    output:
+      dated: false
+      files: 'json, scss, css'
+      format: 'hex'
+      prefix: ''
+      suffix: ''
+    method: 'hsl'
+    steps:
+      h: 0
+      s: 3
+      l: 8
+    absolutes:
+      teal: '#2cb1bc'
+      orange: '#e35f00'
+      green: '#28b840'
+      purple: '#4f3bbf'
+    relatives:
+      success: '#28b840'
+      information: '#2cb1bc'
+    singles:
+      grey-50: '#fafafa'
+      grey-100: '#f5f5f5'
+      grey-200: '#e5e5e5'
+      grey-300: '#d4d4d4'
+      grey-400: '#a3a3a3'
+      grey-500: '#737373'
+      grey-600: '#525252'
+      grey-700: '#404040'
+      grey-800: '#262626'
+      grey-900: '#171717'

data/lib/generators/utility_palettes/config_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module UtilityPalettes
+  module Generators
+    class ConfigGenerator < Rails::Generators::Base
+      source_root File.expand_path('../../..', __dir__)
+
+      def copy_config
+        copy_file 'lib/generators/templates/config/utility_palettes.yml', 'config/utility_palettes.yml'
+      end
+    end
+  end
+end

data/lib/generators/utility_palettes/generate_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module UtilityPalettes
+  module Generators
+    class GenerateGenerator < Rails::Generators::Base
+      def generate_utility_palettes
+        config = {}
+
+        if File.exist?('config/utility_palettes.yml') && defined?(Rails.application.config_for)
+          config = Rails.application.config_for(:utility_palettes).dig('utility_palettes')
+        elsif File.exist?('config/utility_palettes.json')
+          config = JSON.parse(File.read('config/utility_palettes.json')).dig(Rails.env.to_s, 'utility_palettes')
+        end
+
+        if !config.is_a?(Hash)
+          self.class.config_format_warn
+        elsif config.dig('disabled') == true
+          self.class.disabled_warn
+        else
+          UtilityPalettes::Palettes.generate(config)
+        end
+      end
+
+      private
+
+      def self.config_format_warn
+        warn 'ERROR: Utility Palettes config is not formatted as a hash for the "utility_palettes" value'
+      end
+
+      def self.disabled_warn
+        warn 'ERROR: Utility Palettes is disabled for this environment'
+      end
+    end
+  end
+end

data/lib/utility_palettes/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module UtilityPalettes
+  class Configuration
+    def self.setup(config)
+      # default increment steps
+      default_increments = UtilityPalettes::Configuration.defaults
+
+      user_increments = config.dig(:steps) || {}
+
+      h_step = user_increments.dig(:h) || default_increments.dig('hsl', :h)
+      s_step = user_increments.dig(:s) || default_increments.dig('hsl', :s)
+      l_step = user_increments.dig(:l) || default_increments.dig('hsl', :l)
+
+      { h_step: h_step, s_step: s_step, l_step: l_step }
+    end
+
+    def self.defaults
+      {
+        'rgb' => { r: '7%', g: '7%', b: '7%' },
+        'hsl' => { h: 0, s: 2, l: 9 }
+      }
+    end
+  end
+end

data/lib/utility_palettes/defaults.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module UtilityPalettes
+  class Defaults
+    def self.absolutes
+      {
+        'red' => 'hsl(2, 78%, 64%)',
+        'rust' => 'hsl(16, 82%, 62%)',
+        'orange' => 'hsl(31, 90%, 65%)',
+        'gold' => 'hsl(46, 93%, 54%)',
+        'yellow' => 'hsl(58, 87%, 55%)',
+        'pear' => 'hsl(80, 74%, 57%)',
+        'green' => 'hsl(110, 69%, 58%)',
+        'seaside' => 'hsl(156, 78%, 57%)',
+        'cyan' => 'hsl(180, 69%, 37%)',
+        'capri' => 'hsl(197, 90%, 46%)',
+        'blue' => 'hsl(214, 78%, 36%)',
+        'iris' => 'hsl(265, 87%, 57%)',
+        'purple' => 'hsl(279, 85%, 56%)',
+        'magenta' => 'hsl(300, 64%, 66%)',
+        'pink' => 'hsl(320, 74%, 66%)',
+        'satin' => 'hsl(348, 74%, 57%)',
+        'cement' => 'hsl(42, 6%, 87%)',
+        'grey' => 'hsl(0, 3%, 46%)',
+        'base' => 'hsl(0, 3%, 46%)'
+      }
+    end
+
+    def self.relatives
+      {
+        'success' => 'hsl(110, 69%, 58%)',
+        'danger' => 'hsl(2, 78%, 64%)',
+        'information' => 'hsl(214, 78%, 36%)',
+        'warning' => 'hsl(46, 93%, 54%)'
+      }
+    end
+
+    def self.singles
+      {
+        'white' => '#fff',
+        'black' => '#000',
+        'translucent' => 'rgba(0, 0, 0, 0.45)'
+      }
+    end
+  end
+end

data/lib/utility_palettes/outputs.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module UtilityPalettes
+  class Outputs
+    def self.generate(generated_palettes, config)
+      output_format = config.dig(:output, :format).to_s.downcase.presence
+      output_palettes = {}
+
+      generated_palettes.each do |label, colourize_colour|
+        case output_format
+        when 'rgb'
+          values = colourize_colour.rgb.values
+        when 'hsl'
+          values = colourize_colour.hsl.values
+          values[1] = self.append_percentage(values[1])
+          values[2] = self.append_percentage(values[2])
+        when 'hsv'
+          values = colourize_colour.hsv.values
+          values[1] = self.append_percentage(values[1])
+          values[2] = self.append_percentage(values[2])
+        when 'hsb'
+          values = colourize_colour.hsb.values
+          values[1] = self.append_percentage(values[1])
+          values[2] = self.append_percentage(values[2])
+        when 'cmyk'
+          values = colourize_colour.cmyk.values
+          values[1] = self.append_percentage(values[1])
+          values[2] = self.append_percentage(values[2])
+          values[3] = self.append_percentage(values[3])
+          output_format = 'device-cmyk'
+        when 'cielab', 'lab'
+          values = colourize_colour.cielab.values
+          values[0] = self.append_percentage(values[0])
+          output_format = 'lab'
+        when 'cielch', 'lch'
+          values = colourize_colour.cielch.values
+          values[0] = self.append_percentage(values[0])
+          output_format = 'lch'
+        when 'hex'
+          values = colourize_colour.hex
+        else
+          values = colourize_colour.rgb.values
+          output_format = 'rgb'
+        end
+
+        case output_format
+        when 'hex'
+          values += (colourize_colour.alpha * 255).round.to_s(16).slice(0, 2).upcase if colourize_colour.alpha < 1.0
+          output_palettes[label] = values
+        else
+          values << self.append_alpha(colourize_colour.alpha) if colourize_colour.alpha < 1.0
+          output_palettes[label] = "#{output_format}(#{values.join(' ')})"
+        end
+      end
+
+      output_palettes
+    end
+
+    def self.json(filename, output_palettes)
+      file = Tempfile.new([filename, '.json'])
+
+      File.open(file, 'w') do |f|
+        f.write(JSON.pretty_generate(output_palettes))
+      end
+
+      puts 'Exporting utility palettes JSON...'
+      file
+    end
+
+    def self.scss(filename, output_palettes)
+      file = Tempfile.new([filename, '.scss'])
+
+      File.open(file, 'w') do |f|
+        f.write(output_palettes.collect { |label, hex| "$#{label}: #{hex};" }.join("\n"))
+      end
+
+      puts 'Exporting utility palettes SCSS...'
+      file
+    end
+
+    def self.css(filename, output_palettes)
+      file = Tempfile.new([filename, '.css'])
+
+      File.open(file, 'w') do |f|
+        f.write(":root {\n\t#{output_palettes.collect { |label, hex| "--#{label}: #{hex};" }.join("\n\t")}\n}")
+      end
+
+      puts 'Exporting utility palettes CSS...'
+      file
+    end
+
+    def bespoke_property_variables
+      # const utilities = {
+      #   bg: (value) => ({ 'background-color': value }),
+      #   text: (value) => ({ 'color': value }),
+      #   border: (value) => ({ 'border-color': value }),
+      #   'border-t': (value) => ({ '--tw-border-opacity': 1, 'border-top-color': value }),
+      #   'border-r': (value) => ({ '--tw-border-opacity': 1, 'border-right-color': value }),
+      #   'border-b': (value) => ({ '--tw-border-opacity': 1, 'border-bottom-color': value }),
+      #   'border-l': (value) => ({ '--tw-border-opacity': 1, 'border-left-color': value }),
+      #   outline: (value) => ({ 'outline-color': value }),
+      #   ring: (value) => ({ '--tw-ring-opacity': 1, '--tw-ring-color': value }),
+      #   'ring-offset': (value) => ({ '--tw-ring-offset-color': value }),
+      #   'shadow': (value) => ({ '--tw-shadow-color': value, '--tw-shadow': 'var(--tw-shadow-colored)' }),
+      #   accent: (value) => ({ 'accent-color': value }),
+      #   caret: (value) => ({ 'caret-color': value }),
+      #   fill: (value) => ({ 'fill': value }),
+      #   stroke: (value) => ({ 'stroke': value }),
+      # };
+    end
+
+    private
+
+    def self.append_percentage(value)
+      "#{value}%"
+    end
+
+    def self.append_alpha(alpha)
+      "/ #{alpha * 100}"
+    end
+  end
+end

data/lib/utility_palettes/palettes.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module UtilityPalettes
+  class Palettes
+    def self.generate(config)
+      @config = config
+
+      puts 'Generating utility palettes...'
+
+      UtilityPalettes::Validations.validate_config(@config)
+      @increment_steppers = UtilityPalettes::Configuration.setup(@config)
+
+      puts 'Retrieved configuration...'
+
+      default_absolutes = @config.dig(:defaults, :absolutes) == false ? [] : UtilityPalettes::Defaults.absolutes
+      default_relatives = @config.dig(:defaults, :relatives) == false ? [] : UtilityPalettes::Defaults.relatives
+      default_singles = @config.dig(:defaults, :singles) == false ? [] : UtilityPalettes::Defaults.singles
+
+      puts 'Defined default palettes...'
+
+      user_absolutes = @config.dig(:absolutes) || {}
+      user_relatives = @config.dig(:relatives) || {}
+      user_singles = @config.dig(:singles) || {}
+
+      puts 'Retrieved user palettes...'
+
+      # merging should mean any user colours will overwrite default colours with the same key names
+      combined_absolutes = default_absolutes.merge(user_absolutes)
+      combined_relatives = default_relatives.merge(user_relatives)
+      combined_singles = {}.merge(default_absolutes, user_absolutes, default_singles, user_singles)
+
+      @combined_samples = combined_absolutes.merge(combined_relatives).merge(combined_singles)
+
+      puts 'Merged palettes...'
+
+      converted_absolutes = self.colourize_values(combined_absolutes)
+      converted_relatives = self.colourize_values(combined_relatives)
+      converted_singles = self.colourize_values(combined_singles)
+
+      puts 'Converted palettes...'
+
+      generated_absolutes = self.palette_looper(converted_absolutes, 'absolutes')
+      generated_relatives = self.palette_looper(converted_relatives, 'relatives')
+      generated_singles = converted_singles
+
+      puts 'Generated utility palettes...'
+
+      generated_palettes = {}.merge(generated_absolutes, generated_relatives, generated_singles)
+      generated_palettes = self.format_palette(generated_palettes)
+      output_palettes = UtilityPalettes::Outputs.generate(generated_palettes, @config)
+
+      filename = 'utility_palettes'
+      filename += "-#{Time.zone.now.strftime('%Y%m%d-%H%M%S')}" if @config.dig(:output, :dated) == true
+
+      output_files = (@config.dig(:output, :files) || '').split(',').map(&:strip)
+
+      file = nil
+      file = UtilityPalettes::Outputs.json(filename, output_palettes) if output_files.blank? || output_files.include?('json')
+      File.rename(file.path, "#{filename}.json") if file.present?
+      
+      file = nil
+      file = UtilityPalettes::Outputs.scss(filename, output_palettes) if output_files.include?('scss')
+      File.rename(file.path, "app/assets/stylesheets/#{filename}.scss") if file.present?
+
+      file = nil
+      file = UtilityPalettes::Outputs.css(filename, output_palettes) if output_files.include?('css')
+      File.rename(file.path, "app/assets/stylesheets/#{filename}.css") if file.present?
+
+      true
+    end
+
+    private
+
+    def self.colourize_values(colour_hash)
+      colourized_hash = {}
+
+      colour_hash.each do |label, colour|
+        begin
+          if colour.start_with?('$')
+            # if the colour label begins with $ then it is a reference to a different defined colour, so must be looked up in the main
+            colourized_hash[label] = ColorConverters::Color.new(@combined_samples.dig(colour[1..].to_sym))
+          else
+            colourized_hash[label] = ColorConverters::Color.new(colour)
+          end
+
+          # TODO
+          # provide a name if the label is left blank
+          # if label.to_s == '$blank'
+          #   hash[colourized_hash[label].name] = hash.delete(label)
+          #   puts "Blank colour #{colour} has been given the name: #{colourized_hash[label].name}"
+          # end
+        rescue ColorConverters::InvalidColorError => e
+          warn "Error processing colour #{label} with value #{colour}: #{e.message}"
+        end
+      end
+
+      colourized_hash
+    end
+
+    # * Palettes
+
+    # ? Multiple Colour's Palette
+    # a function to loop through a map of colours and create absolute or relative palettes for them all and collect this into a single map
+
+    def self.palette_looper(colour_map, method)
+      looped_generated_palettes = {}
+
+      colour_map.each do |label, base_colour|
+        # create a palette for a single colour from the providing mapping
+        if method == 'absolutes'
+          generated_swatches = UtilityPalettes::Swatch.absolute_generator(label, base_colour, @config.dig(:method), @increment_steppers)
+        elsif method == 'relatives'
+          generated_swatches = UtilityPalettes::Swatch.relative_generator(label, base_colour, @config.dig(:method), @increment_steppers)
+        end
+
+        # merge the colours absolute palette into the collective mapping
+        looped_generated_palettes = {}.merge(looped_generated_palettes, generated_swatches)
+      end
+
+      looped_generated_palettes
+    end
+
+    def self.format_palette(palettes)
+      palettes.compact_blank!
+
+      palettes.transform_keys!(&:to_s)
+      palettes.transform_keys! { |key| @config.dig(:output, :prefix) + key } if @config.dig(:output, :prefix).present?
+      palettes.transform_keys! { |key| key + @config.dig(:output, :suffix) } if @config.dig(:output, :suffix).present?
+
+      palettes
+    end
+  end
+end

data/lib/utility_palettes/sequences.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'color_converters'
+require 'bigdecimal'
+
+# an increase in the 'level' makes the percieved colour darker
+
+module UtilityPalettes
+  class Sequences
+    def self.hsl(colour, level_change, increment_steppers)
+      h_step = increment_steppers[:h_step]
+      s_step = increment_steppers[:s_step]
+      l_step = increment_steppers[:l_step]
+
+      # Use BigDecimal for precise decimal arithmetic
+      h_value = (BigDecimal(colour.hsl[:h].to_s) - BigDecimal((level_change * h_step).to_s)) % 360
+      s_value = (BigDecimal(colour.hsl[:s].to_s) - BigDecimal((level_change * s_step).to_s)).clamp(0, 100)
+      l_value = (BigDecimal(colour.hsl[:l].to_s) - BigDecimal((level_change * l_step).to_s)).clamp(0, 100)
+
+      ColorConverters::Color.new(h: h_value.to_f, s: s_value.to_f, l: l_value.to_f)
+    end
+
+    def self.rgb(colour, level_change, increment_steppers)
+      r_step = increment_steppers[:r_step] || increment_steppers[:rgb_step]
+      g_step = increment_steppers[:g_step] || increment_steppers[:rgb_step]
+      b_step = increment_steppers[:b_step] || increment_steppers[:rgb_step]
+
+      # Use BigDecimal for precise decimal arithmetic
+      r_value = (BigDecimal(colour.rgb[:r].to_s) - BigDecimal((level_change * r_step).to_s)).clamp(0, 255).to_f
+      g_value = (BigDecimal(colour.rgb[:g].to_s) - BigDecimal((level_change * g_step).to_s)).clamp(0, 255).to_f
+      b_value = (BigDecimal(colour.rgb[:b].to_s) - BigDecimal((level_change * b_step).to_s)).clamp(0, 255).to_f
+
+      ColorConverters::Color.new(r: r_value, g: g_value, b: b_value)
+    end
+
+    def tailwind(_colour, _step, _go_lighter, _increment_steppers)
+      # def pSBC(p, _c0, _c1, l)
+      #   r = nil
+      #   g = nil
+      #   b = nil
+      #   pP = nil
+      #   f = nil
+      #   t = nil
+
+      #   if l
+      #     pPr = pP * f[:r]
+      #     f[:g]
+      #     pPb = pP * f[:b]
+
+      #     ptr = p * t[:r]
+      #     t[:g]
+      #     ptb = p * t[:b]
+
+      #     r = (pPr + ptr).round
+      #     g = (pPb + ptb).round
+      #     b = (pPb + ptb).round
+      # else
+      #   pPr = pP * (f[:r]**2)
+      #   pPg = pP * (f[:g]**2)
+      #   pPb = pP * (f[:b]**2)
+
+      #   ptr = p * (t[:r]**2)
+      #   ptg = p * (t[:g]**2)
+      #   ptb = p * (t[:b]**2)
+
+      #   r = ((pPr + ptr)**0.5).round
+      #   g = ((pPg + ptg)**0.5).round
+      #   b = ((pPb + ptb)**0.5).round
+      # end
+
+      # a = f.a
+      # t = t.a
+      # f = a >= 0 || t >= 0
+
+      # t if f && a.negative?
+
+      # a = if f
+      #       if a.negative?
+      #         t
+      #       else
+      #         t.negative? ? a : a * pP + t * p
+      #       end
+      #     else
+      #       0
+      #     end
+
+      ColorConverters::Color.new(r: r, g: g, b: b, a: m(a * 1000) / 1000)
+    end
+  end
+end

data/lib/utility_palettes/swatch.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module UtilityPalettes
+  class Swatch
+    # ? Single Colour's Palette
+    # a function to create an absolute palette that incorporates a single colour input
+    def self.absolute_generator(label, base_colour, method, increment_steppers)
+      @method = method
+      @increment_steppers = increment_steppers
+
+      # colours are index inversely to their lightness
+      base_level = UtilityPalettes::Swatch.base_lightness_index(base_colour)
+      generated_absolute_swatches = {}.merge({ UtilityPalettes::Swatch.label(label, base_level) => base_colour })
+
+      # # Lighter colours
+      # # calc the space available to create lightened colours based off the base colour
+      # if base_level.positive?
+      #   (0..base_level).each do |new_level|
+      #     new_colour = UtilityPalettes::Swatch.generate(base_colour, base_level, new_level)
+      #     generated_absolute_swatches = {}.merge(generated_absolute_swatches, { UtilityPalettes::Swatch.label(label, new_level) => new_colour })
+      #   end
+      # end
+
+      # # Darker colours
+      # # calc the space available to create darkened colours based off the base colour
+      # if base_level < 9
+      #   (base_level..9).each do |new_level|
+      #     new_colour = UtilityPalettes::Swatch.generate(base_colour, base_level, new_level)
+      #     generated_absolute_swatches = {}.merge(generated_absolute_swatches, { UtilityPalettes::Swatch.label(label, new_level) => new_colour })
+      #   end
+      # end
+
+      if base_level.positive?
+        (0..9).each do |new_level|
+          new_colour = UtilityPalettes::Swatch.generate(base_colour, base_level, new_level)
+          generated_absolute_swatches = {}.merge(generated_absolute_swatches, { UtilityPalettes::Swatch.label(label, new_level) => new_colour })
+        end
+      end
+
+      generated_absolute_swatches
+    end
+
+    # ? Single Colour's Relative Palette
+    # a function to create a relative palette centred on a single colour input
+    def self.relative_generator(label, base_colour, method, increment_steppers)
+      @method = method
+      @increment_steppers = increment_steppers
+
+      lighter_colour = nil
+      darker_colour = nil
+
+      # colours are index inversely to their lightness
+      base_level = UtilityPalettes::Swatch.base_lightness_index(base_colour)
+      generated_relative_swatches = {}.merge({ label => base_colour })
+
+      # Lighter Colour
+      if base_level > 1
+        lighter_colour = UtilityPalettes::Swatch.generate(base_colour, base_level, base_level + 2)
+      elsif base_level > 0
+        lighter_colour = UtilityPalettes::Swatch.generate(base_colour, base_level, base_level + 1)
+      else
+        lighter_colour = nil
+      end
+
+      # Darker Colour
+      if base_level < 8
+        darker_colour = UtilityPalettes::Swatch.generate(base_colour, base_level, base_level - 2)
+      elsif base_level < 9
+        darker_colour = UtilityPalettes::Swatch.generate(base_colour, base_level, base_level - 1)
+      else
+        darker_colour = nil
+      end
+
+      generated_relative_swatches = {}.merge(generated_relative_swatches, { "#{label}-light" => lighter_colour })
+      generated_relative_swatches = {}.merge(generated_relative_swatches, { "#{label}-dark" => darker_colour })
+
+      generated_relative_swatches
+    end
+
+    def self.base_lightness_index(colour)
+      9 - (colour.hsl[:l] / 10).floor
+    end
+
+    def self.label(label, index)
+      levels = { '0' => 50, '1' => 100, '2' => 200, '3' => 300, '4' => 400, '5' => 500, '6' => 600, '7' => 700, '8' => 800, '9' => 900 }
+
+      [label, levels.dig(index.to_s)].join('-')
+    end
+
+    # TODO: create other sequence methods
+    # ? How to Calculate the next colour in the Palette
+    def self.generate(colour, base_level, new_level)
+      case @method
+      when 'hsl'
+        UtilityPalettes::Sequences.hsl(colour, new_level - base_level, @increment_steppers)
+      when 'rgb'
+        # TODO
+      else
+        UtilityPalettes::Sequences.hsl(colour, new_level - base_level, @increment_steppers)
+      end
+    end
+
+    def build_step_check
+      # const ALL_LEVELS = [50, 100, 200, 300, 400, 600, 700, 800, 900];
+      # const levels = options.levels == null ? ALL_LEVELS : options.levels.filter(level => ALL_LEVELS.includes(level));
+    end
+  end
+end

data/lib/utility_palettes/validations.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module UtilityPalettes
+  class Validations
+    def self.validate_config(config)
+      sequence_options = ['hsl']
+      warn "ERROR: The colour sequence method you have submitted to Utility Palettes < #{config[:steps]} > is not available (#{sequence_options.to_sentence})" if !config[:method].nil? && !config[:method].to_s.in?(sequence_options)
+
+      warn "ERROR: The colour sequence steps you have submitted to Utility Palettes < #{config[:steps]} > have not been formatted as a hash" if !config[:steps].nil? && !config[:steps].is_a?(Hash)
+
+      warn "ERROR: The absolute swatches you have submitted to Utility Palettes < #{config[:absolutes]} > have not been formatted as a hash" if !config[:absolutes].nil? && !config[:absolutes].is_a?(Hash)
+
+      warn "ERROR: The relative swatches you have submitted to Utility Palettes < #{config[:relatives]} > have not been formatted as a hash" if !config[:relatives].nil? && !config[:relatives].is_a?(Hash)
+
+      warn "ERROR: The single swatches you have submitted to Utility Palettes < #{config[:singles]} > have not been formatted as a hash" if !config[:singles].nil? && !config[:singles].is_a?(Hash)
+
+      config_keys = config.keys - [:defaults, :output, :method, :steps, :absolutes, :relatives, :singles, :disabled]
+
+      warn "WARNING: Utility Palettes does not recognize the following keys; #{config_keys.join(', ')}. Please check they match the spelling of documented palette keys in order for them to be used." if config_keys.present?
+
+      true
+    end
+  end
+end

data/lib/utility_palettes/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module UtilityPalettes
+  VERSION = '0.1.0'
+end

data/lib/utility_palettes.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'utility_palettes/version'
+
+require_relative 'utility_palettes/configuration'
+require_relative 'utility_palettes/defaults'
+require_relative 'utility_palettes/outputs'
+require_relative 'utility_palettes/palettes'
+require_relative 'utility_palettes/sequences'
+require_relative 'utility_palettes/swatch'
+require_relative 'utility_palettes/validations'
+
+module UtilityPalettes
+  class Error < StandardError; end
+  # Your code goes here...
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: utility_palettes
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Louis Davis
+bindir: bin
+cert_chain: []
+date: 2025-08-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: color_converters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+description: Create broad colour palettes based on specific colour swatches, or more
+  specific light/dark variant palettes. Be in control of the colours you use and shorten
+  the iterative process when deciding on how to build your palettes.
+email:
+- LouisWilliamDavis@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/generators/templates/config/utility_palettes.yml
+- lib/generators/utility_palettes/config_generator.rb
+- lib/generators/utility_palettes/generate_generator.rb
+- lib/utility_palettes.rb
+- lib/utility_palettes/configuration.rb
+- lib/utility_palettes/defaults.rb
+- lib/utility_palettes/outputs.rb
+- lib/utility_palettes/palettes.rb
+- lib/utility_palettes/sequences.rb
+- lib/utility_palettes/swatch.rb
+- lib/utility_palettes/validations.rb
+- lib/utility_palettes/version.rb
+homepage: https://github.com/louiswdavis/utility_palettes
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/louiswdavis/utility_palettes
+  source_code_uri: https://github.com/louiswdavis/utility_palettes
+  changelog_uri: https://github.com/louiswdavis/utility_palettes/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Quickly build colour palettes based on default or supplied colour swatches,
+  and export them for use in stylesheets.
+test_files: []