From c8603fc383ce040fa4be1beb7e5b8b61eded15b8 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Mon, 29 Dec 2025 17:24:39 +0000
Subject: [PATCH 01/19] chore: Adds comprehensive .gitignore file

- Introduces a detailed .gitignore file to exclude unnecessary files and directories from version control.
- Includes configurations for Ruby, macOS, Linux, and Windows environments.
- Improves repository cleanliness and reduces unnecessary storage.
---
 .gitignore | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 125 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index b268508..ec4f801 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,9 +1,132 @@
+# Created by https://www.toptal.com/developers/gitignore/api/ruby,macos,linux,windows
+# Edit at https://www.toptal.com/developers/gitignore?templates=ruby,macos,linux,windows
+
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### Ruby ###
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+## Ignore bundler config:
 .bundle/
+
+## Ignore all logfiles and tempfiles.
 log/*.log
-pkg/
+
+## Ignore tempfiles created by testing frameworks.
 test/dummy/db/*.sqlite3
 test/dummy/db/*.sqlite3-journal
 test/dummy/log/*.log
 test/dummy/tmp/
 test/dummy/.sass-cache
-*.gem
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# End of https://www.toptal.com/developers/gitignore/api/ruby,macos,linux,windows

From 24ca4322ffd26bcef6b74078032d500f71f64915 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Mon, 29 Dec 2025 17:24:56 +0000
Subject: [PATCH 02/19] chore(deps): Updates to dartsass-rails

- Replaces sass-rails with dartsass-rails due to EOL.
- Updates the gemfile and gemspec files accordingly.
- Removes sass-rails dependency.
---
 Gemfile.lock             | 69 +++++++++++++++++++++++++++++-----------
 lr_common_styles.gemspec |  6 ++--
 2 files changed, 55 insertions(+), 20 deletions(-)

diff --git a/Gemfile.lock b/Gemfile.lock
index 210a7f1..e1fbfdc 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -3,6 +3,7 @@ PATH
   specs:
     lr_common_styles (2.3.1)
       bootstrap-sass (~> 3.4.1)
+      dartsass-rails (~> 0.5.1)
       font-awesome-rails (~> 4.7.0)
       govuk_elements_rails (= 3.0.2)
       govuk_frontend_toolkit (~> 9.0)
@@ -13,7 +14,6 @@ PATH
       modernizr-rails (~> 2.7)
       modulejs-rails (~> 2.2.0)
       rails (~> 8.0)
-      sass-rails (~> 6.0)
 
 GEM
   remote: https://rubygems.org/
@@ -107,6 +107,9 @@ GEM
     concurrent-ruby (1.3.5)
     connection_pool (2.5.4)
     crass (1.0.6)
+    dartsass-rails (0.5.1)
+      railties (>= 6.0.0)
+      sass-embedded (~> 1.63)
     date (3.5.0)
     diff-lcs (1.6.2)
     drb (2.2.3)
@@ -127,6 +130,33 @@ GEM
       railties (>= 3.2, < 9.0)
     globalid (1.3.0)
       activesupport (>= 6.1)
+    google-protobuf (4.33.2)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.2-aarch64-linux-gnu)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.2-aarch64-linux-musl)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.2-arm64-darwin)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.2-x86-linux-gnu)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.2-x86-linux-musl)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.2-x86_64-darwin)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.2-x86_64-linux-gnu)
+      bigdecimal
+      rake (>= 13)
+    google-protobuf (4.33.2-x86_64-linux-musl)
+      bigdecimal
+      rake (>= 13)
     govuk_elements_rails (3.0.2)
       govuk_frontend_toolkit (>= 5.2.0)
       rails (>= 4.1.0)
@@ -318,19 +348,30 @@ GEM
     rubyzip (2.4.1)
     sass (3.7.4)
       sass-listen (~> 4.0.0)
+    sass-embedded (1.97.1)
+      google-protobuf (~> 4.31)
+      rake (>= 13)
+    sass-embedded (1.97.1-aarch64-linux-gnu)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.1-aarch64-linux-musl)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.1-arm-linux-gnueabihf)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.1-arm-linux-musleabihf)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.1-arm64-darwin)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.1-x86_64-darwin)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.1-x86_64-linux-gnu)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.1-x86_64-linux-musl)
+      google-protobuf (~> 4.31)
     sass-listen (4.0.0)
       rb-fsevent (~> 0.9, >= 0.9.4)
       rb-inotify (~> 0.9, >= 0.9.7)
-    sass-rails (6.0.0)
-      sassc-rails (~> 2.1, >= 2.1.1)
     sassc (2.4.0)
       ffi (~> 1.9)
-    sassc-rails (2.1.2)
-      railties (>= 4.0.0)
-      sassc (>= 2.0)
-      sprockets (> 3.0)
-      sprockets-rails
-      tilt
     securerandom (0.4.1)
     solargraph (0.57.0)
       backport (~> 1.2)
@@ -353,14 +394,6 @@ GEM
       yard (~> 0.9, >= 0.9.24)
       yard-activesupport-concern (~> 0.0)
       yard-solargraph (~> 0.1)
-    sprockets (4.2.2)
-      concurrent-ruby (~> 1.0)
-      logger
-      rack (>= 2.2.4, < 4)
-    sprockets-rails (3.5.2)
-      actionpack (>= 6.1)
-      activesupport (>= 6.1)
-      sprockets (>= 3.0.0)
     stringio (3.1.7)
     temple (0.10.4)
     thor (1.4.0)
@@ -414,4 +447,4 @@ DEPENDENCIES
   solargraph
 
 BUNDLED WITH
-   2.7.1
+   2.7.2
diff --git a/lr_common_styles.gemspec b/lr_common_styles.gemspec
index 58db729..511ff48 100644
--- a/lr_common_styles.gemspec
+++ b/lr_common_styles.gemspec
@@ -34,9 +34,12 @@ Gem::Specification.new do |spec|
   # ! Styles is a gem as well, we cannot use a forked repo as a dependency. As a
   # ! result we are stuck using version 3.0.2 until further investigations provide
   # ! a better solution.
+  spec.add_dependency 'govuk_elements_rails', '3.0.2'
+
   spec.add_dependency 'bootstrap-sass', '~> 3.4.1'
+  # spec.add_dependency 'bootstrap', '~> 5.3.3', '~> 4.5'
+  spec.add_dependency 'dartsass-rails', '~> 0.5.1'
   spec.add_dependency 'font-awesome-rails', '~> 4.7.0'
-  spec.add_dependency 'govuk_elements_rails', '3.0.2'
   spec.add_dependency 'govuk_frontend_toolkit', '~> 9.0'
   spec.add_dependency 'govuk_template', '~> 0.26.0'
   spec.add_dependency 'haml-rails', '~> 3.0'
@@ -44,5 +47,4 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'lodash-rails', '~> 4.17'
   spec.add_dependency 'modernizr-rails', '~> 2.7'
   spec.add_dependency 'modulejs-rails', '~> 2.2.0'
-  spec.add_dependency 'sass-rails', '~> 6.0'
 end

From 80a1b1a5b12f84139fda7bda9dbd915a75a68b69 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Mon, 29 Dec 2025 17:43:43 +0000
Subject: [PATCH 03/19] chore: Update bin/rails for gem development

- Updates the `bin/rails` file to follow current best practices
- Ensures full Rails functionality is available during gem development/testing.
- Includes explanation of all rails component inclusion.
---
 bin/rails | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/bin/rails b/bin/rails
index 18497ae..4b89902 100755
--- a/bin/rails
+++ b/bin/rails
@@ -1,12 +1,18 @@
 #!/usr/bin/env ruby
-# This command will automatically be run when you run "rails" with Rails 4 gems installed from the root of your application.
+# This command will automatically be run when you run "rails" with Rails gems installed from the root of your application.
 
-ENGINE_ROOT = File.expand_path('../..', __FILE__)
-ENGINE_PATH = File.expand_path('../../lib/lr_common_styles/engine', __FILE__)
+ENGINE_ROOT = File.expand_path('..', __dir__)
+ENGINE_PATH = File.expand_path('../lib/lr_common_styles/engine', __dir__)
 
 # Set up gems listed in the Gemfile.
-ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
 require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])
 
+# Note: This gem primarily uses ActionView and ActionDispatch (not ActiveRecord,
+# ActionController, ActionMailer, etc.). While best practice would be to require
+# only specific components (e.g., 'action_view/railtie', 'action_dispatch/railtie'),
+# we keep 'rails/all' here since this bin/rails file is only used during gem
+# development/testing, not in production. The performance impact is negligible and
+# this ensures full Rails functionality is available during development.
 require 'rails/all'
 require 'rails/engine/commands'

From 9171ff238f79d4da1700b8448e2aacfc80618326 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Mon, 29 Dec 2025 17:45:03 +0000
Subject: [PATCH 04/19] feat(styles): Add dartsass-rails dependency

- Introduces `dartsass-rails` to replace `ruby-sass` which is now end-of-life.
- This ensures continued support for Sass compilation within the application.
---
 Gemfile.lock             | 1 +
 lr_common_styles.gemspec | 1 -
 2 files changed, 1 insertion(+), 1 deletion(-)

diff --git a/Gemfile.lock b/Gemfile.lock
index e1fbfdc..26e7c84 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -436,6 +436,7 @@ PLATFORMS
 
 DEPENDENCIES
   byebug
+  dartsass-rails (~> 0.5.1)
   lr_common_styles!
   minitest-rails
   mocha
diff --git a/lr_common_styles.gemspec b/lr_common_styles.gemspec
index 511ff48..8374bb5 100644
--- a/lr_common_styles.gemspec
+++ b/lr_common_styles.gemspec
@@ -37,7 +37,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'govuk_elements_rails', '3.0.2'
 
   spec.add_dependency 'bootstrap-sass', '~> 3.4.1'
-  # spec.add_dependency 'bootstrap', '~> 5.3.3', '~> 4.5'
   spec.add_dependency 'dartsass-rails', '~> 0.5.1'
   spec.add_dependency 'font-awesome-rails', '~> 4.7.0'
   spec.add_dependency 'govuk_frontend_toolkit', '~> 9.0'

From 1322ad019b2531b64d5d374831d1c22b244745a4 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 13:11:04 +0000
Subject: [PATCH 05/19] chore(styles): Move header style file

- Updates header style file location to align with other partials.
---
 .../stylesheets/lr_common_styles/{header.scss => _header.scss}    | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename app/assets/stylesheets/lr_common_styles/{header.scss => _header.scss} (100%)

diff --git a/app/assets/stylesheets/lr_common_styles/header.scss b/app/assets/stylesheets/lr_common_styles/_header.scss
similarity index 100%
rename from app/assets/stylesheets/lr_common_styles/header.scss
rename to app/assets/stylesheets/lr_common_styles/_header.scss

From 7b64c12ba53929403422842227f47503c00a82f5 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 13:11:43 +0000
Subject: [PATCH 06/19] chore(view): replace favicon links with partial

- Extracts favicon related links into a partial.
- Improves maintainability of the application layout.
- Reduces duplication of favicon declarations.
---
 app/views/layouts/application.html.haml | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/app/views/layouts/application.html.haml b/app/views/layouts/application.html.haml
index 706fd8c..b08931b 100644
--- a/app/views/layouts/application.html.haml
+++ b/app/views/layouts/application.html.haml
@@ -13,15 +13,7 @@
     = javascript_include_tag "application"
     = csrf_meta_tags
 
-    %link{ rel: "apple-touch-icon", sizes: "180x180", href: image_path( "favicon/apple-touch-icon.png" )}
-    %link{ rel: "icon", type: "image/png", href: image_path( "favicon/favicon-32x32.png" ), sizes: "32x32"}
-    %link{ rel: "icon", type: "image/png", href: image_path( "favicon/favicon-16x16.png" ), sizes: "16x16"}
-    %link{ rel: "manifest", href: image_path( "favicon/manifest.json" )}
-    %link{ rel: "mask-icon", href: image_path( "favicon/safari-pinned-tab.svg" ), color: "#5bbad5"}
-    %link{ rel: "shortcut icon", href: image_path( "favicon/favicon.ico" )}
-
-    %meta{ name: "msapplication-config", content: image_path( "favicon/browserconfig.xml" )}
-    %meta{ name: "theme-color", content: "#ffffff"}
+    = render partial: "application/favicon"
 
     - if @preferences
       %link{ rel: "canonical", href: "http://#{request.host_with_port}#{@preferences.as_path( :view )}"}

From 53b47884340f33a43a3ecfaddf84c3dd08e9c723 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 13:12:34 +0000
Subject: [PATCH 07/19] refactor(styles): Migrates to Propshaft-compatible
 structure

- Updates stylesheet structure for compatibility with Propshaft.
- Removes redundant imports from lr-common.scss.
- Organises imports in lr_common_styles.scss for clarity.
---
 app/assets/stylesheets/lr_common_styles.scss  | 22 +++++++++++++++++++
 .../lr_common_styles/_lr-common.scss          | 11 ----------
 2 files changed, 22 insertions(+), 11 deletions(-)
 create mode 100644 app/assets/stylesheets/lr_common_styles.scss

diff --git a/app/assets/stylesheets/lr_common_styles.scss b/app/assets/stylesheets/lr_common_styles.scss
new file mode 100644
index 0000000..7c65660
--- /dev/null
+++ b/app/assets/stylesheets/lr_common_styles.scss
@@ -0,0 +1,22 @@
+/*
+ * Entry point stylesheet for Propshaft-enabled apps.
+ * Hosts should include "lr_common_styles.css".
+ * Sprockets users may continue to link directory assets as before.
+ */
+
+
+
+// LR Common Styles partials
+@import "lr_common_styles/common-elements";
+@import "lr_common_styles/cookie-banner";
+@import "lr_common_styles/header";
+@import "lr_common_styles/footer";
+@import "lr_common_styles/feedback";
+@import "lr_common_styles/lr-common";
+
+// Common global styles
+@import "skip_to_main";
+
+// Gem override stylesheets
+@import "lr_common_styles/gov_uk_refine";
+@import "lr_common_styles/bootstrap-refine";
diff --git a/app/assets/stylesheets/lr_common_styles/_lr-common.scss b/app/assets/stylesheets/lr_common_styles/_lr-common.scss
index 5509381..d222508 100644
--- a/app/assets/stylesheets/lr_common_styles/_lr-common.scss
+++ b/app/assets/stylesheets/lr_common_styles/_lr-common.scss
@@ -27,16 +27,8 @@ $lr-green-nav-darkened: darken($lr-green-nav, 20%);
 
 /* elements */
 
-@import 'common-elements';
-
 /* objects */
 
-@import
-  'cookie-banner',
-  'header',
-  'footer',
-  'feedback',
-  'skip_to_main';
 
 .o-container {
   @extend %site-width-container;
@@ -51,6 +43,3 @@ $lr-green-nav-darkened: darken($lr-green-nav, 20%);
 .u-font-bold {
   font-weight: bold;
 }
-
-@import 'gov_uk_refine';
-@import 'bootstrap-refine';

From 490b6643798cfe84239e6c00d152d1dff17b3cf3 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 13:13:33 +0000
Subject: [PATCH 08/19] refactor(config): Simplifies class joining

- Uses `presence&.join(' ')` for more concise and readable code.
- Improves code clarity and maintainability by using modern Ruby syntax.
---
 app/models/lr_common_config.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/models/lr_common_config.rb b/app/models/lr_common_config.rb
index 4c356c9..91859e2 100644
--- a/app/models/lr_common_config.rb
+++ b/app/models/lr_common_config.rb
@@ -54,7 +54,7 @@ def set_link_classes(name, classes, root, current_url)
       if root == false && current_url =~ /#{name}/
         classes << 'lr-header--header-proposition--a__active'
       end
-      classes.join(' ') if classes.present?
+      classes.presence&.join(' ')
     end
   end
 end

From 934cadc984f00bbe2631ff68c530c2e1a19040d6 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 13:59:41 +0000
Subject: [PATCH 09/19] chore(dummy): Removes deprecated timezone config

- Removes the `active_support.to_time_preserves_timezone` configuration from the dummy application.
---
 test/dummy/config/application.rb | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/test/dummy/config/application.rb b/test/dummy/config/application.rb
index 1305833..23cad7c 100644
--- a/test/dummy/config/application.rb
+++ b/test/dummy/config/application.rb
@@ -23,12 +23,6 @@ class Application < Rails::Application
     # Run "rake -D time" for a list of tasks for finding time zone names. Default is UTC.
     # config.time_zone = 'Central Time (US & Canada)'
 
-    # !DEPRECATION WARNING: `to_time` will always preserve the full system
-    # ! timezone offset rather than offset of the receiver in Rails 8.1.
-    # * To opt in to the new behavior and maintain system timezone,
-    # * set the value to :zone; otherwise, set to false
-    config.active_support.to_time_preserves_timezone = :zone
-
     # The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded.
     # config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}').to_s]
     # config.i18n.default_locale = :de

From 1b8d55040cd75596d261f7dc61c5019cabe546b0 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 15:52:24 +0000
Subject: [PATCH 10/19] feat(engine): Adds asset paths for gem dependencies

- Configures the Rails engine to include asset paths from gem dependencies.
- Ensures that stylesheet assets from gems like govuk_template, govuk_elements_rails, bootstrap-sass, font-awesome-rails and govuk_frontend_toolkit are discoverable by the asset pipeline.
- Logs a debug message in development if a gem's asset path cannot be added, preventing errors if a gem is not present.
---
 lib/lr_common_styles/engine.rb | 47 ++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/lib/lr_common_styles/engine.rb b/lib/lr_common_styles/engine.rb
index eb1e7c5..02be111 100644
--- a/lib/lr_common_styles/engine.rb
+++ b/lib/lr_common_styles/engine.rb
@@ -1,6 +1,53 @@
 # frozen_string_literal: true
 
+# :nodoc:
 module LrCommonStyles
+  # :nodoc:
   class Engine < ::Rails::Engine
+    initializer 'lr_common_styles.assets' do |app|
+      # Only configure asset paths if an asset pipeline is available
+      if app.config.respond_to?(:assets)
+        # Add this gem's asset paths
+        assets_path = root.join('app', 'assets', 'stylesheets')
+        unless app.config.assets.paths.include?(assets_path.to_s)
+          app.config.assets.paths << assets_path
+        end
+
+        # Add asset paths for gem dependencies so they're discoverable
+        # when scss files import them
+        dependency_gems = %w[
+          govuk_template
+          govuk_elements_rails
+          bootstrap-sass
+          font-awesome-rails
+          govuk_frontend_toolkit
+        ]
+
+        dependency_gems.each do |gem_name|
+          gem_spec = Gem.loaded_specs[gem_name]
+          if gem_spec
+            gem_assets_path = File.join(gem_spec.gem_dir, 'app', 'assets', 'stylesheets')
+            if File.directory?(gem_assets_path) && app.config.assets.paths.exclude?(gem_assets_path)
+              app.config.assets.paths << gem_assets_path
+            end
+          end
+        rescue StandardError => e
+          # Log but don't fail if gem is not available
+          if Rails.env.development?
+            Rails.logger.debug do
+              "Could not add asset path for #{gem_name}: #{e.message}"
+            end
+          end
+        end
+      end
+    end
+
+    initializer 'lr_common_styles.debug' do |app|
+      if Rails.env.development? && app.config.respond_to?(:assets)
+        puts "\nAsset paths:\n#{app.config.assets.paths.map do |path|
+          "#{path.inspect}\n"
+        end.join}\n"
+      end
+    end
   end
 end

From 9dc083fdb46164d298668fbc8392bb4a013bb78c Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 16:07:10 +0000
Subject: [PATCH 11/19] refactor: Configure assets conditionally

- Modifies asset precompilation logic to only execute when Sprockets is available.
- Prevents errors in Rails 8+ which use Propshaft by default and no longer have `config.assets`.
- Improves compatibility across different Rails versions and asset pipeline configurations.
---
 config/initializers/lr_common_styles_assets.rb |  5 ++++-
 test/dummy/config/initializers/assets.rb       | 17 ++++++++++-------
 2 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/config/initializers/lr_common_styles_assets.rb b/config/initializers/lr_common_styles_assets.rb
index c5ecbfb..937140b 100644
--- a/config/initializers/lr_common_styles_assets.rb
+++ b/config/initializers/lr_common_styles_assets.rb
@@ -1,3 +1,6 @@
 # frozen_string_literal: true
 
-Rails.application.config.assets.precompile += %w[favicon/*]
+# Only configure asset precompilation if Sprockets is available (Rails < 8 or explicit sprockets-rails)
+if Rails.application.config.respond_to?(:assets)
+  Rails.application.config.assets.precompile += %w[favicon/*]
+end
diff --git a/test/dummy/config/initializers/assets.rb b/test/dummy/config/initializers/assets.rb
index 678efe9..2acfd78 100644
--- a/test/dummy/config/initializers/assets.rb
+++ b/test/dummy/config/initializers/assets.rb
@@ -2,12 +2,15 @@
 
 # Be sure to restart your server when you modify this file.
 
-# Version of your assets, change this if you want to expire all your assets.
-Rails.application.config.assets.version = '1.0'
+# Only configure assets if an asset pipeline is available (Sprockets or Propshaft)
+if Rails.application.config.respond_to?(:assets)
+  # Version of your assets, change this if you want to expire all your assets.
+  Rails.application.config.assets.version = '1.0'
 
-# Add additional assets to the asset load path
-# Rails.application.config.assets.paths << Emoji.images_path
+  # Add additional assets to the asset load path
+  # Rails.application.config.assets.paths << Emoji.images_path
 
-# Precompile additional assets.
-# application.js, application.css, and all non-JS/CSS in app/assets folder are already added.
-# Rails.application.config.assets.precompile += %w( search.js )
+  # Precompile additional assets.
+  # application.js, application.css, and all non-JS/CSS in app/assets folder are already added.
+  # Rails.application.config.assets.precompile += %w( search.js )
+end

From 2f1c4dca31c193dd69a254549e5c46ea8fd09b0b Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 16:08:39 +0000
Subject: [PATCH 12/19] chore(assets): Removes unused stylesheet link

- Tidies up unused asset reference to the `lr_common_styles` stylesheet from the asset manifest aligning with updates related to Ruby Sass deprecation and end-of-life
---
 app/assets/config/manifest.js | 1 -
 1 file changed, 1 deletion(-)

diff --git a/app/assets/config/manifest.js b/app/assets/config/manifest.js
index 609946e..a2de13e 100644
--- a/app/assets/config/manifest.js
+++ b/app/assets/config/manifest.js
@@ -1,3 +1,2 @@
 //= link_tree ../images
 //= link_directory ../javascripts/lr_common_styles .js
-//= link_directory ../stylesheets/lr_common_styles .css

From a0aa0874bb81fb3c5f1813f0f6c0186c531271b7 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 16:09:06 +0000
Subject: [PATCH 13/19] refactor: Updates asset loading instructions

- Clarifies asset loading instructions for both Sprockets and Propshaft, promoting a consistent approach.
- Removes framework dependency imports from the common styles file, instead requiring host applications to manage these dependencies.
- Explains the automatic registration of asset paths, ensuring discoverability within host applications.
---
 app/assets/stylesheets/lr_common_styles.scss | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/app/assets/stylesheets/lr_common_styles.scss b/app/assets/stylesheets/lr_common_styles.scss
index 7c65660..fbcb8aa 100644
--- a/app/assets/stylesheets/lr_common_styles.scss
+++ b/app/assets/stylesheets/lr_common_styles.scss
@@ -1,11 +1,19 @@
 /*
- * Entry point stylesheet for Propshaft-enabled apps.
- * Hosts should include "lr_common_styles.css".
- * Sprockets users may continue to link directory assets as before.
+ * Entry point stylesheet for both Sprockets and Propshaft-enabled apps.
+ *
+ * This file includes only LR Common Styles internal assets.
+ * Host applications are responsible for importing framework dependencies:
+ *   @import "govuk-template";
+ *   @import "govuk-elements";
+ *   @import "bootstrap-sprockets";
+ *   @import "bootstrap";
+ *   @import "font-awesome";
+ *   @import "lr_common_styles";
+ *
+ * The asset paths for these dependencies are automatically registered by the engine,
+ * so they will be discoverable when imported directly from host applications.
  */
 
-
-
 // LR Common Styles partials
 @import "lr_common_styles/common-elements";
 @import "lr_common_styles/cookie-banner";

From feacaf0a15b3345c151b23c07e768263df4c877b Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 16:10:34 +0000
Subject: [PATCH 14/19] fix(test): Add sprockets-rails for test app

- Adds `sprockets-rails` gem to the test dummy application.
- Resolves a dependency issue in the test environment, ensuring proper asset compilation and functionality during testing.
- This change is necessary to maintain the integrity of the test suite following updates to related dependencies.
---
 Gemfile      |  1 +
 Gemfile.lock | 10 +++++++++-
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/Gemfile b/Gemfile
index cfb108a..b86fca9 100644
--- a/Gemfile
+++ b/Gemfile
@@ -20,6 +20,7 @@ group :development, :test do
   gem 'rubocop'
   gem 'rubocop-ast'
   gem 'rubocop-rails'
+  gem 'sprockets-rails' # Required for test dummy app
 end
 
 group :development do
diff --git a/Gemfile.lock b/Gemfile.lock
index 26e7c84..4b7e725 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -394,6 +394,14 @@ GEM
       yard (~> 0.9, >= 0.9.24)
       yard-activesupport-concern (~> 0.0)
       yard-solargraph (~> 0.1)
+    sprockets (4.2.2)
+      concurrent-ruby (~> 1.0)
+      logger
+      rack (>= 2.2.4, < 4)
+    sprockets-rails (3.5.2)
+      actionpack (>= 6.1)
+      activesupport (>= 6.1)
+      sprockets (>= 3.0.0)
     stringio (3.1.7)
     temple (0.10.4)
     thor (1.4.0)
@@ -436,7 +444,6 @@ PLATFORMS
 
 DEPENDENCIES
   byebug
-  dartsass-rails (~> 0.5.1)
   lr_common_styles!
   minitest-rails
   mocha
@@ -446,6 +453,7 @@ DEPENDENCIES
   rubocop-rails
   ruby-lsp
   solargraph
+  sprockets-rails
 
 BUNDLED WITH
    2.7.2

From 76dc4c9ca5cbf77ad7d9c7ff1e66ab4c2d590cf7 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 16:15:08 +0000
Subject: [PATCH 15/19] chore(Makefile): Updates make targets and adds help

- Updates and clarifies Makefile targets for gem building, testing and publishing.
- Adds a `help` target to display available make commands and environment variables.
- Renames and adds descriptions for each other target.
---
 Makefile | 45 +++++++++++++++++++++++++++++++--------------
 1 file changed, 31 insertions(+), 14 deletions(-)

diff --git a/Makefile b/Makefile
index 76418dd..002a055 100644
--- a/Makefile
+++ b/Makefile
@@ -21,42 +21,59 @@ ${GEM}: ${SPEC} ./lib/${NAME}/version.rb
 
 all: publish
 
-assets: auth
-	@echo "Installing all packages ..."
-	@bundle install
+assets: auth bundle compile ## Compile assets for gem distribution
+	@echo assets completed.
+
+auth: ${AUTH} ## Set up authentication for GitHub Packages
+	@echo "Authentication set up for GitHub Packages."
 
-auth: ${AUTH}
+build: gem ## Build the gem package
 
-build: gem
+bundle: ## Install Ruby gems via Bundler
+	@echo "Installing Ruby gems via Bundler..."
+	@bundle install
 
-checks: lint test
+checks: lint test ## Run all checks: linting and tests
+	@echo "All checks passed."
 
-clean:
+clean: ## Clean up gem files
+	@echo "Cleaning up ${GEM} files..."
 	@rm -rf ${GEM}
 
-gem: ${GEM}
+compile: ## Compile assets for gem distribution
+	@echo "Removing old compiled assets and compiling ..."
+	@rake assets:clobber assets:precompile
+
+gem: ${GEM} ## Alias for `gem` target
 	@echo ${GEM}
 
-lint: assets
+help: ## Display this message
+	@echo "Available make targets:"
+	@grep -hE '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "%-20s %s\n", $$1, $$2}'
+	@echo ""
+	@echo "Environment variables (optional: all variables have defaults):"
+	@make vars
+
+lint: assets ## Run linting checks
 	@echo "Running rubocop..."
 	@bundle exec rubocop
 
-publish: ${AUTH} ${GEM}
+publish: ${AUTH} ${GEM} ## Publish the gem to GitHub Packages
 	@echo Publishing package ${NAME}:${VERSION} to ${OWNER} ...
 	@gem push --key github --host ${GPR} ${GEM}
 	@echo Done.
 
-realclean: clean
+realclean: clean ## Remove all generated files including authentication
 	@rm -rf ${AUTH}
 
-tags:
+tags: ## Show version tags
 	@echo version=${VERSION}
 
-test: assets
+test: assets ## Run tests in the dummy application
 	@echo "Running tests..."
 	@rake test
 
-vars:
+vars: ## Show important variables
 	@echo "GEM"	= ${GEM}
 	@echo "GPR"	= ${GPR}
 	@echo "NAME = ${NAME}"

From d54dd60df793749038eab9c855330f6c97ac27d3 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 16:47:01 +0000
Subject: [PATCH 16/19] chore: Updates version to 2.4.0-beta

- Updates the gem version to reflect pre-release status.
- This change is due to ongoing modifications and the need for beta testing.
---
 lib/lr_common_styles/version.rb | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/lib/lr_common_styles/version.rb b/lib/lr_common_styles/version.rb
index 963691c..d7105a4 100644
--- a/lib/lr_common_styles/version.rb
+++ b/lib/lr_common_styles/version.rb
@@ -2,8 +2,8 @@
 
 module LrCommonStyles
   MAJOR = 2
-  MINOR = 3
-  PATCH = 1
-  SUFFIX = nil # nil or 'rc' or 'beta' or 'alpha' for pre-release versions
-  VERSION = "#{MAJOR}.#{MINOR}.#{PATCH}#{SUFFIX && "-#{SUFFIX}"}".freeze
+  MINOR = 4
+  PATCH = 0
+  SUFFIX = 'beta' # nil or 'rc' or 'beta' or 'alpha' for pre-release versions
+  VERSION = "#{MAJOR}.#{MINOR}.#{PATCH}#{SUFFIX && ".#{SUFFIX}"}".freeze
 end

From 3661bce73b6968d5f120b17441a460ee1f9aee58 Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 16:52:34 +0000
Subject: [PATCH 17/19] chore: update lr_common_styles gem version

- Updates the `lr_common_styles` gem to version 2.4.0.beta.
- This is to test compatibility issues arising from the end-of-life for Ruby Sass.
---
 Gemfile.lock | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Gemfile.lock b/Gemfile.lock
index 4b7e725..fa49247 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lr_common_styles (2.3.1)
+    lr_common_styles (2.4.0.beta)
       bootstrap-sass (~> 3.4.1)
       dartsass-rails (~> 0.5.1)
       font-awesome-rails (~> 4.7.0)

From faffe6d63b0fda9ef15e20e6f0f92a60f06cbc4a Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 16:52:56 +0000
Subject: [PATCH 18/19] chore(build): Refactor Makefile for clearer gem
 building process

- Updates the `build` target to explicitly signal that it is an alias for the `gem` target.
- Modifies the `gem` target to directly use `gem build` command with the `.spec` file, ensuring correct gem package creation.
- Clarifies output messages for the `build` target.
---
 Makefile | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
index 002a055..2fa8b2b 100644
--- a/Makefile
+++ b/Makefile
@@ -27,7 +27,8 @@ assets: auth bundle compile ## Compile assets for gem distribution
 auth: ${AUTH} ## Set up authentication for GitHub Packages
 	@echo "Authentication set up for GitHub Packages."
 
-build: gem ## Build the gem package
+build: gem ## Alias for the gem target
+	@echo "Built ${GEM}."
 
 bundle: ## Install Ruby gems via Bundler
 	@echo "Installing Ruby gems via Bundler..."
@@ -44,8 +45,8 @@ compile: ## Compile assets for gem distribution
 	@echo "Removing old compiled assets and compiling ..."
 	@rake assets:clobber assets:precompile
 
-gem: ${GEM} ## Alias for `gem` target
-	@echo ${GEM}
+gem: ${GEM} ## Build the gem package
+	@gem build ${SPEC}
 
 help: ## Display this message
 	@echo "Available make targets:"

From 47dcc07770f76cf87d5c20a61e98057cdfa4436c Mon Sep 17 00:00:00 2001
From: "Jon R. Humphrey" <jon.humphrey@epimorphics.com>
Date: Tue, 30 Dec 2025 17:08:35 +0000
Subject: [PATCH 19/19] docs: Updated CHANGELOG

- Introduces Propshaft asset pipeline support, ensuring compatibility with Rails 8+.
- Registers framework gem asset paths automatically within the engine initialiser.
- Replaces `sass-rails` with `dartsass-rails` as the primary SCSS compiler.
- Refactors the SCSS entrypoint to streamline Common Styles imports.
- Includes a `help` target in the Makefile to list available commands.
- Updates the test dummy app configuration for Propshaft/Sprockets compatibility.
---
 CHANGELOG.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6191fde..f995c13 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,44 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.0] - 2025-12-30
+
+### Added
+
+- Adds a `help` target in the Makefile to list available commands
+- Introduced Propshaft asset pipeline support (Rails 8+) alongside existing
+  Sprockets compatibility
+- Refactored Engine initialiser to automatically register framework gem asset
+  paths (govuk_template, govuk_elements_rails, bootstrap-sass,
+  font-awesome-rails, govuk_frontend_toolkit)
+- Added development environment logging for asset path registration in debug
+  mode
+- Added `make compile` target to clobber and precompile gem assets; also run via
+  make assets for consistent builds
+- Includes code guards to ensure asset pipeline configuration only runs when
+  assets pipeline is available
+
+### Changed
+
+- Replaced `sass-rails` with `dartsass-rails` as primary SCSS compiler
+  dependency
+- Refactored SCSS entrypoint (`lr_common_styles.scss`) to contain only internal
+  Common Styles imports; host applications are now responsible for importing
+  framework dependencies
+- Updated `app/assets/config/manifest.js` to remove incorrect stylesheet
+  directory link and duplicate build references
+- Test dummy app configuration also now guards asset configuration with
+  `respond_to?(:assets)` check for compatibility with Propshaft/Sprockets
+- Gem initialiser configuration now conditional on asset pipeline presence,
+  enabling seamless operation in both Sprockets and Propshaft environments
+
+### Fixed
+
+- Clarified asset dependency structure through updated documentation in SCSS
+  entrypoint
+- Removed misleading configuration directives that conflicted with host
+  application asset compilation
+
 ## [2.3.1] - 2025-10
 
 ### Changed