@homepages/template-kit 0.1.0 → 0.3.0

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

@@ -0,0 +1,95 @@
+---
+purpose: The template-kit/size-section-css authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, size-renderer-bundle.md, ../theme-and-css.md]
+updated: 2026-07-14
+---
+# template-kit/size-section-css
+
+> A section's compiled CSS must be **≤ 50 KB gzip** — **including the package CSS its module
+> graph imports.** That inclusion is the whole point of the rule.
+
+## Rule
+
+A section's compiled cascade layer must gzip to **50 KB or less**. What is measured is
+everything that lands in the layer:
+
+- the section's hand-written CSS, and
+- **every package stylesheet its module graph imports** — the `import "swiper/css"` in a
+  component, an island, or a marked enhancer.
+
+The budget is **visible in `template-kit check`'s configuration and is not
+author-overridable**. A workspace cannot raise it, and there is no per-section exemption.
+
+## Reason
+
+Same page, same phone, same buyer as
+[`size-renderer-bundle`](size-renderer-bundle.md) — and here the bytes are worse, because
+CSS blocks the first paint.
+
+"Including package CSS" is not a technicality; it is the failure this rule exists to catch.
+Your own stylesheet is almost never the problem — it is a few kilobytes of overrides. The
+package's is. And the reason it is invisible to you is the mechanism: a package stylesheet's
+`url()` references — its icon sprites, its webfont — are **inlined as `data:` URIs** into the
+compiled stylesheet. A 300 KB font file arrives in your published CSS without you ever
+having seen a 300 KB file. Nothing in your source looks large. Nothing in the package's
+`dist` listing looks alarming. The compiled layer is 400 KB.
+
+So the number this check reports is frequently the first time anyone finds out what a
+one-line CSS import actually cost.
+
+## Fix
+
+Three moves, in order of how often they work:
+
+1. **Import the slimmest entry the package offers.** Most CSS-shipping packages have a core
+   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
+   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.
+
+### Before
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import Swiper from "swiper";
+import "swiper/swiper-bundle.css"; // ← every module Swiper ships, plus its icon font
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  // …uses navigation arrows and pagination dots, and nothing else
+}
+```
+
+### After
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import Swiper from "swiper";
+import "swiper/css";            // ← the core layout only
+import "swiper/css/navigation"; // ← the two modules this carousel actually uses
+import "swiper/css/pagination";
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  // …
+}
+```
+
+The arrows and dots that came from the bundle's icon font are drawn as inline SVG in the
+component instead, so nothing pulls a webfont into the layer.
+
+## See also
+
+- [`size-renderer-bundle`](size-renderer-bundle.md) — the same budget on the section's
+  JavaScript.
+- [`no-bare-css-import`](no-bare-css-import.md) — why a package's stylesheet is imported from
+  code and never `@import`ed from CSS.
+- [Theme and CSS](../theme-and-css.md) — the fonts and tokens the page already loads, which
+  cost you nothing to reuse.

package/docs/rules/slot-group-marker.md

@@ -0,0 +1,127 @@
+---
+purpose: The template-kit/slot-group-marker authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../primitives.md, ../schema-system.md]
+updated: 2026-07-14
+---
+# template-kit/slot-group-marker
+
+> A group declared in `meta.groups` with **two or more members** must be wrapped in
+> `<SlotGroup id="…">` in the JSX. Grouping is authored in two places, and they must agree.
+
+## Rule
+
+For every entry in `schema.ts`'s `meta.groups` whose flattened member list has **≥ 2
+members**, the section's JSX must contain `<SlotGroup id="<that group's id>">` wrapping a
+container that is a **shared ancestor** of every member's marker.
+
+"Flattened" is literal: `members: ["agent_name", ["agent_email", "agent_phone"]]` is three
+members, not two — a `[a, b]` tuple is a 2-up row, not a single member.
+
+Membership is read from the typed `meta.groups` block. The check never guesses a group by
+scanning your markup for things that look related.
+
+Carve-outs:
+
+- **A 1-member group needs no wrapper.** One slot, one card — the group adds no grouping
+  the marker isn't already doing.
+- **A single slot rendered more than once is not a group.** An address shown in both a
+  desktop and a mobile layout is one slot in two places; it needs no `meta.groups` entry
+  and no `<SlotGroup>`.
+
+## Reason
+
+`meta.groups` makes the editor collapse several slots into **one accordion card** in the
+sidebar. The `<SlotGroup>` wrapper is the other half of that promise: the canvas outlines
+and selects the group as **one unit**, because its hover/selection chrome targets the
+`data-slot-group` container.
+
+Declare the group and omit the wrapper and the two halves disagree. The sidebar shows one
+card, and the canvas — with no group container to find — falls back to outlining the
+members one at a time. The user sees a single "Agent" card that highlights three separate
+boxes on the page.
+
+`SlotGroup` must be an **ancestor** of every member's `data-slot-id` element, because the
+editor resolves the group with `closest("[data-slot-group]")` from the clicked slot. A
+marker that sits beside the members rather than around them is never found.
+
+## Fix
+
+Wrap the members' shared container in `<SlotGroup id="…">`, using the **same id** as the
+`meta.groups` entry. If the slots do not actually edit as a unit, the other honest fix is
+to delete the group from `meta.groups` — then each slot is its own card and no wrapper is
+wanted.
+
+### Before
+
+```ts
+// sections/contact/schema.ts
+import type { SectionProps, SectionSchemaShape } from "@homepages/template-kit";
+
+export const schema = {
+  meta: {
+    displayName: "Contact",
+    groups: [
+      { id: "agent", label: "Agent", members: ["agent_name", ["agent_email", "agent_phone"]] },
+    ],
+  },
+  slots: {
+    agent_name: { type: "text", size: "short", required: true, editable_by_user: true },
+    agent_email: { type: "text", size: "short", required: false, editable_by_user: true },
+    agent_phone: { type: "text", size: "short", required: false, editable_by_user: true },
+  },
+} as const satisfies SectionSchemaShape;
+
+export type Props = SectionProps<typeof schema>;
+```
+
+```tsx
+// sections/contact/Renderer.tsx — template-kit/slot-group-marker: agent
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <div className="flex flex-col gap-2">
+        <Slot id="agent_name" textLeaf><h3>{slots.agent_name}</h3></Slot>
+        <Slot id="agent_email" textLeaf><span>{slots.agent_email}</span></Slot>
+        <Slot id="agent_phone" textLeaf><span>{slots.agent_phone}</span></Slot>
+      </div>
+    </Section>
+  );
+}
+```
+
+### After
+
+The container was already there — it just needed to be the group:
+
+```tsx
+// sections/contact/Renderer.tsx
+import { Section, Slot, SlotGroup } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <SlotGroup id="agent" className="flex flex-col gap-2">
+        <Slot id="agent_name" textLeaf><h3>{slots.agent_name}</h3></Slot>
+        <Slot id="agent_email" textLeaf><span>{slots.agent_email}</span></Slot>
+        <Slot id="agent_phone" textLeaf><span>{slots.agent_phone}</span></Slot>
+      </SlotGroup>
+    </Section>
+  );
+}
+```
+
+## See also
+
+- [Contract primitives: `SlotGroup`](../primitives.md#slotgroup--slots-edited-as-one-unit) —
+  the ancestor requirement and what the marker does.
+- [The schema system](../schema-system.md#grouping-slots-into-one-editor-card) — grouping is
+  declared in `meta.groups`; there is no per-slot `group` field.
+- [`missing-slot-marker`](missing-slot-marker.md) — the per-slot marker each member still
+  needs.

package/docs/rules/slot-marker-literal.md

@@ -0,0 +1,148 @@
+---
+purpose: The template-kit/slot-marker-literal authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../primitives.md, ../schema-system.md]
+updated: 2026-07-14
+---
+# template-kit/slot-marker-literal
+
+> A slot key must be written as a string literal wherever it is marked. `SlotItem` is
+> exempt.
+
+## Rule
+
+These four places carry a slot key, and each must be a **string literal**:
+
+| Where | Example |
+|---|---|
+| `<Slot id>` | `<Slot id="headline">` |
+| `<SlotGroup id>` | `<SlotGroup id="agent">` |
+| `slotId` on any element | `<Image slotId="hero_image" …>` |
+| `data-slot-id` / `data-slot-group` on any element | `<div data-slot-id="headline">` |
+
+Anything that is not a plain string literal reports: an expression (`<Slot id={key}>`), a
+template literal (`` <Slot id={`slot_${n}`}> ``), and a valueless attribute
+(`<div data-slot-id>`).
+
+**`SlotItem` is deliberately exempt.** Its prop is `index: number` — an array position,
+written `index={i}` inside a `.map()`, not a schema key. There is nothing to cross-check
+it against, so an expression there is correct and expected.
+
+## Reason
+
+This is not style. A separate, cross-file completeness check verifies that **every slot
+declared in `schema.ts` has a marker in the section's JSX** — and it reads these keys
+**statically**, from the source text, without running your Renderer.
+
+A key written as an expression is a key it cannot resolve. So the check cannot see the
+slot as marked, and — worse — the marker that actually reaches the browser is whatever
+your expression happened to evaluate to. The slot **silently loses editor selection**: it
+still fills, it still renders, and a user clicking on it in the editor selects nothing.
+Nothing throws. The failure is invisible until someone tries to edit that block.
+
+This rule exists **so that** [`missing-slot-marker`](missing-slot-marker.md) can work. A
+`.map()`-generated slot key defeats both at once: the completeness check reports the slot
+as unmarked, and no lint tells you why.
+
+## Fix
+
+This shows up in two different shapes, and the fix depends on which one you're in.
+
+**A key that is static but not literal** — held in a `const`, or assembled with a
+template literal — isn't generating anything: there is exactly one possible value, so
+unwrap it back into a plain inline string literal.
+
+**A key generated inside a `.map()` over an array** is a genuine collection: declare it
+as one slot in `schema.ts`, mark the array **once** with `<Slot>`, and mark each row with
+`<SlotItem index={i}>`.
+
+### Before
+
+```tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+const FIELD = "headline";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id={FIELD} as="h1" textLeaf>
+        <span>{slots.headline}</span>
+      </Slot>
+      <Slot id={`sub${"title"}`} textLeaf>
+        <p>{slots.subtitle}</p>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+Neither `FIELD` nor the template literal is doing any work — both spell out their whole
+value at the call site. That's the common case: a constant or a template literal standing
+in for a string that was always going to be one string.
+
+### After
+
+```tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Slot id="headline" as="h1" textLeaf>
+        <span>{slots.headline}</span>
+      </Slot>
+      <Slot id="subtitle" textLeaf>
+        <p>{slots.subtitle}</p>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+The other shape is different: a key actually produced by iterating an array is modelling
+a real collection, and the fix is structural, not a matter of unwrapping.
+
+```tsx
+// Before — `.map()` produces a different key each iteration; none of them is a literal.
+const FIELDS = ["headline", "subhead"] as const;
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      {FIELDS.map((key) => (
+        <Slot key={key} id={key} textLeaf>
+          <p>{slots[key]}</p>
+        </Slot>
+      ))}
+    </Section>
+  );
+}
+```
+
+A genuine collection keeps its loop — the literal key is on the `<Slot>`, and the loop
+variable stays on `SlotItem`'s `index`, which is exempt:
+
+```tsx
+<Slot id="amenities">
+  {slots.amenities.map((item, i) => (
+    <SlotItem key={item.id} index={i} as="li">
+      <h3>{item.label}</h3>
+    </SlotItem>
+  ))}
+</Slot>
+```
+
+Don't reach for this structural rewrite for the first case above — a named constant or a
+template literal is not a collection, and modelling it as one is solving a problem you
+don't have.
+
+## See also
+
+- [Contract primitives](../primitives.md#the-marker-contract) — the marker attributes and
+  which primitive emits each.
+- [Schema system](../schema-system.md) — where slot keys are declared.

package/docs/rules/typecheck.md

@@ -0,0 +1,103 @@
+---
+purpose: The template-kit/typecheck authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../schema-system.md]
+updated: 2026-07-14
+---
+# template-kit/typecheck
+
+> The template must compile. Every type error is one violation.
+
+## Rule
+
+The template's TypeScript must compile cleanly. The check resolves `typescript` from **your
+workspace's** `node_modules` — the compiler that runs is the one you installed, at the
+version you pinned, against your own `tsconfig.json`.
+
+If `typescript` is not installed, that is itself the diagnostic (with the fix), not a crash.
+
+## Reason
+
+The schema system is the section contract, and it is enforced **through the type system**.
+`SectionProps<typeof schema>` is not a convenience — it is the mechanism that keeps
+`schema.ts` and `Renderer.tsx` in agreement: a slot you add to the schema and forget to
+render, a slot you render under the wrong name, an optional slot you treat as always
+present, a slot whose type you assume wrong. Each of those is a compile error rather than a
+surprise on a stranger's published page.
+
+A template that does not typecheck has opted out of the only thing checking that the two
+files still describe the same section.
+
+## Fix
+
+Fix the type error. If the compiler itself is missing, install it and point your
+`tsconfig.json` at the kit's base config, which sets the module resolution and JSX settings
+the kit's types expect:
+
+```jsonc
+// tsconfig.json
+{ "extends": "@homepages/template-kit/tsconfig", "include": ["sections", "theme.ts"] }
+```
+
+```bash
+npm install --save-dev typescript
+```
+
+### Before
+
+`year_built` is declared `required: false`, so `SectionProps` resolves it to
+`string | null` — and the Renderer treats it as a `string`:
+
+```tsx
+// sections/facts/Renderer.tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      {/* error TS18047: 'slots.year_built' is possibly 'null'. */}
+      <Slot id="year_built" textLeaf>
+        <p>Built {slots.year_built.slice(0, 4)}</p>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+That is not a pedantic complaint. `required: false` means a thin listing really does arrive
+with no year, and this line really does throw on it.
+
+### After
+
+```tsx
+// sections/facts/Renderer.tsx
+import { Section, Slot } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      {slots.year_built ? (
+        <Slot id="year_built" textLeaf>
+          <p>Built {slots.year_built.slice(0, 4)}</p>
+        </Slot>
+      ) : null}
+    </Section>
+  );
+}
+```
+
+If the slot should never be absent, the other correct fix is in the schema — declare it
+`required: true`, and the type narrows to `string` everywhere.
+
+## See also
+
+- [The schema system](../schema-system.md#renderertsx--props-derived-never-hand-written) —
+  how `SectionProps` resolves each slot to its runtime type.
+- [`props-from-schema`](props-from-schema.md) — the rule that stops a hand-written `Props`
+  from disabling this inference in the first place.
+- [`render-invariant`](render-invariant.md) — the same class of bug caught at render time,
+  for the cases the types cannot see.

package/docs/rules/unlayered-fence.md

@@ -0,0 +1,113 @@
+---
+purpose: The template-kit/unlayered-fence authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../theme-and-css.md]
+updated: 2026-07-14
+---
+# template-kit/unlayered-fence
+
+> **This is not "you forgot to layer your CSS."** Everything is layered by default — the
+> build does it for you. This rule governs the *escape hatch* from layering: an
+> `/* unlayered: … */` fence must give a reason and must be closed.
+
+## Rule
+
+Your hand-written CSS is wrapped in a cascade layer by the build. You do not write
+`@layer` yourself, and there is nothing to forget.
+
+The **fence** opts a run of rules *out* of that wrapping, hoisting them above every layer:
+
+```css
+/* unlayered: <reason> */
+…rules that must beat every layer…
+/* endunlayered */
+```
+
+Two things are checked, both under this id:
+
+1. **Every opener carries a non-empty reason.** A bare `/* unlayered: */` is a violation.
+2. **Openers and closers balance.** An unterminated fence is a violation — it would swallow
+   the whole rest of the file out of the layer, which is never what anyone meant.
+
+## Reason
+
+Cascade layers have one rule that decides everything here: **an unlayered rule beats a
+layered one, regardless of specificity.** Not "usually" — always. That is what layers are
+for, and it is why the platform layers your CSS: inside the layer order (`theme, base,
+components, sections, template, utilities`) a Tailwind utility can always override a
+section's stylesheet, and a section's stylesheet can never leak past its layer to beat
+someone else's utility.
+
+So the hatch exists for exactly one situation: **a third-party library injects an unlayered
+rule into the document at runtime** — a map SDK writing a `<style>` element when it mounts,
+say — and that rule beats your layered override no matter how specific you make it. The
+only thing that can beat it is a rule that is also unlayered. Nothing else qualifies. If
+your rule merely needs to beat *your own* CSS, or a Tailwind utility, it belongs in a layer
+and you are reaching for the wrong tool.
+
+Which is why the reason is mandatory. A fence with no reason is a rule that outranks every
+layer on the page for reasons the next author cannot reconstruct — they cannot tell whether
+it is load-bearing or whether someone was fighting a specificity problem with a hammer. And
+an unbalanced fence silently promotes every rule below it, so a stylesheet that behaved
+yesterday starts beating the utilities that were supposed to override it.
+
+## Fix
+
+Close every fence with `/* endunlayered */`, and give every opener a reason that **names the
+runtime-injected rule it has to beat**. A short phrase is enough — it only has to be
+non-empty and specific about which rule it's beating, not a full sentence. If it does not
+have to beat one, delete the fence: layered is the default, and the default is right.
+
+The Before/After below both open with a `/* css-reason: … */` comment. That line has
+nothing to do with fencing — it satisfies a separate rule, [`css-reason`](css-reason.md),
+which every hand-written stylesheet must open with. It's shown here because real section
+CSS carries both; this rule's own grammar starts at `/* unlayered: */`.
+
+### Before
+
+```css
+/* css-reason: overrides the map SDK's injected control chrome. */
+
+/* unlayered: */
+.maplibregl-ctrl-group button {
+  background: var(--tr-color-surface);
+  border-radius: var(--tr-radius-sm);
+}
+
+.tr-map-legend {
+  padding: 0.5rem;
+}
+```
+
+Two violations at once: the reason is empty, and the fence is never closed — so
+`.tr-map-legend` is hoisted out of the layer too, where it now outranks every utility a
+future author might try to override it with.
+
+### After
+
+```css
+/* css-reason: overrides the map SDK's control chrome — the SDK builds those nodes after
+   hydration, so Tailwind's scanner never sees a class to compile. */
+
+/* unlayered: the map SDK injects its control styles as an unlayered <style> element at
+   runtime; a layered rule cannot beat it at any specificity. */
+.maplibregl-ctrl-group button {
+  background: var(--tr-color-surface);
+  border-radius: var(--tr-radius-sm);
+}
+/* endunlayered */
+
+/* Our own DOM — layered, like everything else. */
+.tr-map-legend {
+  padding: 0.5rem;
+}
+```
+
+The fence now wraps exactly the rules that need to escape, and `.tr-map-legend` is back in
+the layer where a utility can still override it.
+
+## See also
+
+- [Theme and CSS](../theme-and-css.md) — the layer order, and why utilities come last.
+- [`css-reason`](css-reason.md) — the comment every hand-written stylesheet opens with; the
+  fence reason is the same discipline, one level in.