How themes work

A theme decides how your site looks. Your content stays the same when you switch themes.

The short version

Switch themes: Admin → Themes → Activate on the one you want.
Change a theme: open it in Themes, edit a file, save. Reset puts a file back to how it shipped.
Make your own: copy a theme folder, rename it, change its id, click Rescan, then Activate. Create a theme walks through it.

You don't need to learn anything else to restyle a site. The rest is reference.

What a theme is

A theme is a folder of files that decides how your site looks. Your content (pages, posts, menus, media) lives in the database. The theme only decides where that content goes and how it is styled. Switching themes never changes or deletes content.

Themes live in your site folder under themes/<tier>/<id>/. A new site gets a copy of the built-in themes on first start. After that, the copies are yours to edit.

Tiers

A tier is the format a theme is written in. Pick static unless you have a reason not to.

Tier	You write	Code runs?	Use it when
static	Plain HTML, CSS, JS. One file per page.	Only your own JS, in the browser	Almost always. Every live site today uses it.
templated	LiquidJS templates	Template logic only, sandboxed. No JS.	You need loops and conditionals over live data.
declarative	JSON block layouts	Nothing	You want a theme that is pure data. Reference only today.
handlebars	Handlebars templates	Template logic only, sandboxed	Supported, but no example theme ships.
code	n/a	n/a	Reserved. Not built. Don't use it.

These docs cover the static tier.

File layout (static tier)

themes/static/my-theme/          folder name must equal "id" in theme.json
  theme.json                     required. Name, tier, templates, partials.
  tokens.json                    required. Colors, fonts, spacing, as design tokens.
  tokens.light.json              optional. Light-mode overrides.
  css/theme.css                  your stylesheet
  scripts/*.js                   optional. Your browser JS.
  assets/                        optional. Images, fonts, logo.
  render/pages/*.html            one complete HTML file per page. index.html is the home page.
  render/partials/nav.html       shared header
  render/partials/footer.html    shared footer
  render/partials/footer-*.html  optional footer variants, e.g. footer-minimal.html
  NOTICE.md                      optional. Credits and licenses.

Three kinds of file under render/:

Page: a complete HTML document for one URL. render/pages/pricing.html is served at /pricing.
Partial: a shared fragment, like the header, pulled into every page with one marker line.
Template: a page file that your own pages and posts can pick to render through. It has a content marker where the page or post body goes. You list templates in theme.json.

Next: Create a theme, then Theme markers for every marker a template can use.