skills/developing-blockninja-plugins/theme-overrides.md

# Codeless themes: template overrides, the ninjatpl engine, seed, screenshots

Read this before building or editing a codeless **theme** (a `.bnp` that re-skins the
built-in blocks and ships page templates, presets, fonts, an email wrapper, and demo
content). Distilled from the theme-fleet build (16 themes, 2026-07-05). Companion to
`cms/docs/TEMPLATE_PLUGINS.md` and `cms/docs/theme-previews.md`.

## What a codeless theme is

No Go, no `plugin.wasm`, **no `go.mod`, no `block_core` pin**. The repo is:

```
manifest.yaml            # theme_presets, bundled_fonts, master_pages, system_templates,
                         # page_templates, template_overrides, css.input_css_append, email wrappers
plugin.mod               # name/display_name/kind="theme"/scope="@themes"/categories/tags/required_icon_packs
templates/<theme>/*.html         # the page templates (default, full-width, landing, article, blog-index, contact, auth)
templates/overrides/<theme>/*.ninjatpl   # one per built-in block key you re-skin
templates/email/<system>.ninjatpl        # email wrapper
blocks/*.ninjatpl + *.schema.json        # persona blocks ONLY (things no built-in covers)
presets.json  fonts.json  master_pages.json
seed/seed.json  seed/workflows.json      # demo content (demo:true)
assets/                                  # fonts, css, static
```

Compatibility is not pinned in the repo — it is enforced by manifest synthesis in
`ninja plugin build` and the registry gates. `kind = "theme"` is frozen at first publish.

## Re-skinning a built-in block = a template override

Ship `templates/overrides/<theme>/<key>.ninjatpl` **plus** a `template_overrides` entry in
`manifest.yaml` (`template_key: <theme>`, `block_key: <key>`). Keys use the **dashed
canonical form** (`video-embed`, `feature-grid`, `author-bio-hero`). Some accept underscore
aliases, but overrides target the dashed key.

A re-skin is **presentation only**. Copy the built-in's default template as your starting
point (`cms/backend/blocks/builtin/manifest/{blocks.yaml,schemas,sample}` for declarative
builtins; the compiled builtin's Go for the rest) and preserve **every** content-field read,
provider variable, custom tag (`{% img %}`, `{% button %}`, `{% form %}`, `{% signup_form %}`,
`{% auth_form %}`), and inline `<script>` verbatim. Only classes and markup change. If you
rename or drop a variable, that part renders empty.

Persona blocks (`blocks/`) are for furniture **no built-in covers** (a reservation strip, a
tour-dates list). Anything that duplicates a built-in (footer, hero, gallery, divider, menu,
stats, pull-quote) must become an override of that built-in, not a parallel block. Delete the
duplicate block + its schema.

## How overrides dispatch — know this or you ship empty lists

There are two kinds of built-in, and they reach your override by different paths:

1. **Definition-backed built-ins** (most of them: navbar, footer, hero, feature-grid, the
   whole blog family, breadcrumbs, category-list, author-bio-hero, …). These declare **data
   providers** (`menus`, `posts`, `authors`, `categories`, `footer_menus`, …). The codeless
   loader registers your override as a template **source**, so render flows through the
   definition engine (`RenderDefinition`), which **builds the providers** and then renders
   your `.ninjatpl` with the content-map fields **and** the provider variables merged in. A
   navbar override gets its menu items; a blog-index override gets its posts.
   - **This is cms main (`fa31808d7`, 2026-07-05) onward.** On an OLDER image the codeless
     loader registered these overrides on the *compiled* path, which skipped
     `RenderDefinition` and never built providers — so the chrome rendered around **empty
     lists**. If your provider-backed override renders empty, your cms is pre-fix.
   - **Author provider-backed overrides faithful to the built-in's provider variable names.**
     Read the built-in default + its `blocks.yaml` providers to get the loop variable exactly
     right.

2. **Compiled built-ins with NO definition** (`auth-form`, `auth-status`,
   `password-reset-form`, `page-suggestions`). Your override dispatches via the **compiled
   path** — `Registry.GetForTemplate(templateKey, blockKey)` returns your override closure
   before the base block, so it renders. Their data is `BlockContext`-driven (`auth.*`,
   `context.*`), not providers, so they render fully. Preserve the hardcoded endpoints and
   input names (`/api/auth/login|register|logout|request-password-reset`, honeypots, the Cap
   `<cap-widget>` markup). `page-suggestions` renders themed 404 chrome, but the dynamic
   "did you mean" list is a server-side Postgres FTS query that a codeless template cannot
   reproduce — themed chrome yes, dynamic list no.

(Internal note if you ever touch the loader: definition-backed keys must be registered via
`RegisterTemplateOverrideSource` so `registry.Has("theme:key")` stays false and the
`blocks.go` dispatch gate takes the `RenderDefinition` branch; non-definition keys keep the
compiled `RegisterTemplateOverride` path. pongo2's tag/filter registries are process-global,
so the source-layer renderer and the compiled `BlockTemplate` closures share the same custom
tags/filters — an override renders identically either way.)

## Legacy override field reconcile (the dead-override trap)

If the theme carried `.so`-era overrides, the built-in field names changed. Fix the reads or
the override renders empty:

- `button`: `href`/`url` → `link`, `variant` → `style`, `text` → `label`
- `card`: `body` → `text`, `image` → `media`

Grep your overrides for the old names before assuming they still work.

## ninjatpl (pongo2) engine gotchas — hard-won, do not rediscover

1. `{% for %}` iterates a **`[]any` of maps ONLY**. No string iteration, no int-slice
   iteration. "Repeat N times" must be unrolled or shaped as data in a provider/sample.
2. **Tailwind JIT cannot see interpolated classes** (`grid-cols-{{ n }}`). Use literal
   conditional classes per enum value.
3. **No bracket subscript** (`foo[bar]`). Dynamic-key lookups are impossible — shape the data
   in a provider/sample instead.
4. `{% if %}` **cannot nest inside a tag's arguments** (`{% img %}`, `{% button %}`). Branch
   the whole tag call.
5. Icons are `"pack:name"` strings: split with `|split:":"|first`/`|last`. The
   `::pack:name:SIZE::` shorthand takes size **keywords** only (`sm`/`md`/`lg`/`xl`), not
   class strings. Render icons **only** as `<svg><use href="/icons/<pack>.svg#<name>"/></svg>`
   — never inline SVG. Declare packs in `plugin.mod` `required_icon_packs` and in
   `RECOMMENDED_ICONS.md`.
6. `{# comments #}` must be **single-line**.
7. The `media` filter is **not registered** in the block render path. Resolve images via
   `{% img %}`, never `|media`.
8. The navbar drawer uses **fixed element ids** — one navbar per page.
9. **Dual-mode via semantic tokens only** (`bg-background`, `text-foreground`,
   `hsl(var(--token))`). A literal `hsl(...)`/hex/`rgb(...)` in a template **fails
   check-safety** and breaks the other mode.
10. `{% extends %}`/`{% include %}` are for page templates, not block overrides.
11. **Bare-string seed values hard-error attribute reads.** `field.text|default:field`
    aborts the whole block (blank hero) when the seed passes `"headline": "..."` instead of
    `{"text": "..."}`. Always read styled-text fields as `field|get:"text"|default:field` —
    the process-global `get` filter degrades gracefully on both shapes.
12. **Scroll-reveal must be robust.** A naive `.reveal` + IntersectionObserver hides
    below-fold content in screenshots and for no-JS/reduced-motion users. Required: reveal
    instantly when already in view at init, a safety-net full reveal (`load` + timeout), and
    content visible without JS (gate hiding on a JS-added class, e.g. `.theme-js`).
13. **Theme templates ARE scanned by the host Tailwind build** (fixed cms `50c713ed0`,
    2026-07-05 — extracted `.bnp` `**/*.ninjatpl` is an injected `@source`; CSS regenerates
    on boot, theme activation, and runtime install/swap). Use normal responsive utilities in
    templates; do NOT duplicate them as hand-rolled media-query CSS in
    `css.input_css_append` — reserve that for genuinely bespoke design CSS.

## Theme font size hooks (`bn-*` classes and `--fs-*` variables)

Since 2026-08 (cms ADR 0029) admins can set per-element font sizes in Theme settings.
The theme CSS emits `--fs-<key>` variables plus rules targeting **class hooks**; a
template only responds if it carries the hook (or its stylesheet consumes the var).
Canonical key list: cms `backend/internal/theme/fontsize.go`; selector map: cms
`backend/internal/theme/css.go` `fontSizeOverrideSelectors`.

| Key | How it applies |
|-----|----------------|
| `h1`..`h6` | bare element rules in `@layer base` (Tailwind size utilities still win, by design) |
| `hero-title` / `hero-subtitle` | `.bn-hero-title` / `.bn-hero-subtitle` (unlayered, beats utilities) |
| `post-title` / `post-lede` | `.bn-post-title` / `.bn-post-lede` (unlayered) |
| `index-card-title` | `.bn-post-card-title` (unlayered) |
| `nav-link` | `.bn-nav-link` — host navbar chrome only; menu links, not brand/CTA/utility anchors |
| `post-body`, `post-h2`, `post-h3`, `post-meta`, `page-title`, `page-lede`, `button` | consumed as `var(--fs-<key>, <fallback>)` in stylesheets (host sheets do this; yours can too) |

Rules for theme/plugin authors:

- **Re-skinning a built-in? Preserve its `bn-*` hooks.** They are content contract, like
  field reads. Dropping `bn-hero-title` from a hero re-skin silently kills the admin's
  Hero Title size control on every site using your theme.
- **Custom templates opt in by adding the hook** to the semantically equivalent element:
  the article `<h1>` gets `bn-post-title`, the hero heading gets `bn-hero-title`, etc.
  Keep existing utility classes; the override rule is unlayered and wins only when set.
- **Hardcoded `font-size` in your CSS on a mapped element? Wrap it**:
  `font-size: var(--fs-hero-title, 3rem);` with your current value as the fallback, so
  zero-override rendering is byte-identical. This works even when you cannot touch markup.
- **Do not invent hooks** for unmapped elements and do not map decorative elements
  (stat numbers, section eyebrows, footers) to keys they do not represent.
- **Published pages freeze markup**: pages published before a hook existed pick it up
  only on republish. The `var()` path applies immediately.

## Presets, fonts, email, motion

- **presets.json** — 4 to 6 presets, all 19 tokens, `mode: "both"`. Tune the dark side
  intentionally (a real dusk/night palette, not an inversion).
- **fonts.json** — bundle woff2 (OFL/Apache only; record the license in `assets/`). **Every**
  `font-family` goes through `var(--font-heading|body|mono, <fallback>)`; never hardcode a
  family (it breaks the admin font picker). If you cannot obtain the exact locked face offline
  (no woff2 in-workspace, no network), bundle a close OFL substitute and name the intended
  face as an admin Google-Fonts assignment in `RECOMMENDED_FONTS.md`. That is an accepted
  deviation; document it.
- **Email wrapper** — `templates/email/<system>.ninjatpl`, email-safe (tables, inline styles,
  **literal hex** — email clients ignore `var()`). Context: `body|safe`,
  `site_name`/`site_url`/`logo_url`, `colors.<camelCase>` hex tokens.
- **Motion** — dependency-free JS only; honor `prefers-reduced-motion`; lazy-init any canvas
  showpiece on view (IntersectionObserver); ship a static no-JS fallback. Keep canvas to the
  hero/landing when a theme is a "big motion" theme; nowhere else.

## Seed demo content (`seed/seed.json`, `demo: true`)

Sections: `settings`, `media`, `pages`, `menu_items`, `data_tables`. Required pages: home,
about, a blog index with ≥3 posts, contact, login. Contact wiring: a `data_tables` entry
(e.g. `contact_submissions`) referenced from the contact-form block as
`formConfig.targetTable` (rewritten to the real table id at apply), plus `seed/workflows.json`
with a `row_inserted` trigger on that table and an `email` step
(`recipients: {mode: "admins", scope: "all"}`).

**Page slugs are single-segment.** The `pages` table enforces `slug_single_segment` (no
slashes). Blog posts under `/blog` must be seeded as **nested pages** (a child of the blog
page with a single-segment child slug), not as a page whose slug is a full path like
`/blog/my-post` — a path slug is rejected and 500s `InstallDemoContent` (home/about/blog-index
seed first, then the nested post fails and aborts the rest). Confirm the current seed
applier's nested-page handling in `cms/backend/internal/services` before authoring blog seed.
Data-table + workflow seeding is proven by the seed-workflows e2e (dojo suite
`seed-workflows-e2e`).

## Verify + commit (theme workflow)

```bash
cd themes/<theme> && make            # ninja plugin build --codeless → <name>-<ver>.bnp
make archive-check                   # git archive HEAD packs cleanly
ninja plugin verify <name>-<ver>.bnp
cd ~/src/blockninja/check-safety && go run . ~/src/blockninja/themes/<theme>   # MUST exit 0
```

A clean theme reports `32 checks: 19 ok 13 skip -> OK`.

**Commit gotcha (bit me repeatedly):** the `safety-gate` commit hook resolves its target from
the **shell cwd**. If you commit while cwd is elsewhere, or a sibling theme repo has
pre-existing violations, the hook scans the wrong repo and denies you. Commit with
`git -C ~/src/blockninja/themes/<theme> commit ...` (or `cd` into the repo first) so the hook
scans your theme. Stage explicit paths; never `git add -A`. `*.bnp`/`*.so` stay gitignored;
`kind = "theme"`.

## Screenshots / registry previews

- A codeless theme renders **only** on a cms that carries the built-ins (and, for populated
  lists, the provider-dispatch fix `fa31808d7`). A **released image can lag `main`** — check
  the released tag's commit before assuming it can render a new theme. A theme built against
  new built-ins will not render on an image that predates them.
- Provisioning resolves the newest cms tag, then does a **local `ImageExists` check before
  pulling** (`orchestrator .../operation_provision.go`). So a **locally-built** image tagged
  as that resolved version is used as-is — you can preview against an unreleased cms without
  pushing anything.
- Documented recipe: provision `siteType: showcase` + `ninja theme screenshot`; the registry
  `previewImageUrl` / `preview.png` is the gallery card (home hero). See
  `cms/docs/theme-previews.md`. Auth to a provisioned instance's CMS via
  `SSOService/GenerateSSOToken` → `/admin/sso?format=json&token=…` (no seeded instance admin
  password).
- Codeless themes provision **fast** (~10 s, no CGO compile), so the old `.so`
  ≤3-concurrent / 5-minute-compile cautions no longer apply. The account 10-site cap still
  does — tear galleries down between batches and poll until gone.
- **Do NOT sideload a `.bnp`** onto an instance's plugin-source dir on an older base image:
  its `entrypoint.sh` runs `./server --build-so <name>` for any source dir and wedges on a
  codeless theme. Provision-time registry install is the clean path.