Building sites
Theme
The theme is one token document for the whole site: colours, fonts, buttons, layout, header and footer, plus a site-wide stylesheet. Tokens become CSS custom properties on :root, and the base styles and every widget read those properties rather than fixed values, so publishing a new primary colour recolours every page at once. Edit it under Theme → Tokens, or one part of the site at a time under Theme → Site parts → Styles.
The Tokens screen
The tabs are Kits, Colours, Typography, Buttons (with the robot check's colours), Layout, Header & footer, Modules (only when a module adds styles of its own, such as the forms module's Forms) and Custom CSS. Beside them is a live preview the core renders with your unsaved tokens inside the published header and footer, at Desktop, Tablet or Mobile width: a sample page, or on the Modules tab the sample of the style being edited. Kits offers complete starting points; pick one and change anything in the other tabs. The address keeps the tab (/admin/theme/tokens/modules).
Tokens and custom properties
| Token | Custom property |
|---|---|
colors.primary, secondary, accent, background, surface, text, muted | --gsy-color-primary and so on |
fonts.heading_family, fonts.body_family | --gsy-font-heading, --gsy-font-body |
fonts.base_size, line_height, scale | --gsy-font-base-size, --gsy-line-height, --gsy-font-scale |
fonts.heading_weight, heading_tracking, heading_line_height, heading_transform | --gsy-heading-weight, --gsy-heading-tracking, --gsy-heading-line-height, --gsy-heading-transform (none, capitalize, uppercase, lowercase) |
buttons.background, text, radius, padding_y, padding_x, font_weight, font_size | --gsy-button-background, --gsy-button-text, --gsy-button-radius, --gsy-button-padding-y, --gsy-button-padding-x, --gsy-button-font-weight, --gsy-button-font-size |
layout.content_width, gutter | --gsy-content-width, --gsy-gutter |
layout.section_padding_small, _medium, _large | --gsy-section-padding-small, -medium, -large |
header.background, header.height | --gsy-header-background, --gsy-header-height (only when set) |
footer.background, footer.text | --gsy-footer-background, --gsy-footer-text (only when set) |
custom | --gsy-<key> for each entry |
Wherever a token takes a colour (button background, header and footer), a colour name such as primary refers to the colour token and anything else is used as a CSS colour. header.position is static, sticky or hidden; it applies to the built-in header and to header parts alike.
The section padding presets are the sizes behind every section's small, medium and large padding, and the content width and gutter are what a contained section and its columns use.
The custom map carries extra properties, such as { "hero-height": "80vh" } for --gsy-hero-height. The style sections write to it (core's captcha-* keys, and each module's <module id>-* keys; see Styles), and kits may carry any key. In names, anything other than letters, digits, - and _ becomes -; in values, { and } are dropped.
Fonts
Fonts are self-hosted. Under Typography → Font files, add a .woff2 (best), .woff, .ttf or .otf file from the media library, give it a family name, a weight (a single weight such as 400, or a range such as 100 900 for a variable font) and a style (Upright or Italic). Each becomes an @font-face rule, and the heading and body font pickers then offer the family first, followed by system fallbacks. A face whose file is not on the site's own domain is never emitted, so a theme cannot load fonts from anywhere else. A font file in use cannot be deleted from the library.
Custom CSS
Custom CSS is a site-wide stylesheet added after the core styles on every page. Classes you give sections, columns and widgets under Code can be styled here, and so can the renderer's own classes: gsy-section, gsy-col, gsy-widget-<kind>, gsy-heading, gsy-button and the rest. Use the custom properties rather than repeating values:
.gsy-section.band { background: var(--gsy-color-surface); }
.gsy-widget-quote { max-width: 40rem; margin-inline: auto; }Saving and publishing
Save draft stores the tokens as a new theme revision without changing the site. Publish stores them and makes them live; every page uses them on its next request. Revert puts the published tokens back in the editor. Revisions are append-only, like page revisions. Editing needs the edit theme permission, publishing the publish theme permission.