Theme Authoring
A Trellis theme is a self-contained directory of HTML layouts, SASS stylesheets, and a YAML manifest. Themes are distributed via git and installed with the trellis CLI. Site builders configure them entirely through YAML – no forking required.
This guide covers creating, testing, and publishing a theme. It assumes you know
the template language (Getting Started,
Syntax Reference) and, in particular, template inheritance –
tl:extends and tl:define are the backbone of a
theme's layouts. For how the static site generator consumes a theme, see
trellis_site.
Author versus site builder
A theme has two audiences:
- You, the author, ship layouts, SASS, and a manifest that declares the params you support.
- Site builders install your theme and configure it through
theme_params:intrellis_site.yaml– they change colors, fonts, navigation, and layout without touching your source.
The standard-params contract (below) is what makes this work: because every theme supports the same 25 params, a site builder can switch themes and carry their customizations across.
Quick start
# Scaffold a new theme
trellis create --template theme my_theme
cd my_theme
# Edit the manifest, add layouts and SASS
# Preview with the bundled example site
cd example
trellis build
trellis serve
trellis create writes example/trellis_site.yaml with theme: my_theme and
links the theme root into the example as example/themes/my_theme (a relative
symlink to ../..), so trellis build in example/ compiles the theme's SASS
to css/main.css and renders the theme's own layouts. The example has no layouts
of its own, because site layouts shadow theme layouts. If the link cannot be
created (Windows without symlink rights), create prints the command to make it;
on Windows, from the theme root: mklink /J example\themes\my_theme .. Do not
run trellis theme add ../ from example/: the source contains the site, and
the command refuses it.
You now have a working theme skeleton. The rest of this guide explains each piece in depth.
Theme directory structure
my_theme/
theme.yaml # Manifest — name, version, params
layouts/
base.html # Root HTML shell (tl:define blocks)
home.html # Home page layout
_default/
single.html # Default single page/post layout
list.html # Default section listing layout
tags/ # Taxonomy-specific layouts (optional)
term.html
list.html
sass/
_variables.scss # Params as $trellis-* with !default; builds the dark palette
_skins/
_light.scss # Light palette map ($palette)
_dark.scss # Dark palette map ($palette)
_base.scss # Reset and typography
_layout.scss # Page structure and breakpoints
_components.scss # UI components
_footer.scss # Footer styles
_a11y.scss # Accessibility: skip-link, focus rings
_code.scss # Code block styles
main.scss # Entry point — @forward 'variables' first, then @use the partials
static/ # Static assets copied as-is (fonts, images)
screenshots/
light.png # Preview screenshot (light skin)
dark.png # Preview screenshot (dark skin)
example/
trellis_site.yaml # Minimal preview site config
content/
_index.md
posts/
_index.md
welcome.md
themes/
<name> -> ../.. # Symlink to the theme root, made by `trellis create`
The theme.yaml manifest
The manifest is the single source of truth for your theme. It declares params with types and defaults, and is parsed by trellis_site at build time.
name: verdant
version: 1.0.0
author: Trellis Team
description: >-
A minimal, accessible blog theme for Trellis. Content-first design with
three color skins, responsive layout, and full keyboard navigation.
min_trellis_version: 0.12.0
screenshots:
- screenshots/light.png
- screenshots/dark.png
features:
- blog
- dark-mode
- responsive
- accessible
params:
# Standard params (required by the contract)
skin:
type: enum
values: [light, dark, auto]
default: auto
description: Color scheme — auto follows OS prefers-color-scheme
primary_color:
type: color
default: "#2563eb"
description: Brand/accent color — links, buttons, active states
# Theme-specific params (optional extensions)
hero_title:
type: string
default: null
description: Homepage hero title override (null = site title)
Manifest fields
| Field | Required | Description |
|---|---|---|
name |
Yes | Theme identifier. Must match ^[a-z0-9][a-z0-9_-]*$ and equal the name of the directory the manifest sits in |
version |
Yes | Semantic version (e.g. 1.0.0) |
author |
No | Author name or organization. Recommended, but nothing reads it — neither ThemeManifest.load nor the gallery generator requires it |
description |
Yes | One-sentence description for theme galleries. Plain prose — no backticks |
min_trellis_version |
No | Minimum trellis_site version required |
screenshots |
No | Relative paths to preview PNG files, resolving inside the theme directory |
features |
Yes | Feature tags. Must contain exactly one archetype tag — docs, landing, or blog — plus any number of free-form tags |
params |
Yes | Parameter definitions (see below). Required by the standard-params contract below, not by the loader: a theme with no params: loads and builds, and simply ignores every theme_params: a site sets |
Name and archetype rules
The theme gallery is generated from the manifests and CI gates the generated
output (dart run tool/generate_theme_gallery.dart --check), so these rules are
checked mechanically. Each one fails the generator with an error naming the
theme:
theme.yamlparses as a YAML mapping — a malformed file is reported against the theme rather than as a bare parser stack trace.nameis a non-empty string matching^[a-z0-9][a-z0-9_-]*$. The name becomes a directory segment in every site that installs the theme and a path segment in the gallery's asset URLs, so it has to be portable on every filesystem and safe in a URL. It is also whattrellis theme add --theme <name>accepts.nameequals the directory name — a theme inthemes/orchard/must declarename: orchard. The installed directory and the configuredtheme:value are the same string, so a mismatch would install a theme that cannot be selected.themes/<name>/README.mdexists — every gallery card links to it, and the link is external to the built site, so no link checker would catch a dead one.descriptionis a non-empty string and contains no backticks. The gallery renders it withtl:text, so`backticks`reach the card as literal characters instead of code formatting.featuresis a list of strings containing exactly one archetype tag — one ofdocs,landing,blog. The gallery shows it as the card's archetype label, which is how a site builder picks a starting point; zero tags leave the card unlabelled and two make the label ambiguous. Every otherfeaturesentry (dark-mode,responsive,search, …) is free-form.- Every declared
screenshotspath stays inside the theme directory, both as written and after symlinks are resolved — the generator copies those files into the published site.
Two screenshot problems are warnings rather than failures, and the card is
published without the image: a file named anything other than light.png or
dark.png (only those two variants reach a card), and a declared path with no
file behind it.
Param types
| Type | YAML example | SASS behavior | CSS custom property |
|---|---|---|---|
color |
"#2563eb" |
$trellis-primary-color: #2563eb !default (plus a _dark twin, see below) |
--trellis-primary-color: #2563eb |
string |
"system-ui, sans-serif" |
$trellis-font-family: system-ui !default |
--trellis-font-family: system-ui |
boolean |
true |
$trellis-show-toc: true !default |
Not emitted as CSS |
int |
160 |
$trellis-excerpt-length: 160 !default |
--trellis-excerpt-length: 160 |
enum |
auto |
$trellis-skin: auto !default |
Not emitted as CSS |
list |
(see nav_links) | Not emitted as SASS or CSS | Not emitted as CSS |
null defaults are emitted as initial in CSS custom property output (e.g.
--trellis-footer-text: initial;).
The SASS column is the declaration in _variables.scss. The build configures
each declared variable with the merged value (see
How the SASS bridge works); a param with no
declaration is inert in SASS.
The standard-params contract
The 25 standard params form a contract between themes and site builders. Every
theme must support all 25. This is what lets site builders switch themes and
carry their theme_params: customizations across.
| Category | Params |
|---|---|
| Skin & Colors (15) | skin, the seven colors primary_color, accent_color, text_color, muted_color, bg_color, surface_color, border_color, and their seven _dark twins (primary_color_dark, …, border_color_dark) |
| Typography | font_family, heading_font_family, code_font_family |
| Layout | max_width, border_radius |
| Navigation | nav_links, social_links |
| Footer | footer_text, show_powered_by |
| Features | show_rss_link |
The twin rule. Every type: color param has a twin <name>_dark, also
type: color, whose default equals the dark palette's entry. A plain color param
sets the light palette's entry and its twin the dark one (see
Colors and skins). Twins have no twins.
Theme-specific params
Themes may add any number of params beyond the 25 standard ones. By convention,
place them after the standard block in theme.yaml with a comment separating
them, and use snake_case names that do not clash with the standard params:
params:
# === Standard Params (25) ===
skin:
...
# (other standard params)
# === Blog-Specific Params ===
show_reading_time:
type: boolean
default: true
description: Show estimated reading time on posts
excerpt_length is an optional, theme-specific content-rendering param. Themes
that use generated summaries can declare it as an int; it controls the
plain-text summary length. It is not part of the 25 standard params.
Theme data files
A theme can provide YAML data files under data/ for structured content that
belongs to the theme rather than to a parameter. For example,
data/navigation.yaml is available to layouts as ${data.navigation.*}. The
filename stem becomes the key below ${data}.
Theme data is a fallback. Trellis loads the theme's files first, then the site's
data/*.yaml files. When both provide the same stem, the site file replaces the
complete theme value – nested maps and lists are not deep-merged. Files with
different stems remain available together. This lets a theme ship useful
defaults while a site owns any deliberate replacement.
Colors and skins
A skin is a complete palette: a map of color entries in
sass/_skins/_light.scss or _dark.scss. A theme ships both, and a site picks
between them with skin: light | dark | auto. Colors are per mode:
- Each color param sets one entry in one palette.
primary_colorsets the light palette'sprimary-color, and its twinprimary_color_darksets the dark palette's. - The
skinparam selects which palette the theme emits:lightthe light one,darkthe dark one,autothe light one plus a@media (prefers-color-scheme: dark)block carrying the dark one. - A plain color param sets the light entry only, under every skin. With
skin: darkit changes nothing, and a site recolors dark mode with the_darktwin. A color chosen against a white background has no verified contrast on a dark one, so Trellis does not apply it there. - Dark is never derived from light. A theme must not compute a palette
(
darken(),color.adjust(), a mixed tint) from the other mode's entry: both palettes are authored, their contrast is checked per pair, and one override must not silently shift 13 pairings.
Every dark view therefore reads $trellis-palette-dark: the forced-dark :root,
the auto @media block, and any reader toggle your theme adds. A dark token
follows <name>_dark exactly when its light counterpart is set from <name>. A
token that merely equals a palette entry, or has no color param, stays
theme-authored.
The twin rule for theme.yaml: every type: color param has a twin named
<name>_dark, also type: color, whose default equals the dark palette's entry
for that name (kebab-case: primary_color_dark is primary-color). Twins have
no twins. This holds for theme-specific colors as well as the seven standard
ones.
SASS integration
_variables.scss – the param bridge
Every theme param that has a SASS representation must have a variable in
_variables.scss, named $trellis-<param-name> (kebab-case) and declared
!default. The skins are maps, so each color's default is read from them, and a
color needs two variables, one per mode:
// sass/_variables.scss (excerpt of the scaffold: trellis create --template theme)
@use 'sass:map';
@use '_skins/light' as light;
@use '_skins/dark' as dark;
$trellis-skin: auto !default; // light | dark | auto
$trellis-primary-color: map.get(light.$palette, primary-color) !default;
$trellis-primary-color-dark: map.get(dark.$palette, primary-color) !default;
// …one pair per color param
// The dark palette with the site's `_dark` overrides applied. No !default: the
// bridge never configures it. Public (not `$_`), because main.scss reads
// $trellis-palette-dark across the module boundary.
$trellis-palette-dark: map.merge(
dark.$palette,
(
primary-color: $trellis-primary-color-dark,
// …
)
);
// A forced dark skin selects the dark palette. Every partial keeps reading
// $trellis-*-color, so this runs before anything derived from them.
@if $trellis-skin == dark {
$trellis-primary-color: map.get($trellis-palette-dark, primary-color);
// …
}
$trellis-font-family: system-ui, -apple-system, sans-serif !default;
$trellis-heading-font-family: null !default;
// Derived variable: no !default, so it is never configured. @if shares the
// root scope, so this updates the global variable without !global.
$trellis-heading-font: $trellis-font-family;
@if $trellis-heading-font-family {
$trellis-heading-font: $trellis-heading-font-family;
}
The !default convention is critical. !default is what makes a variable
configurable. The bridge configures a variable with the merged param value, and
Sass rejects configuring a variable that is not declared !default. Values that
are not params (the dark palette, derived values) carry no !default, so the bridge
never touches them.
Params without a SASS variable are inert. Configuring a variable the entry
cannot take is a Sass error (This variable was not declared with !default in the @used module.), so the build asks Sass. For each compile entry it offers the
manifest params whose $trellis-<name> some file under sass/ declares
!default, drops each one Sass rejects, and configures the rest. nav_links,
social_links and any theme-specific param you read only in templates
(${theme.<name>}) need no variable and cost nothing.
What Sass accepts is the rule:
- A
$trellis-*: … !default;at the top level of the entry, or of a file the entry@forwards, is configured, wherever that file is. A value with line breaks,url(//…)orurl(data:…;…)is fine. - A
!defaultSass cannot configure is left out, silently: one inside a string, a mixin or an@if, or in a file the entry only@uses (a skin, a sub-module). The param bound to it has no SASS effect:trellis buildwarns, naming the theme, entry and param, when a site overrides it (--verboselists every such variable), and the compile-every-theme gate fails for it in bundled themes. Declare every param-backed variable in_variables.scss, which the entry forwards. - Every non-partial
.scssor.sassfile insass/is a compile entry, asked on its own, so each one must@forward 'variables'first (see main.scss below).
How the SASS bridge works
During trellis build, the CSS processing pipeline:
- Reads
theme.yamlparams merged with the site'stheme_params:. - Generates
.trellis/build/_theme_params.scss, a plain module of$trellis-<name>: <value>;for every merged param (no!default). - Offers the params whose variable some theme file declares
!defaultto each entry, and keeps those Sass accepts (the rule above). - Writes a wrapper per compile entry,
.trellis/build/bridge_<entry>.scss, and compiles it:
// .trellis/build/bridge_main.scss
@use "theme_params" as tp;
@use "/abs/path/to/my-theme/sass/main.scss" as theme with (
$trellis-skin: tp.$trellis-skin,
$trellis-primary-color: tp.$trellis-primary-color,
$trellis-primary-color-dark: tp.$trellis-primary-color-dark,
// …every param the theme declares !default
);
With no configurable variables, the entry is @used without with(). The entry
gets the explicit namespace theme because Sass rejects a default namespace that
is not an identifier (an entry named 2col.scss).
The bridge also injects nothing for the skin: skin is an ordinary param, and
_variables.scss selects the palette from it.
Result: site builders control theme appearance entirely through
trellis_site.yaml – no SASS editing required. A theme also compiles without the
bridge (sass main.scss), on its own !default values with skin: auto.
Load path order (searched when a @use has no file next to the importing
one):
.trellis/build/– generated bridge files (_theme_params.scss, wrappers).<site>/sass/– the site's own partials.<theme>/sass/– your theme's partials.
Sass resolves a @use relative to the file containing it before it consults
the load path, so the theme's own @forward 'variables' and @use 'base' always
find the theme's files. A site sass/_variables.scss never shadows them, and
under @use it cannot reconfigure them either: the only way to change a theme's
values is theme_params:. Site stylesheets under static/ can read the merged
values with @use 'theme_params' as tp; (for example
color: tp.$trellis-primary-color).
Skin files
A skin file exposes a $palette map and nothing else: no !default, no
$trellis-* declaration. Its keys are the color params' names in kebab-case
(primary-color, accent-gradient-start), which is how a param finds its entry.
An entry may be a literal or built from other variables. Palette entries with no
param (syntax token colors, say) ride in the same map and stay theme-authored.
// sass/_skins/_light.scss (excerpt)
// WCAG 2.1 AA contrast ratios:
// #1f2937 on #ffffff = 14.68:1 (body text — passes 4.5:1)
// #2563eb on #ffffff = 5.17:1 (primary — passes 4.5:1)
$palette: (
text-color: #1f2937,
bg-color: #ffffff,
primary-color: #2563eb,
// …
);
Name the directory _skins and import it as @use '_skins/light':
@use 'skins/light' does not find it. Keep the file contents equal to the
theme.yaml defaults (light entries to the plain params, dark entries to the
_dark twins). In a site build the theme.yaml defaults are passed to the theme,
so they win over the palette map entries: keep each color param's default equal
to its palette entry. The compile-every-theme gate checks this for bundled
themes, and trellis build warns, naming the theme, the param and both values,
when a default differs from its palette entry in any theme.
main.scss – entry point
// sass/main.scss (excerpt of the scaffold)
@forward 'variables';
@use 'sass:map';
@use 'variables' as *;
:root {
--trellis-primary: #{$trellis-primary-color};
// …
}
// Auto skin: the dark palette for OS dark mode, at runtime.
@if $trellis-skin == auto {
@media (prefers-color-scheme: dark) {
:root {
--trellis-primary: #{map.get($trellis-palette-dark, primary-color)};
// …
}
}
}
@forward 'variables' must be the first rule that loads _variables.scss.
Sass configures a module only when it is first loaded. A @use 'base' above the
forward, where _base.scss has its own @use 'variables', loads it
unconfigured, and the build fails:
This module was already loaded, so it can't be configured using "with".
A main.scss that only @uses variables (no @forward) fails too, because
the variables are then not part of the module the bridge configures:
This variable was not declared with !default in the @used module.
The @forward is needed in addition to @use 'variables' as * when the entry
itself reads the variables (the @if block above); both can sit in one file.
Every partial that reads $trellis-* variables declares its own
@use 'variables' as *; and, if it needs another partial's members, @uses that
partial too. A module's CSS is emitted once, at its first load, so list partials
in the order their rules should appear.
The @if $trellis-skin == auto guard is what makes skin: light and
skin: dark emit no prefers-color-scheme block: under light it would flip a
forced-light site dark for dark-OS visitors, and under dark the base :root is
already dark. SASS variables are compile-time only, so runtime switching between
the two modes needs the CSS custom property override.
Sub-module defaults. To give a sub-module's own !default variable a
theme-specific default while leaving it overridable, forward it with a
configuration:
// sass/_variables.scss
@forward 'tokens' with ($gap: 2rem !default);
!default inside the with() keeps $gap configurable by whoever @uses the
theme. This is a theme-authoring tool, not a bridge tool: the bridge's own
configuration is the @use … with() wrapper above, and it configures only
$trellis-* variables the entry declares !default or forwards.
CSS custom properties
The SASS bridge also emits a css/theme-props.css file with :root custom
properties for every non-boolean, non-enum, non-list param:
:root {
--trellis-primary-color: #2563eb;
--trellis-primary-color-dark: #3b82f6;
--trellis-font-family: system-ui, -apple-system, sans-serif;
--trellis-max-width: 800px;
/* ... */
}
The seven --trellis-<name>-dark properties appear here because the file lists
every color param, but nothing reads them: your dark views take their colors from
the dark palette inside your own CSS, which a <name>_dark param reaches through
$trellis-palette-dark.
Templates reference these via a
<link rel="stylesheet" href="/css/theme-props.css"> tag in base.html. Your own
SASS emits the runtime tokens your components read, from main.scss (or
_variables.scss), so they exist for standalone compilation (without the bridge)
too. Boolean and list params have no CSS custom-property equivalent – use them in
templates via ${theme.show_reading_time} etc.
Layouts with tl:define blocks
Theme layouts are built with template inheritance:
tl:extends points a child layout at a parent, and
tl:define fills named slots the parent declared.
base.html – the HTML shell
base.html provides the full HTML document, navigation, and footer. Child
layouts inherit it via tl:extends and fill named slots via tl:define.
Standard tl:define blocks (present in any theme):
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title tl:text="${page.title} + ' — ' + ${site.title}">Page — Site</title>
<meta name="description"
tl:attr="content=${page.description} ?: ${page.summary} ?: ${site.description}">
<link rel="stylesheet" href="/css/main.css">
<link rel="stylesheet" href="/css/theme-props.css">
<!-- RSS feed link — conditional on show_rss_link param -->
<link tl:if="${site.feeds.atom} and ${theme.show_rss_link}"
rel="alternate" type="application/atom+xml"
title="Atom Feed" tl:attr="href=${site.feeds.atom}">
<!-- Extra head slot for child layouts to inject tags -->
<meta tl:define="head-extra">
</head>
<body>
<a href="#main-content" class="skip-to-content">Skip to content</a>
<header class="site-header" tl:define="site-header">
<!-- nav here -->
</header>
<main id="main-content" class="main-content" tl:define="content">
<!-- child layouts fill this -->
</main>
<footer class="site-footer" tl:define="site-footer">
<!-- footer here -->
</footer>
</body>
</html>
Child layout pattern
<!-- home.html -->
<html tl:extends="layouts/base.html" lang="en">
<head><title>Home</title></head>
<body>
<main tl:define="content">
<div class="container">
<section class="hero">
<h1 tl:text="${theme.hero_title} ?: ${site.title}">Welcome</h1>
</section>
<!-- post cards here -->
</div>
</main>
</body>
</html>
Using ${theme.*} in templates
All merged theme params are available as ${theme.<param_name>}:
<!-- Navigation from the nav_links param -->
<ul class="nav-list">
<li tl:each="link : ${theme.nav_links}">
<a tl:href="${link.url}" tl:text="${link.label}">Link</a>
</li>
</ul>
<!-- Conditional feature toggle -->
<span tl:if="${theme.show_reading_time}"
tl:with="readTime=${#numbers.max(#numbers.ceil(#strings.length(page.content) / 1000), 1)}">
<span tl:text="${readTime} + ' min read'">3 min read</span>
</span>
Boolean params use truthiness directly in tl:if; list params are iterable with
tl:each; null params evaluate to falsy.
What site builders can override
Site builders customize your theme along four dimensions, from simplest to most powerful. Design your theme so the common cases only need dimension 1.
-
Params – change values via
theme_params:intrellis_site.yaml. This covers the vast majority of customization. -
Layout override – a file at the same relative path in the site's
layouts/replaces yours entirely (site layouts are checked before the theme's). -
Block override – override one
tl:defineslot viatl:extends:<!-- site/layouts/base.html — override just the footer --> <html tl:extends="theme:layouts/base.html" lang="en"> <body> <footer tl:define="site-footer"> <p>Custom footer without touching the theme.</p> </footer> </body> </html>The
theme:prefix forces resolution from the theme directory; without it, the site's own layouts are checked first – which is what enables the full replacement in dimension 2. -
Site stylesheets – the site's own
sass/partials andstatic/*.scssfiles can read the merged params with@use 'theme_params' as tp;, but they cannot reconfigure the theme's variables: Sass resolves the theme's own@forward 'variables'relative to the theme file before any load path, so a sitesass/_variables.scssnever shadows it. Params intheme_params:are the one way to change a theme's SASS values.
Because of this precedence, the theme: prefix and the standard-params contract
are what make cross-boundary customization work without forking.
The example directory
The example/ directory holds a minimal preview site so you can test the theme
locally without a real content site:
# example/trellis_site.yaml
title: My Blog
description: A sample blog powered by Trellis and this theme.
baseUrl: http://localhost:4000
# Resolve the bundled theme by name (see the symlink note below).
theme: mytheme
theme_params:
skin: auto
nav_links:
- label: Home
url: /
- label: Posts
url: /posts/
paginate: 5
The build resolves a theme by joining <siteDir>/themes/<value>, so the example
needs a themes/mytheme entry. Because the example lives inside the theme, that
entry is a relative symlink pointing back at the theme root – trellis create
makes it for you; to create it by hand, ln -s ../.. example/themes/mytheme. A bare theme: .. does not work: it
resolves to the example directory itself, not the theme.
Run the preview from the example directory:
cd example && trellis build && trellis serve
Publishing
Repository naming
Convention: trellis-theme-<name> (e.g. trellis-theme-orchard). This makes
themes discoverable via GitHub search.
A theme can also live under themes/<name>/ in a repository that carries
several – the layout the built-in Trellis themes use. Site builders install one
of those with trellis theme add <url> --theme <name>, which copies just that
subdirectory.
Version tagging
Tag releases so site builders can pin to a stable version:
git tag v1.0.0
git push origin v1.0.0
Installation with a pinned ref:
trellis theme add https://github.com/yourname/trellis-theme-orchard --ref v1.0.0
Screenshots
Place 1280×800 PNG screenshots at screenshots/light.png and
screenshots/dark.png. These are referenced in theme.yaml and displayed in
theme galleries. After intentionally recapturing an official theme, review the
image, update its SHA-256 entry in tool/theme_screenshot_digests.json, then run
the gallery generator; it rejects changed bytes until the reviewed digest is
pinned.
Pre-publishing checklist
- All 25 standard params present with correct types and non-null defaults (except optional strings).
- Every color param has a
<name>_darktwin whose default equals its dark palette entry (and each base default equals its light entry). - Every param-backed SASS variable is declared
!defaultin_variables.scss, and every entry stylesheet insass/starts with@forward 'variables'. - Every stylesheet loads others with
@useor@forward; skins expose a$paletteand declare nothing!default. - A
README.mdin the theme directory — the gallery card links straight to it. screenshots/paths match thetheme.yamlscreenshot entries.- The
example/site builds cleanly withtrellis build. - Light and dark skins both pass WCAG 2.1 AA contrast (4.5:1 body text).
- Semantic HTML landmarks:
<header>,<nav>,<main id="main-content">,<footer>,<article>. - A skip-to-content link as the first
<body>element.
The official Verdant theme implements every pattern in this guide – the full
manifest, _variables.scss with !default and the dark palette merge, light and dark
palette maps, a main.scss that forwards variables first and carries the
auto-skin media query, a base.html with all four tl:define blocks,
child layouts with tl:extends, taxonomy layouts, and an example preview site.
Read it alongside this guide as a reference.