@uxfront/layer-docs 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @uxfront/layer-docs
 
+## 0.3.0
+
+### Minor Changes
+
+- 751810d: Stop registering the layer's own `main.css`, and ship the brand-palette guards consumers were each expected to write themselves.
+
+  **Breaking for any consumer that does not already register its own CSS entry.** The layer registered `app/assets/css/main.css` in `css` while every consumer also imported that same base from its brand CSS — because a brand `@theme` only compiles into real `:root` custom properties when it lives inside a Tailwind pass, which means importing the base rather than sitting beside it. Two entries, two Tailwind passes, and a byte-for-byte duplicate of every base utility in the shipped stylesheet: **+212 KB raw / +26.7 KB gzip (+94%)** on inkline's render-blocking `entry.css`, on every page, for every visitor (UXF-118).
+
+  The layer no longer registers it. Consumers register exactly one CSS entry of their own, whose first line imports the layer base — which is what all three consumers were already doing, one of them via a `modules:done` hook that un-registered what the layer had just registered. That hook can now be deleted.
+
+  **Migration.** If your app already has `css: ["./app/assets/css/main.css"]` pointing at a file that starts with `@import "@uxfront/layer-docs/app/assets/css/main.css"`, nothing changes except that your stylesheet halves; drop any hook that stripped the layer's entry. If it does not, add both — see README § Styling. There is no silent middle state: without a CSS entry the app ships no Tailwind utilities at all.
+
+  **What the duplication actually cost.** Payload, not layout. The duplicate pass measured on inkline was a complete superset of the first and was emitted wholly after it, so the last `sm:`/`lg:` variant still landed after the last conflicting base and won by source order — computed-style A/B across 4 pages × 4 viewports found zero rendering difference. That rescue was incidental rather than designed, which is why the cause is fixed rather than the symptom.
+
+  **New: `@uxfront/layer-docs/test`.** The two guards that would have caught this before ship, now parameterised by brand scale instead of copy-pasted per repo. `describeBrandPaletteCss` asserts, without a build, that your CSS entry imports the layer base before its `@theme` and defines the scale it maps onto `--ui-primary`. `describeSingleTailwindPass` reads the built stylesheet and asserts every base utility is emitted **exactly once** — catching a duplicate pass and a CSS entry that never reached the bundle with the same assertion. `vitest` is an optional peer dependency, needed only for these.
+
+  Also fixed: three code comments claimed the second pass "kills every `sm:`/`lg:` responsive variant". It does not, in the equal-superset case measured; the guards now describe the duplicate payload they actually guard.
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -60,6 +60,80 @@ That renders `uxd by UXFront` — the wordmark still links home, `by` is plain
 text, and `UXFront` links out. Omit `attribution` (or leave `label` empty) to
 render the wordmark alone.
 
+## Styling
+
+**The consumer owns the single Tailwind entry.** The layer ships a palette-free
+Tailwind base at `@uxfront/layer-docs/app/assets/css/main.css` and deliberately
+does not register it itself. A brand `@theme` only compiles into real `:root`
+custom properties when it lives inside a Tailwind pass, so your CSS file has to
+_import_ the layer base rather than sit beside it as a second entry — two
+entries each re-emit every base utility into the shipped stylesheet.
+
+Register one CSS entry:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ["@uxfront/layer-docs"],
+  css: ["./app/assets/css/main.css"],
+});
+```
+
+whose first line imports the layer base, followed by your palette:
+
+```css
+/* app/assets/css/main.css */
+@import "@uxfront/layer-docs/app/assets/css/main.css";
+
+/* The layer's own `@source` paths are package-relative (they resolve inside
+   node_modules), so re-scan your content and config for utility classes. */
+@source "../../../content/**/*";
+@source "../../app.config.ts";
+
+@theme static {
+  --color-teal: hsl(189, 53%, 41%);
+  /* … the rest of the scale … */
+}
+
+:root {
+  --ui-primary: var(--color-teal);
+}
+```
+
+The scale name must match `ui.colors.primary` in your `app.config.ts` for Nuxt
+UI to resolve component variants onto it.
+
+### Guardrail tests
+
+Both halves of that contract fail silently, so the layer ships the guards.
+`vitest` is an optional peer dependency, needed only for these.
+
+```ts
+// test/brand-palette-css.test.ts — source-level, no build required
+import { describeBrandPaletteCss } from "@uxfront/layer-docs/test";
+
+describeBrandPaletteCss({
+  entry: new URL("../app/assets/css/main.css", import.meta.url),
+  scale: "teal",
+});
+```
+
+```ts
+// test/brand-palette-compiled.build.test.ts — requires a prior `nuxt build`
+import { describeSingleTailwindPass } from "@uxfront/layer-docs/test";
+
+describeSingleTailwindPass({
+  output: new URL("../.output/public/_nuxt", import.meta.url),
+  scale: "teal",
+});
+```
+
+The first asserts your CSS entry is a Tailwind entry and defines the palette.
+The second reads the built stylesheet and asserts every base utility is emitted
+**exactly once** — catching both a duplicate Tailwind pass (double payload) and
+a CSS entry that never reached the bundle (no base utilities at all). Run it in
+whichever CI job already builds the app; it needs `.output/` on disk.
+
 ## Compatibility
 
 Pinned to the Nuxt 4 documentation stack (Nuxt 4.4, Nuxt UI 4.8, Content 3.14,

package/nuxt.config.ts

@@ -14,12 +14,31 @@ const { resolve } = createResolver(import.meta.url);
  * locale site "just works". A consumer that wants localisation registers the
  * module itself; `modules/config` + `useDocusI18n` pick it up automatically.
  *
+ * ## Styling: the consumer owns the single Tailwind entry
+ *
+ * This layer deliberately does NOT register `app/assets/css/main.css` in `css`.
+ * Its base is palette-free, so a consumer's brand `@theme` only compiles if it
+ * lives inside the same Tailwind pass — which means the consumer's CSS file has
+ * to *import* this base, not sit beside it. Registering it here as well gave
+ * every consumer two Tailwind entries and a byte-for-byte duplicate of every
+ * base utility in the shipped stylesheet (+26.7 KB gzip on inkline, UXF-118),
+ * and left each consumer to un-register what the layer had just registered.
+ *
+ * Consumers therefore register exactly one CSS entry, their own:
+ *
+ * ```ts
+ * // nuxt.config.ts
+ * css: ["./app/assets/css/main.css"],
+ * ```
+ *
+ * whose first line imports this base, followed by the brand `@theme`. Both
+ * halves are guarded by `@uxfront/layer-docs/test`; see README § Styling.
+ *
  * https://nuxt.com/docs/getting-started/layers
  */
 export default defineNuxtConfig({
   compatibilityDate: "2025-07-22",
   telemetry: false,
-  css: [resolve("./app/assets/css/main.css")],
   // Expose `app/constants/` (DOCS_SECTIONS, findDocsSectionBySlug) as
   // auto-imports. The layer ships a neutral empty default; a consumer's own
   // `app/constants/` overrides it via auto-import dir precedence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxfront/layer-docs",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Neutral, brandable Nuxt-layer documentation theme. Consumers extend it and supply their own branding, content and section topology.",
   "keywords": [
     "docs",
@@ -23,6 +23,7 @@
     "i18n",
     "modules",
     "server",
+    "test",
     "utils",
     "nuxt.config.ts",
     "nuxt.schema.ts",
@@ -43,6 +44,10 @@
       "types": "./utils/content.ts",
       "import": "./utils/content.ts"
     },
+    "./test": {
+      "types": "./test/brand-palette.ts",
+      "import": "./test/brand-palette.ts"
+    },
     "./app/assets/css/main.css": "./app/assets/css/main.css",
     "./package.json": "./package.json"
   },
@@ -60,7 +65,8 @@
     "ufo": "^1.6.4"
   },
   "devDependencies": {
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "@nuxt/content": "^3.14.0",
@@ -77,6 +83,7 @@
     "posthog-js": "^1.386.6",
     "tailwindcss": "^4.3.1",
     "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
     "vue": "^3.5.38"
   },
   "peerDependenciesMeta": {
@@ -91,6 +98,9 @@
     },
     "typescript": {
       "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
   },
   "scripts": {

package/test/brand-palette.ts

@@ -0,0 +1,224 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Shared test preset for consumers of `@uxfront/layer-docs`.
+ *
+ * The layer ships a palette-free Tailwind base and expects the consumer to own
+ * the single Tailwind entry: one CSS file that imports the layer's base and
+ * then declares the brand `@theme`. Two invariants make that arrangement work,
+ * and both fail silently, so both get a guard here rather than a comment in
+ * three repos:
+ *
+ * 1. **The consumer's CSS entry is a Tailwind entry.** A `@theme` block only
+ *    compiles into real `:root` custom properties when the file it lives in is
+ *    part of a Tailwind pass. If it stops being one, the block ships to the
+ *    browser verbatim, browsers discard the unknown at-rule, and every
+ *    `*-primary` utility falls back to black/transparent site-wide.
+ *    Guarded by {@link describeBrandPaletteCss} — source-level, no build.
+ *
+ * 2. **Exactly one Tailwind pass reaches the bundle.** A second entry (a bare
+ *    `@import "tailwindcss"` in the consumer, or a layer that registers its own
+ *    base in `css:` alongside the consumer's) re-emits every base utility a
+ *    second time. Guarded by {@link describeSingleTailwindPass} — reads the
+ *    compiled output, so it needs a prior `nuxt build`.
+ *
+ * @example
+ * ```ts
+ * // apps/docs/test/brand-palette-css.test.ts
+ * import { describeBrandPaletteCss } from "@uxfront/layer-docs/test";
+ *
+ * describeBrandPaletteCss({
+ *   entry: new URL("../app/assets/css/main.css", import.meta.url),
+ *   scale: "teal",
+ * });
+ * ```
+ */
+
+/** Resolve a `file:` URL or a plain path to an absolute filesystem path. */
+function toPath(target: string | URL): string {
+  return typeof target === "string" ? target : fileURLToPath(target);
+}
+
+export interface BrandPaletteCssOptions {
+  /**
+   * The consumer's CSS entry — the file registered in `nuxt.config.ts`'s
+   * `css: []`. Pass `new URL("../app/assets/css/main.css", import.meta.url)`.
+   */
+  entry: string | URL;
+  /**
+   * Tailwind colour scale the brand palette defines, without the `--color-`
+   * prefix (`"teal"`, `"violet"`, `"purple"`). Must match `ui.colors.primary`
+   * in the consumer's `app.config.ts`.
+   */
+  scale: string;
+}
+
+/**
+ * Source-level guard for invariant 1: the brand palette compiles at all.
+ *
+ * Cheap — reads one file, runs in the default unit-test job, and catches the
+ * regression without a build. It cannot see invariant 2; that needs
+ * {@link describeSingleTailwindPass}.
+ */
+export function describeBrandPaletteCss(options: BrandPaletteCssOptions): void {
+  const { entry, scale } = options;
+
+  // A Tailwind pass reached via the layer's base CSS, which owns the single
+  // `@import "tailwindcss"`. Importing `tailwindcss` directly here would also
+  // make the file an entry, but it would open a SECOND pass — the exact
+  // regression invariant 2 guards — so only the layer import is accepted.
+  const LAYER_BASE_IMPORT = /@import\s+["']@uxfront\/layer-docs\/[^"']*main\.css["']/;
+
+  describe(`brand palette CSS entrypoint (${scale})`, () => {
+    const css = readFileSync(toPath(entry), "utf8");
+
+    it("imports the layer's base CSS so it is part of the single Tailwind pass", () => {
+      expect(css).toMatch(LAYER_BASE_IMPORT);
+    });
+
+    it("imports the layer base before the first @theme block", () => {
+      const importIndex = css.search(LAYER_BASE_IMPORT);
+      // Match the block opener specifically, not the `@theme` word in a
+      // leading docblock comment.
+      const themeIndex = css.search(/@theme\s+static\s*\{/);
+      expect(importIndex).toBeGreaterThanOrEqual(0);
+      expect(themeIndex).toBeGreaterThanOrEqual(0);
+      expect(importIndex).toBeLessThan(themeIndex);
+    });
+
+    it(`defines the ${scale} scale and maps it onto --ui-primary`, () => {
+      expect(css).toMatch(new RegExp(`@theme\\s+static\\s*\\{[\\s\\S]*--color-${scale}\\s*:`));
+      expect(css).toMatch(new RegExp(`--ui-primary\\s*:\\s*var\\(\\s*--color-${scale}\\s*\\)`));
+    });
+  });
+}
+
+export interface SingleTailwindPassOptions {
+  /**
+   * Directory holding the built assets — usually
+   * `new URL("../.output/public/_nuxt", import.meta.url)`.
+   */
+  output: string | URL;
+  /**
+   * Tailwind colour scale the brand palette defines, without the `--color-`
+   * prefix. Asserts the palette survived into the compiled bundle.
+   */
+  scale: string;
+  /**
+   * Extra base utilities to assert on, appended to {@link BASE_UTILITIES}.
+   * Each entry is a full class selector, e.g. `".text-5xl"`.
+   */
+  utilities?: string[];
+}
+
+/**
+ * Ubiquitous unwrapped utilities the layer and Nuxt UI always emit. In a
+ * single-pass build each appears exactly once; a second pass makes them 2, and
+ * a bundle the layer base never reached makes them 0.
+ */
+const BASE_UTILITIES = [".relative", ".absolute", ".flex", ".grid", ".hidden", ".block"];
+
+/**
+ * Responsive utilities emitted inside `@media` blocks. Asserting these as well
+ * as {@link BASE_UTILITIES} is not redundancy — the two halves duplicate
+ * independently, and a base-only probe reports a duplicating build as clean.
+ *
+ * Measured on the same layer, same config, differing only in the Vite build
+ * used by `@nuxt/vite-builder`:
+ *
+ * | build            | `.flex` | `.lg\:hidden` |
+ * |------------------|---------|---------------|
+ * | rollup (vite 7)  | 2       | 2             |
+ * | rolldown         | 1       | **2**         |
+ * | single pass      | 1       | 1             |
+ *
+ * Rolldown collapses the duplicated top-level rules and leaves the `@media`-
+ * wrapped ones — so the consumer on rolldown still shipped ~63 KB of duplicate
+ * responsive CSS while every base-utility count read 1.
+ *
+ * All three are emitted by this layer's own components (`AppHeader`,
+ * `AppSubHeader`, `DocsAsideRightBottom`), so every consumer of the layer has
+ * them regardless of its own markup.
+ */
+const VARIANT_UTILITIES = [".lg\\:hidden", ".lg\\:block", ".max-lg\\:hidden"];
+
+/**
+ * Compiled-output guard for invariant 2: exactly one Tailwind pass in the
+ * shipped stylesheet.
+ *
+ * **What this guards is payload, not layout.** A second pass emits a
+ * byte-for-byte duplicate of the stylesheet — measured at +212 KB raw /
+ * +26.7 KB gzip (+94%) on a consumer's render-blocking `entry.css`, on every
+ * page for every visitor (UXF-118). It does *not*, on the evidence gathered
+ * there, break the cascade: the duplicate pass observed was a complete superset
+ * of the first and emitted wholly after it, so the last `sm:`/`lg:` variant
+ * still landed after the last conflicting base and won by source order.
+ * Computed-style A/B across 4 pages × 4 viewports found zero rendering
+ * difference.
+ *
+ * That rescue is incidental, not designed — a non-superset second pass, or a
+ * different emission order, and the cascade does break. But the guard should
+ * describe what it actually measures, so nobody re-derives a rendering
+ * emergency from a payload regression.
+ *
+ * Two deliberate choices in what it asserts:
+ *
+ * - **Both unwrapped and `@media`-wrapped utilities** ({@link BASE_UTILITIES}
+ *   and {@link VARIANT_UTILITIES}). They duplicate independently; a base-only
+ *   probe reported a duplicating build as clean.
+ * - **`=== 1`, not `<= 1`.** The same assertion then catches the opposite
+ *   failure — a consumer that never registered a CSS entry importing the layer
+ *   base, and so ships no utilities at all.
+ *
+ * Requires a prior `nuxt build` / `nuxt generate`. Keep these in
+ * `*.build.test.ts` files excluded from the default unit run.
+ */
+export function describeSingleTailwindPass(options: SingleTailwindPassOptions): void {
+  const { output, scale, utilities = [] } = options;
+
+  describe("compiled CSS: single Tailwind pass", () => {
+    const css = readEntryCss(toPath(output));
+    const assertedUtilities = [...BASE_UTILITIES, ...VARIANT_UTILITIES, ...utilities];
+
+    it("emits each utility exactly once (no duplicate Tailwind pass, and the layer base did reach the bundle)", () => {
+      const counts = Object.fromEntries(assertedUtilities.map((u) => [u, countUtility(css, u)]));
+      const expected = Object.fromEntries(assertedUtilities.map((u) => [u, 1]));
+      expect(counts).toEqual(expected);
+    });
+
+    it(`compiles the ${scale} scale and the --ui-primary mapping into the bundle`, () => {
+      expect(css).toMatch(new RegExp(`--color-${scale}\\s*:`));
+      expect(css).toMatch(new RegExp(`--ui-primary\\s*:\\s*var\\(\\s*--color-${scale}\\s*\\)`));
+    });
+  });
+}
+
+/** Read the built `entry.*.css`, comments stripped so counts reflect rules only. */
+function readEntryCss(outputDir: string): string {
+  if (!existsSync(outputDir)) {
+    throw new Error(
+      `Compiled output not found at ${outputDir}. Build the app first ` +
+        `(nuxt build) before running the compiled-output guard.`,
+    );
+  }
+  const entries = readdirSync(outputDir)
+    .filter((file) => /^entry\..*\.css$/.test(file))
+    .sort();
+  if (entries.length === 0) {
+    throw new Error(`No entry.*.css found in ${outputDir}. Build the app first (nuxt build).`);
+  }
+  return readFileSync(`${outputDir}/${entries.at(-1)}`, "utf8").replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+/** Count how many times a utility is emitted as its own class selector. */
+function countUtility(css: string, utility: string): number {
+  const escaped = utility.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // A leading `.` immediately followed by the class name, not part of a longer
+  // variant selector such as `.sm\:text-5xl` (there the class is preceded by an
+  // escaped colon, so `.text-5xl` never appears) and not a prefix of a longer
+  // utility such as `.flex-col`.
+  const pattern = new RegExp(`(?<![\\w\\\\:-])${escaped}(?![\\w-])`, "g");
+  return (css.match(pattern) ?? []).length;
+}