Reference → Branding — Reference

Branding — Reference

The Branding surface is the visual-identity plane for an SGEN site. It owns the logos that render in the chrome, the favicon that loads in the browser tab, the social-share default image that appears when a page is linked into chat or social, the color palette that drives buttons and accents, and the theme-level accents that flow through email templates and PDF receipts.

This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a brand-asset model. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.

Overview

Branding lives under the Appearance module in SG-Admin. The module renders three primary views — the brand asset manager (logos, favicon, social-share image), the color palette editor, and the theme-accent editor that maps palette slots into chrome / email / PDF surfaces — and exposes a small set of write operations for upload asset, replace asset, remove asset, set palette slot, set theme accent, and reset to defaults.

The module is paired by convention: one half renders the views and prepares the asset and palette data, the other half handles writes and returns AJAX responses. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.

Branding is distinct from Themes. A theme is the full layout-and-typography package the storefront renders against; branding is the small set of identity assets that the theme consumes. Both surfaces participate in the storefront-rendering pipeline, but the entry points and the lifecycle differ. Theme records live under the adjacent Themes surface; this page covers identity assets and palette wiring only.

Where it lives in SG-Admin:

Sidebar: SG-Admin → Appearance → Branding
URL prefix: /sg-admin/branding/
View templates: application/views/Admin/Appearance/Branding/

The module surface is intentionally small. Layout templates, typography choices, page-level CSS, and full theme configuration live in adjacent surfaces — this page covers only the brand-asset slots, the color palette, the theme-accent map, and the social-share default image. Per-page header / footer designs sit under Pages.

┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Appearance → Branding │├──────────────────────────────────────────────────────────────────────┤│ Brand assets ││ ───────────────────────────────────────── ││ Logo (light) [logo-light.svg] uploaded 12d ago 1.4 KB ││ Logo (dark) [logo-dark.svg] uploaded 12d ago 1.5 KB ││ Favicon [favicon-32.png] uploaded 12d ago 312 B ││ Apple touch [apple-180.png] uploaded 12d ago 8.2 KB ││ OG default [og-default.png] uploaded 4d ago 84.0 KB ││ ││ Color palette ││ ───────────────────────────────────────── ││ primary ● #c2410c ││ primary-fg ● #ffffff ││ accent ● #1a1a1f ││ surface ● #f5f5f7 ││ border ● #e5e7eb ││ text ● #111111 ││ ││ Theme accents (where the palette is applied) ││ ───────────────────────────────────────── ││ Site chrome primary + surface ││ Emails primary + surface + border ││ PDF receipts primary + text │└──────────────────────────────────────────────────────────────────────┘

Actions

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

View brand assets

Returns the current asset set — logo (light and dark variants), favicon and Apple touch icon, social-share default image — with each asset's storage reference, dimensions, file size, and last-updated timestamp. Empty slots are returned as nulls so the caller can render an upload prompt; default assets supplied by the active theme are returned with a from_theme: true flag.

Upload or replace asset

Accepts a binary upload against a named slot. The slot must be one of the recognized identity slots — logo light, logo dark, favicon, apple-touch, OG default — and the file must satisfy the slot's accepted format and aspect-ratio rules. On success, the prior asset is moved into the Media library's branding-history folder for rollback, and the new asset becomes active immediately.

Engineering note. Asset replacement does not invalidate the page-level cache. Cache invalidation runs on a separate, debounced job so multiple uploads in quick succession only invalidate once. The debounce window is read from Settings.

Remove asset

Detaches an asset from its slot. Removing falls the slot back to either the active theme's default (if any) or to null. The removed file is not deleted from the Media library; it remains queryable for restore.

View color palette

Returns the current palette as an ordered set of named color slots — primary, primary-foreground, accent, surface, border, text, plus any role-named slots declared by the active theme. Each slot carries a stored value and the slot's role (foreground / background / border / accent).

Set palette slot

Rewrites a single palette slot to a new color value. The surface accepts hex, rgb, hsl, and named-color formats; values are normalized to hex on persist. Contrast against paired slots is checked at write time and a structured warning is returned when the pair fails the configured contrast threshold (typically WCAG AA). The write succeeds with the warning attached; the operator chooses whether to act on it.

View theme accents

Returns the mapping of palette slots to specific surfaces — the site chrome (header / footer / buttons), the email template family, the PDF receipt template, and any module-registered surfaces. Each row carries the surface identifier and the palette-slot reference it consumes.

Set theme accent

Rewrites a single accent row to consume a different palette slot, or to lock the surface to a specific color value that ignores the palette. Useful when the email surface needs a fixed brand color that does not follow palette edits.

Reset to defaults

Replaces the calling site's brand assets and palette with the active theme's shipped defaults. Reset is per-section — assets only, palette only, accents only, or all three — and reset writes a single Activity Log entry per section. The prior state is recoverable from the branding-history folder until the configured retention window expires.

Engineering note. The OG default image is read by the social-share preview generator at request time, not embedded at page render. Replacing the OG default surfaces on social platforms only after their cache expires; the platform-side cache TTL is outside SGEN's control.

Data model

A brand-asset slot carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.

Field	Type	Notes
`slot`	enum	`logo_light`, `logo_dark`, `favicon`, `apple_touch`, `og_default`.
`media_id`	integer	Reference into the Media library. Null when the slot is empty.
`from_theme`	boolean	True when the slot is falling back to the active theme default.
`width`	integer	Pixel width, populated on upload.
`height`	integer	Pixel height, populated on upload.
`bytes`	integer	File size in bytes, populated on upload.
`mime`	string	MIME type, validated against the slot's accepted formats.
`updated_at`	timestamp	Touched on upload / replace / remove.

Palette slot: slot_name (primary, primary-foreground, accent, surface, border, text, plus theme-declared slots), value (normalized hex), role (foreground / background / border / accent), updated_at. Theme-declared slots have a from_theme: true flag analogous to the asset slot.

Theme-accent row: surface (site_chrome / email_template / pdf_receipt / module-registered slug), palette_slot (references a palette slot name) or locked_value (a fixed hex value), updated_at. Exactly one of palette_slot or locked_value is populated per row.

Asset semantics: assets are stored once in the Media library and referenced by media_id from the slot record. Replacing a slot rewrites the reference; the prior media record remains in the branding-history folder for the configured retention window. Removing a slot nulls the reference but leaves the prior media record in place.

Palette semantics: palette slots have stable role-based names so themes can reference them. The contrast check on set palette slot is advisory — the value is written even when contrast is below threshold, and a warning is returned. Sites that require hard contrast enforcement can enable the strict palette mode under Settings.

SITE /sg-admin│▼BRAND ASSETS (slot map)├── logo_light → media #482 1.4 KB SVG├── logo_dark → media #483 1.5 KB SVG├── favicon → media #484 312 B PNG 32×32├── apple_touch → media #485 8.2 KB PNG 180×180└── og_default → media #514 84.0 KB PNG 1200×630PALETTE├── primary #c2410c role:accent├── primary-fg #ffffff role:foreground├── accent #1a1a1f role:accent├── surface #f5f5f7 role:background├── border #e5e7eb role:border└── text #111111 role:foregroundTHEME ACCENTS (where the palette is consumed)├── site_chrome palette: primary, surface├── email_template palette: primary, surface, border└── pdf_receipt palette: primary, textRENDER├── storefront uses logo_light / favicon / palette via theme css├── email send uses logo_light / palette via email-template tokens├── PDF generation uses logo_dark / palette via receipt-template tokens└── social share uses og_default at preview-fetch time

Permissions

Access to the Branding 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 Branding surface.

Layer 2 — per-action capability. Within SG-Admin, each Branding 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 brand assets	✔	✔	✔
View palette	✔	✔	✔
View theme accents	✔	✔	✔
Upload / replace asset	✔	✔	—
Remove asset	✔	✔	—
Set palette slot	✔	✔	—
Set theme accent	✔	—	—
Lock theme accent to fixed value	✔	—	—
Reset assets to theme default	✔	—	—
Reset palette to theme default	✔	—	—
Reset accents to theme default	✔	—	—
Configure strict palette mode	✔	—	—

Custom roles defined under Settings → Roles override the default map. The capability slugs are stable; the role slugs are configurable.

Self-protection rules. A favicon upload that fails the slot's format-and-aspect check returns a structured rejection naming the failing rule — file size, aspect ratio, color depth, or transparency support. A palette write that drops a slot's contrast below the configured threshold returns the warning alongside the success, never a rejection, so the operator retains the choice. A theme switch that would invalidate locked accent values returns a structured warning listing the affected accents; the operator must confirm before the theme swap commits.

Audit. Every write — asset upload, replace, remove; palette change; accent change; lock or unlock; reset — emits an Activity Log entry. The log records the acting operator, the affected slot or row, and the change shape (field-level diff). Asset history persists in the branding-history Media folder for the configured retention window; the Activity Log persists per the site's general retention setting.

REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject│ (every /sg-admin/* call) │└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action) │ (custom roles override defaults)└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Self-protection rules │ format / aspect / contrast warn│ │ theme-swap-with-locked-accents│ │ → warn or reject└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log + branding-history retention

Related references

Themes — Reference. Owns the layout, typography, and component library that consumes branding assets and palette slots. Swapping the active theme keeps the operator's brand-asset uploads but may invalidate theme-declared palette slots; warnings are surfaced at the swap step.
Media — Reference. Owns the underlying media storage. Every brand-asset slot references a media record. Branding-history retention sits inside the Media library with its own retention setting.
Settings — Reference. Owns the contrast-threshold default, the strict-palette-mode toggle, the asset-format whitelist per slot, and the branding-history retention window. Changes there reshape the Branding evaluation behavior.
Pages — Reference. Owns per-page overrides for header / footer / logo. A page-level override consumes the Branding palette and assets unless explicitly locked.
Email — Reference. Email templates consume the Branding palette via the email-template-token contract. Locked accent values bypass palette edits on the email surface.
PDF Receipts — Reference. Receipt templates consume the Branding palette and the dark-logo variant. Logo selection is determined by the receipt template, not by per-receipt configuration.
Activity Log — Reference. Captures every branding write. Retention is governed by the site's general settings.

For the corresponding customer-facing walkthrough — uploading a logo, setting the favicon, choosing brand colors, configuring social-share defaults — see the Branding section of the customer docs at /docs/branding.

On this page

Guides

Reference

Changelog

Roadmap