@plutocms/core 0.45.0 → 0.47.0

package/CHANGELOG.md

@@ -1,6 +1,33 @@
 # Changelog
 
 
+## [0.47.0](https://github.com/plutocms/pluto/compare/v0.46.0...v0.47.0) (2026-11-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* PlutoHtml has no Tailwind prose classes. A site imports `@plutocms/css/base` for the prose look. A site that adds its own page offset for the admin bar removes it, or the page moves down twice.
+
+### Features
+
+* the public components use plain CSS, with an optional @plutocms/css/base ([#353](https://github.com/plutocms/pluto/issues/353)) ([d0fa541](https://github.com/plutocms/pluto/commit/d0fa541b34a672370ebf2d95372a967a1aebde10))
+
+
+### Bug Fixes
+
+* the admin has its styles in the first frame of a client navigation ([#354](https://github.com/plutocms/pluto/issues/354)) ([f7a4226](https://github.com/plutocms/pluto/commit/f7a4226966e73bf2a91ae599303c35a8daac61a2))
+
+## [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)
 
 

package/FEATURES.md

@@ -66,9 +66,16 @@ 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
+- Public components: the components for a public site (`PlutoHtml`, `PlutoImage`, `PlutoLogo`,
+  `PlutoRoot`, and those of the layers) use only `pluto-*` classes and work with no Tailwind. Their
+  look is plain CSS in each layer's `pluto-base.css`, which a site imports with the opt-in
+  `@import '@plutocms/css/base'`. @.claude/skills/public-components/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

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

@@ -0,0 +1,228 @@
+/*
+ * The look of the public components of core. Opt-in: a site imports it with
+ * `@import '@plutocms/css/base'`, with or without Tailwind. Plain CSS only:
+ * no Tailwind directive. See the public-components skill.
+ *
+ * Every selector is in `:where()` (zero specificity) and in the `components`
+ * layer. On a Tailwind site, the file joins Tailwind's own layer, so a utility
+ * wins. On a site with no Tailwind, any unlayered rule of the site wins.
+ *
+ * Colors read the Nuxt UI variables, with plain fallbacks: a Nuxt UI site
+ * gets its own theme. A site can also set the `--pluto-prose-*` variables.
+ */
+@layer theme, base, components, utilities;
+
+@layer components {
+  /* PlutoHtml, PlutoMarkdown, and the PlutoProse of the blog layer. */
+  :where(.pluto-prose) {
+    --pluto-prose-heading: var(--ui-text-highlighted, currentColor);
+    --pluto-prose-muted: var(
+      --ui-text-muted,
+      color-mix(in oklab, currentColor 65%, transparent)
+    );
+    --pluto-prose-link: var(--ui-primary, LinkText);
+    --pluto-prose-border: var(
+      --ui-border,
+      color-mix(in oklab, currentColor 15%, transparent)
+    );
+    --pluto-prose-border-accented: var(
+      --ui-border-accented,
+      color-mix(in oklab, currentColor 30%, transparent)
+    );
+    --pluto-prose-code-bg: var(
+      --ui-bg-muted,
+      color-mix(in oklab, currentColor 6%, transparent)
+    );
+    --pluto-prose-th-bg: var(
+      --ui-bg-elevated,
+      color-mix(in oklab, currentColor 4%, transparent)
+    );
+    --pluto-prose-radius: calc(var(--ui-radius, 0.25rem) * 1.5);
+    --pluto-prose-mono: var(
+      --font-mono,
+      ui-monospace,
+      SFMono-Regular,
+      Menlo,
+      Consolas,
+      monospace
+    );
+
+    width: 100%;
+    overflow-wrap: break-word;
+  }
+
+  :where(.pluto-prose) ::selection {
+    background-color: color-mix(
+      in oklab,
+      var(--pluto-prose-link) 20%,
+      transparent
+    );
+  }
+
+  :where(.pluto-prose) > :where(*) {
+    margin-block: 1.25rem;
+  }
+
+  :where(.pluto-prose) > :where(:first-child) {
+    margin-block-start: 0;
+  }
+
+  :where(.pluto-prose) > :where(:last-child) {
+    margin-block-end: 0;
+  }
+
+  :where(.pluto-prose) :where(p) {
+    line-height: 1.75rem;
+  }
+
+  :where(.pluto-prose) :where(a) {
+    color: var(--pluto-prose-link);
+    font-weight: 500;
+    text-decoration: none;
+    border-block-end: 1px solid transparent;
+    transition: border-color 0.15s;
+  }
+
+  :where(.pluto-prose) :where(a:hover) {
+    border-block-end-color: var(--pluto-prose-link);
+  }
+
+  :where(.pluto-prose) :where(a:focus-visible) {
+    border-block-end-color: transparent;
+    border-radius: 0.125rem;
+    outline: 3px solid
+      color-mix(in oklab, var(--pluto-prose-link) 25%, transparent);
+  }
+
+  :where(.pluto-prose) :where(h1, h2, h3, h4, h5, h6) {
+    color: var(--pluto-prose-heading);
+    font-weight: 700;
+  }
+
+  :where(.pluto-prose) :where(h1) {
+    font-size: 1.875rem;
+    line-height: 2.25rem;
+  }
+
+  :where(.pluto-prose) :where(h2) {
+    font-size: 1.5rem;
+    line-height: 2rem;
+  }
+
+  :where(.pluto-prose) :where(h3) {
+    font-size: 1.25rem;
+    line-height: 1.75rem;
+  }
+
+  :where(.pluto-prose) :where(h4) {
+    font-size: 1.125rem;
+    line-height: 1.75rem;
+  }
+
+  :where(.pluto-prose) :where(h5, h6) {
+    font-size: 1rem;
+    line-height: 1.5rem;
+  }
+
+  :where(.pluto-prose) :where(blockquote) {
+    margin-inline: 0;
+    padding-inline-start: 1rem;
+    border-inline-start: 4px solid var(--pluto-prose-border-accented);
+    font-style: italic;
+  }
+
+  :where(.pluto-prose) :where(hr) {
+    border: 0;
+    border-block-start: 1px solid var(--pluto-prose-border);
+  }
+
+  :where(.pluto-prose) :where(code) {
+    display: inline-block;
+    padding: 0.125rem 0.375rem;
+    border: 1px solid var(--pluto-prose-border);
+    border-radius: var(--pluto-prose-radius);
+    background-color: var(--pluto-prose-code-bg);
+    color: var(--pluto-prose-heading);
+    font-family: var(--pluto-prose-mono);
+    font-size: 0.875rem;
+    font-weight: 500;
+  }
+
+  :where(.pluto-prose) :where(pre) {
+    overflow-x: auto;
+    padding: 0.75rem 1rem;
+    border: 1px solid var(--pluto-prose-border);
+    border-radius: var(--pluto-prose-radius);
+    background-color: var(--pluto-prose-code-bg);
+    font-family: var(--pluto-prose-mono);
+    font-size: 0.875rem;
+    line-height: 1.5rem;
+    white-space: pre-wrap;
+  }
+
+  :where(.pluto-prose) :where(pre code) {
+    display: inline;
+    padding: 0;
+    border: 0;
+    border-radius: 0;
+    background-color: transparent;
+    color: inherit;
+    font-size: inherit;
+  }
+
+  :where(.pluto-prose) :where(ul, ol) {
+    padding-inline-start: 1.5rem;
+  }
+
+  :where(.pluto-prose) :where(ul) {
+    list-style-type: disc;
+  }
+
+  :where(.pluto-prose) :where(ol) {
+    list-style-type: decimal;
+  }
+
+  :where(.pluto-prose) :where(ul > li)::marker {
+    color: var(--pluto-prose-border-accented);
+  }
+
+  :where(.pluto-prose) :where(ol > li)::marker {
+    color: var(--pluto-prose-muted);
+  }
+
+  :where(.pluto-prose) :where(li) {
+    margin-block: 0.375rem;
+    padding-inline-start: 0.375rem;
+  }
+
+  :where(.pluto-prose) :where(img) {
+    display: block;
+    max-width: 100%;
+    height: auto;
+    border-radius: var(--pluto-prose-radius);
+  }
+
+  :where(.pluto-prose) :where(table) {
+    display: block;
+    overflow-x: auto;
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 0.875rem;
+  }
+
+  :where(.pluto-prose) :where(th, td) {
+    padding: 0.5rem 0.75rem;
+    border: 1px solid var(--pluto-prose-border);
+  }
+
+  :where(.pluto-prose) :where(th) {
+    background-color: var(--pluto-prose-th-bg);
+    color: var(--pluto-prose-heading);
+    font-weight: 600;
+    text-align: start;
+  }
+
+  :where(.pluto-prose) :where(input[type='checkbox']) {
+    margin-inline-end: 0.5rem;
+  }
+}

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/PlutoHtml.vue

@@ -1,36 +1,21 @@
 <script setup lang="ts">
-import { tv } from '@nuxt/ui/utils/tv'
-import theme from '#build/ui/editor'
-
 // Shows the `html` of a public item (the public API of Pluto), with readable prose styles. It
 // works with every backend: the Git CMS and `@plutocms/supabase-blog` both send the body as
 // sanitized HTML, so the string is safe to set as `innerHTML`. This component never parses or
 // sanitizes. Do not pass any other HTML to it.
-const props = withDefaults(
+//
+// The prose look is `.pluto-prose` in app/assets/css/pluto-base.css: plain CSS that a site
+// imports with `@plutocms/css/base`. No Tailwind class here, so the component works on a site
+// with no Tailwind. See the public-components skill.
+withDefaults(
   defineProps<{
     html: string
     tag?: string
-    class?: any
   }>(),
   {
     tag: 'article',
-    class: undefined,
   }
 )
-
-// The base of the Nuxt UI editor theme gives readable prose with semantic
-// color tokens. The editor adds side padding, so `sm:px-0` removes it.
-// The table classes are here because the editor theme has none.
-const ui = computed(() => tv({ extend: theme })())
-
-const classes = computed(() => [
-  ui.value.base({ class: 'sm:px-0' }),
-  '[&_table]:block [&_table]:w-full [&_table]:overflow-x-auto [&_table]:text-sm',
-  '[&_:is(th,td)]:border [&_:is(th,td)]:border-default [&_:is(th,td)]:px-3 [&_:is(th,td)]:py-2',
-  '[&_th]:bg-elevated [&_th]:text-highlighted [&_th]:text-start [&_th]:font-semibold',
-  '[&_input[type=checkbox]]:me-2',
-  props.class,
-])
 </script>
 
 <template>
@@ -38,5 +23,5 @@ const classes = computed(() => [
        on a dynamic `<component :is>` drops the value in the SSR output. The
        hyphenated spelling renders a literal `inner-h-t-m-l` attribute. -->
   <!-- eslint-disable-next-line vue/attribute-hyphenation -- must stay camelCase, see comment above -->
-  <component :is="tag" v-if="html" :class="classes" :innerHTML="html" />
+  <component :is="tag" v-if="html" :innerHTML="html" class="pluto-prose" />
 </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,58 @@ 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 bar is fixed at the top, so a public page moves down by its height while
+ * it shows: the top of the page is never under the bar. A sticky or fixed
+ * header of the site still needs `top: var(--pluto-admin-bar-height)`. The
+ * admin pages (`data-pluto-admin`) have their own layout. Zero specificity
+ * (`:where`), so a rule of the site wins.
+ */
+:where(:root[data-pluto-admin-bar]:not([data-pluto-admin])) body {
+  padding-top: var(--pluto-admin-bar-height);
+}
+
+:where(:root[data-pluto-admin-bar]:not([data-pluto-admin])) {
+  scroll-padding-top: var(--pluto-admin-bar-height);
+}
+
+:where(:root[data-pluto-admin-bar]:not([data-pluto-admin])) #__nuxt {
+  min-height: calc(100dvh - var(--pluto-admin-bar-height));
+}
+
+/*
+ * 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/pluto-admin-theme.ts

@@ -8,9 +8,30 @@
  *
  * Call it from every admin layout. `useHead` removes the attribute when the
  * layout unmounts, so the public site never gets it.
+ *
+ * `useHead` puts the attribute in the server HTML, but in the browser it
+ * writes <html> after the render, a frame late. The admin build is scoped to
+ * the attribute, so a client navigation from the public site showed one frame
+ * of the admin with no styles. `onMounted` runs in the same task as the DOM
+ * change, before the paint, so the attribute is set there too. A count keeps
+ * it while another admin layout is mounted.
  */
+let mountedAdminLayouts = 0
+
 export function usePlutoAdminTheme() {
   useHead({ htmlAttrs: { 'data-pluto-admin': '' } })
+  if (import.meta.client) {
+    onMounted(() => {
+      mountedAdminLayouts++
+      document.documentElement.setAttribute('data-pluto-admin', '')
+    })
+    onUnmounted(() => {
+      mountedAdminLayouts--
+      if (mountedAdminLayouts === 0) {
+        document.documentElement.removeAttribute('data-pluto-admin')
+      }
+    })
+  }
 }
 
 /**

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

@@ -11,24 +11,30 @@ export const PLUTO_CSS_IMPORT = '@plutocms/css'
 /** The opt-in Pluto site theme: an alias of `#build/pluto-site.css`. */
 export const PLUTO_SITE_CSS_IMPORT = '@plutocms/css/site'
 
+/** A layer's plain CSS for its public components. See the public-components skill. */
+export const LAYER_BASE_CSS_FILE = 'assets/css/pluto-base.css'
+
+/** The opt-in look of the public components: an alias of `#build/pluto-base.css`. */
+export const PLUTO_BASE_CSS_IMPORT = '@plutocms/css/base'
+
 function toPosix(path: string): string {
   return path.replaceAll('\\', '/')
 }
 
 /**
- * Returns the `pluto-layer.css` file of every layer that has one, base
- * layer first. Nuxt lists the layers top first (the app, then each layer it
- * extends), so the list is reversed: a higher layer's `@theme` then comes
- * later in the build and wins.
+ * Returns the `file` of every layer that has one, base layer first. Nuxt
+ * lists the layers top first (the app, then each layer it extends), so the
+ * list is reversed: a higher layer's rules then come later and win.
  */
 export function findLayerCssFiles(
   layerAppDirs: string[],
-  exists: (path: string) => boolean
+  exists: (path: string) => boolean,
+  file = LAYER_CSS_FILE
 ): string[] {
   return [...layerAppDirs]
     .reverse()
-    .map((appDir) => toPosix(join(appDir, LAYER_CSS_FILE)))
-    .filter((file) => exists(file))
+    .map((appDir) => toPosix(join(appDir, file)))
+    .filter((path) => exists(path))
 }
 
 /**
@@ -37,9 +43,26 @@ export function findLayerCssFiles(
  * another drive (Windows) stays absolute.
  */
 export function renderPlutoCss(files: string[], buildDir: string): string {
+  return renderLayerImports(files, buildDir, LAYER_CSS_FILE)
+}
+
+/**
+ * Renders `#build/pluto-base.css`: one `@import` for each layer's
+ * `pluto-base.css`. The plain CSS of the public components: an app imports
+ * it (`@plutocms/css/base`) with or without Tailwind.
+ */
+export function renderPlutoBaseCss(files: string[], buildDir: string): string {
+  return renderLayerImports(files, buildDir, LAYER_BASE_CSS_FILE)
+}
+
+function renderLayerImports(
+  files: string[],
+  buildDir: string,
+  name: string
+): string {
   return [
     '/* Generated by @plutocms/core (modules/pluto-css). Do not edit. */',
-    "/* Each Pluto layer's app/assets/css/pluto-layer.css, base layer first. */",
+    `/* Each Pluto layer's app/${name}, base layer first. */`,
     ...files.map((file) => cssImport(file, buildDir)),
     '',
   ].join('\n')
@@ -70,14 +93,19 @@ 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}";`,
+    // The admin shows public components too: the post preview, the 3D preview.
+    `@import "${PLUTO_BASE_CSS_IMPORT}";`,
     '',
   ].join('\n')
 }
@@ -111,17 +139,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 +152,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 +167,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 +190,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 +220,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,
@@ -12,39 +13,52 @@ import {
   analyzeCssEntry,
   checkCssSetup,
   findLayerCssFiles,
+  LAYER_BASE_CSS_FILE,
+  PLUTO_BASE_CSS_IMPORT,
   PLUTO_CSS_IMPORT,
   PLUTO_SITE_CSS_IMPORT,
+  renderPlutoAdminCss,
+  renderPlutoBaseCss,
   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.
+ * - `@plutocms/css/base` (opt-in) is an alias of `#build/pluto-base.css`: each
+ *   layer's app/assets/css/pluto-base.css, the plain CSS look of its public
+ *   components. It needs no Tailwind. The admin build imports it too.
  * - 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.
  */
@@ -76,18 +90,96 @@ export default defineNuxtModule<PlutoCssOptions>({
       getContents: () => renderPlutoSiteCss(siteTheme, nuxt.options.buildDir),
     })
 
-    // The names that an app's CSS entry imports. Tailwind resolves `@import`
-    // through the Vite aliases. `/site` comes first: an alias also matches the
-    // paths under its name, so `@plutocms/css` would take `@plutocms/css/site`.
+    // The opt-in plain CSS of the public components, from every layer. An
+    // app imports `@plutocms/css/base`, with or without Tailwind.
+    const layerBaseCssFiles = findLayerCssFiles(
+      layers.map((layer) => layer.app),
+      existsSync,
+      LAYER_BASE_CSS_FILE
+    )
+    addTemplate({
+      filename: 'pluto-base.css',
+      write: true,
+      getContents: () =>
+        renderPlutoBaseCss(layerBaseCssFiles, nuxt.options.buildDir),
+    })
+
+    // The names that an app's CSS entry imports. Tailwind and Vite resolve
+    // `@import` through the aliases. `/site` and `/base` come first: an alias
+    // also matches the paths under its name, so `@plutocms/css` would take them.
     nuxt.options.alias[PLUTO_SITE_CSS_IMPORT] = join(
       nuxt.options.buildDir,
       'pluto-site.css'
     )
+    nuxt.options.alias[PLUTO_BASE_CSS_IMPORT] = join(
+      nuxt.options.buildDir,
+      'pluto-base.css'
+    )
     nuxt.options.alias[PLUTO_CSS_IMPORT] = join(
       nuxt.options.buildDir,
       '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 +204,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.45.0",
+  "version": "0.47.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",