# Brand & theme

Set the website's identity, colors, fonts, and logo, with clear limits on what these controls change.

GroCMS 0.1.0 · Website design · Administrators and designers · Reviewed 15 September 2026

## What belongs in the brand resource

Brand & theme controls your public website's name, tagline, logo, colors, fonts, site icon and default social image. Its saved working draft is separate from the published identity visitors see. The GroCMS administration and sign-in screens use the product's official identity independently; changing your website's brand does not rename articles or restyle the administration workspace.

New starter drafts use the official GroCMS Concept 05 identity: the supplied wordmark, white and navy surfaces, blue actions and locally hosted Inter. Existing customer sites retain their saved choices. You can keep this starting point, replace its colors and fonts, use a custom logo or display the site name as text. The official logo is an image asset, not a typed heading with a decorative mark.

Administrators and designers can manage brand resources. The Editor role manages editorial content rather than this design configuration. Edit the site's existing brand record. Only one brand can be published at a time: attempting to publish another brand produces a conflict. There is no active-brand switch that makes a newly created draft replace the existing published identity.

Sources: Brand foundations form (repository: `apps/cms/src/components/admin/brand-fields.tsx`); Official GroCMS brand defaults (repository: `apps/cms/src/cms/brand/preset.ts`); Shared public brand resolver (repository: `apps/cms/src/cms/brand/theme.ts`); Public website frame and theme application (repository: `apps/cms/src/app/site-view.tsx`); Public page selection and resource resolution (repository: `apps/cms/src/cms/services/public.ts`); Role and resource permissions (repository: `apps/cms/src/cms/policy/index.ts`); Revision and publication service (repository: `apps/cms/src/cms/services/content.ts`).

## Change the identity and colors

1. Open Brand & theme and select the existing record. Its main Title is the administrative label; the Name field under Brand foundations supplies the public brand name.
2. Set Name and Tagline. Name supplies the text-only identity and custom-logo description. A tagline remains separate copy; it is not added inside the official logo.
3. Choose Brand defaults. GroCMS official fills missing settings while keeping saved overrides. To deliberately replace current colors and built-in font choices, select Use GroCMS palette and fonts; this leaves your name, tagline, custom assets and logo display choice intact.
4. Set the color pickers or six-digit hex inputs as needed, for example #1857D9 for an accessible blue action. A saved custom font continues to override its built-in family.
5. Choose Logo display: Official GroCMS logo, Custom image or Site name as text. Choosing an image in Logo selects Custom image. You can return to Official GroCMS logo without deleting the retained custom asset.
6. Optionally choose Site icon and Default social image. Use a square icon and a landscape social image. Save, inspect Preview and representative pages, then publish the brand.

Site navigation, the default footer and the Site logo layout component share this identity. A custom footer containing its own Rich text is ordinary content: replace a typed identity with Site logo when you want it to follow the brand. The component offers light/dark background variants and three sizes. Custom images keep their original design; the component does not redraw them for another background.

The published icon and default social image feed website metadata. An entry's featured image takes precedence over the site's default social image. Official defaults are supplied when appropriate; selecting a draft image alone does not make it public. Publish the brand to expose its selected media. Browser and social-network caches may take time to refresh after a publication.

Sources: Brand foundations form (repository: `apps/cms/src/components/admin/brand-fields.tsx`); Official GroCMS brand defaults (repository: `apps/cms/src/cms/brand/preset.ts`); Shared public brand resolver (repository: `apps/cms/src/cms/brand/theme.ts`); Site icon and social image selection (repository: `apps/cms/src/cms/brand/metadata.ts`); Public website frame and theme application (repository: `apps/cms/src/app/site-view.tsx`); Configured website components (repository: `apps/cms/src/cms/components/config.tsx`); Content and composition validation (repository: `apps/cms/src/cms/validation.ts`).

## Understand the shared colors

| Control | Current public effect |
| --- | --- |
| Accent | The shared action color used by primary public buttons and related controls; the official starting value is #1857D9. |
| Background | Sets the site's base paper color and places using the paper/background variables. |
| Text | Sets the base inherited text color where a component does not declare its own color. |
| Surface, Muted text and Border | Control secondary panels, quieter text and separating lines wherever components use the shared website theme. |
| Dark surface and Action hover | Control dark section surfaces and the action color shown when a visitor points at a primary button. |
| Section tone | Paper, Soft and Dark select coordinated surfaces from the shared public theme. Inspect text and logo contrast in each tone you use. |

The public shell and visual-editor canvas resolve the same saved theme settings. The supplied GroCMS logo keeps its official artwork colors; a photo, custom logo or authored illustration is not recolored by these controls. There is no arbitrary CSS box or unlimited per-block palette. Hero's Asterisk option remains an optional illustration, separate from the product identity.

Review contrast after changing colors, especially white button text on the Accent color. The form validates color syntax, not every possible contrast pairing. Check the actual public layout rather than assuming a valid hex code guarantees readable text.

Sources: Official GroCMS brand defaults (repository: `apps/cms/src/cms/brand/preset.ts`); Shared public brand resolver (repository: `apps/cms/src/cms/brand/theme.ts`); Public website frame and theme application (repository: `apps/cms/src/app/site-view.tsx`); Website component styles (repository: `apps/cms/src/app/globals.css`); Configured website components (repository: `apps/cms/src/cms/components/config.tsx`).

## Choose built-in or uploaded fonts

Heading font and Body font offer Inter — GroCMS official, Editorial serif, Modern sans serif and Monospace. Inter is supplied locally with the product, so using it does not contact a font service. Existing serif, sans and monospace choices retain their Georgia/Times, Arial/Helvetica and Courier New fallback stacks. These settings apply where components use the shared heading and body fonts.

1. To use a custom font, upload a WOFF2 file through Media library with an administrator or designer account.
2. Return to the brand and use Choose custom heading font or Choose custom body font. Search and select the uploaded font asset.
3. Publish the brand after saving. A selected custom font takes precedence over the corresponding built-in family, which remains a fallback.
4. Remove the custom-font selection to return to the selected built-in family.

The implementation declares one uploaded face for each heading/body role. There are no controls for variable-font axes or separate uploaded files for every weight and italic style. Font loading uses the browser's normal fallback-and-swap behavior. A file with the wrong media type is rejected as a brand font.

Sources: Brand foundations form (repository: `apps/cms/src/components/admin/brand-fields.tsx`); Shared public brand resolver (repository: `apps/cms/src/cms/brand/theme.ts`); Official GroCMS brand defaults (repository: `apps/cms/src/cms/brand/preset.ts`); Public website frame and theme application (repository: `apps/cms/src/app/site-view.tsx`); Website component styles (repository: `apps/cms/src/app/globals.css`); Media validation and immutable versions (repository: `apps/cms/src/cms/services/media.ts`); Revision and publication service (repository: `apps/cms/src/cms/services/content.ts`).

## Import or export brand tokens

Expand Import or export brand tokens. Export tokens downloads brand-tokens.json containing the current draft's supported brand fields. Import tokens reads a GroCMS brand export and applies its values to this draft; it does not publish immediately. The importer accepts the gcms-brand format, version 1, and files up to the current 64 KB limit.

Version-one exports support the current preset, logo mode, shared colors, built-in fonts and selected logo/font/icon/social-image identifiers. Older version-one GroCMS exports remain supported. The downloadable design-pack brand-tokens.json uses a different design-document structure: it is not a CMS token export and cannot be imported here directly.

A token file transfers settings, not image or font bytes. Referenced assets must already exist in the destination library and be accessible. Unsupported keys, invalid colors or unsupported fonts are rejected. Review the imported fields, wait for saving, then preview and publish through the normal workflow.

Sources: Brand foundations form (repository: `apps/cms/src/components/admin/brand-fields.tsx`); Shared public brand resolver (repository: `apps/cms/src/cms/brand/theme.ts`); Revision and publication service (repository: `apps/cms/src/cms/services/content.ts`); Editor browser verification (repository: `apps/cms/tests/editor-browser.ts`).

## If the change does not appear

- Check that the brand was published, not only saved, and that you edited the existing selected brand resource.
- If a font stays unchanged, check for an overriding custom-font selection and confirm the selected asset is WOFF2.
- If replacing a media file created a new version, select that new asset in the brand. Existing references deliberately retain their old asset identifiers.
- If selecting GroCMS official leaves existing colors in place, those values are saved overrides. Use GroCMS palette and fonts to replace them deliberately, then review before publishing.
- If the logo seems unchanged, check Logo display. An explicit Official GroCMS logo choice takes precedence over a retained custom asset; selecting that asset again chooses Custom image.
- For an unwanted live change, restore an earlier brand revision as a working draft, inspect it, and publish the restored version.

Sources: Public page selection and resource resolution (repository: `apps/cms/src/cms/services/public.ts`); Public website frame and theme application (repository: `apps/cms/src/app/site-view.tsx`); Resource editor and design resource fields (repository: `apps/cms/src/components/admin/resource-editor.tsx`); Media validation and immutable versions (repository: `apps/cms/src/cms/services/media.ts`); Website component styles (repository: `apps/cms/src/app/globals.css`).

## References

- Brand foundations form — repository path: `apps/cms/src/components/admin/brand-fields.tsx`. Color and font controls, logo selection, and validated brand token import/export.

- Official GroCMS brand defaults — repository path: `apps/cms/src/cms/brand/preset.ts`. Approved Concept 05 assets, accessible action colors, official site defaults and product interface tokens.

- Shared public brand resolver — repository path: `apps/cms/src/cms/brand/theme.ts`. Saved overrides, legacy font choices, custom assets, logo display and supported version-one tokens.

- Site icon and social image selection — repository path: `apps/cms/src/cms/brand/metadata.ts`. Published custom icon and social-image selection, official fallbacks and preview metadata behavior.

- Public website frame and theme application — repository path: `apps/cms/src/app/site-view.tsx`. Header, footer, default layouts, archive listings, brand colors, and WOFF2 font application.

- Public page selection and resource resolution — repository path: `apps/cms/src/cms/services/public.ts`. Homepage and template precedence, published resource selection, connected collections, menus, and shared dependencies.

- Role and resource permissions — repository path: `apps/cms/src/cms/policy/index.ts`. Design resources belong to administrator and designer capabilities; content permissions differ.

- Configured website components — repository path: `apps/cms/src/cms/components/config.tsx`. The actual component labels, editable fields, slot definitions, and rendering behavior.

- Content and composition validation — repository path: `apps/cms/src/cms/validation.ts`. Layout size, nesting, supported components, safe links, menu limits, color validation, and resource references.

- Website component styles — repository path: `apps/cms/src/app/globals.css`. Responsive columns, typography, public theme variables, section tones and hero decoration.

- Media validation and immutable versions — repository path: `apps/cms/src/cms/services/media.ts`. Supported uploads, WOFF2 handling, access checks, and replacement versions.

- Revision and publication service — repository path: `apps/cms/src/cms/services/content.ts`. Immutable revisions, required published dependencies, cycle checks, preview selection, and publication actions.

- Editor browser verification — repository path: `apps/cms/tests/editor-browser.ts`. Save/reload evidence for canonical rich text, slots, copied layouts, brand tokens, menus, and remote selection.

- Resource editor and design resource fields — repository path: `apps/cms/src/components/admin/resource-editor.tsx`. Native controls, autosave, publication actions, permissions, template keys, homepage settings, and navigation link editing.

## Related guides

- [Media library](https://grocms.com/docs/media-library)

- [Navigation](https://grocms.com/docs/navigation)

- [Shared sections](https://grocms.com/docs/shared-sections)

- [Homepage](https://grocms.com/docs/homepage)

- [Visual editor](https://grocms.com/docs/visual-editor)

- [Settings](https://grocms.com/docs/settings)

- [Technology stack](https://grocms.com/docs/technology-stack)