Fix CSS overrides in applications (#12646)

* Declare new override entrypoint for frontend * Declare new override entrypoint for admin * Declare new override entrypoint for system panel * Add documentation * Add overrides in the design app to facilitate the development of new themes * Apply suggestions from code review Co-authored-by: Andrés Pereira de Lucena <andreslucena@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Andrés Pereira de Lucena <andreslucena@users.noreply.github.com> * Add docs * Add Readme * Lint * Apply suggestions from code review Co-authored-by: Andrés Pereira de Lucena <andreslucena@users.noreply.github.com> --------- Co-authored-by: Andrés Pereira de Lucena <andreslucena@users.noreply.github.com>
decidim · May 9, 2024 · 359b793 · 359b793
1 parent 2457682
commit 359b793
Show file tree

Hide file tree

Showing 16 changed files with 58 additions and 8 deletions.
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -116,7 +116,20 @@ bin/rails decidim:upgrade:fix_orphan_categorizations
 
 You can read more about this change on PR [\#12143](https://github.com/decidim/decidim/pull/12143).
 
-### 3.5. [[TITLE OF THE ACTION]]
+### 3.5. Improved CSS overrides
+
+We have improved the CSS overriding mechanism. This is what allows you to change the CSS of decidim in your application in a more granular way.
+
+Previously, you could do this by adding CSS rules in the `app/packs/stylesheets/decidim/decidim_application.scss` file. This file remains in place but is loaded as the last file in the application, so it will take precedence over all the CSS rules from the Decidim modules.
+
+Additionally, if you need, you can also customize the `admin` and `system` interfaces by creating in your application the following files:
+
+- `app/packs/stylesheets/decidim/admin/decidim_application.scss` for admin interface
+- `app/packs/stylesheets/decidim/system/decidim_application.scss` for system interface
+
+You can read more about this change on PR [\#12646](https://github.com/decidim/decidim/pull/12646).
+
+### 3.6. [[TITLE OF THE ACTION]]
 
 You can read more about this change on PR [\#XXXX](https://github.com/decidim/decidim/pull/XXXX).
 

diff --git a/decidim-admin/app/packs/entrypoints/decidim_admin_overrides.scss b/decidim-admin/app/packs/entrypoints/decidim_admin_overrides.scss
@@ -0,0 +1,2 @@
+// Application specific styles: https://docs.decidim.org/en/customize/styles/
+@import "stylesheets/decidim/admin/decidim_application";
diff --git a/decidim-admin/app/packs/stylesheets/decidim/admin/decidim_application.scss b/decidim-admin/app/packs/stylesheets/decidim/admin/decidim_application.scss
@@ -0,0 +1,5 @@
+// This is a file that can be overridden by the application in order to override styles
+// Notice that this file is included at the very end of the stylesheets packs to have
+// more priority
+//
+// By default this is empty.
diff --git a/decidim-admin/app/views/layouts/decidim/admin/_header.html.erb b/decidim-admin/app/views/layouts/decidim/admin/_header.html.erb
@@ -3,6 +3,7 @@
 <%= legacy_favicon %>
 <%= favicon %>
 <%= apple_favicon %>
+<%= append_stylesheet_pack_tag "decidim_admin_overrides", media: "all" %>
 <%= stylesheet_pack_tag "decidim_core", "decidim_admin", media: "all" %>
 <%= javascript_pack_tag "decidim_core", "decidim_admin", defer: false %>
 <%= snippets.display(:head) %>
diff --git a/decidim-admin/config/assets.rb b/decidim-admin/config/assets.rb
@@ -4,5 +4,6 @@
 
 Decidim::Webpacker.register_path("#{base_path}/app/packs")
 Decidim::Webpacker.register_entrypoints(
+ decidim_admin_overrides: "#{base_path}/app/packs/entrypoints/decidim_admin_overrides.scss",
  decidim_admin: "#{base_path}/app/packs/entrypoints/decidim_admin.js"
 )
diff --git a/decidim-core/app/packs/entrypoints/decidim_overrides.scss b/decidim-core/app/packs/entrypoints/decidim_overrides.scss
@@ -0,0 +1,2 @@
+// Application specific styles: https://docs.decidim.org/en/customize/styles/
+@import "stylesheets/decidim/decidim_application";
diff --git a/decidim-core/app/packs/stylesheets/decidim/application.scss b/decidim-core/app/packs/stylesheets/decidim/application.scss
@@ -82,6 +82,3 @@
 // This imports all the Decidim module stylesheet imports registered at
 // `config/assets.rb` of the module for the "app" group.
 @import "!decidim-style-imports[app]";
-
-// Application specific styles: https://docs.decidim.org/en/customize/styles/#_webpacker
-@import "stylesheets/decidim/decidim_application";
diff --git a/decidim-core/app/packs/stylesheets/decidim/decidim_application.scss b/decidim-core/app/packs/stylesheets/decidim/decidim_application.scss
@@ -2,4 +2,8 @@
 // Notice that this file is included at the very end of the stylesheets packs to have
 // more priority
 //
+// Please note this file is only targeting the end user interface and not the admin interface.
+// To change the Tailwind CSS configuration, or to override the admin, system or design interface
+// styles follow the instructions in https://docs.decidim.org/en/customize/styles/
+//
 // By default this is empty.
diff --git a/decidim-core/app/views/layouts/decidim/_head.html.erb b/decidim-core/app/views/layouts/decidim/_head.html.erb
@@ -27,6 +27,7 @@
 <link rel="manifest" href="/manifest.webmanifest">
 
 <%= prepend_javascript_pack_tag "decidim_core", defer: false %>
+<%= append_stylesheet_pack_tag "decidim_overrides", media: "all" %>
 <%= stylesheet_pack_tag "decidim_core", media: "all" %>
 <%= yield :css_content %>
 

diff --git a/decidim-core/config/assets.rb b/decidim-core/config/assets.rb
@@ -4,6 +4,7 @@
 
 Decidim::Webpacker.register_path("#{base_path}/app/packs")
 Decidim::Webpacker.register_entrypoints(
+ decidim_overrides: "#{base_path}/app/packs/entrypoints/decidim_overrides.scss",
  decidim_core: "#{base_path}/app/packs/entrypoints/decidim_core.js",
  decidim_sw: "#{base_path}/app/packs/entrypoints/decidim_sw.js",
  decidim_conference_diploma: "#{base_path}/app/packs/entrypoints/decidim_conference_diploma.js",

diff --git a/decidim-design/app/views/layouts/decidim/design/_head.html.erb b/decidim-design/app/views/layouts/decidim/design/_head.html.erb
@@ -1,5 +1,8 @@
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <%= javascript_pack_tag "decidim_core", "decidim_design", defer: false %>
-<%= stylesheet_pack_tag "decidim_core", "decidim_design", media: "all" %>
+
+<%= append_stylesheet_pack_tag "decidim_overrides", media: "all" %>
+<%= append_stylesheet_pack_tag "decidim_design", media: "all" %>
+<%= stylesheet_pack_tag "decidim_core", media: "all" %>
 <%= organization_colors %>
 <%= render partial: "layouts/decidim/js_configuration" %>
diff --git a/decidim-system/app/packs/entrypoints/decidim_system_overrides.scss b/decidim-system/app/packs/entrypoints/decidim_system_overrides.scss
@@ -0,0 +1,2 @@
+// Application specific styles: https://docs.decidim.org/en/customize/styles/
+@import "stylesheets/decidim/system/decidim_application";
diff --git a/decidim-system/app/packs/stylesheets/decidim/system/decidim_application.scss b/decidim-system/app/packs/stylesheets/decidim/system/decidim_application.scss
@@ -0,0 +1,5 @@
+// This is a file that can be overridden by the application in order to override styles
+// Notice that this file is included at the very end of the stylesheets packs to have
+// more priority
+//
+// By default this is empty.
diff --git a/decidim-system/app/views/layouts/decidim/system/_header.html.erb b/decidim-system/app/views/layouts/decidim/system/_header.html.erb
@@ -1,4 +1,5 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <%= csrf_meta_tags %>
+<%= append_stylesheet_pack_tag "decidim_system_overrides", media: "all" %>
 <%= stylesheet_pack_tag "decidim_core", "decidim_system", media: "all" %>
 <%= javascript_pack_tag "decidim_core", "decidim_system", defer: false %>
diff --git a/decidim-system/config/assets.rb b/decidim-system/config/assets.rb
@@ -4,5 +4,6 @@
 
 Decidim::Webpacker.register_path("#{base_path}/app/packs")
 Decidim::Webpacker.register_entrypoints(
+ decidim_system_overrides: "#{base_path}/app/packs/entrypoints/decidim_system_overrides.scss",
  decidim_system: "#{base_path}/app/packs/entrypoints/decidim_system.js"
 )
diff --git a/docs/modules/customize/pages/styles.adoc b/docs/modules/customize/pages/styles.adoc
@@ -50,11 +50,11 @@ image::header-snippet.png[Header snippet]
 
 Notice that you can resize this textarea.
 
-== Webpacker
+== Shakapacker
 
-Decidim uses Webpacker to compile assets. There are two ways to customize CSS:
+Decidim uses Shakapacker to compile assets. There are two ways to customize CSS:
 
-1. if you want to redefine a specific snippet of CSS (say a few classes but not a whole file) you can use decidim_application.scss
+1. if you want to redefine a specific snippet of CSS (say a few classes but not a whole file) you can use decidim_application.scss. You can read more about this in the <<Overriding CSS and styles>> section.
 2. and of course you can overwrite whole files by copying them into the application i.e: to replace `decidim-core/app/packs/stylesheets/decidim/modules/_data-consent.scss` you should create in your Rails app a file in `app/packs/stylesheets/decidim/modules/_data-consent.scss` and it will have more priority over the Decidim file.
 3. if you want to customize the application colors yo can use the admin interface.
 
@@ -68,6 +68,17 @@ Since this file is being managed by Decidim, it will be impossible to customize
 
 You can override the default configuration by creating a file `config/tailwind.config.js.erb` starting from the following https://github.com/decidim/decidim/blob/develop/decidim-core/lib/decidim/assets/tailwind/tailwind.config.js.erb[content]
 
+== Overriding CSS and styles
+
+If you want to override a specific CSS class, you can do so by adding a new CSS class in your `app/assets/stylesheets/decidim_application.scss` file. This will allow you to override the default styles provided by Decidim.
+
+*Please note:* the above file is created by default when you install Decidim. Also the file is empty. This file allows you to edit *only* the end user styles.
+
+If you want to override other layouts, you can do so by creating new files:
+
+. /admin: `app/packs/stylesheets/decidim/admin/decidim_application.scss`
+. /system: `app/packs/stylesheets/decidim/system/decidim_application.scss`
+
 == Accessibility
 
 To maintain accessibility level, if you add new colors use a http://webaim.org/resources/contrastchecker/[Color contrast checker] (WCAG AA is mandatory, WCAG AAA is recommended)