@homepages/template-kit 0.2.0 → 0.4.0

package/docs/rules/manifest-invalid.md

@@ -0,0 +1,99 @@
+---
+purpose: The template-kit/manifest-invalid authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../schema-system.md, schema-invalid.md, no-templates.md]
+updated: 2026-07-14
+---
+# template-kit/manifest-invalid
+
+> `manifest.json` is the one file that says which sections make a page, and in what
+> order. Every check on it lands under this id.
+
+## Rule
+
+A template folder (`templates/<key>/`) must have a `manifest.json` at its root, and that
+file must:
+
+- **exist** — a template folder with none at all reports this once, naming the missing
+  file;
+- **parse as JSON, and satisfy the manifest shape** — `key`, `name`, `deliverable_type`,
+  and an ordered `sections` array of section instances (`section`, `instance_id`,
+  `options`, `locked`, `required`, `reorderable`);
+- **agree with its own folder** — the manifest's `key` must match the template folder
+  name it lives in;
+- **reference real sections** — every `sections[].section` must resolve to a section this
+  workspace actually has;
+- **override only what's real and overridable** — an instance's `options` may only name an
+  option the target section declares, only when that option is not
+  `template_overridable: false`, and only with a value that actually differs from the
+  section's own default;
+- **satisfy the whole-composition nav contract** — the cross-section rules that need the
+  full, resolved section set rather than any one section in isolation.
+
+Every violation collects into the same run; a manifest with several wrong references
+reports all of them together.
+
+## Reason
+
+A section's own four files describe that section in isolation — they say nothing about
+which page it appears on, in what order, or which of its options a specific template has
+chosen to lock in. `manifest.json` is where that composition is declared, and it is the
+only place a downstream consumer (the publisher, the fill pipeline, the editor) can go to
+learn a template's actual shape. A manifest that references a section that doesn't exist,
+or restates a default as if it were an override, is a template whose real composition
+nobody can trust the manifest to describe.
+
+## Fix
+
+Read the message: it names the template, the section instance, and what's wrong.
+Missing entirely, add one. Otherwise, fix the field the message points at.
+
+### Before
+
+```text
+templates/acme-modern/
+  manifest.json
+  sections/
+    hero/
+```
+
+```json
+// templates/acme-modern/manifest.json
+{
+  "key": "acme-classic",
+  "name": "Acme Classic",
+  "deliverable_type": "single_property_website",
+  "sections": [
+    { "section": "hero", "instance_id": "hero-1", "options": {}, "locked": [], "required": true, "reorderable": false }
+  ],
+  "reconcile": []
+}
+```
+
+```text
+Template "acme-modern": manifest key "acme-classic" does not match the template folder name "acme-modern".
+```
+
+### After
+
+```json
+// templates/acme-modern/manifest.json
+{
+  "key": "acme-modern",
+  "name": "Acme Modern",
+  "deliverable_type": "single_property_website",
+  "sections": [
+    { "section": "hero", "instance_id": "hero-1", "options": {}, "locked": [], "required": true, "reorderable": false }
+  ],
+  "reconcile": []
+}
+```
+
+## See also
+
+- [The schema system](../schema-system.md#manifestjson--composing-sections-into-a-template) —
+  what a manifest declares and the type it's validated against.
+- [`schema-invalid`](schema-invalid.md) — the same kind of cross-reference check, one
+  level down, on a single section's own contract files.
+- [`no-templates`](no-templates.md) — reported instead when the workspace has no
+  `templates/<key>/` folder to check at all.

package/docs/rules/no-bare-css-import.md

@@ -2,7 +2,7 @@
 purpose: The template-kit/no-bare-css-import authoring rule — what it enforces, why, and how to fix it.
 status: living
 related: [INDEX.md, ../theme-and-css.md]
-updated: 2026-07-14
+updated: 2026-07-15
 ---
 # template-kit/no-bare-css-import
 
@@ -59,11 +59,11 @@ in the whole kit: the only signal is that the styles are not there.
 Delete the `@import`.
 
 **A package's stylesheet is reached from the code that needs it**, not from CSS. Write
-`import "swiper/css";` in the component, island, or enhancer that renders the thing — the
-CSS build bundles your `Renderer.tsx` and every marked enhancer, transitively, precisely to
-harvest those imports, and it compiles what they pull in into **this section's cascade
-layer**. Package CSS goes in first and your own hand-CSS second, so at equal specificity
-your rules win.
+`import "swiper/css";` in the component or island that renders the thing — the CSS build
+bundles your `Renderer.tsx` and everything it imports, transitively, precisely to harvest
+those imports, and it compiles what they pull in into **this section's cascade layer**.
+Package CSS goes in first and your own hand-CSS second, so at equal specificity your rules
+win.
 
 Two things authors get wrong immediately after:
 
@@ -79,7 +79,7 @@ Two things authors get wrong immediately after:
 
 ```css
 /* sections/gallery/styles.css */
-/* css-reason: styles the slide DOM the Swiper enhancer builds at runtime. */
+/* css-reason: styles the slide DOM the Swiper carousel builds at runtime. */
 @import "swiper/css";              /* template-kit/no-bare-css-import — silently dropped */
 
 .tr-gallery .swiper-pagination-bullet-active {
@@ -95,7 +95,7 @@ The `@import` is gone from the stylesheet:
 
 ```css
 /* sections/gallery/styles.css */
-/* css-reason: overrides the Swiper pagination DOM the enhancer builds at runtime —
+/* css-reason: overrides the Swiper pagination DOM the carousel builds at runtime —
    those nodes carry the library's own classes, which Tailwind's scanner never sees. */
 .tr-gallery .swiper-pagination-bullet-active {
   background: var(--tr-color-primary);

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

@@ -2,7 +2,7 @@
 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
+updated: 2026-07-15
 ---
 # template-kit/no-css-import-from-render-path
 
@@ -31,8 +31,8 @@ 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
+every module it imports, components and islands alike — and harvesting the CSS those
+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
@@ -47,11 +47,10 @@ Delete the import. A local stylesheet already ships — the build picks up every
 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.
+that needs it. The build bundles `Renderer.tsx`'s import graph **transitively**, so a bare
+specifier is equally legal in the Renderer itself or in any component or island it
+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
 

package/docs/rules/no-hex.md

@@ -2,7 +2,7 @@
 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
+updated: 2026-07-15
 ---
 # template-kit/no-hex
 
@@ -11,11 +11,20 @@ updated: 2026-07-14
 
 ## Rule
 
-Two shapes are banned:
+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.
 
-- **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(...)`.
+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]`,
@@ -35,6 +44,40 @@ 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
@@ -49,10 +92,14 @@ 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.
+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
 
@@ -90,8 +137,27 @@ export function Renderer({ slots }: Props) {
 }
 ```
 
+### 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#color-roles) — the token system and the colour roles.
+- [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-templates.md

@@ -0,0 +1,87 @@
+---
+purpose: The template-kit/no-templates authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, manifest-invalid.md]
+updated: 2026-07-14
+---
+# template-kit/no-templates
+
+> A run that gates nothing must never report success. This is what a workspace with no
+> template to check reports instead of a silent pass.
+
+## Rule
+
+`templates/` must hold at least one template folder — for the run you asked for:
+
+- `template-kit check` (no argument, from the workspace root): `templates/` has no
+  folder in it at all.
+- `template-kit check --all`: same — no template folder exists to check.
+- `template-kit check <name>` (or a bare `check` run from inside a template's own
+  folder): that one named template does not exist. (A folder that exists but is
+  missing its `manifest.json` is a different, more specific failure —
+  [`manifest-invalid`](manifest-invalid.md) — because a folder under `templates/` is a
+  template whatever else is wrong with it.)
+
+This is checked once per run, scoped to the workspace, not to any one template.
+
+## Reason
+
+`every()` over an empty set is vacuously true. A `check` run that selected zero templates
+and reported "check passed" would exit 0 having run not one gate — indistinguishable from
+a workspace that passed every rule, when in truth no rule ran at all. Anything that
+re-runs this command on your behalf (an ingest pipeline, a CI step) would accept that
+silence as a clean submission.
+
+Reporting a diagnostic instead means "nothing to check" is a failure your run surfaces,
+not a false green light.
+
+## Fix
+
+Add a template: `templates/<key>/` with a `manifest.json` declaring its section
+composition, and a `sections/` folder holding the sections it composes. If you meant to
+check a specific template and named it wrong, or ran `check` from a folder that isn't a
+template folder, correct the name or your working directory instead.
+
+### Before
+
+```text
+my-workspace/
+  package.json
+  package-lock.json
+  templates/            ← empty
+```
+
+```text
+$ template-kit check
+✗ workspace — 1 problem(s)
+    [template-kit/no-templates] This workspace has no template to check: templates/ holds no template folder.
+    fix: Add a template: templates/<key>/ with a manifest.json declaring its section composition and a sections/ folder holding the sections it composes.
+```
+
+### After
+
+```text
+my-workspace/
+  package.json
+  package-lock.json
+  templates/
+    acme-modern/
+      manifest.json
+      sections/
+        hero/
+          Renderer.tsx
+          schema.ts
+          fill-spec.ts
+          fixtures.ts
+```
+
+```text
+$ template-kit check
+✓ acme-modern
+check passed
+```
+
+## See also
+
+- [`manifest-invalid`](manifest-invalid.md) — the check that takes over once a template
+  folder exists, on whether its `manifest.json` is present and correct.

package/docs/rules/parse-error.md

@@ -0,0 +1,76 @@
+---
+purpose: The template-kit/parse-error authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, typecheck.md]
+updated: 2026-07-14
+---
+# template-kit/parse-error
+
+> A file so broken it never became an AST. Every other rule needs one; this is what's
+> reported when there isn't one to have an opinion about.
+
+## Rule
+
+Every other lint rule runs against a parsed file — an AST it can walk and ask questions
+of. When a `.ts`/`.tsx` file cannot even be parsed (invalid syntax: an unclosed brace, a
+stray token, a JSX tag that never closes), there is no AST for any rule to run against,
+and no rule id of its own to report. This id is what's reported in that one case instead:
+the parser's own message, relocated to the file and line it names.
+
+This is the only diagnostic under this id — it is not a rule you can violate by writing
+working code a particular way, the way `no-hex` or `no-inline-style` are. It exists so
+that "the file didn't parse" is a rule-id and a fix hint, not silence or a raw crash.
+
+## Reason
+
+A stage never aborts the run — an author fixing one file's problem must see every other
+file's problems in the same run, not discover them one release at a time. A parser
+exception is the one case where that promise is hardest to keep: there is genuinely
+nothing else to check about a file that doesn't parse. Reporting it under its own id,
+rather than dropping it or letting it throw, keeps that promise intact.
+
+You may see the **same file** flagged here and under
+[`typecheck`](typecheck.md): the lint stage and the typecheck stage each parse the
+workspace independently, and a syntax error fails both parsers, so both stages report it,
+each in their own words. Fixing the syntax error clears both.
+
+## Fix
+
+Read the message — it is the parser's own error, naming the file and the line. Fix the
+syntax at that location.
+
+### Before
+
+```tsx
+// sections/hero/Renderer.tsx
+export function Renderer() {
+  return (
+    <Section>
+      <h1>{headline}</h1>
+    </Section
+  );
+}
+```
+
+```text
+sections/hero/Renderer.tsx:6
+  Parsing error: '>' expected.
+```
+
+### After
+
+```tsx
+// sections/hero/Renderer.tsx
+export function Renderer() {
+  return (
+    <Section>
+      <h1>{headline}</h1>
+    </Section>
+  );
+}
+```
+
+## See also
+
+- [`typecheck`](typecheck.md) — the sibling failure one layer up: a file that parses but
+  does not type-check.

package/docs/rules/schema-invalid.md

@@ -0,0 +1,96 @@
+---
+purpose: The template-kit/schema-invalid authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../schema-system.md, fixtures-invalid.md, manifest-invalid.md]
+updated: 2026-07-14
+---
+# template-kit/schema-invalid
+
+> `schema.ts` and `fill-spec.ts` are a matched pair. This is every check that makes sure
+> they actually agree.
+
+## Rule
+
+A section's `schema.ts` and `fill-spec.ts` must, together:
+
+- **parse** — each is `as const satisfies` its shape (`SectionSchemaShape`,
+  `FillSpecShape`); a value that doesn't satisfy it fails here with the parse error;
+- **cross-reference correctly** — every `fill-spec.ts` decision produces a slot that
+  actually exists in `schema.ts`, every `reads` entry names a real, author-declarable
+  facts key, every option's `affects_decisions`/`affects_slots` names a real decision or
+  slot;
+- **satisfy the closed per-type contracts** — an `object_list` slot's `item_order`
+  covers every field, a `select` slot's cases match its transform, a group's members are
+  slots that exist, and the rest of the per-slot-type rules the schema system documents.
+
+One violation is one diagnostic; a section with several wrong things reports all of them
+in the same run, not one per fix.
+
+This is the id you also see when a section **cannot be built or parsed at all** — a
+syntax error in `schema.ts`, a missing export, an import that doesn't resolve. The
+message in that case is the underlying build error, relocated to the file it points at.
+
+## Reason
+
+`fill-spec.ts` is not free-standing — every decision it declares exists to fill a slot
+`schema.ts` declared, and every fact it reads must be one the platform actually exposes.
+A decision that produces a slot no schema declares, or reads a fact that doesn't exist,
+is not a style problem: the fill pipeline would either drop the output on the floor or
+crash trying to read a fact key that isn't there. Catching the mismatch here, at author
+time, is the difference between a red check and a listing that silently fails to fill.
+
+## Fix
+
+Read the message: it names the section, the decision or slot in question, and what's
+wrong with it. Fix whichever side is actually stale — the schema, or the fill-spec.
+
+### Before
+
+```ts
+// sections/facts/schema.ts
+export const schema = {
+  meta: { displayName: "Facts" },
+  slots: {
+    year_built: { type: "text", required: false, produced_by: "year_built_text" },
+  },
+  options: {},
+} as const satisfies SectionSchemaShape;
+```
+
+```ts
+// sections/facts/fill-spec.ts
+export const fillSpec = {
+  reads: [],
+  decisions: [
+    { id: "year_built_text", type: "text-block", produces: ["year_built_summary"], length_cap: 20 },
+    //                                                       ^ typo — schema.ts declares "year_built"
+  ],
+} as const satisfies FillSpecShape;
+```
+
+```text
+Section "facts": fill-spec decision "year_built_text" produces unknown slot "year_built_summary".
+```
+
+### After
+
+```ts
+// sections/facts/fill-spec.ts
+export const fillSpec = {
+  reads: [],
+  decisions: [
+    { id: "year_built_text", type: "text-block", produces: ["year_built"], length_cap: 20 },
+  ],
+} as const satisfies FillSpecShape;
+```
+
+## See also
+
+- [The schema system](../schema-system.md) — the full authoring contract for `schema.ts`
+  and `fill-spec.ts`.
+- [`fixtures-invalid`](fixtures-invalid.md) — the sibling gate on the third contract
+  file, `fixtures.ts`.
+- [`manifest-invalid`](manifest-invalid.md) — the same kind of cross-reference check, one
+  level up, on a template composing several sections.
+- [`bundle-incomplete`](bundle-incomplete.md) — reported instead of this id when a
+  contract file is missing outright, rather than present and wrong.

package/docs/rules/size-assets.md

@@ -0,0 +1,88 @@
+---
+purpose: The template-kit/size-assets authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, size-section-css.md, ../theme-and-css.md]
+updated: 2026-07-15
+---
+# template-kit/size-assets
+
+> A section's static assets — the svg, images, and fonts it imports or `url()`-references —
+> must total **≤ 250 KB raw.** Raw, not gzip: images and fonts are already compressed
+> formats, so gzipping them again buys nothing.
+
+## Rule
+
+A section's static assets are budgeted by **total raw bytes, 250 KB or less**. What is
+measured is every asset the published section actually ships:
+
+- an svg, image, or font `import`ed directly in `Renderer.tsx` (or an island), and
+- an svg, image, or font `url()`-referenced from the section's own CSS or from a
+  package stylesheet its module graph pulls in — including a webfont `@font-face`s.
+
+The same asset referenced twice (from both a stylesheet and a component, say) counts
+once, not twice.
+
+The budget is **visible in `template-kit check`'s configuration and is not
+author-overridable**. A workspace cannot raise it, and there is no per-section exemption.
+
+## Reason
+
+An svg icon or a product photo a section imports, and a webfont a package's stylesheet
+pulls in, both ship to the same page load as the section's own code and CSS — they are
+not free just because they never appear in a byte-budget an author is used to watching.
+
+Fonts are the sharpest case. A `url()`-referenced webfont used to inline as part of the
+compiled stylesheet, which made a large font look like a CSS problem: trimming your own
+rules never fixed it, because the bytes were never your CSS to begin with. This rule
+separates that weight into its own budget — a font, an icon, or an image is measured as
+what it is, and the stylesheet budget ([`size-section-css`](size-section-css.md)) is left
+to measure only what it actually contains.
+
+## Fix
+
+Two moves, in order of how often they work:
+
+1. **Shrink or subset the asset.** A full variable font family, shipped for three
+   weights actually used, is the usual cause — subset it to the characters and weights
+   the section renders. An unoptimized PNG is the other common case — recompress it, or
+   switch to a format built for the content (`webp`/`avif` for photos, `svg` for icons).
+2. **Drop assets the section does not use.** A copied-in icon set or a leftover preview
+   image that never renders still ships its bytes — delete what the section does not
+   reference.
+
+### Before
+
+```tsx
+// sections/hero/Renderer.tsx
+import "brandfont/css"; // ← ships the package's full variable font family
+
+export default function Renderer() {
+  return <h1 style={{ fontFamily: "BrandFont" }}>Welcome home</h1>;
+}
+```
+
+### After
+
+```tsx
+// sections/hero/Renderer.tsx
+import heroIcon from "./assets/hero-icon.svg"; // ← a small, single-purpose asset
+
+export default function Renderer() {
+  // Uses a font the template's theme already declares (`--tr-font-<name>`),
+  // which costs nothing because it is already loaded — no package font import.
+  return (
+    <h1 className="tr-font-display">
+      <img src={heroIcon} alt="" /> Welcome home
+    </h1>
+  );
+}
+```
+
+## See also
+
+- [`size-section-css`](size-section-css.md) — the stylesheet budget this rule was split
+  out of; a `url()`-referenced font now counts here, not there.
+- [`size-renderer-bundle`](size-renderer-bundle.md) — the same idea applied to the
+  section's JavaScript.
+- [Theme and CSS](../theme-and-css.md) — the fonts and tokens the page already loads,
+  which cost you nothing to reuse.