@homepages/template-kit 0.2.0 → 0.3.0

package/dist/styles.css

@@ -1,15 +1,26 @@
 /*
- * @homepages/template-kit — theme tokens + kit source registration.
+ * @homepages/template-kit — the global Tailwind preamble.
  *
- * Import this AFTER `@import "tailwindcss";` in your own CSS entry:
+ * Import this AFTER `@import "tailwindcss";` in your own CSS entry, and import your
+ * template's compiled theme after it:
  *
  *   @import "tailwindcss";
  *   @import "@homepages/template-kit/styles.css";
+ *   @import "./theme.css";        // compileThemeToCss(yourTheme) output
  *
  * This file must NOT import Tailwind itself. Exactly one `@import "tailwindcss"` may
  * exist per build graph — your entry owns it. Two double-emit Tailwind's preflight
  * reset (box-sizing declared twice, ~4 KB of duplicate base layer).
  *
+ * WHAT IS HERE: only what is true of EVERY template — the breakpoint ladder, the
+ * spacing base unit, and the motion defaults.
+ *
+ * WHAT IS NOT: your design tokens. Colors, fonts, type, radii and shadows are yours.
+ * Declare them in `theme.ts` under names you choose, and `compileThemeToCss` generates
+ * the `@theme inline` alias layer that turns each one into a utility. Nothing about
+ * your visual system is shared, and there is no global file for you to edit to make a
+ * token of yours usable.
+ *
  * The @source below resolves relative to THIS FILE'S SHIPPED LOCATION (dist/styles.css),
  * registering the kit's compiled JS for class scanning — that is how the utility classes
  * baked into the kit's primitives reach your compiled CSS. It also overrides Tailwind's
@@ -23,107 +34,39 @@
  * utilities and 19 stray @property registrations, ~2.5 KB. If a primitive ever moves out
  * of primitives/, widen this — an unstyled <Image> in every template is the failure mode,
  * and scripts/verify-consumer.mjs is what catches it.
- *
- * The @theme block aliases Tailwind's utility namespace onto the `--tr-*` custom
- * properties your template's theme.ts supplies (`text-ink` → `var(--tr-color-ink)`).
- * The aliases are the cross-template contract; the values behind them are yours.
  */
 @source "./primitives/**/*.js";
 
+/* `@theme inline` so a spacing/breakpoint value is substituted straight into the
+ * utilities Tailwind generates (`.gap-2 { gap: .5rem }`), rather than emitted as a
+ * `:root` custom property the utilities then read through `var()`. These are fixed
+ * global constants, not per-page-overridable tokens, so inlining is both correct and
+ * what keeps the compiled output stable. Nothing here may reference a token a theme.ts
+ * defines. */
 @theme inline {
-  /* ---------- Colors (alias to the --tr-color-* values a theme.ts supplies) ---------- */
-  --color-ink:           var(--tr-color-ink);
-  --color-ink-soft:      var(--tr-color-ink-soft);
-  --color-ink-mute:      var(--tr-color-ink-mute);
-  --color-background:    var(--tr-color-background);
-  --color-surface:       var(--tr-color-surface);
-  --color-surface-alt:   var(--tr-color-surface-alt);
-  --color-border:        var(--tr-color-border);
-  --color-border-strong: var(--tr-color-border-strong);
-  --color-accent:        var(--tr-color-accent);
-  --color-accent-strong: var(--tr-color-accent-strong);
-  --color-accent-contrast: var(--tr-color-accent-contrast);
-  --color-primary:         var(--tr-color-primary);
-  --color-primary-fg:      var(--tr-color-primary-fg);
-  --color-primary-darker:  var(--tr-color-primary-darker);
-  --color-overlay:        var(--tr-color-overlay);
-  --color-overlay-strong: var(--tr-color-overlay-strong);
-  --color-overlay-light:  var(--tr-color-overlay-light);
-  --color-footer-bg:      var(--tr-color-footer-bg);
-  --color-footer-fg:      var(--tr-color-footer-fg);
-  --color-footer-fg-mute: var(--tr-color-footer-fg-mute);
-  --color-footer-divider: var(--tr-color-footer-divider);
-
-  /* Decorative brand swatches — the open `palette` escape hatch in TokenTheme.
-   * A theme that omits one leaves its utility resolving to an unset custom
-   * property; only reach for these when a semantic role genuinely doesn't fit. */
-  --color-yellow-deep:  var(--tr-color-yellow-deep);
-  --color-yellow-200:   var(--tr-color-yellow-200);
-  --color-yellow-100:   var(--tr-color-yellow-100);
-  --color-brown:        var(--tr-color-brown);
-  --color-green:        var(--tr-color-green);
-  --color-blue:         var(--tr-color-blue);
-  --color-rule:         var(--tr-color-rule);
-  --color-gray-light:   var(--tr-color-gray-light);
-  --color-team-gold:   var(--tr-color-team-gold);
-  --color-mute:         var(--tr-color-mute);
-  --color-scrim:        var(--tr-color-scrim);
-  --color-footer-line:  var(--tr-color-footer-line);
-  --color-footer-mute:  var(--tr-color-footer-mute);
-  --color-divider-40:   var(--tr-color-divider-40);
-  --color-contact-deep: var(--tr-color-contact-deep);
-  --color-header-deep:  var(--tr-color-header-deep);
-
-  /* ---------- Fonts ---------- */
-  --font-sans:    var(--tr-font-sans);
-  --font-display: var(--tr-font-sans);
-  --font-serif:   var(--tr-font-serif);
-  --font-num:     var(--tr-font-num);
-  --font-label:   var(--tr-font-label);
-
-  /* ---------- Type scale (mobile baseline; layer up with md:/lg:) ---------- */
-  --text-xs:      var(--tr-text-xs);
-  --text-sm:      var(--tr-text-sm);
-  --text-base:    var(--tr-text-base);
-  --text-lg:      var(--tr-text-lg);
-  --text-xl:      var(--tr-text-xl);
-  --text-2xl:     var(--tr-text-2xl);
-  --text-3xl:     var(--tr-text-3xl);
-  --text-4xl:     var(--tr-text-4xl);
-  --text-5xl:     var(--tr-text-5xl);
-  --text-display: var(--tr-text-display);
-
-  /* ---------- Spacing (Tailwind's own scale — no custom aliases) ---------- */
+  /* ---------- Spacing ---------- */
   --spacing: 0.25rem;  /* v4 base unit; Tailwind multiplies (e.g. p-4 = 1rem) */
 
-  /* ---------- Radii ---------- */
-  --radius-sm:   var(--tr-radius-sm);
-  --radius-md:   var(--tr-radius-md);
-  --radius-lg:   var(--tr-radius-lg);
-  --radius-full: var(--tr-radius-full);
-
-  /* ---------- Shadows ---------- */
-  --shadow-sm: var(--tr-shadow-sm);
-  --shadow-md: var(--tr-shadow-md);
-  --shadow-lg: var(--tr-shadow-lg);
-
-  /* ---------- Motion ---------- */
+  /* ---------- Motion ----------
+   * The --tr-* values these read are defined in base.css, which every page loads. */
   --default-transition-duration: var(--tr-duration-fast);
   --default-transition-timing-function: var(--tr-ease);
 
   /* ---------- Canonical breakpoint ladder ----------
-   * Eight canonical widths — the same set the preview grid and the screenshot
-   * harness verify a section against (VERIFICATION_WIDTHS is the matching TS
-   * constant). 350 is the mobile-first BASE (no prefix); the other seven are
-   * named breakpoints:
+   * Eight canonical widths — the same set the preview grid and the screenshot harness
+   * verify a section against. `VERIFICATION_WIDTHS` (design-system/breakpoints.ts) is
+   * the matching TS constant; CSS cannot import it, so `src/css/styles.test.ts` fails
+   * the build if the two ever drift.
+   *
+   * 350 is the mobile-first BASE (no prefix); the other seven are named breakpoints:
    *
    *   bp390 (390) · bp425 (425) · bp512 (512) · md (768) · lg (1024)
    *   · bp1440 (1440) · bp1920 (1920)
    *
    * `md` and `lg` keep Tailwind's own names and values. The off-ladder defaults
-   * (sm/xl/2xl) are reset to `initial` so a section cannot come to depend on a
-   * width nobody screenshots. A swap-heavy section may still reach for a raw
-   * `@media` micro-breakpoint at an off-ladder width (e.g. 640 / 769).
+   * (sm/xl/2xl) are reset to `initial` so a section cannot come to depend on a width
+   * nobody screenshots. A swap-heavy section may still reach for a raw `@media`
+   * micro-breakpoint at an off-ladder width (e.g. 640 / 769).
    */
   --breakpoint-sm:    initial;
   --breakpoint-bp390:  390px;

package/docs/INDEX.md

@@ -2,7 +2,7 @@
 purpose: Router for the docs corpus that ships inside the @homepages/template-kit npm package.
 status: living
 related: []
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # template-kit docs — router
 
@@ -16,7 +16,8 @@ detail.
 | `llms.txt` | Machine-readable index of this corpus for an agent working inside an installed kit | orienting an agent in a consuming workspace |
 | `schema-system.md` | The section authoring contract: `schema.ts` / `fill-spec.ts` / `fixtures.ts` / `Renderer.tsx`, `SectionProps` inference, the closed source/transform vocabulary, and the golden property fixtures | authoring or changing any section |
 | `primitives.md` | The five contract primitives (`Section`, `Slot`, `SlotItem`, `SlotGroup`, `Image`) and the marker attributes they emit | writing a section's markup |
-| `theme-and-css.md` | The two CSS entries, the one-Tailwind-import rule, `TokenTheme`, the breakpoint ladder, and the opt-in `content-visibility` recipe for long, image-heavy pages | a template's theme, its CSS entry, or a long page with a live map or full-screen overlay |
+| `theme-and-css.md` | The two CSS entries, the one-Tailwind-import rule, `TokenTheme` (your own token names → your own Tailwind utilities), the `template-kit theme` command that generates `theme.css` from `theme.ts`, the breakpoint ladder, and the opt-in `content-visibility` recipe for long, image-heavy pages | a template's theme, its CSS entry, or a long page with a live map or full-screen overlay |
 | `islands.md` | Interactivity: `"use client"` components, the serializable-props rule, editor options, the loader | anything interactive in a section |
-| `eslint.md` | The `@homepages/template-kit/eslint` preset: zero-config setup and its glob scope | wiring up lint in a template workspace |
+| `eslint.md` | The `@homepages/template-kit/eslint` preset: the two-line config, the ESLint + parser install it expects, and its glob scope | wiring up lint in a template workspace |
+| `check.md` | The `template-kit check` CLI command: the toolchain it resolves from your workspace, its stages, `--all`/`--json`, output shape, and exit code | running `check` locally or wiring it into CI |
 | `rules/` | One page per rule-id (`template-kit/*`), across both venues — the id printed by a lint or `check` failure resolves here. `rules/INDEX.md` routes them; `rules/server-vs-client.md` is the concept the server-rendering rules assume | any lint or `check` failure |

package/docs/check.md

@@ -0,0 +1,121 @@
+---
+purpose: The `template-kit check` command — what it runs, its flags, its output shape, and its exit code.
+status: living
+related: [INDEX.md, rules/INDEX.md, eslint.md, theme-and-css.md]
+updated: 2026-07-15
+---
+# template-kit check
+
+`template-kit check` is the one command that answers "will the platform accept this
+template?" — the same gate you run locally and the one the registry re-runs when you
+submit. Every failure prints a stable `template-kit/<id>`, a `file:line` where one
+applies, and a one-line fix hint. The id resolves to its own page under
+[`rules/`](rules/INDEX.md).
+
+## Usage
+
+```bash
+template-kit check                # infer the template from cwd, or the workspace's one template
+template-kit check <template>     # check one named template by its key
+template-kit check --all          # check every template in the workspace
+template-kit check --json         # machine-readable report (combine with any of the above)
+```
+
+Run it from the workspace root, or from inside a template's own folder — a bare `check`
+infers which template you mean. A workspace with more than one template must either name
+one or pass `--all`.
+
+### What it needs installed
+
+```bash
+npm i -D typescript eslint @typescript-eslint/parser esbuild
+```
+
+`check` runs **your** toolchain, not a copy of its own: it resolves TypeScript, ESLint
+and esbuild from your workspace, so the compiler that judges your types is the one you
+pinned, and a linter and a bundler never end up in the production install of a package
+whose job is to render sections. A missing one is reported by name, with the install
+line to fix it.
+
+## What it runs
+
+Two granularities, because a workspace has one `package.json` and one lockfile, but can
+hold many templates.
+
+**Six authoring stages**, run in order, once per selected template. None of them abort
+the run — a template with several unrelated problems reports all of them in one pass, not
+one class of fix at a time:
+
+1. **typecheck** — the workspace's own TypeScript compiles the template's files, judged
+   against the workspace's own `tsconfig.json`.
+2. **lint** — the workspace's own ESLint, running the kit's shipped preset over the
+   template's files. See [the ESLint preset](eslint.md) for the rules this stage shares
+   with your editor.
+3. **validate** — the schema, fill-spec, fixtures, and manifest contracts: every
+   cross-reference between a section's contract files, and a template's `manifest.json`
+   against the sections it composes.
+4. **tree** — the rules a one-file-at-a-time linter cannot express: a missing contract
+   file, a slot declared in `schema.ts` with no marker anywhere in the section's JSX, a
+   hand-written CSS file's own rules.
+5. **render** — a determinism probe (every fixture is rendered twice; the two outputs
+   must be byte-identical) and a scan of the rendered HTML for objective defects — a
+   stray `[object Object]`, a bare `null`/`undefined`/`NaN` leaf, a `src`-less `<img>` —
+   plus, for the `typical` fixture, that the editor's sidebar order matches the page's
+   real render order.
+6. **size** — every section's renderer bundle and compiled stylesheet, gzipped, against a
+   fixed byte budget.
+
+**The dependency gates** run once per invocation, never once per template — they are
+properties of the workspace's one lockfile and installed tree, not of any one template:
+a lockfile present and satisfying `package.json`, exactly one copy of React installed,
+no `npm audit` finding at high or critical severity, and every shipped dependency's
+license on an allowlist.
+
+A run that selects zero templates to check is itself a failure —
+[`no-templates`](rules/no-templates.md) — never a silent pass.
+
+## Output
+
+Human-readable output prints one line per template (`✓ <key>`, or `✗ <key> — N
+problem(s)` followed by each finding), then any workspace-level findings from the
+dependency gates, then `check passed` if everything passed.
+
+`--json` prints one report object instead, keyed per template so a single-template
+consumer (the registry, ingesting one submission) and an all-templates consumer (your
+own CI) parse the same shape:
+
+```ts
+{
+  ok: boolean,
+  kitVersion: string,
+  templates: {
+    [templateKey: string]: { ok: boolean, diagnostics: Diagnostic[] },
+  },
+  // Dependency-gate findings — evaluated once, not per template.
+  workspace: { ok: boolean, diagnostics: Diagnostic[] },
+}
+```
+
+Each `Diagnostic` carries a `ruleId` (`template-kit/<id>`), the `template` it belongs to,
+an optional `section` and `file`/`line`, a `message`, and a `fix`.
+
+## Exit code
+
+`0` iff every selected template and the workspace pass. `1` otherwise — including when
+the run itself can't proceed at all (an unknown template name, no `templates/` folder
+in the workspace).
+
+## Thresholds are not configurable
+
+Every byte budget, severity floor, and license allowlist `check` enforces is a platform
+acceptance criterion, not a per-workspace preference — there is no config file or flag
+that raises them. If a template has a legitimate reason to need an exception, ask the
+platform team; a workaround that quietly disables a gate will simply fail again at
+submission.
+
+## See also
+
+- [Rules](rules/INDEX.md) — every id `check` (and the lint preset) can print, one page
+  each, Rule / Reason / Fix.
+- [ESLint preset](eslint.md) — the one-file-at-a-time half of the same rule set, run
+  directly by your editor, not only through `check`.

package/docs/eslint.md

@@ -1,7 +1,7 @@
 ---
 purpose: The authoring-lint preset shipped at `@homepages/template-kit/eslint` — setup and scope. Per-rule reference lives in `rules/`.
 status: living
-related: [INDEX.md, rules/INDEX.md, islands.md, theme-and-css.md, primitives.md]
+related: [INDEX.md, rules/INDEX.md, check.md, islands.md, theme-and-css.md, primitives.md]
 updated: 2026-07-14
 ---
 # ESLint preset
@@ -12,6 +12,10 @@ rule namespace.
 
 ## Setup
 
+```bash
+npm i -D eslint @typescript-eslint/parser
+```
+
 ```js
 // eslint.config.mjs
 import kit from "@homepages/template-kit/eslint";
@@ -19,9 +23,15 @@ export default kit;
 ```
 
 That is the whole setup — no plugin registration, no parser wiring, no tsconfig.
-The preset ships its own parser (`@typescript-eslint/parser`, a real `dependency`
-of the kit, not a devDependency) and sets `languageOptions` itself, so `npm i -D
-eslint` plus the three lines above is a complete consumer config.
+The preset registers its rules and sets `languageOptions` (parser included) itself,
+so those two lines are a complete config.
+
+You install ESLint and the parser yourself because the kit deliberately does **not**
+depend on them: a package whose main entry is a set of React primitives must not drag
+a linter into the production install of every app that renders a template. The preset
+resolves the parser from your workspace when you import it. If you see
+`Cannot find package '@typescript-eslint/parser'`, that is the install line above
+missing.
 
 The preset is **syntactic only** — it never sets `parserOptions.project` or
 `projectService`. Nothing it enforces requires type information, which is what
@@ -36,7 +46,7 @@ three config entries, matched by glob rather than by directory depth:
 
 | Entry | Files | Rules |
 |---|---|---|
-| `template-kit/authoring` | `**/*.ts`, `**/*.tsx` | the nine file-scoped rules — see [`rules/`](rules/INDEX.md) |
+| `template-kit/authoring` | `**/*.ts`, `**/*.tsx` | the eleven file-scoped rules — see [`rules/`](rules/INDEX.md) |
 | `template-kit/contract-files` | `**/Renderer.tsx`, `**/schema.ts`, `**/fill-spec.ts`, `**/fixtures.ts` | `no-client-directive-in-contract` |
 | `template-kit/renderer` | `**/Renderer.tsx` | `props-from-schema` |
 
@@ -50,6 +60,6 @@ Every rule the preset enforces — what it bans, why, and a before/after fix —
 documented once, per id, in [`rules/`](rules/INDEX.md). Rules scoped to a single
 file are enforced here, by this preset; rules scoped to the **tree** — a missing
 contract file, a slot declared in `schema.ts` but unmarked in `Renderer.tsx`, a CSS
-budget — cannot be expressed one-file-at-a-time and belong to `template-kit check`
-under the same `template-kit/<id>` namespace. One namespace, two venues: the id
-printed by either failure resolves to exactly one page.
+budget — cannot be expressed one-file-at-a-time and belong to
+[`template-kit check`](check.md) under the same `template-kit/<id>` namespace. One
+namespace, two venues: the id printed by either failure resolves to exactly one page.

package/docs/llms.txt

@@ -4,9 +4,11 @@
 > inside the npm package so an agent can read it locally, versioned in lockstep
 > with the code it describes.
 
-Status: 0.0.x. The schema system, the contract primitives, and the theme tokens are
+Status: 0.0.x. The schema system, the contract primitives, and the theme system are
 complete — a section is authorable end to end against the kit. The `template-kit`
-CLI's commands arrive with the surfaces they drive.
+CLI's `check` and `theme` commands are implemented — see [Check](check.md) and
+[Theme and CSS](theme-and-css.md#generating-themecss); its other commands arrive with
+the surfaces they drive.
 
 Everything an author writes a section against is imported from the package root —
 `@homepages/template-kit`, no subpath imports. The two CSS entries
@@ -28,15 +30,25 @@ Everything an author writes a section against is imported from the package root
   contract (`ATTR_SLOT_ID`, `ATTR_SLOT_ITEM`, …). Presentation is the template's own JSX.
 - [Theme and CSS](theme-and-css.md): the two CSS entries and how they load; import
   Tailwind exactly once; `base.css` ships no reset of its own — it requires the
-  preflight your Tailwind entry brings; `TokenTheme` + `compileThemeToCss`; the breakpoint ladder
-  (base 350, `bp390` `bp425` `bp512` `md` `lg` `bp1440` `bp1920`); the opt-in
-  `content-visibility` recipe for long, image-heavy pages, and why it requires a
-  full-screen overlay to be appended to `document.body` rather than rendered inside
-  the section.
+  preflight your Tailwind entry brings; `TokenTheme` — a template declares its own
+  tokens under names it chooses (`colors` `fonts` `type` `radii` `shadows` `layout`,
+  kebab-case, emitted verbatim) and each becomes a Tailwind utility; the `template-kit
+  theme` CLI command that compiles `theme.ts` to the generated `theme.css` the
+  Tailwind entry `@import`s after the kit's `styles.css`; the required `document`
+  block; the breakpoint ladder (base 350, `bp390` `bp425` `bp512` `md` `lg` `bp1440`
+  `bp1920`); the opt-in `content-visibility` recipe for long, image-heavy pages, and
+  why it requires a full-screen overlay to be appended to `document.body` rather than
+  rendered inside the section.
 - [README](../README.md): install, exports, and the release flow.
 - [Islands](islands.md): interactivity — client components, the serializable-props contract, editor options, and the browser loader.
-- [ESLint preset](eslint.md): `@homepages/template-kit/eslint`, the zero-config flat-config
-  preset — setup and its three-entry glob scope. Per-rule reference lives in `rules/`.
+- [ESLint preset](eslint.md): `@homepages/template-kit/eslint`, the flat-config preset —
+  a two-line config with no parser wiring, over an ESLint + `@typescript-eslint/parser`
+  install of your own (the kit depends on neither — both resolve from your workspace).
+  Its three-entry glob scope. Per-rule reference lives in `rules/`.
+- [Check](check.md): the `template-kit check` CLI command — the toolchain it runs (your
+  TypeScript, ESLint and esbuild, resolved from your workspace), its six per-template
+  stages, the once-per-invocation dependency gates, `--all`/`--json`, the report shape,
+  and the exit code. Thresholds are fixed platform acceptance criteria, not configurable.
 - [Rules](rules/INDEX.md): every rule-id a lint or `check` failure can print, under the
   `template-kit/<id>` namespace, one page each at `docs/rules/<id>.md` — Rule / Reason /
   Fix / Before→After. **The loop:** see an id in a failure → read `docs/rules/<id>.md` →

package/docs/primitives.md

@@ -176,6 +176,11 @@ When `src` is empty the wrapper renders alone as a neutral `role="img"` rect, ke
 layout box and the slot selectable. **That deterministic empty state is the reason the
 frame exists**, so pass `aspectRatio` rather than sizing the image from its own content.
 
+The frame's placeholder fill rides on `.tr-image-frame` (from
+[`base.css`](theme-and-css.md#basecss-requires-a-tailwind-entry)), not on a theme utility:
+you name your own tokens, so no primitive may assume a colour of yours exists. Retint it
+per template by setting `--tr-image-frame-bg`; it defaults to a neutral grey.
+
 **Responsive.** Given a `responsive` descriptor the `<img>` is wrapped in `<picture>` with
 per-format AVIF/WebP `<source srcset>` (the base raster stays on the `<img>`), plus a
 media-gated mobile crop when `responsiveMobile` + `mobileBreakpoint` are set, and carries

package/docs/rules/INDEX.md

@@ -1,7 +1,7 @@
 ---
 purpose: Router for the rule corpus — every template-kit/<id> an author can hit, and the page that explains it.
 status: living
-related: [server-vs-client.md, ../eslint.md, ../INDEX.md]
+related: [server-vs-client.md, ../eslint.md, ../check.md, ../INDEX.md]
 updated: 2026-07-14
 ---
 # Rules
@@ -13,8 +13,8 @@ and resolves to exactly one page here: `docs/rules/<id>.md`.
 in a Renderer) and are enforced by the ESLint preset. Others are properties of the
 **tree** (a slot declared in `schema.ts` but never marked in the JSX, a stylesheet, a
 dependency, a byte budget) and cannot be expressed one file at a time; those are enforced
-by `template-kit check`. You never need to know which engine produced a violation — only
-the id, which names its page either way.
+by [`template-kit check`](../check.md). You never need to know which engine produced a
+violation — only the id, which names its page either way.
 
 Read [server vs client](server-vs-client.md) first if you are here for any rule that
 mentions "server-rendered code" or an island. It is the one concept those rules assume,
@@ -31,9 +31,13 @@ and it is explained there rather than on each of them.
 | [`no-raw-element`](no-raw-element.md) | eslint | No raw `<section>` or `<img>` — use `<Section>` and `<Image>`. |
 | [`image-bare-needs-reason`](image-bare-needs-reason.md) | eslint | `<Image bare>` needs a `// bare:` comment saying why it skips the frame. |
 | [`slot-marker-literal`](slot-marker-literal.md) | eslint | A slot-marker key must be a string literal, not an expression. |
-| [`no-hex`](no-hex.md) | eslint | No hard-coded colours. Islands are NOT exempt. |
+| [`no-hex`](no-hex.md) | eslint | No hard-coded colours — the one legal colour function is a `color-mix()` over theme-derived arguments. Islands are NOT exempt. |
 | [`no-css-import-from-render-path`](no-css-import-from-render-path.md) | eslint | No relative/absolute .css import from a section's render path — a package's is the sanctioned channel. |
 | [`bundle-incomplete`](bundle-incomplete.md) | check | A section folder is missing one of its four required files. |
+| [`bundle-binary-asset`](bundle-binary-asset.md) | check | A binary asset file sits in a section folder — not supported yet. |
+| [`schema-invalid`](schema-invalid.md) | check | A section's schema.ts or fill-spec.ts fails a contract assertion, or cannot be loaded. |
+| [`fixtures-invalid`](fixtures-invalid.md) | check | A section's fixtures.ts does not satisfy the fixture-module shape. |
+| [`manifest-invalid`](manifest-invalid.md) | check | A template's manifest.json is missing, unparseable, or violates the manifest contract. |
 | [`missing-slot-marker`](missing-slot-marker.md) | check | An editable slot in schema.ts has no marker in the section's JSX. |
 | [`slot-group-marker`](slot-group-marker.md) | check | A group with two or more members has no `<SlotGroup>` wrapper. |
 | [`css-reason`](css-reason.md) | check | A hand-written CSS file must open with a `css-reason:` comment. |
@@ -41,6 +45,7 @@ and it is explained there rather than on each of them.
 | [`unlayered-fence`](unlayered-fence.md) | check | An `/* unlayered: */` escape hatch must be balanced and give a reason. |
 | [`sidebar-order`](sidebar-order.md) | check | Schema slot order must match the order the page renders them in. |
 | [`typecheck`](typecheck.md) | check | The template must compile under TypeScript. |
+| [`parse-error`](parse-error.md) | check | A file could not be parsed at all — a syntax error, not a rule violation. |
 | [`determinism-drift`](determinism-drift.md) | check | Rendering the same fixture twice must produce byte-identical HTML. |
 | [`render-invariant`](render-invariant.md) | check | Rendered output must carry no [object Object], bare null/undefined/NaN leaf, or src-less `<img>`. |
 | [`lockfile-missing`](lockfile-missing.md) | check | The workspace has no package-lock.json. |
@@ -50,9 +55,11 @@ and it is explained there rather than on each of them.
 | [`license-denied`](license-denied.md) | check | A production dependency's license is not on the allowlist. |
 | [`size-renderer-bundle`](size-renderer-bundle.md) | check | A section's renderer bundle exceeds its byte budget. |
 | [`size-section-css`](size-section-css.md) | check | A section's compiled CSS exceeds its byte budget. |
+| [`no-templates`](no-templates.md) | check | The workspace has no template to check at all. |
 
 ## See also
 
 - [Server vs client](server-vs-client.md) — how a file is scoped, and which rules stop at
   the hydration boundary.
 - [ESLint preset](../eslint.md) — setting the preset up in a template workspace.
+- [Check](../check.md) — running `template-kit check`, its flags, output shape, and exit code.

package/docs/rules/bundle-binary-asset.md

@@ -0,0 +1,102 @@
+---
+purpose: The template-kit/bundle-binary-asset authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, bundle-incomplete.md, ../primitives.md]
+updated: 2026-07-14
+---
+# template-kit/bundle-binary-asset
+
+> A section folder holds code, not static files. A binary asset dropped into it has no
+> build meaning yet.
+
+## Rule
+
+No file inside a section folder may be a binary asset: an image, a font, a video, an
+audio file, an archive, a document. The check looks two ways:
+
+- **By extension** — `.svg`, `.png`, `.jpg`/`.jpeg`, `.gif`, `.webp`, `.avif`, `.ico`,
+  `.woff`/`.woff2`, `.ttf`, `.otf`, `.eot`, `.mp4`, `.webm`, `.mov`, `.mp3`, `.wav`,
+  `.pdf`, `.zip`.
+- **By content** — any other file whose first bytes contain a NUL byte, catching an
+  asset type the extension list doesn't name.
+
+This is scoped to the section folder itself (`Renderer.tsx`, `schema.ts`, `components/`,
+everything under it) — not to the photos a listing supplies. Those arrive at runtime
+through a slot's `src`, never as a file that ships inside your section.
+
+## Reason
+
+A section folder is published as source: its content hash covers every file in it, and
+the platform has no pipeline yet to fingerprint, optimize, or serve a binary file that
+lives alongside your code. A `.png` committed today has no URL tomorrow — there is
+nowhere for it to be requested from.
+
+Everything a section needs to draw — an icon, a divider graphic, a background pattern —
+is expressible as markup instead: an inline `<svg>`, or a shape built from CSS. That
+markup is text, ships with the rest of your JSX, and needs no pipeline at all.
+
+## Fix
+
+Delete the binary file and inline its content as SVG markup — either directly in the
+JSX that used it, or as its own small component if more than one place needs it.
+
+### Before
+
+```text
+sections/hero/
+  Renderer.tsx
+  schema.ts
+  fill-spec.ts
+  fixtures.ts
+  assets/
+    arrow.svg          ← binary asset in the bundle
+```
+
+```tsx
+// sections/hero/Renderer.tsx
+import arrowUrl from "./assets/arrow.svg";
+
+export function Renderer() {
+  return <img src={arrowUrl} alt="" className="h-4 w-4" />;
+}
+```
+
+### After
+
+```text
+sections/hero/
+  Renderer.tsx
+  schema.ts
+  fill-spec.ts
+  fixtures.ts
+  components/
+    ScrollArrow.tsx     ← markup, not a binary file
+```
+
+```tsx
+// sections/hero/components/ScrollArrow.tsx
+export function ScrollArrow() {
+  return (
+    <svg viewBox="0 0 16 16" className="h-4 w-4" fill="none" aria-hidden="true">
+      <path d="M8 3v10M3 9l5 4 5-4" stroke="currentColor" strokeWidth="1.5" />
+    </svg>
+  );
+}
+```
+
+```tsx
+// sections/hero/Renderer.tsx
+import { ScrollArrow } from "./components/ScrollArrow.js";
+
+export function Renderer() {
+  return <ScrollArrow />;
+}
+```
+
+## See also
+
+- [`bundle-incomplete`](bundle-incomplete.md) — the other rule on the folder's contents,
+  checked by the same pass over the section anatomy.
+- [Contract primitives](../primitives.md) — `Image`, the primitive that owns every photo
+  a listing supplies. It reads a `src` at runtime; it is not a way to ship a binary file
+  inside your section.