@autono/open-pages 0.1.0 → 0.4.0

package/README.md

@@ -20,9 +20,10 @@ pnpm add @autono/open-pages react react-dom
 
 - **Dev server + workspace viewer** — a home page listing every page with live thumbnails, folders, search, and sort; a per-page viewer at `/p/<id>` with desktop / tablet (820px) / mobile (390px) viewport toggles, reload, and open-in-new-tab.
 - **Inspect mode** — press `i`, click any element on the page to see its exact source line and leave a comment. Comments persist as `@page-comment` markers in the source, ready for a coding agent to apply.
-- **Vite plugin** — discovers `pages/<id>/index.tsx` and `pages/<id>/index.html`, exposes pages via virtual modules, generates a Tailwind v4 stylesheet scoped to `pages/` and `themes/`, hot-reloads on add/remove/edit.
+- **Vite plugin** — discovers `pages/<id>/index.tsx` and `pages/<id>/index.html`, exposes pages via virtual modules, serves the workspace's `styles/globals.css` (Tailwind v4 plus the shadcn tokens) as the page stylesheet, maps `@` to the workspace root, and hot-reloads on add/remove/edit.
+- **shadcn/ui baked in** — a scaffolded workspace ships all 61 components under `ui/`, `lib/utils.ts`, `hooks/`, and a token theme in `styles/globals.css`. Pages import from `@/ui/*`; no `add` step. Themes are `themes/<id>.css` token overrides the runtime injects when a page sets `meta.theme`.
 - **Export CLI** — builds each page into `export/<id>/index.html` plus hashed assets with relative URLs.
-- **Agent skills** — file-based skills (`create-page`, `page-authoring`, `apply-comments`, `create-theme`, `current-page`) that sync into workspaces; no MCP server required.
+- **Agent skills** — file-based skills (`create-page`, `page-authoring`, `apply-comments`, `create-theme`, `current-page`, and the official `shadcn` skill) that sync into workspaces; no MCP server required.
 
 ## CLI
 
@@ -39,10 +40,11 @@ Once installed, the `open-pages` bin is available in the workspace:
 
 ## Authoring
 
-A page is one folder under `pages/` with an `index.tsx` that default-exports a React component. Style with Tailwind via `className`; it is a real web page, so hooks, state, and browser APIs all work.
+A page is one folder under `pages/` with an `index.tsx` that default-exports a React component. Compose from the bundled shadcn components, style with Tailwind via `className`; it is a real web page, so hooks, state, and browser APIs all work.
 
 ```tsx
 import type { PageMeta } from '@autono/open-pages';
+import { Button } from '@/ui/button';
 
 export const meta: PageMeta = {
   title: 'Hello, open-pages',
@@ -51,9 +53,10 @@ export const meta: PageMeta = {
 
 export default function Page() {
   return (
-    <main className="mx-auto max-w-2xl px-6 py-24">
+    <main className="min-h-screen bg-background px-6 py-24 text-foreground">
       <h1 className="text-5xl font-bold tracking-tight">Hello, open-pages</h1>
-      <p className="mt-4 text-lg text-slate-600">This is a real web page.</p>
+      <p className="mt-4 text-lg text-muted-foreground">This is a real web page.</p>
+      <Button className="mt-8">Get started</Button>
     </main>
   );
 }

package/dist/{build-TP72kiw7.js → build-L50pau9v.js}

@@ -1,9 +1,9 @@
 import "./design-C13iz9_4.js";
-import { findPages, loadUserConfig } from "./open-pages-plugin-D_DN_zjh.js";
-import { createViteConfig } from "./config-L0IbktJ0.js";
+import { findPages, loadUserConfig } from "./open-pages-plugin-C0poXLsx.js";
+import { createViteConfig } from "./config-CDUdFE8N.js";
 import "./update-package-Cxt57pz7.js";
 import { readCoreVersion } from "./version-B6AiiGvT.js";
-import { buildPage } from "./export-ic28osQP.js";
+import { buildPage } from "./export-DbVwSmKW.js";
 import path from "node:path";
 import { build as build$1, mergeConfig } from "vite";
 

package/dist/cli/bin.js

@@ -57,19 +57,19 @@ async function run(argv) {
 	program.name("open-pages").description("Author web pages — we handle the Vite/React stack.").version(version, "-v, --version", "print version").helpOption("-h, --help", "show help").showHelpAfterError(chalk.dim("(run `open-pages --help` for usage)"));
 	program.command("dev").description("Start the dev server").addOption(new Option("-p, --port <port>", "port to listen on").argParser(parsePort)).addOption(new Option("--host [host]", "expose on the network (optional host)")).option("--open", "open the browser on start").option("--no-skills-check", "skip the built-in skills drift check").action(async (flags) => {
 		if (flags.skillsCheck !== false) await runSkillsDriftCheck(resolveBuiltinSkillsDir());
-		const { dev } = await import("../dev-I2IyEh5W.js");
+		const { dev } = await import("../dev-CzJYXFOO.js");
 		await dev(flags);
 	});
 	program.command("build").description("Build the workspace as a static site").option("--out-dir <dir>", "output directory (defaults to `dist`)").action(async (flags) => {
-		const { build } = await import("../build-TP72kiw7.js");
+		const { build } = await import("../build-L50pau9v.js");
 		await build(flags);
 	});
 	program.command("preview").description("Preview the production build").addOption(new Option("-p, --port <port>", "port to listen on").argParser(parsePort)).addOption(new Option("--host [host]", "expose on the network (optional host)")).option("--open", "open the browser on start").action(async (flags) => {
-		const { preview } = await import("../preview-BrDuvgAN.js");
+		const { preview } = await import("../preview-CPufRmuj.js");
 		await preview(flags);
 	});
 	program.command("export").description("Build pages into self-contained static folders (one per page)").argument("[pages...]", "page ids to export (default: all)").option("--out-dir <dir>", "output directory (defaults to `export`)").action(async (pages, flags) => {
-		const { exportPages } = await import("../export-B-kBRWB1.js");
+		const { exportPages } = await import("../export-BsK6OCpc.js");
 		await exportPages({
 			pages,
 			outDir: flags.outDir

package/dist/{config-L0IbktJ0.js → config-CDUdFE8N.js}

@@ -1,5 +1,5 @@
 import { defaultDesign } from "./design-C13iz9_4.js";
-import { PAGE_ID_RE, duplicatePageDir, loadUserConfig, openPagesPlugin, resolvePageEntry, rmPageDir, updateMetaTitleInSource, validatePageName } from "./open-pages-plugin-D_DN_zjh.js";
+import { PAGE_ID_RE, duplicatePageDir, invalidatePagesModule, loadUserConfig, openPagesPlugin, resolvePageEntry, rmPageDir, updateMetaTitleInSource, validatePageName } from "./open-pages-plugin-C0poXLsx.js";
 import { detectPackageManager, fetchLatest, formatCommand, invalidateLatestCache, isOutdated, localOpenPagesCommand, runCommand, updateCommandFor } from "./update-package-Cxt57pz7.js";
 import { APP_ROOT, PKG_ROOT, readCoreVersion } from "./version-B6AiiGvT.js";
 import fs from "node:fs/promises";
@@ -2131,6 +2131,7 @@ function registerPageRoutes(server, ctx) {
 					manifest.assignments[duplicated.pageId] = folderId;
 					await writeManifest(ctx.manifestPath, manifest);
 				}
+				invalidatePagesModule(server);
 				return json(res, 200, {
 					ok: true,
 					pageId: duplicated.pageId
@@ -2172,6 +2173,7 @@ function registerPageRoutes(server, ctx) {
 				const manifest = await readManifest(ctx.manifestPath);
 				delete manifest.assignments[pageId];
 				await writeManifest(ctx.manifestPath, manifest);
+				invalidatePagesModule(server);
 				return json(res, 200, { ok: true });
 			}
 			return next();
@@ -2826,10 +2828,14 @@ function designPlugin(opts) {
 
 //#endregion
 //#region src/vite/loc-tags-plugin.ts
-const FORWARDING_COMPONENTS = new Set(["ImagePlaceholder"]);
+const UNTAGGABLE_COMPONENTS = new Set([
+	"Fragment",
+	"StrictMode",
+	"Suspense"
+]);
 function isTaggableJsxName(name) {
 	if (!t.isJSXIdentifier(name)) return false;
-	return /^[a-z]/.test(name.name) || FORWARDING_COMPONENTS.has(name.name);
+	return !UNTAGGABLE_COMPONENTS.has(name.name);
 }
 function alreadyTagged(opening) {
 	return opening.attributes.some((attr) => t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name) && attr.name.name === "data-op-loc");
@@ -2943,11 +2949,14 @@ async function readTheme(mdAbs, themesRoot) {
 			break;
 		}
 	}
+	const cssPath = path.join(themesRoot, `${id}.css`);
+	const cssAbs = existsSync(cssPath) ? cssPath : null;
 	return {
 		id,
 		frontmatter: fm,
 		body,
-		demoAbs
+		demoAbs,
+		cssAbs
 	};
 }
 function generateThemesModule(themes, isDev) {
@@ -2956,7 +2965,8 @@ function generateThemesModule(themes, isDev) {
 		name: t$4.frontmatter.name,
 		description: t$4.frontmatter.description,
 		body: t$4.body,
-		hasDemo: t$4.demoAbs !== null
+		hasDemo: t$4.demoAbs !== null,
+		hasCss: t$4.cssAbs !== null
 	}));
 	const cases = themes.flatMap((t$4) => {
 		const abs = t$4.demoAbs;
@@ -2965,8 +2975,24 @@ function generateThemesModule(themes, isDev) {
 		const importExpr = isDev ? `import(/* @vite-ignore */ import.meta.env.BASE_URL + ${JSON.stringify(importPath)})` : `import(${JSON.stringify(importPath)})`;
 		return [`    case ${JSON.stringify(t$4.id)}: return ${importExpr};`];
 	}).join("\n");
+	const withCss = themes.filter((t$4) => t$4.cssAbs !== null);
+	const cssCases = withCss.map((t$4) => {
+		const importPath = isDev ? `@fs/${normalizePath(t$4.cssAbs).replace(/^\/+/, "")}` : t$4.cssAbs;
+		const importExpr = isDev ? `import(/* @vite-ignore */ import.meta.env.BASE_URL + ${JSON.stringify(importPath)})` : `import(${JSON.stringify(importPath)})`;
+		return `    case ${JSON.stringify(t$4.id)}: return ${importExpr};`;
+	}).join("\n");
 	return `// virtual:open-pages/themes — generated
 export const themes = ${JSON.stringify(meta)};
+export const themeCssIds = ${JSON.stringify(withCss.map((t$4) => t$4.id))};
+
+// Importing a stylesheet through Vite injects it into the document; the
+// frame calls this for a page's meta.theme and for theme demos.
+export async function loadThemeCss(id) {
+  switch (id) {
+${cssCases}
+    default: return;
+  }
+}
 
 export async function loadThemeDemo(id) {
   switch (id) {
@@ -3001,7 +3027,7 @@ function themesPlugin(opts) {
 				const rel = path.relative(themesRoot, p);
 				if (rel.startsWith("..") || path.isAbsolute(rel)) return false;
 				if (rel.includes(path.sep)) return false;
-				return /\.(md|demo\.(tsx|jsx|ts|js))$/.test(rel);
+				return /\.(md|css|demo\.(tsx|jsx|ts|js))$/.test(rel);
 			};
 			let reloadTimer = null;
 			const reload = () => {
@@ -3073,7 +3099,8 @@ async function createViteConfig(opts) {
 			})
 		],
 		resolve: { alias: {
-			"@": APP_ROOT,
+			"~": APP_ROOT,
+			"@": userCwd,
 			"@assets": assetsAbs
 		} },
 		optimizeDeps: {

package/dist/{dev-I2IyEh5W.js → dev-CzJYXFOO.js}

@@ -1,6 +1,6 @@
 import "./design-C13iz9_4.js";
-import "./open-pages-plugin-D_DN_zjh.js";
-import { DEV_SUPERVISED_ENV, RESTART_EXIT_CODE, createViteConfig } from "./config-L0IbktJ0.js";
+import "./open-pages-plugin-C0poXLsx.js";
+import { DEV_SUPERVISED_ENV, RESTART_EXIT_CODE, createViteConfig } from "./config-CDUdFE8N.js";
 import "./update-package-Cxt57pz7.js";
 import "./version-B6AiiGvT.js";
 import chalk from "chalk";

package/dist/export-BsK6OCpc.js

@@ -0,0 +1,4 @@
+import "./open-pages-plugin-C0poXLsx.js";
+import { buildPage, exportPages } from "./export-DbVwSmKW.js";
+
+export { exportPages };

package/dist/{export-ic28osQP.js → export-DbVwSmKW.js}

@@ -1,7 +1,8 @@
-import { extractMeta, findPages, loadUserConfig, openPagesPlugin } from "./open-pages-plugin-D_DN_zjh.js";
+import { extractMeta, findPages, loadUserConfig, openPagesPlugin } from "./open-pages-plugin-C0poXLsx.js";
 import chalk from "chalk";
 import { mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { existsSync } from "node:fs";
 import tailwindcss from "@tailwindcss/vite";
 import react from "@vitejs/plugin-react";
 import { build } from "vite";
@@ -33,6 +34,8 @@ async function buildPage(opts) {
 		const meta = extractMeta(await readFile(entry.file, "utf8"));
 		const title = escapeHtml(meta.title ?? entry.id);
 		const description = extractDescription(await readFile(entry.file, "utf8"));
+		const themeCss = meta.theme ? path.resolve(userCwd, config.themesDir ?? "themes", `${meta.theme}.css`) : null;
+		const themeImport = themeCss && existsSync(themeCss) ? `import ${JSON.stringify(themeCss)};` : "";
 		await writeFile(path.join(root, "index.html"), [
 			"<!doctype html>",
 			"<html lang=\"en\">",
@@ -51,6 +54,7 @@ async function buildPage(opts) {
 		].filter((l) => l !== "").join("\n"), "utf8");
 		await writeFile(path.join(root, "entry.tsx"), [
 			"import 'virtual:open-pages/pages.css';",
+			themeImport,
 			"import { StrictMode } from 'react';",
 			"import { createRoot } from 'react-dom/client';",
 			`import Page from ${JSON.stringify(entry.file)};`,
@@ -61,7 +65,7 @@ async function buildPage(opts) {
 			"  </StrictMode>,",
 			");",
 			""
-		].join("\n"), "utf8");
+		].filter((l) => l !== "").join("\n"), "utf8");
 	}
 	await build({
 		root,
@@ -78,7 +82,10 @@ async function buildPage(opts) {
 				coreVersion
 			})
 		],
-		resolve: { alias: { "@assets": assetsAbs } },
+		resolve: { alias: {
+			"@": userCwd,
+			"@assets": assetsAbs
+		} },
 		build: {
 			outDir,
 			emptyOutDir: true,

package/dist/{open-pages-plugin-D_DN_zjh.js → open-pages-plugin-C0poXLsx.js}

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { loadConfigFromFile, normalizePath } from "vite";
 import { parse } from "@babel/parser";
 import { createRequire } from "node:module";
@@ -267,6 +267,11 @@ const PAGES_VMOD = "virtual:open-pages/pages";
 const CONFIG_VMOD = "virtual:open-pages/config";
 const FOLDERS_VMOD = "virtual:open-pages/folders";
 const PAGES_CSS_VMOD = "virtual:open-pages/pages.css";
+const WORKSPACE_SOURCE_DIRS = [
+	"ui",
+	"lib",
+	"hooks"
+];
 const ENTRY_GLOB = "*/index.{tsx,jsx,ts,js,html}";
 const REACT_ENTRY_RE = /^index\.(tsx|jsx|ts|js)$/;
 async function readFoldersManifest(file) {
@@ -288,6 +293,11 @@ async function readFoldersManifest(file) {
 function resolved(id) {
 	return `\0${id}`;
 }
+function invalidatePagesModule(server) {
+	const mod = server.moduleGraph.getModuleById(resolved(PAGES_VMOD));
+	if (mod) server.moduleGraph.invalidateModule(mod);
+	server.ws.send({ type: "full-reload" });
+}
 /**
 * Every `pages/<id>/index.*` entry. A folder with both a React entry and an
 * `index.html` is a React page — the HTML is then a plain asset of the page.
@@ -443,6 +453,21 @@ ${cases}
 function pagesCssFile(userCwd) {
 	return path.join(userCwd, "node_modules", ".open-pages", "pages.css");
 }
+/**
+* The workspace's own stylesheet when it has one (the shadcn `tailwind.css`
+* entry from components.json, default `styles/globals.css`) — it carries the
+* theme tokens every installed component reads. Falls back to the generated
+* file for workspaces scaffolded without one.
+*/
+function workspaceCssFile(userCwd) {
+	let rel = "styles/globals.css";
+	try {
+		const cfg = JSON.parse(readFileSync(path.join(userCwd, "components.json"), "utf8"));
+		if (typeof cfg.tailwind?.css === "string" && cfg.tailwind.css) rel = cfg.tailwind.css;
+	} catch {}
+	const abs = path.resolve(userCwd, rel);
+	return existsSync(abs) ? abs : null;
+}
 const TAILWIND_CSS = normalizePath(createRequire(import.meta.url).resolve("tailwindcss/index.css"));
 function writePagesCss(userCwd, sources) {
 	const file = pagesCssFile(userCwd);
@@ -456,6 +481,9 @@ function rewriteHtmlUrls(html, pageDir) {
 	const prefix = `/@fs/${normalizePath(pageDir).replace(/^\/+/, "")}/`;
 	return html.replace(/(\s(?:src|href)=)(["'])(?!\/|[a-z][a-z0-9+.-]*:|#|\2)(?:\.\/)?([^"']+)\2/gi, (_m, attr, quote, rel) => `${attr}${quote}${prefix}${rel}${quote}`);
 }
+function pagesSignature(entries) {
+	return entries.map((e) => `${e.id}:${e.kind}:${e.file}`).join(",");
+}
 function openPagesPlugin(opts) {
 	const { userCwd, config, coreVersion } = opts;
 	const pagesDir = config.pagesDir ?? "pages";
@@ -465,6 +493,7 @@ function openPagesPlugin(opts) {
 	const foldersManifestPath = path.join(pagesRoot, ".folders.json");
 	let isDev = false;
 	let cssFile = "";
+	let generatedSignature = "";
 	const pageIdForEntry = (p) => {
 		const rel = path.relative(pagesRoot, p);
 		if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
@@ -502,7 +531,11 @@ function openPagesPlugin(opts) {
 		name: "open-pages",
 		config(_c, env) {
 			isDev = env.command === "serve";
-			cssFile = writePagesCss(userCwd, [pagesRoot, themesRoot]);
+			cssFile = workspaceCssFile(userCwd) ?? writePagesCss(userCwd, [
+				pagesRoot,
+				themesRoot,
+				...WORKSPACE_SOURCE_DIRS.map((d) => path.join(userCwd, d))
+			]);
 			return { server: { fs: { allow: [userCwd] } } };
 		},
 		resolveId(id) {
@@ -515,6 +548,7 @@ function openPagesPlugin(opts) {
 		async load(id) {
 			if (id === resolved(PAGES_VMOD)) {
 				const entries = await findPages(userCwd, pagesDir);
+				generatedSignature = pagesSignature(entries);
 				const { code, ignored } = await generatePagesModule(entries, isDev);
 				for (const pageId of ignored) {
 					if (warnedInvalidPageIds.has(pageId)) continue;
@@ -555,13 +589,18 @@ function openPagesPlugin(opts) {
 			let reloadTimer = null;
 			const reload = () => {
 				if (reloadTimer) clearTimeout(reloadTimer);
-				reloadTimer = setTimeout(() => {
+				reloadTimer = setTimeout(async () => {
 					reloadTimer = null;
-					const mod = server.moduleGraph.getModuleById(resolved(PAGES_VMOD));
-					if (mod) server.moduleGraph.invalidateModule(mod);
-					server.ws.send({ type: "full-reload" });
+					try {
+						const entries = await findPages(userCwd, pagesDir);
+						if (pagesSignature(entries) === generatedSignature) return;
+					} catch (err) {
+						server.config.logger.error(`[open-pages] failed to rescan pages: ${err}`, { error: err instanceof Error ? err : void 0 });
+					}
+					invalidatePagesModule(server);
 				}, 150);
 			};
+			const isPageDir = (p) => path.dirname(p) === pagesRoot;
 			if (existsSync(pagesRoot)) server.watcher.add(pagesRoot);
 			server.watcher.on("add", (p) => {
 				if (pageIdForEntry(p)) reload();
@@ -569,6 +608,12 @@ function openPagesPlugin(opts) {
 			server.watcher.on("unlink", (p) => {
 				if (pageIdForEntry(p)) reload();
 			});
+			server.watcher.on("addDir", (p) => {
+				if (isPageDir(p)) reload();
+			});
+			server.watcher.on("unlinkDir", (p) => {
+				if (isPageDir(p)) reload();
+			});
 			server.watcher.on("change", (p) => {
 				const entry = pageIdForEntry(p);
 				if (entry?.kind === "html") queuePageChanged(server, entry.id);
@@ -629,4 +674,4 @@ async function loadUserConfig(userCwd) {
 }
 
 //#endregion
-export { PAGE_ID_RE, duplicatePageDir, extractMeta, findPages, loadUserConfig, openPagesPlugin, resolvePageEntry, rmPageDir, updateMetaTitleInSource, validatePageName };
+export { PAGE_ID_RE, duplicatePageDir, extractMeta, findPages, invalidatePagesModule, loadUserConfig, openPagesPlugin, resolvePageEntry, rmPageDir, updateMetaTitleInSource, validatePageName };

package/dist/{preview-BrDuvgAN.js → preview-CPufRmuj.js}

@@ -1,6 +1,6 @@
 import "./design-C13iz9_4.js";
-import "./open-pages-plugin-D_DN_zjh.js";
-import { createViteConfig } from "./config-L0IbktJ0.js";
+import "./open-pages-plugin-C0poXLsx.js";
+import { createViteConfig } from "./config-CDUdFE8N.js";
 import "./update-package-Cxt57pz7.js";
 import "./version-B6AiiGvT.js";
 import { mergeConfig, preview as preview$1 } from "vite";

package/dist/vite/index.js

@@ -1,6 +1,6 @@
 import "../design-C13iz9_4.js";
-import "../open-pages-plugin-D_DN_zjh.js";
-import { createViteConfig } from "../config-L0IbktJ0.js";
+import "../open-pages-plugin-C0poXLsx.js";
+import { createViteConfig } from "../config-CDUdFE8N.js";
 import "../update-package-Cxt57pz7.js";
 import "../version-B6AiiGvT.js";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autono/open-pages",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "Runtime and CLI for open-pages — live preview of React and HTML pages, click-to-comment inspector, and static export.",
   "type": "module",
   "exports": {
@@ -84,8 +84,8 @@
     "fast-glob": "^3.3.2",
     "lucide-react": "^1.25.0",
     "next-themes": "^0.4.6",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "react-router-dom": "^7.18.1",
     "shadcn": "^4.19.0",
     "sonner": "^2.0.7",
@@ -93,13 +93,13 @@
     "tailwindcss": "^4.2.2",
     "tw-animate-css": "^1.4.0",
     "use-sync-external-store": "^1.6.0",
-    "vite": "^5.4.10"
+    "vite": "^6.4.3"
   },
   "devDependencies": {
     "@playwright/test": "~1.62.1",
     "@types/node": "^22.19.17",
-    "@types/react": "^18.3.12",
-    "@types/react-dom": "^18.3.1",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
     "tsdown": "^0.9.9",
     "typescript": "^5.9.3"
   }

package/skills/apply-comments/SKILL.md

@@ -9,7 +9,7 @@ The open-pages viewer has an inspector that lets the user click any element on t
 
 Your job: read those markers, perform the described edits, and delete the markers.
 
-> **Before making any page edit**, consult the **`page-authoring`** skill — it is the technical reference for how a page is structured (file contract, `className` styling, layout and responsive rules, type scale, interactivity). A comment like *"make this bigger"* or *"change the accent colour"* should be applied in a way that stays consistent with those rules and still works on mobile.
+> **Before making any page edit**, consult the **`page-authoring`** skill (and the **`shadcn`** skill for component props and variants) — it is the technical reference for how a page is structured (file contract, `className` styling, layout and responsive rules, type scale, interactivity). A comment like *"make this bigger"* or *"change the accent colour"* should be applied in a way that stays consistent with those rules and still works on mobile.
 
 ## Marker format
 
@@ -38,8 +38,8 @@ Your job: read those markers, perform the described edits, and delete the marker
    - If there are no markers, tell the user and stop.
 
 3. **Understand each comment in context.**
-   - The targeted JSX element is the **enclosing** element of the marker — i.e. read upward from the marker line until you reach the unclosed JSX opening tag whose body the marker lives in. That element is the target. (For self-closing elements like `<img />`, the inspector hoists the marker to the nearest non-self-closing ancestor; in that case the comment usually refers to a child of the enclosing element rather than the enclosing element itself — use the `note` text to disambiguate.)
-   - Read enough surrounding code (parent element, sibling elements, `className` strings, any state the element depends on) to apply the change faithfully. A comment inside a `<button>` with an `onClick` may be about behaviour, not looks.
+   - The targeted JSX element is the **enclosing** element of the marker — i.e. read upward from the marker line until you reach the unclosed JSX opening tag whose body the marker lives in. That element is the target. It is often a shadcn component (`<Button>`, `<Card>`, `<TabsTrigger>`): the inspector tags components too, so a click on the rendered button lands on the `<Button>` line in the page, never inside `ui/*.tsx`. (For self-closing elements like `<img />`, the inspector hoists the marker to the nearest non-self-closing ancestor; in that case the comment usually refers to a child of the enclosing element rather than the enclosing element itself — use the `note` text to disambiguate.)
+   - Read enough surrounding code (parent element, sibling elements, `className` strings, any state the element depends on) to apply the change faithfully. A comment inside a `<Button>` with an `onClick` may be about behaviour, not looks. Apply look changes with the component's variants and semantic tokens (`variant="outline"`, `bg-muted`), not raw colors; if the comment really wants a different palette across the page, say so — that is a theme change, not a page edit.
    - If the marker sits inside a `.map` body, the comment applies to the row template — every rendered row changes. If the user clearly meant one item ("make the *middle* one green"), change the data or add a per-item field rather than special-casing the JSX.
    - If the `note` is ambiguous, do the smallest reasonable interpretation and mention the assumption in your summary.
 
@@ -81,6 +81,6 @@ You can run this inline via `node -e '...'` if you need to inspect a payload; ot
 
 ## Do not
 
-- Do not touch `package.json`, `open-pages.config.ts`, or files outside `pages/`.
+- Do not touch `package.json`, `open-pages.config.ts`, `ui/`, `lib/`, `hooks/`, `styles/globals.css`, or any file outside `pages/`. A comment that asks to change a shared component ("make all buttons rounder") is applied by wrapping in the page, or flagged as a theme/`ui/` change for the user to decide.
 - Do not add dependencies.
 - Do not re-introduce markers or leave `TODO` breadcrumbs — the user already has a record in git.

package/skills/create-page/SKILL.md

@@ -5,7 +5,9 @@ description: Use this skill when the user wants to create, build, draft, or gene
 
 # Create a page in open-pages
 
-This skill owns the **workflow** for building a new page. The technical reference — file contract, Tailwind via `className`, layout and responsive rules, type scale, interactivity, assets — lives in the **`page-authoring`** skill. Read that skill whenever you need details on *how* a page is structured. This skill assumes you'll consult it before writing code.
+This skill owns the **workflow** for building a new page. The technical reference — file contract, composing from the preinstalled shadcn/ui set under `ui/`, semantic tokens, layout and responsive rules, type scale, interactivity, assets — lives in the **`page-authoring`** skill. Read that skill whenever you need details on *how* a page is structured. This skill assumes you'll consult it before writing code. Component-level questions (props, variants, blocks, registries) go to the vendored **`shadcn`** skill.
+
+Every workspace already ships the full shadcn/ui set (`ui/`), `lib/utils.ts`, `hooks/`, and `styles/globals.css` with the neutral OKLCH tokens. Nothing needs `npx shadcn add`; pages import `@/ui/<name>` and compose.
 
 You only write files under `pages/<id>/`. Never modify `package.json`, `open-pages.config.ts`, or existing pages.
 
@@ -13,8 +15,8 @@ You only write files under `pages/<id>/`. Never modify `package.json`, `open-pag
 
 List files under `themes/`. If any theme markdown files exist (anything other than `README.md`), call `AskUserQuestion` with each theme id as an option plus a final **"no theme — design from scratch"** option. (`AskUserQuestion` holds at most 4 options — with 4+ themes, offer the 3 most topic-relevant plus "no theme"; the auto-added "Other" lets the user name any omitted theme.)
 
-- If the user picks a theme: read `themes/<id>.md` end-to-end. The theme's palette, typography, and fixed components are now authoritative — copy them directly into the page. **Also set `theme: '<theme-id>'` on the `meta` export** so the page back-links to the theme. In Step 2, skip the **visual direction** question (the theme already commits to one); confirm the page's purpose itself before moving on. Sections and interactivity are independent of theme — ask those normally.
-- If the user picks "no theme", or `themes/` contains no theme markdown files: proceed to Step 2 unchanged.
+- If the user picks a theme: read `themes/<id>.md` end-to-end. Its direction, fonts, and component notes are now authoritative. **Set `theme: '<theme-id>'` on the `meta` export** — the runtime injects `themes/<id>.css` (the token overrides) into the page, so you keep writing semantic token classes and never paste color values. In Step 2, skip the **visual direction** question (the theme already commits to one); confirm the page's purpose itself before moving on. Sections and interactivity are independent of theme — ask those normally.
+- If the user picks "no theme", or `themes/` contains no theme markdown files: the page uses the default neutral tokens from `styles/globals.css`. Proceed to Step 2 unchanged.
 
 If you skip the visual-direction question because a theme was picked, restate the theme name in Step 2 so the user can correct course before you start writing.
 
@@ -67,17 +69,32 @@ Sketch the page as an ordered list of sections before writing code. Common shape
 
 Decide the data shape now: which sections render from a typed const array (`.map`), which are explicit component instances — `page-authoring` explains why this matters for the inspector.
 
-## Step 5 — Commit to a visual direction
+## Step 5 — Compose from `ui/`
+
+Before writing code, map every planned section to the shadcn components it should be built from. Pages compose `@/ui/*` first and hand-roll only what shadcn lacks (heroes, marketing feature grids, footers). Typical mappings:
+
+| Page type | Reach for |
+| --- | --- |
+| Landing / marketing | `navigation-menu` or plain links + `sheet` for mobile nav, `button` (CTAs), `badge` (eyebrows), `card` (features, pricing tiers), `tabs` or `switch` (billing toggle), `accordion` (FAQ), `separator` |
+| Dashboard / app UI | `sidebar` (`SidebarProvider` + `SidebarInset`), `table`, `chart`, `card` (KPIs), `tabs`, `select`, `dropdown-menu`, `badge` (status), `skeleton`, `empty` |
+| Form / signup | `form` (react-hook-form + zod) or `field`, `input`, `select`, `checkbox`, `radio-group`, `switch`, `textarea`, `button`, `alert` |
+| Docs / long-form | `sidebar` or a sticky `scroll-area` TOC, `breadcrumb`, prose in a `max-w-[65ch]` column, `kbd`, `table`, `alert` (callouts) |
+| Portfolio / gallery | `carousel`, `aspect-ratio`, `card`, `dialog` (lightbox), `hover-card` |
+| Internal tool | `command` (palette), `combobox`, `resizable`, `context-menu`, `tooltip`, `sonner` (toasts), `alert-dialog` (confirm) |
+
+Write the list down (component per section) so the structure in Step 4 and the code in Step 6 agree. If a section needs something shadcn only ships as a block (`dashboard-01`, `login-03`), the `shadcn` skill explains `npx shadcn@latest view` / `add` for blocks.
+
+## Step 5b — Commit to a visual direction
 
-One palette, one type scale, held for the whole page. The constraints (web type scale, palette structure, contrast) live in `page-authoring` and its `references/typography-and-color.md` — apply them. Define the palette as repeated Tailwind utilities (or a small const map of class strings). Fonts: default to the system stack; load a Google Font or self-hosted file only when the user names one or a theme requires it (`references/assets-and-fonts.md`).
+One type scale, held for the whole page, expressed in the semantic tokens (`bg-background`, `bg-card`, `bg-primary`, `text-muted-foreground`, `border-border`) so a theme can repaint everything. Dark direction = `dark` on the root element, not a hand-picked dark palette. The constraints (web type scale, token system, contrast) live in `page-authoring` and its `references/typography-and-color.md` — apply them. Raw palette classes are for one deliberate brand moment, if any. Fonts: default to the token font; load a Google Font or self-hosted file only when the user names one or a theme requires it (`references/assets-and-fonts.md`).
 
 ## Step 6 — Write `pages/<id>/index.tsx`
 
-Read the **`page-authoring`** skill before writing — file contract, `className` styling, layout and responsive rules, interactivity constraints, assets. Its file-contract example is the starter template. Split large pages into `pages/<id>/components/*.tsx` when a section is more than ~80 lines.
+Read the **`page-authoring`** skill before writing — file contract, `@/ui/*` composition, token styling, layout and responsive rules, interactivity constraints, assets. Its file-contract example is the starter template. Never edit files under `ui/`, `lib/`, `hooks/`, or `styles/` for a page; wrap components under `pages/<id>/components/` when they need a page-specific look. Split large pages into `pages/<id>/components/*.tsx` when a section is more than ~80 lines.
 
 ## Step 7 — Self-review
 
-Run the checklist in `page-authoring` ("Self-review before finishing"). Check all three viewports.
+Run the checklist in `page-authoring` ("Self-review before finishing"): every button/input/card/dialog/tab is a `@/ui` component, colors are tokens, nothing under `ui/` changed. Check all three viewports.
 
 ## Step 8 — Hand off to the user
 
@@ -85,7 +102,8 @@ Tell the user:
 
 - The page id and file path you created.
 - The preview URL — `http://localhost:5173/p/<id>` — hot-reloads on every edit, with Desktop / Tablet / Mobile toggles and **Open** to view the page by itself.
-- That they can hit **Inspect** (or `i`) in the preview, click any element, and leave comments — then ask you to run `apply-comments`.
+- That they can hit **Inspect** (or `i`) in the preview, click any element or component, and leave comments — then ask you to run `apply-comments`.
+- That the look is token-driven: `/create-theme` can restyle the whole page (and every other page) without touching its code.
 - That `open-pages export <id>` writes `export/<id>/` — a static folder (index.html + assets) they can deploy to Netlify, Vercel, Cloudflare Pages, GitHub Pages, or any static host.
 - If dev isn't running: run the project's `dev` script from the project root with its package manager (`npm run dev`, `pnpm dev`, … — match the lockfile).