@plutocms/core 0.44.1 → 0.46.0

package/CHANGELOG.md

@@ -1,6 +1,24 @@
 # Changelog
 
 
+## [0.46.0](https://github.com/plutocms/pluto/compare/v0.45.0...v0.46.0) (2026-11-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* an app with no Tailwind entry no longer gets one from Pluto. A site whose pages use Tailwind or Nuxt UI adds its own entry.
+
+### Features
+
+* the admin has its own Tailwind build, and a site needs no Tailwind ([#343](https://github.com/plutocms/pluto/issues/343)) ([6d6ae4a](https://github.com/plutocms/pluto/commit/6d6ae4a59f14289abf2da421d028dba920cacd76))
+
+## [0.45.0](https://github.com/plutocms/pluto/compare/v0.44.1...v0.45.0) (2026-11-01)
+
+
+### Features
+
+* in production, the admin shows a not-configured page when no auth driver is registered ([#346](https://github.com/plutocms/pluto/issues/346)) ([6f49cb8](https://github.com/plutocms/pluto/commit/6f49cb814d1d3614d8b3b7b92722081ba82549ae))
+
 ## [0.44.1](https://github.com/plutocms/pluto/compare/v0.44.0...v0.44.1) (2026-11-01)
 
 

package/FEATURES.md

@@ -66,9 +66,12 @@ policies shared by every project here.
   @.claude/skills/i18n/SKILL.md
 - Settings pages: `/admin/settings` is a section with tabs. A layer adds a tab with a `settingsPages` entry and a page file at `pages/admin/settings/<x>.vue`. The tabs show with 2 or more pages, the sidebar and the command palette list them, and a tab can need a capability (`'*'` is admin only). The capability picker groups by layer. @.claude/skills/extension-registry/SKILL.md
 - Mail: a mail driver contract (`sendPlutoMail`, `registerMailDriver`) with Resend, dev (console and Mailpit) and none drivers, plain-TypeScript email templates (test, invite) translated by a server translator, and a guided `Settings > Email` page (admin only) that checks the key, adds and verifies a domain, and tests the setup. Secrets stay in the environment. @.claude/skills/mail/SKILL.md
-- Single Tailwind build: the app owns the only Tailwind build. The pluto-css module generates
-  `#build/pluto.css` from each layer's `pluto-layer.css` (the app imports it as `@plutocms/css`), adds a fallback entry, and warns
-  about a wrong CSS setup. @.claude/skills/single-tailwind-build/SKILL.md
+- Admin and site CSS: the admin has its own Tailwind build, scoped to the admin and loaded only
+  with the admin UI, so a site needs no Tailwind and a site's theme does not reach the admin. A
+  Tailwind site owns its one build. The pluto-css module generates `#build/pluto.css` from each
+  layer's `pluto-layer.css` (imported as `@plutocms/css` by the admin build and by a Tailwind
+  site), and warns about a Tailwind build in a layer or more than one.
+  @.claude/skills/single-tailwind-build/SKILL.md
 - Git CMS: a standalone CMS with Markdown posts in a Git repo. Out of the box it publishes to the
   local Git repo (dev only: each save is a local commit, `commit.local`); a GitHub App publishes
   from a deployed site. The module is `pluto-github` (config
@@ -101,7 +104,7 @@ policies shared by every project here.
   `defineAsyncComponent`, shows a skeleton per field, widget and settings panel while a chunk
   loads, and warns in dev about a registered component that is not async.
   @.claude/skills/extension-registry/SKILL.md
-- Admin shell: core owns the `/admin` parent route, the `/admin/login` page, the route guard, the admin banners, the navbar and the user menu. A backend layer registers an auth driver, account menu items, site info and link actions. The admin is for staff only: a signed-in user with no capability goes to `/admin/no-access`. The bar shows on `/admin/**` for staff, and on public pages for staff only. A route hides the bar with the page meta `plutoAdminBar: false`, and `isPlutoPreviewPath` marks the preview path. The bar height is the token `--pluto-admin-bar-height`, and `<html>` gets `data-pluto-admin-bar` while the bar shows. A hint cookie puts the bar frame in the server HTML of a public page for staff (the actions and the user menu load after the mount). Content types with `adminBar` get "New <type>" and "Edit <type>" buttons (`usePlutoEditLink`). With two or more types, one "New" menu lists them, grouped by `navGroup`. A `navGroup` also puts related types under one sidebar item (registry bucket `navGroups`, core group `pages`). @.claude/skills/admin-shell/SKILL.md
+- Admin shell: core owns the `/admin` parent route, the `/admin/login` page, the route guard, the admin banners, the navbar and the user menu. A backend layer registers an auth driver, account menu items, site info and link actions. The admin is for staff only: a signed-in user with no capability goes to `/admin/no-access`. In production, an app with no auth driver (the backend is missing or did not load) sends every admin path to `/admin/not-configured`; in dev the admin opens. The bar shows on `/admin/**` for staff, and on public pages for staff only. A route hides the bar with the page meta `plutoAdminBar: false`, and `isPlutoPreviewPath` marks the preview path. The bar height is the token `--pluto-admin-bar-height`, and `<html>` gets `data-pluto-admin-bar` while the bar shows. A hint cookie puts the bar frame in the server HTML of a public page for staff (the actions and the user menu load after the mount). Content types with `adminBar` get "New <type>" and "Edit <type>" buttons (`usePlutoEditLink`). With two or more types, one "New" menu lists them, grouped by `navGroup`. A `navGroup` also puts related types under one sidebar item (registry bucket `navGroups`, core group `pages`). @.claude/skills/admin-shell/SKILL.md
 - Local layers helper: `plutoLayer(name)` from `@plutocms/core/layers` gives a Nuxt `extends` entry.
   With `PLUTO_LOCAL_ROOT`, it uses the local checkouts of the Pluto layers. @.claude/skills/local-layers/SKILL.md
 - Pluto logo: `PlutoLogo` draws the logo inline. The wordmark takes the text color, so the logo works

package/app/assets/css/pluto-layer.css

@@ -1,14 +1,15 @@
 /*
  * The pluto layer's CSS. It is not a Tailwind entry.
  *
- * The app's CSS entry owns the one Tailwind build of the app:
+ * `@plutocms/css` (core generates it) imports this file (and the same file of every other
+ * Pluto layer). Two builds import `@plutocms/css`: the admin build of core
+ * (scoped to the admin), and the app's own CSS entry of a Tailwind site:
  *
  *   @import 'tailwindcss';
  *   @import '@nuxt/ui';
  *   @import '@plutocms/css';
  *
- * `@plutocms/css` (core generates it) imports this file (and the same file of every other
- * Pluto layer). Rules for this file:
+ * Rules for this file:
  * - Do not import tailwindcss or @nuxt/ui here.
  * - Use only @theme, @custom-variant, @utility, unlayered rules, and
  *   imports of plain CSS files next to this one.
@@ -26,12 +27,8 @@
 }
 
 /*
- * `--pluto-admin-bar-height` is the height of the admin navbar: 2.5rem (40px)
- * at every width. The admin navbar and the admin layout read it. A public site
- * that shows the admin navbar to a logged-in admin offsets its own header by
- * the same value. Core sets `data-pluto-admin-bar` on <html> while the bar
- * shows, so a site can offset its header only then:
- * `:root[data-pluto-admin-bar] .site-header { top: var(--pluto-admin-bar-height) }`.
+ * `--pluto-admin-bar-height` (the admin navbar height) is in PlutoRoot, in
+ * plain CSS, so a site with no Tailwind has it too.
  *
  * `--ui-header-height` stays 2.5rem for existing apps. Set it outside a layer.
  * This overrides Nuxt UI's own `@layer theme` value for the same variable. A
@@ -39,7 +36,6 @@
  * `--ui-header-height`, and the admin keeps `--pluto-admin-bar-height`.
  */
 :root {
-  --pluto-admin-bar-height: 2.5rem;
   --ui-header-height: 2.5rem;
 }
 

package/app/components/Pluto/Admin/PlutoAdminNavbarProvider.vue

@@ -1,8 +1,9 @@
 <script setup lang="ts">
 // Decides if the core admin navbar shows. The rule lives in `usePlutoAdminBar`.
+// The navbar is lazy, so its code and the admin CSS load only when it shows.
 const { visible } = usePlutoAdminBar()
 </script>
 
 <template>
-  <PlutoAdminNavbar v-if="visible" />
+  <LazyPlutoAdminNavbar v-if="visible" />
 </template>

package/app/components/Pluto/Admin/PlutoAdminTheme.vue

@@ -8,6 +8,10 @@ import {
   PLUTO_ADMIN_UI,
   PLUTO_ADMIN_UI_PROPS,
 } from '../../../composables/pluto-admin-theme'
+// The admin's own Tailwind build, scoped to the admin. Only the async chunks of
+// the admin UI import this component, so a visitor who sees no admin UI does
+// not load the build. See the pluto-css module.
+import '#build/pluto-admin.css'
 </script>
 
 <template>

package/app/components/Pluto/PlutoRoot.vue

@@ -114,8 +114,8 @@ useHead({
 </script>
 
 <template>
-  <div class="flex min-h-0 w-full min-w-0 grow flex-col">
-    <UApp :locale="uiLocale" class="flex min-h-0 w-full min-w-0 grow flex-col">
+  <div class="pluto-root">
+    <UApp :locale="uiLocale">
       <NuxtRouteAnnouncer />
       <NuxtLoadingIndicator />
 
@@ -125,9 +125,9 @@ useHead({
         Public pages have no admin sidebar. The admin navbar menu button
         opens this slideover there instead.
       -->
-      <PlutoNavbarAdminMenu v-if="!isAdmin && adminBar.visible.value" />
+      <LazyPlutoNavbarAdminMenu v-if="!isAdmin && adminBar.visible.value" />
 
-      <div class="min-h-0 w-full min-w-0 grow">
+      <div class="pluto-root-page">
         <NuxtLayout>
           <slot />
         </NuxtLayout>
@@ -149,6 +149,39 @@ useHead({
   flex-direction: column;
 }
 
+/*
+ * `--pluto-admin-bar-height` is the height of the admin navbar: 2.5rem (40px)
+ * at every width. The admin navbar and the admin layout read it. A public site
+ * that shows the bar to a logged-in admin offsets its own header by the same
+ * value. Core sets `data-pluto-admin-bar` on <html> while the bar shows, so a
+ * site can offset its header only then:
+ * `:root[data-pluto-admin-bar] .site-header { top: var(--pluto-admin-bar-height) }`.
+ * It is here, in plain CSS, so a site with no Tailwind has it too.
+ */
+:root {
+  --pluto-admin-bar-height: 2.5rem;
+}
+
+/*
+ * The wrappers grow to fill #__nuxt. Plain CSS, not Tailwind classes: a site
+ * may have no Tailwind (the admin has a build of its own).
+ */
+.pluto-root {
+  display: flex;
+  flex-direction: column;
+  flex-grow: 1;
+  width: 100%;
+  min-width: 0;
+  min-height: 0;
+}
+
+.pluto-root-page {
+  flex-grow: 1;
+  width: 100%;
+  min-width: 0;
+  min-height: 0;
+}
+
 :root[data-pluto-admin],
 :root[data-pluto-admin] body,
 :root[data-pluto-admin] #__nuxt {

package/app/composables/internal/admin-shell.ts

@@ -9,6 +9,7 @@ import type {
 export const ADMIN_LOGIN_PATH = '/admin/login'
 export const ADMIN_HOME_PATH = '/admin/home'
 export const ADMIN_NO_ACCESS_PATH = '/admin/no-access'
+export const ADMIN_NOT_CONFIGURED_PATH = '/admin/not-configured'
 
 const FAKE_ORIGIN = 'http://pluto.invalid'
 
@@ -111,6 +112,40 @@ function firstString(value: unknown): unknown {
   return Array.isArray(value) ? value[0] : value
 }
 
+export interface DriverInput {
+  path: string
+  /** An auth driver is registered. */
+  hasDriver: boolean
+  /** The app runs in dev (`import.meta.dev`). */
+  dev: boolean
+}
+
+/**
+ * Decides what the route guard does about the auth driver, before the sign-in
+ * rules. It returns `undefined` when a driver is registered and the sign-in
+ * rules apply. It never touches a path outside `/admin`.
+ *
+ * - No driver in production: the backend is missing or did not load (both
+ *   backends register a driver). Every admin path goes to the not-configured
+ *   page, so the admin pages do not show to everyone.
+ * - No driver in dev: allow, so admin pages can be built with no backend.
+ * - A driver, on the not-configured page: go to the admin home.
+ */
+export function driverDecision(input: DriverInput): GuardDecision | undefined {
+  const { path, hasDriver, dev } = input
+  if (!isAdminPath(path)) {
+    return { action: 'allow' }
+  }
+  const onPage = trimSlash(path) === ADMIN_NOT_CONFIGURED_PATH
+  if (hasDriver) {
+    return onPage ? { action: 'redirect', to: ADMIN_HOME_PATH } : undefined
+  }
+  if (dev || onPage) {
+    return { action: 'allow' }
+  }
+  return { action: 'redirect', to: ADMIN_NOT_CONFIGURED_PATH }
+}
+
 /**
  * Decides what the route guard does. It never touches a path outside `/admin`.
  * A signed-out user on a private admin path goes to the login page, with the

package/app/middleware/pluto-admin-auth.global.ts

@@ -1,16 +1,16 @@
 import {
+  driverDecision,
   guardDecision,
-  isAdminPath,
   matchPublicPath,
   staffDecision,
 } from '../composables/internal/admin-shell'
 
 /**
- * The route guard of the admin. It does nothing when no auth driver is
- * registered, so a backend with its own guard (supabase 0.10) is not affected.
- * It never touches a path outside `/admin`. A signed-out user on a private
- * admin path goes to the login page. A signed-in user on a public auth path
- * goes to the admin home. The driver's own `guard` runs first, so a backend
+ * The route guard of the admin. It never touches a path outside `/admin`.
+ * With no auth driver, `driverDecision` decides: in production every admin
+ * path goes to the not-configured page, in dev the admin opens. With a driver,
+ * a signed-out user on a private admin path goes to the login page. A
+ * signed-in user on a public auth path goes to the admin home. The driver's own `guard` runs first, so a backend
  * can send the user somewhere else (supabase: the first setup). Then a signed-in
  * user on a private path must be staff (at least one capability, or no
  * permissions driver). Other users go to `/admin/no-access`. The public auth
@@ -19,8 +19,15 @@ import {
  */
 export default defineNuxtRouteMiddleware(async (to) => {
   const auth = usePlutoAuth()
-  if (!auth.hasDriver.value || !isAdminPath(to.path)) {
-    return
+  const driver = driverDecision({
+    path: to.path,
+    hasDriver: auth.hasDriver.value,
+    dev: import.meta.dev,
+  })
+  if (driver) {
+    return driver.action === 'redirect'
+      ? navigateTo(driver.to, { replace: true })
+      : undefined
   }
 
   try {

package/app/pages/admin/not-configured.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+// The page for an admin with no auth driver in production: the backend is
+// missing or did not load. The route guard sends every admin path here (see
+// `driverDecision`), so the admin pages do not show to everyone. The frame is
+// PlutoAdminAuthCard. See the admin-shell skill.
+definePageMeta({ layout: 'auth' })
+
+const { t } = usePlutoI18n()
+
+useHead({ title: () => t('pluto.notConfigured.title') })
+</script>
+
+<template>
+  <PlutoAdminAuthCard :title="t('pluto.notConfigured.title')">
+    <UAlert
+      :description="t('pluto.notConfigured.description')"
+      color="warning"
+      icon="lucide:plug-zap"
+      variant="subtle"
+    />
+  </PlutoAdminAuthCard>
+</template>

package/i18n/locales/en.json

@@ -597,6 +597,10 @@
       "goToSite": "Go to the site",
       "signOut": "Sign out"
     },
+    "notConfigured": {
+      "title": "The admin is not set up",
+      "description": "This site has no sign-in for the admin. If you run this site, make sure that the server can load its content backend, and check the environment variables of the server."
+    },
     "post": {
       "previewTitle": "Post preview",
       "previewBadge": "Preview",

package/i18n/locales/pt-BR.json

@@ -597,6 +597,10 @@
       "goToSite": "Ir para o site",
       "signOut": "Sair"
     },
+    "notConfigured": {
+      "title": "O painel não está configurado",
+      "description": "Este site não tem login para o painel. Se você administra este site, confira se o servidor consegue carregar o backend de conteúdo e verifique as variáveis de ambiente do servidor."
+    },
     "post": {
       "previewTitle": "Prévia do post",
       "previewBadge": "Prévia",

package/modules/pluto-css/css-entries.ts

@@ -70,11 +70,14 @@ function cssImport(file: string, buildDir: string): string {
   return `@import "${path}";`
 }
 
-/** The fallback entry, used only when the app has no Tailwind entry. */
-export function renderPlutoEntryCss(): string {
+/**
+ * Renders `#build/pluto-admin.css`: the Tailwind build of the admin. The module
+ * scopes its output to the admin (see scope.ts), and PlutoAdminTheme imports it.
+ */
+export function renderPlutoAdminCss(): string {
   return [
     '/* Generated by @plutocms/core (modules/pluto-css). Do not edit. */',
-    '/* Fallback Tailwind entry: the app has no CSS entry that imports Tailwind. */',
+    '/* The admin build: scoped to [data-pluto-admin] and [data-pluto-admin-scope]. */',
     '@import "tailwindcss";',
     '@import "@nuxt/ui";',
     `@import "${PLUTO_CSS_IMPORT}";`,
@@ -111,17 +114,12 @@ export interface CssEntryInfo {
   file: string
   /** It imports Tailwind (`@import 'tailwindcss'`), so it is a Tailwind build. */
   tailwind: boolean
-  /** It imports `@nuxt/ui`. */
-  nuxtUi: boolean
-  /** It imports `@plutocms/css` (or the generated `#build/pluto.css` itself). */
-  plutoCss: boolean
 }
 
 /**
  * Follows the local `@import`s of a CSS entry, to `maxDepth`, and reports
- * what it imports. `resolveImport` turns a specifier into a file path, or
- * returns `undefined` for a package import (such as `tailwindcss`), which is
- * not followed.
+ * whether it imports Tailwind. `resolveImport` turns a specifier into a file
+ * path, or returns `undefined` for a package import, which is not followed.
  */
 export function analyzeCssEntry(
   file: string,
@@ -129,12 +127,7 @@ export function analyzeCssEntry(
   resolveImport: (specifier: string, fromFile: string) => string | undefined,
   maxDepth = 3
 ): CssEntryInfo {
-  const info: CssEntryInfo = {
-    file,
-    tailwind: false,
-    nuxtUi: false,
-    plutoCss: false,
-  }
+  const info: CssEntryInfo = { file, tailwind: false }
   const seen = new Set<string>()
 
   function visit(path: string, depth: number) {
@@ -149,13 +142,6 @@ export function analyzeCssEntry(
     for (const specifier of parseCssImports(css)) {
       if (specifier === 'tailwindcss') {
         info.tailwind = true
-      } else if (specifier === '@nuxt/ui') {
-        info.nuxtUi = true
-      } else if (
-        specifier === PLUTO_CSS_IMPORT ||
-        (/(?:^|\/)pluto\.css$/.test(specifier) && specifier.includes('#build'))
-      ) {
-        info.plutoCss = true
       } else {
         const next = resolveImport(specifier, path)
         if (next) {
@@ -179,27 +165,18 @@ export function resolveRelativeImport(
     : undefined
 }
 
-export interface CssSetupReport {
-  /** Inject the fallback entry: no CSS entry imports Tailwind. */
-  injectFallback: boolean
-  warnings: string[]
-}
-
 /**
- * Checks the app's CSS setup against the single-build rules and returns
- * what to do. `layerRoots` are the root dirs of every layer except the app.
+ * Checks the app's CSS entries and returns the warnings. The admin has a build
+ * of its own, so the app's entry is for the site only, and an app with no
+ * Tailwind entry is fine. A Tailwind build belongs in the app, not in a layer,
+ * and there is one. `layerRoots` are the root dirs of every layer except the app.
  */
 export function checkCssSetup(
   entries: CssEntryInfo[],
   layerRoots: string[]
-): CssSetupReport {
+): string[] {
   const warnings: string[] = []
   const tailwindEntries = entries.filter((entry) => entry.tailwind)
-  const snippet = `  @import 'tailwindcss';\n  @import '@nuxt/ui';\n  @import '${PLUTO_CSS_IMPORT}';`
-
-  if (tailwindEntries.length === 0) {
-    return { injectFallback: true, warnings }
-  }
 
   for (const entry of tailwindEntries) {
     const layerRoot = layerRoots.find((root) =>
@@ -218,17 +195,5 @@ export function checkCssSetup(
     )
   }
 
-  if (!tailwindEntries.some((entry) => entry.plutoCss)) {
-    warnings.push(
-      `No CSS entry imports ${PLUTO_CSS_IMPORT}. The admin theme and layer tokens are missing. Start the app's CSS entry with:\n${snippet}`
-    )
-  }
-
-  if (!tailwindEntries.some((entry) => entry.nuxtUi)) {
-    warnings.push(
-      `No CSS entry imports @nuxt/ui. Nuxt UI styles, the \`light:\` variant, and the layer sources are missing. Start the app's CSS entry with:\n${snippet}`
-    )
-  }
-
-  return { injectFallback: false, warnings }
+  return warnings
 }

package/modules/pluto-css/index.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import {
   addTemplate,
+  addVitePlugin,
   defineNuxtModule,
   getLayerDirectories,
   resolvePath,
@@ -14,37 +15,44 @@ import {
   findLayerCssFiles,
   PLUTO_CSS_IMPORT,
   PLUTO_SITE_CSS_IMPORT,
+  renderPlutoAdminCss,
   renderPlutoCss,
-  renderPlutoEntryCss,
   renderPlutoSiteCss,
   resolveRelativeImport,
 } from './css-entries'
+import { scopeCss } from './scope'
 
 export interface PlutoCssOptions {
-  /** Warn at build time about a CSS setup that breaks the single build. Default true. */
+  /** Warn at build time about a Tailwind build in a layer, or more than one. Default true. */
   check?: boolean
 }
 
 /**
- * One Tailwind build per app. The app's CSS entry owns the build:
+ * The CSS of Pluto. The admin and the site have separate Tailwind builds:
  *
- *   @import 'tailwindcss';
- *   @import '@nuxt/ui';
- *   @import '@plutocms/css';
+ * - The admin build `#build/pluto-admin.css` (`tailwindcss`, `@nuxt/ui`,
+ *   `@plutocms/css`). Tailwind compiles it at the app's build, then the
+ *   `pluto-css:scope-admin` plugin scopes every rule to the admin
+ *   (`[data-pluto-admin]`, `[data-pluto-admin-scope]`). PlutoAdminTheme imports
+ *   it, so it loads only with the admin UI.
+ * - The site's build is the app's own CSS entry, if the app has one. A site
+ *   needs no Tailwind. A Tailwind site imports what its pages use:
+ *
+ *     @import 'tailwindcss';
+ *     @import '@nuxt/ui';
+ *     @import '@plutocms/css';
  *
  * - `@plutocms/css` is an alias of the generated `#build/pluto.css`. It imports
- *   each layer's app/assets/css/pluto-layer.css (tokens, the admin theme), so one
- *   import covers every layer of the app. Nuxt UI already adds `@source` for
- *   every layer's app/ dir, so this file adds no sources.
+ *   each layer's app/assets/css/pluto-layer.css (the Pluto tokens, the layer
+ *   tokens). Nuxt UI already adds `@source` for every layer's app/ dir, so this
+ *   file adds no sources.
  * - `@plutocms/css/site` (opt-in) is an alias of `#build/pluto-site.css`: the
  *   Pluto site theme of core (app/assets/css/pluto-site-theme.css), the look of
  *   the Pluto docs for a site.
  * - The names are aliases, not npm packages, so they resolve with every package
  *   manager, also when the app installs only an outer layer.
- * - An app with no Tailwind entry (a layer repo run on its own, or an app
- *   with no CSS) gets the fallback entry `#build/pluto-entry.css`.
- * - The module warns about a layer that registers its own Tailwind build,
- *   more than one build, or a missing import.
+ * - The module warns about a layer that registers its own Tailwind build, and
+ *   about more than one build in the app.
  *
  * See the single-tailwind-build skill.
  */
@@ -88,6 +96,66 @@ export default defineNuxtModule<PlutoCssOptions>({
       'pluto.css'
     )
 
+    // The admin build. Not written to disk: on disk, Tailwind IntelliSense
+    // could take this entry for the app's design system. Not in `css`:
+    // PlutoAdminTheme imports it, so it loads with the admin UI only.
+    addTemplate({
+      filename: 'pluto-admin.css',
+      getContents: renderPlutoAdminCss,
+    })
+
+    // Server HTML links the admin build, not inlines it: inline, every page
+    // view of a staff user would carry the full build, which no cache keeps.
+    const inline = nuxt.options.features.inlineStyles
+    if (inline) {
+      nuxt.options.features.inlineStyles = (id) =>
+        !id?.includes('PlutoAdminTheme.vue') && (inline === true || inline(id))
+    }
+
+    // Nuxt prefetches the CSS of every async chunk, so each visitor would
+    // download the admin build after the page loads. The plugin below finds
+    // the CSS files of the client chunk with the build, and this hook turns
+    // off their prefetch. The chunks that render admin UI still load them.
+    // The file names, without the assets dir: the manifest keys have none.
+    const adminCssFiles = new Set<string>()
+    nuxt.hook('build:manifest', (manifest) => {
+      for (const file of adminCssFiles) {
+        if (manifest[file]) {
+          manifest[file].prefetch = false
+        }
+      }
+    })
+
+    // A file path, or a Nuxt virtual id (`virtual:nuxt:…%2Fpluto-admin.css`).
+    const adminCssId = /(?:[\\/]|%2F)pluto-admin\.css(?:\?|$)/
+    addVitePlugin({
+      name: 'pluto-css:scope-admin',
+      transform(code, id) {
+        if (adminCssId.test(id)) {
+          return { code: scopeCss(code), map: null }
+        }
+      },
+      generateBundle(_options, bundle) {
+        if (this.environment?.name !== 'client') {
+          return
+        }
+        for (const chunk of Object.values(bundle)) {
+          if (
+            chunk.type === 'chunk' &&
+            chunk.moduleIds.some((id) => adminCssId.test(id))
+          ) {
+            for (const file of chunk.viteMetadata?.importedCss ?? []) {
+              adminCssFiles.add(file.slice(file.lastIndexOf('/') + 1))
+            }
+          }
+        }
+      },
+    })
+
+    if (!options.check || nuxt.options._prepare) {
+      return
+    }
+
     const entries = []
     for (const entry of nuxt.options.css) {
       const file =
@@ -112,29 +180,8 @@ export default defineNuxtModule<PlutoCssOptions>({
     const layerRoots = layers
       .map((layer) => layer.root.replaceAll('\\', '/'))
       .filter((root) => root !== appRoot)
-    const report = checkCssSetup(entries, layerRoots)
-
-    // Only an app with no Tailwind entry gets the fallback file. In an app with
-    // its own entry, the file would be a second Tailwind entry on disk, and
-    // Tailwind IntelliSense could take it for the app's design system.
-    if (report.injectFallback) {
-      addTemplate({
-        filename: 'pluto-entry.css',
-        write: true,
-        getContents: renderPlutoEntryCss,
-      })
-      nuxt.options.css.push('#build/pluto-entry.css')
-      if (!nuxt.options._prepare) {
-        logger.info(
-          'No CSS entry imports Tailwind. Using the Pluto fallback entry (#build/pluto-entry.css).'
-        )
-      }
-    }
-
-    if (options.check && !nuxt.options._prepare) {
-      for (const warning of report.warnings) {
-        logger.warn(warning)
-      }
+    for (const warning of checkCssSetup(entries, layerRoots)) {
+      logger.warn(warning)
     }
   },
 })

package/modules/pluto-css/scope.ts

@@ -0,0 +1,117 @@
+// Scopes a compiled stylesheet to the Pluto admin: every rule matches only
+// inside a scope root. Pure (no `nuxt/kit`), so the unit tests call it directly.
+// See the single-tailwind-build skill, "The admin build".
+import type { AtRule, Rule } from 'postcss'
+import postcss from 'postcss'
+import selectorParser from 'postcss-selector-parser'
+
+/**
+ * The elements that start the admin scope: <html> on an admin page
+ * (`data-pluto-admin`), and the admin bar and its portals on a public page
+ * (`data-pluto-admin-scope`).
+ */
+export const PLUTO_ADMIN_SCOPE_ROOTS = [
+  '[data-pluto-admin]',
+  '[data-pluto-admin-scope]',
+] as const
+
+/** Selectors that mean the document root. They become the scope roots. */
+const ROOT_SELECTORS = new Set([':root', ':host', 'html'])
+
+/** A pseudo-element: the scope goes before it. */
+const PSEUDO_ELEMENT = /^(?:::|:(?:before|after|first-line|first-letter)$)/
+
+/** Scopes each selector of a selector list. */
+function scopeSelectorList(selector: string, roots: readonly string[]): string {
+  // An element in the scope: a root itself, or anything inside a root.
+  const inScope = `:is(${[...roots, ...roots.map((root) => `${root} *`)].join(', ')})`
+  const rootNames = roots.map((root) => root.slice(1, -1))
+  const out: string[] = []
+
+  selectorParser((list) => {
+    list.each((sel) => {
+      const text = sel.toString().trim()
+      if (rootNames.some((name) => text.includes(name))) {
+        out.push(text)
+        return
+      }
+      if (ROOT_SELECTORS.has(text)) {
+        // A doubled root, (0,2,0): on <html> of an admin page it beats the
+        // app's own `:root` (0,1,0), whatever order the two files load in.
+        out.push(...roots.map((root) => `${root}${root}`))
+        return
+      }
+      // The subject is the last compound: `.a .b::before` becomes
+      // `.a .b:is(…)::before`.
+      const nodes = sel.nodes
+      let start = 0
+      nodes.forEach((node, index) => {
+        if (node.type === 'combinator') {
+          start = index + 1
+        }
+      })
+      const pseudoElement = nodes.findIndex(
+        (node, index) =>
+          index >= start &&
+          node.type === 'pseudo' &&
+          PSEUDO_ELEMENT.test(node.value)
+      )
+      const scope = selectorParser.pseudo({ value: inScope })
+      if (pseudoElement === -1) {
+        sel.append(scope)
+      } else {
+        // The space before the pseudo-element (`, ::after`) moves to the
+        // scope. Left in place, it would be a descendant combinator.
+        const target = nodes[pseudoElement]!
+        scope.spaces.before = target.spaces.before
+        target.spaces.before = ''
+        sel.insertBefore(target, scope)
+      }
+      out.push(sel.toString().trim())
+    })
+  }).processSync(selector)
+
+  return out.join(', ')
+}
+
+/** True when the rule is in `@keyframes`, or nested in another rule. */
+function keepAsIs(rule: Rule): boolean {
+  let parent = rule.parent
+  while (parent && parent.type !== 'root') {
+    if (parent.type === 'rule') {
+      return true
+    }
+    if (
+      parent.type === 'atrule' &&
+      /keyframes$/i.test((parent as AtRule).name)
+    ) {
+      return true
+    }
+    parent = parent.parent
+  }
+  return false
+}
+
+/**
+ * Returns `css` with every top-level rule scoped to `roots`:
+ *
+ * - `:root`, `:host`, and `html` become the roots, doubled for (0,2,0), so the
+ *   theme variables and the base of the document apply from each root down,
+ *   over the app's own `:root` rules.
+ * - Any other selector gets `:is(<root>, <root> *)` on its subject. It then
+ *   matches only in the scope, with (0,1,0) more specificity.
+ * - A selector that names a root already stays.
+ * - Rules nested in rules (they follow their parent) and `@keyframes` stay.
+ */
+export function scopeCss(
+  css: string,
+  roots: readonly string[] = PLUTO_ADMIN_SCOPE_ROOTS
+): string {
+  const ast = postcss.parse(css)
+  ast.walkRules((rule) => {
+    if (!keepAsIs(rule)) {
+      rule.selector = scopeSelectorList(rule.selector, roots)
+    }
+  })
+  return ast.toString()
+}

package/nuxt.config.ts

@@ -41,9 +41,10 @@ export default defineNuxtConfig({
     },
   },
 
-  // No `css` entry: the app's CSS entry owns the one Tailwind build, and
-  // modules/pluto-css adds this layer's pluto-layer.css to it through
-  // @plutocms/css (#build/pluto.css). See the single-tailwind-build skill.
+  // No `css` entry: modules/pluto-css gives the admin a Tailwind build of its
+  // own, and the site's build is the app's CSS entry. Both get this layer's
+  // pluto-layer.css through @plutocms/css (#build/pluto.css). See the
+  // single-tailwind-build skill.
 
   runtimeConfig: {
     // Private mail settings. Empty defaults on purpose: Nuxt reads

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/core",
   "type": "module",
-  "version": "0.44.1",
+  "version": "0.46.0",
   "description": "The base layer every Pluto app extends: the admin, the content model, and the Git CMS",
   "author": "Victor Ribeiro",
   "license": "MIT",
@@ -47,6 +47,8 @@
     "@vueuse/nuxt": "^15.0.0",
     "image-meta": "^0.3.0",
     "marked": "^18.1.1",
+    "postcss": "^8.5.30",
+    "postcss-selector-parser": "^7.1.4",
     "reka-ui": "^2.11.0",
     "tailwind-merge": "^3.7.0",
     "ultrahtml": "^1.7.0",