Guide
Admin panels' look (admin_theme)
The admin panels — comments, newsletter, shop, accounts, the admin home — ship
with a neutral look. admin_theme: in .ssg.yaml gives them the site's name,
logo, colours and fonts. It takes effect through the core worker, which
serves the result; without core it does nothing. The keys are checked at
build time, and the colours are adjusted until every pair the panels use keeps
its WCAG 2.2 contrast.
The keys
| Key | Default | Notes |
|---|---|---|
admin_theme |
empty | The site's look for the admin panels, served by the core worker. Absent: the panels look as shipped |
admin_theme.name |
empty | Plain text, at most 80 characters, shown in the shared navigation instead of "Site admin" |
admin_theme.logo |
empty | A .svg, .png or .webp file on the site's own host (/img/logo.svg); shown through <img> only, with the name as its alternative text |
admin_theme.logo_dark |
empty | The same for dark backgrounds; the navigation bar (dark in both schemes) shows it when set |
admin_theme.main |
empty | The brand's main colour, #rgb or #rrggbb: the navigation bar, primary buttons, the current menu item, the first chart series |
admin_theme.accent |
empty | The accent: links, the focus ring, the current-page marker in the bar, the second chart series. Either colour alone derives the other |
admin_theme.font |
empty | Font-family list for headings (Georgia, serif) |
admin_theme.font_body |
empty | Font-family list for everything else |
admin_theme.font_files |
empty | @font-face files: family, src (a .woff2, .woff, .ttf or .otf on this host), optional weight (400, 400 700, bold) and style (normal, italic, oblique); at most 8 |
admin_theme.tokens |
empty | Advanced: light: / dark: maps overriding single derived tokens (primary, on-primary, primary-soft, on-primary-soft, link, focus, c1–c5, nav-bg, on-nav, nav-muted, nav-hover, nav-control, nav-current) |
check_admin_theme |
warn |
off, warn or strict: a logo or font file missing from the output, an override that breaks a contrast pair, admin_theme without a core worker |
1admin_theme:
2 name: "Anna's Kitchen"
3 logo: /img/logo.svg
4 logo_dark: /img/logo-light-text.svg
5 main: "#1b3a4b"
6 accent: "#e07a5f"
7 font: "Georgia, serif"
8 font_body: '"Brand Sans", system-ui'
9 font_files:
10 - family: "Brand Sans"
11 src: /fonts/brand-sans.woff2
12 weight: "400 700"
13 tokens:
14 dark:
15 focus: "#ffcc80"
What is derived
Four things to set, the rest is computed. From main and accent the build
derives every colour token the panels use for the light and the dark scheme,
so that text keeps 4.5:1 on its background (links in the accent colour
included, on the page, on cards and on inset areas) and the focus ring, chart marks
and the bar's edges 3:1 (WCAG 2.2), the focus ring stays apart from the
primary colour and every two chart series stay apart. A brand colour that can
serve its role is used exactly; one that cannot keeps its hue and moves to the
nearest lightness that works, and the core worker's Appearance view
(/core/#appearance) says where and why. Neutral backgrounds and text and the
state colours (error, warning, success, info) are never themed — red always
means an error. The result is written as /core/theme.css (over the empty file
the core template ships) and as the module registry's theme
(WORKER-MODULES); panels pick it
up by loading /core/theme.css after their own tokens. Pages visitors see
(subscription confirmations, unsubscribing) are never themed.
What stops the build
Every value is checked at build time, and one that cannot be used stops the
build with the file and the key, whatever check_admin_theme says: a colour
that is not opaque hex (an alpha channel is refused — a translucent colour has
no contrast ratio of its own); a logo or font path that is not a file on this
host (no scheme, host, //, .., backslash, query, fragment or space — the
panels' content security policy allows images and fonts from their own host
only, and stays that way); a font list outside the grammar (family names,
quoted or not, and generic families, separated by commas — nothing that could
end a CSS declaration); a name with control characters or longer than 80
characters; an unknown token or scheme under tokens. The guidelines — how to
choose the two colours, what is derived, what cannot be set and why — are in
the core worker's README.
Without a core worker admin_theme has no effect (a finding); a site
without admin_theme builds byte for byte as before.