@homepages/template-kit 0.1.0 → 0.3.0

package/docs/rules/no-client-directive-in-contract.md

@@ -0,0 +1,111 @@
+---
+purpose: The template-kit/no-client-directive-in-contract authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, server-vs-client.md, ../schema-system.md]
+updated: 2026-07-14
+---
+# template-kit/no-client-directive-in-contract
+
+> A section's four contract files may never carry `"use client"`. This is the one rule
+> scoped by **filename**, not by the directive.
+
+## Rule
+
+The rule runs only on a section's four contract files — `Renderer.tsx`, `schema.ts`,
+`fill-spec.ts`, `fixtures.ts` — matched by glob. On one of those files, a `"use client"`
+string in the **directive prologue** is reported.
+
+The prologue is the run of leading string-literal statements (see
+[server vs client](server-vs-client.md)). Three consequences worth knowing:
+
+- **`"use strict"; "use client";` reports.** A second directive is still in the prologue.
+- **`const x = 1;` above `"use client"` does not report** — real code ended the prologue,
+  so that string is not a directive. This is a trap, not a loophole: the file is also
+  **not an island**, and every server-rendering rule still applies to it. It is a dead
+  string.
+- **`foo("use client")` is not a directive** — it is a call argument, and is ignored.
+
+Any other file in the section folder may carry the directive freely. That is exactly
+where interactivity belongs.
+
+## Reason
+
+The four contract files are the platform's interface to a section. They are read by the
+publisher, the editor, and the fill pipeline — **none of which is a browser**.
+`schema.ts` is loaded to learn what slots exist; `fill-spec.ts` to learn how AI fills
+them; `fixtures.ts` to render a preview; `Renderer.tsx` to produce the section's HTML.
+
+Marking one `"use client"` would make the whole section an island — and take the
+section's server-rendered HTML with it. The section would ship as an empty shell that
+only appears once JavaScript has run, which is precisely what a published property page
+must never do.
+
+## Fix
+
+Put the interactive part in its **own** `"use client"` component in the section folder,
+and render it from the Renderer. The contract file stays server-only; the island next to
+it does the browser work.
+
+### Before
+
+```tsx
+// sections/gallery/Renderer.tsx
+"use client";
+
+import { useState } from "react";
+
+import { Section } from "@homepages/template-kit";
+
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  const [open, setOpen] = useState(false);
+  return (
+    <Section>
+      <button onClick={() => setOpen(true)}>Open gallery</button>
+      {open && <p>{slots.headline}</p>}
+    </Section>
+  );
+}
+```
+
+### After
+
+```tsx
+// sections/gallery/Lightbox.tsx
+"use client";
+
+import { useState } from "react";
+
+export default function Lightbox({ headline }: { headline: string }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <div>
+      <button onClick={() => setOpen(true)}>Open gallery</button>
+      {open && <p>{headline}</p>}
+    </div>
+  );
+}
+```
+
+```tsx
+// sections/gallery/Renderer.tsx — no directive; server-rendered again
+import { Section } from "@homepages/template-kit";
+
+import Lightbox from "./Lightbox.js";
+import type { Props } from "./schema.js";
+
+export function Renderer({ slots }: Props) {
+  return (
+    <Section>
+      <Lightbox headline={slots.headline} />
+    </Section>
+  );
+}
+```
+
+## See also
+
+- [Server vs client](server-vs-client.md) — the directive, the prologue, and what an
+  island may do.
+- [Schema system](../schema-system.md) — what each of the four contract files is for.

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,163 @@
+---
+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-15
+---
+# 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
+
+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.
+
+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]`,
+    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.
+
+### 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
+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 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
+
+```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>
+  );
+}
+```
+
+### 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#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-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.