# Port60 template development, the complete reference for AI agents

Port60 site templates are versioned artifacts of Liquid renderers + CSS rendered by the
platform engine. Scaffold one with `p60-template-kit create`, iterate with
`p60-template-kit validate --json` (the machine feedback loop), preview with `dev`, and
`package` for studio upload. Every scaffold contains AGENTS.md with the working rules.

━━━ GUIDES ━━━

━━ guides/ai-quickstart.md ━━


Port60 templates are unusually good territory for AI coding agents: the whole job is a handful of
Liquid files against a **machine-readable contract**, with a validator that returns structured
errors the agent can iterate against, and hard walls (the dialect whitelist, escape-by-default,
render budgets, human review) that make the worst an agent can produce a *rejected upload*, never
a broken charity site.

## The setup

```bash
npx @port60/template-kit create riverside-warm
cd riverside-warm && npm install
```

The scaffold ships **`AGENTS.md`** (and an identical `CLAUDE.md`), the briefing every serious
coding agent reads on entry: the file layout, the contract rules, and the iteration loop. You
don't need to explain the platform to your agent; the scaffold already has.

## The loop your agent should run

1. Edit `sections/*.liquid`, `layout.liquid`, `assets/theme.css`, `manifest.json`.
2. **`npm run validate:json`**, machine-readable: `{ok, errors[], warnings[], provenSupports}`.
   The agent fixes every error and re-runs until `ok: true`. This is the platform's *exact*
   upload check, so a clean local pass is a guaranteed clean upload.
3. You watch **`npm run dev`** at `http://localhost:4400`, the same fixtures render reviewers
   see. Refresh after edits; validation re-runs in the terminal on every save.
4. **`npm run package`**, the uploadable `<name>-<version>.zip`.

## A kickoff prompt that works

> Read AGENTS.md first. Build me a warm, editorial template for a food-bank charity: generous
> type, cream background, a photography-led hero. Support the hero, values, cta and whatsOn
> sections, a layout with the member menu island in the header, and ship two looks, "Warm" and
> "Evening". After every change run `npm run validate:json` and fix all errors. Tell me when it
> validates clean.

## For the agent itself

Everything on this site is available as one plain-text file at
[`/llms-full.txt`](/llms-full.txt), the guides plus the generated contract reference (sections,
islands, context variables, dialect, tokens, manifest schema). Fetch it once into context and
build against it.

## What the agent cannot do, by design

Supports flags are **proven, not claimed**: declaring `supports.worship` without rendering the
worship fixture is a validation error, as is the reverse. Islands are placed, never implemented.
Uploads only exist for approved developers, and every version passes human review before it can
reach a charity's site. The agent gets you to a validated artifact fast; the trust chain stays.


━━ guides/artifact-anatomy.md ━━


A template artifact is a directory published to object storage under `{name}/{version}/`. Once
published, that prefix is **immutable**; the platform caches artifacts aggressively (in-memory and
at the CDN) precisely because a version can never change underneath anyone.

```text
{name}/{version}/
├── manifest.json        # REQUIRED: identity, format, what you support
├── layout.liquid        # OPTIONAL: the page chrome, when supports.layout is true
├── sections/            # REQUIRED: one {type}.liquid per supported section type
│   └── *.liquid
├── pages/               # OPTIONAL: display bodies for pages in supports.pageTemplates
│   └── *.liquid
└── assets/
    └── theme.css        # REQUIRED: the template's entire look
```

## manifest.json

The manifest declares what your template **is** and what it **supports**. It's validated against
[a JSON Schema](/reference/manifest/) at publish time; the important fields:

| Field | What it means |
| --- | --- |
| `name` | Permanent identity. Lowercase, hyphenated, stable across every version. |
| `version` | Semver. Immutable once published, a fix is a new version. |
| `format` | The contract major you're written against, currently `port60-liquid@1`. |
| `supports.pages` | Section based page bodies you render: currently `home` and `about`. |
| `supports.sections` | Which section types you ship renderers for. |
| `supports.islands` | Every island your renderers place. |
| `supports.layout` | True when you ship `layout.liquid` and own the chrome, see [Layouts](/guides/layouts/). |
| `supports.pageTemplates` | Route specific data views you render. Listings are `events` and `articles`; details are `course` and `article`. See [Page templates](/guides/page-templates/). |
| `compositions` | Your preferred composition per page: the ordered section types the design is built around, each with a role. `core` carries the design (an organisation removing one is warned, never stopped), `recommended` is on by default, `optional` is offered. A page an organisation never edited renders this composition, the kit preview renders it, and the Pages editor offers it as the order to reset to. Every type must be in `supports.sections` and belong to that page. |
| `requiresCapabilities` | Capabilities the design needs to work as intended. This is checked against the artifact and used for catalogue matching. It never grants an entitlement. |
| `suitsProfiles` | Organisation profiles the design was composed for. This improves recommendations but never hides or unlocks a feature. |
| `fonts` | Webfont stylesheet URLs the platform loads in `<head>`. |
| `settings.schema` | Your own theming knobs (colour schemes etc.), see [Theming](/guides/theming/). |

Two support rules matter:

1. **Sections you don't support are omitted, never an error.** If a charity authors a section your
   template has no renderer for, that section silently doesn't render. Support the catalogue
   broadly, but you'll never crash for missing one.
2. **Every island you place must be declared** in `supports.islands`; the validator enforces
   placed ⊆ declared ⊆ platform registry.
3. **Every required capability needs a visible surface.** The validator rejects a capability claim
   that has no matching section, page template, island or context declaration in the artifact.

## sections/*.liquid

One file per supported section type, named exactly after it (`hero.liquid` renders `hero`
sections). Each is a self-contained fragment written in the
[Port60 dialect](/reference/dialect/), there is no include mechanism and no partials in contract
v1, and sections never contain chrome (that's [the layout's job](/guides/layouts/)).

Each renderer receives the [render context](/reference/context/): the `section` object (typed per
the [section catalogue](/reference/sections/)) and `brand`.

Renderers must survive the **minimal fixture** of every type they support, the least content a
charity can author. The validator renders both fixtures; if your hero falls over when `eyebrow`
is absent, you don't publish.

## assets/theme.css

Your whole look, one file. It layers on top of the platform base stylesheet, which owns
mechanics (layout plumbing, form controls, island internals) and exposes
[CSS tokens](/reference/tokens/) for everything brandable. Your CSS:

- overrides tokens under `:root:root` (doubled specificity so the theme wins),
- styles your own section markup (class names are yours, the starter uses an `lq-` prefix),
- may restyle islands **only** through their published [styling API](/reference/islands/).

## What an artifact may NOT contain

- **No JavaScript.** Behaviour is platform-owned; templates place [islands](/guides/islands/).
- **No network calls, no data fetching.** The platform feeds renderers everything they get.
- **No unsanitised HTML output.** `| raw` is for the contract's richtext fields only.
- **No file inclusion**, `include`/`render`/`layout` are excluded from the dialect and fail at
  parse time.


━━ guides/capabilities-and-profiles.md ━━


Port60 separates content, reusable capabilities, organisation profiles and visual templates. A
template can present a capability, but it cannot enable that capability or grant an entitlement.

## Declare requirements honestly

Use `requiresCapabilities` for capabilities the design needs in order to work as intended. The
validator requires each declaration to have a corresponding section, page template or island:

```json
{
  "requiresCapabilities": ["worship", "giving", "newsletter"],
  "suitsProfiles": ["mosque"]
}
```

If a decorative region merely looks good when a capability exists, but the template still works
without it, do not call that capability required. Optional contexts are always sparse, so branch and
omit when their data is absent.

`requiresCapabilities` is catalogue metadata. The Appearance picker compares it with the tenant's
enabled features, labels missing requirements and prevents a misleading recommendation. It never
turns a feature on.

## Profile recommendations

`suitsProfiles` accepts `general`, `mosque`, `church`, `appeal-charity`, `pta`, `community` and
`training`. An empty list means general purpose. An exact profile match sorts ahead of a general
template in the picker, but profile metadata never hides a template and never changes permissions.

Profiles describe design intent, not fixed content. A mosque template can use worship and giving
surfaces without inventing prayer times or appeals. The organisation supplies the data.

## Capability surfaces

| Capability | Template-facing surface | Platform boundary |
| --- | --- | --- |
| Giving and appeals | `donation_widget`; `appealGrid` and `emergency` with `causes[]` | Payment, Gift Aid and processor data stay in the platform |
| Worship | `worship` layout context and `next_prayer` | The platform supplies times and owns the ticking clock |
| Events and courses | Listing data or page templates; transaction islands | RSVP, tickets, enrolment and payment remain islands |
| Articles | `articles`, `article`, categories and engagement islands | Comments and engagement behaviour remain platform owned |
| Services | `programmes` with `services[]` | Templates receive display projections, not service internals |
| Forms | `form` island | Field rendering, human checks and submissions remain platform owned |
| Resources | `resources` with `resources[]` | Only public documents are exposed |
| Locations | `locations` with `locations[]` | Provider references and private notes are excluded |
| Newsletter | `newsletter_signup` | Explicit consent, evidence and unsubscribe handling stay in the platform |
| Internationalisation | `locale` context and `language_switch` | The platform owns locale switching and document direction |
| Search | `search` | Searches public article, service, event and resource projections only |

## Current module depth

The first capability release is intentionally narrow at its public boundary. Forms provide text,
email, long text, choice and checkbox fields with privacy-recorded submissions. Form responses
contain personal data. Organisations should collect only what they need and apply their own
retention policy; the initial inbox does not claim automated retention, export or case-management
workflows.

Those surfaces do not turn a template into an operational CRM. Forms do not provide workflow
automation or payment collection. Template authors should not imply functionality beyond the
published contract.

## Design for more than one sector

Prefer reusable structures over organisation-specific assumptions. `locations` works for branches,
community halls and campuses. `programmes` works for services, classes and projects. `resources`
works for policies, lesson materials and community guides. Profile-specific character should come
from composition, typography and content hierarchy, while the underlying capability surfaces stay
consistent.


━━ guides/first-template.md ━━


This walkthrough takes you from an empty directory to a template zip that the Port60 Studio can
accept. You do not need the Port60 platform repository or a platform account to build and validate
the template locally.

## Prerequisites

- Node 20 or newer
- npm

Templates contain Liquid and CSS only. The kit supplies the preview renderer, contract fixtures and
the same conformance checks used when you upload a template.

## 1. Create the template

Run the published kit with `npx`:

```bash
npx @port60/template-kit@latest create my-template
cd my-template
npm install
```

The folder name becomes the template's name, and the label derives from it, pass `--name` or
`--label` only when the identity should differ from the folder (the name is your immutable
catalogue identity, `name@version`, in the store and marketplace). The scaffold pins the kit you
scaffolded with as a devDependency, so `npm install` puts you on the current contract tooling. The scaffold
includes npm scripts plus `AGENTS.md` and `CLAUDE.md`, so a coding agent receives the same rules as a
human contributor.

Your new project contains:

```text
my-template/
├── manifest.json
├── layout.liquid
├── sections/
├── assets/
│   └── theme.css
├── AGENTS.md
└── package.json
```

`manifest.json` is the template's identity and capability declaration. Keep `name` lowercase and
hyphenated. Change `label` and `description` to the wording a non profit will see in the picker.

## 2. Preview it

```bash
npm run dev
```

Open [http://localhost:4400](http://localhost:4400). The preview renders the contract's sample
content, including a worship schedule when the template declares `supports.worship`. Functional
islands appear as realistic, non-interactive skeletons using their published styling classes.
Payments, identity, consent and other live behaviour remain platform owned, and the preview makes
no network requests.

Files are read again on refresh. Keep the preview open while you edit `layout.liquid`,
`sections/*.liquid` and `assets/theme.css`.

## 3. Make the design yours

Most of the design lives in two places:

- `assets/theme.css` controls colour, typography, spacing, responsive layout and the documented
  styling classes for platform islands.
- `sections/*.liquid` controls the markup for each supported section type.

Keep outputs escaped. Use `| raw` only for a contract field documented as sanitised rich text:

```liquid
<section class="page-hero">
  {% if section.eyebrow %}<p>{{ section.eyebrow }}</p>{% endif %}
  <h1>{{ section.title }}</h1>
  {% if section.bodyHtml %}
    <div>{{ section.bodyHtml | raw }}</div>
  {% endif %}
</section>
```

Navigation, worship times, donations and sign in are all supplied by the platform. Render their
documented data or place their islands. Do not replace them with fixed sample content.

## 4. Validate it

```bash
npm run validate:json
```

The command checks the manifest, restricted Liquid dialect, minimal and sample fixtures, island
declarations, layout slot and capability claims. A successful result includes the capabilities the
validator has proven:

```json
{
  "ok": true,
  "errors": [],
  "warnings": [],
  "provenSupports": {
    "layout": true,
    "worship": true
  }
}
```

Treat every error as an upload blocker. Review warnings too, particularly a missing
`member_menu`, because member enabled sites would otherwise lose their sign in route.

## 5. Package and upload it

```bash
npm run package
```

The kit validates once more and creates `<name>-<version>.zip` with only the allowed artifact
files. Upload that zip in your Studio, open the template, choose **Versions**, then submit the
validated version for review.

Published versions are immutable. Increase the semantic version in `manifest.json` before you
package the next release. Existing sites stay on their pinned version until they deliberately
apply an update.

## Where to go next

- [Anatomy of an artifact](/guides/artifact-anatomy/)
- [Sections and data](/guides/sections-and-data/)
- [Layouts and chrome](/guides/layouts/)
- [Capabilities and profiles](/guides/capabilities-and-profiles/)
- [The template kit](/guides/template-kit/)
- [Publishing and conformance](/guides/publishing/)


━━ guides/islands.md ━━


Templates are static by design, no scripts, no SDKs, no API calls. Live functionality (taking a
donation, buying a ticket, signing in) comes from **islands**: platform-owned, hydrated components
your template *places* with a single tag.

## Why islands are opaque, deliberately

You cannot re-lay-out an island's internals, and that's a design decision, not a missing feature:

1. **Compliance is platform-owned.** The donation widget isn't display, it's Strong Customer
   Authentication, the Gift Aid declaration's legal wording, consent capture. Markup a template
   could rearrange is markup a template could break in ways that have regulatory consequences.
2. **The upgrade promise depends on it.** The platform ships payment, security and accessibility
   changes underneath published templates with zero author intervention. That's only possible
   because transactional internals belong to the platform, your template keeps working precisely
   *because* it never reached inside.

The boundary is drawn at **transactional vs display**. Money movement, identity and consent are
islands forever. *Display* of platform data, what an event or article looks like in a listing, is yours to own through [page templates](/guides/page-templates/) and their documented data
context. If you're fighting an island for layout control, you're usually on the display side of
the line and a page template is the right tool.

```liquid
<div class="lq-cta-widget">
  {% island 'donation_widget' %}
</div>
```

At render time the platform splits your output at each island marker and mounts the real,
interactive component in that position. Payment logic, compliance (Gift Aid, consent), provider
SDKs, accessibility, all platform-side, all upgraded platform-side. **Your template keeps working
when we upgrade the internals**; that's the deal.

The local kit and Studio preview show non-interactive fixture skeletons instead. They expose the
same stable styling classes as the live island, so you can assess spacing, type, colour and common
content states while the preview remains network dead. They are visual aids, not simulations of a
payment, identity or consent flow.

## The rules

1. **Declare what you place.** Every island name used in your renderers must be listed in
   `manifest.supports.islands`. The validator enforces placed ⊆ declared ⊆
   [platform registry](/reference/islands/).
2. **Unknown names render nothing.** An island that isn't in the registry produces no output, never an error page.
3. **Planned islands are placeable-later.** The registry marks each island `available` or
   `planned`. Declaring a planned island is a validator warning today; it starts rendering the day
   the platform ships it.

Submission islands such as `newsletter_signup` and `form` keep abuse checks,
privacy acceptance and consent evidence in the platform. `search` reads public projections only.
`language_switch` and `next_prayer` own client behaviour that Liquid cannot provide without
JavaScript. Templates position these islands and style only their published classes.

## The primary action widget

Most templates should not place `donation_widget` in the hero at all. Place this instead:

```liquid
{% island 'primary_action_widget' %}
```

It is the widget that leads the site, and the charity decides what that is from their Pages editor:
the **donation widget** when giving leads, the **volunteer sign-up** when volunteering leads, or
nothing when they chose no widget in the hero. `site.focus` tells your template which one it will be
(`donate`, `volunteer` or `none`), and `section.action` on the home hero is the button that goes with
it: always the action whose widget is *not* on the page, so the leading action never appears twice.

To take part, declare both the island and what your template can lead with:

```json
"islands": ["primary_action_widget"],
"focus": ["donate", "volunteer"]
```

The validator holds you to it: a template that declares `volunteer` must place either this island
or `volunteer_signup`.

See both while you work: in `p60-template-kit dev` the bar at the top has a **Leads with** switch
(giving, volunteering, buttons only), or add `?focus=volunteer` or `?focus=none` to any preview URL.
The hero widget becomes the donation widget, the volunteer sign-up, or nothing, and `site.focus`,
`site.actions`, the header button and `section.action` follow, exactly as they do on a live site. Place `donation_widget` directly only when your template deliberately owns the
switch itself by branching on `section.primary.kind`.

## Styling an island

You never restyle island internals, those class names are private and change without notice.
Each island publishes a **styling API**: the stable class names your `theme.css` may target. The
[donation widget](/reference/islands/#donation_widget), for example, exposes `.donate-card`,
`.freq-tabs`, `.amount-grid` and friends.

```css
/* Safe: published styling API + platform tokens */
.donate-card {
  border-radius: var(--radius);
  box-shadow: var(--shadow);
}

/* NOT safe: anything not in the styling API is internal */
```

Most of an island's look follows your [token overrides](/reference/tokens/) automatically, islands are built from the same `--primary`/`--accent`/`--surface` palette as everything else, so
a well-themed template usually needs little or no island-specific CSS.

## Layout around islands

An island renders into the position of its tag, sized by your surrounding markup. Give it a
container you control (like the starter's `.lq-cta-widget`) and do your layout there, grid
placement, max-width, spacing. Treat the island itself as an opaque box.

## Islands are batteries, not cages

Three home sections, `events`, `whatsOn` and `articles`, used to be island-only. They now carry
**data contexts** (`events`, `infoEvents`, `latestArticles`, see [sections & data](/guides/sections-and-data/)),
so you choose per section:

- **Render the data yourself**, your markup, your voice. A newspaper template might set events as
  a ruled diary column; a photography-led one as full-bleed cards. Honour derive-or-omit: wrap the
  section in `{% if events.size > 0 %}` so an empty list renders nothing (the validator proves both
  directions).
- **Or place the island**, `{% island 'events_carousel' %}`, `{% island 'whats_on_strip' %}`,
  `{% island 'latest_articles' %}` remain the zero-effort defaults and handle empty states for you.

The payment boundary is absolute either way: these are listing models. Ticket sales, RSVP and
enrolment happen on platform-rendered detail views, link with `detailHref` / `href`, never rebuild
those flows.


━━ guides/layout.md ━━


Your template supplies the chrome (header, footer, sections). The platform supplies **pages**, donate, services, events, campaigns, the members area, and they render *inside your template*. For those pages to line up with your own sections, there is exactly one rule.

## The seam: `.container` and `.full`

Platform pages render through two layout intents, and your template **styles them**:

- **`.container`**, the contained content column (text, forms, cards). This is where the vast majority of content lives.
- **`.full`**, edge-to-edge, regardless of the container it sits in (a hero image, a colour band).

You control how they look:

- Set the **width** with the `--container` token (see [CSS tokens](/reference/tokens/)).
- Add your **gutter** and any treatment by styling `.container` (and `.full`) in your `theme.css`.

Because your sections and the platform's pages both flow through `.container`; they line up automatically, in every template, on every page, with no per-page work.

```css
:root:root {
  --container: min(1200px, 92vw); /* your content width */
}
.container {
  padding-inline: 1.5rem;         /* your gutter */
}
```

Use `.container` in your own layout and sections too, the header inner, the footer inner, each section's content wrapper. One container, everywhere.

## Never build a parallel content container

The one thing that breaks alignment is defining your **own** content container, a class sized off `var(--container)`:

```css
/* ✗ Rejected at publish. Platform pages stay on .container, so this drifts from them. */
.mytheme-container { max-width: var(--container); margin: 0 auto; padding: 0 1.5rem; }
```

Platform pages never see `.mytheme-container`, so your sections and our pages end up in two different columns with two different gutters. **The publish validator rejects any selector other than `.container`/`.full` that sizes its width off `var(--container)`**, so this is caught the moment you upload, before review, with a message telling you to style `.container` instead.

If you need a full-width bar with a centred inner (an announcement rail, a stat strip), compose the seam instead of copying it, put `.container` on the inner element and keep your own class only for the extra styling:

```html
<div class="mytheme-rail">
  <div class="container mytheme-rail-inner">…</div>
</div>
```

```css
/* ✓ .container gives the width + gutter; your class only adds the flourish. */
.mytheme-rail { background: var(--band-deep); }
.mytheme-rail-inner { display: flex; justify-content: center; gap: 1.2rem; }
```

That is the whole contract: **customise the seam, never replace it.** Fill it and every platform page falls into your layout, fluidly.


━━ guides/layouts.md ━━


By default the platform wraps your rendered sections in its own chrome. Declare
`supports.layout: true` and ship a `layout.liquid`, and your template owns the **body chrome**, header, navigation, footer, and where the page content sits. This is what lets a template
*restructure* a site, not just recolour it.

## The division of ownership

| Yours (layout.liquid) | The platform's (always) |
| --- | --- |
| Header markup & brand lockup | `<head>`, title, SEO, social cards, JSON-LD |
| Navigation (from `nav` data) | Consent banner + consent-gated tags |
| Footer | The Port60 ID identity brand (the `member_menu` island) |
| Where `{% content %}` goes | Webfont loading (from your manifest's `fonts`) |

A template can never omit compliance chrome, the platform appends it after your layout's output.

## A minimal layout

```liquid
<header class="site-header">
  <div class="container header-inner">
    <a class="brand-lockup" href="/">
      {% if brand.logoUrl and brand.logoType != 'icon' %}
        <img class="brand-logo" src="{{ brand.logoUrl }}" alt="{{ brand.name }}">
      {% else %}
        <strong>{{ brand.name }}</strong>
      {% endif %}
    </a>
    <nav class="site-nav" id="site-nav" aria-label="Primary">
      {% for item in nav.items %}
        {% if item.cta %}<a class="nav-cta" href="{{ item.href }}">{{ item.label }}</a>
        {% else %}<a href="{{ item.href }}">{{ item.label }}</a>{% endif %}
      {% endfor %}
      {% island 'member_menu' %}
    </nav>
  </div>
</header>

<main>
  {% content %}
</main>

<footer class="site-footer">
  <p>{{ brand.name }}{% if brand.tagline %}, {{ brand.tagline }}{% endif %}</p>
</footer>
```

Three rules the validator enforces:

1. **Exactly one `{% content %}`**, the slot the page's rendered sections are injected into.
2. `{% content %}` is **layout-only**, a section renderer using it fails conformance.
3. Islands placed in the layout follow the same discipline as everywhere: declared in
   `supports.islands`, present in the registry.

## Navigation is data, not markup

Your layout receives `nav.items`, the tenant's primary navigation. By default it's **derived** by
the platform from what actually exists (pages, enabled features, published content); when the tenant
has **curated** a header menu in their admin, `nav.items` is *that* menu instead. Either way it's the
same shape, so you render it identically and never need feature logic. Each item has `label`, `href`,
an optional `cta` flag (style it prominently, the Donate action), an optional `external` flag (add
`target="_blank" rel="noopener"`), and optional `children` for dropdown groups. Render **all of it**.

Two more menus ride alongside:

- **`nav.footer`**, the tenant's curated FOOTER menu (same item shape). It's **empty** unless they've
  built one, so branch on it and fall back to whatever footer links you'd normally show:
  `{% if nav.footer.size > 0 %}…{% else %}…{% endif %}`. Supporting it is optional, a template that
  ignores it just keeps its own footer.
- **`nav.derived`**, the platform's automatic list, always present even when the tenant has curated
  `nav.items`. Reach for it only if you want the auto, feature-aware nav somewhere regardless of their
  header curation; most templates just render `nav.items`.

See [Render context](/reference/context/) for the fixture your layout must survive.

## Dropdowns and mega navigation

Navigation may contain two levels below the top item. A child can carry `group`, `description` and
`imageUrl`, while a top item can carry `megaMenu.columns` and an optional `megaMenu.promo` card.
These presentation fields are tenant-authored. They have different jobs:

- **`group` is a shared presentation heading**, such as "Ways to help" or "Events". Several
  siblings with the same value belong under one heading; it is not a badge to repeat on every card.
- **`children` is the actual navigation hierarchy.** Keep each child's descendants attached to
  that child. Grouping siblings must not flatten a category and its article links into unrelated cards.
- **Article categories organise content.** A navigation `group` string does not assign an article
  to a category or create a category archive. Use the category links the platform supplies.

The example below reads the current `site.nav` tree. It renders named groups in their first-seen
order, keeps links within each group in supplied order, then renders ungrouped links in a separate
area without inventing an "Other" heading. Missing, null, empty and whitespace-only group values
are ungrouped. Every supplied child and grandchild remains available.

`map`, `compact`, `uniq` and `where` are supported by the Liquid whitelist. `group_by` is not.
Render the supplied structure and omit optional presentation when its data is absent:

```liquid
<nav id="site-nav" aria-label="Primary" data-p60-nav>
{% for item in site.nav.items %}
  {% if item.children.size > 0 %}
    <div class="nav-group" data-p60-nav-item>
      <a
        class="nav-group-toggle"
        href="{{ item.href }}"
        data-p60-nav-toggle
        aria-haspopup="true"
        aria-expanded="false"
        aria-controls="mega-menu-{{ forloop.index }}"
        {% if item.external %}target="_blank" rel="noopener noreferrer"{% endif %}
      >
        {{ item.label }}
      </a>
      <div class="mega-menu" id="mega-menu-{{ forloop.index }}" data-p60-nav-menu>
        <div class="mega-menu-heading">
          <strong>{{ item.label }}</strong>
          <a href="{{ item.href }}"{% if item.external %} target="_blank" rel="noopener noreferrer"{% endif %}>View all {{ item.label }}</a>
        </div>
        <div class="mega-menu-links"{% if item.megaMenu.columns %} style="--mega-columns: {{ item.megaMenu.columns }}"{% endif %}>
          {% assign groupNames = item.children | map: 'group' | compact | uniq %}
          {% for groupName in groupNames %}
            {% assign trimmedGroup = groupName | strip %}
            {% if trimmedGroup == '' %}{% continue %}{% endif %}
            {% assign groupedChildren = item.children | where: 'group', groupName %}
            <section class="mega-menu-group">
              <h3 class="mega-menu-group-label">{{ groupName }}</h3>
              <div class="mega-menu-group-items">
                {% for child in groupedChildren %}
                  <div class="mega-menu-card">
                    <a href="{{ child.href }}"{% if child.external %} target="_blank" rel="noopener noreferrer"{% endif %}>
                      {% if child.imageUrl != nil and child.imageUrl != '' %}<img src="{{ child.imageUrl }}" alt="">{% endif %}
                      <strong>{{ child.label }}</strong>
                      {% if child.description %}<span>{{ child.description }}</span>{% endif %}
                    </a>
                    {% if child.children.size > 0 %}
                      <ul class="mega-menu-children">
                        {% for leaf in child.children %}
                          <li><a href="{{ leaf.href }}"{% if leaf.external %} target="_blank" rel="noopener noreferrer"{% endif %}>{{ leaf.label }}</a></li>
                        {% endfor %}
                      </ul>
                    {% endif %}
                  </div>
                {% endfor %}
              </div>
            </section>
          {% endfor %}
          {% assign hasUngrouped = false %}
          {% for child in item.children %}
            {% assign childGroup = child.group | default: '' | strip %}
            {% if childGroup == '' %}{% assign hasUngrouped = true %}{% break %}{% endif %}
          {% endfor %}
          {% if hasUngrouped %}
            <div class="mega-menu-group-items mega-menu-ungrouped">
              {% for child in item.children %}
                {% assign childGroup = child.group | default: '' | strip %}
                {% unless childGroup == '' %}{% continue %}{% endunless %}
                <div class="mega-menu-card">
                  <a href="{{ child.href }}"{% if child.external %} target="_blank" rel="noopener noreferrer"{% endif %}>
                    {% if child.imageUrl != nil and child.imageUrl != '' %}<img src="{{ child.imageUrl }}" alt="">{% endif %}
                    <strong>{{ child.label }}</strong>
                    {% if child.description %}<span>{{ child.description }}</span>{% endif %}
                  </a>
                  {% if child.children.size > 0 %}
                    <ul class="mega-menu-children">
                      {% for leaf in child.children %}
                        <li><a href="{{ leaf.href }}"{% if leaf.external %} target="_blank" rel="noopener noreferrer"{% endif %}>{{ leaf.label }}</a></li>
                      {% endfor %}
                    </ul>
                  {% endif %}
                </div>
              {% endfor %}
            </div>
          {% endif %}
        </div>
        {% if item.megaMenu.promo %}
          <a class="mega-menu-promo" href="{{ item.megaMenu.promo.href | default: item.href }}">
            {% if item.megaMenu.promo.imageUrl %}<img src="{{ item.megaMenu.promo.imageUrl }}" alt="">{% endif %}
            <strong>{{ item.megaMenu.promo.title }}</strong>
            {% if item.megaMenu.promo.text %}<span>{{ item.megaMenu.promo.text }}</span>{% endif %}
            {% if item.megaMenu.promo.label %}<span>{{ item.megaMenu.promo.label }}</span>{% endif %}
          </a>
        {% endif %}
      </div>
    </div>
  {% elsif item.cta %}
    <a class="nav-cta" href="{{ item.href }}"{% if item.external %} target="_blank" rel="noopener noreferrer"{% endif %}>{{ item.label }}</a>
  {% else %}
    <a href="{{ item.href }}"{% if item.external %} target="_blank" rel="noopener noreferrer"{% endif %}>{{ item.label }}</a>
  {% endif %}
{% endfor %}
</nav>
```

You design the menu; the platform's `nav` behaviour makes it work. Under `.p60-js` show a panel
only when its group carries `is-open`, which the engine manages with hover intent (the pointer can
cross the gap between the toggle and the panel), keyboard and touch toggling, Escape, outside-click
and focus-away dismissal, and honest `aria-expanded`. Keep your `:hover` and `:focus-within` rules
scoped to `html:not(.p60-js)` so the no-JS render still opens on hover. Inside the open mobile panel
the same `is-open` lands on the group when its toggle is tapped. Declare `nav` in
`supports.behaviors`; the grammar is in [Motion and behaviour](/guides/motion-and-behaviour/#navigation-your-menu-made-robust).
The older `data-nav-drop` hooks keep working, but only cover taps inside the mobile panel. Do not
add fixed category descriptions or links that are not present in the navigation data.

The editor limits `megaMenu.columns` to 2 through 4 and the context limits navigation depth, so a
template can make responsive decisions without handling an unbounded tree. The template decides
whether a named group is one column or spans a row containing several cards. Do not repeat its
heading merely to fill each column.

### News, blogs and article categories

Articles and blog posts use the same article content model. "News", "Blog" and "Latest" can be
tenant-chosen navigation labels; they do not identify separate collections. Categories organise
those articles, while the navigation tree determines which category and article links a visitor sees.

In automatic navigation, published articles produce an entry using the tenant's articles label.
When at least two categories exist, its children are category archive links followed by "All
articles". With fewer categories it is a plain link. A tenant-curated header menu replaces this
automatic menu rather than merging with it. Curated article-topic links therefore stay where the
tenant placed them; templates must not append a second set of categories from article content.

The menu builder also offers a top-level "Latest articles in a topic (auto)" item. The platform
resolves its article links at render time; this automatic item is not currently available nested
inside another menu. A supplied tree can otherwise use both child levels, for example a News
parent, category children and article grandchildren. Render those relationships as supplied, using
their existing URLs. A matching `group` label is only a shared visual heading, not an instruction to
fetch articles, create a category or invent another hierarchy.

## Worship schedules

A template that declares `supports.worship: true` receives the optional `worship` object in its
layout. It contains tenant supplied labels, dates, a note and up to eight prayer or service times.
Always branch on the object so sites without a configured schedule do not receive empty chrome:

```liquid
{% if worship %}
  <aside class="worship-rail" aria-label="Worship times">
    <p>
      {{ worship.today }}
      {% if worship.todayAlt %}<span>{{ worship.todayAlt }}</span>{% endif %}
    </p>
    <div class="worship-scroll">
      <table>
        <thead>
          <tr>
            <td></td>
            {% for time in worship.times %}<th scope="col">{{ time.name }}</th>{% endfor %}
          </tr>
        </thead>
        <tbody>
          <tr>
            <th scope="row">{{ worship.beginsLabel }}</th>
            {% for time in worship.times %}<td>{{ time.begins }}</td>{% endfor %}
          </tr>
          <tr>
            <th scope="row">{{ worship.congregationLabel }}</th>
            {% for time in worship.times %}<td>{{ time.congregation }}</td>{% endfor %}
          </tr>
        </tbody>
      </table>
    </div>
    {% if worship.note %}
      {% if worship.href %}<a href="{{ worship.href }}">{{ worship.note }}</a>
      {% else %}<p>{{ worship.note }}</p>{% endif %}
    {% endif %}
  </aside>
{% endif %}
```

Use horizontal scrolling for the timetable on narrow screens. Do not calculate prayer times in the
template. The platform and tenant own those values.

The same object can also contain `worship.next`, structured `worship.jumah`, `worship.hijri` and
`worship.observances`. Branch on each value. Place `{% island 'next_prayer' %}` when you want the
platform-owned live countdown instead of a static next time.

## Locale and direction

Every layout receives `locale.code`, `locale.direction` and `locale.languages`. The platform sets
the document `lang` and `dir` attributes before your layout renders. Use logical CSS properties such
as `margin-inline-start`, and place `{% island 'language_switch' %}` when the design needs the
platform-owned language selector. Contract v1 currently supplies English, Welsh and Arabic.

## Identity is placed, never rebuilt

Put `{% island 'member_menu' %}` in your header's nav. It renders the branded Port60 ID sign-in
button for guests and the account pill for signed-in members, and renders **nothing** when the
tenant doesn't allow member sign-ups. The button's look and popup behaviour are platform-owned and
identical across every template (it's a trust anchor, like a "Sign in with Google" button, a
hand-rolled copy would erode it). Omitting it is a validator warning: sign-in becomes unreachable
on member-enabled tenants.

## Behaviour attributes

The platform tail script binds behaviours to documented attributes, emit them and the behaviour
arrives free, platform-maintained:

| Attribute | Behaviour |
| --- | --- |
| `data-p60-nav`, `data-p60-nav-item`, `data-p60-nav-toggle`, `data-p60-nav-menu`, `data-p60-nav-burger` | The `nav` behaviour: menus and the burger with hover intent, keyboard, touch, Escape and dismissal, state class `is-open` (declare `nav` in `supports.behaviors`) |
| `data-nav-burger` on a button + `id="site-nav"` on the nav | Legacy mobile burger open/close (an `.open` class toggle; links close the panel) |
| `data-consent-open` on any element | Opens the cookie preference centre |

The platform's base stylesheet also ships the chrome *mechanics* for the standard class names
(`.site-header`, `.site-nav`, `.nav-dropdown`, `.nav-burger` breakpoints…). Reusing them is
optional but saves you the responsive plumbing; your own class names are equally valid, then the
responsive behaviour is yours to style.

## Fonts

Declare webfont stylesheets in the manifest, the platform loads them in `<head>` with proper
preconnects (never a render-blocking CSS `@import`):

```json
{ "fonts": ["https://fonts.googleapis.com/css2?family=Inter:wght@400;600;800&display=swap"] }
```

Google Fonts `css2` URLs only (the schema enforces the pattern).

## Honesty applies to chrome too

The [truthfulness rule](/guides/sections-and-data/#the-truthfulness-rule) covers layouts: a footer
derives from `brand` and `nav`, it must not ship fabricated mission statements or invented
claims. The starter's footer is the worked example: brand name, tagline (only when present),
navigation links, legal links. Derive or omit.


━━ guides/motion-and-behaviour.md ━━


Templates never ship JavaScript. That rule is enforced by the validator: a `<script>` tag, an
inline event handler or a `javascript:` URL in any `.liquid` file fails validation before your
template goes anywhere. And yet a Port60 template can breathe: content that reveals as the
visitor scrolls, numbers that count up, heroes that rotate, FAQs that fold smoothly.

The mechanism is the **behaviour catalogue**. You author complete, honest, static markup and opt
into behaviour with a `data-p60-*` attribute; the platform engine finds the attribute after
render and attaches the JavaScript, the accessibility wiring and the reduced-motion handling.
You decide whether a hero is static or a carousel by writing markup. The full grammar for every
behaviour is in the [behaviour catalogue reference](/reference/behaviours/).

## Declare what you use

```json
"supports": {
  "behaviors": ["reveal", "carousel"]
}
```

The validator proves declaration and usage agree in both directions: declaring a behaviour whose
attributes never appear is an error, and using the attributes without declaring is too.

## The no-JS rule (read this twice)

The engine adds the class `p60-js` to the root element the moment its script runs. **Any CSS that
hides content before a behaviour shows it must be scoped under `.p60-js`.** A visitor without
JavaScript then sees your complete static page: all slides stacked, every reveal already visible.
Never hide content unconditionally and rely on a script to show it.

```css
/* ✓ pre-reveal state only exists when the engine is there to finish the story */
.p60-js .my-cards li { opacity: 0; transform: translateY(0.6rem); transition: opacity 480ms, transform 480ms; }
.p60-js .my-cards.is-revealed li { opacity: 1; transform: none; }

/* ✗ never this, a no-JS visitor gets a blank section */
.my-cards li { opacity: 0; }
```

## Reduced motion is shared work

The runtime honours `prefers-reduced-motion` on its side: reveals land instantly, counters show
the final number, progress bars render at their final width, carousels stop auto-advancing. The
transitions in your CSS are yours, so gate every motion rule on the visitor allowing it:

```css
@media (prefers-reduced-motion: no-preference) {
  .p60-js .my-cards li { transition: opacity 480ms, transform 480ms; }
}
```

## Reveal: the highest alive-per-effort ratio

```liquid
<ol class="my-cards" data-p60-reveal-group>
  {% for item in section.items %}<li>…</li>{% endfor %}
</ol>
```

The engine stamps `--p60-reveal-index` on each child and adds `is-revealed` when the group enters
the viewport. Your CSS keys the stagger off the index:

```css
.p60-js .my-cards li { transition-delay: calc(var(--p60-reveal-index, 0) * 90ms); }
```

Taste guidance: subtle rise (half a rem), under half a second, staggered under 100ms per item.
The Stripe feel comes from restraint, not amplitude. Reduced-motion visitors get everything
visible immediately; you never have to handle that yourself.

## Carousel: static or alive is your call

```liquid
<div class="my-hero-slides" data-p60-carousel="auto">
  {% for image in section.images %}
  <img data-p60-slide {% if forloop.first %}class="is-active"{% endif %} src="{{ image.imageUrl }}" alt="{{ image.alt }}">
  {% endfor %}
</div>
```

The engine manages `is-active`, injects a dots nav (`.p60-carousel-dots`, yours to style), wires
swipe and keyboard arrows, hides inactive slides from assistive tech, and only auto-advances when
you said `auto` and the visitor allows motion. With `auto` it also injects a rotation control
(`.p60-carousel-pause`, first in the carousel's tab order, `.p60-carousel-pause--stopped` while
stopped) and follows the WAI-ARIA carousel pattern: hovering pauses and leaving resumes, keyboard
focus entering the carousel stops rotation and leaving does not restart it, and the control is
the only way back. `is-paused` sits on your container while rotation is stopped, so you can style
that state. Style the control; the engine gives it only an accessible label. Class-based fade on
`is-active` is the simplest CSS pattern; the engine also stamps `--p60-carousel-index` for
track-translate designs. The starter template's standard hero is a worked example, and its vista framings show
the other route: the ready-made `hero_carousel` island. Both are legitimate; the island is
zero-effort; the behaviour is yours to design.

## Counters, progress, countdowns, accordions

- `data-p60-count` on the element that holds the figure, typed exactly as it should read: `£20`,
  `95%`, `1,200`, `2.5k`. Only the digits count up on first reveal; prefix, suffix, grouping and
  decimal places stay as typed and the final frame restores the text exactly. Nothing to format.
- `data-p60-progress` on a bar whose authored width is the target: it sweeps in on reveal.
- `data-p60-countdown data-p60-until="2026-09-01T18:00:00Z"`: static date text becomes a live
  remainder, `is-elapsed` lands on expiry.
- `data-p60-accordion` on a group of native `<details>`: exclusive-open plus smooth height, with
  working no-JS semantics for free.

## Structure and chrome: sticky, lightbox, tabs

- `data-p60-sticky-header` on your header gets `is-condensed` past a small scroll (add
  `auto-hide` for the hide-on-scroll-down pair). The engine only toggles classes; the look is
  yours.
- `data-p60-sticky-cta` on a bar adds `is-stuck` past the threshold. The bar must duplicate an
  action already on the page, which is why it is the one element allowed to hide unconditionally
  in CSS: a no-JS visitor loses nothing.
- `data-p60-lightbox` on a gallery whose `data-p60-lightbox-item` anchors point at the full
  images: the no-JS click is a plain navigation, the enhanced click is an injected overlay with
  keyboard, captions and a focus trap. Style the injected `.p60-lightbox` parts.
- `data-p60-tabs` with `data-p60-tab="key"` controls and `data-p60-panel="key"` panels: the
  engine wires the roles, arrows and roving focus, and hides inactive panels itself, so the no-JS
  render shows everything stacked with no CSS scoping needed.

## Reading, browsing and finding your place: reading progress, show more, scrollspy

- `data-p60-reading-progress` on a bar gets `--p60-reading-progress` (0 to 1) and a progressbar
  role kept honest by the engine. Draw the bar from the variable (`width: calc(var(--p60-reading-progress) * 100%)`).
  Name the element the reading covers with `data-p60-reading-target="article-body"`, or leave it
  off for the whole document. It keeps updating under reduced motion: position is information.
  The bar is pure enhancement, so it may be hidden unconditionally in CSS.
- `data-p60-show-more="6"` on a list whose entries carry `data-p60-show-more-item`, with a
  `data-p60-show-more-toggle` `<button>` inside the list (or pointing at it with `aria-controls`):
  the engine hides the items past the count with `hidden`, so no-JS visitors see the whole list,
  and keeps `aria-expanded` honest. Give the toggle a value (`data-p60-show-more-toggle="Show
  fewer"`) and its text swaps while expanded. A list with nothing to hide hides its toggle. Show
  the toggle only under `.p60-js`.
- `data-p60-scrollspy` on a menu of `href="#id"` links: the link for the section being read gets
  `is-current` and `aria-current="location"`. The value is the activation line in pixels from the
  top (default 96). Links keep navigating, nothing moves focus, and links whose target is not on
  the page are ignored.

## Lifecycle, and a limit to know about

Behaviours initialise once per page load, after render, and the runtime stamps each wired element
with `data-p60-bound-<behaviour>` so a second pass never binds twice. Pages are full documents:
there is no teardown step, because nothing swaps template markup in place, and the appearance
editor reloads its preview frame rather than patching it.

Reveal fires when about fifteen percent of an element is inside the viewport. An element at least
a viewport tall fires the moment any of it appears instead, so a long section can never stay
hidden waiting for a ratio it cannot reach. Reveal sections and cards all the same, and prefer
animating on `is-revealed` over hiding until it arrives: content that is visible by default and
moves when the class lands can never be lost.

Each behaviour initialises on its own. If one throws, the engine reports it on the console and
the others still wire, so a mistake in one part of a page never switches off the menu.

## Navigation: your menu, made robust

You design the menu: the markup, every pixel, the breakpoint at which it stacks. CSS `:hover` alone
cannot make it reliable, though: the pointer leaves the group in the gap between a toggle and its
panel and the menu vanishes on the way to a link, touch has no hover, and Escape and outside clicks
need script. The `nav` behaviour supplies exactly that interaction and nothing else. It injects no
markup and styles nothing; it toggles `is-open` and keeps `aria-expanded` honest.

```liquid
<button class="my-burger" data-p60-nav-burger aria-controls="site-nav" aria-expanded="false">Menu</button>
<nav id="site-nav" aria-label="Primary" data-p60-nav>
  <div class="my-group" data-p60-nav-item>
    <a href="{{ item.href }}" data-p60-nav-toggle aria-expanded="false">{{ item.label }}</a>
    <div class="my-panel" data-p60-nav-menu>…</div>
  </div>
</nav>
```

What the engine does on an item: hover-capable pointers get hover intent, a short delay before
opening and a grace period before closing, so crossing the gap never closes the panel. Keyboard,
touch and pen toggle on the control: Enter or a tap opens without navigating, again closes,
ArrowDown opens and focuses the first link. A mouse click on a parent link whose menu is already
open by hover navigates, as a link should. Escape closes and returns focus to the toggle. A click
outside, or focus moving to another element, closes. One item stays open per level; nested items
and several independent nav roots are fine. The burger toggles `is-open` on itself and on the panel
it names, closes on Escape with focus returned, on a real navigation inside the panel, on an outside
click, and when it disappears at a wider viewport.

Your CSS keys off `is-open` under `.p60-js`, and keeps hover for the no-JS render:

```css
.my-panel { display: none; }
.my-group.is-open > .my-panel,
html:not(.p60-js) .my-group:hover > .my-panel,
html:not(.p60-js) .my-group:focus-within > .my-panel { display: block; }

@media (max-width: 1080px) {
  .p60-js #site-nav:not(.is-open) { display: none; }
}
```

**Crowded headers.** When the nav's row wraps or overflows before your burger breakpoint, the
engine steps `is-fit-1`, `is-fit-2` and `is-fit-3` onto the nav root, re-measuring after each,
until the row fits, and clears them again when there is room. The platform's own sign-in pill
already uses the steps: the Port60 ID wordmark goes at step one and the text at step two, leaving
the person icon with its accessible label. Map the same classes to whatever you would rather give
up before collapsing into the burger: gaps, a smaller nav font, a shorter label.

```css
.my-nav.is-fit-2 { gap: .35rem .85rem; }
.my-nav.is-fit-3 { font-size: .88em; }
```

The older chrome hooks (`data-nav-burger`, `#site-nav`, `data-nav-drop`) keep working for templates
that have not moved yet; they only cover the burger and taps inside the mobile panel.

## In the local preview

`p60-template-kit dev` inlines the same runtime the platform ships, so every behaviour on this
page works locally, menus and burger built on the `nav` behaviour included. Only the older chrome
hooks stay inert in the preview; check those on a live site or a development version of your own
site.

## What belongs where

- **Your CSS** already owns hover effects, transitions, sticky positioning and scroll snap: no
  behaviour needed, no declaration, full freedom.
- **Behaviours** are for what genuinely needs JavaScript but carries no data: observers, timers,
  input handling on your own markup.
- **Islands** are for anything data-bearing or transactional. If it needs tenant data or takes
  money, it is an island: you place it rather than build it.


━━ guides/page-templates.md ━━


A Port60 template can own several independent presentation surfaces. Each surface is opt in and
the platform keeps responsibility for data fetching, transactions, identity and consent.

## The four presentation surfaces

| Manifest declaration | What the template owns | Required file |
| --- | --- | --- |
| `supports.layout: true` | Header, navigation and footer around every public page | `layout.liquid` |
| `supports.pages: ["home", "about"]` | The section based body of the named page | One renderer in `sections/` for each supported section type |
| `supports.pageTemplates: ["events", "course", "articles", "article"]` | A documented platform data view, with the route specific ownership described below | The corresponding file in `pages/` |
| Capability flags such as `supports.worship` | A documented optional context used by the declared surface | The renderer that consumes the context |

These declarations do not imply one another. A page template requires layout because its body is
inserted into the layout content slot. A template may own layout without owning any page template,
and it may support only some section based pages.

## Route ownership

| Route or view | Template owned body when declared | Platform owned body |
| --- | --- | --- |
| `/` | Home sections when `supports.pages` contains `home` | Built in home renderers |
| `/about` | About sections when `supports.pages` contains `about` | Built in about renderers |
| `/events` | `pages/events.liquid` when `supports.pageTemplates` contains `events` | Built in event listing |
| Event detail | Never | Detail, RSVP and ticket purchase |
| `/courses` | Never | Course listing |
| Course detail | `pages/course.liquid` when `supports.pageTemplates` contains `course` | Built in detail when not declared, with enrolment still handled by an island |
| `/articles` and `/articles/all` | `pages/articles.liquid` when declared | Built in editorial front page and archive |
| `/articles/{slug}` | `pages/article.liquid` when declared | Built in article detail when not declared; engagement and comments remain islands |
| Donations, services, members and prayer times | Never in contract v1 | Platform body inside the template layout |

The platform always owns the document head, consent controls, identity flows and transactional
behaviour. Your layout supplies the visible chrome around these bodies.

## Declaring a page template

```json
{ "supports": { "pageTemplates": ["events"] } }
```

Ship `pages/events.liquid` with that declaration. The platform fetches the data, renders your
markup with the documented context, then inserts the result into your layout. Without the
declaration, the platform body renders inside the same layout.

## The data is curated, not raw

A page template receives the page's documented context objects. See
[Render context](/reference/context/). It never receives internal API responses. The events
listing receives `events`, a stable view containing fields such as name, times, venue, mode,
availability and `priceFrom`. Article listings receive `articles` and `categories`. Article details
receive `article`, `categories` and `moreArticles`.

Two habits are important:

- Branch on nullable fields. `description`, `venueName`, `imageUrl` and `priceFrom` are null when
  absent.
- Use `detailHref` for links. Routing belongs to the platform, so templates must not construct
  detail URLs.

```liquid
{% for e in events %}
  <article>
    <h3><a href="{{ e.detailHref }}">{{ e.name }}</a></h3>
    <p>{{ e.startsAt | date: "%A %-d %B, %H:%M" }}{% if e.venueName %} · {{ e.venueName }}{% endif %}</p>
    {% if e.soldOut %}<span>Sold out</span>{% elsif e.priceFrom %}<span>from £{{ e.priceFrom }}</span>{% endif %}
  </article>
{% endfor %}
```

The conformance validator renders each page template against its fixture states. Publication
fails when a supported state cannot render.

## Listing and detail ownership

The four page templates deliberately own different views:

- `events` owns the event listing. Event details and every RSVP or ticket transaction remain
  platform owned.
- `course` owns a course detail presentation. The course listing remains platform owned, and the
  enrolment action is provided by the `course_enrol` island.
- `articles` owns the article front page and archive listings. Use the supplied `href` values for
  articles and category filters.
- `article` owns the article detail presentation. The sanitised `article.bodyHtml` is the only
  article field intended for `| raw`; place `article_engagement` and `article_comments` for the
  platform-owned interactive parts.

This is a display contract, not a route takeover. The manifest reference and generated context
reference are the source of truth as new views are introduced additively.


━━ guides/publishing.md ━━


Publishing has four stages:

```text
validate  →  package  →  upload to Studio  →  review
```

## Validate before packaging

From the template project created by `@port60/template-kit`, run:

```bash
npm run validate
npm run validate:json
```

The validator uses the same contract and dialect enforcement as the upload service. It checks:

1. `manifest.json` matches the [manifest schema](/reference/manifest/).
2. Every declared section exists in the [section catalogue](/reference/sections/) and has a
   renderer.
3. Every renderer parses under the restricted Liquid dialect.
4. Every renderer survives both minimal and sample fixtures.
5. Placed islands are declared and available in the [island registry](/reference/islands/).
6. `assets/theme.css` exists and is not empty.
7. A declared layout contains exactly one `{% content %}` slot and renders the layout fixture.
8. Declared worship and hero imagery support is proven by the rendered output.
9. Declared page templates exist and render their documented data fixtures.
10. Every `requiresCapabilities` entry is backed by a section, page template, island or context
    surface the artifact actually uses.

Errors block packaging and upload. Warnings do not block them, but should be understood before a
version is submitted.

## Create the uploadable zip

```bash
npm run package
```

Packaging validates again, then creates `dist/<name>-<version>.zip` (`dist/` is recreated on every run, so it only ever holds the current build). Only contract shaped files are
included: the manifest, layout, section and page renderers, and CSS assets. Project notes,
dependencies and source control files are excluded.

### What the zip contains

Exactly the contract-shaped set: `manifest.json`, `layout.liquid`, `sections/*.liquid`,
`pages/*.liquid` and `assets/*.css`, where `assets/theme.css` is the one stylesheet the platform
loads. Everything else beside your template stays on your machine: notes, dependencies, preview
content, design references, and any image, font or script file. From kit 0.14.3, `package` and
`publish` list what they left out, so a photograph dropped into `assets/` is a line in the output
rather than a broken URL on a live site. The upload refuses anything outside the set.

Photographs belong in the charity's media library, where the charity chooses them and holds them
(a starter media pack a template can offer is on the roadmap). Decorative textures and patterns
fit inside `theme.css` as data URIs within the stylesheet size limit.

## Upload through Studio

1. Sign in to your organisation's tenant admin.
2. Open **Studio** and select your template.
3. Open **Versions** and upload the zip.
4. Review the validation result and preview.
5. Submit the version for review.

The platform validates the uploaded bytes again. A successful local run is therefore useful before
upload, but the Studio result is the final gate for that exact zip.

## Publish from the terminal

The kit can also sign you in and publish without leaving your terminal. The Studio upload above still
works and is unchanged; this is the same result in one command, for when you would rather stay on the
command line or automate the loop.

Sign in once. This opens your browser to approve the device, then stores an offline token in
`~/.port60`. It finds your studio workspace automatically:

```bash
p60-template-kit login
```

Then, from your template project:

```bash
p60-template-kit publish
```

`publish` runs the same four stages as above in order: validate, package, upload to your studio and
submit the version for review. Add `--no-submit` to upload the version without submitting it, and
submit later from Studio. The manifest `name` must match a template you own (an unclaimed name
creates the template on first publish; a name owned by another studio is refused).

Two more sign-in commands:

- `p60-template-kit whoami`: who is signed in, and which studio workspace.
- `p60-template-kit logout`: sign this machine out and revoke its token.

By default the kit talks to Port60's hosted stack (`auth.port60.com` / `api.port60.com`). To point it
at a local or self-hosted environment, set `P60_AUTH_BASE`, `P60_API_BASE`, `P60_REALM` and
`P60_CLIENT_ID` before running `login`.

## Publish from GitHub Actions

Your repository can publish on its own, the way a release pipeline would: push a version tag, the
workflow validates and uploads, and the template or its new version arrives in the review queue
exactly as an upload from Studio does. Review still decides; nothing is approved automatically.

There is no token to create, store or rotate. GitHub signs every workflow run with a short-lived OIDC
token, and the platform verifies that signature and checks it against a repository you trusted in
Studio. Remove the trust and publishing stops from the very next run.

### 1. Trust the repository in Studio

In Studio choose **Automate** (next to the upload button), paste the repository as `owner/name` or its
GitHub URL, and add it. That is the whole registration, done once per repository for the whole studio,
the way a trust policy names a repository. From then on the workflow can do what you can from a
terminal: create a template from its manifest or add a version to one you own.

Behind the one field, the platform checks GitHub's permanent numeric id for the repository on every
run, never the name, so a renamed or re-created repository never inherits the trust. For a public
repository the id is looked up when you add it; for a private one it is learned from the first
workflow run and shown in Studio as verified from then on. Any branch or tag may publish; choose what
triggers the workflow in the workflow file itself.

### 2. Add the workflow

Save this as `.github/workflows/publish.yml`. The `id-token` permission is what lets GitHub sign the
run for you; no secret is needed.

```yaml
name: Publish template
on:
  push:
    tags: ['v*']
permissions:
  id-token: write
  contents: read
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npx @port60/template-kit publish --ci
```

### 3. Release by tag

Bump `version` in `manifest.json`, describe the change in `changelog`, then tag and push:

```bash
git tag v1.2.0
git push --tags
```

The run validates the template locally, packages it, and posts it with the run's own token. The job
log shows the validation report and whether the version was submitted for review. Add `--no-submit`
to upload without submitting.

What CI can and cannot do: it can create a template from the manifest `name` (the first publish
claims it, label and description included) and add versions to any template the studio owns. It cannot
publish from an untrusted repository, take a name another studio owns, or run more than a modest number
of times a day per repository. Every refusal is explained in the job log and shown under Automate in
Studio.

## Immutable versions

A reviewed version cannot be overwritten. For every change:

1. Increase `version` in `manifest.json` using semantic versioning.
2. Describe the release in `changelog`.
3. Validate and package again.
4. Upload the new zip as a new version.

Sites pinned to an older version continue to render that version until an update is deliberately
applied. This protects live sites from unexpected design changes.

## Use a development version with real content

The local and Studio previews use safe contract fixtures and non-interactive island skeletons. To
check your own site with real navigation, content lengths, imagery, worship data and enabled
features, upload a version such as `1.2.0-dev.1`. Once it validates, choose **Use on this site** in
Studio.

A development version is deliberately restricted:

- only the template owner's own tenant can activate it;
- its artifact is read from quarantine through an internal tenant-bound route;
- it cannot be submitted for review, promoted or listed in the catalogue;
- the site pin is explicit and responses are served with no-store caching.

Increase the final number for each development build. When the design is ready, upload a stable
version such as `1.2.0` and submit that version for review.


━━ guides/sections-and-data.md ━━


Charities don't edit pages, they compose them from **sections**. Each page holds an ordered list
of sections drawn from a [closed catalogue](/reference/sections/); each section carries typed
content the charity authored in their admin. Your template's job is to render whatever subset of
that they actually wrote.

## The render context

A section renderer receives exactly two things (see [Render context](/reference/context/)):

- **`section`**, the typed content of the section being rendered. Its shape is the section
  type's fields; consult the [catalogue](/reference/sections/) per type.
- **`brand`**, `brand.name` and `brand.tagline`, the charity's identity.

That's the whole surface. No API access, no other tenants, no secrets, and the context only ever
**grows** within a contract major, so new variables can appear but existing ones never vanish or
change shape.

## Escape-by-default

Every `{{ output }}` is HTML-escaped. The single opt-out is `| raw`, and the only fields you
should ever pass through it are the catalogue's `richtext` fields (like `hero.bodyHtml`), the
platform sanitises those server-side on save, before a template ever sees them.

```liquid
<h1>{{ section.title }}</h1>          <!-- escaped: always safe -->
{{ section.bodyHtml | raw }}          <!-- sanitised richtext: the one legitimate raw -->
{{ section.title | raw }}             <!-- NEVER: plain text doesn't get raw -->
```

## Sparse data is normal, degrade, don't decorate

Every section is independently omittable, and inside a section most fields are optional. The
validator renders your template against each type's **minimal fixture**, the least a charity can
author, and your renderer must produce something sensible.

The pattern: wrap optional output in a condition, or give it an honest default.

```liquid
{% if section.eyebrow %}<p class="lq-kicker">{{ section.eyebrow }}</p>{% endif %}
<h2>{{ section.heading | default: "What guides us" }}</h2>
```

## The truthfulness rule

**Derive or omit, never fabricate.** A template must not invent claims on a charity's behalf:
no placeholder impact numbers ("10,000 meals served"), no fake testimonials, no invented history.
If the charity didn't author it and the platform can't derive it from real data, the space
doesn't render. A generic default like a heading ("What guides us") is fine; a factual-sounding
claim is not. This is a publish-gate policy, not just style guidance, template review checks
for it.

## Field kinds

| Kind | What it is | How to render |
| --- | --- | --- |
| `text` | Plain text | `{{ section.field }}` (escaped) |
| `richtext` | Sanitised HTML from the platform editor | `{{ section.field | raw }}` |
| `url` | A link, scheme-guarded on save | `href="{{ section.field }}"` |
| `icon` | An emoji, or a Lucide icon name such as `heart-handshake` | `{{ item.icon }}`. When the name is a Lucide icon the platform also supplies `item.iconSvg` (platform-generated markup, safe for `raw`): `{% if item.iconSvg %}{{ item.iconSvg | raw }}{% else %}{{ item.icon }}{% endif %}`. The local preview resolves `iconSvg` the same way |
| `items` | A list of objects (see the type's `itemFields`) | `{% for item in section.items %}` |

## Platform-data sections

These sections have no author-editable fields in the admin, their content is the tenant's live
data, provided to your renderer:

| Section | Context | What it is |
| --- | --- | --- |
| `events` | `events[]` | Upcoming **ticketed** events (curated event shape, `name`, `startsAt`, `venueName`, `priceFrom`, `soldOut`, `detailHref`…) |
| `whatsOn` | `infoEvents[]` | Info events (special days, no sign-up), same shape |
| `articles` | `latestArticles[]` | Newest published articles (up to 6): `title`, `href`, `excerpt`, `imageUrl`, `publishedAt`, `readingMinutes`, `categories` |
| `campaigns` | `campaigns[]`, `campaignsLabel` | Live campaigns in display order (`title`, `href`, `summary`, `imageUrl`) plus the tenant's chosen section label, always link via `href` |
| `appealGrid`, `emergency` | `causes[]` | Active appeals with target, raised amount, progress percentage and the platform donation `href` |
| `programmes` | `services[]` | Published services with summary, image and platform-provided `href` |
| `resources` | `resources[]` | Public document links only; private media and storage metadata are excluded |
| `locations` | `locations[]` | Public venues with safe directions links; provider references and admin notes are excluded |

Render them your way, or place the section's default island and ignore the context entirely, see
[islands](/guides/islands/). Empty lists must render nothing: derive or omit.

Collection drops are deliberately curated projections rather than raw service responses. Use their
supplied `href` or `url` fields. Do not construct storage, payment, event or service routes inside a
template.


━━ guides/template-kit.md ━━


`@port60/template-kit` is the local half of the platform: the **same** contract, dialect,
validator and preview renderer the engine runs in production, packaged as a CLI. If it validates
on your machine, it validates at upload, the two cannot drift.

## Commands

```bash
p60-template-kit create <dir>
```
A working template from the platform starter: renders immediately, validates clean, and comes
briefed for AI agents (`AGENTS.md`/`CLAUDE.md`) with npm scripts wired. The folder name becomes
the template name and the label derives from it; `--name`/`--label` override the identity when it
should differ from the folder.

```bash
p60-template-kit dev [dir] [--port 4400]
```
Live preview over the contract's **kind fixtures** with realistic, non-interactive island
skeletons for worship rails, events, donation widgets and other platform features. The skeletons
use each island's stable styling API, so theme CSS can be judged without a platform account.
Files are re-read per request, so refresh is the reload; validation re-runs in the terminal on
save.

What the preview is, precisely, so nothing surprises you at upload:

- **Two compositions, as the platform composes them.** When your manifest declares
  `compositions`, `/` and `/about` render your composition for that page, in your order, with the
  `optional` entries left out, against the catalogue's sample content. Without one, `/` renders the
  sections you declare that the catalogue assigns to the home page and `/about` the ones it assigns
  to about, each in manifest order. A template that does not declare `about` in `supports.pages`
  sees the platform's own About body there, as it would live. Your own compositions and copy come
  from the `pages` block of `preview-content.json` (below).
- **Routed platform surfaces.** The bar at the top links to `/about`, `/events`, `/services`,
  `/donate`, `/articles`, `/campaigns` and `/courses`, each wearing your chrome and, where you
  ship one, your page template.
- **What leads is switchable.** The bar's **Leads with** links (or `?focus=donate|volunteer|none`
  on any URL) set the site focus: the `primary_action_widget` island in your hero becomes the
  donation widget, the volunteer sign-up, or nothing, and `site.focus`, `site.actions`, the header
  button and the hero's `section.action` follow. The studio renders the default, giving.
- **Behaviours run.** The platform's behaviour runtime is inlined, so reveals, carousels,
  accordions, tabs, and menus built on the `nav` behaviour work as in production. Only the older
  chrome hooks (`data-nav-burger`, `data-nav-drop`) stay inert in the preview; they work on a live
  site and on a development version of your own site.
- **Knobs and Looks switch.** Knobs render at their defaults; the bar's **Looks** links (or
  `?look=Name` on any URL) apply one of your `manifest.looks`, and `?p60s-<key>=<value>` sets a
  single knob, exactly as Appearance does for a charity. Values are checked the way production
  checks them: a select value outside the knob's options and an unknown font family fall back to
  the default.
- **Webfonts load.** The dev preview loads your `manifest.fonts` and your font knobs' families
  from the platform's provider mirror, so type is judged for real. The studio review render stays
  network-dead and shows the fallback stacks.
- **Icons resolve.** `item.iconSvg` is supplied for a Lucide icon name, as live; render
  `item.icon` as the fallback for anything else.

Photographic fixtures: set `P60_FIXTURE_IMAGES=https://your-image-host` before `dev` and the
built-in fixture image references load `<kind>-<seed>.jpg` from that one origin instead of the
sealed inline art; the preview admits exactly that host. Your own photographs go in a `preview/`
folder beside the template: the dev server serves them at `/preview/<file>` (images only), so a
`preview-content.json` can point `imageUrl` values at `/preview/hero.jpg`. Unset and without the
folder, the preview stays fully network-dead. Images you place next to the template are never
packaged, see [what the zip contains](/guides/publishing/#what-the-zip-contains).

```bash
p60-template-kit validate [dir] [--json]
```
The conformance checks the platform runs at upload, manifest schema, dialect, fixture renders,
island discipline, the two-way `supports` honesty, render budgets. `--json` emits
`{ok, errors, warnings, manifest, provenSupports}`: **supports as an output**, a clean pass is
what turns your declarations into proven capability, and it's the feedback loop AI agents iterate
against.

```bash
p60-template-kit package [dir]
```
Validates, then produces `dist/<name>-<version>.zip` containing exactly the contract-shaped file set, the artifact your studio's upload accepts as-is. `dist/` is wiped and recreated on every run and is gitignored by the scaffold.

```bash
p60-template-kit model [--json]
```
The [content model](/reference/content-model/) in hand: every `site.content.*` collection with its
bound, onward link and fields. `--json` emits the registry verbatim for agents. The dev server
renders the same reference with live example data at `/model`.

```bash
p60-template-kit content [dir] [--out file]
p60-template-kit dev [dir] --content my-org.json
```
Bring your own content and imagery. `content` EJECTS every collection plus the brand, the menu
(`nav`) and the home and about compositions (`pages`, each declared section with its sample copy),
fully populated with the canonical organisation, as one editable JSON file; edit the copy in
place, reorder or drop sections, swap `imageUrl` values for your own hosted images or a `preview/`
folder, and `dev --content` renders your data on every surface; the preview admits exactly the
image hosts your file names and nothing else. The shape stays the platform's (schema-checked on
every read: a section type must be in the catalogue and its fields must be ones the section
declares), the data becomes yours; the file is hot-reloaded, never packaged, and refused at upload.

```bash
p60-template-kit login
p60-template-kit whoami
p60-template-kit logout
```
Sign in from the terminal. `login` runs the Keycloak device flow (the browser approves), stores an
offline token in `~/.port60`, and discovers your studio workspace automatically; `whoami` shows who
is signed in and which workspace; `logout` signs this machine out and revokes its token. By default
the kit talks to Port60's hosted stack; set `P60_AUTH_BASE` / `P60_API_BASE` / `P60_REALM` /
`P60_CLIENT_ID` to point it at a local or self-hosted environment.

```bash
p60-template-kit publish [dir] [--no-submit]
```
Validate, package, upload to your studio and submit the version for review, in one command. The
dashboard upload in [Publishing](/guides/publishing/#publish-from-the-terminal) still works, this is
the same result from the terminal (`--no-submit` uploads without submitting).

```bash
p60-template-kit publish [dir] --ci
```
The same from a GitHub Actions workflow: no login, the run's own OIDC token is the credential, and
the repository must be trusted in Studio (once, for the whole studio). See
[Publish from GitHub Actions](/guides/publishing/#publish-from-github-actions) for the workflow.

## Staying current

```bash
npx @port60/template-kit@latest upgrade
```

Your scaffold pins the kit as a devDependency and every npm script runs that local copy, so the
whole enforcement surface, contract, content model, validator, fixtures, preview, behaviour
runtime, upgrades with one install. `upgrade` does it properly: it installs the latest kit into
your pin, regenerates `AGENTS.md`/`CLAUDE.md` (they are the kit's generated briefing, stale the
moment the contract moves, your own notes belong in `README.md`), prints the kit, contract and
content-model versions now in force, and re-runs the full conformance check so you immediately
see what, if anything, the newer contract asks of your template.

Your template sources are never touched, and the contract is add-only within a major, an
upgrade can inform you, it cannot break you. New collections, fields and behaviours simply become
available; anything the validator newly asks for appears in the report, not in production. See
[Versioning](/guides/versioning/) for why published versions stay safe regardless.

## From zip to a charity's site

1. **Upload** the zip in your studio (tenant admin → Studio → your template → Versions), the
   platform re-runs validation and stores the artifact in quarantine.
2. **Submit** the validated version for review.
3. A Port60 reviewer approves; the artifact is promoted to the live catalogue, privately
   delivered to your commissioning charity or listed on the marketplace at your price.

Versions are immutable once reviewed; ship fixes as a new semver. The name in your manifest is
your claimed identity, it must match the template you created in the studio.


━━ guides/theming.md ━━


A template's look lives in one file: `assets/theme.css`. It layers over the **platform base
stylesheet**, which owns the mechanics, layout plumbing, form controls, island internals, and
declares a [contract of CSS custom properties](/reference/tokens/) for everything brandable.

Your stylesheet is applied after the platform base, on the live site and in every preview, so
when a rule of yours and a platform rule have equal specificity, yours wins. Token overrides still
use the doubled `:root:root` selector below, because the base declares them on `:root` and you
want to win by specificity as well as by order.

## Layer 1: override the tokens

The fastest way to a distinct look is re-pointing the palette. Use doubled `:root:root`
specificity so your values win over the base:

```css
:root:root {
  --bg: #0e1614;
  --surface: #16231f;
  --ink: #eef6f2;
  --muted: #93a8a0;
  --primary: #2dd4a7;
  --accent: #f2b23e;
  --radius: 10px;
}
```

Because islands and platform chrome consume the same tokens, this restyles *everything*, the donation widget's tabs, buttons and cards follow your palette with zero island-specific CSS.

Tokens are **additive-only within a contract major**: new ones can appear (with working defaults),
existing ones are never removed or repurposed. Styles written against them don't rot.

## Layer 2: style your own markup

Your section renderers emit your own class names, namespace them (the starter uses `lq-`) so they
can never collide with platform classes. Typography, spacing, section composition: all yours.

```css
.lq-kicker {
  display: inline-block;
  border: 1px solid var(--line-strong);
  color: var(--primary);
  letter-spacing: 0.14em;
  text-transform: uppercase;
}
```

### The content container is shared, never namespace it

There is one deliberate exception to "namespace everything": the **content column**. Platform pages
(donate, services, events, campaigns, the members area) render inside `.container`, the shared content
**seam**, with `.full` for edge-to-edge. Your own layout and sections must use the *same* `.container`,
so your chrome and every platform page sit in one column. Set its width with the `--container` token and
its gutter by styling `.container`:

```css
:root:root { --container: min(1200px, 92vw); } /* your content width */
.container  { padding-inline: 1.5rem; }         /* your gutter  */
```

**Never build your own content container.** A namespaced class sized off `--container`, e.g.
`.mytheme-container { max-width: var(--container) }`, is a *parallel* container: platform pages stay on
`.container` and drift from your sections. **The publish validator rejects it before review**, naming the
offending selector and telling you to style `.container` instead. For a full-width bar with a centred
inner, compose the seam (put `.container` on the inner element, keep your class only for the flourish).
Full detail: [Layout & the content seam](/reference/layout/).

## Layer 3 (optional): island styling APIs

Where the token layer isn't enough, each island publishes stable class names you may target, see
[Placing islands](/guides/islands/#styling-an-island). Anything not in an island's published API
is internal; don't reach for it.

## Template settings: your own knobs

Your manifest may declare **settings**, theming knobs the charity edits in their admin
(Appearance) and the get-started flow:

```json
{
  "settings": {
    "schema": [
      { "key": "scheme", "kind": "select", "label": "Colour scheme",
        "options": ["Midnight", "Daylight"], "default": "Midnight" },
      { "key": "accent", "kind": "color", "label": "Accent colour", "default": "#f2b23e" },
      { "key": "roundedCorners", "kind": "toggle", "label": "Rounded corners", "default": true }
    ]
  }
}
```

Three kinds: `color`, `select`, `toggle`. The charity edits them in Appearance; their choices are
stamped onto the public page for your CSS to key off:

- **`select` / `toggle`** → a `data-p60s-{key}="{value}"` attribute on `<body>`:

  ```css
  body[data-p60s-scheme="Ink"] {
    --bg: #14110d;
    --ink: #f3ede2;
  }
  ```

- **`color`** → a `--p60s-{key}` CSS variable on `:root`:

  ```css
  .ed-btn-ink { background: var(--p60s-accent, var(--accent)); }
  ```

Always style the **default** scheme unconditionally and treat the attributes as overrides, a
tenant who never opens the options must get your canonical look. Keep knobs few and opinionated:
charities want "Paper or Ink", not thirty sliders.

## Fonts

Fonts arrive two ways, both loaded by the platform in `<head>` from Bunny Fonts, the privacy-first
mirror of the Google catalogue. Never `@import` a stylesheet from `theme.css`: the file is inlined
into the page and the preview is network-dead, so an import fails silently.

- **Font knobs.** Declare a `font` knob in `manifest.settings.schema` with the default family and
  the weights your type system uses. The charity picks a family from the platform catalogue; the
  platform loads one stylesheet at your weights and sets `--p60s-<key>` to the family plus an
  honest fallback stack. Use that variable wherever you set `font-family`.
- **`manifest.fonts`.** Google Fonts css2 URLs for families you fix rather than offer as knobs.
  The platform rewrites them to the mirror and loads them with preconnects.

The local `dev` preview loads both from the mirror, so type is judged for real; the studio review
render stays network-dead and shows the fallback stacks.

## Hero photographs & image treatment

Charities upload their own hero photographs (`homeHero.images`, phone photos, mixed lighting,
any colour cast). **Never place them raw.** A raw photo fights your palette; the professional
move is a *treatment layer* built from your own variables, so every upload is toned into the
template, and changing scheme re-tones every photo for free:

```css
/* A scrim made of the palette itself, not a hard-coded black wash. */
.my-hero--photo::before {
  content: '';
  position: absolute;
  inset: 0;
  background: linear-gradient(
    180deg,
    color-mix(in srgb, var(--bg) 65%, transparent) 0%,
    color-mix(in srgb, var(--bg) 35%, transparent) 50%,
    color-mix(in srgb, var(--bg-tint) 70%, transparent) 100%
  );
}
```

Other tools in the same spirit: `background-blend-mode: multiply | soft-light` against a palette
colour (the duotone/tint look), and gentle `filter: saturate(.85) contrast(.95)` to stop uploads
shouting. The starter's `.lq-homehero` is the reference implementation.

The rules, enforced at validation when you declare `supports.heroImagery`:

- **One photo** must render directly (`section.images.first.imageUrl`), as a treated backdrop,
  a split layout, whatever your design language says.
- **Two or more**: place the platform's `hero_carousel` island; it owns the motion
  (auto-advance, swipe, reduced-motion) and every slide carries an empty `.hero-slide-scrim`
  element for your treatment; style it exactly like your single-photo scrim.
- **No photos** means your *designed* no-photo state, a gradient, a colour field, typography.
  Never a placeholder image (and artifacts can't ship binaries anyway).
- Don't declare `supports.heroImagery` if your hero ignores the photos, the validator checks
  behaviourally, and the choosers warn charities that their photos won't show.

Photographs also carry the charity's **framing** choice (`homeHero.photoFraming`), honour both:
`fill` (default) covers your designed hero shape, with per-photo `focus` picking the surviving
slice; `whole` is the **vista**, size the hero toward the photo's own aspect (an in-flow
`<img>` with `width: 100%; height: auto; max-height: ~74vh` is the trick; no stored dimensions
needed) so a wide landscape stays entirely visible, and stack or overlay your copy accordingly.

Declare your hero's ideal in the manifest, `imagery.hero: { idealAspect, minWidth, note }`, and the charity's editor measures their actual upload against it, advising in your words
("much wider than this template's ideal, show the whole photo keeps the full scene"). Entity
images (events, courses, articles) are platform-scoped instead: they render on several surfaces
at once, so their envelopes live in the contract's `imagery.json`, not per-template.


━━ guides/versioning.md ━━


The versioning model exists to make one promise credible: **the platform can upgrade itself, dependencies, security patches, new features, without breaking a template that hasn't changed.**

## Your version: immutable semver

Every published `{name}/{version}` is frozen forever. Tenants render the exact version they're
pinned to; caches (engine memory, CDN) never need invalidating because the content under a
version can't change. Ship fixes as new versions:

- **Patch** (`1.0.1`), visual fixes, CSS tweaks, no new content requirements.
- **Minor** (`1.1.0`), new supported sections/pages, new settings.
- **Major** (`2.0.0`), a redesign, or adopting a new contract major.

## The contract major: `format`

Your manifest's `format` (`port60-liquid@1`) names the **contract major** you're written against, the dialect whitelist, section catalogue, island registry, CSS tokens, and render context as a
set. Within a major, the contract is **additive-only**:

- Section types and fields are added, never removed or re-shaped.
- Context variables are added, never removed.
- CSS tokens are added (with working defaults), never removed or repurposed.
- The dialect only ever widens.
- Island styling APIs are stable; island internals are explicitly not.

So a template written against `port60-liquid@1` today still validates and renders against every
future platform release that supports major 1, that's the Android-style compatibility promise,
and it's enforceable because the contract is machine-readable.

## How the platform holds its side

Before any platform release that touches the template system goes live:

1. **Contract-diff gate**, CI diffs the contract files against the previous release and fails
   anything non-additive within a supported major.
2. **Template regression fleet**, every published template@version is re-rendered against its
   fixtures and golden output; a rendering difference blocks the release, not your template.
3. **Multi-major engine**: when `port60-liquid@2` arrives, the engine keeps rendering major 1
   artifacts side-by-side. A new major is an *invitation* to upgrade, never an eviction.

(These gates are commissioning as the platform approaches go-live; the contract they enforce is
already the one you're building against.)

## What you should still do

- Declare honestly: `supports` should list exactly what you render, islands included.
- Don't reach past the contract, undocumented class names, un-listed context variables, and
  island internals are the only ways a platform upgrade *can* surprise you.
- Watch `planned` islands you declared: they begin rendering when they ship, so leave sensible
  space around them.

## The gates are on

Since 2026-08-09 the Android-model promise is mechanically enforced on every platform change:

- **The contract freeze**, contract v1 may only grow. A frozen lock captures every surface your
  template may depend on (dialect tags/filters, section types, island styling APIs, context
  variables and their scopes, tokens, fonts, manifest rules); any removal or narrowing fails the
  platform's own test suite and CI. Breaking changes require a new format major, never a quiet
  edit to `@1`.
- **The regression fleet**, every published template@version is re-rendered against the contract
  fixtures on every platform change and compared to stored goldens. If a platform change would
  alter your template's output, the platform's release fails, not your template.
- **Multi-major engine**, when `port60-liquid@2` ships, `@1` artifacts keep rendering through
  their own contract set, with a published deprecation window before any retirement.

Your obligations still end at conformance; keeping your template rendering is our job.

## Keeping your toolchain current

Published versions never need you to act; the platform renders them forever. Your *working copy*
is different: `npx @port60/template-kit@latest upgrade` moves an existing template onto the
latest kit and contract, regenerates the agent briefing, and reports what (if anything) the new
contract asks of you. See [the template kit](/guides/template-kit/#staying-current).


━━━ GENERATED REFERENCE (from the enforced contract, cannot drift) ━━━

━━ reference/behaviours.md ━━


:::note[Generated reference]
This page is generated from the machine-readable contract the platform engine enforces (`contract/v1`). It cannot drift from production behaviour.
:::


The behaviour catalogue: engine-attached JavaScript a template opts into with data attributes on its own markup. Templates never ship code; they author complete static markup and declare behaviours in supports.behaviors. The engine adds the p60-js class to the root element when its script runs; any CSS that hides pre-behaviour content MUST be scoped under .p60-js so the no-JS render stays complete. All behaviours honour prefers-reduced-motion centrally. State classes are toggled by the engine; their appearance is entirely the template's CSS. Each entry's primaryAttribute is the opt-in attribute: the validator derives its declaration checks from it and the reference documents it, so the catalogue is the single source.


| Behaviour | Status | Label |
| --- | --- | --- |
| `reveal` | ✅ available | Reveal on scroll |
| `counter` | ✅ available | Animated counter |
| `progress` | ✅ available | Progress bar sweep |
| `countdown` | ✅ available | Countdown |
| `accordion` | ✅ available | Accordion |
| `stickyHeader` | ✅ available | Sticky header condense |
| `stickyCta` | ✅ available | Sticky call-to-action bar |
| `lightbox` | ✅ available | Lightbox |
| `tabs` | ✅ available | Tabs |
| `carousel` | ✅ available | Carousel |
| `readingProgress` | ✅ available | Reading progress |
| `showMore` | ✅ available | Show more and less |
| `scrollspy` | ✅ available | Scrollspy |
| `nav` | ✅ available | Navigation |

## `reveal`

**Reveal on scroll**

Adds is-revealed when the element first enters the viewport; the template's CSS does the actual motion. data-p60-reveal-group on a container staggers its children by stamping --p60-reveal-index on each (use it in a transition-delay calc). Reduced motion: is-revealed applies immediately on load.


Opt in with `data-p60-reveal` on your own markup and declare `reveal` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-reveal` | optional variant name for the CSS to key on |
| `data-p60-reveal-group` | none; staggers direct children |

**State classes** (engine-toggled; the appearance is your CSS): `is-revealed`

**CSS variables the engine stamps**: `--p60-reveal-index`

## `counter`

**Animated counter**

Counts the element's figure up from zero when first revealed. The static text IS the final value, typed exactly as it should read ("£20", "95%", "1,200", "2.5k"): the engine animates only the first run of digits and keeps the prefix, suffix, grouping and decimal places as typed, restoring the exact text on the last frame. A numeric attribute value (legacy) overrides the target; the text still sets the format. Reduced motion: the final figure shows immediately.


Opt in with `data-p60-count` on your own markup and declare `counter` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-count` | none: the element's own text is the target and the format; or a numeric target (legacy) |
| `data-p60-count-duration` | optional ms, capped at 4000 (default 1200) |

**State classes** (engine-toggled; the appearance is your CSS): `is-revealed`

## `progress`

**Progress bar sweep**

Animates the marked element's width from zero to its authored width when first revealed. The authored width (inline style or CSS) is the target and the no-JS render. Reduced motion: the authored width stands untouched.


Opt in with `data-p60-progress` on your own markup and declare `progress` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-progress` | none; the element's own width is the target |

**State classes** (engine-toggled; the appearance is your CSS): `is-revealed`

## `countdown`

**Countdown**

Replaces the element's content with a live compact remainder to data-p60-until ("3d 12h 45m"). The static content is the authored date text (the no-JS render). On expiry the engine adds is-elapsed and swaps to data-p60-elapsed-text when provided. Countdowns keep ticking under reduced motion: they are information, not decoration. v1 unit labels are compact and language-neutral (d/h/m/s).


Opt in with `data-p60-countdown` on your own markup and declare `countdown` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-countdown` | segments: dhms, dhm (default) or hm |
| `data-p60-until` | ISO-8601 instant, required |
| `data-p60-elapsed-text` | optional text shown once elapsed |

**State classes** (engine-toggled; the appearance is your CSS): `is-elapsed`

## `accordion`

**Accordion**

On a container of native details elements: exclusive-open (opening one closes the others) plus smooth height animation. data-p60-accordion="multi" keeps independent opening. Built on details/summary so the no-JS render is already functional and semantics are free. Reduced motion: no height animation, instant toggle.


Opt in with `data-p60-accordion` on your own markup and declare `accordion` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-accordion` | none for exclusive-open; "multi" for independent |

**State classes** (engine-toggled; the appearance is your CSS): `is-open`

## `stickyHeader`

**Sticky header condense**

State classes for scroll-aware headers: past a small threshold the engine adds is-condensed; with the "auto-hide" value, scrolling down past 160px adds is-hidden and scrolling up removes it. The engine only ever toggles classes (rAF-throttled), what condensing or hiding looks like, and whether it animates, is entirely the template's CSS (gate transitions behind prefers-reduced-motion yourself; the classes always apply because a condensed header is layout, not decoration).


Opt in with `data-p60-sticky-header` on your own markup and declare `stickyHeader` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-sticky-header` | none for condense-only; "auto-hide" adds the hide-on-scroll-down pair |

**State classes** (engine-toggled; the appearance is your CSS): `is-condensed`, `is-hidden`

## `stickyCta`

**Sticky call-to-action bar**

Adds is-stuck once the visitor scrolls past the threshold (the attribute value in px, default 480) and removes it above. The bar should DUPLICATE an action that already exists in the page (a donate button, a ticket link); because of that, this is the one behaviour whose element may be hidden unconditionally in CSS rather than .p60-js-scoped: a no-JS visitor loses nothing; the original action is still on the page.


Opt in with `data-p60-sticky-cta` on your own markup and declare `stickyCta` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-sticky-cta` | optional scroll threshold in px (default 480) |

**State classes** (engine-toggled; the appearance is your CSS): `is-stuck`

## `lightbox`

**Lightbox**

On a group container: each data-p60-lightbox-item is an anchor whose href is the full image (the no-JS render simply navigates to it, already functional). The engine intercepts the click and opens an injected overlay (.p60-lightbox) with the image, a caption from data-p60-caption or the thumbnail's alt, a close button, backdrop and Escape close, arrow-key prev/next within the group, and a focus trap. Reduced motion: no transition on the overlay (the engine sets none; style the steady state).


Opt in with `data-p60-lightbox` on your own markup and declare `lightbox` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-lightbox` | none; the group container |
| `data-p60-lightbox-item` | none; on each anchor to a full image |
| `data-p60-caption` | optional caption text on an item |

**State classes** (engine-toggled; the appearance is your CSS): `is-open`

**Injected markup you may style**: `.p60-lightbox`, `.p60-lightbox-img`, `.p60-lightbox-caption`, `.p60-lightbox-close`, `.p60-lightbox-prev`, `.p60-lightbox-next`

## `tabs`

**Tabs**

data-p60-tab="key" on each tab control and data-p60-panel="key" on each panel, inside a data-p60-tabs container. The engine wires the tablist/tab/tabpanel roles, aria-selected, roving tabindex, arrow/Home/End keys, toggles is-active on the active pair and hides inactive panels with the hidden attribute, so the no-JS render shows every panel stacked and complete, with no CSS scoping needed. The first tab (or the one authored with is-active) starts active.


Opt in with `data-p60-tabs` on your own markup and declare `tabs` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-tabs` | none; the container |
| `data-p60-tab` | the key of the panel this control activates |
| `data-p60-panel` | the key matching its control |

**State classes** (engine-toggled; the appearance is your CSS): `is-active`

## `carousel`

**Carousel**

On a container with one data-p60-slide per child: the engine manages is-active across slides, injects a dots nav (.p60-carousel-dots with one button per slide), wires optional template-provided data-p60-carousel-prev/data-p60-carousel-next controls, adds swipe, keyboard arrows, and hides inactive slides from assistive tech. Value "auto" enables auto-advance (data-p60-interval ms, min 3000, default 6000) and injects a rotation control (.p60-carousel-pause, first in the carousel's tab order) following the WAI-ARIA carousel pattern: hovering pauses and leaving resumes, keyboard focus entering the carousel stops rotation and leaving does not restart it, and the control is the only way back; is-paused sits on the carousel while rotation is stopped. Reduced motion disables auto-advance and the control while every other control keeps working. The engine stamps --p60-carousel-index on the container for track-translate designs; class-based fade on is-active is the simplest pattern. CSS hiding non-active slides MUST be .p60-js-scoped so the no-JS render shows all slides.


Opt in with `data-p60-carousel` on your own markup and declare `carousel` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-carousel` | none for manual; "auto" for auto-advance |
| `data-p60-slide` | none; one per slide child |
| `data-p60-interval` | optional auto-advance ms, min 3000 (default 6000) |
| `data-p60-carousel-prev` | none; optional template-provided control |
| `data-p60-carousel-next` | none; optional template-provided control |

**State classes** (engine-toggled; the appearance is your CSS): `is-active`, `is-paused`

**CSS variables the engine stamps**: `--p60-carousel-index`

**Injected markup you may style**: `.p60-carousel-dots`, `.p60-carousel-dot`, `.p60-carousel-dot--active`, `.p60-carousel-pause`, `.p60-carousel-pause--stopped`

## `readingProgress`

**Reading progress**

A reading-position indicator. The engine writes --p60-reading-progress (0 to 1) on the marked element and keeps a progressbar role honest (aria-valuenow 0 to 100, an accessible name of "Reading progress" unless the template gives one); the bar's shape and motion are the template's CSS. With data-p60-reading-target naming an element's id the reading is that element's extent, otherwise the whole document; a target the page does not have leaves the bar static. is-started once past zero, is-complete at the end. Information, not decoration: it keeps updating under reduced motion. The bar is pure enhancement, so it may be hidden unconditionally in CSS: a no-JS visitor loses nothing.


Opt in with `data-p60-reading-progress` on your own markup and declare `readingProgress` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-reading-progress` | none; the indicator element |
| `data-p60-reading-target` | optional id of the element whose extent is the reading (default: the document) |

**State classes** (engine-toggled; the appearance is your CSS): `is-started`, `is-complete`

**CSS variables the engine stamps**: `--p60-reading-progress`

## `showMore`

**Show more and less**

A list that starts short. On a container whose entries carry data-p60-show-more-item and which holds (or is named by aria-controls from) a data-p60-show-more-toggle button: the engine hides every item past the visible count with the hidden attribute, so the no-JS render shows the complete list and needs no CSS scoping; the toggle expands and collapses, aria-expanded stays honest, is-expanded sits on the container, and a toggle whose attribute carries a value swaps its text to that value while expanded. A list with nothing to hide hides its toggle: there is never a dead control. Author the toggle to show only under .p60-js.


Opt in with `data-p60-show-more` on your own markup and declare `showMore` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-show-more` | optional number of items shown while collapsed (default 6) |
| `data-p60-show-more-item` | none; on each entry |
| `data-p60-show-more-toggle` | none, or the label to show while expanded; on a button inside the list or pointing at it with aria-controls |

**State classes** (engine-toggled; the appearance is your CSS): `is-expanded`

## `scrollspy`

**Scrollspy**

On a menu of in-page links (href="#id"): the link whose section is being read gets is-current and aria-current="location", where the current section is the target furthest down the page whose top has passed the activation line (the attribute value in px from the top of the viewport, default 96). Links keep navigating and nothing ever moves focus; links whose target is not on the page are ignored, and a menu with no targets is left alone. Information, not decoration: it keeps updating under reduced motion.


Opt in with `data-p60-scrollspy` on your own markup and declare `scrollspy` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-scrollspy` | none, or the activation line in px (default 96); on the menu |

**State classes** (engine-toggled; the appearance is your CSS): `is-current`

## `nav`

**Navigation**

Your menu, made robust. You design the menu (markup, every pixel, the breakpoint); the engine supplies the interaction CSS :hover cannot: data-p60-nav on each nav root (several allowed), data-p60-nav-item on each group holding a data-p60-nav-toggle control and a data-p60-nav-menu panel (nesting allowed). Hover-capable pointers get hover intent (a short delay to open, a grace period to close) so crossing the gap between a toggle and its panel never closes it; keyboard, touch and pen toggle on the control (Enter/click, ArrowDown opens and focuses the first link; a mouse click on an already-hovered parent link navigates); Escape closes and returns focus to the toggle; a click outside or focus moving away closes; one item stays open per level and aria-expanded is kept honest. The burger: data-p60-nav-burger on a button whose aria-controls (or the attribute value) names the stacked panel; the engine toggles is-open on both, closes on Escape (returning focus), on a real navigation inside the panel, on an outside click, and when the burger disappears at a wider viewport. State is is-open on the item, the panel and the burger; under .p60-js show a panel only on is-open and keep your :hover/:focus-within rules scoped to html:not(.p60-js) for the no-JS render. Fit steps: when the root's row wraps or overflows, the engine steps is-fit-1, is-fit-2, is-fit-3 onto the root until it fits, re-measured on resize and once fonts settle, never on a stacked (column) nav; the platform's defaults shrink the member_menu pill at each step (the Port60 ID wordmark, then the text, leaving the person icon with its accessible label), and a template maps the same classes to anything else it wants to give up before the burger.


Opt in with `data-p60-nav` on your own markup and declare `nav` in `supports.behaviors`.


| Attribute | Value |
| --- | --- |
| `data-p60-nav` | none; a nav root, several allowed |
| `data-p60-nav-item` | none; a group holding one toggle and one menu, nestable |
| `data-p60-nav-toggle` | none; the item's control (a link or button) |
| `data-p60-nav-menu` | none; the item's panel |
| `data-p60-nav-burger` | none, or the id of the panel when aria-controls is absent |

**State classes** (engine-toggled; the appearance is your CSS): `is-open`, `is-fit-1`, `is-fit-2`, `is-fit-3`

Declare what you use in `supports.behaviors`, the validator proves declaration and usage agree in both directions. Remember the no-JS rule: any CSS hiding pre-behaviour content must be scoped under `.p60-js`.


━━ reference/content-bounds.md ━━


:::note[Generated reference]
This page is generated from the machine-readable contract the platform engine enforces (`contract/v1`). It cannot drift from production behaviour.
:::


The maximum lengths of every admin-entered display field a template renders. The admin screens stop input at these caps and the API rejects anything longer, so a template can design cards, headings and captions against known worst cases. Additive-only within a contract major: a bound may loosen, never tighten. Long-form bodies (article bodies, course About pages, service pages) are deliberately outside this table; they are sanitised HTML rendered in dedicated full-width regions, never inside cards.

Design for the maximum, and use CSS (`line-clamp`, `text-overflow`) where your layout wants less than the guarantee. Never assume a field is short just because the demo data is.

## Brand (layout chrome)

| Field | Max | Notes |
| --- | --- | --- |
| brand.name | 60 | The masthead/wordmark text. |
| brand.tagline | 140 | One line under the masthead; may be empty. |

## Articles

| Field | Max | Notes |
| --- | --- | --- |
| Article title | 200 |  |
| Excerpt | 500 | The card/front-page summary. |
| Author name / role | 120 | Each. |
| Articles nav label | 30 | The tenant's name for the section ("Latest", "News", …). |
| Categories | ,  | ≤5 per article; names come from a tenant catalogue capped at 20 entries. |

## Events

| Field | Max | Notes |
| --- | --- | --- |
| Event name | 200 |  |
| Summary (description) | 200 | A sentence or two for cards and listings. The long-form About body is separate sanitised HTML on the detail page. |
| Venue name | 200 |  |
| Venue address | 500 |  |
| Tag | 40 | Each, rendered as chips. |

## Courses

| Field | Max | Notes |
| --- | --- | --- |
| Course title | 200 |  |
| Description | 500 | The card/detail summary; the long-form About page is separate sanitised HTML. |
| Venue label | 200 |  |

## Donations

| Field | Max | Notes |
| --- | --- | --- |
| Cause name | 200 |  |
| Cause description | 500 |  |

## Service pages

| Field | Max | Notes |
| --- | --- | --- |
| Page name | 200 | The body is sanitised HTML rendered full-width, not card content. |


━━ reference/content-model.md ━━


:::note[Generated reference]
This page is generated from the machine-readable contract the platform engine enforces (`contract/v1`). It cannot drift from production behaviour.
:::


Everything a template reads lives on one tree: `site.brand`, `site.nav`, `site.socials`, `site.locale` and the typed collections under `site.content.*`. Model version **1.0**.

Four rules the model never breaks, so neither should your template:

1. **Bounded collections.** Every list documents its cap and carries a `moreHref`, link onward, never assume you have everything.
2. **Open enums.** Type fields grow; branch on the values you style and fall back for the rest (the validator proves your template survives unknown values).
3. **Explicit nullability.** Optional fields are documented nullable; always branch.
4. **Add-only.** Nothing you read today is removed within the major; deprecated means it stops being documented, never that it stops being served.

Your template's **content footprint** (which paths it reads) and its **minimum model version** are computed at publish from your sources, you never declare either. Dynamic indexing into `site.content` is refused so that stays decidable. During development, `preview-content.json` beside your manifest replaces collection DATA wholesale (shape is schema-checked; the file is hot-reloaded, never packaged, refused at upload); the kit's dev server renders this same reference with live example data at `/model`.


## `site.content.services`

The organisation's published content pages (the services CMS), newest curation order first.

Bounded at **24** · more at `/services` · since 1.0

| Field | Type | Notes | Since |
| --- | --- | --- | --- |
| `id` | string |  | 1.0 |
| `title` | string | max 200 chars | 1.0 |
| `slug` | string |  | 1.0 |
| `summary` | string | nullable, always branch · max 500 chars | 1.0 |
| `imageUrl` | string | nullable, always branch | 1.0 |
| `href` | string |  | 1.0 |

**Example (the canonical fixture):**

```json
{
  "id": "66666666-6666-6666-6666-666666666661",
  "title": "Food Bank",
  "slug": "food-bank",
  "summary": "Emergency parcels, no referral needed, from the Foundry Lane depot every weekday morning.",
  "imageUrl": "p60fixture:service/foodbank",
  "href": "/services?service=food-bank"
}
```


## `site.content.events`

Published events, soonest first. `registrationMode` is an OPEN enum: INFO, RSVP and TICKETED exist today and new modes will arrive; branch on the ones you style and fall back for the rest.

Bounded at **12** · more at `/events` · since 1.0

| Field | Type | Notes | Since |
| --- | --- | --- | --- |
| `id` | string |  | 1.0 |
| `name` | string | max 200 chars | 1.0 |
| `description` | string | nullable, always branch · max 200 chars | 1.0 |
| `registrationMode` | string | open enum: INFO, RSVP, TICKETED today | 1.0 |
| `startsAt` | string |  | 1.0 |
| `endsAt` | string | nullable, always branch | 1.0 |
| `venueName` | string | nullable, always branch · max 200 chars | 1.0 |
| `online` | boolean |  | 1.0 |
| `imageUrl` | string | nullable, always branch | 1.0 |
| `onSale` | boolean |  | 1.0 |
| `soldOut` | boolean |  | 1.0 |
| `priceFrom` | number | nullable, always branch | 1.0 |
| `currency` | string | nullable, always branch | 1.0 |
| `detailHref` | string |  | 1.0 |

**Example (the canonical fixture):**

```json
{
  "id": "22222222-2222-2222-2222-222222222222",
  "name": "The Lantern Gala",
  "description": "Our biggest night of the year: supper, music from the Alderford Community Choir, and the annual lantern walk along the river to close.",
  "registrationMode": "TICKETED",
  "startsAt": "2030-09-20T19:00:00Z",
  "endsAt": null,
  "venueName": "The Maltings, Alderford",
  "online": false,
  "imageUrl": "p60fixture:event/gala",
  "onSale": true,
  "soldOut": false,
  "priceFrom": 25,
  "currency": "GBP",
  "detailHref": "/events?event=22222222-2222-2222-2222-222222222222"
}
```


## `site.content.articles`

Published articles, newest first. Detail bodies stay editor-owned sanitised richtext on the article page BY DESIGN; the card model carries everything a listing needs.

Bounded at **12** · more at `/articles/all` · since 1.0

| Field | Type | Notes | Since |
| --- | --- | --- | --- |
| `id` | string |  | 1.0 |
| `title` | string | max 200 chars | 1.0 |
| `slug` | string |  | 1.0 |
| `excerpt` | string | nullable, always branch · max 500 chars | 1.0 |
| `imageUrl` | string | nullable, always branch | 1.0 |
| `authorName` | string | nullable, always branch · max 120 chars | 1.0 |
| `authorRole` | string | nullable, always branch · max 120 chars | 1.0 |
| `categories` | string[] |  | 1.0 |
| `publishedAt` | string |  | 1.0 |
| `readingMinutes` | number | nullable, always branch | 1.0 |
| `href` | string |  | 1.0 |

**Example (the canonical fixture):**

```json
{
  "id": "88888888-8888-8888-8888-888888888888",
  "title": "The Community Garden Opens Its Gates",
  "slug": "community-garden-opens",
  "excerpt": "Two years of digging, fundraising and Saturday mornings in the rain: the Foundry Lane garden is finally open to everyone.",
  "imageUrl": "p60fixture:article/garden",
  "authorName": "Amina Khan",
  "authorRole": "Community Editor",
  "categories": [
    "News"
  ],
  "publishedAt": "2030-04-12T09:00:00Z",
  "readingMinutes": 5,
  "href": "/articles/community-garden-opens"
}
```


## `site.content.campaigns`

Live campaigns, curation order.

Bounded at **12** · more at `/campaigns` · since 1.0

| Field | Type | Notes | Since |
| --- | --- | --- | --- |
| `id` | string |  | 1.0 |
| `title` | string | max 200 chars | 1.0 |
| `href` | string |  | 1.0 |
| `summary` | string | nullable, always branch · max 500 chars | 1.0 |
| `imageUrl` | string | nullable, always branch | 1.0 |

**Example (the canonical fixture):**

```json
{
  "id": "99999999-9999-9999-9999-999999999991",
  "title": "Keep the 27 Bus",
  "href": "/campaigns/keep-the-27-bus",
  "summary": "The only bus serving the Fenwick estate is set to be cut. Add your name before the consultation closes.",
  "imageUrl": "p60fixture:campaign/bus"
}
```


## `site.content.causes`

Causes currently accepting donations, quick-give first. `paymentOptions` mirrors the public cause contract.

Bounded at **12** · more at `/donate` · since 1.0

| Field | Type | Notes | Since |
| --- | --- | --- | --- |
| `id` | string |  | 1.0 |
| `title` | string | max 200 chars | 1.0 |
| `slug` | string |  | 1.0 |
| `description` | string | nullable, always branch · max 500 chars | 1.0 |
| `imageUrl` | string | nullable, always branch | 1.0 |
| `targetAmount` | number | nullable, always branch | 1.0 |
| `raisedAmount` | number | nullable, always branch | 1.0 |
| `progressPercentage` | number | nullable, always branch | 1.0 |
| `href` | string |  | 1.0 |
| `paymentOptions` | object | nullable, always branch | 1.0 |

**Example (the canonical fixture):**

```json
{
  "id": "55555555-5555-5555-5555-555555555550",
  "title": "Flood Response Appeal",
  "slug": "flood-response",
  "description": "The Aldern broke its banks on Sunday. Thirty households need dry bedding, dehumidifiers and somewhere warm now.",
  "imageUrl": "p60fixture:cause/flood",
  "targetAmount": 50000,
  "raisedAmount": 18750,
  "progressPercentage": 38,
  "href": "/donate/flood-response",
  "paymentOptions": {
    "oneOff": true,
    "recurringCard": true,
    "directDebit": true
  }
}
```


## `site.content.courses`

Enrollable courses. The long-form About body is sanitised richtext on the course page, never in cards.

Bounded at **12** · more at `/courses` · since 1.0

| Field | Type | Notes | Since |
| --- | --- | --- | --- |
| `id` | string |  | 1.0 |
| `title` | string | max 200 chars | 1.0 |
| `description` | string | nullable, always branch · max 500 chars | 1.0 |
| `imageUrl` | string | nullable, always branch | 1.0 |
| `venue` | string | nullable, always branch · max 200 chars | 1.0 |
| `audience` | string | open enum: ADULT, CHILD, FAMILY today | 1.0 |
| `priceFrom` | number | nullable, always branch | 1.0 |
| `currency` | string | nullable, always branch | 1.0 |
| `soldOut` | boolean |  | 1.0 |
| `href` | string |  | 1.0 |

**Example (the canonical fixture):**

```json
{
  "id": "33333333-3333-3333-3333-333333333333",
  "title": "Junior Athletics",
  "description": "Weekly athletics for children aged 7 to 12, coached by qualified volunteers at the King's Park track.",
  "imageUrl": "p60fixture:course/athletics",
  "venue": "King's Park track",
  "audience": "CHILD",
  "priceFrom": 15,
  "currency": "GBP",
  "soldOut": false,
  "href": "/courses"
}
```


## `site.content.resources`

Published documents, grouped by folder.

Bounded at **24** · more at `/resources` · since 1.0

| Field | Type | Notes | Since |
| --- | --- | --- | --- |
| `id` | string |  | 1.0 |
| `title` | string | max 200 chars | 1.0 |
| `folder` | string | nullable, always branch | 1.0 |
| `url` | string |  | 1.0 |
| `contentType` | string | nullable, always branch | 1.0 |
| `bytes` | number | nullable, always branch | 1.0 |
| `publishedAt` | string | nullable, always branch | 1.0 |

**Example (the canonical fixture):**

```json
{
  "id": "88888888-8888-8888-8888-888888888881",
  "title": "Annual report 2029.pdf",
  "folder": "Reports",
  "url": "/fixture/annual-report-2029.pdf",
  "contentType": "application/pdf",
  "bytes": 1245760,
  "publishedAt": "2030-02-01T10:00:00Z"
}
```


## `site.content.locations`

The organisation's physical places, primary first.

Bounded at **12** · more at `/locations` · since 1.0

| Field | Type | Notes | Since |
| --- | --- | --- | --- |
| `id` | string |  | 1.0 |
| `name` | string | max 200 chars | 1.0 |
| `address` | string | nullable, always branch · max 500 chars | 1.0 |
| `latitude` | number | nullable, always branch | 1.0 |
| `longitude` | number | nullable, always branch | 1.0 |
| `primary` | boolean |  | 1.0 |
| `directionsHref` | string | nullable, always branch | 1.0 |

**Example (the canonical fixture):**

```json
{
  "id": "99999999-9999-9999-9999-999999999901",
  "name": "Foundry Lane Hub",
  "address": "14 Foundry Lane, Alderford AL2 4RS",
  "latitude": 53.8008,
  "longitude": -1.5491,
  "primary": true,
  "directionsHref": "https://www.google.com/maps/dir/?api=1&destination=Foundry%20Lane%20Hub"
}
```


## `site.content.schedules`

TYPE-DERIVED recurring schedules. `type` is an OPEN enum; 'worship' is the first (its shape is the layout worship contract: times, labels, today, next). Other institutions arrive as new types; render the types you know, ignore the rest.

Bounded at **4** · since 1.0

| Field | Type | Notes | Since |
| --- | --- | --- | --- |
| `type` | string | open enum: worship today | 1.0 |
| `content` | object |  | 1.0 |

**Example (the canonical fixture):**

```json
{
  "type": "worship",
  "content": {
    "times": [
      {
        "name": "Fajr",
        "begins": "03:20",
        "congregation": "04:00"
      },
      {
        "name": "Zuhr",
        "begins": "13:11",
        "congregation": "13:30"
      },
      {
        "name": "Asr",
        "begins": "18:30",
        "congregation": "19:00"
      },
      {
        "name": "Maghrib",
        "begins": "21:04",
        "congregation": "21:04"
      },
      {
        "name": "Isha",
        "begins": "22:12",
        "congregation": "22:30"
      }
    ],
    "beginsLabel": "Begins",
    "congregationLabel": "Jama'at",
    "note": "Jum'a 13:15 & 14:15",
    "href": "/services?service=prayer-times",
    "today": "24 July 2026",
    "todayAlt": "11 Safar 1448",
    "next": {
      "name": "Asr",
      "begins": "18:30",
      "congregation": "19:00",
      "target": "2030-07-24T19:00:00+01:00"
    },
    "jumah": [
      {
        "name": "Jum'a 1",
        "begins": null,
        "congregation": "13:15"
      },
      {
        "name": "Jum'a 2",
        "begins": null,
        "congregation": "14:15"
      }
    ],
    "hijri": {
      "display": "11 Safar 1448"
    },
    "observances": [
      {
        "name": "Community iftar",
        "date": "2 March 2030",
        "href": "/events"
      }
    ]
  }
}
```


## `site.content.about`

The admin-authored page composition: the ordered sections of the home/about surface. `type` is the section catalogue's OPEN enum; `content` is that section type's fields. This is what `section.*` re-addresses; a mega-page template can walk it directly.

Bounded at **24** · since 1.0

| Field | Type | Notes | Since |
| --- | --- | --- | --- |
| `type` | string | open enum | 1.0 |
| `content` | object |  | 1.0 |

━━ reference/context.md ━━


:::note[Generated reference]
This page is generated from the machine-readable contract the platform engine enforces (`contract/v1`). It cannot drift from production behaviour.
:::


The data context templates render with. Templates receive ONLY platform-provided data, never secrets, never other tenants' data. Additive-only within a contract major. Section renderers get {section, brand}; the layout gets {brand, nav, socials}; page templates (pages/{page}.liquid) get their page's documented objects + brand.


:::note[The content model is the way in]
New templates read the one `site` tree, see the [Content model](/reference/content-model/) reference. The flat-era variables (bare `brand`, `nav`, `socials`, widget-section data) are no longer documented; they keep being served to published pre-v1 template versions, and only there.
:::


## In section renderers

| Variable | Description |
| --- | --- |
| `site` | The one content tree (content model v1, contract/v1/content-model.json): site.brand, site.nav, site.socials, site.locale and the typed collections under site.content.*. Available to every render scope; page templates receive it alongside their page objects. |
| `site.brand` | The organisation's branding (same shape as the flat-era brand object). |
| `site.nav` | Navigation: items (curated main or platform-derived), footer, derived, the flat-era nav shape, re-addressed. |
| `site.focus` | What the primary_action_widget island becomes: 'donate' (default, the donation widget), 'volunteer' (the volunteer sign-up) or 'none' (the charity chose no widget in the hero). The charity's one switch (docs/volunteering.md 'Site focus'); everything below follows from it. |
| `site.actions` | The two resolved actions: primary { kind, label, href } is the focus (the widget in the hero); secondary is the other action (the header button). Both always exist. |
| `section.primary` | homeHero only: the leading action { kind, label, href }, the same as site.actions.primary. Render it as a widget with {% island 'primary_action_widget' %} when section.actionStyle is 'widget'; that island becomes this action's widget. |
| `section.secondary` | homeHero only: the other action { kind, label, href }, the same as site.actions.secondary; the header button carries it. |
| `section.action` | homeHero only: the hero's own button { kind, label, href }: the action whose widget is NOT on the page (donation widget present, the button is Volunteer; volunteer widget present, the button is Donate), or the leading action when actionStyle is 'button'. Render it as the first hero button unless the author set primaryLabel / primaryHref; the second button stays the author's story link. |
| `section.actionStyle` | homeHero only: 'widget' (the leading action's widget sits in the hero) or 'button' (copy only, the primary button is the way in). The old givingStyle value is kept as an alias ('form' = 'widget'). |
| `site.socials` | Social links, the flat-era socials shape. |
| `site.locale` | Locale: code, direction, languages. |
| `site.content` | The typed collections: services, events, articles, campaigns, causes, courses, resources, locations, schedules, about. EVERY collection is bounded (cap + moreHref in the model registry), every enum is open, every optional field explicitly nullable, and the model only ever grows. The validator computes your template's content footprint from the paths you read and stamps the required minimum model version at publish; dynamic indexing into site.content is refused so the footprint stays decidable. |

## In the layout

| Variable | Description |
| --- | --- |
| `site` | The one content tree (content model v1, contract/v1/content-model.json): site.brand, site.nav, site.socials, site.locale and the typed collections under site.content.*. Available to every render scope; page templates receive it alongside their page objects. |
| `site.brand` | The organisation's branding (same shape as the flat-era brand object). |
| `site.nav` | Navigation: items (curated main or platform-derived), footer, derived, the flat-era nav shape, re-addressed. |
| `site.focus` | What the primary_action_widget island becomes: 'donate' (default, the donation widget), 'volunteer' (the volunteer sign-up) or 'none' (the charity chose no widget in the hero). The charity's one switch (docs/volunteering.md 'Site focus'); everything below follows from it. |
| `site.actions` | The two resolved actions: primary { kind, label, href } is the focus (the widget in the hero); secondary is the other action (the header button). Both always exist. |
| `site.socials` | Social links, the flat-era socials shape. |
| `site.locale` | Locale: code, direction, languages. |
| `site.content` | The typed collections: services, events, articles, campaigns, causes, courses, resources, locations, schedules, about. EVERY collection is bounded (cap + moreHref in the model registry), every enum is open, every optional field explicitly nullable, and the model only ever grows. The validator computes your template's content footprint from the paths you read and stamps the required minimum model version at publish; dynamic indexing into site.content is refused so the footprint stays decidable. |

## In pages/events.liquid

| Variable | Description |
| --- | --- |

## In the events section renderer (sections/events.liquid)

| Variable | Description |
| --- | --- |

## In the appealGrid section renderer (sections/appealGrid.liquid)

| Variable | Description |
| --- | --- |

## In the emergency section renderer (sections/emergency.liquid)

| Variable | Description |
| --- | --- |

## In the programmes section renderer (sections/programmes.liquid)

| Variable | Description |
| --- | --- |

## In the resources section renderer (sections/resources.liquid)

| Variable | Description |
| --- | --- |

## In the locations section renderer (sections/locations.liquid)

| Variable | Description |
| --- | --- |

## In the whatsOn section renderer (sections/whatsOn.liquid)

| Variable | Description |
| --- | --- |

## In the articles section renderer (sections/articles.liquid)

| Variable | Description |
| --- | --- |

## In the campaigns section renderer (sections/campaigns.liquid)

| Variable | Description |
| --- | --- |

## In pages/articles.liquid

| Variable | Description |
| --- | --- |

## In pages/article.liquid

| Variable | Description |
| --- | --- |

## In pages/course.liquid

| Variable | Description |
| --- | --- |

```liquid
<p class="lq-kicker">{{ section.eyebrow | default: brand.name }}</p>
```

## The validator's fixtures

The conformance validator renders your templates against these (they must survive them):

**brand:**

```json
{
  "name": "The Lantern Trust",
  "tagline": "Neighbours, looked after.",
  "logoUrl": null,
  "logoType": "full",
  "footerLogoUrl": null
}
```

**nav (layout only):**

```json
{
  "items": [
    {
      "label": "Home",
      "href": "/",
      "cta": false
    },
    {
      "label": "About us",
      "href": "/about",
      "cta": false
    },
    {
      "label": "Events",
      "href": "/events",
      "cta": false
    },
    {
      "label": "Services",
      "href": "/services",
      "cta": false,
      "children": [
        {
          "label": "Food bank",
          "href": "/services?service=food-bank",
          "group": "Support",
          "description": "Emergency food parcels and practical advice."
        },
        {
          "label": "Community",
          "href": "#",
          "group": "Get involved",
          "children": [
            {
              "label": "Youth club",
              "href": "/services?service=youth-club"
            }
          ]
        }
      ],
      "megaMenu": {
        "columns": 3,
        "promo": {
          "title": "Visit this week",
          "text": "Find a programme and meet the team.",
          "href": "/services",
          "label": "Explore services"
        }
      }
    },
    {
      "label": "Donate",
      "href": "/donate",
      "cta": true
    }
  ],
  "footer": [
    {
      "label": "About us",
      "href": "/about"
    },
    {
      "label": "Contact",
      "href": "https://example.org/contact",
      "external": true
    },
    {
      "label": "Our work",
      "href": "#",
      "children": [
        {
          "label": "Food bank",
          "href": "/services?service=food-bank"
        }
      ]
    }
  ],
  "derived": [
    {
      "label": "Home",
      "href": "/",
      "cta": false
    },
    {
      "label": "About us",
      "href": "/about",
      "cta": false
    },
    {
      "label": "Events",
      "href": "/events",
      "cta": false
    },
    {
      "label": "Donate",
      "href": "/donate",
      "cta": true
    }
  ]
}
```

**worship (layout only, OPTIONAL, null when the tenant has no schedule; always branch):**

```json
{
  "times": [
    {
      "name": "Fajr",
      "begins": "03:20",
      "congregation": "04:00"
    },
    {
      "name": "Zuhr",
      "begins": "13:11",
      "congregation": "13:30"
    },
    {
      "name": "Asr",
      "begins": "18:30",
      "congregation": "19:00"
    },
    {
      "name": "Maghrib",
      "begins": "21:04",
      "congregation": "21:04"
    },
    {
      "name": "Isha",
      "begins": "22:12",
      "congregation": "22:30"
    }
  ],
  "beginsLabel": "Begins",
  "congregationLabel": "Jama'at",
  "note": "Jum'a 13:15 & 14:15",
  "href": "/services?service=prayer-times",
  "today": "24 July 2026",
  "todayAlt": "11 Safar 1448",
  "next": {
    "name": "Asr",
    "begins": "18:30",
    "congregation": "19:00",
    "target": "2030-07-24T19:00:00+01:00"
  },
  "jumah": [
    {
      "name": "Jum'a 1",
      "begins": null,
      "congregation": "13:15"
    },
    {
      "name": "Jum'a 2",
      "begins": null,
      "congregation": "14:15"
    }
  ],
  "hijri": {
    "display": "11 Safar 1448"
  },
  "observances": [
    {
      "name": "Community iftar",
      "date": "2 March 2030",
      "href": "/events"
    }
  ]
}
```

**pages/events.liquid:**

```json
{
  "events": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "name": "The Lantern Gala",
      "description": "Our biggest night of the year: supper, music from the Alderford Community Choir, and the annual lantern walk along the river to close.",
      "registrationMode": "TICKETED",
      "startsAt": "2030-09-20T19:00:00Z",
      "endsAt": null,
      "venueName": "The Maltings, Alderford",
      "online": false,
      "imageUrl": "p60fixture:event/gala",
      "onSale": true,
      "soldOut": false,
      "priceFrom": 25,
      "currency": "GBP",
      "detailHref": "/events?event=22222222-2222-2222-2222-222222222222"
    },
    {
      "id": "44444444-4444-4444-4444-444444444444",
      "name": "Riverside Harvest Supper",
      "description": "A long-table supper on the Aldern meadow, cooked by our kitchen volunteers with produce from the community garden.",
      "registrationMode": "TICKETED",
      "startsAt": "2030-10-04T18:30:00Z",
      "endsAt": "2030-10-04T22:00:00Z",
      "venueName": "Aldern Meadow",
      "online": false,
      "imageUrl": "p60fixture:event/harvest",
      "onSale": true,
      "soldOut": false,
      "priceFrom": 12.5,
      "currency": "GBP",
      "detailHref": "/events?event=44444444-4444-4444-4444-444444444444"
    },
    {
      "id": "55555555-5555-5555-5555-555555555555",
      "name": "Volunteer Welcome Evening",
      "description": "Meet the team, hear where help is needed most this season, and find a role that fits the time you have.",
      "registrationMode": "RSVP",
      "startsAt": "2030-09-03T18:00:00Z",
      "endsAt": "2030-09-03T19:30:00Z",
      "venueName": "Foundry Lane Hub",
      "online": false,
      "imageUrl": "p60fixture:event/welcome",
      "onSale": true,
      "soldOut": false,
      "priceFrom": null,
      "currency": null,
      "detailHref": "/events?event=55555555-5555-5555-5555-555555555555"
    },
    {
      "id": "66666666-6666-6666-6666-666666666666",
      "name": "Warm Space Wednesdays",
      "description": "Our hall is open, warm and stocked with tea every Wednesday through the cold months. No booking, no questions, everyone welcome.",
      "registrationMode": "INFO",
      "startsAt": "2030-11-06T10:00:00Z",
      "endsAt": "2030-11-06T15:00:00Z",
      "venueName": "St Chad's Hall",
      "online": false,
      "imageUrl": null,
      "onSale": true,
      "soldOut": false,
      "priceFrom": null,
      "currency": null,
      "detailHref": "/events?event=66666666-6666-6666-6666-666666666666"
    },
    {
      "id": "77777777-7777-7777-7777-777777777777",
      "name": "Money Advice Drop-in",
      "description": "A quiet hour with our trained advisers. Bring letters you are worried about; we will work through them together.",
      "registrationMode": "INFO",
      "startsAt": "2030-09-12T10:00:00Z",
      "endsAt": "2030-09-12T12:00:00Z",
      "venueName": null,
      "online": true,
      "imageUrl": null,
      "onSale": true,
      "soldOut": false,
      "priceFrom": null,
      "currency": null,
      "detailHref": "/events?event=77777777-7777-7777-7777-777777777777"
    },
    {
      "id": "88888888-8888-8888-8888-888888888888",
      "name": "Winter Fair",
      "description": "Stalls, carols and the grand raffle in aid of the Winter Appeal. Free entry; every stall staffed by volunteers.",
      "registrationMode": "TICKETED",
      "startsAt": "2030-12-07T11:00:00Z",
      "endsAt": "2030-12-07T16:00:00Z",
      "venueName": "Alderford Market Square",
      "online": false,
      "imageUrl": "p60fixture:event/winterfair",
      "onSale": true,
      "soldOut": true,
      "priceFrom": 0,
      "currency": "GBP",
      "detailHref": "/events?event=88888888-8888-8888-8888-888888888888"
    }
  ]
}
```

**pages/course.liquid:**

```json
{
  "course": {
    "id": "33333333-3333-3333-3333-333333333333",
    "title": "Junior Athletics",
    "description": "Weekly athletics for children aged 7 to 12, coached by qualified volunteers at the King's Park track.",
    "aboutHtml": "<h2>What we do</h2><p>Track and field fundamentals in a friendly, coached setting: warm-ups, drills, and a different discipline every week.</p><ul><li>Sprints, relays and middle distance</li><li>Long jump, high jump and throws</li><li>A club mini-meet at the end of every term</li></ul><h2>What to bring</h2><p>Trainers, a water bottle and a waterproof. Everything else, including spikes for the older group, is provided.</p>",
    "imageUrl": "p60fixture:course/athletics",
    "venue": "King's Park track",
    "audience": "CHILD",
    "billingMode": "ROLLING",
    "termStart": null,
    "termEnd": null,
    "currency": "GBP",
    "priceFrom": 15,
    "soldOut": false,
    "backHref": "/courses"
  }
}
```

**pages/articles.liquid:**

```json
{
  "selectedCategory": null,
  "categories": [
    {
      "name": "News",
      "count": 3,
      "href": "/articles/all?category=News"
    },
    {
      "name": "Stories",
      "count": 2,
      "href": "/articles/all?category=Stories"
    },
    {
      "name": "Guides",
      "count": 1,
      "href": "/articles/all?category=Guides"
    }
  ],
  "articles": [
    {
      "id": "88888888-8888-8888-8888-888888888888",
      "title": "The Community Garden Opens Its Gates",
      "slug": "community-garden-opens",
      "excerpt": "Two years of digging, fundraising and Saturday mornings in the rain: the Foundry Lane garden is finally open to everyone.",
      "imageUrl": "p60fixture:article/garden",
      "authorName": "Amina Khan",
      "authorRole": "Community Editor",
      "categories": [
        "News"
      ],
      "publishedAt": "2030-04-12T09:00:00Z",
      "readingMinutes": 5,
      "viewCount": 412,
      "likeCount": 38,
      "commentCount": 9,
      "href": "/articles/community-garden-opens"
    },
    {
      "id": "99999999-9999-9999-9999-999999999999",
      "title": "What a Food Parcel Actually Holds",
      "slug": "what-a-food-parcel-holds",
      "excerpt": "People imagine tins and pasta. The real list is longer, more personal, and put together with more care than you might think.",
      "imageUrl": "p60fixture:article/parcel",
      "authorName": "Derek Osei",
      "authorRole": "Food Bank Lead",
      "categories": [
        "Stories"
      ],
      "publishedAt": "2030-03-28T09:00:00Z",
      "readingMinutes": 6,
      "viewCount": 655,
      "likeCount": 61,
      "commentCount": 14,
      "href": "/articles/what-a-food-parcel-holds"
    },
    {
      "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "title": "Meet the Wednesday Kitchen Crew",
      "slug": "wednesday-kitchen-crew",
      "excerpt": "Eleven volunteers, one borrowed oven, and a hundred and forty hot meals a week. The kitchen crew tell it in their own words.",
      "imageUrl": "p60fixture:people/kitchen",
      "authorName": "Amina Khan",
      "authorRole": "Community Editor",
      "categories": [
        "Stories"
      ],
      "publishedAt": "2030-03-02T09:00:00Z",
      "readingMinutes": 7,
      "viewCount": 388,
      "likeCount": 45,
      "commentCount": 11,
      "href": "/articles/wednesday-kitchen-crew"
    },
    {
      "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "title": "Winter Appeal: Where Your Money Went",
      "slug": "winter-appeal-report",
      "excerpt": "You gave 18,400 pounds in eight weeks. Here is the line-by-line account of what it paid for, and what we learned.",
      "imageUrl": "p60fixture:campaign/winterreport",
      "authorName": "Priya Sharma",
      "authorRole": "Trustee",
      "categories": [
        "News"
      ],
      "publishedAt": "2030-02-14T09:00:00Z",
      "readingMinutes": 8,
      "viewCount": 902,
      "likeCount": 84,
      "commentCount": 21,
      "href": "/articles/winter-appeal-report"
    },
    {
      "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
      "title": "Five Things Our Money Advisers Wish You Knew",
      "slug": "money-advice-five-things",
      "excerpt": "The advice team see the same worries again and again. Most of them have a fix that takes less than an hour.",
      "imageUrl": null,
      "authorName": "Tom Bradley",
      "authorRole": "Advice Service",
      "categories": [
        "Guides"
      ],
      "publishedAt": "2030-01-30T09:00:00Z",
      "readingMinutes": 4,
      "viewCount": 1204,
      "likeCount": 96,
      "commentCount": 17,
      "href": "/articles/money-advice-five-things"
    },
    {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "title": "A Year of Warm Spaces, in Numbers",
      "slug": "warm-spaces-in-numbers",
      "excerpt": "Fourteen hundred visits, ninety regulars, and one chess league nobody planned. What happens when you just open the door.",
      "imageUrl": "p60fixture:service/warmspace",
      "authorName": "Amina Khan",
      "authorRole": "Community Editor",
      "categories": [
        "News"
      ],
      "publishedAt": "2030-01-08T09:00:00Z",
      "readingMinutes": 5,
      "viewCount": 517,
      "likeCount": 42,
      "commentCount": 8,
      "href": "/articles/warm-spaces-in-numbers"
    }
  ]
}
```

**pages/article.liquid:**

```json
{
  "article": {
    "id": "88888888-8888-8888-8888-888888888888",
    "title": "The Community Garden Opens Its Gates",
    "slug": "community-garden-opens",
    "excerpt": "Two years of digging, fundraising and Saturday mornings in the rain: the Foundry Lane garden is finally open to everyone.",
    "imageUrl": "p60fixture:article/garden",
    "authorName": "Amina Khan",
    "authorRole": "Community Editor",
    "categories": [
      "News"
    ],
    "publishedAt": "2030-04-12T09:00:00Z",
    "readingMinutes": 5,
    "viewCount": 412,
    "likeCount": 38,
    "commentCount": 9,
    "href": "/articles/community-garden-opens",
    "updatedAt": "2030-04-12T10:00:00Z",
    "bodyHtml": "<h2>A shared place to grow</h2><p>The gates opened at ten. By half past, every raised bed had a family around it, the tool shed had a queue, and somebody had already claimed the sunny corner by the wall for tomatoes.</p><p>The Foundry Lane garden has been two years in the making. It began as a patch of rubble behind the old ironworks, offered to us on a peppercorn lease after the Winter Fair of 2028, and it has been built almost entirely by volunteer weekends since: twenty-two raised beds, a wheelchair-accessible path, a rainwater store, and a greenhouse pieced together from three donated ones.</p><blockquote><p>I have lived on this street forty years and never once stood on this ground. Now my grandchildren grow beans here.</p></blockquote><h2>What happens next</h2><p>The beds are allocated, but the garden is not finished, and it is not meant to be. This season the growers' committee has three priorities:</p><ul><li>A covered seating area, so the garden works in the rain it will certainly get</li><li>Weekly sessions with the youth club, growing the salads the kitchen crew cook with</li><li>A seed library in the old gatehouse, free to any Alderford household</li></ul><p>If you can lay a slab, mend a frame or simply keep a kettle going, the volunteer team would love to hear from you. And if you just want somewhere green to sit, the gate is open every day until dusk.</p><h3>Thank you</h3><p>To the eighty-one people who gave to the garden appeal, the six local firms who lent tools and time, and the council officers who said yes when it mattered: this one is yours as much as ours.</p>",
    "allowComments": true
  },
  "relatedArticles": [
    {
      "id": "99999999-9999-9999-9999-999999999999",
      "title": "What a Food Parcel Actually Holds",
      "slug": "what-a-food-parcel-holds",
      "excerpt": "People imagine tins and pasta. The real list is longer, more personal, and put together with more care than you might think.",
      "imageUrl": "p60fixture:article/parcel",
      "authorName": "Derek Osei",
      "authorRole": "Food Bank Lead",
      "categories": [
        "Stories"
      ],
      "publishedAt": "2030-03-28T09:00:00Z",
      "readingMinutes": 6,
      "viewCount": 655,
      "likeCount": 61,
      "commentCount": 14,
      "href": "/articles/what-a-food-parcel-holds"
    },
    {
      "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "title": "Winter Appeal: Where Your Money Went",
      "slug": "winter-appeal-report",
      "excerpt": "You gave 18,400 pounds in eight weeks. Here is the line-by-line account of what it paid for, and what we learned.",
      "imageUrl": "p60fixture:campaign/winterreport",
      "authorName": "Priya Sharma",
      "authorRole": "Trustee",
      "categories": [
        "News"
      ],
      "publishedAt": "2030-02-14T09:00:00Z",
      "readingMinutes": 8,
      "viewCount": 902,
      "likeCount": 84,
      "commentCount": 21,
      "href": "/articles/winter-appeal-report"
    },
    {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "title": "A Year of Warm Spaces, in Numbers",
      "slug": "warm-spaces-in-numbers",
      "excerpt": "Fourteen hundred visits, ninety regulars, and one chess league nobody planned. What happens when you just open the door.",
      "imageUrl": "p60fixture:service/warmspace",
      "authorName": "Amina Khan",
      "authorRole": "Community Editor",
      "categories": [
        "News"
      ],
      "publishedAt": "2030-01-08T09:00:00Z",
      "readingMinutes": 5,
      "viewCount": 517,
      "likeCount": 42,
      "commentCount": 8,
      "href": "/articles/warm-spaces-in-numbers"
    }
  ],
  "backHref": "/articles"
}
```


━━ reference/dialect.md ━━


:::note[Generated reference]
This page is generated from the machine-readable contract the platform engine enforces (`contract/v1`). It cannot drift from production behaviour.
:::


The Port60 dialect is a **strict, whitelisted subset of Liquid**, identified as `port60-liquid@1` (the value your manifest's `format` field must carry). Anything not listed on this page is rejected, at publish time by the conformance validator and at render time by the engine, with the same shared enforcement code.

## Output escaping

Every `{{ output }}` is **HTML-escaped by default**. The single opt-out is the `raw` filter, and the only values you should ever pass through it are the contract's `richtext` fields (e.g. `section.bodyHtml`); they are sanitised server-side before a template ever sees them.

```liquid
<h1>{{ section.title }}</h1>            {%- comment -%} escaped, safe for any text {%- endcomment -%}
{{ section.bodyHtml | raw }}            {%- comment -%} sanitised richtext only {%- endcomment -%}
```

Unknown filters are a **hard error** (`strictFilters`), not a silent pass-through.

## Tags

| Tag | Purpose |
| --- | --- |
| `if` / `elsif` / `else` / `endif` | Conditionals |
| `unless` / `endunless` | Negated conditional |
| `case` / `when` / `endcase` | Switch |
| `for` / `endfor` / `break` / `continue` | Iteration |
| `assign` | Set a variable |
| `capture` / `endcapture` | Capture rendered output into a variable |
| `comment` / `endcomment` | Comments |
| `echo` | Output inside `{% liquid %}` blocks |
| `raw` / `endraw` | Verbatim (non-rendered) output |
| `liquid` | Multi-statement block |

## Custom tags

### `{% island %}`

Places a platform functional island (a live, hydrated component) at this position. Templates place islands, never implement them, the island's markup, behaviour and data are platform-owned and upgraded platform-side. The island name must be declared in the manifest's supports.islands.

```liquid
{% island 'donation_widget' %}
```

### `{% content %}`

LAYOUT ONLY: the slot where the page's rendered sections are injected. A layout must contain exactly one. Section renderers must not use it.

```liquid
{% content %}
```


## Filters

All 49 allowed filters:

`abs` · `append` · `at_least` · `at_most` · `capitalize` · `ceil` · `compact` · `concat` · `date` · `default` · `divided_by` · `downcase` · `escape` · `escape_once` · `first` · `floor` · `join` · `last` · `lstrip` · `map` · `minus` · `modulo` · `newline_to_br` · `plus` · `prepend` · `raw` · `remove` · `remove_first` · `replace` · `replace_first` · `reverse` · `round` · `rstrip` · `size` · `slice` · `sort` · `sort_natural` · `split` · `strip` · `strip_html` · `strip_newlines` · `times` · `truncate` · `truncatewords` · `uniq` · `upcase` · `url_decode` · `url_encode` · `where`

## Excluded, and why

These standard Liquid tags are **not** part of the dialect and fail at parse time:

- `{% include %}`
- `{% render %}`
- `{% layout %}`
- `{% tablerow %}`
- `{% cycle %}`
- `{% increment %}`
- `{% decrement %}`

> File inclusion (no file system exists inside an artifact yet, a snippets mechanism arrives with the Layout slot), table markup generation, and stateful counters are outside the v1 dialect.


━━ reference/islands.md ━━


:::note[Generated reference]
This page is generated from the machine-readable contract the platform engine enforces (`contract/v1`). It cannot drift from production behaviour.
:::


The platform's functional islands, the app-block table. A template PLACES an island with {% island 'name' %}; the platform renders, hydrates, upgrades and patches it. The stylingApi lists the STABLE class names a template may target with CSS; anything not listed is internal and may change without notice.


| Island | Status | Label |
| --- | --- | --- |
| `donation_widget` | ✅ available | Donation widget |
| `member_menu` | ✅ available | Port60 ID sign-in / account menu |
| `events_carousel` | ✅ available | Events carousel |
| `whats_on_strip` | ✅ available | What's-on strip |
| `latest_articles` | ✅ available | Latest articles |
| `course_enrol` | ✅ available | Course enrolment widget |
| `next_prayer` | ✅ available | Next worship time |
| `article_engagement` | ✅ available | Article engagement |
| `article_comments` | ✅ available | Article comments |
| `hero_carousel` | ✅ available | Hero image carousel |
| `newsletter_signup` | ✅ available | Newsletter sign-up |
| `language_switch` | ✅ available | Language switch |
| `search` | ✅ available | Site search |
| `form` | ✅ available | Public form |
| `map` | ✅ available | Impact map |
| `volunteer_signup` | 🚧 planned | Volunteer sign-up |
| `primary_action_widget` | ✅ available | Primary action widget |

## `donation_widget`

**Donation widget**, available now

The full donation flow for the tenant's quick-give cause: suggested amounts, custom amount, donor details, Gift Aid opt-in, payment. All payment/compliance behaviour is platform-owned.

```liquid
{% island 'donation_widget' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.action-card`
- `.donate-card`
- `.donate-head`
- `.donate-sub`
- `.freq-tabs`
- `.freq-tab`
- `.amount-grid`
- `.amount-option`
- `.amount-list`
- `.amount-row`
- `.giftaid-box`
- `.donate-submit`
- `.donate-note`
- `.donate-success`

## `member_menu`

**Port60 ID sign-in / account menu**, available now

The branded Port60 ID entry point: the sign-in button (popup flow) for guests, the account pill (Members area / Sign out) for signed-in members. Renders NOTHING when the tenant doesn't allow member sign-ups. The identity brand and popup behaviour are platform-owned and identical across every template, place it in your header's nav; never rebuild it.

```liquid
{% island 'member_menu' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.nav-p60-signin`
- `.nav-account`
- `.nav-account-toggle`
- `.nav-account-menu`
- `.p60-mark`
- `.nav-p60-signin-label`
- `.nav-account-name`
- `.nav-account-caret`
- `.nav-account-icon`

## `events_carousel`

**Events carousel**, available now

The rotating showcase of published ticketed events. Renders nothing when the tenant has no matching published content.

```liquid
{% island 'events_carousel' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.events-carousel`
- `.carousel-slide`
- `.carousel-caption`
- `.carousel-dots`
- `.carousel-dot`

## `whats_on_strip`

**What's-on strip**, available now

The slim banner of upcoming info events. Renders nothing when the tenant has no matching published content.

```liquid
{% island 'whats_on_strip' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.info-events-bar`
- `.info-events-inner`
- `.info-event-chip`

## `latest_articles`

**Latest articles**, available now

A strip of the most recent published articles. Renders nothing when the tenant has no matching published content.

```liquid
{% island 'latest_articles' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.article-grid`
- `.article-card`
- `.article-card-body`
- `.article-strip-cta`

## `course_enrol`

**Course enrolment widget**, available now

The member-gated course enrolment journey (schedule options, household picker, payment, seat holds) for the course the page addresses. Only meaningful on the course page template (pages/course.liquid), place it where your layout wants the purchase column (left rail, right rail, or below the content); position in your source is position on the page. Everything inside is platform-owned; it renders a standard sold-out note when no places remain (branch on course.soldOut if you want your own tag elsewhere).

```liquid
{% island 'course_enrol' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.course-enrol`
- `.course-variant-list`
- `.course-subject-list`
- `.course-summary`
- `.course-pay-panel`
- `.course-soldout-note`

## `next_prayer`

**Next worship time**, available now

A live countdown to worship.next for the tenant's schedule. Renders nothing when no next time is available. The platform owns the clock; the template owns presentation through the stable classes.

```liquid
{% island 'next_prayer' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.next-prayer`
- `.next-prayer-label`
- `.next-prayer-name`
- `.next-prayer-time`
- `.next-prayer-countdown`

## `article_engagement`

**Article engagement**, available now

The platform-owned article views, likes and sharing bar for the article page being rendered.

```liquid
{% island 'article_engagement' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.article-engage`
- `.article-views`
- `.article-share-group`
- `.article-share-btn`
- `.article-share-word`
- `.article-share-copied`

## `article_comments`

**Article comments**, available now

The identity-aware article conversation for the article page being rendered. Renders the closed state when comments are disabled.

```liquid
{% island 'article_comments' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.article-comments`
- `.article-comment-list`
- `.article-comment`
- `.article-comment-head`
- `.article-comment-form`
- `.article-comments-gate`
- `.article-comments-note`

## `hero_carousel`

**Hero image carousel**, available now

Rotation for the home hero's photographs (homeHero.images, 2+): auto-advance every ~6s, pauses on hover/focus, honours prefers-reduced-motion (no auto-advance), swipe on touch, dot navigation. The platform owns the motion; the TEMPLATE owns the look, including the tonal treatment: every slide ships an empty .hero-slide-scrim layer over its image, and the template colours it from its OWN palette variables (a colour wash, a blend, a gradient) so any uploaded photo sits inside the template's tones. Renders nothing with fewer than 2 images, single-image and no-image states are the template's own renderer, not this island's.

```liquid
{% island 'hero_carousel' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.hero-carousel`
- `.hero-slides`
- `.hero-slide`
- `.hero-slide--active`
- `.hero-slide-img`
- `.hero-slide-scrim`
- `.hero-dots`
- `.hero-dot`
- `.hero-dot--active`

## `newsletter_signup`

**Newsletter sign-up**, available now

Explicit email opt-in over the platform's versioned consent and one-click unsubscribe rail. Templates own placement and presentation; wording, evidence and abuse checks remain platform-owned.

```liquid
{% island 'newsletter_signup' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.newsletter-signup`
- `.newsletter-label`
- `.newsletter-fields`
- `.newsletter-email`
- `.newsletter-submit`
- `.newsletter-consent`
- `.newsletter-message`

## `language_switch`

**Language switch**, available now

Switches between the platform's supported public languages while preserving the current route. The host supplies locale and text direction to Liquid and the document element.

```liquid
{% island 'language_switch' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.language-switch`
- `.language-switch-label`
- `.language-switch-select`

## `search`

**Site search**, available now

The site's search box: a typeahead over the platform's search index (articles, events, services, campaigns, appeals, volunteering and public documents; published and live rows only, never member, payment, private media or admin data). Suggestions are the things themselves, grouped by kind, each a direct link, with a matched-text line when the hit was in the body; Enter or the last row goes to the platform's /search results page. An accessible combobox: the active suggestion carries is-active. Where the box sits is the template's decision.

```liquid
{% island 'search' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.site-search`
- `.site-search-form`
- `.site-search-label`
- `.site-search-fields`
- `.site-search-input`
- `.site-search-submit`
- `.site-search-results`
- `.site-search-result`
- `.site-search-kind`
- `.site-search-link`
- `.site-search-summary`
- `.site-search-empty`
- `.site-search-title`
- `.site-search-context`
- `.site-search-more`
- `.site-search-corrected`

## `form`

**Public form**, available now

Renders the tenant's first published platform form and records its submission with explicit privacy acceptance. Templates cannot handle or redirect submissions themselves.

```liquid
{% island 'form' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.public-form`
- `.public-form-head`
- `.public-form-field`
- `.public-form-check`
- `.public-form-privacy`
- `.public-form-submit`
- `.public-form-message`

## `map`

**Impact map**, available now

The tenant's published impact map: a themed, privacy-clean map (platform-served tiles, never a third-party tile CDN) whose points open cards derived from the content they link. The island derives its colours from the template's tokens; v1 renders the tenant's first published map.

```liquid
{% island 'map' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.impact-map`
- `.impact-map-head`
- `.impact-map-intro`
- `.impact-map-canvas`
- `.impact-map-pin`
- `.impact-map-pin--active`
- `.impact-map-card`
- `.impact-map-card-kind`
- `.impact-map-card-title`
- `.impact-map-card-summary`
- `.impact-map-card-cta`
- `.impact-map-empty`

## `volunteer_signup`

**Volunteer sign-up**, planned (declaring it today is a validator warning, placing it renders nothing)

The volunteer sign-up flow: what to help with (general, then the events and campaigns that need people), when (only when the opportunity runs in shifts), a few details, then confirmation by a charity-branded email that also signs the volunteer in. Shares the donation widget's card vocabulary so a themed donate card themes this too; the vol-* classes cover what is specific to asking for help.

```liquid
{% island 'volunteer_signup' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.donate-card`
- `.action-card`
- `.vol-body`
- `.volunteer-card`
- `.vol-card`
- `.vol-chosen`
- `.vol-search`
- `.vol-list`
- `.vol-group`
- `.vol-group-label`
- `.vol-option`
- `.vol-option-main`
- `.vol-option-summary`
- `.vol-option-meta`
- `.vol-needed`
- `.vol-shift-count`
- `.vol-form`
- `.vol-availability`
- `.vol-chips`
- `.vol-chip`
- `.vol-confirm`
- `.vol-optional`
- `.vol-why`
- `.vol-extra`
- `.vol-summary`
- `.vol-signed-in`
- `.vol-summary-needed`
- `.vol-field-error`

## `primary_action_widget`

**Primary action widget**, available now

The widget that leads the site. It IS the donation widget when the charity chose giving to lead, the volunteer sign-up when volunteering leads, and nothing when the charity chose no widget in the hero; site.focus tells you which ('donate', 'volunteer' or 'none'). Place {% island 'primary_action_widget' %} in the home hero's widget slot INSTEAD of donation_widget whenever your template declares supports.focus: the platform decides which widget renders, the template never does, and the charity's switch moves it without a template change. Both widgets wear .action-card for shared treatment; .donate-card and .volunteer-card carry kind-specific styling. A template that wants a different layout per kind may branch on section.primary.kind and place donation_widget or volunteer_signup itself, but then it owns the switch.

```liquid
{% island 'primary_action_widget' %}
```

**Styling API**, the stable class names your theme.css may target (anything else is internal and may change without notice):

- `.action-card`
- `.donate-card`
- `.volunteer-card`

━━ reference/layout.md ━━


:::note[Generated reference]
This page is generated from the machine-readable contract the platform engine enforces (`contract/v1`). It cannot drift from production behaviour.
:::


How platform pages are placed inside a template. Every platform page (donate, services, events, campaigns, the members area) renders through a fixed set of LAYOUT INTENTS, the content SEAM. A template STYLES these intents to place content its way; it must never build a parallel content container, or platform pages drift from the template's own sections. Enforced at publish by the conformance validator.


## The content seam

| Class | Intent | Notes |
| --- | --- | --- |
| `.container` | contained | The contained content column, text, forms, cards. Style it (and override --container) to set your content width and gutter. Use it in your own layout and sections too, so everything shares one column. |
| `.full` | full-bleed | Edge-to-edge regardless of the container it sits in, a hero image, a colour band. Restyle it freely; the default breaks out to the viewport width. |

Set your content width with the `--container` token and style `.container`/`.full` in your `assets/theme.css`. Use `.container` in your own layout and sections too, so your chrome and every platform page share one column.


## The rule, enforced at publish


A selector other than `.container` / `.full` that sizes its width off `var(--container)` is **refused at publish, before review**, it builds its own content container from var(--container). Platform pages render inside .container, so a parallel container drifts from your sections, style .container instead (override --container for width and add your gutter there), and use .full for edge-to-edge.

```css
/* ✗ REJECTED, a parallel content container */
.mytheme-container { max-width: var(--container); margin: 0 auto; padding: 0 1.5rem; }

/* ✓ style the seam instead */
:root:root { --container: min(1200px, 92vw); }
.container { padding-inline: 1.5rem; }
```

━━ reference/manifest.md ━━


:::note[Generated reference]
This page is generated from the machine-readable contract the platform engine enforces (`contract/v1`). It cannot drift from production behaviour.
:::


Every artifact ships a `manifest.json` validated against [a JSON Schema](https://developers.port60.co.uk/schemas/template-manifest-v1.json) at publish time. Required fields: `name`, `version`, `format`, `supports`.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | The template's identity, lowercase, hyphenated, stable across versions. |
| `version` | string | Semver. Stable versions are immutable once submitted. Owner-only development versions use x.y.z-dev.N, remain non-promotable, and may be replaced before creating a stable release. |
| `format` | `port60-liquid@1` | The dialect/contract major this template is written against. |
| `label` | string | Human-readable name shown in pickers. |
| `description` | string |  |
| `requiresCapabilities` | array | Platform capabilities this design needs in order to work as intended. This is a catalogue matching signal, never an entitlement grant. The validator checks that each declared capability has a corresponding section, page template, island or context surface. |
| `suitsProfiles` | array | Organisation profiles this design was composed for. An empty list means the template is general purpose. Profiles improve catalogue recommendations but do not hide or unlock features. |
| `changelog` | string | One human line describing what THIS version changed, shown on the Appearance update nudge. |
| `supports` | object |  |
| `supports.pages` | array | Section based page bodies this template renders from sections/{type}.liquid. Contract v1 supports home and about. This is independent of layout chrome and route-specific pageTemplates. |
| `supports.sections` | array | Section types this template ships renderers for (sections/{type}.liquid). Unsupported types are omitted at render, never an error. |
| `supports.islands` | array | Islands this template places. Every {% island %} name must be listed here AND exist in the platform island registry. |
| `supports.layout` | boolean | True when the template ships layout.liquid and owns the page chrome (header/nav/footer). The platform still owns <head>, consent, and identity, see the layouts guide. |
| `supports.pageTemplates` | array | Route-specific data views rendered from pages/{page}.liquid with documented context. Events and articles own listings; course and article own detail presentation. Event transactions, course enrolment, article engagement, comments, identity and consent stay platform-owned islands. Requires supports.layout; without an entry the platform body renders inside the template chrome. |
| `supports.worship` | boolean | True when the layout renders the `worship` context (the prayer/service-times rail). Declared honesty: the choosers badge worship-enabled tenants toward looks that show their times, and warn on looks that don't. Requires supports.layout; the layout must actually branch on `worship`. |
| `supports.heroImagery` | boolean | True when the homeHero renderer displays the tenant's hero photographs (homeHero.images, legacy imageUrl), always under a TREATMENT built from the template's own palette variables (scrim/tint/blend), never raw. Declared honesty, proven behaviourally at validation: the choosers badge photo-led tenants toward templates that show their images and warn on ones that won't. Requires the homeHero section among supports.sections. |
| `supports.behaviors` | array | Engine-attached behaviours this template's markup opts into via data-p60-* attributes (see the behaviour catalogue). Templates never ship JavaScript; declaring here is what makes the engine wire the markup, and the validator proves declaration and usage agree in both directions. |
| `supports.focus` | array | The site-focus kinds this template can LEAD with (docs/volunteering.md). Declaring 'volunteer' means the home hero places the primary_action_widget island (the widget that becomes the donation widget or the volunteer sign-up as the charity chooses) or branches on section.primary.kind, so the volunteer sign-up can take the widget slot; the picker marks templates that cannot lead with volunteering. Templates that predate the setting keep rendering the donation widget, since donate is the default. |
| `imagery` | object | The template's OWN image advice, surfaced beside uploads in the charity's editor, a design statement (what shape suits THIS composition), advisory only, never enforced. Entity images (events, courses, articles) are platform-scoped instead: see the contract's imagery.json envelopes. |
| `imagery.hero` | object |  |
| `imagery.hero.idealAspect` | string | The aspect this hero composes best with, e.g. "16:9". |
| `imagery.hero.minWidth` | integer | Below this pixel width the photo may look soft full-bleed. |
| `imagery.hero.note` | string | One human line of advice, e.g. how panoramas or portraits behave in this hero. |
| `fonts` | array | Webfont stylesheet URLs the platform loads in <head> (with preconnects, never a CSS @import). Google Fonts css2 URLs only. |
| `looks` | array | One-click LOOKS: author-named bundles of knob values (scheme + fonts + width…) applied together. Everything remains individually adjustable afterwards. |
| `looks[].name` | string | The look's evocative, author-chosen name, shown as a one-click chip in Appearance. |
| `looks[].values` | object | Knob key → value. Every key must be a declared settings knob; select values must be listed options; font values must be catalogue families. |
| `compositions` | object | The template's preferred composition per supported page (site editor stage 4): the ordered section types it designs the page around, each with a role. `core` sections carry the design (removing one warns, never locks), `recommended` ones are on by default, `optional` ones are offered. A page a tenant never edited renders this composition; the Pages editor offers it as the order to reset to. |
| `settings` | object |  |
| `settings.schema` | array | The template's own theming knobs (colour schemes etc.), rendered as an editor in Appearance/get-started; values land in site-config config.theme. |
| `settings.schema[].key` | string |  |
| `settings.schema[].kind` | `color` \| `select` \| `toggle` \| `font` |  |
| `settings.schema[].label` | string |  |
| `settings.schema[].default` |  |  |
| `settings.schema[].options` | array |  |
| `settings.schema[].group` | `typography` \| `looks` | Where the admin surfaces this knob: 'typography' → the Typography section beside the font slots; 'looks' → the Looks section with the one-click bundles (colour schemes and accent dials belong there, and ungrouped color knobs plus a knob keyed 'scheme' default there anyway); other ungrouped knobs render under Template options. |
| `settings.schema[].weights` | array | FONT knobs only: the weights this template's typographic system uses for the slot. The host requests these for the tenant's chosen family (clamped to the family's real weights). The tenant picks the FAMILY; weights, sizes and tracking stay template-owned. |

## Worked example, the starter template's manifest

```json
{
  "name": "starter",
  "version": "1.13.0",
  "format": "port60-liquid@1",
  "label": "Starter",
  "description": "The reference template for the Port60 dialect, the developer docs' worked example and the base to copy when building your own. 1.1.0 adds the layout slot: the template owns the header, navigation and footer chrome.",
  "supports": {
    "pages": [
      "home",
      "about"
    ],
    "sections": [
      "homeHero",
      "hero",
      "values",
      "cta",
      "people",
      "campaigns",
      "impactMap"
    ],
    "islands": [
      "donation_widget",
      "member_menu",
      "hero_carousel",
      "map",
      "primary_action_widget",
      "search"
    ],
    "layout": true,
    "heroImagery": true,
    "behaviors": [
      "reveal",
      "carousel"
    ],
    "focus": [
      "donate",
      "volunteer"
    ]
  },
  "compositions": {
    "home": [
      {
        "type": "homeHero",
        "role": "core"
      },
      {
        "type": "campaigns",
        "role": "recommended"
      },
      {
        "type": "impactMap",
        "role": "optional"
      },
      {
        "type": "cta",
        "role": "recommended"
      }
    ],
    "about": [
      {
        "type": "hero",
        "role": "core"
      },
      {
        "type": "values",
        "role": "recommended"
      },
      {
        "type": "people",
        "role": "optional"
      },
      {
        "type": "cta",
        "role": "recommended"
      }
    ]
  },
  "settings": {
    "schema": [
      {
        "key": "siteFont",
        "kind": "font",
        "label": "Site font",
        "default": "Inter",
        "weights": [
          400,
          500,
          600,
          700,
          800
        ]
      }
    ]
  },
  "changelog": "Places the site search box in the header: a typeahead across events, articles, services, campaigns, appeals, volunteering and documents, with the results page at /search.",
  "imagery": {
    "hero": {
      "idealAspect": "16:9",
      "minWidth": 1600,
      "note": "Landscape around 16:9 fills the hero cleanly; panoramas suit the whole-photo framing."
    }
  }
}
```

━━ reference/sections.md ━━


:::note[Generated reference]
This page is generated from the machine-readable contract the platform engine enforces (`contract/v1`). It cannot drift from production behaviour.
:::


The content-section catalogue, the closed set of section types a page may hold and a template may render. Section type = content KIND (coarse); layout/variant is the template's job. Additive-only: types and fields are added, never removed or re-shaped, within a contract major. Every section is independently omittable, a template must degrade gracefully when any subset is absent.


## `hero`, Hero banner

The page opener: a headline with an optional kicker and sanitised rich-text intro.

**Pages:** `about`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `eyebrow` | text | no | Short kicker above the headline. |
| `title` | text | yes | The headline. |
| `bodyHtml` | richtext | no | Sanitised HTML intro, render with the raw filter. |

**Minimal fixture** (the least content your renderer must survive):

```json
{
  "title": "Our story"
}
```

**Sample fixture:**

```json
{
  "eyebrow": "About us",
  "title": "Neighbours, looked after.",
  "bodyHtml": "<p>The Lantern Trust began in 2011 with a soup pot, a borrowed hall and a belief that nobody in Alderford should face a hard winter alone. Today we run a food bank, a youth club, an advice service and a community garden, powered by more than a hundred volunteers.</p>"
}
```


## `values`, Values / list

A set of principles shown as cards or a numbered list, per the template.

**Pages:** `about`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `eyebrow` | text | no | Short kicker above the heading. |
| `heading` | text | no | The section heading. |
| `items` | items | yes | The value entries. |
| `items[].title` | text | yes | The value's name. |
| `items[].description` | text | yes | One sentence describing it. |
| `items[].icon` | icon | no | Optional emoji/icon. |

**Minimal fixture** (the least content your renderer must survive):

```json
{
  "items": [
    {
      "title": "Transparency",
      "description": "Every pound is tracked and reported."
    }
  ]
}
```

**Sample fixture:**

```json
{
  "eyebrow": "What we stand for",
  "heading": "Our values",
  "items": [
    {
      "title": "Openness",
      "description": "Every pound is tracked, reported and published in our annual accounts."
    },
    {
      "title": "Dignity",
      "description": "No referrals, no means tests at the door. If you say you need help, that is enough."
    },
    {
      "title": "Neighbourliness",
      "description": "We work alongside people, not for them. Most of our volunteers first came to us for help."
    }
  ]
}
```


## `cta`, Call to action

A closing band: heading, optional line, one button.

**Pages:** `home`, `about`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `heading` | text | yes | The band heading. |
| `text` | text | no | A supporting line. |
| `buttonLabel` | text | yes | The button's label. |
| `buttonHref` | url | yes | The button's destination (scheme-guarded on save). The editor's cause picker writes /donate/{slug} here and records causeId beside it (editor bookkeeping, renderers use buttonHref only and may ignore causeId). |

**Minimal fixture** (the least content your renderer must survive):

```json
{
  "heading": "Ready to help?",
  "buttonLabel": "Donate",
  "buttonHref": "/donate"
}
```

**Sample fixture:**

```json
{
  "heading": "Be somebody's good news today",
  "text": "A monthly gift keeps the shelves stocked and the hall warm.",
  "buttonLabel": "Donate now",
  "buttonHref": "/#donate"
}
```


## `homeHero`, Home hero

The home opener. EVERY field optional: eyebrow/title derive from branding when absent, the lead OMITS when absent (never a fabricated placeholder), buttons fall back to platform defaults.

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `eyebrow` | text | no | Defaults to the charity's name. |
| `title` | text | no | Defaults to the charity's tagline. |
| `lead` | text | no | A lead paragraph; omitted entirely when blank. |
| `primaryLabel` | text | no | Main button label (default: Donate now). |
| `primaryHref` | url | no | Main button link (default: #donate). |
| `secondaryLabel` | text | no | Second button label (default: Our story). |
| `secondaryHref` | url | no | Second button link (default: /about). |
| `givingStyle` | select | no | How this hero offers giving: 'form' (default) places the donation widget beside the copy; 'button' renders copy only, the primary button becomes the giving path (defaulting to /donate). Templates MUST render both. |
| `imageUrl` | image | no | Background photograph for the hero (uploaded through the platform pipeline). Superseded by `images` when that carries any entry, render imageUrl only when images is absent/empty. The template must TREAT the photo (scrim/tint from its own palette variables), never place it raw, and omit for its designed no-photo state. |
| `photoFraming` | select | no | How hero photographs meet the hero. 'fill' (default): the hero keeps its designed shape and photos crop to fill it (use each photo's focus to pick the surviving slice). 'whole': the hero adapts toward the photo's own shape (height-clamped) so the FULL scene stays visible, the vista treatment for wide landscape photographs; templates overlay or stack their copy accordingly. |
| `images` | items | no | Hero photographs (0–6, uploaded through the platform pipeline). One = a main image; several = rotation material, a template with supports.heroImagery renders at least the first and MAY place the hero_carousel island (or a CSS scroll strip) for the rest. Like every field: absent means the template's designed no-photo state, never a placeholder. |
| `images[].imageUrl` | image | yes | The photograph. |
| `images[].alt` | text | no | Accessible description; empty renders as decorative (alt=""). |
| `images[].focus` | select | no | Which part of the photograph survives the fill-crop (templates render photos cover-style, so an aspect mismatch crops, this picks the slice that stays). Maps to background-position/object-position; absent means centre. |

**Minimal fixture** (the least content your renderer must survive):

```json
{}
```

**Sample fixture:**

```json
{
  "lead": "We turn everyday generosity into food parcels, warm rooms and open doors across Alderford.",
  "givingStyle": "button",
  "images": [
    {
      "imageUrl": "p60fixture:hero/dusk",
      "alt": "Volunteers serving supper as the light fades"
    },
    {
      "imageUrl": "p60fixture:hero/river",
      "alt": "The lantern walk along the River Aldern"
    },
    {
      "imageUrl": "p60fixture:hero/garden",
      "alt": "Raised beds in the Foundry Lane community garden"
    }
  ]
}
```


## `impact`, Impact cards

What gifts make possible, optional intro plus icon/title/description cards. Claims must be truthful for the tenant.

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `eyebrow` | text | no | Short kicker. |
| `heading` | text | no | The section heading. |
| `text` | text | no | An intro line. |
| `items` | items | yes | The impact cards. |
| `items[].imageUrl` | image | no | Card image (uploaded through the platform pipeline). Preferred over icon. |
| `items[].icon` | icon | no | Legacy emoji/icon, superseded by imageUrl; render it only when imageUrl is absent. |
| `items[].title` | text | yes | The card title. |
| `items[].description` | text | yes | One sentence describing it. |

**Minimal fixture** (the least content your renderer must survive):

```json
{
  "items": [
    {
      "title": "Warm meals",
      "description": "Hot meals served at a community kitchen."
    }
  ]
}
```

**Sample fixture:**

```json
{
  "eyebrow": "Where your gift goes",
  "heading": "Real help, made of small acts",
  "items": [
    {
      "imageUrl": "p60fixture:impact/parcel",
      "title": "£10 · A family food parcel",
      "description": "Three days of meals, toiletries and a bag of fresh produce from the garden."
    },
    {
      "icon": "🔥",
      "title": "£25 · A warm week",
      "description": "Heating top-ups for a household choosing between eating and heating."
    },
    {
      "title": "£50 · A month of youth club",
      "description": "Coaching, kit and hot food for a young person, four evenings a week."
    }
  ]
}
```


## `whatsOn`, What's on

Upcoming info events (special days, no sign-up). Render the `infoEvents` context your way, or place {% island 'whats_on_strip' %} for the ready-made strip.

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |

**Places island:** [`whats_on_strip`](/reference/islands/#whatsonstrip)

**Minimal fixture** (the least content your renderer must survive):

```json
{}
```

**Sample fixture:**

```json
{}
```


## `events`, Events

Upcoming ticketed events on the home page. Your template renders the `events` context (the curated listing model) however its voice demands, or places {% island 'events_carousel' %} for the ready-made rotating showcase. Listing data only: ticket sales happen on the platform-rendered detail view (detailHref).

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |

**Places island:** [`events_carousel`](/reference/islands/#eventscarousel)

**Minimal fixture** (the least content your renderer must survive):

```json
{}
```

**Sample fixture:**

```json
{}
```


## `articles`, Latest articles

The newest published articles. Render the `latestArticles` context your way, or place {% island 'latest_articles' %} for the ready-made strip.

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |

**Places island:** [`latest_articles`](/reference/islands/#latestarticles)

**Minimal fixture** (the least content your renderer must survive):

```json
{}
```

**Sample fixture:**

```json
{}
```


## `campaigns`, Campaigns

The tenant's LIVE campaigns (appeals, petitions, surveys) as cards linking to each campaign's page. Render the `campaigns` context your way; render nothing when no campaign is live.

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `eyebrow` | text | no | Short kicker. |
| `heading` | text | no | The section heading; fall back to the campaignsLabel context when unset. |
| `text` | text | no | Optional introduction. |

**Minimal fixture** (the least content your renderer must survive):

```json
{}
```

**Sample fixture:**

```json
{
  "eyebrow": "Get involved",
  "heading": "What we are campaigning for",
  "text": "The changes Alderford is asking for right now, and how to add your voice."
}
```


## `emergency`, Emergency appeal strip

A high-urgency full-width strip, one headline, an optional line, one action. For live emergencies and time-critical appeals.

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `heading` | text | yes | The urgent headline. |
| `text` | text | no | One supporting line. |
| `buttonLabel` | text | no | Action label (default: Donate now). |
| `buttonHref` | url | no | Action link (default: /donate). Scheme-guarded on save. |

**Minimal fixture** (the least content your renderer must survive):

```json
{
  "heading": "Emergency appeal"
}
```

**Sample fixture:**

```json
{
  "heading": "Flood response appeal",
  "text": "The Aldern broke its banks on Sunday. Thirty households need dry bedding and warmth now.",
  "buttonLabel": "Give to the flood response",
  "buttonHref": "/donate"
}
```


## `stats`, Stats band

Big headline numbers, the at-a-glance impact band. Values are author-entered text (write them exactly as they should read), or, per item, a live figure the platform counts (`source`).

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `eyebrow` | text | no | Short kicker. |
| `heading` | text | no | The band heading. |
| `items` | items | yes | The stat entries. |
| `items[].value` | text | yes | The number, as it should read (e.g. 12,000 or 98%). |
| `items[].label` | text | yes | What it counts (e.g. meals served). |
| `items[].source` | select | no | A figure the platform counts rather than the author types (volunteers who helped in the last twelve months, hours logged this year, opportunities open now, volunteers still needed). When set, `value` is replaced at render with the live count, formatted for the site's locale; templates render `value` exactly as before. |

**Minimal fixture** (the least content your renderer must survive):

```json
{
  "items": [
    {
      "value": "1,200",
      "label": "meals served"
    }
  ]
}
```

**Sample fixture:**

```json
{
  "eyebrow": "Last year",
  "heading": "What your giving did",
  "items": [
    {
      "value": "9,200",
      "label": "food parcels packed"
    },
    {
      "value": "1,400",
      "label": "warm space visits"
    },
    {
      "value": "96p",
      "label": "of every pound spent in Alderford"
    }
  ]
}
```


## `appealGrid`, Appeal cards

A grid of appeal/campaign cards, image, title, a line, and a per-card action.

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `eyebrow` | text | no | Short kicker. |
| `heading` | text | no | The section heading. |
| `items` | items | yes | The appeal cards. |
| `items[].imageUrl` | image | no | Card photograph (uploaded through the platform pipeline). |
| `items[].title` | text | yes | The appeal's name. |
| `items[].text` | text | yes | One sentence on what it funds. |
| `items[].buttonLabel` | text | no | Card action label (default: Donate). |
| `items[].buttonHref` | url | no | Card action link (default: /donate). Scheme-guarded on save. The cause picker writes /donate/{slug} and records causeId beside it (editor bookkeeping; renderers use buttonHref only). |

**Minimal fixture** (the least content your renderer must survive):

```json
{
  "items": [
    {
      "title": "Winter appeal",
      "text": "Warm meals through the coldest months."
    }
  ]
}
```

**Sample fixture:**

```json
{
  "eyebrow": "Our appeals",
  "heading": "Where help is needed most",
  "items": [
    {
      "title": "Winter Appeal",
      "text": "Heating top-ups, warm bedding and a hot meal through the coldest months.",
      "buttonLabel": "Support winter",
      "buttonHref": "/donate"
    },
    {
      "title": "Food Bank Fund",
      "text": "Ten pounds fills a family parcel and keeps the depot shelves stocked.",
      "buttonLabel": "Fill a parcel",
      "buttonHref": "/donate"
    }
  ]
}
```


## `programmes`, Services and programmes

The tenant's published services and programmes as a dynamic card collection. Render the services context and omit the section when it is empty.

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `eyebrow` | text | no | Short kicker. |
| `heading` | text | no | The section heading. |
| `text` | text | no | Optional introduction. |

**Minimal fixture** (the least content your renderer must survive):

```json
{}
```

**Sample fixture:**

```json
{
  "eyebrow": "What we do",
  "heading": "Support that meets you where you are",
  "text": "Food, advice, activity and company: five programmes, one front door."
}
```


## `resources`, Resource library

Public documents from the tenant's media library. The resources context contains PUBLIC documents only; private files and storage metadata never reach Liquid.

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `eyebrow` | text | no | Short kicker. |
| `heading` | text | no | The section heading. |
| `text` | text | no | Optional introduction. |

**Minimal fixture** (the least content your renderer must survive):

```json
{}
```

**Sample fixture:**

```json
{
  "eyebrow": "Resources",
  "heading": "Reports and documents",
  "text": "Our accounts, policies and handbooks, all in one place."
}
```


## `locations`, Locations

The tenant's public venue directory with safe directions links. Provider references and private venue notes are never exposed.

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `eyebrow` | text | no | Short kicker. |
| `heading` | text | no | The section heading. |
| `text` | text | no | Optional introduction. |

**Minimal fixture** (the least content your renderer must survive):

```json
{}
```

**Sample fixture:**

```json
{
  "eyebrow": "Find us",
  "heading": "Where to find us",
  "text": "Two front doors in the middle of Alderford, both step-free."
}
```


## `people`, People / team

The key people behind the charity, trustees, staff, volunteers, as simple cards: name, position, an optional photograph (uploaded through the platform pipeline) and an optional one-line statement. Templates render a card grid that collapses to a single column on small screens; a card without a photo renders cleanly (initials or plain), never a placeholder face.

**Pages:** `about`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `eyebrow` | text | no | Short kicker, e.g. Who we are. |
| `heading` | text | no | The section heading, e.g. Our team. |
| `text` | text | no | An optional intro line. |
| `items` | items | yes | The people. |
| `items[].name` | text | yes | The person's name. |
| `items[].role` | text | yes | Their position, e.g. Chair of Trustees. |
| `items[].imageUrl` | image | no | A photograph (platform pipeline). Absent renders cleanly, never a placeholder face. |
| `items[].statement` | text | no | One line in their voice, e.g. why they serve. |

**Minimal fixture** (the least content your renderer must survive):

```json
{
  "items": [
    {
      "name": "Amina Khan",
      "role": "Chair of Trustees"
    }
  ]
}
```

**Sample fixture:**

```json
{
  "eyebrow": "Who we are",
  "heading": "The people behind the work",
  "text": "A small staff team, a board of local trustees, and more than a hundred volunteers, accountable to you.",
  "items": [
    {
      "name": "Priya Sharma",
      "role": "Chair of Trustees",
      "imageUrl": "p60fixture:people/priya/portrait",
      "statement": "Every pound is a trust. We spend it like a neighbour is watching, because one is."
    },
    {
      "name": "Derek Osei",
      "role": "Food Bank Lead",
      "imageUrl": "p60fixture:people/derek/portrait"
    },
    {
      "name": "Sara Malik",
      "role": "Volunteer Coordinator",
      "statement": "A hundred pairs of hands, one purpose."
    }
  ]
}
```


## `impactMap`, Impact map

The organisation's impact map: a themed map whose points link existing content (campaigns, causes, articles, events, places), each opening a card derived from the linked thing. Place the `map` island, it brings the map, the points and the cards; your template brings placement and tokens (the island theming contract).

**Pages:** `home`

| Field | Kind | Required | Description |
| --- | --- | --- | --- |
| `eyebrow` | text | no | Short kicker. |
| `heading` | text | no | The section heading. |
| `text` | text | no | Optional introduction. |
| `mapSlug` | text | no | WHICH map renders here, by its address (the Pages editor's placement picker writes it; the Maps area is where maps exist). Absent = the tenant's first published map. |

**Minimal fixture** (the least content your renderer must survive):

```json
{}
```

**Sample fixture:**

```json
{
  "eyebrow": "Where we work",
  "heading": "Our impact, on the map",
  "text": "Every marker is a real place: a programme, an appeal, a story. Click one to see what happens there."
}
```


━━ reference/starter-source.md ━━


:::note[Generated reference]
This page is generated from the machine-readable contract the platform engine enforces (`contract/v1`). It cannot drift from production behaviour.
:::


The complete, publishable source of the reference template, copy it as the base for your own. This is the exact artifact published as `starter@1.13.0`.


## `assets/theme.css`

```css
/* starter theme, a deliberately distinct look (midnight/emerald) proving the artifact owns the skin */
:root:root {
  --bg: #0e1614;
  --bg-tint: #14201d;
  --surface: #16231f;
  --ink: #eef6f2;
  --muted: #93a8a0;
  --primary: #2dd4a7;
  --primary-strong: #19b28a;
  --primary-soft: rgba(45, 212, 167, 0.14);
  --accent: #f2b23e;
  --accent-strong: #d99a24;
  --line: rgba(238, 246, 242, 0.14);
  --line-strong: rgba(45, 212, 167, 0.4);
  --shadow-sm: 0 8px 24px rgba(0, 0, 0, 0.35);
  --shadow: 0 24px 60px rgba(0, 0, 0, 0.5);
  --radius: 10px;
  --radius-sm: 7px;
}
body { background: var(--bg); }
h1, h2, h3, h4 { color: var(--ink); font-family: 'IBM Plex Sans Arabic', var(--p60s-siteFont, 'Inter'), sans-serif; letter-spacing: -0.02em; margin: 0 0 1rem; line-height: 1.1; }
h1 { font-size: clamp(2.4rem, 5vw, 3.6rem); }
h2 { font-size: clamp(1.7rem, 3vw, 2.4rem); }
h3 { font-size: 1.15rem; }
p { color: var(--muted); line-height: 1.7; margin: 0 0 1rem; }
strong { color: var(--ink); }
.site-header { background: rgba(14, 22, 20, 0.86); }
.lq-hero { padding: 4.5rem 0 2.5rem; border-bottom: 1px solid var(--line); }
.lq-kicker { display: inline-block; border: 1px solid var(--line-strong); color: var(--primary); border-radius: 4px; padding: 0.3rem 0.8rem; font-size: 0.75rem; letter-spacing: 0.14em; text-transform: uppercase; font-weight: 700; }
.lq-hero h1 { margin-top: 1rem; max-width: 18ch; }
.lq-hero-body { max-width: 62ch; }
.lq-values { padding: 3.5rem 0; }
.lq-value-rail { list-style: none; margin: 0; padding: 0 0 0 1.4rem; border-left: 2px solid var(--line-strong); display: grid; gap: 1.6rem; max-width: 700px; }
.lq-value-rail li { position: relative; }
.lq-value-dot { position: absolute; left: -1.75rem; top: 0.35rem; width: 0.65rem; height: 0.65rem; border-radius: 50%; background: var(--primary); box-shadow: 0 0 0 4px var(--primary-soft); }
.lq-value-rail h3 { margin: 0 0 0.25rem; }
.lq-value-rail p { margin: 0; }
.lq-cta { padding: 3.5rem 0 4.5rem; }
.lq-cta-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 2.5rem; align-items: start; }
@media (max-width: 900px) { .lq-cta-grid { grid-template-columns: 1fr; } }

/* The one font slot, headings above already follow it; body text too. */
body { font-family: ' IBM Plex Sans Arabic', var(--p60s-siteFont, 'Inter'), ui-sans-serif, system-ui, sans-serif; }

/* ── Home hero (supports.heroImagery, the reference treatment) ─────────────────────────────
   The no-photo state is a DESIGNED gradient (rule: derive or omit, never a placeholder image).
   Photos get a scrim built from the palette itself via color-mix, so uploads tone into the
   template, and any palette change re-tones them for free. Never place a hero photo raw. */
.lq-homehero {
  position: relative;
  padding: 4.5rem 0;
  background:
    radial-gradient(720px 380px at 85% -10%, var(--primary-soft), transparent 60%),
    linear-gradient(165deg, var(--bg-tint) 0%, var(--bg) 100%);
}
.lq-homehero--photo { background-size: cover; background-position: center; }
.lq-homehero--photo::before {
  content: '';
  position: absolute;
  inset: 0;
  background: linear-gradient(
    180deg,
    color-mix(in srgb, var(--bg) 68%, transparent) 0%,
    color-mix(in srgb, var(--bg) 38%, transparent) 50%,
    color-mix(in srgb, var(--bg-tint) 72%, transparent) 100%
  );
}
.lq-homehero > .container { position: relative; z-index: 1; }
.lq-homehero-inner { display: grid; gap: 2.5rem; align-items: center; }
@media (min-width: 900px) {
  .lq-homehero-inner { grid-template-columns: 1.2fr 1fr; }
}
.lq-homehero-lead { color: var(--muted); max-width: 46ch; margin: 0.9rem 0 1.4rem; }
.lq-homehero-actions { display: flex; gap: 0.8rem; flex-wrap: wrap; }

/* The platform hero_carousel island, styled through its class API, the island owns motion
   (auto-advance, swipe, reduced-motion), this owns the look. Each slide's .hero-slide-scrim is
   the same palette treatment as a single photo. */
.lq-homehero--carousel { overflow: hidden; }
.lq-homehero--carousel .hero-carousel { position: absolute; inset: 0; z-index: 0; }
.lq-homehero--carousel .hero-slides,
.lq-homehero--carousel .hero-slide { position: absolute; inset: 0; }
.lq-homehero--carousel .hero-slide { opacity: 0; transition: opacity 1s ease; }
.lq-homehero--carousel .hero-slide--active { opacity: 1; }
.lq-homehero--carousel .hero-slide-img { width: 100%; height: 100%; object-fit: cover; display: block; }
.lq-homehero--carousel .hero-slide-scrim {
  position: absolute;
  inset: 0;
  background: linear-gradient(
    180deg,
    color-mix(in srgb, var(--bg) 68%, transparent) 0%,
    color-mix(in srgb, var(--bg) 38%, transparent) 50%,
    color-mix(in srgb, var(--bg-tint) 72%, transparent) 100%
  );
}
.lq-homehero--carousel .hero-dots {
  position: absolute;
  left: 0;
  right: 0;
  bottom: 0.8rem;
  display: flex;
  justify-content: center;
  gap: 0.4rem;
  z-index: 2;
}
.lq-homehero--carousel .hero-dot {
  width: 9px;
  height: 9px;
  border-radius: 50%;
  border: 1px solid var(--accent);
  background: transparent;
  padding: 0;
  cursor: pointer;
}
.lq-homehero--carousel .hero-dot--active { background: var(--accent); }

/* ── Vista framing (photoFraming 'whole'), the hero adapts to the PHOTO's shape ───────────── */
.lq-homehero--vista { padding-top: 0; }
.lq-vista { position: relative; overflow: hidden; }
.lq-vista-sizer { display: block; width: 100%; height: auto; max-height: 74vh; object-fit: cover; }
.lq-vista-scrim,
.lq-homehero--vista .hero-slide-scrim {
  position: absolute;
  inset: 0;
  pointer-events: none;
  background: linear-gradient(
    180deg,
    color-mix(in srgb, var(--bg) 45%, transparent) 0%,
    color-mix(in srgb, var(--bg) 12%, transparent) 40%,
    color-mix(in srgb, var(--bg-tint) 60%, transparent) 100%
  );
}
.lq-homehero--vista .lq-homehero-inner { padding-top: 2.4rem; }
.lq-homehero--vista .hero-carousel { position: absolute; inset: 0; z-index: 0; }

/* Vista 1.5.1: copy ON the photograph (strengthened lower scrim); the widget follows in its
   own strip; narrow screens flow the copy back underneath. */
.lq-vista-copy { position: absolute; inset-inline: 0; bottom: 0; padding: 1.4rem 0 2rem; z-index: 1; }
.lq-homehero--vista .lq-vista-scrim,
.lq-homehero--vista .hero-slide-scrim {
  background: linear-gradient(
    180deg,
    color-mix(in srgb, var(--bg) 38%, transparent) 0%,
    color-mix(in srgb, var(--bg) 10%, transparent) 38%,
    color-mix(in srgb, var(--bg-tint) 82%, transparent) 100%
  );
}
.lq-vista-sizer { min-height: 280px; }
.lq-vista-widget { padding: 2.2rem 0 0; display: flex; justify-content: center; }
.lq-vista-widget aside { width: min(560px, 100%); }
@media (max-width: 720px) {
  .lq-vista-copy { position: static; padding: 1.8rem 0 0; }
  .lq-vista-sizer { min-height: 160px; }
}

/* Vista + form (1.5.2): the widget rides the seam, grid pulled up over the band (under the
   280px floor), gradient filling where the image ends; narrow screens stack back underneath. */
.lq-homehero--vista-form { padding-bottom: 2.6rem; }
.lq-vista-overlap { position: relative; z-index: 1; margin-top: -240px; align-items: start; }
@media (max-width: 899px) {
  .lq-vista-overlap { margin-top: 0; padding-top: 1.6rem; }
}

/* People / team cards, grid to single column on phones. */
.lq-people {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
  gap: 1.2rem;
  text-align: center;
}
.lq-person {
  background: var(--surface);
  border: 1px solid var(--line);
  border-radius: 12px;
  padding: 1.4rem 1.1rem;
}
.lq-person-photo {
  width: 88px;
  height: 88px;
  border-radius: 50%;
  object-fit: cover;
  display: block;
  margin: 0 auto 0.8rem;
}
.lq-person-role { margin: 0.15rem 0 0; font-size: 0.9rem; color: var(--muted); }
.lq-person-statement { margin: 0.7rem 0 0; font-style: italic; color: var(--muted); }
@media (max-width: 640px) {
  .lq-people { grid-template-columns: 1fr; }
}

/* Campaigns, the same quiet rail as values: title, summary, one action. */
.lq-campaigns { padding: 3.5rem 0; }
.lq-campaign-list { list-style: none; margin: 0; padding: 0; display: grid; gap: 1.6rem; max-width: 700px; }
.lq-campaign h3 { margin: 0 0 0.25rem; }
.lq-campaign p { margin: 0 0 0.6rem; }

/* Behaviours (engine-wired via data-p60-*, docs: Motion and behaviour guide). Everything that
   hides pre-behaviour content is .p60-js-scoped: the no-JS render stays complete. */

/* Reveal: the values rail rises in with a stagger. */
.p60-js .lq-value-rail li {
  opacity: 0;
  transform: translateY(0.6rem);
  transition: opacity 480ms ease, transform 480ms ease;
  transition-delay: calc(var(--p60-reveal-index, 0) * 90ms);
}
.p60-js .lq-value-rail.is-revealed li { opacity: 1; transform: none; }
@media (prefers-reduced-motion: reduce) {
  .p60-js .lq-value-rail li { opacity: 1; transform: none; transition: none; }
}

/* Behaviour carousel: the standard hero's photo stack (the vista framings use the island). */
.lq-hero-slides { position: absolute; inset: 0; overflow: hidden; }
.lq-hero-slide { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
.p60-js .lq-hero-slide { opacity: 0; transition: opacity 700ms ease; }
.p60-js .lq-hero-slide.is-active { opacity: 1; }
.lq-hero-slides .p60-carousel-dots {
  position: absolute;
  inset-inline: 0;
  bottom: 0.9rem;
  display: flex;
  justify-content: center;
  gap: 0.45rem;
  z-index: 2;
}
.lq-hero-slides .p60-carousel-dot {
  width: 0.55rem;
  height: 0.55rem;
  border-radius: 50%;
  border: 1px solid rgba(255, 255, 255, 0.9);
  background: transparent;
  padding: 0;
  cursor: pointer;
}
.lq-hero-slides .p60-carousel-dot--active { background: rgba(255, 255, 255, 0.95); }
```

## `layout.liquid`

```liquid
{% comment %}
  The starter's chrome, header/nav/footer around the {% content %} slot. It reuses the platform
  chrome classes (.site-header/.site-nav/…) so the base mechanics (sticky header, burger
  breakpoint, dropdown hover) apply, and emits the documented behaviour attributes
  (data-nav-burger, #site-nav) so the platform tail script wires the mobile burger. Identity is
  PLACED, never rebuilt: {% island 'member_menu' %} and {% island 'search' %}. The footer derives everything from brand/nav, no fabricated copy (derive or omit).
{% endcomment %}
<header class="site-header">
  <div class="container header-inner">
    <a class="brand-lockup" href="/">
      {% if site.brand.logoUrl and site.brand.logoType != 'icon' %}
        <img class="brand-logo" src="{{ site.brand.logoUrl }}" alt="{{ site.brand.name }}">
      {% elsif site.brand.logoUrl %}
        <img class="brand-logo-icon" src="{{ site.brand.logoUrl }}" alt="">
        <strong>{{ site.brand.name }}</strong>
      {% else %}
        <span class="brand-mark" aria-hidden="true">♥</span>
        <strong>{{ site.brand.name }}</strong>
      {% endif %}
    </a>

    <button type="button" class="nav-burger" data-nav-burger aria-label="Menu" aria-expanded="false" aria-controls="site-nav">
      <span aria-hidden="true"></span>
      <span aria-hidden="true"></span>
      <span aria-hidden="true"></span>
    </button>

    <nav class="site-nav" id="site-nav" aria-label="Primary">
      {% for item in site.nav.items %}
        {% if item.children %}
          <span class="nav-dropdown">
            <a href="{{ item.href }}" class="nav-dropdown-toggle" aria-haspopup="true">{{ item.label }} ▾</a>
            <span class="nav-dropdown-menu">
              {% for child in item.children %}
                <a href="{{ child.href }}"{% if child.external %} target="_blank" rel="noopener"{% endif %}>{{ child.label }}</a>
              {% endfor %}
            </span>
          </span>
        {% elsif item.cta %}
          <a class="nav-cta" href="{{ item.href }}"{% if item.external %} target="_blank" rel="noopener"{% endif %}>{{ item.label }}</a>
        {% else %}
          <a href="{{ item.href }}"{% if item.external %} target="_blank" rel="noopener"{% endif %}>{{ item.label }}</a>
        {% endif %}
      {% endfor %}
      {% island 'search' %}
      {% island 'member_menu' %}
    </nav>
  </div>
</header>

<main>
  {% content %}
</main>

<footer class="site-footer">
  <div class="container footer-grid">
    <div>
      <p class="lq-kicker">{{ site.brand.name }}</p>
      {% if site.brand.tagline %}<h2>{{ site.brand.tagline }}</h2>{% endif %}
    </div>
    <div class="footer-links">
      {% comment %} A tenant-curated footer menu when they've built one, else the main site.nav. {% endcomment %}
      {% if site.nav.footer.size > 0 %}
        {% for item in site.nav.footer %}
          <a href="{{ item.href }}"{% if item.external %} target="_blank" rel="noopener"{% endif %}>{{ item.label }}</a>
          {% for child in item.children %}
            <a href="{{ child.href }}"{% if child.external %} target="_blank" rel="noopener"{% endif %}>{{ child.label }}</a>
          {% endfor %}
        {% endfor %}
      {% else %}
        {% for item in site.nav.items %}
          <a href="{{ item.href }}">{{ item.label }}</a>
        {% endfor %}
      {% endif %}
    </div>
  </div>
  <div class="container">
    <p class="footer-note">
      <span class="footer-legal-links">
        <a href="/cookies">Cookies</a>
        · <button type="button" class="footer-linklike" data-consent-open>Cookie settings</button>
      </span>
    </p>
  </div>
</footer>
```

## `manifest.json`

```json
{
  "name": "starter",
  "version": "1.13.0",
  "format": "port60-liquid@1",
  "label": "Starter",
  "description": "The reference template for the Port60 dialect, the developer docs' worked example and the base to copy when building your own. 1.1.0 adds the layout slot: the template owns the header, navigation and footer chrome.",
  "supports": {
    "pages": [
      "home",
      "about"
    ],
    "sections": [
      "homeHero",
      "hero",
      "values",
      "cta",
      "people",
      "campaigns",
      "impactMap"
    ],
    "islands": [
      "donation_widget",
      "member_menu",
      "hero_carousel",
      "map",
      "primary_action_widget",
      "search"
    ],
    "layout": true,
    "heroImagery": true,
    "behaviors": [
      "reveal",
      "carousel"
    ],
    "focus": [
      "donate",
      "volunteer"
    ]
  },
  "compositions": {
    "home": [
      {
        "type": "homeHero",
        "role": "core"
      },
      {
        "type": "campaigns",
        "role": "recommended"
      },
      {
        "type": "impactMap",
        "role": "optional"
      },
      {
        "type": "cta",
        "role": "recommended"
      }
    ],
    "about": [
      {
        "type": "hero",
        "role": "core"
      },
      {
        "type": "values",
        "role": "recommended"
      },
      {
        "type": "people",
        "role": "optional"
      },
      {
        "type": "cta",
        "role": "recommended"
      }
    ]
  },
  "settings": {
    "schema": [
      {
        "key": "siteFont",
        "kind": "font",
        "label": "Site font",
        "default": "Inter",
        "weights": [
          400,
          500,
          600,
          700,
          800
        ]
      }
    ]
  },
  "changelog": "Places the site search box in the header: a typeahead across events, articles, services, campaigns, appeals, volunteering and documents, with the results page at /search.",
  "imagery": {
    "hero": {
      "idealAspect": "16:9",
      "minWidth": 1600,
      "note": "Landscape around 16:9 fills the hero cleanly; panoramas suit the whole-photo framing."
    }
  }
}
```

## `sections/campaigns.liquid`

```liquid
{% comment %}
  Live site.content.campaigns, the starter's plain rendering of the `site.content.campaigns` context, kept simple on
  purpose: this template is the worked example template authors copy from. The context is the
  platform's published site.content.campaigns; hrefs are platform-derived, always link via campaign.href.
  Derive or omit: nothing renders when no campaign is live.
{% endcomment %}
{% if site.content.campaigns.size > 0 %}
<section class="lq-site.content.campaigns">
  <div class="container">
    <h2>{{ section.heading | default: campaignsLabel }}</h2>
    {% if section.text %}<p>{{ section.text }}</p>{% endif %}
    <ul class="lq-campaign-list">
      {% for campaign in site.content.campaigns %}
      <li class="lq-campaign">
        <h3>{{ campaign.title }}</h3>
        {% if campaign.summary %}<p>{{ campaign.summary }}</p>{% endif %}
        <a class="button button-primary" href="{{ campaign.href }}">View campaign</a>
      </li>
      {% endfor %}
    </ul>
  </div>
</section>
{% endif %}
```

## `sections/cta.liquid`

```liquid
<section class="lq-cta">
  <div class="container lq-cta-grid">
    <div>
      <h2>{{ section.heading }}</h2>
      {% if section.text %}<p>{{ section.text }}</p>{% endif %}
      <a class="button button-primary" href="{{ section.buttonHref }}">{{ section.buttonLabel }}</a>
    </div>
    <div class="lq-cta-widget">
      {% island 'donation_widget' %}
    </div>
  </div>
</section>
```

## `sections/hero.liquid`

```liquid
<section class="lq-hero">
  <div class="container">
    {% if section.eyebrow %}<p class="lq-kicker">{{ section.eyebrow }}</p>{% endif %}
    <h1>{{ section.title }}</h1>
    <div class="lq-hero-body">{{ section.bodyHtml | raw }}</div>
  </div>
</section>
```

## `sections/homeHero.liquid`

```liquid
{% comment %}
  The home opener, and the REFERENCE IMPLEMENTATION of supports.heroImagery. Rules worth
  copying:

  1. EVERY field is optional. Copy derives from brand (| default) or omits; no photos means the
     designed gradient below, never a placeholder image.
  2. Photos are NEVER placed raw. The treatments in theme.css lay scrims built from the palette
     variables (color-mix over var(--bg)/var(--bg-tint)), so any uploaded photograph is toned
     into the template. Tune the treatment, don't remove it.
  3. Rotation is the PLATFORM's hero_carousel island (templates ship no JavaScript): with two or
     more photos, place it and style its documented classes.
  4. photoFraming is the charity's call, honour BOTH: 'fill' (default) covers your designed hero
     shape (per-photo focus picks the surviving slice); 'whole' is the VISTA, the hero adapts
     toward the photo's own shape (height-clamped) so a wide landscape stays entirely visible,
     with your copy stacked after the band.
{% endcomment %}
{% assign heroCount = section.images | size %}
{% if heroCount == 1 %}
  {% assign heroPhoto = section.images.first.imageUrl %}
{% elsif heroCount == 0 %}
  {% assign heroPhoto = section.imageUrl %}
{% endif %}
{% assign heroFocus = 'center' %}
{% if heroCount > 0 %}
  {% case section.images.first.focus %}
    {% when 'top' %}{% assign heroFocus = 'center top' %}
    {% when 'bottom' %}{% assign heroFocus = 'center bottom' %}
    {% when 'left' %}{% assign heroFocus = 'left center' %}
    {% when 'right' %}{% assign heroFocus = 'right center' %}
  {% endcase %}
{% endif %}
{% assign heroFraming = section.photoFraming | default: 'fill' %}
{% if heroCount > 0 and heroFraming == 'whole' %}
{% if section.actionStyle == 'button' or section.givingStyle == 'button' %}
<section class="lq-homehero lq-homehero--vista{% if heroCount > 1 %} lq-homehero--carousel{% endif %}">
  <div class="lq-vista">
    <img class="lq-vista-sizer" src="{{ section.images.first.imageUrl }}" alt="{{ section.images.first.alt }}" style="object-position: {{ heroFocus }}" fetchpriority="high" decoding="async">
    {% if heroCount > 1 %}{% island 'hero_carousel' %}{% else %}<div class="lq-vista-scrim" aria-hidden="true"></div>{% endif %}
    <div class="lq-vista-copy">
      <div class="container">
        <p class="lq-kicker">{{ section.eyebrow | default: site.brand.name }}</p>
        <h1>{{ section.title | default: site.brand.tagline | default: site.brand.name }}</h1>
        {% if section.lead %}<p class="lq-homehero-lead">{{ section.lead }}</p>{% endif %}
        <div class="lq-homehero-actions">
          <a class="button button-primary" href="{{ section.primaryHref | default: '/donate' }}">{{ section.primaryLabel | default: 'Donate now' }}</a>
          <a class="button" href="{{ section.secondaryHref | default: '/about' }}">{{ section.secondaryLabel | default: 'Our story' }}</a>
        </div>
      </div>
    </div>
  </div>
</section>
{% else %}
{% comment %} Form mode: the grid pulls up over the band, copy on the photo, the widget riding
    the seam onto the gradient below (never a stacked strip). {% endcomment %}
<section class="lq-homehero lq-homehero--vista lq-homehero--vista-form{% if heroCount > 1 %} lq-homehero--carousel{% endif %}">
  <div class="lq-vista">
    <img class="lq-vista-sizer" src="{{ section.images.first.imageUrl }}" alt="{{ section.images.first.alt }}" style="object-position: {{ heroFocus }}" fetchpriority="high" decoding="async">
    {% if heroCount > 1 %}{% island 'hero_carousel' %}{% else %}<div class="lq-vista-scrim" aria-hidden="true"></div>{% endif %}
  </div>
  <div class="container lq-homehero-inner lq-vista-overlap">
    <div>
      <p class="lq-kicker">{{ section.eyebrow | default: site.brand.name }}</p>
      <h1>{{ section.title | default: site.brand.tagline | default: site.brand.name }}</h1>
      {% if section.lead %}<p class="lq-homehero-lead">{{ section.lead }}</p>{% endif %}
      <div class="lq-homehero-actions">
        {% if section.action or section.primaryLabel %}<a class="button button-primary" href="{{ section.primaryHref | default: section.action.href | default: '#donate' }}">{{ section.primaryLabel | default: section.action.label | default: 'Donate now' }}</a>{% endif %}
        <a class="button" href="{{ section.secondaryHref | default: '/about' }}">{{ section.secondaryLabel | default: 'Our story' }}</a>
      </div>
    </div>
    <aside id="donate">
      {%- comment -%} The site focus decides which widget leads (section.primary); this island becomes it: the donation widget or the volunteer sign-up. {%- endcomment -%}
      {% island 'primary_action_widget' %}
    </aside>
  </div>
</section>
{% endif %}
{% else %}
<section class="lq-homehero{% if heroPhoto %} lq-homehero--photo{% endif %}{% if heroCount > 1 %} lq-homehero--carousel{% endif %}"{% if heroPhoto %} style="background-image: url('{{ heroPhoto }}'); background-position: {{ heroFocus }}"{% endif %}>
  {% comment %}
    Several photos → the BEHAVIOUR carousel (data-p60-carousel, engine-wired, the template ships
    no JavaScript): complete static markup, one data-p60-slide per photo, auto-advance opt-in.
    Hiding non-active slides is .p60-js-scoped in theme.css so a no-JS visitor sees the photos
    stacked, never a blank hero. The vista framings above show the other route: the ready-made
    hero_carousel island. A template chooses either.
  {% endcomment %}
  {% if heroCount > 1 %}
  <div class="lq-hero-slides" data-p60-carousel="auto" aria-label="Hero photographs">
    {% for image in section.images %}
    <img class="lq-hero-slide{% if forloop.first %} is-active{% endif %}" data-p60-slide
         src="{{ image.imageUrl }}" alt="{{ image.alt }}" style="object-position: {{ heroFocus }}"
         {% if forloop.first %}fetchpriority="high"{% else %}loading="lazy"{% endif %} decoding="async">
    {% endfor %}
  </div>
  {% endif %}
  <div class="container lq-homehero-inner">
    <div>
      <p class="lq-kicker">{{ section.eyebrow | default: site.brand.name }}</p>
      <h1>{{ section.title | default: site.brand.tagline | default: site.brand.name }}</h1>
      {% if section.lead %}<p class="lq-homehero-lead">{{ section.lead }}</p>{% endif %}
      <div class="lq-homehero-actions">
        {% if section.actionStyle == 'button' or section.givingStyle == 'button' %}
        {% if section.action or section.primaryLabel %}<a class="button button-primary" href="{{ section.primaryHref | default: section.action.href | default: '/donate' }}">{{ section.primaryLabel | default: section.action.label | default: 'Donate now' }}</a>{% endif %}
        {% else %}
        {% if section.action or section.primaryLabel %}<a class="button button-primary" href="{{ section.primaryHref | default: section.action.href | default: '#donate' }}">{{ section.primaryLabel | default: section.action.label | default: 'Donate now' }}</a>{% endif %}
        {% endif %}
        <a class="button" href="{{ section.secondaryHref | default: '/about' }}">{{ section.secondaryLabel | default: 'Our story' }}</a>
      </div>
    </div>
    {% unless section.actionStyle == 'button' or section.givingStyle == 'button' %}
    <aside id="donate">
      {% island 'primary_action_widget' %}
    </aside>
    {% endunless %}
  </div>
</section>
{% endif %}
```

## `sections/impactMap.liquid`

```liquid
<section class="section">
  <div class="container">
    {% island 'map' %}
  </div>
</section>
```

## `sections/people.liquid`

```liquid
{% comment %}
  People / team, the reference implementation: simple cards (name, role, optional photo and
  one-line statement), a grid that collapses to one column on phones. No placeholder faces:
  a person without a photo just renders text (derive or omit, never fabricate).
{% endcomment %}
<section class="lq-section">
  <div class="container">
    {% if section.eyebrow or section.heading or section.text %}
    <div class="lq-section-head">
      {% if section.eyebrow %}<p class="lq-kicker">{{ section.eyebrow }}</p>{% endif %}
      {% if section.heading %}<h2>{{ section.heading }}</h2>{% endif %}
      {% if section.text %}<p class="lq-muted">{{ section.text }}</p>{% endif %}
    </div>
    {% endif %}
    <div class="lq-people">
      {% for person in section.items %}
      <article class="lq-person">
        {% if person.imageUrl %}<img class="lq-person-photo" src="{{ person.imageUrl }}" alt="" loading="lazy">{% endif %}
        <h3>{{ person.name }}</h3>
        <p class="lq-person-role">{{ person.role }}</p>
        {% if person.statement %}<p class="lq-person-statement">“{{ person.statement }}”</p>{% endif %}
      </article>
      {% endfor %}
    </div>
  </div>
</section>
```

## `sections/values.liquid`

```liquid
<section class="lq-values">
  <div class="container">
    <h2>{{ section.heading | default: "What guides us" }}</h2>
    {% comment %}
      data-p60-reveal-group: the engine stamps --p60-reveal-index on each child and adds
      is-revealed when the rail scrolls into view, the stagger and motion are OURS, in theme.css,
      and .p60-js-scoped so a no-JS visitor sees the rail complete and still.
    {% endcomment %}
    <ol class="lq-value-rail" data-p60-reveal-group>
      {% for item in section.items %}
      <li>
        <span class="lq-value-dot"></span>
        <h3>{{ item.title }}</h3>
        <p>{{ item.description }}</p>
      </li>
      {% endfor %}
    </ol>
  </div>
</section>
```

━━ reference/tokens.md ━━


:::note[Generated reference]
This page is generated from the machine-readable contract the platform engine enforces (`contract/v1`). It cannot drift from production behaviour.
:::


The CSS custom-property contract, the theming tokens the platform base declares and every island/page consumes. A template overrides them via :root:root in its theme.css. Additive-only: tokens are never removed or repurposed within a contract major.


| Token | Purpose |
| --- | --- |
| `--bg` | Page background. |
| `--bg-tint` | Subtle tinted background (footer, wells). |
| `--surface` | Card/panel surface. |
| `--ink` | Primary text colour. |
| `--muted` | Secondary text colour. |
| `--primary` | Brand primary (progress, links, selected states). |
| `--primary-strong` | Darker primary (hover/emphasis). |
| `--primary-soft` | Translucent primary wash (selected fills, chips). |
| `--accent` | Action accent (the donate CTA family). |
| `--accent-strong` | Darker accent. |
| `--gold` | Highlight tint (marks, ratings). |
| `--marker` | Impact-map pin colour (the live-map markers are a zoom-scaling circle layer that take this colour). Defaults to --accent. |
| `--map-mode` | Impact-map basemap colour mode read by the map island: auto (derive the map's paper/ink from the theme), light, dark, or muted. Default auto. |
| `--map-projection` | Impact-map projection: flat (default) or globe, the planet as a rotatable sphere with atmosphere. |
| `--line` | Hairline borders. |
| `--line-strong` | Emphasised borders (selected, focus). |
| `--danger` | Errors and destructive affordances. |
| `--cta-hover` | The donate-button hover 'go' colour. |
| `--cta-hover-strong` | Darker CTA hover. |
| `--shadow-sm` | Small elevation shadow. |
| `--shadow` | Large elevation shadow. |
| `--radius` | Large corner radius (cards, bands). |
| `--radius-sm` | Small corner radius (inputs, chips). |
| `--container` | Max content width. |

Override them in your `assets/theme.css` with doubled specificity so the theme wins over the platform base:

```css
:root:root {
  --primary: #0f766e;
  --accent: #ea580c;
  --radius: 18px;
}
```