keystone_ui 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3461e5f2648165cab0fbea2244fe15dbf42c2bf1da5a96f5ebfdfe89b7a2278c
-  data.tar.gz: c39d95798511ddbe58a61144a98fca8b2070475c3850e83b7016a73627c439ce
+  metadata.gz: 9007e4cf813a277f78f01bdf10df84d28856a5eaf1e7460c51e77db5d8b13143
+  data.tar.gz: a31771c5217f422c78000dc895be2314e9ecac0de206155f3d3a123b3da362af
 SHA512:
-  metadata.gz: 2a0eb208c6a668bf2d2e62ae1d5a996f04b4c8cae8b5f014287cc066a4840195b24756b7efe5a44ef1b3aa2cec367c32129361897f2aa8dbeff09ee786a8ba5f
-  data.tar.gz: 5d596e9a799b189775af38d413afc945fea87828d90517cd21930c80a6efa9a222faa32d8401c4d8bfe8f4d5bc03f32f1e4bb8dfb5f8691aa570e8322d4340bd
+  metadata.gz: d5649e25777890bf3bd01be1f42260c92038b66cef09c71f1b6e4655658f6d602102d0adcef0bd4b063edb837490818df7734c84b3f0e0198e2a859a83b2ea10
+  data.tar.gz: 52bce90d7e68c9ead4e459f71376c16257b235b1418ef92c156bd8d7fb1bd2b33a17cf7111bcb0412d19d79e6ad0626ce8d2aa72db8fe00988fbaae41705151d

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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/app/assets/javascripts/keystone_ui/index.js

@@ -12,6 +12,7 @@ import AccordionController from "keystone_ui/accordion_controller"
 import StatCardInfoController from "keystone_ui/stat_card_info_controller"
 import AutoSubmitController from "keystone_ui/auto_submit_controller"
 import LineChartController from "keystone_ui/line_chart_controller"
+import ThemeToggleController from "keystone_ui/theme_toggle_controller"
 
 export function registerControllers(application) {
   application.register("color-picker", ColorPickerController)
@@ -28,6 +29,7 @@ export function registerControllers(application) {
   application.register("stat-card-info", StatCardInfoController)
   application.register("auto-submit", AutoSubmitController)
   application.register("line-chart", LineChartController)
+  application.register("theme-toggle", ThemeToggleController)
 }
 
 export { ColorPickerController, MultiSelectController, SwipeDeckController, ColumnPickerController, FileUploadController, DropdownController, DismissController, ModalController, ClipboardController, TabSwitcherController, AccordionController, StatCardInfoController, AutoSubmitController, LineChartController }

data/app/assets/javascripts/keystone_ui/theme_toggle_controller.js

@@ -0,0 +1,25 @@
+import { Controller } from "@hotwired/stimulus"
+
+const COOKIE = "keystone_theme"
+const ONE_YEAR = 60 * 60 * 24 * 365
+
+export default class extends Controller {
+  choose({ params: { mode } }) {
+    const page = this.element.ownerDocument
+    this.#showPressed(mode)
+
+    if (mode === "system") {
+      delete page.documentElement.dataset.theme
+      page.cookie = `${COOKIE}=; path=/; max-age=0; samesite=lax`
+    } else {
+      page.documentElement.dataset.theme = mode
+      page.cookie = `${COOKIE}=${mode}; path=/; max-age=${ONE_YEAR}; samesite=lax`
+    }
+  }
+
+  #showPressed(mode) {
+    this.element.querySelectorAll("[data-theme-toggle-mode-param]").forEach((option) => {
+      option.setAttribute("aria-pressed", String(option.dataset.themeToggleModeParam === mode))
+    })
+  }
+}

data/app/components/keystone/ui/button_component.rb

@@ -3,17 +3,17 @@
 module Keystone
   module Ui
     class ButtonComponent < ViewComponent::Base
-      BASE_CLASSES = "inline-flex items-center justify-center font-semibold rounded-lg border-0 cursor-pointer no-underline"
+      BASE_CLASSES = "ks-button"
 
       VARIANT_CLASSES = {
-        secondary: "bg-gray-500 text-white hover:bg-gray-400",
-        danger: "bg-red-600 text-white hover:bg-red-500"
+        secondary: "ks-button-secondary",
+        danger: "ks-button-danger"
       }.freeze
 
       SIZE_CLASSES = {
-        sm: "text-sm px-3 py-1.5",
-        md: "text-base px-4 py-2",
-        lg: "text-lg px-5 py-3"
+        sm: "ks-button-sm",
+        md: "ks-button-md",
+        lg: "ks-button-lg"
       }.freeze
 
       def initialize(label:, href: nil, variant: :primary, size: :md, type: :submit, data: nil)
@@ -27,7 +27,7 @@ module Keystone
 
       def classes
         variant_css = if @variant == :primary
-          "bg-accent-600 text-white hover:bg-accent-500"
+          "ks-button-primary"
         else
           VARIANT_CLASSES.fetch(@variant)
         end

data/app/components/keystone/ui/form_field_component.html.erb

@@ -14,7 +14,7 @@
   <% elsif textarea? %>
     <textarea name="<%= @attribute %>" rows="3" class="<%= Keystone::Ui::TextareaComponent::BASE_CLASSES %>"<% if @placeholder %> placeholder="<%= @placeholder %>"<% end %>><%= @value %></textarea>
   <% elsif select? %>
-    <select name="<%= @attribute %>" class="<%= Keystone::Ui::SelectComponent::BASE_CLASSES %> <%= Keystone::Ui::SelectComponent::FOCUS_CLASSES %>">
+    <select name="<%= @attribute %>" class="<%= Keystone::Ui::SelectComponent::BASE_CLASSES %>">
       <% unless required? %><option value=""></option><% end %>
       <% select_options.each do |label, value| %>
         <option value="<%= value %>" <%= "selected" if @value.to_s == value.to_s %>><%= label %></option>

data/app/components/keystone/ui/form_field_component.rb

@@ -4,11 +4,11 @@ module Keystone
   module Ui
     class FormFieldComponent < ViewComponent::Base
       WRAPPER_CLASSES = "space-y-1"
-      LABEL_CLASSES = "block text-sm font-medium text-gray-700 dark:text-gray-300"
-      REQUIRED_CLASSES = "text-red-500 ml-0.5"
-      HINT_CLASSES = "mt-1 text-sm text-gray-500 dark:text-gray-400"
-      ERROR_CLASSES = "mt-1 text-sm text-red-600 dark:text-red-400"
-      CHECKBOX_CLASSES = "rounded border-gray-300 text-accent-600 focus:ring-accent-500 dark:border-zinc-600 dark:bg-zinc-900"
+      LABEL_CLASSES = "ks-label"
+      REQUIRED_CLASSES = "ks-required"
+      HINT_CLASSES = "ks-hint"
+      ERROR_CLASSES = "ks-error"
+      CHECKBOX_CLASSES = "ks-checkbox"
       CHECKBOX_WRAPPER_CLASSES = "flex items-center gap-2"
 
       def initialize(attribute:, label: nil, type: :text, required: false, hint: nil, placeholder: nil, min: nil, max: nil, step: nil, value: nil, options: [], errors: [])

data/app/components/keystone/ui/input_component.rb

@@ -3,9 +3,9 @@
 module Keystone
   module Ui
     class InputComponent < ViewComponent::Base
-      BASE_CLASSES = "block w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 placeholder:text-gray-400 focus:outline-none focus:ring-1 dark:bg-zinc-900 dark:border-zinc-700 dark:text-white dark:placeholder:text-gray-500"
+      BASE_CLASSES = "ks-input"
 
-      DISABLED_CLASSES = "cursor-not-allowed bg-gray-50 text-gray-500 dark:bg-zinc-800 dark:text-gray-400"
+      DISABLED_CLASSES = "ks-input-disabled"
 
       TYPE_MAP = {
         text: "text",
@@ -26,10 +26,8 @@ module Keystone
         @step = step
       end
 
-      FOCUS_CLASSES = "focus:border-accent-500 focus:ring-accent-500 dark:focus:border-accent-400 dark:focus:ring-accent-400"
-
       def classes
-        tokens = [ BASE_CLASSES, FOCUS_CLASSES ]
+        tokens = [ BASE_CLASSES ]
         tokens << DISABLED_CLASSES if @disabled
         tokens.join(" ")
       end

data/app/components/keystone/ui/panel_component.rb

@@ -12,7 +12,7 @@ module Keystone
         @shadow = shadow
       end
 
-      BASE_CLASSES = "border border-gray-200 bg-white dark:bg-zinc-900 dark:border-zinc-700"
+      BASE_CLASSES = "ks-panel"
       SHADOW_CLASS = "shadow-sm"
 
       def classes

data/app/components/keystone/ui/select_component.rb

@@ -3,9 +3,9 @@
 module Keystone
   module Ui
     class SelectComponent < ViewComponent::Base
-      BASE_CLASSES = "block w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 focus:outline-none focus:ring-1 dark:bg-zinc-900 dark:border-zinc-700 dark:text-white"
+      BASE_CLASSES = "ks-input"
 
-      DISABLED_CLASSES = "cursor-not-allowed bg-gray-50 text-gray-500 dark:bg-zinc-800 dark:text-gray-400"
+      DISABLED_CLASSES = "ks-input-disabled"
 
       attr_reader :options, :selected, :include_blank
 
@@ -17,10 +17,8 @@ module Keystone
         @disabled = disabled
       end
 
-      FOCUS_CLASSES = "focus:border-accent-500 focus:ring-accent-500 dark:focus:border-accent-400 dark:focus:ring-accent-400"
-
       def classes
-        tokens = [ BASE_CLASSES, FOCUS_CLASSES ]
+        tokens = [ BASE_CLASSES ]
         tokens << DISABLED_CLASSES if @disabled
         tokens.join(" ")
       end

data/app/components/keystone/ui/stat_card_component.html.erb

@@ -5,18 +5,16 @@
       <button type="button" class="<%= info_button_classes %>" data-action="click->stat-card-info#toggle" aria-label="Show metric details">
         <%= info_icon.html_safe %>
       </button>
+      <div class="<%= disclosure_classes %>" data-stat-card-info-target="panel">
+        <% if definition %><p><span class="font-medium text-gray-700 dark:text-gray-300">Captures:</span> <%= definition %></p><% end %>
+        <% if calculation %><p><span class="font-medium text-gray-700 dark:text-gray-300">Calc:</span> <%= calculation %></p><% end %>
+      </div>
     <% end %>
   </div>
   <p class="<%= value_classes %>">
-    <%= value %><% if suffix? %><span class="<%= suffix_classes %>"> <%= suffix %></span><% end %>
+    <% if link? %><a href="<%= href %>" class="<%= value_link_classes %>"><%= value %></a><% else %><%= value %><% end %><% if suffix? %><span class="<%= suffix_classes %>"> <%= suffix %></span><% end %>
   </p>
   <% if change? %>
     <p class="mt-1 text-sm font-medium <%= change_classes %>"><%= change_label %></p>
   <% end %>
-  <% if info? %>
-    <div class="<%= disclosure_classes %>" data-stat-card-info-target="panel">
-      <% if definition %><p><span class="font-medium text-gray-700 dark:text-gray-300">Captures:</span> <%= definition %></p><% end %>
-      <% if calculation %><p><span class="font-medium text-gray-700 dark:text-gray-300">Calc:</span> <%= calculation %></p><% end %>
-    </div>
-  <% end %>
 </div>

data/app/components/keystone/ui/stat_card_component.rb

@@ -3,12 +3,13 @@
 module Keystone
   module Ui
     class StatCardComponent < ViewComponent::Base
-      CARD_CLASSES = "rounded-xl border border-gray-200 bg-white p-6 dark:border-zinc-700 dark:bg-zinc-800"
+      CARD_CLASSES = "relative rounded-xl border border-gray-200 bg-white p-6 dark:border-zinc-700 dark:bg-zinc-800"
       LABEL_CLASSES = "text-sm font-medium text-gray-500 dark:text-gray-400"
       VALUE_BASE_CLASSES = "mt-1 text-3xl font-bold"
       SUFFIX_CLASSES = "text-lg text-gray-500 dark:text-gray-400"
-      DISCLOSURE_CLASSES = "hidden mt-4 space-y-1 border-t border-gray-200 pt-3 text-sm text-gray-600 dark:border-zinc-700 dark:text-gray-400"
-      INFO_BUTTON_CLASSES = "shrink-0 text-gray-400 transition hover:text-accent-600 dark:hover:text-accent-400"
+      DISCLOSURE_CLASSES = "hidden peer-hover:block peer-focus-visible:block absolute inset-x-0 top-full z-10 mt-2 space-y-1 rounded-lg border border-gray-200 bg-white p-3 text-sm text-gray-600 shadow-lg dark:border-zinc-700 dark:bg-zinc-800 dark:text-gray-400"
+      VALUE_LINK_CLASSES = "hover:underline focus:outline-none focus-visible:underline"
+      INFO_BUTTON_CLASSES = "peer shrink-0 text-gray-400 transition hover:text-accent-600 dark:hover:text-accent-400"
 
       INFO_ICON = <<~SVG.freeze
         <svg xmlns="http://www.w3.org/2000/svg" class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg>
@@ -22,9 +23,9 @@ module Keystone
         info: "text-accent-600 dark:text-accent-400"
       }.freeze
 
-      attr_reader :label, :value, :suffix, :definition, :calculation, :change
+      attr_reader :label, :value, :suffix, :definition, :calculation, :change, :href
 
-      def initialize(label:, value:, variant: :neutral, suffix: nil, definition: nil, calculation: nil, change: nil)
+      def initialize(label:, value:, variant: :neutral, suffix: nil, definition: nil, calculation: nil, change: nil, href: nil)
         @label = label
         @value = value
         @variant = variant
@@ -32,6 +33,7 @@ module Keystone
         @definition = definition
         @calculation = calculation
         @change = change
+        @href = href
       end
 
       def classes
@@ -62,6 +64,14 @@ module Keystone
         !@change.nil?
       end
 
+      def link?
+        !@href.nil?
+      end
+
+      def value_link_classes
+        VALUE_LINK_CLASSES
+      end
+
       def change_label
         formatted = "#{format("%.1f", @change.abs)}%"
         return formatted if @change.zero?

data/app/components/keystone/ui/textarea_component.rb

@@ -3,9 +3,9 @@
 module Keystone
   module Ui
     class TextareaComponent < ViewComponent::Base
-      BASE_CLASSES = "block w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 placeholder:text-gray-400 focus:outline-none focus:ring-1 dark:bg-zinc-900 dark:border-zinc-700 dark:text-white dark:placeholder:text-gray-500"
+      BASE_CLASSES = "ks-input"
 
-      DISABLED_CLASSES = "cursor-not-allowed bg-gray-50 text-gray-500 dark:bg-zinc-800 dark:text-gray-400"
+      DISABLED_CLASSES = "ks-input-disabled"
 
       def initialize(name:, value: nil, rows: 3, placeholder: nil, disabled: false)
         @name = name
@@ -15,10 +15,8 @@ module Keystone
         @disabled = disabled
       end
 
-      FOCUS_CLASSES = "focus:border-accent-500 focus:ring-accent-500 dark:focus:border-accent-400 dark:focus:ring-accent-400"
-
       def classes
-        tokens = [ BASE_CLASSES, FOCUS_CLASSES ]
+        tokens = [ BASE_CLASSES ]
         tokens << DISABLED_CLASSES if @disabled
         tokens.join(" ")
       end

data/app/components/keystone/ui/theme_toggle_component.html.erb

@@ -0,0 +1,10 @@
+<div class="<%= GROUP_CLASSES %>" role="group" aria-label="Theme" data-controller="theme-toggle">
+  <% options.each do |label, mode| %>
+    <button
+      type="button"
+      class="<%= OPTION_CLASSES %>"
+      aria-pressed="<%= pressed?(mode) %>"
+      data-action="theme-toggle#choose"
+      data-theme-toggle-mode-param="<%= mode %>"><%= label %></button>
+  <% end %>
+</div>

data/app/components/keystone/ui/theme_toggle_component.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class ThemeToggleComponent < ViewComponent::Base
+      OPTIONS = [ [ "Light", "light" ], [ "Dark", "dark" ], [ "System", "system" ] ].freeze
+      GROUP_CLASSES = "inline-flex gap-1"
+      OPTION_CLASSES = "ks-button ks-button-sm ks-button-secondary aria-pressed:bg-accent-600 aria-pressed:hover:bg-accent-500"
+
+      def initialize(current: nil)
+        @current = current
+      end
+
+      def options
+        OPTIONS
+      end
+
+      def pressed?(mode)
+        mode == (KeystoneUi::ThemeChoice::MODES.include?(@current) ? @current : "system")
+      end
+    end
+  end
+end

data/app/helpers/keystone_ui_helper.rb

@@ -41,6 +41,14 @@ module KeystoneUiHelper
     render Keystone::Ui::BadgeComponent.new(**args)
   end
 
+  def ui_theme_toggle
+    render Keystone::Ui::ThemeToggleComponent.new(current: cookies[KeystoneUi::ThemeChoice::COOKIE])
+  end
+
+  def keystone_theme_attributes
+    KeystoneUi::ThemeChoice.new(cookies[KeystoneUi::ThemeChoice::COOKIE]).html_attributes_markup.html_safe
+  end
+
   def ui_copy_button(**args)
     render Keystone::Ui::CopyButtonComponent.new(**args)
   end

data/config/importmap.rb

@@ -13,6 +13,7 @@ pin "keystone_ui/accordion_controller", to: "keystone_ui/accordion_controller.js
 pin "keystone_ui/stat_card_info_controller", to: "keystone_ui/stat_card_info_controller.js"
 pin "keystone_ui/auto_submit_controller", to: "keystone_ui/auto_submit_controller.js"
 pin "keystone_ui/line_chart_controller", to: "keystone_ui/line_chart_controller.js"
+pin "keystone_ui/theme_toggle_controller", to: "keystone_ui/theme_toggle_controller.js"
 
 # Chart.js for the line-chart controller, so host apps don't pin it themselves.
 # Vendored as a single self-contained bundle (deps inlined, no external imports).

data/lib/generators/keystone/install_generator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "layout_theme_attributes"
+
 module Keystone
   class InstallGenerator < Rails::Generators::Base
     desc "Set up Keystone UI in your Rails application"
@@ -11,6 +13,8 @@ module Keystone
     JS_IMPORT = 'import { registerControllers } from "keystone_ui/index"'
     JS_REGISTER = "registerControllers(application)"
 
+    LAYOUT_PATH = "app/views/layouts/application.html.erb"
+
     def setup_tailwind
       say ""
       say "Keystone UI — setup", :green
@@ -86,5 +90,26 @@ module Keystone
       append_to_file js_path, "\n#{JS_IMPORT}\n#{JS_REGISTER}\n"
       say "  ✔ Registered Keystone UI controllers", :green
     end
+
+    def setup_theme
+      say ""
+      say "Wiring the Keystone UI theme toggle...", :green
+
+      layout_path = Rails.root.join(LAYOUT_PATH)
+      unless layout_path.exist?
+        say "  ⚠ #{LAYOUT_PATH} not found — add `<%= keystone_theme_attributes %>` to your <html> tag manually.", :yellow
+        return
+      end
+
+      layout = layout_path.read
+      updated = Keystone::LayoutThemeAttributes.new(layout).apply
+
+      if updated == layout
+        say "  ✔ Layout already marks the theme", :green
+      else
+        File.write(layout_path, updated)
+        say "  ✔ Added the theme attributes to the layout's html tag", :green
+      end
+    end
   end
 end

data/lib/generators/keystone/layout_theme_attributes.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Keystone
+  class LayoutThemeAttributes
+    HELPER_CALL = "<%= keystone_theme_attributes %>"
+
+    def initialize(layout)
+      @layout = layout
+    end
+
+    def apply
+      return @layout if @layout.include?(HELPER_CALL)
+
+      @layout.sub(/<html\b/, "<html #{HELPER_CALL}")
+    end
+  end
+end

data/lib/keystone_ui/engine.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "keystone_ui/source_css"
+
 module KeystoneUi
   class Engine < ::Rails::Engine
     config.autoload_paths << root.join("app/components")
@@ -27,21 +29,7 @@ module KeystoneUi
       keystone_import = '@import "./keystone_source.css";'
       next unless css_path.read.include?(keystone_import)
 
-      source_css = tailwind_dir.join("keystone_source.css")
-      lines = [ %(@source "#{root}/app/components/**/*.{erb,rb}";) ]
-
-      # Import theme CSS (accent + surface custom property defaults)
-      theme_css = root.join("app/assets/tailwind/keystone_ui_engine/theme.css")
-      lines << %(@import "#{theme_css}";) if theme_css.exist?
-
-      # Import component CSS files shipped with the gem
-      nav_css = root.join("app/assets/tailwind/keystone_ui_engine/nav.css")
-      lines << %(@import "#{nav_css}";) if nav_css.exist?
-
-      color_picker_css = root.join("app/assets/tailwind/keystone_ui_engine/color_picker.css")
-      lines << %(@import "#{color_picker_css}";) if color_picker_css.exist?
-
-      source_css.write(lines.join("\n") + "\n")
+      tailwind_dir.join("keystone_source.css").write(KeystoneUi::SourceCss.new(root).to_s)
     end
   end
 end

data/lib/keystone_ui/safelist.rb

@@ -52,7 +52,8 @@ module Keystone
       Keystone::Ui::FunnelComponent,
       Keystone::Ui::PipelineComponent,
       Keystone::Ui::CodeComponent,
-      Keystone::Ui::DisclosureComponent
+      Keystone::Ui::DisclosureComponent,
+      Keystone::Ui::ThemeToggleComponent
     ].freeze
 
     # Constants that hold non-CSS values (e.g. HTML input type maps)

data/lib/keystone_ui/source_css.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "keystone_ui/styles"
+
+module KeystoneUi
+  class SourceCss
+    def initialize(root)
+      @root = Pathname.new(root)
+    end
+
+    def to_s
+      lines.join("\n") + "\n"
+    end
+
+    private
+
+    def styles_entry
+      KeystoneUi::Styles::Engine.root.join("app/assets/tailwind/keystone_ui_styles/engine.css")
+    end
+
+    def lines
+      [
+        %(@import "#{styles_entry}";),
+        %(@source "#{@root}/app/components/**/*.{erb,rb}";),
+        %(@import "#{@root}/app/assets/tailwind/keystone_ui_engine/nav.css";),
+        %(@import "#{@root}/app/assets/tailwind/keystone_ui_engine/color_picker.css";)
+      ]
+    end
+  end
+end

data/lib/keystone_ui/theme_choice.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  class ThemeChoice
+    COOKIE = "keystone_theme"
+    MODES = %w[light dark].freeze
+
+    def initialize(mode)
+      @mode = mode
+    end
+
+    def html_attributes
+      MODES.include?(@mode) ? { "data-theme" => @mode } : {}
+    end
+
+    def html_attributes_markup
+      html_attributes.map { |name, value| %(#{name}="#{value}") }.join(" ")
+    end
+  end
+end

data/lib/keystone_ui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KeystoneUi
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/keystone_ui.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require "view_component"
+require "keystone_ui/styles"
 require "keystone_ui/configuration"
+require "keystone_ui/theme_choice"
 require "keystone_ui/engine"
 require "keystone_ui/version"
 

data/the_local/agents/keystone_ui-develop.md

@@ -157,11 +157,14 @@ one raises at render time.
   close control.
 - `ui_progress(value:, max:, label: nil)` — a labeled progress bar. The percent
   is `value / max`, rounded and clamped at 100.
-- `ui_stat_card(label:, value:, variant: :neutral, suffix: nil, definition: nil, calculation: nil, change: nil)`
+- `ui_stat_card(label:, value:, variant: :neutral, suffix: nil, definition: nil, calculation: nil, change: nil, href: nil)`
   — a single metric tile. `variant:` `:neutral` `:success` `:danger` `:warning`
   `:info` colors the value. `change:` is a signed number rendered as `▲ 4.2%` in
-  green when positive, `▼` in red when negative, plain when zero. Passing
-  `definition:` and/or `calculation:` adds an info button that reveals them.
+  green when positive, `▼` in red when negative, plain when zero. `href:` makes
+  the value a link to its drill-down screen; only the value is linked, never the
+  whole card. Passing `definition:` and/or `calculation:` adds an info button
+  whose details show in a panel floating below the card while the button is
+  hovered or focused, and tapping the button toggles it.
 - `ui_copy_button(text:, label: "Copy", success_message: "Copied!", error_message: "Failed!")`
   — copies `text:` to the clipboard.
 - `ui_code(language: nil, caption: nil)` — takes a block holding the code. The
@@ -242,7 +245,8 @@ one raises at render time.
 5. Fill the body with the leaf helpers from the Interface above. Reach for the
    most specific one that fits — `ui_form_field` over `ui_input`,
    `ui_data_table` over a hand-built `<table>`, `ui_stat_card` over a panel with
-   text in it.
+   text in it. To make a stat card clickable, pass `href:` — never wrap it in
+   `ui_card_link`, because a tap on the info button would then follow the link.
 
 6. For a table, decide how columns are declared. Use `{ key: "Label" }` hashes
    when every column is plain. Switch the whole set to `Keystone::Ui::Column`

data/the_local/interface.yml

@@ -105,6 +105,7 @@ sources:
   - app/components/keystone/ui/settings_link_component.rb
   - app/components/keystone/ui/show_page_component.rb
   - app/components/keystone/ui/stat_card_component.rb
+  - app/components/keystone/ui/stat_card_component.html.erb
   - app/components/keystone/ui/swipe_deck_component.rb
   - app/components/keystone/ui/tab_switcher_component.rb
   - app/components/keystone/ui/textarea_component.rb

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Tyler Schneider
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-31 00:00:00.000000000 Z
+date: 2026-09-14 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: keystone_ui-styles
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement
@@ -37,6 +51,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- MIT-LICENSE
 - app/assets/javascripts/keystone_ui/accordion_controller.js
 - app/assets/javascripts/keystone_ui/auto_submit_controller.js
 - app/assets/javascripts/keystone_ui/chartjs.js
@@ -53,10 +68,10 @@ files:
 - app/assets/javascripts/keystone_ui/stat_card_info_controller.js
 - app/assets/javascripts/keystone_ui/swipe_deck_controller.js
 - app/assets/javascripts/keystone_ui/tab_switcher_controller.js
+- app/assets/javascripts/keystone_ui/theme_toggle_controller.js
 - app/assets/tailwind/keystone_ui_engine/color_picker.css
 - app/assets/tailwind/keystone_ui_engine/engine.css
 - app/assets/tailwind/keystone_ui_engine/nav.css
-- app/assets/tailwind/keystone_ui_engine/theme.css
 - app/components/keystone/ui/accordion_component.html.erb
 - app/components/keystone/ui/accordion_component.rb
 - app/components/keystone/ui/alert_component.html.erb
@@ -154,13 +169,18 @@ files:
 - app/components/keystone/ui/tab_switcher_component.rb
 - app/components/keystone/ui/textarea_component.html.erb
 - app/components/keystone/ui/textarea_component.rb
+- app/components/keystone/ui/theme_toggle_component.html.erb
+- app/components/keystone/ui/theme_toggle_component.rb
 - app/helpers/keystone_ui_helper.rb
 - config/importmap.rb
 - lib/generators/keystone/install_generator.rb
+- lib/generators/keystone/layout_theme_attributes.rb
 - lib/keystone_ui.rb
 - lib/keystone_ui/configuration.rb
 - lib/keystone_ui/engine.rb
 - lib/keystone_ui/safelist.rb
+- lib/keystone_ui/source_css.rb
+- lib/keystone_ui/theme_choice.rb
 - lib/keystone_ui/version.rb
 - the_local/agents/keystone_ui-develop.md
 - the_local/agents/keystone_ui-info.md

data/app/assets/tailwind/keystone_ui_engine/theme.css

@@ -1,32 +0,0 @@
-/* Keystone UI theme — defines accent and surface color tokens as CSS custom properties.
-   Apps override these variables to customize the color palette. */
-
-@theme {
-  /* Accent — defaults to blue */
-  --color-accent-50: #eff6ff;
-  --color-accent-100: #dbeafe;
-  --color-accent-200: #bfdbfe;
-  --color-accent-300: #93c5fd;
-  --color-accent-400: #60a5fa;
-  --color-accent-500: #3b82f6;
-  --color-accent-600: #2563eb;
-  --color-accent-700: #1d4ed8;
-  --color-accent-800: #1e40af;
-  --color-accent-900: #1e3a8a;
-
-  /* Surface — defaults to zinc */
-  --color-surface-50: #fafafa;
-  --color-surface-100: #f4f4f5;
-  --color-surface-200: #e4e4e7;
-  --color-surface-300: #d4d4d8;
-  --color-surface-400: #a1a1aa;
-  --color-surface-500: #71717a;
-  --color-surface-600: #52525b;
-  --color-surface-700: #3f3f46;
-  --color-surface-800: #27272a;
-  --color-surface-900: #18181b;
-  --color-surface-950: #09090b;
-
-  /* Accent — darkest shade */
-  --color-accent-950: #172554;
-}