Customizer-Based Design System

caution

Avoid changing Customizer values directly in the database on production. Use the Customizer UI or a controlled WP-CLI workflow on staging, then export/import.

Customizer-Based Design System Explained

Concept	What it means in GeneratePress	Where to look
Customizer configs	PHP files that declare settings/controls	`/wp-content/themes/generatepress/inc/customizer/` and `/inc/customizer/configs/`
Theme mods	Saved Customizer values for the active theme	`wp option get theme_mods_generatepress`
Defaults	Fallbacks used when no user value exists	`/wp-content/themes/generatepress/inc/defaults.php` (and related)
Output	CSS/markup changes generated from settings	Typically via `wp_head`, inline styles, or enqueue logic

Why It Matters

Consistency: Customizer settings become your site's global design tokens (layout widths, typography scales, color palette).
Auditability: you can export/import settings and treat them as artifacts in a deployment workflow.
Performance: GeneratePress aims to output only what is needed; knowing the pipeline helps you avoid redundant CSS and cache thrash.

How It Works

GeneratePress registers Customizer settings and controls via the WordPress Customizer API. When a user saves a value, WordPress stores it as theme mods. On the front end, the theme reads those mods and outputs CSS/markup accordingly.

flowchart LR
  UI[Customizer UI] --> API[customize_register]
  API --> MODS[(theme_mods_generatepress)]
  MODS --> THEME[GeneratePress reads mods]
  THEME --> OUT[CSS + markup output]

Practical Walkthrough

Step 1: Inspect the Customizer Directory

inspect-customizer-files.sh
cd /var/www/html/wp-content/themes/generatepress
ls inc/customizer
ls inc/customizer/configs

Expected output (example):

controls.php  defaults.php  init.php  configs/

Step 2: Find Where Settings Are Registered

find-customize-register.sh
cd /var/www/html/wp-content/themes/generatepress
grep -R "customize_register" -n inc/customizer | head -n 25

Step 3: View Saved Theme Mods with WP-CLI

view-theme-mods.sh
cd /var/www/html
wp option get theme_mods_generatepress --format=json

Expected output (example, truncated):

{
  "container_width": 1100,
  "body_font_family": "System",
  "link_color": "#1e73be"
}

Step 4: Locate the Source of a Specific Setting

Example: find where container_width is defined.

locate-setting-definition.sh
cd /var/www/html/wp-content/themes/generatepress
grep -R "container_width" -n inc/customizer inc/defaults.php | head -n 25

Practical Examples

Example 1: Export and Import Customizer Settings

If your stack includes a Customizer export/import workflow, treat it like a deployable config artifact.

export-import-customizer.sh
cd /var/www/html
wp customizer export > gp-customizer.json
wp customizer import gp-customizer.json

warning

Run imports on staging first. A bad import can change layout, colors, and typography site-wide.

Example 2: Diff Settings Between Environments

capture-and-diff-mods.sh
cd /var/www/html
wp option get theme_mods_generatepress --format=json > /tmp/theme_mods_generatepress.json
wc -l /tmp/theme_mods_generatepress.json

Outcome: you now have a file you can diff between staging and production to explain design drift.

Best Practices

Practice	Why it helps
Use Customizer for global design tokens	Keeps styles consistent and reduces one-off CSS
Prefer export/import for promotions	Makes visual config reproducible
Keep site-wide changes out of ad-hoc DB edits	Avoids hard-to-debug state
Purge cache after significant Customizer changes	LSCache can hold stale HTML/CSS

Troubleshooting

Issue	Cause	Fix
Customizer changes not visible	Page cache / CSS cache	Purge LSCache, and verify output logged-out
Missing settings panels	GP Premium module disabled (or theme version mismatch)	Verify plugin modules and theme version; re-check `inc/customizer/configs/`
`wp option get theme_mods_generatepress` empty	Theme mods stored under a different key	List options with `wp option list
Live preview laggy	Heavy plugins or Customizer JS conflicts	Disable plugins temporarily and re-test on staging

Hands-On

Run wp option get theme_mods_generatepress --format=json and identify 3 settings you recognize.
Use grep to locate where one of those settings is declared.
Export your Customizer settings to gp-customizer.json and store it with your deployment notes.

Quick Reference

Task	Command
List Customizer configs	`ls /var/www/html/wp-content/themes/generatepress/inc/customizer/configs`
View saved settings	`wp option get theme_mods_generatepress --format=json`
Search for a setting	`grep -R "setting_name" -n inc/customizer`

What's Next

Next: Global Layout Framework
Related: Theme Architecture