@homepages/template-kit 0.2.0 → 0.4.0

package/docs/rules/size-island-bundle.md

@@ -0,0 +1,123 @@
+---
+purpose: The template-kit/size-island-bundle authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, size-renderer-bundle.md, size-section-css.md, server-vs-client.md]
+updated: 2026-07-15
+---
+# template-kit/size-island-bundle
+
+> Each island's browser bundle must be **≤ 50 KB gzip**. The budget is not
+> author-overridable, and it applies per island, not per section.
+
+## Rule
+
+An island — a component whose file opens with the `"use client"` directive (see
+[Server vs client](server-vs-client.md)) — ships to the browser as its own bundle,
+separate from the section's server-rendered HTML. Each island is bundled with esbuild
+and minified, with **React treated as external** (the page's runtime chunk supplies it
+once, shared by every island on the page, and is not counted against any one of them).
+The gzipped result must be **50 KB or less**.
+
+A section can have more than one island. The budget is checked **per island**: a section
+with three islands each at 40 KB passes; a section with one island at 60 KB fails, even
+though the same section's other files are small.
+
+The budget is **visible in `template-kit check`'s configuration and is not
+author-overridable**. A template workspace cannot raise it, and there is no per-island
+exemption.
+
+## Reason
+
+An island is the part of the page that has to work on a phone before the visitor does
+anything — a carousel, a filter, a form. Every one of its bytes is downloaded, parsed,
+and executed on the client, on top of whatever the page's shared runtime already costs.
+Unlike the section's server-rendered markup, which the browser only has to paint, an
+island's code has to run.
+
+The number is set to be generous, so it does not fight ordinary authoring — a real
+interactive widget fits comfortably inside it. You hit the budget when something
+**runaway** gets pulled into the client bundle:
+
+- **a whole UI or icon library imported for one component**, which drags every export
+  into the bundle so the island can use a handful of them;
+- **a heavy dependency that belongs on the server**, ported into the island because it
+  was easiest to reach for where the code was being written, not because the browser
+  needs it.
+
+That is the shape of essentially every violation: not an island that grew, but a single
+import that was more expensive than it looked.
+
+## Fix
+
+Find the import that is not paying for itself, or narrow what ships to the browser at
+all.
+
+- **Import named symbols, never a namespace.** `import { ArrowRight } from "…"` is
+  tree-shakeable; `import * as Icons from "…"` is not — a namespace object has to contain
+  everything, so nothing can be dropped.
+- **Prefer the package's narrow entry** if it offers one, instead of its default
+  "everything" bundle.
+- **Move what doesn't need to be interactive out of the island.** If only a small part of
+  a component actually needs client-side behavior — an expand/collapse toggle inside an
+  otherwise static block — split the interactive part into its own small island and leave
+  the rest server-rendered. Server-rendered markup costs nothing against this budget.
+- **Hand-write the residue.** If you use one function out of a large utility package, copy
+  the function instead of importing the package for it.
+
+### Before
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import * as Icons from "lucide-react"; // ← the whole set: every icon, in this island's bundle
+import { useState } from "react";
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  const [index, setIndex] = useState(0);
+  return (
+    <div>
+      <img src={slides[index]?.url} alt="" />
+      <button onClick={() => setIndex((i) => (i - 1 + slides.length) % slides.length)}>
+        <Icons.ChevronLeft aria-hidden />
+      </button>
+      <button onClick={() => setIndex((i) => (i + 1) % slides.length)}>
+        <Icons.ChevronRight aria-hidden />
+      </button>
+    </div>
+  );
+}
+```
+
+### After
+
+```tsx
+// sections/gallery/Carousel.tsx
+"use client";
+
+import { ChevronLeft, ChevronRight } from "lucide-react"; // ← two icons, and the bundler can drop the rest
+import { useState } from "react";
+
+export default function Carousel({ slides }: { slides: { id: string; url: string }[] }) {
+  const [index, setIndex] = useState(0);
+  return (
+    <div>
+      <img src={slides[index]?.url} alt="" />
+      <button onClick={() => setIndex((i) => (i - 1 + slides.length) % slides.length)}>
+        <ChevronLeft aria-hidden />
+      </button>
+      <button onClick={() => setIndex((i) => (i + 1) % slides.length)}>
+        <ChevronRight aria-hidden />
+      </button>
+    </div>
+  );
+}
+```
+
+## See also
+
+- [`size-renderer-bundle`](size-renderer-bundle.md) — the same budget on the section's
+  server-rendered bundle.
+- [`size-section-css`](size-section-css.md) — the same budget on the section's stylesheet.
+- [Server vs client](server-vs-client.md) — what makes a file an island in the first
+  place.

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

@@ -1,8 +1,8 @@
 ---
 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
+related: [INDEX.md, size-renderer-bundle.md, size-assets.md, ../theme-and-css.md]
+updated: 2026-07-15
 ---
 # template-kit/size-section-css
 
@@ -16,7 +16,7 @@ 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.
+  component or an island.
 
 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.
@@ -29,14 +29,15 @@ 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.
+package's is. A one-line `import "some-ui/dist.css"` can drag in thousands of rules for
+components you never render — resets, theme variants, every widget's styles — and they all
+land in your compiled layer. Nothing in your source looks large; 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.
+one-line CSS import actually cost. (What this budget does **not** count is asset bytes: a
+`url()`-referenced webfont or icon file resolves to a cached URL and is weighed separately —
+see [`size-assets`](size-assets.md).)
 
 ## Fix
 
@@ -45,10 +46,11 @@ 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 page's
-   theme already declares (`--tr-font-sans`, `--tr-font-serif`), which costs nothing
-   because it is already loaded.
+2. **Drop the icon font.** If the package's stylesheet declares an icon font and you use
+   three of its glyphs, 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. (The font *file* is weighed under [`size-assets`](size-assets.md), but its
+   `@font-face` rules and every `.icon-*` class still land in this layer.)
 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.
 
@@ -83,12 +85,15 @@ 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.
+component instead, so the layer no longer carries that font's `@font-face` and icon-class
+rules (and the font file no longer counts against [`size-assets`](size-assets.md) either).
 
 ## See also
 
 - [`size-renderer-bundle`](size-renderer-bundle.md) — the same budget on the section's
   JavaScript.
+- [`size-assets`](size-assets.md) — the separate budget on the static asset *files*
+  (fonts, images) a stylesheet or component references.
 - [`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

package/docs/schema-system.md

@@ -1,8 +1,8 @@
 ---
 purpose: The section authoring contract — schema.ts, fill-spec.ts, fixtures.ts, and the closed source/transform vocabulary.
 status: living
-related: [primitives.md, theme-and-css.md]
-updated: 2026-07-14
+related: [primitives.md, theme-and-css.md, vocabulary.md]
+updated: 2026-07-16
 ---
 # The schema system
 
@@ -32,22 +32,17 @@ from. Without it, `SectionProps` cannot tell a required slot from an optional on
 and your renderer props collapse to a useless widened shape.
 
 ```ts
-import { direct, type FrameConfig, type SectionProps, type SectionSchemaShape } from "@homepages/template-kit";
-
-export const HERO_FRAME = {
-  breakpoint: 425,
-  desktop: { aspect: 5 / 3 },
-} as const satisfies FrameConfig;
+import { direct, type SectionProps, type SectionSchemaShape } from "@homepages/template-kit";
 
 export const schema = {
   meta: { displayName: "Hero" },
   slots: {
-    headline: { type: "text", size: "medium", required: true, produced_by: "headline_text" },
-    listing_status: { type: "select", required: false, source: direct("listing_intent") },
-    hero_image: { type: "image", required: true, produced_by: "hero_image_assign", frame: HERO_FRAME },
+    hero_image: { type: "image", required: true, produced_by: "hero_image_assign", crop: { mode: "locked", aspect: 16 / 9 } },
+    headline: { type: "text", size: "medium", required: true, source: direct("address") },
+    blurb: { type: "text", size: "long", required: true, produced_by: "blurb_text" },
   },
   options: {
-    align: { type: "enum", values: ["left", "center"], default: "left" },
+    align: { type: "enum", values: ["left", "center"], default: "center" },
   },
 } as const satisfies SectionSchemaShape;
 
@@ -65,14 +60,20 @@ binds it to a computed transform. Both take names from a **closed vocabulary**,
 a typo is a compile error at the call site — not a runtime surprise:
 
 ```ts
-source: direct("listing_intent")   // ✅
-source: direct("listing_intentt")  // ✗ compile error: not a SOURCE_FIELDS key
+source: direct("address")   // ✅
+source: direct("addresss")  // ✗ compile error: not a SOURCE_FIELDS key
 ```
 
-The vocabulary is the kit's, not yours. Read it off the exported tables —
-`SOURCE_FIELDS` (facts `direct()` accepts), `TRANSFORMS` (`derived()`), and
-`SLOT_TYPE_DESCRIPTORS` (the slot types) — or let your editor autocomplete it.
-Adding to it is a kit release, not a change you can make in a template.
+The vocabulary is the kit's, not yours. Adding to it is a kit release, not a
+change you can make in a template. See [the closed vocabulary](vocabulary.md)
+for the sets and when to pick each; your editor autocompletes the exact fields.
+
+A `select` slot binds the same way as any other type — here fact-bound rather
+than AI-produced, with `values` declaring the closed set the fact resolves to:
+
+```ts
+listing_status: { type: "select", required: false, source: direct("listing_intent"), values: ["for_sale", "for_rent"] },
+```
 
 ### Grouping slots into one editor card
 
@@ -104,7 +105,6 @@ import type { Props } from "./schema.js";
 
 export default function Hero({ slots, options, nav }: Props) {
   // headline is `string` — the schema says required: true
-  // listing_status is `string | null` — required: false
   // options.align is `"left" | "center"` — the enum's declared values
   return (
     <Section id={nav.selfAnchor}>
@@ -153,12 +153,12 @@ export const fillSpec = {
   decisions: [
     { id: "hero_image_assign", type: "image-assign", produces: ["hero_image"], tag_query: "category:exterior" },
     {
-      id: "headline_text",
+      id: "blurb_text",
       type: "text-block",
-      produces: ["headline"],
-      length_cap: 60,
-      structure: "single_sentence",
-      voice_prompt: "Confident premium-listing voice. Title Case.",
+      produces: ["blurb"],
+      length_cap: 400,
+      structure: "paragraph",
+      voice_prompt: "Warm, concrete paragraph a buyer would want to read.",
     },
   ],
 } as const satisfies FillSpecShape;
@@ -177,14 +177,14 @@ import type { FixtureModule } from "@homepages/template-kit";
 const fixtures: FixtureModule = {
   base: {
     slots: {
-      headline: "A mansard Victorian in the heart of Jamaica Plain",
-      listing_status: "for_sale",
+      headline: "101 Queensway, Jamaica Plain, MA 02130",
       hero_image: { photo_id: "p1", url: "https://example.com/a.jpg", alt: "Front elevation" },
+      blurb: "A bright corner home moments from the Emerald Necklace.",
     },
-    options: { align: "left" },
+    options: { align: "center" },
   },
   states: {
-    centered: { label: "Centered", options: { align: "center" } },
+    left: { label: "Left-aligned", options: { align: "left" } },
   },
 };
 

package/docs/theme-and-css.md

@@ -1,41 +1,170 @@
 ---
 purpose: The kit's two CSS entries, how a section's own CSS reaches the page, the TokenTheme a template supplies, and the breakpoint ladder.
 status: living
-related: [primitives.md, schema-system.md, eslint.md, rules/INDEX.md]
-updated: 2026-07-14
+related: [primitives.md, schema-system.md, eslint.md, rules/INDEX.md, check.md]
+updated: 2026-07-15
 ---
 # Theme and CSS
 
-The kit owns the **contract**: the Tailwind utility namespace (`text-ink`,
-`bg-surface-alt`, `rounded-md`), the breakpoint ladder, the reset gaps Tailwind's preflight leaves, and the section box
-model. Your template owns the **values** behind that namespace, declared once as a
-`TokenTheme`.
+Your template owns its design system end to end — **the token names included**. You
+declare the tokens your design actually has in a `TokenTheme`, and `template-kit theme`
+compiles that one declaration into the Tailwind utilities that expose them. Declare a
+colour named `lagoon` and `bg-lagoon` exists.
+
+The kit owns only what is true of **every** template: the breakpoint ladder, the spacing
+base unit, the motion defaults, the reset gaps Tailwind's preflight leaves, and the
+section box model. It ships no colour, font, type, radius or shadow of its own, and there
+is no shared file for you to edit to make a token of yours usable.
 
 Two CSS entries ship, and they are not interchangeable.
 
 | Entry | What it is | How it loads |
 |---|---|---|
-| `@homepages/template-kit/styles.css` | The Tailwind v4 `@theme inline` alias layer + the breakpoint ladder + `@source` registration of the kit's compiled JS | imported into **your Tailwind entry**, after Tailwind |
-| `@homepages/template-kit/base.css` | Cascade-layer order, the three reset gaps Tailwind's preflight leaves, `.tr-section`, and the motion tokens | its **own stylesheet** on the page — not part of the Tailwind entry |
+| `@homepages/template-kit/styles.css` | The global Tailwind preamble: breakpoint ladder, `--spacing`, motion defaults, and `@source` registration of the kit's compiled JS | imported into **your Tailwind entry**, after Tailwind |
+| `@homepages/template-kit/base.css` | Cascade-layer order, the three reset gaps Tailwind's preflight leaves, `.tr-section`, `.tr-image-frame`, and the motion tokens | its **own stylesheet** on the page — not part of the Tailwind entry |
 
-## Import Tailwind exactly once
+## Your Tailwind entry
 
 ```css
 /* your CSS entry */
 @import "tailwindcss";
 @import "@homepages/template-kit/styles.css";
+@import "./theme.css";                 /* generated by `template-kit theme` from theme.ts */
 ```
 
-`styles.css` deliberately does **not** `@import "tailwindcss"` itself. Exactly one
-`@import "tailwindcss"` may exist per build graph — yours. Two double-emit Tailwind's
-preflight reset (`box-sizing` declared twice, several KB of duplicate base layer), and
-nothing errors to tell you.
+Three constraints, all of them silent when broken:
+
+- **Import Tailwind exactly once per build graph.** `styles.css` deliberately does not
+  `@import "tailwindcss"` itself — yours does. Two double-emit Tailwind's preflight reset
+  (`box-sizing` declared twice, several KB of duplicate base layer), and nothing errors.
+- **Your generated theme must be imported here, inside the Tailwind build graph.** It
+  contains an `@theme` block, which is a Tailwind directive: anywhere outside the graph it
+  is inert, and you get a stylesheet with no token utilities and no error explaining why.
+- **Import it after `styles.css`**, so the kit's globals are in place before your tokens
+  land on top of them.
+
+`styles.css` also carries an `@source` line registering the kit's own shipped `dist` for
+Tailwind's class scan. That is how the utility classes baked into the kit's primitives
+(`Image`'s `object-cover`, …) reach your compiled CSS; it also overrides Tailwind's default
+exclusion of `node_modules`. You do not need to add a `@source` for the kit yourself.
+
+## `TokenTheme` — your template's design system
+
+A template's `theme.ts` exports a `TokenTheme`: six open records of tokens, plus the
+document defaults that dress the page. `theme.ts` is the file you write; run
+`template-kit theme` to compile it into the `theme.css` your Tailwind entry imports
+(see [Generating `theme.css`](#generating-themecss) below).
+
+```ts
+import type { TokenTheme } from "@homepages/template-kit";
+
+export const theme: TokenTheme = {
+  colors: { ink: "#111418", page: "#ffffff", "surface-alt": "#f4f4f5", lagoon: "#1c6e7d" },
+  fonts:  { sans: '"Inter", system-ui, sans-serif', display: '"Canela", Georgia, serif' },
+  type:   { base: "1rem", "2xl": "1.5rem", display: "clamp(2.5rem, 6vw, 4.5rem)" },
+  radii:  { md: "6px", pill: "9999px" },
+  shadows: { card: "0 1px 2px rgb(0 0 0 / 0.06)" },
+  layout: { "container-max": "1280px", "header-height": "72px" },
+
+  // Optional font-loading block, emitted ahead of everything else.
+  fontFaces: '@import url("https://fonts.example/inter.css");',
+
+  // Which of YOUR tokens dress the document.
+  document: { font: "sans", color: "ink", background: "page", fontSize: "base" },
+};
+```
+
+Nothing is required to exist. Tailwind's own defaults survive underneath your tokens —
+`text-2xl`, `rounded-lg`, `red-500` all still work — so a sparse theme is a working theme.
+(The breakpoint ladder is the one exception: `sm:`, `xl:` and `2xl:` are deliberately
+switched off. See below.)
+
+### Namespaces and the utilities they produce
+
+Each record maps to one Tailwind theme namespace. A token's key is emitted **verbatim**
+into both the custom property and the utility — no camelCase-to-kebab transform, so what
+you type is what you get.
+
+| Record | Custom property | Tailwind utilities | Example |
+|---|---|---|---|
+| `colors` | `--tr-color-<name>` | `bg-`, `text-`, `border-`, `ring-`, `fill-`, `stroke-`, … | `lagoon` → `bg-lagoon` |
+| `fonts` | `--tr-font-<name>` | `font-<name>` | `display` → `font-display` |
+| `type` | `--tr-text-<name>` | `text-<name>` | `2xl` → `text-2xl` |
+| `radii` | `--tr-radius-<name>` | `rounded-<name>` | `pill` → `rounded-pill` |
+| `shadows` | `--tr-shadow-<name>` | `shadow-<name>` | `card` → `shadow-card` |
+| `layout` | `--tr-<name>` | *(none)* | `header-height` → `var(--tr-header-height)` |
+
+`layout` has no Tailwind utility namespace, so its tokens get a `--tr-*` value and no
+utility — reference them with `var()` from your own CSS.
+
+### Token names
+
+Kebab-case: `[a-z0-9]` groups separated by single hyphens (`ink`, `ink-soft`, `bp2`).
+`TokenNameSchema` is exported if you want to validate names yourself.
+
+**One token, one utility.** Two utility names cannot share a token — if you want both
+`bg-brand` and `bg-primary`, declare both.
+
+### The `document` block
+
+Required. It names which of your **own** tokens dress the page — the `body` font-family,
+colour, background, and font-size. `font` and `fontSize` resolve against `fonts` and
+`type`; `color` and `background` resolve against `colors`.
+
+Every reference is validated against your declared tokens, in its own group: a typo, or a
+colour name where a font belongs, fails at parse rather than rendering an unthemed page in
+silence.
+
+### Validation
+
+`TokenThemeSchema` validates the object at runtime, and it is `.strict()` — an unknown
+top-level key is an error rather than a silently-dead set of tokens.
+
+## Generating `theme.css`
 
-`styles.css` also carries `@source "./**/*.js"`, which registers the kit's own shipped
-`dist` for Tailwind's class scan. That is how the utility classes baked into the kit's
-primitives (`Image`'s `bg-surface-alt`, `object-cover`, …) reach your compiled CSS; it
-also overrides Tailwind's default exclusion of `node_modules`. You do not need to add a
-`@source` for the kit yourself.
+`template-kit theme` loads `templates/<key>/theme.ts`, validates its `theme` export
+against `TokenThemeSchema`, and writes `templates/<key>/theme.css` — the file your
+Tailwind entry imports.
+
+```bash
+template-kit theme                # infer the template from cwd, or the workspace's one template
+template-kit theme <template>     # generate one named template's theme.css, by its key
+template-kit theme --all          # generate every template in the workspace
+```
+
+`theme.css` is generated — it opens with a header saying so, and it is not meant to be
+hand-edited. Re-run `template-kit theme` after changing `theme.ts` and commit the
+regenerated file alongside it.
+
+A missing `theme.ts`, a `theme.ts` that doesn't export `theme`, or a `theme` that fails
+`TokenThemeSchema` all fail the command with a message naming the file and the problem —
+nothing is written in that case.
+
+In order, the file it writes contains:
+
+1. your `fontFaces` block, if you set one;
+2. `@theme inline { --color-<name>: var(--tr-color-<name>); … }` — the alias layer, which
+   is what brings your token utilities into existence;
+3. `:root { --tr-color-<name>: <value>; … }` — the values behind those aliases;
+4. `body { … }` — your `document` defaults, written as `var()` indirections so a runtime
+   `:root` override still cascades to the page.
+
+Deterministic: keys are sorted, so the same theme always content-hashes identically.
+
+## Colour in sections
+
+A section carries no palette of its own, in server-rendered code or inside an island — the
+`template-kit/no-hex` [lint rule](rules/no-hex.md) flags a hard-coded hex literal in a
+colour context, and a CSS colour function anywhere, without exempting `"use client"` files
+the way most of the preset's other rules do. Sections spend the theme's tokens; the theme
+is where a colour is named.
+
+For a colour the theme does not name — a hover, active, or pressed step, or a translucent
+tint — derive it from the tokens that *are* named, with a `color-mix()` over theme-derived
+arguments:
+`hover:bg-[color-mix(in_srgb,var(--tr-color-primary)_80%,var(--tr-color-surface))]`. Such a
+mix composes a colour out of the theme rather than stating one, and is the single colour
+function `no-hex` allows — it carves out no other.
 
 ## How a section's CSS reaches the page
 
@@ -48,8 +177,8 @@ never write an import to make either happen:
    template's own hand-written stylesheet is collected the same way, into
    `@layer template`.
 2. **Package CSS, harvested from the render path.** The build also bundles
-   `Renderer.tsx`'s module graph — and any component that carries `export const
-   enhancer` — and pulls in whatever `.css` those imports resolve to. A bare specifier
+   `Renderer.tsx`'s module graph — every component and island it imports — and pulls in
+   whatever `.css` those imports resolve to. A bare specifier
    (`import "swiper/css";`) resolves into `node_modules` and lands in the same
    `@layer sections`; that is the sanctioned way for a third-party package's
    stylesheet to reach the page.
@@ -70,12 +199,10 @@ Two constraints follow directly, and both are enforced by lint:
 
 A published page loads, in order:
 
-1. **`base.css`** — layer order, the reset gaps, `.tr-section`, motion tokens.
-2. **Your compiled theme CSS** — the `:root` block that defines the `--tr-*` values
-   *and* the `body` block that applies them (font-family, color, background, size),
-   both produced by `compileThemeToCss`.
-3. **Your compiled Tailwind bundle** — `@import "tailwindcss"` + `styles.css` + your
-   section markup's utilities.
+1. **`base.css`** — layer order, the reset gaps, `.tr-section`, `.tr-image-frame`, motion
+   tokens.
+2. **Your compiled Tailwind bundle** — your entry: `@import "tailwindcss"` + the kit's
+   `styles.css` + your compiled theme + the utilities your section markup uses.
 
 The layer order `base.css` declares is:
 
@@ -96,70 +223,9 @@ not make: `font-smoothing`, `button { cursor: pointer }` (Tailwind v4 leaves but
 
 Ship `base.css` without a Tailwind entry on the page and you get an unreset page.
 
-`base.css` references **no theme token**. Your fonts and colors reach the document
-through `compileThemeToCss`, which emits both the `:root` block that defines your tokens
-and the `body` block that applies them. Nothing global is opinionated about your brand.
-
-## `TokenTheme` — your template's values
-
-A template's `theme.ts` exports a `TokenTheme`. `compileThemeToCss` turns it into the
-`:root { --tr-*: … }` block that defines your tokens **and** the `body` block that
-applies them (font-family, color, background, size) to the document — together, the
-CSS the template's bundle ships. Deterministic (stable key order, palette keys
-sorted), so the same theme always content-hashes identically.
-
-```ts
-import { compileThemeToCss, type TokenTheme } from "@homepages/template-kit";
-
-export const theme: TokenTheme = {
-  colors: { ink: "#111418", background: "#ffffff", /* …every role, see below */ },
-  palette: { "brand-gold": "#c8a248" },        // optional escape hatch
-  fonts: {
-    body: '"Inter", system-ui, sans-serif',
-    heading: '"Canela", Georgia, serif',
-    numeric: '"Inter", system-ui, sans-serif',
-    label: '"Inter", system-ui, sans-serif',
-    fontFaces: '@import url("https://fonts.example/inter.css");', // optional, emitted before :root
-  },
-  type: { xs: "0.75rem", sm: "0.875rem", base: "1rem", /* lg xl 2xl 3xl 4xl 5xl display */ },
-  radii: { sm: "2px", md: "6px", lg: "12px", full: "9999px" },
-  shadows: { sm: "…", md: "…", lg: "…" },
-  layout: { containerMax: "1280px", containerPad: "1.5rem", headerHeight: "72px" },
-};
-
-const css = compileThemeToCss(theme);
-```
-
-`TokenThemeSchema` validates it at runtime; the object is `.strict()`, so an unknown key
-is an error rather than a silently-dead token. Every scale is **complete or invalid** —
-there are no defaults to fall back on.
-
-### Color roles
-
-The role keys are fixed. Each maps 1:1 to a `--tr-color-*` variable, and the Tailwind
-utility is named after **the variable**, not the role key — so `surfaceAlt` is
-`bg-surface-alt`, and `primaryStrong` is `bg-primary-darker`. Read the mapping off the
-exported `COLOR_ROLE_VARS` (and `FONT_ROLE_VARS`, `TYPE_STEP_VARS`, `RADIUS_VARS`,
-`SHADOW_VARS`, `LAYOUT_VARS` for the other scales), or let your editor autocomplete the
-`ColorRole` union:
-
-| Role key | CSS variable | Utility |
-|---|---|---|
-| `ink` `inkSoft` `inkMute` | `--tr-color-ink[-soft|-mute]` | `text-ink`, `text-ink-soft`, `text-ink-mute` |
-| `background` `surface` `surfaceAlt` | `--tr-color-background` / `-surface` / `-surface-alt` | `bg-surface-alt`, … |
-| `border` `borderStrong` | `--tr-color-border[-strong]` | `border-border-strong`, … |
-| `primary` `primaryFg` `primaryStrong` | `--tr-color-primary` / `-primary-fg` / `-primary-darker` | `bg-primary`, `text-primary-fg`, `bg-primary-darker` |
-| `accent` `accentFg` `accentStrong` | `--tr-color-accent` / `-accent-contrast` / `-accent-strong` | `bg-accent`, `text-accent-contrast`, `bg-accent-strong` |
-| `overlay` `overlayStrong` `overlayLight` | `--tr-color-overlay[-strong|-light]` | `bg-overlay`, … |
-| `darkBg` `darkFg` `darkFgMute` `darkBorder` | `--tr-color-footer-bg` / `-footer-fg` / `-footer-fg-mute` / `-footer-divider` | `bg-footer-bg`, `text-footer-fg`, `border-footer-divider`, … |
-
-`palette` is the open escape hatch: each key becomes `--tr-color-<key>`. Sections normally
-use the semantic roles — reach for a brand swatch only when no role honestly fits.
-
-A section carries no palette of its own, in server-rendered code or inside an island —
-the `template-kit/no-hex` [lint rule](eslint.md#universal--no-island-exemption) bans a
-hard-coded hex literal or CSS color function in a color context and does not exempt
-`"use client"` files, unlike most of the preset's other rules.
+`base.css` references **no design token of yours** — nothing global is opinionated about
+your brand. Its one tintable surface is the `Image` frame's placeholder fill; see
+[`Image`](primitives.md#image--the-defensive-image-primitive).
 
 ## The breakpoint ladder
 
@@ -191,8 +257,7 @@ memory — enough to make it evict a live WebGL map's layer on scroll, blanking
 they stop consuming that memory.
 
 The kit does **not** apply this for you — it has a real cost (below), and only you know
-whether your page needs it. If it does, add the rule to the same CSS entry that does
-`@import "tailwindcss"; @import "@homepages/template-kit/styles.css";` — the third
+whether your page needs it. If it does, add the rule to your Tailwind entry — the second
 stylesheet the page loads:
 
 ```css