@homepages/template-kit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @homepages/template-kit
 
+## 0.2.0
+
+### Minor Changes
+
+- e64d4d7: `base.css` no longer ships a reset — Tailwind's preflight (from your entry's
+  `@import "tailwindcss"`) already is one, and the two were duplicating each other. It
+  now carries only the three declarations preflight does not make: font-smoothing,
+  `button { cursor: pointer }`, and `svg { max-width: 100% }`.
+
+  **`base.css` now requires a Tailwind entry on the page.** If a page loads `base.css`
+  without an `@import "tailwindcss"` entry present — a standalone preview, an embed, a
+  hand-written CSS page — it renders fully unreset (UA body margin, bulleted lists,
+  underlined links, unconstrained inline images), and nothing errors to tell you.
+  Confirm every page that loads `base.css` also loads a Tailwind entry.
+
+  `base.css` also no longer references any theme token. The `body` document defaults
+  (font, color, background, size) are now emitted by `compileThemeToCss`, alongside the
+  `:root` block that defines those tokens. **Regenerate and republish your compiled theme
+  CSS.** If you upgrade `base.css` but keep serving a previously-compiled theme
+  stylesheet, that stylesheet still only has the old `:root` block — `body` silently
+  loses `font-family`, `color`, `background`, and `font-size` page-wide, because
+  `base.css` no longer carries them as a fallback. The compiled output's content hash
+  changes.
+
+  The `--tr-space-*` scale is removed — Tailwind's own spacing scale (`p-4`, `gap-6`)
+  was never aliased to it. Any of your CSS still referencing `var(--tr-space-*)` (e.g.
+  `padding: var(--tr-space-4)`) now points at an undefined custom property, which is
+  invalid at computed-value time, so the declaration drops. The `scroll-behavior` /
+  `scroll-padding-top` policy is removed; set it in your own template stylesheet if you
+  have a sticky header.
+
+- a24174f: Every rule-id now resolves to a page. The lint preset and `template-kit check` share one
+  id namespace (`template-kit/<id>`), and each of those ids — all 28 — now has a page at
+  `docs/rules/<id>.md` giving the rule, the reason it exists, and a before/after fix you can
+  copy.
+
+  The docs ship **inside the tarball**, so the loop closes with no network: hit
+  `template-kit/no-hex`, read `node_modules/@homepages/template-kit/docs/rules/no-hex.md`,
+  fix it. That matters most for the coding agents authoring against this kit — an agent that
+  can resolve a failure to its own reference page fixes the violation instead of guessing at
+  it.
+
+  Each ESLint rule also carries `meta.docs.url` pointing at its page, so an editor's "show
+  documentation for this rule" lands on the same file.
+
+  Start at `docs/rules/INDEX.md`. `docs/rules/server-vs-client.md` explains the one concept
+  several rules assume — that server-vs-client is a **per-file** fact, decided by the
+  `"use client"` directive prologue, not by an import graph.
+
+### Patch Changes
+
+- be1507d: Fixed `no-css-import-from-render-path`, which banned the one legal way to get a
+  third-party stylesheet into a section.
+
+  A **bare** `.css` specifier in the render path — `import "swiper/css"` in `Renderer.tsx`,
+  in a marked enhancer, or in any module either one imports — is how a package's CSS reaches
+  the section's cascade layer: the build bundles that import graph precisely to harvest it.
+  The rule flagged it anyway, and its `Fix:` hint sent you to `@import` the stylesheet from
+  `styles.css`, which is never legal there (hand-written CSS is wrapped in `@layer`, where a
+  browser drops an `@import` silently).
+
+  The rule now reports only a **local** stylesheet import — a relative or absolute specifier.
+  That is the real defect: the build already collects every `.css` file in the section folder
+  by filename, so importing one from code ships its rules twice and can corrupt the cascade.
+
+  If you worked around the old rule by moving a package's CSS into a stylesheet `@import`,
+  move it back into the module that needs it — see `docs/rules/no-css-import-from-render-path.md`
+  and `docs/rules/no-bare-css-import.md`, which are the two halves of the same mental model.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -65,7 +65,7 @@ Full contract: **[docs/primitives.md](docs/primitives.md)**.
 | `@homepages/template-kit/island-runtime` | Browser loader that hydrates a page's islands |
 | `@homepages/template-kit/browser` | Browser helpers for published pages (site config, signed ingest) |
 | `@homepages/template-kit/styles.css` | Tailwind v4 theme tokens, the breakpoint ladder, kit source registration |
-| `@homepages/template-kit/base.css` | The page's base stylesheet: layer order, reset, `.tr-section`, universal tokens |
+| `@homepages/template-kit/base.css` | Cascade-layer order, the three reset gaps Tailwind's preflight leaves, `.tr-section`, and the motion tokens |
 | `@homepages/template-kit/eslint` | ESLint flat-config preset |
 | `@homepages/template-kit/tsconfig` | tsconfig preset (`"extends"`) |
 
@@ -80,9 +80,19 @@ write a section against. The two CSS entries are the deliberate exception.
 ```
 
 Two `@import "tailwindcss"` in one graph double-emits preflight. `base.css` is not part
-of that entry — it loads as its own stylesheet on the page. Full contract:
+of that entry — it loads as its own stylesheet on the page. `base.css` ships no reset
+of its own — it depends on the preflight your entry's `@import "tailwindcss"` brings.
+Both must be on the page. Full contract:
 **[docs/theme-and-css.md](docs/theme-and-css.md)**.
 
+## Rules
+
+The lint preset and the `template-kit check` CLI share one id namespace,
+`template-kit/<id>`. A rule-id printed by either resolves to a page —
+`docs/rules/<id>.md` — giving the rule, the reason it exists, and a before/after fix.
+Start at **[docs/rules/INDEX.md](docs/rules/INDEX.md)**; the full doc set is routed
+from **[docs/INDEX.md](docs/INDEX.md)**.
+
 ## Development
 
 ```bash

package/dist/base.css

@@ -7,52 +7,46 @@
  *
  * Contains:
  *   - The cascade-layer order declaration above — the one place it is stated
- *   - The @layer base reset
- *   - Document defaults (html/body)
+ *   - The three reset gaps Tailwind's preflight leaves (below)
  *   - The section box model (.tr-section, emitted by the <Section> primitive)
- *   - Universal tokens: the spacing scale and motion
+ *   - Universal tokens: motion
  *
- * NOT here: anything a template owns. Colors, fonts, type, radii, shadows and
- * layout all come from your theme.ts, compiled by compileThemeToCss into a
- * `:root { --tr-*: … }` block. Component styling is Tailwind utilities written
- * on the elements themselves.
+ * REQUIRES A TAILWIND ENTRY ON THE PAGE. Your entry's `@import "tailwindcss"` brings
+ * Tailwind's preflight, and preflight does the reset: box-sizing, margin/padding,
+ * list-style, the button and anchor resets, display:block on replaced elements. This
+ * file only fills the three gaps preflight leaves. Ship base.css without a Tailwind
+ * entry and you get an unreset page.
+ *
+ * NOT here: anything a template owns. Colors, fonts, type, radii, shadows and layout
+ * — and the `body` document defaults that apply them — all come from your theme.ts,
+ * compiled by compileThemeToCss. This file references no theme token at all.
  */
 
-/* ----- Reset (lightweight; assumes modern browsers) --------------------- *
+/* ----- Reset gaps ------------------------------------------------------- *
+ * The three declarations Tailwind's preflight does NOT make. Each is load-bearing:
+ * delete one and your page changes.
+ *
  * Wrapped in `@layer base` so Tailwind's utilities (which compile into
- * `@layer utilities`) win over these element defaults. Unlayered, a rule like
- * `a { color: inherit }` would beat the layered `.text-ink` utility outright —
- * unlayered always wins over layered in the cascade.
+ * `@layer utilities`) win over these element defaults. Unlayered, `button { cursor:
+ * pointer }` would beat a layered `.cursor-default` utility outright — unlayered
+ * always wins over layered in the cascade.
  */
 
 @layer base {
-  *, *::before, *::after { box-sizing: border-box; }
-  html, body { margin: 0; padding: 0; }
+  /* preflight carries no font-smoothing rule at all */
   body { -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; }
-  img, svg, video { display: block; max-width: 100%; }
-  button { background: none; border: 0; padding: 0; cursor: pointer; font: inherit; color: inherit; }
-  a { color: inherit; text-decoration: none; }
-  ul, ol { margin: 0; padding: 0; list-style: none; }
-  h1, h2, h3, h4, h5, h6, p { margin: 0; }
-}
-
-/* ----- Document defaults ------------------------------------------------ */
-
-html { scroll-behavior: smooth; scroll-padding-top: var(--tr-header-height); }
-body {
-  font-family: var(--tr-font-sans);
-  color: var(--tr-color-ink);
-  background: var(--tr-color-background);
-  font-size: var(--tr-text-base);
-  line-height: 1.5;
+  /* Tailwind v4 deliberately leaves buttons at the UA default `cursor: default` */
+  button { cursor: pointer; }
+  /* preflight caps max-width on img and video, but not on svg */
+  svg { max-width: 100%; }
 }
 
 /* ----- Primitives ------------------------------------------------------- */
 
-/* The full-bleed section root, emitted by the <Section> primitive. Always 100%
- * wide with zero padding/margin, so adjacent sections butt edge-to-edge and a page
- * composes as a vertical stack with no framework-injected whitespace. A section
- * brings its own background and internal padding. */
+/* The full-bleed section root, emitted by the <Section> primitive. Always 100% wide
+ * with zero padding/margin, so adjacent sections butt edge-to-edge and a page composes
+ * as a vertical stack with no framework-injected whitespace. A section brings its own
+ * background and internal padding. */
 .tr-section {
   display: block;
   width: 100%;
@@ -63,21 +57,6 @@ body {
 /* ----- Universal tokens ------------------------------------------------- */
 
 :root {
-  /* Spacing scale */
-  --tr-space-1: 0.25rem;
-  --tr-space-2: 0.5rem;
-  --tr-space-3: 0.75rem;
-  --tr-space-4: 1rem;
-  --tr-space-5: 1.25rem;
-  --tr-space-6: 1.5rem;
-  --tr-space-8: 2rem;
-  --tr-space-10: 2.5rem;
-  --tr-space-12: 3rem;
-  --tr-space-16: 4rem;
-  --tr-space-20: 5rem;
-  --tr-space-24: 6rem;
-  --tr-space-32: 8rem;
-
   /* Motion */
   --tr-duration-fast: 150ms;
   --tr-duration-base: 250ms;

package/dist/design-system/theme.d.ts

@@ -298,7 +298,8 @@ declare const TokenThemeSchema: z.ZodObject<{
 type TokenTheme = z.infer<typeof TokenThemeSchema>;
 /**
  * Compile a `TokenTheme` into the CSS a template's bundle ships: an optional
- * font-loading block followed by a single `:root { --tr-*: … }` declaration.
+ * font-loading block, a `:root { --tr-*: … }` declaration that defines the
+ * design tokens, and a `body` block that applies those tokens to the document.
  * Deterministic (stable key order; palette keys sorted) so the same theme
  * always content-hashes identically.
  */

package/dist/design-system/theme.js

@@ -72,9 +72,16 @@ fontFaces: z.string().optional() }),
 	shadows: scale(Object.keys(SHADOW_VARS)),
 	layout: scale(Object.keys(LAYOUT_VARS))
 }).strict();
+const BODY_DEFAULTS = `body {
+  font-family: var(--tr-font-sans);
+  color: var(--tr-color-ink);
+  background: var(--tr-color-background);
+  font-size: var(--tr-text-base);
+}`;
 /**
 * Compile a `TokenTheme` into the CSS a template's bundle ships: an optional
-* font-loading block followed by a single `:root { --tr-*: … }` declaration.
+* font-loading block, a `:root { --tr-*: … }` declaration that defines the
+* design tokens, and a `body` block that applies those tokens to the document.
 * Deterministic (stable key order; palette keys sorted) so the same theme
 * always content-hashes identically.
 */
@@ -87,8 +94,8 @@ function compileThemeToCss(theme) {
 	for (const k of Object.keys(RADIUS_VARS)) decls.push(`  ${RADIUS_VARS[k]}: ${theme.radii[k]};`);
 	for (const k of Object.keys(SHADOW_VARS)) decls.push(`  ${SHADOW_VARS[k]}: ${theme.shadows[k]};`);
 	for (const k of Object.keys(LAYOUT_VARS)) decls.push(`  ${LAYOUT_VARS[k]}: ${theme.layout[k]};`);
-	const root = `:root {\n${decls.join("\n")}\n}`;
-	return theme.fonts.fontFaces ? `${theme.fonts.fontFaces}\n\n${root}\n` : `${root}\n`;
+	const blocks = `${`:root {\n${decls.join("\n")}\n}`}\n\n${BODY_DEFAULTS}`;
+	return theme.fonts.fontFaces ? `${theme.fonts.fontFaces}\n\n${blocks}\n` : `${blocks}\n`;
 }
 
 //#endregion

package/dist/eslint/rules/image-bare-needs-reason.js

@@ -1,8 +1,13 @@
+import { docsPathForRule } from "../../rules/registry.js";
+
 //#region src/eslint/rules/image-bare-needs-reason.ts
 const imageBareNeedsReason = {
 	meta: {
 		type: "problem",
-		docs: { description: "<Image bare> requires a `// bare:` reason comment" },
+		docs: {
+			description: "<Image bare> requires a `// bare:` reason comment",
+			url: docsPathForRule("image-bare-needs-reason")
+		},
 		schema: [],
 		messages: { bareNeedsReason: "`<Image bare>` skips the framed wrapper's aspect-ratio box and fallback rect. Fix: document why this case warrants it with a `// bare: <reason>` comment immediately above the element." }
 	},

package/dist/eslint/rules/no-client-directive-in-contract.js

@@ -1,8 +1,13 @@
+import { docsPathForRule } from "../../rules/registry.js";
+
 //#region src/eslint/rules/no-client-directive-in-contract.ts
 const noClientDirectiveInContract = {
 	meta: {
 		type: "problem",
-		docs: { description: "Ban the \"use client\" directive in a section's four contract files" },
+		docs: {
+			description: "Ban the \"use client\" directive in a section's four contract files",
+			url: docsPathForRule("no-client-directive-in-contract")
+		},
 		schema: [],
 		messages: { clientContractFile: "A section's contract files (Renderer.tsx, schema.ts, fill-spec.ts, fixtures.ts) are server-only and must not carry \"use client\" — the platform reads them outside a browser. Fix: put the interactive part in its own \"use client\" component in the section folder and render it from the Renderer." }
 	},

package/dist/eslint/rules/no-client-runtime-in-server.js

@@ -1,3 +1,4 @@
+import { docsPathForRule } from "../../rules/registry.js";
 import { hasClientDirective, isClientFile, resolveImportedFile } from "../is-client-file.js";
 
 //#region src/eslint/rules/no-client-runtime-in-server.ts
@@ -22,7 +23,10 @@ const BANNED_GLOBALS = /* @__PURE__ */ new Set([
 const noClientRuntimeInServer = {
 	meta: {
 		type: "problem",
-		docs: { description: "Ban effects, state, handlers, network, and browser globals in server-rendered section code" },
+		docs: {
+			description: "Ban effects, state, handlers, network, and browser globals in server-rendered section code",
+			url: docsPathForRule("no-client-runtime-in-server")
+		},
 		schema: [],
 		messages: {
 			clientRuntime: "`{{what}}` is browser-only and is banned in server-rendered code — a Renderer must be a pure function of its props. Fix: move this into a `\"use client\"` component in the section folder and render it from the Renderer; it will be hydrated as an island.",

package/dist/eslint/rules/no-css-import-from-render-path.js

@@ -1,15 +1,21 @@
+import { docsPathForRule } from "../../rules/registry.js";
+
 //#region src/eslint/rules/no-css-import-from-render-path.ts
 const noCssImportFromRenderPath = {
 	meta: {
 		type: "problem",
-		docs: { description: "Ban CSS imports from a section's render path" },
+		docs: {
+			description: "Ban local CSS imports from a section's render path",
+			url: docsPathForRule("no-css-import-from-render-path")
+		},
 		schema: [],
-		messages: { cssFromRenderPath: "`{{source}}` is a CSS import in the render path — the renderer is compiled for SSR, where this is dropped, so the styles would silently not ship. Fix: `@import` it from the section's root `styles.css`, which is the entry the CSS build actually reads." }
+		messages: { cssFromRenderPath: "`{{source}}` is a local stylesheet imported from the render path — the build already collects every `.css` file in the section folder by filename, so this ships the rules twice. Fix: delete the import; the file is picked up on its own. (A package's stylesheet belongs here, imported by its bare specifier — that is how it reaches the section's layer.)" }
 	},
 	create(context) {
 		return { ImportDeclaration(node) {
 			const source = node.source.value;
 			if (typeof source !== "string" || !source.endsWith(".css")) return;
+			if (!source.startsWith(".") && !source.startsWith("/")) return;
 			context.report({
 				node,
 				messageId: "cssFromRenderPath",

package/dist/eslint/rules/no-hex.js

@@ -1,3 +1,5 @@
+import { docsPathForRule } from "../../rules/registry.js";
+
 //#region src/eslint/rules/no-hex.ts
 const COLOR_FN = /(?:oklch|oklab|rgba?|hsla?|color-mix)\s*\([^)]*\)/;
 const HEX = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{4}|[0-9a-fA-F]{3})\b/g;
@@ -67,7 +69,10 @@ function isWithinStyleAttribute(node) {
 const noHex = {
 	meta: {
 		type: "problem",
-		docs: { description: "Ban hard-coded colour literals in section code" },
+		docs: {
+			description: "Ban hard-coded colour literals in section code",
+			url: docsPathForRule("no-hex")
+		},
 		schema: [],
 		messages: { hardCodedColor: "`{{value}}` is a hard-coded colour — a section carries no palette of its own, or it breaks the first time another template reuses it. Fix: use a semantic token utility (e.g. `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." }
 	},

package/dist/eslint/rules/no-inline-style.js

@@ -1,10 +1,14 @@
+import { docsPathForRule } from "../../rules/registry.js";
 import { hasClientDirective } from "../is-client-file.js";
 
 //#region src/eslint/rules/no-inline-style.ts
 const noInlineStyle = {
 	meta: {
 		type: "problem",
-		docs: { description: "Ban the inline style prop in server-rendered section JSX" },
+		docs: {
+			description: "Ban the inline style prop in server-rendered section JSX",
+			url: docsPathForRule("no-inline-style")
+		},
 		schema: [],
 		messages: { inlineStyle: "The inline `style=` prop is banned in server-rendered section JSX — it bypasses the cascade and Tailwind's responsive prefixes. 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." }
 	},

package/dist/eslint/rules/no-nondeterminism.js

@@ -1,3 +1,4 @@
+import { docsPathForRule } from "../../rules/registry.js";
 import { hasClientDirective } from "../is-client-file.js";
 
 //#region src/eslint/rules/no-nondeterminism.ts
@@ -10,7 +11,10 @@ const BANNED_MEMBERS = {
 const noNondeterminism = {
 	meta: {
 		type: "problem",
-		docs: { description: "Ban clock and randomness reads in server-rendered section code" },
+		docs: {
+			description: "Ban clock and randomness reads in server-rendered section code",
+			url: docsPathForRule("no-nondeterminism")
+		},
 		schema: [],
 		messages: { nondeterministic: "`{{what}}` is nondeterministic and is banned in server-rendered code — the publisher and the editor must render byte-identical HTML. Fix: compute this at fill time and pass it in as a slot value, or move the code into a `\"use client\"` island, where it runs in the browser." }
 	},

package/dist/eslint/rules/no-raw-element.js

@@ -1,3 +1,5 @@
+import { docsPathForRule } from "../../rules/registry.js";
+
 //#region src/eslint/rules/no-raw-element.ts
 const FORBIDDEN = {
 	section: "<Section>",
@@ -6,7 +8,10 @@ const FORBIDDEN = {
 const noRawElement = {
 	meta: {
 		type: "problem",
-		docs: { description: "Ban raw <section> and <img> in section JSX" },
+		docs: {
+			description: "Ban raw <section> and <img> in section JSX",
+			url: docsPathForRule("no-raw-element")
+		},
 		schema: [],
 		messages: { rawElement: "Raw `<{{tag}}>` is banned in section JSX — {{use}} carries the contract it skips. Fix: `import { {{name}} } from \"@homepages/template-kit\";` and use {{use}}." }
 	},

package/dist/eslint/rules/props-from-schema.js

@@ -1,8 +1,13 @@
+import { docsPathForRule } from "../../rules/registry.js";
+
 //#region src/eslint/rules/props-from-schema.ts
 const propsFromSchema = {
 	meta: {
 		type: "problem",
-		docs: { description: "A Renderer must import its Props type from ./schema" },
+		docs: {
+			description: "A Renderer must import its Props type from ./schema",
+			url: docsPathForRule("props-from-schema")
+		},
 		schema: [],
 		messages: { handWritten: "`{{name}}` is a hand-written props type in a Renderer — it bypasses the schema→Props inference and will drift. Fix: add `export type Props = SectionProps<typeof schema>;` to schema.ts and `import type { Props } from \"./schema.js\";` here." }
 	},

package/dist/eslint/rules/serializable-island-props.js

@@ -1,3 +1,4 @@
+import { docsPathForRule } from "../../rules/registry.js";
 import { isClientFile, resolveImportedFile } from "../is-client-file.js";
 
 //#region src/eslint/rules/serializable-island-props.ts
@@ -56,7 +57,10 @@ function inspect(node, path, out) {
 const serializableIslandProps = {
 	meta: {
 		type: "problem",
-		docs: { description: "Island props must be JSON-serializable" },
+		docs: {
+			description: "Island props must be JSON-serializable",
+			url: docsPathForRule("serializable-island-props")
+		},
 		schema: [],
 		messages: {
 			notSerializableBadType: "{{path}} is {{what}} — island props must be JSON-serializable (string, number, boolean, null, plain object, array). Fix: pass data, not behavior — an island owns its own handlers.",

package/dist/eslint/rules/slot-marker-literal.js

@@ -1,3 +1,5 @@
+import { docsPathForRule } from "../../rules/registry.js";
+
 //#region src/eslint/rules/slot-marker-literal.ts
 const KEY_ATTRS = /* @__PURE__ */ new Set([
 	"data-slot-id",
@@ -8,7 +10,10 @@ const KEY_COMPONENTS = /* @__PURE__ */ new Set(["Slot", "SlotGroup"]);
 const slotMarkerLiteral = {
 	meta: {
 		type: "problem",
-		docs: { description: "Slot markers must carry a string-literal key" },
+		docs: {
+			description: "Slot markers must carry a string-literal key",
+			url: docsPathForRule("slot-marker-literal")
+		},
 		schema: [],
 		messages: { markerNotLiteral: "`{{attr}}` must be a string literal, not an expression — the slot-marker completeness check reads this key statically, and cannot resolve a computed one (the slot would silently lose editor selection). Fix: write the key inline, e.g. `{{attr}}=\"headline\"`." }
 	},

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.1.0";
+var version = "0.2.0";
 
 //#endregion
 export { version };

package/dist/rules/registry.js

@@ -0,0 +1,16 @@
+//#region src/rules/registry.ts
+/**
+* `no-hex` → `docs/rules/no-hex.md`.
+*
+* Package-relative on purpose: the caller decides what to resolve it against. A
+* printer prefixes the resolved package root so an author sees a path they can open
+* with no network (`node_modules/@homepages/template-kit/docs/rules/no-hex.md`);
+* ESLint's `meta.docs.url` uses it as-is. This module never touches the filesystem —
+* the ESLint preset imports it.
+*/
+function docsPathForRule(id) {
+	return `docs/rules/${id}.md`;
+}
+
+//#endregion
+export { docsPathForRule };

package/dist/styles.css

@@ -93,7 +93,7 @@
   --text-5xl:     var(--tr-text-5xl);
   --text-display: var(--tr-text-display);
 
-  /* ---------- Spacing scale (alias to --tr-space-*) ---------- */
+  /* ---------- Spacing (Tailwind's own scale — no custom aliases) ---------- */
   --spacing: 0.25rem;  /* v4 base unit; Tailwind multiplies (e.g. p-4 = 1rem) */
 
   /* ---------- Radii ---------- */

package/docs/INDEX.md

@@ -18,4 +18,5 @@ detail.
 | `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 |
 | `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, its glob scope, and the eleven `template-kit/*` rule ids | wiring up lint in a template workspace, or adding/changing an authoring rule |
+| `eslint.md` | The `@homepages/template-kit/eslint` preset: zero-config setup and its glob scope | wiring up lint in a template workspace |
+| `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/eslint.md

@@ -1,7 +1,7 @@
 ---
-purpose: The authoring-lint preset shipped at `@homepages/template-kit/eslint` — setup, scope, and the eleven rule ids.
+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, islands.md, theme-and-css.md, primitives.md]
+related: [INDEX.md, rules/INDEX.md, islands.md, theme-and-css.md, primitives.md]
 updated: 2026-07-14
 ---
 # ESLint preset
@@ -36,55 +36,20 @@ three config entries, matched by glob rather than by directory depth:
 
 | Entry | Files | Rules |
 |---|---|---|
-| `template-kit/authoring` | `**/*.ts`, `**/*.tsx` | the nine file-scoped rules below |
+| `template-kit/authoring` | `**/*.ts`, `**/*.tsx` | the nine 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` |
 
 Server-vs-client scoping is decided **per file**, by the `"use client"` directive
-prologue — not by an import graph or a build transform. A file carrying the
-directive is an island: it hydrates in the browser, so effects, state, event
-handlers, and inline `style` are legal there and the corresponding rules exempt
-it. A rule that does not exempt islands says so explicitly below.
+prologue — see [server vs client](rules/server-vs-client.md) for what that means
+and exactly which rules stop at that boundary.
 
 ## The rules
 
-Rules that are properties of one file live here. Rules that are properties of the
-**tree** — a missing contract file, a slot declared in `schema.ts` but unmarked in
-`Renderer.tsx`, a CSS rule — cannot be expressed one-file-at-a-time; they belong to
-`template-kit check` (not yet built) under the same `template-kit/<id>` namespace.
-One namespace, two venues.
-
-### Server-rendered code
-
-| Rule | What it bans |
-|---|---|
-| `no-nondeterminism` | Clock/randomness reads (`Date.now()`, `new Date()` with no args, `Math.random()`, `crypto.randomUUID()`/`getRandomValues()`, `performance.now()`) — the publisher and the editor must render byte-identical HTML. Exempt inside an island. |
-| `no-client-runtime-in-server` | Effects, state hooks, event handlers, and browser globals (`fetch`, `window`, `document`, …) — a Renderer must be a pure function of its props. Exempt inside an island. |
-| `no-inline-style` | The `style=` JSX prop — it bypasses the cascade and Tailwind's responsive prefixes. Exempt inside an island. |
-| `no-raw-element` | Raw `<section>`/`<img>` — each has a contract-bearing primitive (`Section`/`Image`) that must be used instead. |
-| `image-bare-needs-reason` | `<Image bare>` with no `// bare: <reason>` comment justifying the skipped frame. |
-| `no-css-import-from-render-path` | A `.css` import anywhere in a section's render path — the SSR graph drops it silently. Import CSS from the section's own `styles.css` instead. |
-
-### Islands
-
-| Rule | What it checks |
-|---|---|
-| `serializable-island-props` | A statically-visible prop passed to an island (a literal function, `new Date()`/`Map`/`Set`/etc., a bigint literal, `NaN`/`Infinity`) that cannot cross the server→browser JSON boundary. It is the static twin of the runtime check — see [islands.md](islands.md#props-must-be-json-serializable). |
-
-### Universal — no island exemption
-
-| Rule | What it bans |
-|---|---|
-| `no-hex` | Hex color literals and CSS color functions (`oklch`/`oklab`/`rgb`/`rgba`/`hsl`/`hsla`/`color-mix`) in a color context (a Tailwind color-utility bracket, an arbitrary-property color declaration, or an inline `style` value). Token discipline is universal — see [theme-and-css.md](theme-and-css.md#color-roles). |
-
-Deliberate asymmetry: `no-inline-style` exempts islands, `no-hex` does not — the
-hydration boundary is not a palette boundary. A section carries no palette of its
-own in either render path.
-
-### Markers and schema
-
-| Rule | What it checks |
-|---|---|
-| `slot-marker-literal` | A slot-key-bearing marker (`<Slot id>`, `<SlotGroup id>`, `slotId`, `data-slot-id`, `data-slot-group`) must carry a string-literal key, not an expression — the slot-marker completeness check (`template-kit check`) reads these keys statically. `SlotItem` is exempt: its prop is `index: number`, an array position, so there is no schema key to cross-check. |
-| `props-from-schema` | A `Renderer.tsx`'s exported `Props` type must come from `SectionProps<typeof schema>`. A hand-written `Props` shadows that inference and drifts. |
-| `no-client-directive-in-contract` | `"use client"` in a section's four contract files (`Renderer.tsx`, `schema.ts`, `fill-spec.ts`, `fixtures.ts`) — the platform reads them outside a browser; marking one an island takes the section's server-rendered HTML with it. |
+Every rule the preset enforces — what it bans, why, and a before/after fix — is
+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.

package/docs/llms.txt

@@ -27,7 +27,8 @@ Everything an author writes a section against is imported from the package root
   and `Image` (responsive `<picture>`, empty-state box). Plus the marker-attribute
   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; `TokenTheme` + `compileThemeToCss`; the breakpoint ladder
+  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
@@ -35,6 +36,8 @@ Everything an author writes a section against is imported from the package root
 - [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 covering the eleven `template-kit/*` authoring rules — determinism, the
-  server/island boundary, serializable island props, the marker and schema contracts,
-  and token discipline.
+  preset — setup and its three-entry glob scope. Per-rule reference lives in `rules/`.
+- [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` →
+  fix. Nothing else to search for; the id is the filename.