@homepages/template-kit 0.1.0 → 0.2.0

package/docs/rules/no-client-runtime-in-server.md

@@ -0,0 +1,143 @@
+---
+purpose: The template-kit/no-client-runtime-in-server authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, server-vs-client.md, ../islands.md, serializable-island-props.md]
+updated: 2026-07-14
+---
+# template-kit/no-client-runtime-in-server
+
+> No effects, state, event handlers, network, or browser globals in server-rendered code.
+> Interactivity is not banned — it is **relocated** into an island. Islands are exempt.
+
+## Rule
+
+Whether a file is server-rendered or an island is decided per file, by the `"use client"`
+directive — see [server vs client](server-vs-client.md). On an island this rule installs
+no visitors at all.
+
+In a server-rendered file it reports three things:
+
+- **React hooks that only mean something in the browser** — `useEffect`,
+  `useLayoutEffect`, `useState`, `useReducer`, `useRef`, `useSyncExternalStore`,
+  `useImperativeHandle` — called bare (`useState(…)`) or namespace-qualified
+  (`React.useEffect(…)`).
+- **Browser globals read as a value** — `fetch`, `XMLHttpRequest`, `window`, `document`,
+  `localStorage`, `sessionStorage`, `navigator`. "Read as a value" is exact: the SSR-guard
+  idiom `typeof window !== "undefined"` **is** reported, while `cfg.window` (a property)
+  and `{ window: 1 }` (an object key) are not.
+- **Event-handler props** — any JSX prop matching `on[A-Z]…` whose value is an expression:
+  `onClick={…}`, `onChange={…}`, `onPointerMove={…}`.
+
+Carve-outs:
+
+- **Your own definitions are yours.** A name that resolves to a real local declaration —
+  `function fetch() {}`, your own `useRef` helper — is not the global or React's hook, and
+  is left alone.
+- **`onSurface={1}` and `onIcon={<Icon />}` are not handlers.** A prop whose value is
+  plainly a literal or a JSX element is not reported.
+- **A handler on an island is not reported here.** If the element's component resolves to
+  a real `"use client"` file on disk, this rule stays quiet:
+  [`serializable-island-props`](serializable-island-props.md) already speaks for that
+  prop, and "move it into a client component" would be nonsense advice for something that
+  already is one.
+
+## Reason
+
+A server-rendered file is run once, to a string of HTML, in a process that is not a
+browser. There is no `window` to read and no DOM to mutate; an effect never fires, and
+`useState` has no second render to give you. An event handler is worse than useless: it
+is a function, and a function cannot be serialized into HTML, so **it is silently dropped
+from the published page**. The button ships. The click does nothing. Nothing errors.
+
+So a Renderer must be a **pure function of its props**. Interactivity is not something the
+kit forbids — it is something the kit gives a specific home: a `"use client"` island,
+which is hydrated in the browser and is exempt from every one of these bans.
+
+## Fix
+
+Move the interactive markup into a `"use client"` component in the section folder, and
+render it from the Renderer with plain data props. The Renderer keeps the static markup
+and passes the island what it needs to do its job; the island owns the state and the
+handlers.
+
+### Before
+
+```tsx
+// sections/floorplan/Renderer.tsx
+import { useState } from "react";
+
+import { Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  const [beds, setBeds] = useState<number | null>(null);
+  const shown = beds === null ? slots.units : slots.units.filter((u) => u.beds === beds);
+  return (
+    <Section>
+      <button onClick={() => setBeds(2)}>2 beds</button>
+      <ul>
+        {shown.map((u) => (
+          <li key={u.id}>{u.label}</li>
+        ))}
+      </ul>
+    </Section>
+  );
+}
+```
+
+### After
+
+The state and the handler move into an island. Its props are plain data — see
+[`serializable-island-props`](serializable-island-props.md).
+
+```tsx
+// sections/floorplan/UnitFilter.tsx
+"use client";
+
+import { useState } from "react";
+
+type Unit = { id: string; label: string; beds: number };
+
+export default function UnitFilter({ units }: { units: Unit[] }) {
+  const [beds, setBeds] = useState<number | null>(null);
+  const shown = beds === null ? units : units.filter((u) => u.beds === beds);
+  return (
+    <div>
+      <button onClick={() => setBeds(2)}>2 beds</button>
+      <ul>
+        {shown.map((u) => (
+          <li key={u.id}>{u.label}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+```tsx
+// sections/floorplan/Renderer.tsx
+import { Section } from "@homepages/template-kit";
+
+import UnitFilter from "./UnitFilter.js";
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <UnitFilter units={slots.units} />
+    </Section>
+  );
+}
+```
+
+The import carries the **emitted** extension (`./UnitFilter.js`) while the file on disk is
+`UnitFilter.tsx` — that is TypeScript's ESM convention, and it is what the kit's rules
+resolve against.
+
+## See also
+
+- [Server vs client](server-vs-client.md) — how a file is scoped, and what an island may do.
+- [Islands](../islands.md) — writing one, its props contract, and its editor options.
+- [`serializable-island-props`](serializable-island-props.md) — the rule that instead
+  reports a function-valued prop when the target *is* an island.

package/docs/rules/no-css-import-from-render-path.md

@@ -0,0 +1,118 @@
+---
+purpose: The template-kit/no-css-import-from-render-path 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/no-css-import-from-render-path
+
+> No **local** `.css` import in a section's render path. A **package's** `.css` import
+> belongs there — it is how its stylesheet reaches the section's cascade layer.
+
+## Rule
+
+An `import` whose specifier ends in **`.css`**, in any of the section's `.ts`/`.tsx`
+files, is reported **only when the specifier is local** — relative
+(`import "./gallery.css";`) or absolute (`import "/gallery.css";`) — including the
+side-effect-only form with no bindings.
+
+A **bare** specifier (`import "swiper/css";`, `import "@scope/pkg/dist/style.css";`) is
+not reported. That is the sanctioned channel for a third-party package's stylesheet.
+
+What it does **not** match:
+
+- `.scss` and `.less` — a different pipeline, out of this rule's scope;
+- `require("./x.css")`;
+- a dynamic `import("./x.css")`.
+
+There is no island exemption: a `"use client"` file is part of the render path too — it is
+server-rendered inline before it is hydrated.
+
+## Reason
+
+The section's CSS build works by **bundling the render path itself** — `Renderer.tsx` and
+any enhancer that carries `export const enhancer` — and harvesting the CSS its imports
+pull in. A bare specifier resolves into `node_modules`, which is exactly what that build
+looks for: `import "swiper/css";` in `Renderer.tsx` is not a mistake, it is the mechanism.
+
+A **local** stylesheet is a different problem. Every `.css` file that already lives in the
+section's folder is collected on its own, by filename — the build doesn't need an import
+to find it. Importing it again from the render path doesn't just ship duplicate rules
+harmlessly: it can also smuggle a stray `@layer` order statement into a nested layer and
+corrupt the cascade for the whole page.
+
+## Fix
+
+Delete the import. A local stylesheet already ships — the build picks up every `.css` file
+in the section folder on its own; importing it again only makes it double-emit.
+
+A package's stylesheet is different: import it **by its bare specifier**, from the module
+that needs it. The build bundles `Renderer.tsx` and every marked enhancer's import graph
+**transitively**, so a bare specifier is equally legal in the Renderer itself, in a marked
+enhancer, or in any component either one imports — not only at the top of the tree. That
+import is how the build finds the stylesheet and routes it into the section's cascade
+layer.
+
+### Before
+
+```tsx
+// sections/gallery/Renderer.tsx
+import { Section } from "@homepages/template-kit";
+
+import "./styles.css"; // template-kit/no-css-import-from-render-path — already collected by filename
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <div className="tr-gallery-track">{slots.headline}</div>
+    </Section>
+  );
+}
+```
+
+### After
+
+The local import is simply deleted — `styles.css` was already shipping:
+
+```tsx
+// sections/gallery/Renderer.tsx
+import { Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <div className="tr-gallery-track">{slots.headline}</div>
+    </Section>
+  );
+}
+```
+
+Compare a **package's** stylesheet, which is the legal counterpart — imported by its bare
+specifier, from the same file, and left in place:
+
+```tsx
+// sections/gallery/Renderer.tsx
+import { Section } from "@homepages/template-kit";
+import "swiper/css"; // legal — a bare specifier is how package CSS reaches this section's layer
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <div className="tr-gallery-track">{slots.headline}</div>
+    </Section>
+  );
+}
+```
+
+## See also
+
+- [`no-bare-css-import`](no-bare-css-import.md) — the other half of this mental model.
+  Render path: no *local* CSS imports. Hand-written CSS: no `@import`s at all, package or
+  otherwise. An author who reads only one of the two pages will be confused by the other.
+- [Theme and CSS](../theme-and-css.md) — the two CSS entries and how they load.

package/docs/rules/no-hex.md

@@ -0,0 +1,97 @@
+---
+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
+---
+# template-kit/no-hex
+
+> No hard-coded colours in section code. **Islands are not exempt** — this is the one
+> rule that holds on both sides of the hydration boundary.
+
+## Rule
+
+Two shapes are banned:
+
+- **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(...)`.
+- **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]`,
+    and the rest of `border-color`, `outline-color`, `box-shadow`, `text-shadow`,
+    `fill`, `stroke`, `caret-color`, `accent-color`, `text-decoration-color`;
+  - **any** custom property — `[--brand:#ff0000]`;
+  - a colour-utility prefix, with variants stripped — `bg-[#f00]`, `hover:bg-[#f00]`,
+    `md:dark:text-[#f00]`, `border-t-[#000]`, and the same for `ring`, `outline`,
+    `shadow`, `fill`, `stroke`, `decoration`, `divide`, `accent`, `caret`,
+    `placeholder`, `from`, `via`, `to`;
+  - or anywhere inside a JSX `style` attribute.
+
+Everywhere else, a `#`-prefixed string is left alone: `href="#cafe"` is an anchor, and
+`w-[#…]` is not a colour utility. `#cafe`, `#facade`, `#decade`, and `#beef` are real
+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.
+
+## Reason
+
+A section carries **zero palette of its own**. It is theme-agnostic, and must look
+right under every template's theme — so a baked colour breaks the first time another
+template reuses the section. Keeping colour in tokens is what makes a section portable
+rather than a one-off.
+
+This is why islands get no exemption. An island is exempt from the effect, state,
+handler, and inline-`style` bans because those are server-render concerns and an island
+runs in the browser. A palette is not a render-path concern: the hydration boundary is
+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.
+
+### Before
+
+```tsx
+import { Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <div className="bg-[#f5f5f5]">
+        <h2 style={{ color: "#1a1a1a" }}>{slots.headline}</h2>
+      </div>
+    </Section>
+  );
+}
+```
+
+### After
+
+```tsx
+import { Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <div className="bg-surface-alt">
+        <h2 className="text-ink">{slots.headline}</h2>
+      </div>
+    </Section>
+  );
+}
+```
+
+## See also
+
+- [Theme and CSS](../theme-and-css.md#color-roles) — the token system and the colour roles.
+- [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-inline-style.md

@@ -0,0 +1,121 @@
+---
+purpose: The template-kit/no-inline-style 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
+---
+# template-kit/no-inline-style
+
+> No inline `style=` in server-rendered section JSX. Islands are exempt — but an island
+> is **not** exempt from [`no-hex`](no-hex.md).
+
+## Rule
+
+Whether a file is server-rendered or an island is decided per file, by the `"use client"`
+directive — see [server vs client](server-vs-client.md). On an island this rule installs
+no visitors at all.
+
+In a server-rendered file it reports **any JSX attribute named `style`, on any element**.
+The value is never inspected: a static object, a computed one, a spread, a string — all
+the same. There is no "but this one is fine" case in a server-rendered file.
+
+**The island exemption does not extend to colour.** `no-hex` reads inside `style` values
+and has no island exemption at all, so this still fails on a `"use client"` file:
+
+```tsx
+"use client";
+
+export default function Badge() {
+  return <div style={{ color: "#ff0000" }} />; // template-kit/no-hex
+}
+```
+
+Exempt from *this* rule; still a hard-coded colour.
+
+## Reason
+
+Three concrete failures, all of them server-render concerns:
+
+- **It bypasses the cascade.** An inline style is the highest-specificity declaration
+  short of `!important`, so a template's theme can no longer restyle the section. The
+  section stops being portable.
+- **It skips Tailwind's responsive prefixes.** `style={{ padding: 16 }}` has no
+  breakpoint form; there is no way to say "16 on mobile, 48 on desktop" in it. Utilities
+  have exactly that (`p-4 lg:p-12`), which is why the layout ladder lives in classes.
+- **It churns per-call identity** that the editor's hash-based diff cannot dedupe — the
+  editor re-renders the section on every keystroke, and a fresh style object each render
+  is work it cannot skip.
+
+An island computing a transform from live pointer state has none of these problems: it
+runs in the browser, it is not part of the cascade the theme is styling, and that is
+precisely what an island is for. So it is exempt.
+
+## Fix
+
+Use Tailwind utility classes. For a value that only exists at runtime, move the markup
+into a `"use client"` island, where `style` is allowed.
+
+### Before
+
+```tsx
+import { Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <div style={{ padding: 16, display: "flex", gap: 8 }}>
+        <h2>{slots.headline}</h2>
+      </div>
+    </Section>
+  );
+}
+```
+
+### After
+
+```tsx
+import { Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <div className="flex gap-2 p-4">
+        <h2>{slots.headline}</h2>
+      </div>
+    </Section>
+  );
+}
+```
+
+The runtime-value case — a transform driven by live state — has no utility form, and is
+the case the island exemption exists for:
+
+```tsx
+// sections/hero/Parallax.tsx
+"use client";
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+
+export default function Parallax({ children }: { children: ReactNode }) {
+  const [offset, setOffset] = useState(0);
+  return (
+    <div
+      onPointerMove={(e) => setOffset(e.clientX / 40)}
+      style={{ transform: `translateX(${offset}px)` }}
+    >
+      {children}
+    </div>
+  );
+}
+```
+
+## See also
+
+- [Server vs client](server-vs-client.md) — the island exemption, and the one rule that
+  does not take it.
+- [Theme and CSS](../theme-and-css.md) — the token utilities and the breakpoint ladder.

package/docs/rules/no-nondeterminism.md

@@ -0,0 +1,100 @@
+---
+purpose: The template-kit/no-nondeterminism authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, server-vs-client.md]
+updated: 2026-07-14
+---
+# template-kit/no-nondeterminism
+
+> No clock reads and no randomness in server-rendered code. Islands are exempt.
+
+## Rule
+
+Whether a file is server-rendered or an island is decided per file, by the `"use client"`
+directive — see [server vs client](server-vs-client.md). On an island this rule installs
+no visitors at all.
+
+In a server-rendered file, two shapes are banned:
+
+- **A read of a nondeterministic source**: `Date.now`, `Math.random`,
+  `crypto.randomUUID`, `crypto.getRandomValues`, `performance.now`. The member expression
+  alone is enough — `Date.now` reports even without a call, because handing the function
+  itself somewhere is the same read one hop later.
+- **`new Date()` with no arguments.** That reads the clock.
+
+Two carve-outs:
+
+- **`new Date(props.listed_at)` is fine.** It parses a value the section was *given*,
+  which is perfectly deterministic. Only the zero-argument form reads the clock.
+- **Your own definitions are yours.** If the object name resolves to a real local
+  declaration — `const performance = { now: () => 1 };` — it is not the global, and the
+  rule leaves it alone.
+
+## Reason
+
+The publisher and the editor both run a section's `Renderer`, and they must produce
+**byte-identical HTML** from the same props. A clock read or a random value makes the two
+renders disagree: the section's output is hashed, so a `Date.now()` in the markup means
+the section looks changed on every single render — a fresh version each publish, and an
+editor canvas that never settles.
+
+An island does not have this problem. It runs in the browser, after hydration, and its
+output is nobody's content hash. That is why it is exempt.
+
+## Fix
+
+Compute the value **at fill time** and pass it in as a slot value — that is the right
+route for anything that is content. Reach for an island only when the value is genuinely
+live (a countdown, a "time since listed" that must tick).
+
+### Before
+
+```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>
+      <p>© {new Date().getFullYear()} — all rights reserved</p>
+    </Section>
+  );
+}
+```
+
+### After
+
+The year is content, so it becomes a slot the fill pipeline supplies. Declare it in
+`schema.ts`, and the Renderer just renders what it was given:
+
+```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="copyright_year" textLeaf>
+        <p>© {slots.copyright_year} — all rights reserved</p>
+      </Slot>
+    </Section>
+  );
+}
+```
+
+If the value must be live in the browser rather than baked at fill time, move that
+markup into a `"use client"` component in the section folder instead, and render it from
+the Renderer — the rule does not run there.
+
+## See also
+
+- [Server vs client](server-vs-client.md) — how a file is scoped, and what an island may do.
+- [Schema system](../schema-system.md) — declaring the slot the value arrives in.

package/docs/rules/no-raw-element.md

@@ -0,0 +1,100 @@
+---
+purpose: The template-kit/no-raw-element authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../primitives.md]
+updated: 2026-07-14
+---
+# template-kit/no-raw-element
+
+> **Exactly two** raw elements are banned: `<section>` and `<img>`. Every other tag is
+> yours.
+
+## Rule
+
+Two tags, and no others:
+
+| Raw tag | Use instead |
+|---|---|
+| `<section>` | `<Section>` |
+| `<img>` | `<Image>` |
+
+That is the entire rule. **`<a>`, `<h1>`–`<h6>`, `<div>`, `<ul>`, `<button>`, `<picture>`,
+`<figure>` — every other element is yours to write.** Presentation is the template's own
+JSX; the kit is not trying to own your markup. If you have concluded "the kit bans raw
+HTML", that is exactly backwards.
+
+There is no island exemption: the two tags are banned in a `"use client"` file too.
+
+## Reason
+
+Each of the two banned tags has a **contract-bearing primitive that must emit it**, and
+writing the raw tag skips the contract.
+
+- **`<Section>`** emits `<section class="tr-section">`, which is full-bleed by contract:
+  100% width, zero padding, zero margin, so consecutive sections butt edge-to-edge and a
+  page composes as a clean vertical stack. A raw `<section>` lacks that class, so the
+  page grows gaps the template never asked for.
+- **`<Image>`** owns the responsive `<picture>` (per-format AVIF/WebP `srcset`, the
+  mobile crop, `sizes`), the aspect-ratio box, and the neutral fallback rect that keeps
+  the layout box when `src` is empty. A raw `<img>` with a null `src` is a collapsed box
+  or a broken-image icon on a real customer's page — and a missing image is a **supported
+  state**, not a bug: it happens whenever a listing is thin. `<Image slotId>` also emits
+  the slot marker itself, so the image stays selectable in the editor.
+
+The two tags are banned because they are the two the platform has to be able to trust.
+Everything else carries no contract, so nothing is gained by policing it.
+
+## Fix
+
+Import the primitive from the package root and use it:
+
+```tsx
+import { Section, Image } from "@homepages/template-kit";
+```
+
+### Before
+
+```tsx
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <section>
+      <h2>{slots.headline}</h2>
+      <img src={slots.hero_image.url ?? ""} alt={slots.hero_image.alt} />
+    </section>
+  );
+}
+```
+
+### After
+
+```tsx
+import { Image, Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <h2>{slots.headline}</h2>
+      <Image
+        slotId="hero_image"
+        src={slots.hero_image.url}
+        alt={slots.hero_image.alt}
+        responsive={slots.hero_image.responsive}
+        aspectRatio="5 / 3"
+      />
+    </Section>
+  );
+}
+```
+
+The `<h2>` stays exactly as it was. `Image` takes `src`/`alt` directly — a `null` or empty
+`src` is a supported state it renders a fallback rect for, so no `?? ""` guard is needed.
+
+## See also
+
+- [Contract primitives](../primitives.md) — all five primitives and the markers they emit.
+- [`image-bare-needs-reason`](image-bare-needs-reason.md) — the escape hatch that drops
+  `<Image>`'s frame, and what it costs.