@homepages/template-kit 0.2.0 → 0.3.0

package/docs/rules/fixtures-invalid.md

@@ -0,0 +1,96 @@
+---
+purpose: The template-kit/fixtures-invalid authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../schema-system.md, schema-invalid.md]
+updated: 2026-07-14
+---
+# template-kit/fixtures-invalid
+
+> `fixtures.ts` is the one contract file nothing else parses for you. This is that parse.
+
+## Rule
+
+The default export of `fixtures.ts` must satisfy the fixture-module shape:
+
+```ts
+{
+  base: {
+    slots: { /* every required slot, with a valid value */ },
+    options: { /* optional */ },
+    anchors: { /* optional */ },
+    variants: { /* optional */ },
+  },
+  option_matrix: [ /* optional: { label?, options } entries */ ],
+  states: { /* optional: named scenario → { label?, slots?, options?, anchors?, variants? } */ },
+}
+```
+
+`base` is required and must be an object holding a `slots` record — every other key is
+optional. Each violation names the exact path inside the module that's wrong (`"base"`,
+`"base.slots"`, `"states.empty-address"`, …) and what shape was expected there instead.
+
+## Reason
+
+`schema.ts` and `fill-spec.ts` are both Zod-parsed on the way into every other check, so a
+malformed one is caught immediately. `fixtures.ts` used to be the exception: nothing
+touched it until the render stage read it directly, so a wrong shape there surfaced as a
+raw crash mid-render, blamed on whatever line happened to dereference the missing field —
+never on the fixture that was actually wrong.
+
+This gate exists to move that failure to where the mistake was made, with a message about
+the fixture module instead of a stack trace from three files away.
+
+## Fix
+
+Read the message's path — it points at the exact key that's wrong — and bring that key's
+shape in line with what's documented above.
+
+### Before
+
+```ts
+// sections/hero/fixtures.ts
+import type { FixtureModule } from "@homepages/template-kit";
+
+const fixtures: FixtureModule = {
+  base: {
+    slots: { headline: "A mansard Victorian in the heart of Jamaica Plain" },
+  },
+  states: {
+    "no-photo": { slots: { hero_image: null }, label: 12 },
+    //                                                 ^ label must be a string
+  },
+};
+
+export default fixtures;
+```
+
+```text
+Section "hero": fixtures.ts — "states.no-photo.label": Expected string, received number.
+```
+
+### After
+
+```ts
+// sections/hero/fixtures.ts
+import type { FixtureModule } from "@homepages/template-kit";
+
+const fixtures: FixtureModule = {
+  base: {
+    slots: { headline: "A mansard Victorian in the heart of Jamaica Plain" },
+  },
+  states: {
+    "no-photo": { slots: { hero_image: null }, label: "No hero photo" },
+  },
+};
+
+export default fixtures;
+```
+
+## See also
+
+- [The schema system](../schema-system.md) — `fixtures.ts`'s place among the section's
+  four contract files.
+- [`schema-invalid`](schema-invalid.md) — the sibling gate on `schema.ts` and
+  `fill-spec.ts`.
+- [`bundle-incomplete`](bundle-incomplete.md) — reported instead of this id when
+  `fixtures.ts` is missing outright, rather than present and wrong.

package/docs/rules/license-denied.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/license-denied authoring rule — what it enforces, why, and how to fix it.
 status: living
 related: [INDEX.md, audit-severity.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # template-kit/license-denied
 
@@ -31,8 +31,16 @@ Two cases people expect to slide through, and neither does:
 - **A missing `license` field is a denial**, not a pass. An unlicensed package is not a
   permissive one — by default, no rights are granted at all.
 
-**Scope: the production tree only.** `devDependencies` are not evaluated — your bundler,
-your test runner, and your formatter do not ship to anyone.
+**Scope: the production tree only.** "Production tree" means exactly what
+`npm ci --omit=dev` installs. `devDependencies` are not evaluated — your bundler, your
+test runner, and your formatter do not ship to anyone.
+
+**An optional peer you have anyway counts.** If a production package declares an
+optional `peerDependency` and your workspace has that package for any reason (even as a
+`devDependency`), npm resolves the peer and keeps it in the `--omit=dev` install — so it
+is in the production tree and its license is checked, transitively. An optional peer you
+do **not** have is never installed and is not evaluated. Run `npm ci --omit=dev` and look
+at the resulting `node_modules` if you want the exact set the check sees.
 
 **There is no per-package override.** No allowlist entry you can add, no waiver comment. By
 design.

package/docs/rules/manifest-invalid.md

@@ -0,0 +1,99 @@
+---
+purpose: The template-kit/manifest-invalid authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../schema-system.md, schema-invalid.md, no-templates.md]
+updated: 2026-07-14
+---
+# template-kit/manifest-invalid
+
+> `manifest.json` is the one file that says which sections make a page, and in what
+> order. Every check on it lands under this id.
+
+## Rule
+
+A template folder (`templates/<key>/`) must have a `manifest.json` at its root, and that
+file must:
+
+- **exist** — a template folder with none at all reports this once, naming the missing
+  file;
+- **parse as JSON, and satisfy the manifest shape** — `key`, `name`, `deliverable_type`,
+  and an ordered `sections` array of section instances (`section`, `instance_id`,
+  `options`, `locked`, `required`, `reorderable`);
+- **agree with its own folder** — the manifest's `key` must match the template folder
+  name it lives in;
+- **reference real sections** — every `sections[].section` must resolve to a section this
+  workspace actually has;
+- **override only what's real and overridable** — an instance's `options` may only name an
+  option the target section declares, only when that option is not
+  `template_overridable: false`, and only with a value that actually differs from the
+  section's own default;
+- **satisfy the whole-composition nav contract** — the cross-section rules that need the
+  full, resolved section set rather than any one section in isolation.
+
+Every violation collects into the same run; a manifest with several wrong references
+reports all of them together.
+
+## Reason
+
+A section's own four files describe that section in isolation — they say nothing about
+which page it appears on, in what order, or which of its options a specific template has
+chosen to lock in. `manifest.json` is where that composition is declared, and it is the
+only place a downstream consumer (the publisher, the fill pipeline, the editor) can go to
+learn a template's actual shape. A manifest that references a section that doesn't exist,
+or restates a default as if it were an override, is a template whose real composition
+nobody can trust the manifest to describe.
+
+## Fix
+
+Read the message: it names the template, the section instance, and what's wrong.
+Missing entirely, add one. Otherwise, fix the field the message points at.
+
+### Before
+
+```text
+templates/acme-modern/
+  manifest.json
+  sections/
+    hero/
+```
+
+```json
+// templates/acme-modern/manifest.json
+{
+  "key": "acme-classic",
+  "name": "Acme Classic",
+  "deliverable_type": "single_property_website",
+  "sections": [
+    { "section": "hero", "instance_id": "hero-1", "options": {}, "locked": [], "required": true, "reorderable": false }
+  ],
+  "reconcile": []
+}
+```
+
+```text
+Template "acme-modern": manifest key "acme-classic" does not match the template folder name "acme-modern".
+```
+
+### After
+
+```json
+// templates/acme-modern/manifest.json
+{
+  "key": "acme-modern",
+  "name": "Acme Modern",
+  "deliverable_type": "single_property_website",
+  "sections": [
+    { "section": "hero", "instance_id": "hero-1", "options": {}, "locked": [], "required": true, "reorderable": false }
+  ],
+  "reconcile": []
+}
+```
+
+## See also
+
+- [The schema system](../schema-system.md#manifestjson--composing-sections-into-a-template) —
+  what a manifest declares and the type it's validated against.
+- [`schema-invalid`](schema-invalid.md) — the same kind of cross-reference check, one
+  level down, on a single section's own contract files.
+- [`no-templates`](no-templates.md) — reported instead when the workspace has no
+  `templates/<key>/` folder to check at all.

package/docs/rules/no-hex.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/no-hex authoring rule — what it enforces, why, and how to fix it.
 status: living
 related: [INDEX.md, server-vs-client.md, ../theme-and-css.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # template-kit/no-hex
 
@@ -11,11 +11,20 @@ updated: 2026-07-14
 
 ## Rule
 
-Two shapes are banned:
+This rule ships as a **warning**, not an error: a section spending theme tokens is
+recommended, not gated. A hard-coded colour squiggles in your editor, but it does not
+fail `template-kit check` (the check gates on errors only, so a warning never reaches it)
+and so does not block ingest either. The guidance below is still the right thing to do —
+it only changes what the linter does with a violation, not whether the violation is
+worth fixing.
 
-- **A CSS colour function**, anywhere in a string or template literal:
-  `oklch(…)`, `oklab(…)`, `rgb(…)`, `rgba(…)`, `hsl(…)`, `hsla(…)`, `color-mix(…)`.
-  No context test — nobody spells an anchor id `rgb(...)`.
+The rule flags two shapes:
+
+- **A CSS colour function that bakes a colour**, anywhere in a string or template
+  literal: `oklch(…)`, `oklab(…)`, `rgb(…)`, `rgba(…)`, `hsl(…)`, `hsla(…)`,
+  `color-mix(…)`. No context test — nobody spells an anchor id `rgb(...)`. **One
+  carve-out:** a `color-mix()` whose colour arguments are all theme-derived is legal —
+  see below.
 - **A hex literal** (3, 4, 6, or 8 digits) **in a colour context**. A colour context is
   a Tailwind arbitrary-value bracket that resolves to a colour:
   - a colour property — `[color:#fff]`, `[background:#fff]`, `[background-color:#fff]`,
@@ -35,6 +44,40 @@ anchor ids that happen to be spelled from hex digits.
 Every hex-shaped token in a string is checked, not just the first — an out-of-context
 token early in a `className` cannot shadow a genuine colour later in it.
 
+### The `color-mix()` carve-out
+
+A `color-mix()` carries **no palette of its own** when every one of its colour arguments
+is theme-derived — a `var(--…)` reference, `transparent`, `currentColor`, or a nested
+`color-mix()` judged on these same terms. It composes a colour out of the theme the
+section was handed, so it is as theme-agnostic as `bg-surface` and cannot break when
+another template reuses the section. It is legal:
+
+```
+hover:bg-[color-mix(in_srgb,var(--tr-color-surface)_92%,var(--tr-color-ink))]
+bg-[color-mix(in_srgb,var(--tr-color-ink)_50%,transparent)]   ← a translucent tint:
+                                                                overlay, scrim, hover wash
+```
+
+A mix weight (`92%`) is not a colour; only the colour arguments are tested.
+
+`transparent` and `currentColor` are the only palette-free keywords: `transparent` names
+the *absence* of a colour, and `currentColor` defers to the inherited (theme-driven)
+`color`. Every other CSS named colour (`white`, `black`, `rebeccapurple`, …) is a baked
+palette exactly as a hex is. So these report:
+
+```
+color-mix(in srgb, var(--tr-color-primary) 80%, #fff)     ← a hex literal
+color-mix(in srgb, var(--tr-color-primary) 80%, white)    ← a CSS named colour
+color-mix(in srgb, var(--tr-color-accent, #fff) 80%, …)   ← a var FALLBACK is a baked
+                                                            colour the moment the
+                                                            property is undefined
+```
+
+The carve-out is `color-mix()` **only** — it is the one colour function that *composes* a
+colour rather than stating one. The other six take raw channel values, so they bake a
+colour by construction: `rgb(0 0 0)`, `oklch(0.7 0.1 20)`, and even
+`rgb(var(--r) var(--g) var(--b))` report.
+
 ## Reason
 
 A section carries **zero palette of its own**. It is theme-agnostic, and must look
@@ -49,10 +92,14 @@ not a palette boundary.
 
 ## Fix
 
-Use a semantic token utility (`bg-surface-alt`, `text-ink`). If the value is genuinely
-brand decoration with no token, add it to the **template's** `theme.ts` palette and use
-the `--tr-color-<name>` utility it compiles to — which keeps the value in one place
-instead of in one section.
+Use one of your theme's colour utilities. If the value is genuinely brand decoration with
+no token yet, add it to `colors` in the **template's** `theme.ts` — the key `lagoon`
+compiles to `--tr-color-lagoon` and the `bg-lagoon` / `text-lagoon` utilities — which
+keeps the value in one place instead of in one section.
+
+If you need a colour the theme does not name — a hover, active, or pressed step — derive
+it from the tokens the theme *does* name with `color-mix()`, rather than reaching for a
+literal to lighten or darken with.
 
 ### Before
 
@@ -90,8 +137,27 @@ export function Renderer({ slots }: Props) {
 }
 ```
 
+### A state colour, derived
+
+Lightening a hover step by mixing in a hard-coded white is both the violation and the
+bug: under a dark theme it lightens a button the theme wanted dark. Mix toward a colour
+the **theme** names, and the step follows whatever theme the section is handed.
+
+```tsx
+// Before — `#fff` is a palette this section invented.
+<button className="bg-primary hover:bg-[color-mix(in_srgb,var(--tr-color-primary)_80%,#fff)]">
+  {slots.cta}
+</button>
+
+// After — every colour argument is a theme var.
+<button className="bg-primary hover:bg-[color-mix(in_srgb,var(--tr-color-primary)_80%,var(--tr-color-surface))]">
+  {slots.cta}
+</button>
+```
+
 ## See also
 
-- [Theme and CSS](../theme-and-css.md#color-roles) — the token system and the colour roles.
+- [Theme and CSS](../theme-and-css.md#tokentheme--your-templates-design-system) — the
+  token system, and how a `colors` entry becomes a utility.
 - [Server vs client](server-vs-client.md) — why the other bans stop at the hydration
   boundary and this one does not.

package/docs/rules/no-templates.md

@@ -0,0 +1,87 @@
+---
+purpose: The template-kit/no-templates authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, manifest-invalid.md]
+updated: 2026-07-14
+---
+# template-kit/no-templates
+
+> A run that gates nothing must never report success. This is what a workspace with no
+> template to check reports instead of a silent pass.
+
+## Rule
+
+`templates/` must hold at least one template folder — for the run you asked for:
+
+- `template-kit check` (no argument, from the workspace root): `templates/` has no
+  folder in it at all.
+- `template-kit check --all`: same — no template folder exists to check.
+- `template-kit check <name>` (or a bare `check` run from inside a template's own
+  folder): that one named template does not exist. (A folder that exists but is
+  missing its `manifest.json` is a different, more specific failure —
+  [`manifest-invalid`](manifest-invalid.md) — because a folder under `templates/` is a
+  template whatever else is wrong with it.)
+
+This is checked once per run, scoped to the workspace, not to any one template.
+
+## Reason
+
+`every()` over an empty set is vacuously true. A `check` run that selected zero templates
+and reported "check passed" would exit 0 having run not one gate — indistinguishable from
+a workspace that passed every rule, when in truth no rule ran at all. Anything that
+re-runs this command on your behalf (an ingest pipeline, a CI step) would accept that
+silence as a clean submission.
+
+Reporting a diagnostic instead means "nothing to check" is a failure your run surfaces,
+not a false green light.
+
+## Fix
+
+Add a template: `templates/<key>/` with a `manifest.json` declaring its section
+composition, and a `sections/` folder holding the sections it composes. If you meant to
+check a specific template and named it wrong, or ran `check` from a folder that isn't a
+template folder, correct the name or your working directory instead.
+
+### Before
+
+```text
+my-workspace/
+  package.json
+  package-lock.json
+  templates/            ← empty
+```
+
+```text
+$ template-kit check
+✗ workspace — 1 problem(s)
+    [template-kit/no-templates] This workspace has no template to check: templates/ holds no template folder.
+    fix: Add a template: templates/<key>/ with a manifest.json declaring its section composition and a sections/ folder holding the sections it composes.
+```
+
+### After
+
+```text
+my-workspace/
+  package.json
+  package-lock.json
+  templates/
+    acme-modern/
+      manifest.json
+      sections/
+        hero/
+          Renderer.tsx
+          schema.ts
+          fill-spec.ts
+          fixtures.ts
+```
+
+```text
+$ template-kit check
+✓ acme-modern
+check passed
+```
+
+## See also
+
+- [`manifest-invalid`](manifest-invalid.md) — the check that takes over once a template
+  folder exists, on whether its `manifest.json` is present and correct.

package/docs/rules/parse-error.md

@@ -0,0 +1,76 @@
+---
+purpose: The template-kit/parse-error authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, typecheck.md]
+updated: 2026-07-14
+---
+# template-kit/parse-error
+
+> A file so broken it never became an AST. Every other rule needs one; this is what's
+> reported when there isn't one to have an opinion about.
+
+## Rule
+
+Every other lint rule runs against a parsed file — an AST it can walk and ask questions
+of. When a `.ts`/`.tsx` file cannot even be parsed (invalid syntax: an unclosed brace, a
+stray token, a JSX tag that never closes), there is no AST for any rule to run against,
+and no rule id of its own to report. This id is what's reported in that one case instead:
+the parser's own message, relocated to the file and line it names.
+
+This is the only diagnostic under this id — it is not a rule you can violate by writing
+working code a particular way, the way `no-hex` or `no-inline-style` are. It exists so
+that "the file didn't parse" is a rule-id and a fix hint, not silence or a raw crash.
+
+## Reason
+
+A stage never aborts the run — an author fixing one file's problem must see every other
+file's problems in the same run, not discover them one release at a time. A parser
+exception is the one case where that promise is hardest to keep: there is genuinely
+nothing else to check about a file that doesn't parse. Reporting it under its own id,
+rather than dropping it or letting it throw, keeps that promise intact.
+
+You may see the **same file** flagged here and under
+[`typecheck`](typecheck.md): the lint stage and the typecheck stage each parse the
+workspace independently, and a syntax error fails both parsers, so both stages report it,
+each in their own words. Fixing the syntax error clears both.
+
+## Fix
+
+Read the message — it is the parser's own error, naming the file and the line. Fix the
+syntax at that location.
+
+### Before
+
+```tsx
+// sections/hero/Renderer.tsx
+export function Renderer() {
+  return (
+    <Section>
+      <h1>{headline}</h1>
+    </Section
+  );
+}
+```
+
+```text
+sections/hero/Renderer.tsx:6
+  Parsing error: '>' expected.
+```
+
+### After
+
+```tsx
+// sections/hero/Renderer.tsx
+export function Renderer() {
+  return (
+    <Section>
+      <h1>{headline}</h1>
+    </Section>
+  );
+}
+```
+
+## See also
+
+- [`typecheck`](typecheck.md) — the sibling failure one layer up: a file that parses but
+  does not type-check.

package/docs/rules/schema-invalid.md

@@ -0,0 +1,96 @@
+---
+purpose: The template-kit/schema-invalid authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../schema-system.md, fixtures-invalid.md, manifest-invalid.md]
+updated: 2026-07-14
+---
+# template-kit/schema-invalid
+
+> `schema.ts` and `fill-spec.ts` are a matched pair. This is every check that makes sure
+> they actually agree.
+
+## Rule
+
+A section's `schema.ts` and `fill-spec.ts` must, together:
+
+- **parse** — each is `as const satisfies` its shape (`SectionSchemaShape`,
+  `FillSpecShape`); a value that doesn't satisfy it fails here with the parse error;
+- **cross-reference correctly** — every `fill-spec.ts` decision produces a slot that
+  actually exists in `schema.ts`, every `reads` entry names a real, author-declarable
+  facts key, every option's `affects_decisions`/`affects_slots` names a real decision or
+  slot;
+- **satisfy the closed per-type contracts** — an `object_list` slot's `item_order`
+  covers every field, a `select` slot's cases match its transform, a group's members are
+  slots that exist, and the rest of the per-slot-type rules the schema system documents.
+
+One violation is one diagnostic; a section with several wrong things reports all of them
+in the same run, not one per fix.
+
+This is the id you also see when a section **cannot be built or parsed at all** — a
+syntax error in `schema.ts`, a missing export, an import that doesn't resolve. The
+message in that case is the underlying build error, relocated to the file it points at.
+
+## Reason
+
+`fill-spec.ts` is not free-standing — every decision it declares exists to fill a slot
+`schema.ts` declared, and every fact it reads must be one the platform actually exposes.
+A decision that produces a slot no schema declares, or reads a fact that doesn't exist,
+is not a style problem: the fill pipeline would either drop the output on the floor or
+crash trying to read a fact key that isn't there. Catching the mismatch here, at author
+time, is the difference between a red check and a listing that silently fails to fill.
+
+## Fix
+
+Read the message: it names the section, the decision or slot in question, and what's
+wrong with it. Fix whichever side is actually stale — the schema, or the fill-spec.
+
+### Before
+
+```ts
+// sections/facts/schema.ts
+export const schema = {
+  meta: { displayName: "Facts" },
+  slots: {
+    year_built: { type: "text", required: false, produced_by: "year_built_text" },
+  },
+  options: {},
+} as const satisfies SectionSchemaShape;
+```
+
+```ts
+// sections/facts/fill-spec.ts
+export const fillSpec = {
+  reads: [],
+  decisions: [
+    { id: "year_built_text", type: "text-block", produces: ["year_built_summary"], length_cap: 20 },
+    //                                                       ^ typo — schema.ts declares "year_built"
+  ],
+} as const satisfies FillSpecShape;
+```
+
+```text
+Section "facts": fill-spec decision "year_built_text" produces unknown slot "year_built_summary".
+```
+
+### After
+
+```ts
+// sections/facts/fill-spec.ts
+export const fillSpec = {
+  reads: [],
+  decisions: [
+    { id: "year_built_text", type: "text-block", produces: ["year_built"], length_cap: 20 },
+  ],
+} as const satisfies FillSpecShape;
+```
+
+## See also
+
+- [The schema system](../schema-system.md) — the full authoring contract for `schema.ts`
+  and `fill-spec.ts`.
+- [`fixtures-invalid`](fixtures-invalid.md) — the sibling gate on the third contract
+  file, `fixtures.ts`.
+- [`manifest-invalid`](manifest-invalid.md) — the same kind of cross-reference check, one
+  level up, on a template composing several sections.
+- [`bundle-incomplete`](bundle-incomplete.md) — reported instead of this id when a
+  contract file is missing outright, rather than present and wrong.

package/docs/rules/size-section-css.md

@@ -46,8 +46,8 @@ Three moves, in order of how often they work:
    stylesheet plus opt-in modules, *and* a fat "everything" bundle that is the one you get
    from copying the quickstart. Take the core, plus only the modules you use.
 2. **Cut the webfont.** If the package's stylesheet drags in a font for its icons, and you
-   are using three of those icons, replace them with inline SVG — or with a family the page's
-   theme already declares (`--tr-font-sans`, `--tr-font-serif`), which costs nothing
+   are using three of those icons, replace them with inline SVG — or with a family the
+   template's theme already declares in `fonts` (`--tr-font-<name>`), which costs nothing
    because it is already loaded.
 3. **Drop the package and hand-write the residue.** If you use one component from a large
    widget library, its stylesheet is paying for components you never render.