refactor(docs): consume @uxfront/layer-docs package instead of local shared layer (#327)

* refactor(docs): consume @uxfront/docs-theme package instead of local shared layer

Re-point apps/docs from the local `apps/shared` Nuxt layer onto the
published `@uxfront/docs-theme@0.1.0` package. Branding stays entirely in
the app's own config: header/footer links move into app.config.ts, the
teal palette remains in main.css. Drop the 13 shell components that the
theme layer now provides, register `nuxt-og-image` locally (the theme
does not ship it), and add a `header.links` CustomAppConfig type.

apps/shared is retained (still extended by apps/app), so the layer is
reduced to brand-only overrides rather than removed.

Workaround for a packaging bug in @uxfront/docs-theme@0.1.0: its `files`
array omits `i18n/`, but `app/composables/useDocusI18n.ts` statically
imports `../../i18n/locales/en.json`, breaking the build. Kept local
`useDocusI18n.ts` + `AppHeader.vue` (explicit relative import) and a
`useDocusI18nOverride` module (auto-import consumers) as a shim until the
package ships 0.1.1 with i18n included.

Build parity verified: `nuxt generate` prerenders 638 routes (== baseline),
identical HTML route set, teal palette compiled.

* fix(docs): restore Tailwind entry so brand @theme compiles to :root vars

The re-point removed the `@import` that made `apps/docs/.../main.css` a
Tailwind entry. A `@theme` block only compiles into real `:root` custom
properties when it lives in a Tailwind-processed file; without the import
the `@theme static { --color-teal … }` block was emitted verbatim and
browsers discard the unknown at-rule. Result: `--color-teal`/`--ui-primary`
resolved to nothing and every `*-primary` utility fell back to
black/transparent site-wide (P1, all routes).

Re-add `@import "tailwindcss";` plus consumer-scoped `@source` lines (the
theme package's own `@source` paths are package-relative and never see the
consumer's content/app.config).

Verified on the emitted entry CSS: literal `@theme` count 0 (was 1),
`--color-teal:#318fa0` compiled under `:host,:root`,
`:root{--ui-primary:var(--color-teal)}`, `.text-primary` → teal.

* test(docs): guard brand @theme is a Tailwind entry (regression for #327)

Adds a source-invariant vitest for apps/docs/app/assets/css/main.css: the
brand palette file must import tailwindcss (before its @theme block) so the
teal @theme compiles into real :root custom properties. Without it the block
ships verbatim and browsers discard it, dropping --color-teal/--ui-primary and
every *-primary utility site-wide (the P1 regressed by the @uxfront/docs-theme
re-point, fixed in 56b8d7d).

Fails on the pre-fix file, passes on the fix. Also wires apps/docs into
`turbo run test` via a `test` script + vitest config.

* fix(docs): type theme header/footer app config surface

The consumed @uxfront/docs-theme@0.1.0 reads appConfig.header.*,
footer.credits and footer.links in its layer components but declares
none of them, so the re-point onto the published package regressed
`nuxt typecheck` (green on main only via the locally-typed apps/shared
layer). Declare the brand config surface with optional shapes so the
keys are not forced onto AppConfigInput (which extends CustomAppConfig)
— a non-optional key would break the package's own defineAppConfig.

Clears the footer.* and AppConfigInput errors and removes the
AppConfigInput regression introduced by the prior non-optional
declaration. header.links remains unresolvable consumer-side: the theme
seeds `header` into inlineConfig, so the resolved AppConfig returns
{ title, logo } and the generated MergedAppConfig ignores this
augmentation for that key. Tracked for the theme 0.1.1 typing fix.

* fix(docs): consume @uxfront/docs-theme@0.1.1 and drop redundant config shim

0.1.1 ships the previously-missing `i18n/` and `server/` directories and
types the theme's `footer` / app-config surface, so the local
`app/types/app-config.ts` augmentation that patched those errors is no
longer needed — removed it. Verified against a clean typecheck: with the
shim gone, `footer.*` and the AppConfigInput error stay resolved.

Build parity holds: `nuxt generate` prerenders all 659 routes; the brand
palette is app-local (main.css) and unaffected by the bump.

One typecheck error remains and is not fixable in this app:
AppHeaderCTA.vue reads `appConfig.header.links`, but the theme's config
module seeds a partial `header` into inlineConfig, so defu's *type* drops
the array-valued `links` during the deep object merge (footer survives
only because it is taken wholesale, not seeded). Needs a theme-side fix.

* refactor(docs): re-point docs layer to renamed @uxfront/layer-docs

The theme package was renamed @uxfront/docs-theme → @uxfront/layer-docs
out-of-band. Propagate the rename across the docs app: dependency in
package.json (pinned ^0.1.0, the only published version under the new name),
the nuxt.config `extends` entry, and the layer-name references in config,
CSS, and test comments. layer-docs@0.1.0 already carries the header.links
typecheck fix, so nuxt typecheck is green and generate parity holds (659
routes).

Author: alexgrozav

.github/workflows/ci.yml

@@ -92,6 +92,9 @@ jobs:
               env:
                   NODE_ENV: production
 
+            - name: Check compiled CSS (duplicate-utility guard)
+              run: pnpm --filter '@styleframe/docs' test:build
+
             - name: Upload docs build
               uses: actions/upload-artifact@v4
               with:

apps/docs/app/app.config.ts

@@ -1,8 +1,8 @@
 export default defineAppConfig({
 	/**
-	 * Styleframe branding for the docs site. The `apps/shared` layer ships
-	 * neutral defaults; these values are merged over them by Nuxt's `defu`
-	 * layer merge (consumer wins).
+	 * Styleframe branding for the docs site. The `@uxfront/layer-docs` layer
+	 * ships neutral defaults; these values are merged over them by Nuxt's
+	 * `defu` layer merge (consumer wins).
 	 *
 	 * @docs https://www.docus.dev/concepts/configuration#global-configuration
 	 */
@@ -22,6 +22,23 @@ export default defineAppConfig({
 			light: "/logotype-light.svg",
 			dark: "/logotype-dark.svg",
 		},
+		// Header CTA nav — brand data read by the theme's AppHeaderCTA.
+		links: [
+			{
+				label: "Docs",
+				to: "/docs/getting-started/introduction",
+				activeMatch: "/docs",
+			},
+			{
+				label: "Changelog",
+				to: "/changelog",
+				activeMatch: "/changelog",
+			},
+			{
+				label: "Log in",
+				to: "https://app.styleframe.dev",
+			},
+		],
 	},
 	/**
 	 * @docs https://www.docus.dev/concepts/configuration#socials-links
@@ -39,6 +56,21 @@ export default defineAppConfig({
 	},
 	footer: {
 		credits: `Copyright © ${new Date().getFullYear()} styleframe`,
+		// Footer legal links read by the theme's AppFooterCenter.
+		links: [
+			{
+				label: "Privacy",
+				to: "/privacy",
+			},
+			{
+				label: "Terms",
+				to: "/terms",
+			},
+			{
+				label: "License",
+				to: "/license",
+			},
+		],
 	},
 	toc: {
 		// Title of the main table of contents
@@ -83,7 +115,7 @@ export default defineAppConfig({
 	},
 
 	// Palette only — the Nuxt UI Pro component slot overrides are neutral shell
-	// defaults inherited from the `apps/shared` layer (merged under this by defu).
+	// defaults inherited from the `@uxfront/layer-docs` layer (merged under this by defu).
 	ui: {
 		colors: {
 			primary: "teal",

apps/docs/app/assets/css/main.css

@@ -1,9 +1,35 @@
-@import "../../../../shared/app/assets/css/main.css";
+/*
+ * Single Tailwind entry for the docs app.
+ *
+ * The styleframe brand `@theme` below (the teal scale + `--ui-primary` mapping)
+ * is only compiled into real `:root` custom properties and utilities when it
+ * lives inside a Tailwind pass. Rather than starting a second pass with its own
+ * `@import "tailwindcss"`, this file imports the layer's neutral base — which
+ * owns the single `@import "tailwindcss"` / `@import "@nuxt/ui"` — so the brand
+ * theme compiles in that SAME pass.
+ *
+ * The layer also registers its `main.css` as a standalone CSS entry; that
+ * registration is stripped in `nuxt.config.ts` (see the `modules:done` hook).
+ * Two Tailwind entries would each re-emit every base utility, and the second
+ * copy — landing after the first pass's responsive rules at equal specificity —
+ * wins by source order and silently kills every `sm:`/`lg:` variant (h1 renders
+ * 48px instead of 72px, layouts collapse). One entry, one emission, correct
+ * cascade.
+ */
+@import "@uxfront/layer-docs/app/assets/css/main.css";
+
+/*
+ * `@source` re-scans this app's own content + config for utility classes: the
+ * layer's `@source` paths are package-relative (they resolve inside
+ * node_modules), so they never see the consumer's markdown or app.config.
+ */
+@source "../../../content/**/*";
+@source "../../app.config.ts";
 
 /*
- * Styleframe brand palette. The shared layer ships neutral (palette-free)
- * styling; this consumer supplies the teal scale and maps it onto Nuxt UI's
- * `--ui-primary`. Pairs with `ui.colors.primary: "teal"` in app.config.ts.
+ * Styleframe brand palette. This consumer supplies the teal scale and maps it
+ * onto Nuxt UI's `--ui-primary`. Pairs with `ui.colors.primary: "teal"` in
+ * app.config.ts.
  */
 @theme static {
 	--color-teal: hsl(189, 53%, 41%);