Appearance — Reference
The Appearance surface is the visual configuration plane for an SGEN site. It owns the theme-level color tokens, typography selections, header and footer template assignments, and the pointer to the Custom CSS surface that complements it. Anything that controls how the public site looks — short of in-page edits made inside SG-Builder — traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or porting a theme configuration across sites. Customer-facing walkthroughs for picking colors and choosing fonts live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Appearance lives under the Appearance module in SG-Admin. The module renders four primary views — the color tokens panel, the typography panel, the header / footer assignment panel, and the global Custom CSS pointer — and exposes a small set of write operations for token updates, font additions, template swaps, and reset-to-defaults.
The module is paired by convention with the Theme Editor surface, which owns per-template structure and component composition. Appearance configures the global tokens and the visual fragments (header / footer) that the templates consume; the Theme Editor decides how those tokens render inside a given page layout.
A second surface — per-page overrides — lives inside SG-Builder. Individual pages can override the global tokens for a section or component. Per-page overrides do not write back to the global Appearance record; they live on the page record itself. This page covers the global surface only.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Appearance
- URL prefix:
/sg-admin/appearance/ - View templates:
application/views/Admin/Appearance/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Appearance [Save] [Reset]│├──────────────────────────────────────────────────────────────────────┤│ Color tokens ││ ───────────── ││ primary ▓▓▓▓ #c2410c ││ secondary ▓▓▓▓ #1a1a1f ││ accent ▓▓▓▓ #15803d ││ background ░░░░ #ffffff ││ surface ░░░░ #f5f5f7 ││ text ▓▓▓▓ #1a1a1f ││ muted ▒▒▒▒ #6b7280 ││ ││ Typography ││ ────────── ││ Display font Inter Tight [Change] ││ Body font Inter [Change] ││ Mono font JetBrains Mono [Change] ││ ││ Header / Footer ││ ─────────────── ││ Header template header-primary.html [Swap] ││ Footer template footer-full.html [Swap] ││ ││ Custom CSS ││ ────────── ││ → Edit global Custom CSS in /sg-admin/custom_css │└──────────────────────────────────────────────────────────────────────┘Actions
The Appearance surface exposes the following operations. Each is described by what it does to the site state, not by its internal method name.
View appearance
Returns the current global appearance record — every color token, every font selection, every header / footer assignment. Used by SG-Admin to render the panel and by SG-Builder to resolve token references at edit time.
Update color tokens
Writes one or more color values into the global token map. Accepts either a single-token update or a batch update of the full map. Values accept hex, rgb, rgba, hsl, and linear-gradient strings — gradient values are supported on every token slot natively, with the caveat that a gradient on text requires a background-clip: text rendering path on the consuming template.
Update typography
Writes the display, body, and mono font selections. Each selection carries a source flag — Google Fonts, the platform's basic URL list, or a Custom Fonts entry. Custom Fonts entries must exist in the Custom Fonts surface before they can be referenced here; the update rejects an unresolvable reference.
Add Google font
A standalone shortcut that opens the Google Fonts picker scoped to the platform's basic list. On selection, the font is registered for the site and becomes available in the typography picker.
Add custom font
A pointer to the Custom Fonts surface. Self-hosted fonts and variable-axis fonts must be uploaded there first; the typography picker reads from the resulting registry.
Swap header template
Reassigns the global header to a different template file. The list is drawn from the templates registered under the Theme Editor. The swap takes effect on the next page render — no cache flush required.
Swap footer template
Reassigns the global footer. Same shape as the header swap.
Reset to defaults
Restores the appearance record to the theme's shipped defaults. Tokens, typography selections, and header / footer assignments all revert. The reset is reversible inside a 30-minute window — the prior state is held in a buffer; after 30 minutes the buffer drops.
Reset-to-defaults does not touch Custom CSS or the Custom Fonts library. Those surfaces are separate and retain their state.
Preview appearance
Renders a preview page using the unsaved token + typography state. Used by operators to evaluate a change before committing. The preview lives at a session-scoped URL; it is not publicly reachable.
Export appearance
Produces a JSON snapshot of the appearance record. Used for porting a configuration into a new site or for storing a known-good baseline. The snapshot includes color tokens, typography selections (with source references), header / footer assignments, and a pointer to (but not the contents of) the global Custom CSS surface.
Import appearance
Reads a JSON snapshot and applies it. Custom font references are resolved by name; missing fonts fall back to the platform default and surface a warning. Header / footer template references resolve by template slug; missing templates fall back to the shipped default and surface a warning.
Data model
The appearance record is a singleton per site. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. One row per site. |
site_id | integer | Foreign key. Unique. |
colors | JSON | Token map. Keys: primary, secondary, accent, background, surface, text, muted. Each carries a default value and optional state values (hover, active, disabled). Gradient strings accepted on every token. |
typography | JSON | display, body, mono. Each carries a font reference and source flag. |
header_template_slug | string | Foreign key by slug to the templates registry. |
footer_template_slug | string | Foreign key by slug to the templates registry. |
custom_css_pointer | string | Static path to /sg-admin/custom_css. Not editable here. |
reset_buffer | JSON | Optional. Holds the prior state for the 30-minute reset-undo window. |
last_reset_at | timestamp | Optional. When the reset buffer was last populated. |
created_at | timestamp | Immutable. |
updated_at | timestamp | Touched on any edit. |
default and optional hover, active, disabled states. The consuming template decides which states apply to which surfaces; the token slot is a named bucket of color values.Gradient support: color slots accept full CSS gradient strings as native values. The platform does not decompose gradients into stop arrays. A gradient on the text token requires the consuming template to set background-clip: text and -webkit-background-clip: text; without that, the gradient renders as a solid color (the first stop).
Font source flags: google (platform's basic Google Fonts list), custom (registered under Custom Fonts), system (system font stack). A custom reference points at a Custom Fonts entry by unique name; the entry holds the file location, weight axis, and unicode-range data.
Custom CSS surface: the appearance record does not store custom CSS. It carries a pointer to the global Custom CSS surface, which is a separate endpoint (/sg-admin/custom_css). The two surfaces are deliberately split — design-system tier (Appearance + Custom CSS) versus absolute-last-resort tier (Custom Codes under /sg-admin/custom_codes).
APPEARANCE RECORD (singleton per site)┌─────────────────────────────────────────┐│ id, site_id ││ ││ colors (JSON) ││ primary { default, hover, active } ││ secondary { default } ││ accent { default, hover } ││ background { default } ││ surface { default } ││ text { default, muted } ││ muted { default } ││ ││ typography (JSON) ││ display { font, source } ││ body { font, source } ││ mono { font, source } ││ ││ header_template_slug ──► TEMPLATES ││ footer_template_slug ──► TEMPLATES ││ ││ custom_css_pointer ──► /sg-admin/... ││ ││ reset_buffer (30-min undo) ││ timestamps │└─────────────────────────────────────────┘↓ resetSHIPPED DEFAULT BASELINE(theme-supplied; non-destructible)Permissions
Access to the Appearance surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Appearance surface.
Layer 2 — per-action capability. Within SG-Admin, each Appearance action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| View appearance | ✔ | ✔ | ✔ |
| Update color tokens | ✔ | ✔ | — |
| Update typography | ✔ | ✔ | — |
| Add Google font | ✔ | ✔ | — |
| Add custom font (pointer) | ✔ | — | — |
| Swap header template | ✔ | ✔ | — |
| Swap footer template | ✔ | ✔ | — |
| Reset to defaults | ✔ | — | — |
| Undo reset (within 30 min) | ✔ | — | — |
| Preview appearance | ✔ | ✔ | ✔ |
| Export appearance | ✔ | ✔ | — |
| Import appearance | ✔ | — | — |
Self-protection rules. Reset-to-defaults emits a confirmation prompt before write. Import-appearance rejects a snapshot whose schema version exceeds the running platform version; downgrade imports are accepted but surface a compatibility warning.
Audit. Every write — token update, typography update, template swap, reset, import — emits an Activity Log entry. The log records the acting operator, the prior value (full snapshot for resets and imports, field-level diff for tokens and typography), and the new value. Activity Log retention follows the site's general settings.
REQUEST → /sg-admin/appearance/...│▼┌────────────────────────┐│ Admin gate │ unauth → reject└──────────┬─────────────┘│ authed▼┌────────────────────────┐│ Role capability check │ role lacks cap → reject└──────────┬─────────────┘│ allowed▼┌────────────────────────┐│ Schema-version check │ import: incoming schema > running → reject│ (import only) │└──────────┬─────────────┘│ passes▼┌────────────────────────┐│ Reset confirmation │ reset path only — confirm or abort└──────────┬─────────────┘│ confirmed▼write executes│▼Activity Log entry(field-level diff or snapshot)Related references
- Custom CSS — Reference. The design-system tier for site-wide CSS overrides. Appearance carries a static pointer to this surface; the two work as a pair.
- Custom Codes — Reference. The absolute-last-resort tier for arbitrary code injection. Distinct endpoint from Custom CSS — different surfaces, different gates.
- Custom Fonts — Reference. Owns self-hosted font uploads and variable-axis registrations. Typography picker reads from this registry.
- Theme Editor — Reference. Owns per-template structure. Appearance configures global tokens; the Theme Editor decides how templates consume them.
- SG-Builder — Reference. Per-page overrides live inside SG-Builder. Overrides do not write back to the global Appearance record.
- Settings — Reference. Activity Log retention and role definitions live in Settings; they decide what the audit log keeps and who can write here.
- Backups — Reference. A
.sgenbackup captures the appearance record alongside the site content. Restore overwrites the appearance record from the snapshot.
/docs/appearance.