Kira Templates

Template kits for Kira Page Builder. A kit is a complete site design for one industry: header, footer, pages and a 404 page, plus its own images, forms and colors and fonts. Sites browse the catalog under Kira → Template Kits (Kira 1.4.0+) and download only the kits they choose.

This repo must stay public: sites read it without a token.

What sites download

Path	What
catalog.json	{ industries: {slug: title}, kits: [{slug, industry, title, description, version}] }
kits/<slug>/kit.json	{ kpb_kit: 1, slug, title, version, tokens, tokens_css, images: [{file, id, alt}], forms: [{id, form}], templates: [...] }. Each template uses Kira's template export format.
kits/<slug>/img/*.webp	The kit's images, which are added to the site's media library on download.
kits/<slug>/thumb.webp	The catalog card image, 960×600 (the top of the kit's Home page).

Templates point to images as https://kpb-kit.invalid/img/<file> and as media id 900001 + index. Form widgets point to form id 900101 + n. On download, Kira replaces these placeholders with the real attachment and form ids.

Making a kit

Kits live in src/kits/<industry>/<slug>.kit.ts (default export: a Kit). The build finds them by that name, so there's no index to edit. Industries and their catalog order are in src/kits/industries.ts. Work in progress goes in src/drafts/ (git-ignored), which the full build skips.

1. Write <slug>.images.json next to the kit, one entry per image: {file, alt, size: landscape|square|portrait, prompt}. Only add entries at the end: an image's position fixes its media id.
2. Run python3 tools/images.py <industry>/<slug> (or drafts/<industry>/<slug>). It generates the missing images with the Codex CLI (IMG_THREADS parallel runs, default 4), saves them as WebP in kits/<slug>/img/ with their sizes, and retries failures. To regenerate specific images, pass their file names after the slug.
3. Write <slug>.kit.ts: tokens, forms and templates, built from Kira's own helpers (@kira/kit) and src/lib.ts. Shared forms per industry go in forms.ts.
4. Run node build.mjs <path/to/slug.kit.ts> to check one kit, or node build.mjs for every kit plus catalog.json. The build renders with Kira's renderer and fails if Kira would drop an element, a style or a prop. Then run python3 tools/check-forms.py <slug>: forms use the kit's "text" color for labels and its "background" color for fields, so whatever a form sits on (its card) must contrast with "text" (WCAG AA 4.5). On a dark kit, put forms on a dark card, not a white one.
5. QA on the local test site: run tools/qa.sh <path/to/slug.kit.ts>. It needs a mu-plugin that points the kpb_kits_url filter at wp-content/uploads/kpb-kits-test/. The script serves the kit from there, downloads it, runs tools/demo-setup.php (kit design, published header/footer/404, real pages, a "Kit demo" menu, Home as the front page), screenshots every page into .work/shots/<slug>/ (with _sheet.png showing all of them side by side) and writes kits/<slug>/thumb.webp. tools/demo-restore.php undoes the site-wide changes.
6. Run the full build, then commit src/kits/<industry>/, kits/<slug>/ and catalog.json and push. Sites see the new kit within the hour.

The build uses a Kira checkout with node_modules installed: KIRA_DIR, which defaults to ../html/wp-content/plugins/kira-page-builder.

Rules for kit content

• Use no invented testimonials or quotes.
• Copy uses placeholder details (address, phone, example.com emails), which buyers replace.
• Each page has one clear main call to action.
• Page links use each page's kebab-case title ("Book an Appointment" → /book-an-appointment/).