Merge pull request #5 from lincolnloop/make-css-customizable-per-project

dchukhin · web-flow · commit 9d7a6f9c3f2d · 2025-09-18T13:14:49.000-04:00
Make Pattern Library CSS Customizable
diff --git a/pattern_library/__init__.py b/pattern_library/__init__.py
@@ -35,6 +35,13 @@
         ("templates", ["patterns/templates"]),
         ("pages", ["patterns/pages"]),
     ),
+    # CUSTOM_CSS allows users to override pattern library styles by providing a path to a CSS file
+    # (relative to STATIC_URL) that contains CSS custom properties. This file will be included
+    # after the main bundle to override default styles.
+    # Example: "css/pattern-library-custom.css"
+    "CUSTOM_CSS": None,
+    # SITE_TITLE allows users to customize the pattern library title displayed in the header
+    "SITE_TITLE": "Django Pattern Library",
 }
 
 
diff --git a/pattern_library/static/pattern_library/src/scss/_config.scss b/pattern_library/static/pattern_library/src/scss/_config.scss
@@ -1,7 +1,14 @@
-// Overwrite the title, main colour and font family here
-$site-title: 'Django Pattern Library';
-$color-primary: #34b2b2;
-$family-primary: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif;
+// Configuration with support for runtime customization via CSS custom properties
+
+// Default SCSS variables for compile-time usage (needed for Sass functions)
+$color-primary: #34b2b2 !default;
+$family-primary: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif !default;
+
+// CSS Custom Properties for runtime customization
+html, :root {
+  --color-primary: #{$color-primary};
+  --family-primary: #{$family-primary};
+}
 
 // $color--primary + $family--primary are in _config.scss
 $white: #fff;
diff --git a/pattern_library/static/pattern_library/src/scss/abstracts/_base.scss b/pattern_library/static/pattern_library/src/scss/abstracts/_base.scss
@@ -9,7 +9,7 @@
 html,
 body {
     margin: 0;
-    font-family: $family-primary;
+    font-family: var(--family-primary);
     height: 100%;
 }
 
diff --git a/pattern_library/static/pattern_library/src/scss/components/_list.scss b/pattern_library/static/pattern_library/src/scss/components/_list.scss
@@ -70,7 +70,7 @@
         &:hover,
         &.is-active {
             background: $white;
-            border-left: 5px solid $color-primary;
+            border-left: 5px solid var(--color-primary);
         }
     }
 }
diff --git a/pattern_library/static/pattern_library/src/scss/components/_tabbed-listing.scss b/pattern_library/static/pattern_library/src/scss/components/_tabbed-listing.scss
@@ -25,14 +25,14 @@
 
             &:hover {
                 color: #000;
-                background-color: $color-primary;
+                background-color: var(--color-primary);
             }
         }
 
         &--active {
             > a {
                 color: #000;
-                background-color: $color-primary;
+                background-color: var(--color-primary);
             }
         }
 
diff --git a/pattern_library/static/pattern_library/src/scss/layout/_header.scss b/pattern_library/static/pattern_library/src/scss/layout/_header.scss
@@ -1,7 +1,7 @@
 @use "../config" as *;
 
 .header {
-    background-color: $color-primary;
+    background-color: var(--color-primary);
     display: flex;
     align-items: center;
     height: 45px;
@@ -17,10 +17,8 @@
         letter-spacing: 1px;
         font-size: 16px;
         margin-left: 15px;
-
-        &::after {
-            content: $site-title;
-        }
+        margin-top: 0;
+        margin-bottom: 0;
 
         @media only screen and (min-width: 600px) {
             font-size: 22px;
diff --git a/pattern_library/templates/pattern_library/base.html b/pattern_library/templates/pattern_library/base.html
@@ -1,4 +1,5 @@
 {% load static %}
+{% load pattern_library_tags %}
 
 <!DOCTYPE html>
 <html lang="en">
@@ -9,6 +10,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>♻️</text></svg>"/>
     <script type="text/javascript" src="{% static 'pattern_library/dist/bundle.js' %}"></script>
+    {% pattern_library_custom_css %}
 </head>
 
 <body class="body">
@@ -19,7 +21,7 @@
         </a>
         <h1 class="header__title">
             <span class="sr-only">Pattern Library</span>
-            {# Set in _config.scss #}
+            {% pattern_library_site_title %}
         </h1>
     </header>
     <aside class="sidebar">
diff --git a/pattern_library/templatetags/__init__.py b/pattern_library/templatetags/__init__.py
@@ -0,0 +1 @@
+# Template tags for django-pattern-library
diff --git a/pattern_library/templatetags/pattern_library_tags.py b/pattern_library/templatetags/pattern_library_tags.py
@@ -0,0 +1,51 @@
+from django import template
+from django.templatetags.static import static
+from django.utils.safestring import mark_safe
+
+from pattern_library import get_setting
+
+register = template.Library()
+
+
+@register.simple_tag
+def pattern_library_custom_css():
+    """
+    Include custom CSS for pattern library customization.
+
+    This tag optionally includes an external CSS file for additional customization.
+
+    Usage in templates:
+        {% load pattern_library_tags %}
+        {% pattern_library_custom_css %}
+
+    Example PATTERN_LIBRARY setting:
+        PATTERN_LIBRARY = {
+            "CUSTOM_CSS": "css/pattern-library-custom.css"  # relative to STATIC_URL
+        }
+    """
+    css_content = []
+
+    # Include external CSS file if specified
+    custom_css_path = get_setting("CUSTOM_CSS")
+    if custom_css_path:
+        try:
+            css_url = static(custom_css_path)
+            css_content.append(
+                f'<link rel="stylesheet" type="text/css" href="{css_url}">'
+            )
+        except Exception:
+            pass  # If static file handling fails, just skip the external file
+
+    return mark_safe("\n".join(css_content))
+
+
+@register.simple_tag
+def pattern_library_site_title():
+    """
+    Get the site title for the pattern library.
+
+    Usage in templates:
+        {% load pattern_library_tags %}
+        {% pattern_library_site_title %}
+    """
+    return get_setting("SITE_TITLE")

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@`
`9`	`9`	`html,`
`10`	`10`	`body {`
`11`	`11`	`margin: 0;`
`12`		`- font-family: $family-primary;`
	`12`	`+ font-family: var(--family-primary);`
`13`	`13`	`height: 100%;`
`14`	`14`	`}`
`15`	`15`
Original file line number	Diff line number	Diff line change
`@@ -70,7 +70,7 @@`
`70`	`70`	`&:hover,`
`71`	`71`	`&.is-active {`
`72`	`72`	`background: $white;`
`73`		`- border-left: 5px solid $color-primary;`
	`73`	`+ border-left: 5px solid var(--color-primary);`
`74`	`74`	`}`
`75`	`75`	`}`
`76`	`76`	`}`
Original file line number	Diff line number	Diff line change
`@@ -25,14 +25,14 @@`
`25`	`25`
`26`	`26`	`&:hover {`
`27`	`27`	`color: #000;`
`28`		`- background-color: $color-primary;`
	`28`	`+ background-color: var(--color-primary);`
`29`	`29`	`}`
`30`	`30`	`}`
`31`	`31`
`32`	`32`	`&--active {`
`33`	`33`	`> a {`
`34`	`34`	`color: #000;`
`35`		`- background-color: $color-primary;`
	`35`	`+ background-color: var(--color-primary);`
`36`	`36`	`}`
`37`	`37`	`}`
`38`	`38`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+# Template tags for django-pattern-library`