Document 11 of 14 · docs/NEW-TEMPLATE-SKILL.md

new-template skill, draft

SPEC.md section 8 says the skill is extracted after the invoice proves the pattern, the way new-tool came out of measureandbuy's paint calculator. This draft exists so the traps already found do not have to be found twice. The build session that ships the invoice turns it into ~/.ai/skills/new-template/SKILL.md and deletes this file.

One template, in order

1. Research, one hour. The search phrase from CATALOG.md; the top ten results looked at as printed pages, not screenshots; what they get wrong on paper (margins, ink, a name that cannot fit). One paragraph in meta.json copy.description notes.
2. Fields before design. Write fields.json first: what a person needs to change and nothing more. Every text field gets a max. Every long field decides whether it gets assist. Lists get a cap. The compute string is the only arithmetic.
3. Design in HTML and CSS, on a .sheet in physical units. @page carries the default size only; the runtime swaps it. Two faces at most, from data/fonts.md, as static instances. Colours only through --t-*. Every editable region is a fixed box with data-max. Light-ink theme included. Decoration is CSS or SVG we drew.
4. Print it. At 100%, on the home printer, on the paper the template is for. Photograph it into the session. Fix what the paper shows (it always shows something).
5. Drive it. The sweep at 1440 and 390; the overflow test with every field at its longest allowed value and one past it; every optional field empty; pdfcheck on the free file (page count, box size, FontFile2 present, Type3 absent, credit line present).
6. Shots. shots.mjs for preview, OG and pin. Look at the pin at phone size once.
7. Copy. copy.mjs drafts; a person rewrites the description, the five FAQs, the pin text and the OG line into meta.json; human-voice lint.
8. Register. build.mjs (catalog, landing page, customizer, free file, sitemap), the category page, related grids, the homepage "new this month" if it is new this month. Month pages if meta.months is set.
9. Verify live after the deploy: the free file downloads from www, the customizer opens on a phone, one test-mode purchase if the runtime changed.
10. Handoff line in HANDOFF.md: what shipped, what the paper showed, anything the next template should know.

Traps, each one already paid for

• A variable font prints as Type 3 outlines. No embedded program, four times the size. Static instances only, per weight and style. (spikes/render/)
• @page cannot be selected by a class. The paper size is a <style id="page-size"> the runtime writes. A template that puts two @page rules in its CSS gets the last one, always.
• display: grid beats the UA [hidden] rule. Restate [hidden] { display: none !important } in every template.
• The overflow guard is only as good as the boxes. A data-max box with max-height one line short of its own default text flags itself; that is the guard working. Fix the box, do not loosen the guard.
• data-ready after document.fonts.ready, not on load. The renderer waits for the attribute; set it early and the PDF ships fallback fonts.
• Landscape is meta.orientation, not a CSS trick. The runtime writes Letter landscape; the sheet's width and height swap with the landscape class.
• Never name a local r or v inside a compute string in a way that shadows the values object. Same hoisting trap as measureandbuy's diagrams.
• The free file is rendered at build time by hand, not by the cloud renderer. If it looks different from the customizer, the fonts on the build machine are not the fonts in assets/fonts/.
• Escape everything. The runtime writes with textContent; the values script is serialised with < escaped. A template that innerHTMLs anything is a template that gets rejected.
• A theme is a set of --t-* values and nothing else. A hard-coded hex in template.css is a theme that cannot exist and a light-ink mode that does not work.

What "done" means for one template

The free file downloads from www and opens in Preview and Acrobat; the customizer passes the sweep at both widths; the overflow test fires and clears; pdfcheck passes; the page carries three valid JSON-LD blocks and the Rich Pin fields; it is in the sitemap, the category page and two related grids; and the paper photo is in the handoff.