RubyGems - keystone_ui-colors - Versions diffs - 0.2.0 - Mend

keystone_ui-colors 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

checksums.yaml +7 -0
data/MIT-LICENSE +20 -0
data/README.md +198 -0
data/Rakefile +11 -0
data/app/controllers/concerns/keystone_ui/colors/current_palette.rb +91 -0
data/app/controllers/keystone_ui/colors/application_controller.rb +12 -0
data/app/controllers/keystone_ui/colors/settings_controller.rb +53 -0
data/app/helpers/keystone_ui/colors/palette_helper.rb +14 -0
data/app/javascript/keystone_ui/colors/theme_settings_controller.js +50 -0
data/app/models/keystone_ui/colors/application_record.rb +7 -0
data/app/models/keystone_ui/colors/theme_preference.rb +47 -0
data/app/views/keystone_ui/colors/settings/show.html.erb +99 -0
data/config/routes.rb +5 -0
data/lib/generators/keystone_ui/colors/install/install_generator.rb +49 -0
data/lib/generators/keystone_ui/colors/install/templates/create_keystone_ui_colors_theme_preferences.rb.erb +15 -0
data/lib/generators/keystone_ui/colors/update/templates/add_mode_to_keystone_ui_colors_theme_preferences.rb.erb +5 -0
data/lib/generators/keystone_ui/colors/update/update_generator.rb +30 -0
data/lib/keystone_ui/colors/configuration.rb +31 -0
data/lib/keystone_ui/colors/engine.rb +23 -0
data/lib/keystone_ui/colors/palettes.rb +72 -0
data/lib/keystone_ui/colors/templates.rb +63 -0
data/lib/keystone_ui/colors/version.rb +7 -0
data/lib/keystone_ui/colors.rb +11 -0
data/lib/keystone_ui-colors.rb +1 -0
metadata +129 -0

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a6fe78366470d37cb8598bfa4181561c42eca52a409dd7648246c397584daad9
+  data.tar.gz: dbbcf12bbc4fd745c85cf35a94d0608cabfa9565e7a92e87eb22a5a5faa17f01
+SHA512:
+  metadata.gz: 9764dcad37f39f954cc377abf737bad185b2ee9e1e0ce301982bd6a52d286a0069ca8513b5afb918df2411475b40040646c5e605a6c384edf8b88e3f3c5c4d9b
+  data.tar.gz: 60f59e26247a9580e2422d873f0e8cb4d4daa2b9aecd5dda755972b76f7dbfb46be9cf07bed75954fb2ee591a0699ac94285e65ebf445611a8f8443e84ada4a9

data/MIT-LICENSE ADDED Viewed

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Tyler Schneider
+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 ADDED Viewed

@@ -0,0 +1,198 @@
+# KeystoneUi::Colors
+A Rails engine that adds per-user color palette persistence and preset themes. Companion to [keystone_ui](https://github.com/DYB-Development/keystone_ui).
+Users pick from preset themes or custom hex colors. The gem generates CSS custom properties (`--color-accent-*`, `--color-surface-*`) and injects them via a `<style>` tag -- no frontend build step required.
+## Requirements
+- Ruby >= 3.1
+- Rails >= 7.0
+- [keystone_ui](https://github.com/DYB-Development/keystone_ui) >= 0.4.1
+## Installation
+Add to your Gemfile:
+```ruby
+gem "keystone_ui-colors"
+```
+Run the install generator:
+```bash
+bin/rails generate keystone_ui:colors:install
+bin/rails db:migrate
+```
+This creates:
+- A migration for `keystone_ui_colors_theme_preferences`
+- A Stimulus controller at `app/javascript/controllers/keystone_ui/colors/theme_settings_controller.js`
+### Manual setup
+**1. Mount the engine** in `config/routes.rb`:
+```ruby
+mount KeystoneUi::Colors::Engine => "/keystone_ui_colors"
+```
+**2. Include the concern** in your `ApplicationController`:
+```ruby
+class ApplicationController < ActionController::Base
+  include KeystoneUi::Colors::CurrentPalette
+  before_action :set_current_palette
+end
+```
+**3. Add the style tag** to your layout (`<head>`):
+```erb
+<%= keystone_palette_style_tag %>
+```
+This outputs CSS variables:
+```css
+:root {
+  --color-accent-50: #eff6ff;
+  --color-accent-100: #dbeafe;
+  /* ... through 950 */
+  --color-surface-50: #f8fafc;
+  /* ... through 950 */
+}
+```
+**4. Register the Stimulus controller** in `app/javascript/controllers/index.js`:
+```js
+import ThemeSettingsController from "./keystone_ui/colors/theme_settings_controller"
+application.register("keystone-ui--colors--theme-settings", ThemeSettingsController)
+```
+## Configuration
+Create `config/initializers/keystone_ui_colors.rb`:
+```ruby
+KeystoneUi::Colors.configure do |config|
+  config.owner_class_name = "User"            # Model that owns preferences
+  config.current_owner_method = :current_user  # Controller method for current user
+  config.default_template = :ocean             # Fallback theme
+  config.default_accent = "blue"               # Fallback accent color
+  config.default_surface = "zinc"              # Fallback surface color
+  config.default_mode = "light"                # Fallback theme mode: "light", "dark" or "system"
+  config.layout = "application"                # Layout for settings page
+end
+```
+All values shown are defaults and can be omitted.
+## Light and Dark Mode
+Users choose Light, Dark or System on the settings page, and the choice is saved
+with their palette. keystone_ui renders each page in, strongest first:
+1. The choice made with keystone_ui's `ui_theme_toggle` in this browser.
+2. The mode the signed-in user saved.
+3. `config.default_mode`, for users who saved none and for visitors who are not signed in.
+Saving a mode on the settings page clears the toggle's choice in that browser, so the
+saved mode takes effect. Pages are marked through keystone_ui's
+`keystone_theme_attributes` helper on the layout's `html` tag.
+## Preset Themes
+| Name     | Accent  | Surface | Description                    |
+|----------|---------|---------|--------------------------------|
+| Default  | *(configured)* | *(configured)* | Uses config defaults |
+| Ocean    | blue    | slate   | Cool blues with slate undertones |
+| Forest   | emerald | stone   | Natural greens with warm stone   |
+| Twilight | violet  | zinc    | Deep violet with clean zinc      |
+| Coral    | rose    | neutral | Warm rose with neutral balance   |
+| Arctic   | cyan    | gray    | Bright cyan with crisp gray      |
+## Available Colors
+**Accents:** blue, emerald, cyan, indigo, violet, rose
+**Surfaces:** zinc, slate, gray, neutral, stone
+Each color includes shades 50 through 950 (Tailwind scale). Users can also pick arbitrary hex colors -- the gem generates a full shade palette automatically.
+## Custom Owner Models
+The owner association is polymorphic:
+```ruby
+KeystoneUi::Colors.configure do |config|
+  config.owner_class_name = "Account"
+  config.current_owner_method = :current_account
+end
+```
+## Using the CSS Variables
+```css
+.btn-primary {
+  background-color: var(--color-accent-500);
+  color: white;
+}
+.page-bg {
+  background-color: var(--color-surface-50);
+}
+.sidebar {
+  background-color: var(--color-surface-900);
+  color: var(--color-surface-100);
+}
+```
+## Engine Routes
+| Method | Path | Action |
+|--------|------|--------|
+| GET    | /    | Settings page |
+| PATCH  | /    | Update preference |
+| DELETE | /    | Reset to default |
+## API Reference
+### `KeystoneUi::Colors::Palettes`
+```ruby
+KeystoneUi::Colors::Palettes.accent(:blue)             # => { 50 => "#eff6ff", ..., 950 => "#172554" }
+KeystoneUi::Colors::Palettes.surface(:zinc)             # => { 50 => "#fafafa", ..., 950 => "#09090b" }
+KeystoneUi::Colors::Palettes.generate_shades("#8b5cf6")  # => full shade palette from hex
+```
+### `KeystoneUi::Colors::Templates`
+```ruby
+KeystoneUi::Colors::Templates.names      # => [:default, :ocean, :forest, :twilight, :coral, :arctic]
+KeystoneUi::Colors::Templates[:ocean]    # => { accent: :blue, surface: :slate, label: "Ocean", ... }
+KeystoneUi::Colors::Templates.all        # => Hash of all templates
+```
+### `KeystoneUi::Colors::ThemePreference`
+```ruby
+pref = KeystoneUi::Colors::ThemePreference.find_by(owner: current_user)
+pref.apply_template!(:forest)
+```
+Accepts named colors (`"blue"`) or hex values (`"#3b82f6"`) for `accent` and `surface`.
+## Updating
+Run the update generator to get the latest Stimulus controller and any new migrations, then migrate:
+```bash
+bin/rails generate keystone_ui:colors:update
+```
+## License
+MIT License. See [MIT-LICENSE](MIT-LICENSE).

data/Rakefile ADDED Viewed

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+require "rake/testtask"
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+task default: :test

data/app/controllers/concerns/keystone_ui/colors/current_palette.rb ADDED Viewed

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+require "active_support/concern"
+module KeystoneUi
+  module Colors
+    module CurrentPalette
+      extend ActiveSupport::Concern
+      included do
+        helper_method :keystone_palette_css, :keystone_theme_mode if respond_to?(:helper_method)
+      end
+      def set_current_palette
+        owner = send(KeystoneUi::Colors.configuration.current_owner_method)
+        unless owner
+          @keystone_theme_mode = KeystoneUi::Colors.configuration.default_mode
+          build_palette_css(
+            KeystoneUi::Colors.configuration.default_accent,
+            KeystoneUi::Colors.configuration.default_surface
+          )
+          return
+        end
+        cached = session[:keystone_ui_colors_palette]
+        if cached && !stale_cache?(owner, cached)
+          @keystone_theme_mode = cached[:mode] || KeystoneUi::Colors.configuration.default_mode
+          build_palette_css(cached[:accent], cached[:surface])
+          return
+        end
+        preference = KeystoneUi::Colors::ThemePreference.find_by(owner: owner)
+        @keystone_theme_mode = preference&.mode || KeystoneUi::Colors.configuration.default_mode
+        accent = preference&.accent || KeystoneUi::Colors.configuration.default_accent
+        surface = preference&.surface || KeystoneUi::Colors.configuration.default_surface
+        build_palette_css(accent, surface)
+        if preference
+          session[:keystone_ui_colors_palette] = {
+            accent: preference.accent,
+            surface: preference.surface,
+            mode: preference.mode,
+            updated_at: preference.updated_at.to_i
+          }
+        end
+      end
+      def keystone_palette_css
+        @keystone_palette_css
+      end
+      def keystone_theme_mode
+        @keystone_theme_mode
+      end
+      private
+      def build_palette_css(accent, surface)
+        accent_shades = resolve_shades(accent, :accent)
+        surface_shades = resolve_shades(surface, :surface)
+        lines = []
+        accent_shades.each { |shade, hex| lines << "  --color-accent-#{shade}: #{hex};" }
+        surface_shades.each { |shade, hex| lines << "  --color-surface-#{shade}: #{hex};" }
+        @keystone_palette_css = ":root {\n#{lines.join("\n")}\n}"
+      end
+      def resolve_shades(value, type)
+        if value&.start_with?("#")
+          KeystoneUi::Colors::Palettes.generate_shades(value)
+        else
+          (type == :accent) ? KeystoneUi::Colors::Palettes.accent(value) : KeystoneUi::Colors::Palettes.surface(value)
+        end
+      end
+      def stale_cache?(owner, cached)
+        updated_at = KeystoneUi::Colors::ThemePreference
+          .where(owner: owner)
+          .pick(:updated_at)
+        return true unless updated_at
+        updated_at.to_i != cached[:updated_at]
+      end
+    end
+  end
+end

data/app/controllers/keystone_ui/colors/application_controller.rb ADDED Viewed

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module KeystoneUi
+  module Colors
+    class ApplicationController < ::ApplicationController
+      before_action { send(KeystoneUi::Colors.configuration.authentication_method) }
+      helper KeystoneUiHelper
+      layout -> { KeystoneUi::Colors.configuration.layout }
+    end
+  end
+end

data/app/controllers/keystone_ui/colors/settings_controller.rb ADDED Viewed

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+module KeystoneUi
+  module Colors
+    class SettingsController < ApplicationController
+      def show
+        @preference = theme_preference
+      end
+      def destroy
+        ThemePreference.find_by(owner: current_owner)&.destroy
+        redirect_to keystone_ui_colors.settings_path, notice: "Color settings reset to default."
+      end
+      def update
+        @preference = theme_preference
+        if preference_params[:template_name].present?
+          template = Templates[preference_params[:template_name]]
+          @preference.assign_attributes(
+            accent: template[:accent].to_s,
+            surface: template[:surface].to_s,
+            template_name: preference_params[:template_name],
+            mode: preference_params[:mode]
+          )
+        else
+          @preference.assign_attributes(preference_params)
+        end
+        if @preference.save
+          cookies.delete(KeystoneUi::ThemeChoice::COOKIE)
+          redirect_to keystone_ui_colors.settings_path, notice: "Color settings updated."
+        else
+          render :show, status: :unprocessable_entity
+        end
+      end
+      private
+      def current_owner
+        send(KeystoneUi::Colors.configuration.current_owner_method)
+      end
+      def theme_preference
+        ThemePreference.find_or_initialize_by(owner: current_owner)
+      end
+      def preference_params
+        params.require(:theme_preference).permit(:accent, :surface, :template_name, :mode)
+      end
+    end
+  end
+end

data/app/helpers/keystone_ui/colors/palette_helper.rb ADDED Viewed

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+module KeystoneUi
+  module Colors
+    module PaletteHelper
+      def keystone_palette_style_tag
+        css = keystone_palette_css
+        return unless css
+        content_tag(:style, css)
+      end
+    end
+  end
+end

data/app/javascript/keystone_ui/colors/theme_settings_controller.js ADDED Viewed

@@ -0,0 +1,50 @@
+import { Controller } from "@hotwired/stimulus"
+export default class extends Controller {
+  static targets = ["accentPicker", "surfacePicker", "customRadio", "templateLabel"]
+  connect() {
+    this.accentPickerTarget.addEventListener("change", () => this.customColorChanged())
+    this.surfacePickerTarget.addEventListener("change", () => this.customColorChanged())
+  }
+  selectTemplate(event) {
+    const input = event.currentTarget
+    const label = input.closest("[data-template]")
+    const accentHex = input.dataset.accentHex
+    const surfaceHex = input.dataset.surfaceHex
+    this.setPickerValue(this.accentPickerTarget, accentHex)
+    this.setPickerValue(this.surfacePickerTarget, surfaceHex)
+    this.highlightTemplate(label.dataset.template)
+  }
+  customColorChanged() {
+    if (this.hasCustomRadioTarget) this.customRadioTarget.checked = true
+    this.highlightTemplate("custom")
+  }
+  highlightTemplate(selected) {
+    this.templateLabelTargets.forEach(label => {
+      const border = label.querySelector("span")
+      if (label.dataset.template === selected) {
+        border.classList.remove("border-transparent")
+        border.classList.add("border-accent-500")
+      } else {
+        border.classList.remove("border-accent-500")
+        border.classList.add("border-transparent")
+      }
+    })
+  }
+  setPickerValue(wrapper, hex) {
+    const input = wrapper.querySelector("input[type='hidden']")
+    const swatch = wrapper.querySelector("[data-color-picker-target='swatch']")
+    const hexLabel = wrapper.querySelector("[data-color-picker-target='hexLabel']")
+    if (input) input.value = hex
+    if (swatch) swatch.style.backgroundColor = hex
+    if (hexLabel) hexLabel.textContent = hex
+  }
+}

data/app/models/keystone_ui/colors/application_record.rb ADDED Viewed

@@ -0,0 +1,7 @@
+module KeystoneUi
+  module Colors
+    class ApplicationRecord < ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/app/models/keystone_ui/colors/theme_preference.rb ADDED Viewed

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+module KeystoneUi
+  module Colors
+    class ThemePreference < ApplicationRecord
+      self.table_name = "keystone_ui_colors_theme_preferences"
+      belongs_to :owner, polymorphic: true
+      SUPPORTED_ACCENTS = %w[blue emerald cyan indigo violet rose].freeze
+      SUPPORTED_SURFACES = %w[zinc slate gray neutral stone].freeze
+      HEX_COLOR = /\A#[0-9a-fA-F]{6}\z/
+      MODES = %w[light dark system].freeze
+      validate :accent_is_valid
+      validate :surface_is_valid
+      validates :template_name, inclusion: { in: Templates.names.map(&:to_s) }, allow_blank: true
+      validates :mode, inclusion: { in: MODES }, allow_nil: true
+      def apply_template!(name)
+        template = Templates[name]
+        update!(
+          accent: template[:accent].to_s,
+          surface: template[:surface].to_s,
+          template_name: name.to_s
+        )
+      end
+      private
+      def accent_is_valid
+        return if SUPPORTED_ACCENTS.include?(accent) || accent&.match?(HEX_COLOR)
+        errors.add(:accent, "must be a supported color name or hex value")
+      end
+      def surface_is_valid
+        return if SUPPORTED_SURFACES.include?(surface) || surface&.match?(HEX_COLOR)
+        errors.add(:surface, "must be a supported color name or hex value")
+      end
+    end
+  end
+end

data/app/views/keystone_ui/colors/settings/show.html.erb ADDED Viewed

@@ -0,0 +1,99 @@
+<%= ui_page_header(title: "Color Settings") %>
+<% if flash[:notice] %>
+  <%= ui_alert(message: flash[:notice], type: :success) %>
+<% end %>
+<%
+  current_accent_hex = if @preference.accent&.start_with?("#")
+    @preference.accent
+  else
+    KeystoneUi::Colors::Palettes.accent(@preference.accent || "blue")[500]
+  end
+  current_surface_hex = if @preference.surface&.start_with?("#")
+    @preference.surface
+  else
+    KeystoneUi::Colors::Palettes.surface(@preference.surface || "zinc")[500]
+  end
+  selected_template = @preference.template_name
+  custom_selected = @preference.accent&.start_with?("#") || (selected_template.blank? && @preference.persisted?)
+%>
+<%= ui_panel(padding: :lg) do %>
+  <%= form_with(
+    url: keystone_ui_colors.settings_path,
+    method: :patch,
+    scope: :theme_preference,
+    data: { turbo: false, controller: "keystone-ui--colors--theme-settings", selected_template: selected_template }
+  ) do |form| %>
+    <div style="display: flex; flex-direction: column; gap: 2rem;">
+      <%= ui_section(title: "Theme", spacing: :sm) do %>
+        <div style="display: flex; flex-wrap: wrap; gap: 0.5rem;">
+          <% KeystoneUi::Colors::Templates.names.each do |name| %>
+            <% template = KeystoneUi::Colors::Templates[name] %>
+            <% accent_hex = KeystoneUi::Colors::Palettes.accent(template[:accent])[500] %>
+            <% surface_hex = KeystoneUi::Colors::Palettes.surface(template[:surface])[500] %>
+            <%= ui_option_card(
+              name: "theme_preference[template_name]",
+              value: name,
+              selected: selected_template == name.to_s,
+              input_data: {
+                action: "keystone-ui--colors--theme-settings#selectTemplate",
+                "accent-hex": accent_hex,
+                "surface-hex": surface_hex
+              },
+              label_data: {
+                "keystone-ui--colors--theme-settings-target": "templateLabel",
+                template: name
+              }
+            ) do %>
+              <span style="display: inline-block; width: 1rem; height: 1rem; border-radius: 9999px; background-color: <%= accent_hex %>;"></span>
+              <span style="display: inline-block; width: 1rem; height: 1rem; border-radius: 0.25rem; background-color: <%= surface_hex %>;"></span>
+              <span><%= template[:label] %></span>
+            <% end %>
+          <% end %>
+          <%= ui_option_card(
+            name: "theme_preference[template_name]",
+            value: "",
+            selected: custom_selected,
+            input_data: {
+              "keystone-ui--colors--theme-settings-target": "customRadio"
+            },
+            label_data: {
+              "keystone-ui--colors--theme-settings-target": "templateLabel",
+              template: "custom"
+            }
+          ) do %>
+            <span>Custom</span>
+          <% end %>
+        </div>
+      <% end %>
+      <%= ui_section(title: "Accent Color", spacing: :sm) do %>
+        <div data-keystone-ui--colors--theme-settings-target="accentPicker">
+          <%= ui_color_picker(name: "theme_preference[accent]", value: current_accent_hex) %>
+        </div>
+      <% end %>
+      <%= ui_section(title: "Surface", spacing: :sm) do %>
+        <div data-keystone-ui--colors--theme-settings-target="surfacePicker">
+          <%= ui_color_picker(name: "theme_preference[surface]", value: current_surface_hex) %>
+        </div>
+      <% end %>
+      <%= ui_section(title: "Mode", spacing: :sm) do %>
+        <div style="display: flex; flex-wrap: wrap; gap: 0.5rem;">
+          <% KeystoneUi::Colors::ThemePreference::MODES.each do |mode| %>
+            <%= ui_radio_card(name: "theme_preference[mode]", value: mode, label: mode.capitalize, checked: (@preference.mode || KeystoneUi::Colors.configuration.default_mode) == mode) %>
+          <% end %>
+        </div>
+      <% end %>
+      <div>
+        <%= ui_button(label: "Save", type: :submit) %>
+      </div>
+    </div>
+  <% end %>
+<% end %>

data/config/routes.rb ADDED Viewed

@@ -0,0 +1,5 @@
+KeystoneUi::Colors::Engine.routes.draw do
+  get "/", to: "settings#show", as: :settings
+  patch "/", to: "settings#update"
+  delete "/", to: "settings#destroy"
+end

data/lib/generators/keystone_ui/colors/install/install_generator.rb ADDED Viewed

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+require "rails/generators"
+require "rails/generators/active_record"
+module KeystoneUi
+  module Colors
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        include ActiveRecord::Generators::Migration
+        source_root File.expand_path("templates", __dir__)
+        desc "Installs KeystoneUi::Colors: copies migration and prints setup instructions."
+        def copy_migration
+          migration_template(
+            "create_keystone_ui_colors_theme_preferences.rb.erb",
+            "db/migrate/create_keystone_ui_colors_theme_preferences.rb"
+          )
+        end
+        def copy_stimulus_controller
+          js_source = File.expand_path("../../../../../app/javascript/keystone_ui/colors/theme_settings_controller.js", __dir__)
+          create_file "app/javascript/controllers/keystone_ui/colors/theme_settings_controller.js", File.read(js_source)
+        end
+        def show_instructions
+          say ""
+          say "KeystoneUi::Colors installed! Next steps:", :green
+          say ""
+          say "  1. Run migrations:"
+          say "       rails db:migrate"
+          say ""
+          say "  2. Mount the engine in config/routes.rb:"
+          say "       mount KeystoneUi::Colors::Engine => '/keystone_ui_colors'"
+          say ""
+          say "  3. Include the concern in your ApplicationController:"
+          say "       include KeystoneUi::Colors::CurrentPalette"
+          say "       before_action :set_current_palette"
+          say ""
+          say "  4. Add the style tag to your layout <head>:"
+          say "       <%= keystone_palette_style_tag %>"
+          say ""
+        end
+      end
+    end
+  end
+end

data/lib/generators/keystone_ui/colors/install/templates/create_keystone_ui_colors_theme_preferences.rb.erb ADDED Viewed

@@ -0,0 +1,15 @@
+class CreateKeystoneUiColorsThemePreferences < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :keystone_ui_colors_theme_preferences do |t|
+      t.string :accent, null: false
+      t.string :surface, null: false
+      t.string :template_name
+      t.string :mode
+      t.references :owner, polymorphic: true, null: false
+      t.timestamps
+    end
+    add_index :keystone_ui_colors_theme_preferences, %i[owner_type owner_id], unique: true,
+      name: "index_keystone_ui_colors_theme_prefs_on_owner"
+  end
+end

data/lib/generators/keystone_ui/colors/update/templates/add_mode_to_keystone_ui_colors_theme_preferences.rb.erb ADDED Viewed

@@ -0,0 +1,5 @@
+class AddModeToKeystoneUiColorsThemePreferences < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :keystone_ui_colors_theme_preferences, :mode, :string
+  end
+end

data/lib/generators/keystone_ui/colors/update/update_generator.rb ADDED Viewed

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+require "rails/generators"
+require "rails/generators/active_record"
+module KeystoneUi
+  module Colors
+    module Generators
+      class UpdateGenerator < Rails::Generators::Base
+        include ActiveRecord::Generators::Migration
+        source_root File.expand_path("../../../../../app/javascript/keystone_ui/colors", __dir__)
+        desc "Updates KeystoneUi::Colors: copies the Stimulus controller and adds new migrations."
+        def add_mode_migration
+          migration_template(
+            File.expand_path("templates/add_mode_to_keystone_ui_colors_theme_preferences.rb.erb", __dir__),
+            "db/migrate/add_mode_to_keystone_ui_colors_theme_preferences.rb"
+          )
+        end
+        def copy_stimulus_controller
+          copy_file "theme_settings_controller.js",
+            "app/javascript/controllers/keystone_ui/colors/theme_settings_controller.js"
+        end
+      end
+    end
+  end
+end

data/lib/keystone_ui/colors/configuration.rb ADDED Viewed

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+module KeystoneUi
+  module Colors
+    class Configuration
+      attr_accessor :current_owner_method, :authentication_method, :default_template, :default_accent, :default_surface, :default_mode, :layout
+      def initialize
+        @current_owner_method = :current_user
+        @authentication_method = :authenticate_user!
+        @default_template = :ocean
+        @default_accent = "blue"
+        @default_surface = "zinc"
+        @default_mode = "light"
+        @layout = "application"
+      end
+    end
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+    def self.configure
+      yield(configuration)
+    end
+    def self.reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/keystone_ui/colors/engine.rb ADDED Viewed

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+module KeystoneUi
+  module Colors
+    class Engine < ::Rails::Engine
+      isolate_namespace KeystoneUi::Colors
+      initializer "keystone_ui.colors.theme_mode" do
+        KeystoneUi.configure do |config|
+          config.theme_mode_supplier = lambda do |view|
+            view.respond_to?(:keystone_theme_mode) ? view.keystone_theme_mode : KeystoneUi::Colors.configuration.default_mode
+          end
+        end
+      end
+      initializer "keystone_ui.colors.url_helpers" do
+        ActiveSupport.on_load(:action_controller) do
+          helper Rails.application.routes.url_helpers
+        end
+      end
+    end
+  end
+end

data/lib/keystone_ui/colors/palettes.rb ADDED Viewed

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+module KeystoneUi
+  module Colors
+    module Palettes
+      ACCENTS = {
+        blue: { 50 => "#eff6ff", 100 => "#dbeafe", 200 => "#bfdbfe", 300 => "#93c5fd", 400 => "#60a5fa", 500 => "#3b82f6", 600 => "#2563eb", 700 => "#1d4ed8", 800 => "#1e40af", 900 => "#1e3a8a", 950 => "#172554" },
+        emerald: { 50 => "#ecfdf5", 100 => "#d1fae5", 200 => "#a7f3d0", 300 => "#6ee7b7", 400 => "#34d399", 500 => "#10b981", 600 => "#059669", 700 => "#047857", 800 => "#065f46", 900 => "#064e3b", 950 => "#022c22" },
+        cyan: { 50 => "#ecfeff", 100 => "#cffafe", 200 => "#a5f3fc", 300 => "#67e8f9", 400 => "#22d3ee", 500 => "#06b6d4", 600 => "#0891b2", 700 => "#0e7490", 800 => "#155e75", 900 => "#164e63", 950 => "#083344" },
+        indigo: { 50 => "#eef2ff", 100 => "#e0e7ff", 200 => "#c7d2fe", 300 => "#a5b4fc", 400 => "#818cf8", 500 => "#6366f1", 600 => "#4f46e5", 700 => "#4338ca", 800 => "#3730a3", 900 => "#312e81", 950 => "#1e1b4b" },
+        violet: { 50 => "#f5f3ff", 100 => "#ede9fe", 200 => "#ddd6fe", 300 => "#c4b5fd", 400 => "#a78bfa", 500 => "#8b5cf6", 600 => "#7c3aed", 700 => "#6d28d9", 800 => "#5b21b6", 900 => "#4c1d95", 950 => "#2e1065" },
+        rose: { 50 => "#fff1f2", 100 => "#ffe4e6", 200 => "#fecdd3", 300 => "#fda4af", 400 => "#fb7185", 500 => "#f43f5e", 600 => "#e11d48", 700 => "#be123c", 800 => "#9f1239", 900 => "#881337", 950 => "#4c0519" }
+      }.freeze
+      SURFACES = {
+        zinc: { 50 => "#fafafa", 100 => "#f4f4f5", 200 => "#e4e4e7", 300 => "#d4d4d8", 400 => "#a1a1aa", 500 => "#71717a", 600 => "#52525b", 700 => "#3f3f46", 800 => "#27272a", 900 => "#18181b", 950 => "#09090b" },
+        slate: { 50 => "#f8fafc", 100 => "#f1f5f9", 200 => "#e2e8f0", 300 => "#cbd5e1", 400 => "#94a3b8", 500 => "#64748b", 600 => "#475569", 700 => "#334155", 800 => "#1e293b", 900 => "#0f172a", 950 => "#020617" },
+        gray: { 50 => "#f9fafb", 100 => "#f3f4f6", 200 => "#e5e7eb", 300 => "#d1d5db", 400 => "#9ca3af", 500 => "#6b7280", 600 => "#4b5563", 700 => "#374151", 800 => "#1f2937", 900 => "#111827", 950 => "#030712" },
+        neutral: { 50 => "#fafafa", 100 => "#f5f5f5", 200 => "#e5e5e5", 300 => "#d4d4d4", 400 => "#a3a3a3", 500 => "#737373", 600 => "#525252", 700 => "#404040", 800 => "#262626", 900 => "#171717", 950 => "#0a0a0a" },
+        stone: { 50 => "#fafaf9", 100 => "#f5f5f4", 200 => "#e7e5e4", 300 => "#d6d3d1", 400 => "#a8a29e", 500 => "#78716c", 600 => "#57534e", 700 => "#44403c", 800 => "#292524", 900 => "#1c1917", 950 => "#0c0a09" }
+      }.freeze
+      # Shade lightness targets (0.0 = black, 1.0 = white)
+      SHADE_TARGETS = {
+        50 => 0.95, 100 => 0.9, 200 => 0.8, 300 => 0.7, 400 => 0.6,
+        500 => 0.0, 600 => -0.15, 700 => -0.3, 800 => -0.45, 900 => -0.6, 950 => -0.75
+      }.freeze
+      def self.accent(name)
+        ACCENTS.fetch(name.to_sym)
+      end
+      def self.surface(name)
+        SURFACES.fetch(name.to_sym)
+      end
+      def self.generate_shades(hex)
+        r, g, b = hex_to_rgb(hex)
+        SHADE_TARGETS.each_with_object({}) do |(shade, factor), result|
+          result[shade] = if shade == 500
+            hex
+          elsif factor > 0
+            rgb_to_hex(mix(r, g, b, 255, 255, 255, factor))
+          else
+            rgb_to_hex(mix(r, g, b, 0, 0, 0, factor.abs))
+          end
+        end
+      end
+      def self.hex_to_rgb(hex)
+        hex = hex.delete_prefix("#")
+        [ hex[0..1], hex[2..3], hex[4..5] ].map { |c| c.to_i(16) }
+      end
+      private_class_method :hex_to_rgb
+      def self.rgb_to_hex(rgb)
+        "#" + rgb.map { |c| c.clamp(0, 255).round.to_s(16).rjust(2, "0") }.join
+      end
+      private_class_method :rgb_to_hex
+      def self.mix(r1, g1, b1, r2, g2, b2, weight)
+        [
+          r1 + (r2 - r1) * weight,
+          g1 + (g2 - g1) * weight,
+          b1 + (b2 - b1) * weight
+        ]
+      end
+      private_class_method :mix
+    end
+  end
+end

data/lib/keystone_ui/colors/templates.rb ADDED Viewed

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+module KeystoneUi
+  module Colors
+    module Templates
+      PRESETS = {
+        ocean: {
+          accent: :blue,
+          surface: :slate,
+          label: "Ocean",
+          description: "Cool blues with slate undertones"
+        },
+        forest: {
+          accent: :emerald,
+          surface: :stone,
+          label: "Forest",
+          description: "Natural greens with warm stone"
+        },
+        twilight: {
+          accent: :violet,
+          surface: :zinc,
+          label: "Twilight",
+          description: "Deep violet with clean zinc"
+        },
+        coral: {
+          accent: :rose,
+          surface: :neutral,
+          label: "Coral",
+          description: "Warm rose with neutral balance"
+        },
+        arctic: {
+          accent: :cyan,
+          surface: :gray,
+          label: "Arctic",
+          description: "Bright cyan with crisp gray"
+        }
+      }.freeze
+      def self.all
+        PRESETS.merge(default: default_template)
+      end
+      def self.[](name)
+        return default_template if name.to_sym == :default
+        PRESETS.fetch(name.to_sym)
+      end
+      def self.names
+        [ :default ] + PRESETS.keys
+      end
+      def self.default_template
+        {
+          accent: KeystoneUi::Colors.configuration.default_accent,
+          surface: KeystoneUi::Colors.configuration.default_surface,
+          label: "Default",
+          description: "Default theme"
+        }
+      end
+    end
+  end
+end

data/lib/keystone_ui/colors/version.rb ADDED Viewed

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+module KeystoneUi
+  module Colors
+    VERSION = "0.2.0"
+  end
+end

data/lib/keystone_ui/colors.rb ADDED Viewed

@@ -0,0 +1,11 @@
+require "keystone_ui"
+require "keystone_ui/colors/version"
+require "keystone_ui/colors/configuration"
+require "keystone_ui/colors/templates"
+require "keystone_ui/colors/palettes"
+require "keystone_ui/colors/engine"
+module KeystoneUi
+  module Colors
+  end
+end

data/lib/keystone_ui-colors.rb ADDED Viewed

	@@ -0,0 +1 @@
1	+ require "keystone_ui/colors"

metadata ADDED Viewed

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: keystone_ui-colors
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Tyler Schneider
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: keystone_ui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: A companion engine for keystone_ui that provides preset themes and per-user
+  color palette persistence.
+email:
+- tylercschneider@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/concerns/keystone_ui/colors/current_palette.rb
+- app/controllers/keystone_ui/colors/application_controller.rb
+- app/controllers/keystone_ui/colors/settings_controller.rb
+- app/helpers/keystone_ui/colors/palette_helper.rb
+- app/javascript/keystone_ui/colors/theme_settings_controller.js
+- app/models/keystone_ui/colors/application_record.rb
+- app/models/keystone_ui/colors/theme_preference.rb
+- app/views/keystone_ui/colors/settings/show.html.erb
+- config/routes.rb
+- lib/generators/keystone_ui/colors/install/install_generator.rb
+- lib/generators/keystone_ui/colors/install/templates/create_keystone_ui_colors_theme_preferences.rb.erb
+- lib/generators/keystone_ui/colors/update/templates/add_mode_to_keystone_ui_colors_theme_preferences.rb.erb
+- lib/generators/keystone_ui/colors/update/update_generator.rb
+- lib/keystone_ui-colors.rb
+- lib/keystone_ui/colors.rb
+- lib/keystone_ui/colors/configuration.rb
+- lib/keystone_ui/colors/engine.rb
+- lib/keystone_ui/colors/palettes.rb
+- lib/keystone_ui/colors/templates.rb
+- lib/keystone_ui/colors/version.rb
+homepage: https://github.com/DYB-Development/keystone_ui-colors
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/DYB-Development/keystone_ui-colors
+  source_code_uri: https://github.com/DYB-Development/keystone_ui-colors
+  changelog_uri: https://github.com/DYB-Development/keystone_ui-colors/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/DYB-Development/keystone_ui-colors/issues
+  documentation_uri: https://github.com/DYB-Development/keystone_ui-colors#readme
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Per-user color palette settings for Keystone UI.
+test_files: []