@homepages/template-kit 0.1.0 → 0.3.0

package/docs/theme-and-css.md

@@ -1,119 +1,231 @@
 ---
-purpose: The kit's two CSS entries, the Tailwind import rule, the TokenTheme a template supplies, and the breakpoint ladder.
+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]
-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, 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 reset, document defaults, `.tr-section`, and the universal spacing / 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:
 
-`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.
+- **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.
 
-## The page's stylesheets
+`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.
 
-A published page loads, in order:
+## `TokenTheme` — your template's design system
 
-1. **`base.css`** — layer order, reset, `.tr-section`, universal tokens.
-2. **Your theme's `:root` block** — the `--tr-*` values, produced by `compileThemeToCss`.
-3. **Your compiled Tailwind bundle** — `@import "tailwindcss"` + `styles.css` + your
-   section markup's utilities.
+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).
 
-`base.css` reads `--tr-color-ink`, `--tr-color-background`, `--tr-font-sans`,
-`--tr-text-base` and `--tr-header-height` for the document defaults, so the theme block
-must be present on the page too. The layer order it declares is:
+```ts
+import type { TokenTheme } from "@homepages/template-kit";
 
-```css
-@layer theme, base, components, sections, template, utilities;
+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" },
+};
 ```
 
-Utilities come last, so a Tailwind utility always beats the reset's element defaults.
+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.)
 
-## `TokenTheme` — your template's values
+### Namespaces and the utilities they produce
 
-A template's `theme.ts` exports a `TokenTheme`. `compileThemeToCss` turns it into the
-`:root { --tr-*: … }` block the template's CSS bundle ships — deterministic (stable key
-order, palette keys sorted), so the same theme always content-hashes identically.
+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.
 
-```ts
-import { compileThemeToCss, type TokenTheme } from "@homepages/template-kit";
+| 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)` |
 
-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" },
-};
+`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.
 
-const css = compileThemeToCss(theme);
+### 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`
+
+`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
 ```
 
-`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.
+`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
+
+A section's compiled CSS layer is assembled from two sources, both automatic — you
+never write an import to make either happen:
+
+1. **Hand-written CSS, collected by path.** Every `.css` file inside the section's
+   folder — `styles.css` and any other stylesheet nested under it — is picked up by
+   walking the folder, wherever it sits, and concatenated into `@layer sections`. A
+   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
+   (`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.
+
+Two constraints follow directly, and both are enforced by lint:
+
+- **Don't re-import your own stylesheet.** It is already collected by path —
+  importing it again from a `.ts`/`.tsx` file only double-emits it, and can smuggle a
+  stray `@layer` statement into a nested layer.
+  See [`no-css-import-from-render-path`](rules/no-css-import-from-render-path.md).
+- **`@import` never works inside hand-written CSS, package or local.** An `@import`
+  landing inside `@layer sections` / `@layer template` is invalid CSS, and the
+  browser drops it silently rather than erroring — the package's styling is simply
+  missing from the published page. Reach a package's stylesheet from code instead.
+  See [`no-bare-css-import`](rules/no-bare-css-import.md).
 
-### Color roles
+## The page's stylesheets
 
-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:
+A published page loads, in order:
 
-| 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.
+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:
+
+```css
+@layer theme, base, components, sections, template, utilities;
+```
+
+Utilities come last, so a Tailwind utility always beats the reset's element defaults.
+
+### base.css requires a Tailwind entry
+
+`base.css` does **not** ship a reset. Your entry's `@import "tailwindcss"` brings
+Tailwind's preflight, and preflight is the reset — box-sizing, margins, list-style, the
+button and anchor resets. `base.css` carries only the three declarations preflight does
+not make: `font-smoothing`, `button { cursor: pointer }` (Tailwind v4 leaves buttons at
+`cursor: default`), and `svg { max-width: 100% }` (preflight caps only `img` and
+`video`).
+
+Ship `base.css` without a Tailwind entry on the page and you get an unreset page.
+
+`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
 
@@ -145,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homepages/template-kit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Authoring kit for HomePages marketing-section templates: schema system, contract primitives, theme tokens, and the template-kit CLI.",
   "license": "UNLICENSED",
   "type": "module",
@@ -58,6 +58,7 @@
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
+    "pretest": "node test/link-fixture-workspace.mjs",
     "test": "node --import tsx --test 'src/**/*.test.ts' 'src/**/*.test.tsx'",
     "lint:pkg": "publint --strict && attw --pack . --profile esm-only --exclude-entrypoints styles.css base.css",
     "verify:consumer": "node scripts/verify-consumer.mjs",
@@ -67,15 +68,9 @@
     "release": "changeset publish"
   },
   "peerDependencies": {
-    "eslint": "^9.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
-  "peerDependenciesMeta": {
-    "eslint": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@changesets/cli": "^2.29.8",
@@ -85,6 +80,7 @@
     "@types/node": "^20.17.10",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@typescript-eslint/parser": "^8.60.1",
     "esbuild": "^0.28.1",
     "eslint": "^9.39.4",
     "jsdom": "^26.1.0",
@@ -98,7 +94,6 @@
     "typescript-eslint": "^8.60.1"
   },
   "dependencies": {
-    "@typescript-eslint/parser": "^8.60.1",
-    "zod": "^3.23.8"
+    "zod": "^4.4.3"
   }
 }

package/tsconfig.json

@@ -3,5 +3,5 @@
   "compilerOptions": {
     "noEmit": true
   },
-  "exclude": ["node_modules", "dist", ".tmp-consumer"]
+  "exclude": ["node_modules", "dist", ".tmp-consumer", "test/fixtures"]
 }