Reference → Themes — Reference

Themes — Reference

The Themes surface controls the visual chrome of an SGEN site — the header, the footer, the mobile menu, the typography and color baseline, and the site-wide template set that every page renders inside of. It is the single place where an operator picks a starting visual identity and the layer that every SG-Builder page composes on top of.

This page is a reference for platform engineers and integrators who need to understand the theme surface before extending it, scripting against it, or mapping a customer site to a starter. The customer-facing walkthroughs for picking a theme and customizing the chrome live in the customer docs set; this page describes the shape of the surface, not the editorial flow.

Overview

Themes live under the Appearance module in SG-Admin. The module is broader than themes alone — it groups the chrome surfaces (header, footer, mobile menu), the global style baseline (typography, color, layout tokens), the menu builder, the widget library, the shortcode helper, and the theme picker itself. The theme picker is the entry point: it lists the installed themes, marks which one is active, and exposes the activation write.

The module is paired by convention: one half renders the views and prepares the data (theme list, header config, footer config, mobile menu config, styles and layouts, widget registry), the other half handles writes and returns AJAX responses (update header, update footer, update mobile menu, update styles, update navigation, activate theme).

Themes themselves are not user-authored on the SGEN platform — they ship from the platform vendor as packaged starters. Customers select one, then customize it via the surrounding Appearance surfaces (header, footer, menus, styles, widgets, custom CSS). A theme change does not replace customer content; pages, posts, and media stay intact. It does swap the default header, footer, and style tokens to the theme's bundled defaults.

Where it lives in SG-Admin:

Sidebar: SG-Admin → Appearance → Themes
URL prefix: /sg-admin/appearance/themes/
Sibling surfaces under Appearance: header, footer, mobile_menu, menu, styles_layouts, widgets, shortcodes_helper
View templates: application/views/Admin/Appearance/

Paired-controller note. Themes do not have their own dedicated paired-controller. They live inside the broader Appearance module, sharing its action layer with the other chrome surfaces. The activate-theme write is one method among six on that action layer.

┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Appearance → Themes │├──────────────────────────────────────────────────────────────────────┤│ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ││ │ │ │ │ │ │ ││ │ Aurora │ │ Granite │ │ Stride │ ││ │ [PREVIEW] │ │ [PREVIEW] │ │ [PREVIEW] │ ││ │ │ │ │ │ │ ││ │ ● ACTIVE │ │ [ Activate] │ │ [ Activate] │ ││ └──────────────┘ └──────────────┘ └──────────────┘ ││ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ││ │ your business │ │ Origin │ │ Pace │ ││ │ [PREVIEW] │ │ [PREVIEW] │ │ [PREVIEW] │ ││ │ [ Activate] │ │ [ Activate] │ │ [ Activate] │ ││ └──────────────┘ └──────────────┘ └──────────────┘ ││ │└──────────────────────────────────────────────────────────────────────┘

Actions

The Themes surface exposes the following operations. Each is described by what it does to the site state, not by its internal method name.

List installed themes

Returns the set of themes installed on the platform for this site. Each entry carries a slug, a display name, a preview thumbnail, a short description, the bundled font and color defaults, and the active flag. A site has at most one active theme at any time; the others are dormant but selectable.

Activate theme

Changes the active theme for the site. The activation write does three things: it stamps the new theme slug onto the site configuration, it loads the new theme's bundled header, footer, mobile menu, and styles-and-layouts defaults into the corresponding Appearance surfaces (overwriting their current values), and it triggers a cache flush so the front-end renders the new chrome on the next request.

Activation is destructive to the chrome customization layer. The current header, footer, mobile menu, and style tokens are replaced with the new theme's defaults. Operators who customized those surfaces should export their configuration first — there is no in-platform rollback. Customer content (pages, posts, media) is not touched.

Edit header configuration

Loads the active theme's header into an editor — logo, menu placement, contact bar, search affordance, sticky behavior, mobile breakpoint. Submit replaces the stored header configuration. The change applies site-wide on the next render.

Edit footer configuration

Same shape as the header editor — columns, copyright line, social links, newsletter widget slot, legal-link row. Submit replaces the stored footer configuration.

Edit mobile menu configuration

Mobile menu is configured independently from the desktop menu — drawer-vs-overlay, hamburger position, link list source, optional CTA pinned to the menu base.

Edit styles and layouts

The global typography and color baseline — font family per role (heading, body, accent), font sizes and line heights, color tokens (primary, secondary, neutral scale, surface, status), spacing scale, container widths, and breakpoint thresholds. SG-Builder reads from these tokens at render time; pages that did not override a token inherit the current value.

Edit menu (Menu Builder)

The site's navigation structure — primary nav, secondary nav, footer nav, custom menus. Each menu is a tree of items (label + link + optional icon + optional CSS class). Menus reference pages and posts by record ID, so renaming a page does not break the menu.

List widgets

The widget library — operator-droppable content blocks for widget areas. Includes a contact form widget, a recent-posts widget, a newsletter signup widget, a custom HTML widget, and theme-bundled extras.

List fonts

The font registry — Google fonts auto-discovered plus any self-hosted fonts uploaded via the Custom Fonts surface. Used by the styles-and-layouts editor's font pickers.

List icons

The icon library — bundled icon sets exposed for use in menus, widgets, and SG-Builder components.

Data model

A theme record (vendor-shipped) and the site's theme-related configuration carry the following fields.

Field	Type	Notes
`theme.slug`	string	Unique identifier. Stable across versions.
`theme.name`	string	Display name.
`theme.version`	string	Vendor-set version stamp.
`theme.thumbnail_url`	string	Preview image for the picker.
`theme.bundle.header_defaults`	JSON	Header configuration loaded on activation.
`theme.bundle.footer_defaults`	JSON	Footer configuration loaded on activation.
`theme.bundle.mobile_menu_defaults`	JSON	Mobile menu configuration loaded on activation.
`theme.bundle.styles_defaults`	JSON	Typography, color, spacing, breakpoint tokens.
`theme.bundle.widget_set`	array	Theme-specific widgets exposed in the registry.
`site.active_theme_slug`	string	Foreign key to the active theme. One per site.
`site.header_config`	JSON	Current header — initialized from theme defaults, edited in place.
`site.footer_config`	JSON	Current footer.
`site.mobile_menu_config`	JSON	Current mobile menu.
`site.styles_config`	JSON	Current global styles.
`site.menus[]`	array	Operator-built navigation trees. Survives theme activation.
`activated_at`	timestamp	Stamped on every theme switch.
`updated_at`	timestamp	Touched on any chrome edit.

Persistence semantics. Theme records themselves are read-only from the operator's view — they are vendor assets. The site-side configuration (header, footer, mobile menu, styles) is initialized from the theme's bundled defaults and then edited in place. Menus, widgets-in-areas, and custom CSS survive theme activation; the four chrome configurations above are replaced.

No soft delete. Theme records cannot be deleted by the operator. To stop offering a theme, the platform vendor unpublishes it; existing sites already running it continue to render.

THEME RECORD SITE CONFIGURATION(vendor-shipped) (editable in place)┌──────────────────────┐ ┌────────────────────────────┐│ slug, name, version │ │ active_theme_slug ││ thumbnail │ ├────────────────────────────┤│ bundle.header │ ───► │ header_config │ replaced│ bundle.footer │ ───► │ footer_config │ replaced│ bundle.mobile_menu │ ───► │ mobile_menu_config │ replaced│ bundle.styles │ ───► │ styles_config │ replaced│ bundle.widget_set │ │ │└──────────────────────┘ │ menus[] │ preserved│ widgets-in-areas │ preservedon Activate: │ custom_css (separate svc) │ preserved│ pages, posts, media │ untouched└────────────────────────────┘↓ flush cachefront-end renders new chrome

Permissions

Access to the Themes surface is gated at two layers.

Layer 1 — admin gate. Every action under SG-Admin passes through the standard admin access check at request entry. Unauthenticated requests never reach this surface.

Layer 2 — per-action capability. Within the Appearance module, each operation checks a capability on the calling operator's role. The default capability map ships as:

Capability	Administrator	Editor	Designer	Viewer
List themes	✔	✔	✔	✔
Activate theme	✔	—	—	—
Edit header / footer / mobile menu	✔	✔	✔	—
Edit styles and layouts	✔	✔	✔	—
Edit menus	✔	✔	✔	—
List widgets / fonts / icons	✔	✔	✔	✔

The Designer role is a common custom role on sites that want creative ownership separated from billing and user management. The default ships with Administrator / Editor / Viewer; Designer is added via Settings → Roles.

Self-protection. Theme activation cannot complete if the site is in a publish lock (an in-progress migration or restore). The surface returns a structured rejection in that case.

Audit. Every theme activation, header edit, footer edit, mobile menu edit, styles edit, and menu edit emits an Activity Log entry. The log records the acting operator, the surface that changed, and a field-level diff where applicable.

REQUEST → /sg-admin/appearance/...│▼┌────────────────────────┐│ Admin gate │ unauth → reject└──────────┬─────────────┘│ authed▼┌────────────────────────┐│ Capability check │ role lacks cap → reject│ (per surface) │└──────────┬─────────────┘│ allowed▼┌────────────────────────┐│ Publish-lock check │ migration/restore in flight → reject│ (Activate only) │└──────────┬─────────────┘│ passes▼write executes│▼Activity Log entry

Related references

Custom CSS — Reference. Theme styles establish the baseline tokens; Custom CSS layers on top per page or site-wide.
Custom Codes — Reference. Site-wide HTML / JS injection that survives theme activation.
Custom Fonts — Reference. Self-hosted typeface uploads. Surfaced into the styles-and-layouts font pickers.
Pages — Reference. Pages render inside the active theme's header and footer. The chrome is theme-side; the page body is page-side.
Posts — Reference. Same — the blog archive and post detail templates inherit from the active theme.
Settings — Reference. Roles, publish locks, fallback configurations.
SG-Builder — Reference. Builder pages compose against the active theme's styles tokens.

For the corresponding customer-facing walkthrough — picking a theme, customizing the header and footer, building menus — see the Appearance section of the customer docs at /docs/appearance.

On this page

Guides

Reference

Changelog

Roadmap