@homepages/template-kit 0.1.0 → 0.2.0

package/docs/rules/unlayered-fence.md

@@ -0,0 +1,113 @@
+---
+purpose: The template-kit/unlayered-fence authoring rule — what it enforces, why, and how to fix it.
+status: living
+related: [INDEX.md, ../theme-and-css.md]
+updated: 2026-07-14
+---
+# template-kit/unlayered-fence
+
+> **This is not "you forgot to layer your CSS."** Everything is layered by default — the
+> build does it for you. This rule governs the *escape hatch* from layering: an
+> `/* unlayered: … */` fence must give a reason and must be closed.
+
+## Rule
+
+Your hand-written CSS is wrapped in a cascade layer by the build. You do not write
+`@layer` yourself, and there is nothing to forget.
+
+The **fence** opts a run of rules *out* of that wrapping, hoisting them above every layer:
+
+```css
+/* unlayered: <reason> */
+…rules that must beat every layer…
+/* endunlayered */
+```
+
+Two things are checked, both under this id:
+
+1. **Every opener carries a non-empty reason.** A bare `/* unlayered: */` is a violation.
+2. **Openers and closers balance.** An unterminated fence is a violation — it would swallow
+   the whole rest of the file out of the layer, which is never what anyone meant.
+
+## Reason
+
+Cascade layers have one rule that decides everything here: **an unlayered rule beats a
+layered one, regardless of specificity.** Not "usually" — always. That is what layers are
+for, and it is why the platform layers your CSS: inside the layer order (`theme, base,
+components, sections, template, utilities`) a Tailwind utility can always override a
+section's stylesheet, and a section's stylesheet can never leak past its layer to beat
+someone else's utility.
+
+So the hatch exists for exactly one situation: **a third-party library injects an unlayered
+rule into the document at runtime** — a map SDK writing a `<style>` element when it mounts,
+say — and that rule beats your layered override no matter how specific you make it. The
+only thing that can beat it is a rule that is also unlayered. Nothing else qualifies. If
+your rule merely needs to beat *your own* CSS, or a Tailwind utility, it belongs in a layer
+and you are reaching for the wrong tool.
+
+Which is why the reason is mandatory. A fence with no reason is a rule that outranks every
+layer on the page for reasons the next author cannot reconstruct — they cannot tell whether
+it is load-bearing or whether someone was fighting a specificity problem with a hammer. And
+an unbalanced fence silently promotes every rule below it, so a stylesheet that behaved
+yesterday starts beating the utilities that were supposed to override it.
+
+## Fix
+
+Close every fence with `/* endunlayered */`, and give every opener a reason that **names the
+runtime-injected rule it has to beat**. A short phrase is enough — it only has to be
+non-empty and specific about which rule it's beating, not a full sentence. If it does not
+have to beat one, delete the fence: layered is the default, and the default is right.
+
+The Before/After below both open with a `/* css-reason: … */` comment. That line has
+nothing to do with fencing — it satisfies a separate rule, [`css-reason`](css-reason.md),
+which every hand-written stylesheet must open with. It's shown here because real section
+CSS carries both; this rule's own grammar starts at `/* unlayered: */`.
+
+### Before
+
+```css
+/* css-reason: overrides the map SDK's injected control chrome. */
+
+/* unlayered: */
+.maplibregl-ctrl-group button {
+  background: var(--tr-color-surface);
+  border-radius: var(--tr-radius-sm);
+}
+
+.tr-map-legend {
+  padding: 0.5rem;
+}
+```
+
+Two violations at once: the reason is empty, and the fence is never closed — so
+`.tr-map-legend` is hoisted out of the layer too, where it now outranks every utility a
+future author might try to override it with.
+
+### After
+
+```css
+/* css-reason: overrides the map SDK's control chrome — the SDK builds those nodes after
+   hydration, so Tailwind's scanner never sees a class to compile. */
+
+/* unlayered: the map SDK injects its control styles as an unlayered <style> element at
+   runtime; a layered rule cannot beat it at any specificity. */
+.maplibregl-ctrl-group button {
+  background: var(--tr-color-surface);
+  border-radius: var(--tr-radius-sm);
+}
+/* endunlayered */
+
+/* Our own DOM — layered, like everything else. */
+.tr-map-legend {
+  padding: 0.5rem;
+}
+```
+
+The fence now wraps exactly the rules that need to escape, and `.tr-map-legend` is back in
+the layer where a utility can still override it.
+
+## See also
+
+- [Theme and CSS](../theme-and-css.md) — the layer order, and why utilities come last.
+- [`css-reason`](css-reason.md) — the comment every hand-written stylesheet opens with; the
+  fence reason is the same discipline, one level in.

package/docs/theme-and-css.md

@@ -1,13 +1,13 @@
 ---
-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]
+related: [primitives.md, schema-system.md, eslint.md, rules/INDEX.md]
 updated: 2026-07-14
 ---
 # 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
+`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`.
 
@@ -16,7 +16,7 @@ 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/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 |
 
 ## Import Tailwind exactly once
 
@@ -37,18 +37,47 @@ primitives (`Image`'s `bg-surface-alt`, `object-cover`, …) reach your compiled
 also overrides Tailwind's default exclusion of `node_modules`. You do not need to add a
 `@source` for the kit yourself.
 
+## 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).
+
 ## The page's stylesheets
 
 A published page loads, in order:
 
-1. **`base.css`** — layer order, reset, `.tr-section`, universal tokens.
-2. **Your theme's `:root` block** — the `--tr-*` values, produced by `compileThemeToCss`.
+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.
 
-`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:
+The layer order `base.css` declares is:
 
 ```css
 @layer theme, base, components, sections, template, utilities;
@@ -56,11 +85,28 @@ must be present on the page too. The layer order it declares is:
 
 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 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 the template's CSS bundle ships — deterministic (stable key
-order, palette keys sorted), so the same theme always content-hashes identically.
+`: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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homepages/template-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Authoring kit for HomePages marketing-section templates: schema system, contract primitives, theme tokens, and the template-kit CLI.",
   "license": "UNLICENSED",
   "type": "module",