@autono/create-open-pages 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @autono/create-open-pages
 
-Scaffold a workspace for [open-pages](https://openpages.sh) — the web page framework built for agents. Your coding agent writes pages as React components or plain HTML; you get a live browser preview, click-to-comment, and static export to any host.
+Scaffold a workspace for [open-pages](https://openpages.sh) — the web page framework built for agents. Your coding agent writes pages as React components or plain HTML, with the full shadcn/ui set already installed; you get a live browser preview, click-to-comment, and static export to any host.
 
 ## Usage
 
@@ -13,12 +13,15 @@ npm run dev
 This creates a workspace containing:
 
 - `pages/getting-started/` — a starter page you can edit or delete.
+- `ui/` — all 61 shadcn/ui components, plus `lib/utils.ts` (`cn`) and `hooks/use-mobile.ts`. Pages import `@/ui/button` and friends; nothing to `add`.
+- `styles/globals.css` — Tailwind v4 entry with the shadcn token theme (`:root` / `.dark`). The runtime uses it for preview and export.
+- `components.json` — shadcn config (new-york, radix, `@/ui` aliases) so `npx shadcn@latest add` works for blocks and other registries, and the bundled `shadcn` skill activates.
 - `package.json` — depends on `@autono/open-pages`, which provides the runtime (viewer, inspector, export) and the `open-pages` CLI.
 - `open-pages.config.ts` — optional typed config (pagesDir, port, base).
-- `.claude/skills/` and `.agents/skills/` — agent skills (`create-page`, `page-authoring`, `apply-comments`, `create-theme`, `current-page`).
+- `.claude/skills/` and `.agents/skills/` — agent skills (`create-page`, `page-authoring`, `apply-comments`, `create-theme`, `current-page`, `shadcn`).
 - `AGENTS.md` (linked as `CLAUDE.md`) — agent guide for authoring pages.
 
-You won't see any Vite, React, Tailwind, or tsconfig files in the workspace. They live inside `@autono/open-pages` and you never touch them.
+You won't see any Vite or React config in the workspace. That lives inside `@autono/open-pages`. The shadcn components are yours: real source files under `ui/`, editable like any shadcn project.
 
 ## Flags
 

package/dist/cli.js

@@ -102,7 +102,7 @@ async function isDirNonEmpty(target) {
 	return entries.some((e) => !e.startsWith("."));
 }
 function coreVersionRange() {
-	return `^0.1.0`;
+	return `^0.3.0`;
 }
 async function linkOrCopy(relSrc, dst) {
 	await rm(dst, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autono/create-open-pages",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Scaffold an open-pages workspace — agent skills preconfigured, live real-PDF preview out of the box.",
   "type": "module",
   "bin": {

package/template/.agents/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/template/.agents/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).
 

package/template/.agents/skills/create-theme/SKILL.md

@@ -1,49 +1,106 @@
 ---
 name: create-theme
-description: Use this skill when the user wants to create, draft, author, or extract a page theme in this open-pages repo. Triggers on phrases like "create a theme", "make a theme called X", "extract a theme from <page>", "build a design system from these screenshots", "match our brand". Produces two paired files under `themes/` — `<id>.md` (palette, typography, layout, fixed components) and `<id>.demo.tsx` (a runnable demo page the workspace's Themes panel previews live). Do NOT use for editing real pages — only for authoring the theme bundle.
+description: Use this skill when the user wants to create, draft, author, or extract a theme in this open-pages repo. Triggers on phrases like "create a theme", "make a theme called X", "extract a theme from <page>", "match our brand", "build a design system from these screenshots", "apply this shadcn preset". Produces a three-file bundle under `themes/` — `<id>.md` (direction, fonts, component notes, token table), `<id>.css` (the shadcn token overrides), and `<id>.demo.tsx` (a demo page composed from `ui/` components that the workspace's Themes panel previews live). Do NOT use for editing real pages — only for authoring the theme bundle.
 ---
 
-# Create a page theme
+# Create a theme
 
-This skill produces a **theme bundle** under `themes/`: two paired files that together describe a reusable visual identity for web pages.
+A theme is a **token set**. Every workspace ships the full shadcn/ui set under `ui/`, and every component reads its colors, radius, and fonts from the CSS variables in `styles/globals.css` (`--background`, `--primary`, `--radius`, …). A theme overrides those variables; every component and every token-styled page restyles at once. Nothing is copied into pages.
 
-1. `themes/<id>.md` — agent-facing documentation: palette, typography, layout, fixed components (nav, hero, section wrapper, buttons, card, footer). This is what `create-page` reads when an author picks the theme.
-2. `themes/<id>.demo.tsx` — a runnable demo page (same module shape as `pages/<id>/index.tsx`: **one default-exported component**) that shows the theme on a single scrolling page. The workspace's Themes panel renders it live, exactly like a real page.
+The bundle is three files sharing one stem under `themes/`:
 
-Both files share the same stem so the runtime can pair them automatically.
+1. `themes/<id>.md` — agent-facing direction: aesthetic, fonts, how to use the components in this theme, and a table of token → value. This is what `create-page` reads when an author picks the theme.
+2. `themes/<id>.css` — **only** `:root { … }` and `.dark { … }` blocks overriding the shadcn tokens (plus an optional Google Fonts `@import url(…)` at the very top). No `@theme` block, no Tailwind import, no selectors beyond those two.
+3. `themes/<id>.demo.tsx` — a runnable page module (same shape as `pages/<id>/index.tsx`, **one default-exported component**) composed from `@/ui/*` components so the tokens are shown on real parts. The Themes panel renders it with `<id>.css` injected automatically; the demo does not set `meta.theme`.
 
-The theme markdown is authoring-time direction — `create-page` copies its palette, utilities, and components into a real page's source. The demo `.tsx` is a self-contained preview, not a real page — it does not appear in the pages list.
+A page opts in with `meta.theme: '<id>'`; the runtime injects `themes/<id>.css` into that page's preview frame and into its export.
 
-You only write `themes/<id>.md` and `themes/<id>.demo.tsx`. Never modify real pages or configuration. The styling rules and web defaults that themes override live in the **`page-authoring`** skill — read it before writing the theme so your overrides are stated explicitly.
+You only write the three theme files. Never modify pages, `ui/`, `styles/globals.css`, or configuration. The token names and how pages consume them live in the **`page-authoring`** skill (`references/typography-and-color.md`) — read it first. Component props and variants: the **`shadcn`** skill.
 
 ## Step 1 — Identify the input source
 
-A theme can be derived from any combination of three input shapes:
+A theme can be derived from any combination of:
 
-- **Image references** — paths or URLs to screenshots, mood-board images, brand assets.
+- **A shadcn preset** — a code or URL from https://ui.shadcn.com/create. `npx shadcn@latest preset decode <code>` prints its tokens; or run `npx shadcn@latest apply <code> --only theme,font` in a scratch copy and lift the resulting `:root`/`.dark` values. Never run `apply` against the workspace's `styles/globals.css` directly — that changes the default for every page.
+- **Image references / brand guidelines** — paths or URLs to screenshots, mood boards, logo files, a brand PDF. You will translate them into OKLCH tokens.
 - **Free-text description** — prose describing the desired palette, weight, feel.
-- **An existing page** — `pages/<id>/index.tsx` whose visual identity should be lifted out into a reusable theme.
+- **An existing page** — `pages/<id>/index.tsx` whose look should become reusable.
 
-If the user's original message already specifies the inputs unambiguously, skip the question and proceed. Otherwise call `AskUserQuestion` (multi-select) so they can pick one or more sources, and ask follow-ups (paths, page id, prose) only as needed.
+If the user's original message already specifies the inputs unambiguously, skip the question and proceed. Otherwise call `AskUserQuestion` (multi-select) so they can pick one or more sources, and ask follow-ups (paths, preset code, page id, prose) only as needed.
 
 ## Step 2 — Gather raw inputs
 
-- **Images**: read each path with the `Read` tool (it accepts images). Note dominant colors as hex, type weight and family feel, corner radius, surface treatment (flat vs. cards vs. borders), density, and recurring chrome (nav style, footer).
-- **Text**: extract explicit tokens (hex codes, font names, tone words) and resolve vague language into concrete decisions before writing.
-- **Existing page**: read `pages/<id>/index.tsx` (and `components/`) and pull:
-  - The Tailwind color utilities used consistently (`bg-…`, `text-…`, accent classes) → Palette section.
-  - Type sizes and any font loading (`<link>` to Google Fonts, `font-[…]`) → Typography section.
-  - Container widths, section padding, breakpoints used → Layout section.
-  - Recurring helper components (nav, hero, cards, buttons, footer) → Fixed components section.
-  - The aesthetic feel implied → Aesthetic paragraph.
+- **Preset**: take its tokens as the baseline; adjust only what the user asked to change.
+- **Images**: read each path with the `Read` tool (it accepts images). Note dominant colors (write them as hex, then convert to OKLCH), type family feel, corner radius, surface treatment (flat vs. cards vs. borders), light or dark default, and chrome (nav style, footer).
+- **Text**: extract explicit values (hex codes, font names, "rounded", "sharp", "dense") and resolve vague language into concrete decisions before writing.
+- **Existing page**: read `pages/<id>/index.tsx` (and `components/`) and pull any raw palette classes or hex values into token roles (the page's `bg-[#0b0b10]` root → `--background`; its CTA fill → `--primary`; its card border → `--border`), plus fonts and radius.
 
-When inputs disagree (e.g. images use blue but the description says green), ask the user which to honor.
+Every color ends up as `oklch(L C H)` — the same format as `styles/globals.css`. When inputs disagree (images use blue but the description says green), ask the user which to honor.
 
 ## Step 3 — Pick a theme id
 
 Use **kebab-case**, short, descriptive. Examples: `dark-launch`, `clean-saas`, `editorial-warm`, `ops-console`. Check `themes/` to avoid collisions.
 
-## Step 4 — Write `themes/<id>.md`
+## Step 4 — Write `themes/<id>.css`
+
+Override the full token list for both modes, even when a value equals the default, so the file is self-describing:
+
+```css
+@import url('https://fonts.googleapis.com/css2?family=Inter+Tight:wght@500;700&family=Inter:wght@400;500&display=swap');
+
+:root {
+  --font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
+  --font-heading: 'Inter Tight', var(--font-sans);
+  --radius: 0.75rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.55 0.2 265);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.5 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.55 0.2 265);
+  --chart-1: oklch(0.55 0.2 265);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.55 0.2 265);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.55 0.2 265);
+}
+
+.dark {
+  --background: oklch(0.13 0.01 265);
+  --foreground: oklch(0.985 0 0);
+  /* … every token again, dark values … */
+}
+```
+
+Rules:
+
+- Exactly the shadcn token names (`--background` … `--sidebar-ring`, `--radius`), plus optionally `--font-sans` / `--font-heading` and the font `@import`. Unknown names do nothing; misspelled names silently fall back to the default.
+- `*-foreground` must contrast with its surface (≥ 4.5:1 for body pairs). Check `--muted-foreground` on `--background` and `--primary-foreground` on `--primary` explicitly.
+- A dark-first theme still defines `:root` for light; a page that wants dark puts `dark` on its root element. If the theme is dark-only, make both blocks the dark values.
+- `--radius` sets every radius (`rounded-sm` … `rounded-2xl` scale from it): `0` sharp, `0.5rem` default-ish, `1rem` soft.
+- Fonts load from Google Fonts via `@import url(…)` at the top of this file, or from a self-hosted file the theme tells `create-page` to place under `assets/` (then `@font-face` goes in the page's `styles.css`, not here).
+
+## Step 5 — Write `themes/<id>.md`
 
 Produce a file with this exact section order. Section bodies adapt to the theme; the headings stay consistent across all themes.
 
@@ -55,169 +112,99 @@ description: <one-line elevator pitch>
 
 # <Theme name>
 
-## Palette
+## Tokens
 
-| Role | Tailwind | Hex | Notes |
+| Token | Light | Dark | Role in pages |
 | --- | --- | --- | --- |
-| background | `bg-[#0b0b10]` | #0b0b10 | page root |
-| surface | `bg-white/[0.04] border-white/10` | — | cards, panels |
-| text | `text-white` | #ffffff | headings, body |
-| muted | `text-white/60` | — | secondary copy, labels |
-| accent | `bg-emerald-400 text-black` / `text-emerald-400` | #34d399 | primary CTA, eyebrows |
-| border | `border-white/10` | — | dividers, card edges |
+| `--background` / `--foreground` | `oklch(1 0 0)` / `oklch(0.145 0 0)` | … | page root (`bg-background text-foreground`) |
+| `--primary` / `--primary-foreground` | … | … | the one accent: CTAs, active tabs, links |
+| `--card`, `--muted`, `--accent`, `--secondary` | … | … | surfaces |
+| `--border`, `--input`, `--ring` | … | … | rules, fields, focus |
+| `--destructive` | … | … | delete, errors |
+| `--chart-1…5` | … | … | chart series order |
+| `--radius` | `0.75rem` | | rounded-lg cards, pill buttons via `rounded-full` |
+
+The full set lives in `themes/<id>.css`; this table is the reference for what each value is *for*.
 
 ## Typography
 
-- Font: system stack, or a named family with how to load it (Google Fonts `<link>` rendered in the page, or a self-hosted file the page must place under `assets/`).
-- Type-scale overrides (only list what differs from `page-authoring` defaults):
-  - Hero heading: `text-5xl sm:text-7xl font-bold leading-[1.02] tracking-tight`
-  - Section heading: `text-3xl font-bold tracking-tight`
-  - Body: `text-lg text-white/60`
-  - Eyebrow: `text-xs font-semibold uppercase tracking-[0.25em] text-emerald-400`
+- Fonts: `--font-sans` / `--font-heading` set in the CSS (how they load: Google Fonts `@import`, or a self-hosted file under `assets/`).
+- Type-scale overrides (only what differs from `page-authoring` defaults): hero `text-5xl sm:text-7xl font-heading tracking-tight`; body `text-lg`; eyebrow `<Badge variant="secondary">`.
 
 ## Layout
 
-- Container: `mx-auto max-w-6xl px-6`.
-- Section rhythm: `py-20`, sections separated by `border-t border-white/10`.
-- Breakpoints: single column by default; `sm:grid-cols-3` for feature and pricing grids; nav links `hidden sm:flex`.
-- Radius: `rounded-full` for buttons, `rounded-2xl` for cards.
-
-## Fixed components
-
-These are paste-ready React JSX with `className`. Copy them verbatim into a page that uses this theme.
-
-### Nav
-
-```tsx
-const Nav = ({ brand, links, cta }: { brand: string; links: { label: string; href: string }[]; cta: { label: string; href: string } }) => (
-  <header className="mx-auto flex max-w-6xl items-center justify-between px-6 py-6">
-    <span className="font-semibold tracking-tight">{brand}</span>
-    <nav className="hidden gap-8 text-sm text-white/70 sm:flex">
-      {links.map((l) => (
-        <a key={l.href} href={l.href} className="hover:text-white">{l.label}</a>
-      ))}
-    </nav>
-    <a href={cta.href} className="rounded-full bg-white px-4 py-2 text-sm font-medium text-black hover:bg-white/90">{cta.label}</a>
-  </header>
-);
-```
-
-### Hero
-
-```tsx
-const Hero = ({ eyebrow, title, lede, children }: { eyebrow: string; title: string; lede: string; children?: React.ReactNode }) => (
-  <section className="mx-auto max-w-6xl px-6 pt-20 pb-24 text-center">
-    <p className="text-xs font-semibold uppercase tracking-[0.25em] text-emerald-400">{eyebrow}</p>
-    <h1 className="mx-auto mt-6 max-w-3xl text-5xl font-bold leading-[1.02] tracking-tight sm:text-7xl">{title}</h1>
-    <p className="mx-auto mt-6 max-w-xl text-lg text-white/60">{lede}</p>
-    <div className="mt-10 flex flex-col justify-center gap-3 sm:flex-row">{children}</div>
-  </section>
-);
-```
-
-### Section
-
-```tsx
-const Section = ({ id, children }: { id?: string; children: React.ReactNode }) => (
-  <section id={id} className="border-t border-white/10">
-    <div className="mx-auto max-w-6xl px-6 py-20">{children}</div>
-  </section>
-);
-```
+- Container: `mx-auto max-w-6xl px-6`; section rhythm `py-20`; separators `border-t border-border`.
+- Default mode: light | dark (`dark` on the page root).
+- Density: airy | standard | dense — how much `gap-*` and padding pages should use.
 
-### Buttons
+## Components in this theme
 
-```tsx
-const PrimaryButton = ({ href, children }: { href: string; children: React.ReactNode }) => (
-  <a href={href} className="rounded-full bg-emerald-400 px-6 py-3 font-medium text-black hover:bg-emerald-300">{children}</a>
-);
-const SecondaryButton = ({ href, children }: { href: string; children: React.ReactNode }) => (
-  <a href={href} className="rounded-full border border-white/20 px-6 py-3 font-medium text-white/80 hover:border-white/40">{children}</a>
-);
-```
+Notes on how to use the `ui/` set so pages feel like this theme — which variants to prefer, what to avoid:
 
-### Card
-
-```tsx
-const Card = ({ title, children }: { title: string; children: React.ReactNode }) => (
-  <div className="rounded-2xl border border-white/10 bg-white/[0.03] p-6">
-    <h3 className="font-semibold">{title}</h3>
-    <div className="mt-2 text-white/60">{children}</div>
-  </div>
-);
-```
-
-### Footer
-
-```tsx
-const Footer = ({ left, right }: { left: string; right: string }) => (
-  <footer className="border-t border-white/10">
-    <div className="mx-auto flex max-w-6xl items-center justify-between px-6 py-8 text-sm text-white/40">
-      <span>{left}</span>
-      <span>{right}</span>
-    </div>
-  </footer>
-);
-```
+- Buttons: primary CTA `<Button size="lg">`; secondary `<Button size="lg" variant="outline">`; pill shape via `className="rounded-full"` (or not).
+- Cards: `<Card>` with `border-border`, no shadow | `shadow-sm`.
+- Nav: `<NavigationMenu>` on desktop, `<Sheet>` on mobile; sticky with `bg-background/90 backdrop-blur`.
+- Data: `<Table>` + `<Badge>` for status; charts use `--chart-*` in order.
+- Feedback: `<Alert>`, `sonner` toasts.
+- Avoid: gradients | shadows | more than one accent | … (whatever the theme forbids).
 
 ## Aesthetic
 
-One paragraph. What it feels like, the references it draws on, what to avoid (e.g. "no gradients; one accent only; borders over shadows; motion limited to hover color changes"). Commit to a single direction.
+One paragraph. What it feels like, the references it draws on, what to avoid. Commit to a single direction.
 
 ## Example usage
 
 ```tsx
-<main className="min-h-screen bg-[#0b0b10] text-white antialiased">
-  <Nav brand="Meridian" links={links} cta={{ label: 'Get started', href: '#pricing' }} />
-  <Hero eyebrow="Now in public beta" title="Your analytics, turned into decisions" lede="…">
-    <PrimaryButton href="#pricing">Start free</PrimaryButton>
-    <SecondaryButton href="#features">See how it works</SecondaryButton>
-  </Hero>
-  {/* … */}
-  <Footer left="© 2026 Meridian" right="Built with open-pages" />
+export const meta: PageMeta = { title: '…', theme: '<id>', createdAt: '…' };
+
+<main className="min-h-screen bg-background text-foreground antialiased">
+  <header className="mx-auto flex max-w-6xl items-center justify-between px-6 py-6">…<Button>Get started</Button></header>
+  <section className="mx-auto max-w-6xl px-6 py-20">…</section>
 </main>
 ```
 ````
 
-## Step 4b — Write `themes/<id>.demo.tsx`
+The markdown never contains color values that are not also in the CSS, and never contains paste-ready components with raw colors — pages compose `ui/` and the tokens do the rest.
+
+## Step 6 — Write `themes/<id>.demo.tsx`
 
-The demo is a normal page module — same shape as `pages/<id>/index.tsx`, just sitting under `themes/` so the runtime knows it's preview-only.
+The demo is a normal page module — same shape as `pages/<id>/index.tsx`, sitting under `themes/` so the runtime knows it's preview-only.
 
 Contract:
 
-- `import type { PageMeta } from '@autono/open-pages';` and React hooks as needed.
-- **One default-exported component** — a single scrolling page that exercises the theme: nav, hero with both buttons, a section with a card grid, a footer.
-- Inline the **same** fixed components defined in the theme markdown — verbatim, no abstractions. Demo and markdown must stay in lockstep so what `create-page` pastes matches what the demo shows.
-- Root element sets `min-h-screen`, the theme background, and text color. Must look right at Mobile (390px) as well as Desktop.
-- Content should be plausible and realistic, not lorem ipsum. Self-contained: no `@/` imports, no page-local assets; if the theme names a Google Font, render the `<link>` tag in the demo too.
+- `import type { PageMeta } from '@autono/open-pages';`, `@/ui/*` imports, React hooks as needed. No `meta.theme` (the runtime injects `<id>.css` for demos).
+- **One default-exported component** — a single scrolling page that exercises the tokens on real components: a header with `<Button>`s, a hero, a `<Card>` grid, a `<Tabs>` or `<Accordion>`, a `<Table>` with `<Badge>` status, an `<Input>` + `<Button>` form row, and a footer. Include one dark section (`<div className="dark bg-background text-foreground">`) if the theme is light-first, or one light section if dark-first, so both blocks of the CSS are visible.
+- Root element: `min-h-screen bg-background text-foreground` (with `dark` if the theme is dark by default). Everything token-styled — the demo is the proof that pages need no raw colors.
+- Realistic content, not lorem ipsum. Must look right at Mobile (390px) as well as Desktop. Self-contained: no page-local assets.
 
-## Step 5 — Self-review
+## Step 7 — Self-review
 
-- [ ] Palette table covers background / surface / text / muted / accent / border as Tailwind utilities, with hex where fixed.
-- [ ] Frontmatter has `name` and `description` only (the runtime reads nothing else).
-- [ ] Typography names only fonts the theme explains how to load (or the system stack).
-- [ ] Layout specifies container width, section rhythm, and breakpoints.
-- [ ] Fixed components are paste-ready React JSX (`className`, typed props, no `@/` imports) and cover nav, hero, section, buttons, card, footer.
-- [ ] Aesthetic paragraph names a single coherent direction.
-- [ ] Both files written: `themes/<id>.md` and `themes/<id>.demo.tsx`. No page changes, no config changes.
-- [ ] Demo `.tsx` default-exports one component and inlines the same fixed components as the markdown; contrast holds; nothing overflows on mobile.
+- [ ] `themes/<id>.css` overrides every shadcn token in both `:root` and `.dark`, in OKLCH, with only those two selectors (plus an optional font `@import`).
+- [ ] Every `*-foreground` passes contrast on its surface; `--muted-foreground` is readable on `--background`.
+- [ ] Frontmatter in the `.md` has `name` and `description` only (the runtime reads nothing else).
+- [ ] Typography names only fonts the CSS loads (or the system stack).
+- [ ] "Components in this theme" gives variant guidance for buttons, cards, nav, data, feedback.
+- [ ] Demo `.tsx` default-exports one component, imports only `@/ui/*`, uses semantic tokens only, shows both modes, nothing overflows on mobile.
+- [ ] All three files written with the same stem. No page changes, no `ui/` changes, no `styles/globals.css` changes.
 
-## Step 6 — Hand off
+## Step 8 — Hand off
 
 Tell the user:
 
-- The theme id and the two file paths.
+- The theme id and the three file paths.
 - That the Themes panel in the workspace (`http://localhost:5173/themes`) previews the demo live, and `/create-page` will list the theme as a picker option on its next run.
-- A one-line summary of the look (palette + aesthetic).
+- That any existing page can adopt it by setting `meta.theme: '<id>'` — no other change.
+- A one-line summary of the look (accent, mode, radius, fonts).
 
 Do not run the dev server. Do not modify real pages — the demo `.tsx` is the demonstration.
 
 ## Anti-patterns
 
-- ❌ Writing executable code in `themes/<id>.md` outside the labeled component snippets — the markdown is documentation.
-- ❌ Producing only the markdown without the demo, or only the demo without the markdown. A theme is the **bundle** — both files, every time.
-- ❌ Desktop-only components: a nav with no mobile behaviour, grids with no stacking fallback.
-- ❌ Naming font families the theme never explains how to load.
-- ❌ Inventing palette / styling when the user supplied images or an existing page. Extract, don't fabricate.
-- ❌ Editing `pages/`, `packages/`, `package.json`, or `open-pages.config.ts`.
-- ❌ Skipping Fixed components. Nav, hero, buttons, and footer are the most common reuse targets — they must be paste-ready.
+- ❌ Pasting token values into pages, or theme markdown full of `bg-[#hex]` snippets. Tokens live in the CSS; pages stay semantic.
+- ❌ `@theme inline`, `@import "tailwindcss"`, `@source`, or selectors other than `:root`/`.dark` in `themes/<id>.css`.
+- ❌ Editing `styles/globals.css` or running `npx shadcn apply` against the workspace — that silently rethemes every page.
+- ❌ Producing one or two of the three files. A theme is the **bundle** — `.md`, `.css`, `.demo.tsx`, every time.
+- ❌ A demo with raw colors or hand-rolled buttons — it must prove the tokens carry the look through `ui/`.
+- ❌ Naming font families the CSS never loads.
+- ❌ Inventing values when the user supplied a preset, images, or an existing page. Extract, don't fabricate.
+- ❌ Editing `pages/`, `ui/`, `packages/`, `package.json`, or `open-pages.config.ts`.

package/template/.agents/skills/current-page/SKILL.md

@@ -49,7 +49,7 @@ Path is relative to the project root (the user's `cwd`, the directory that conta
 - `view` — `"pages"` when the user is viewing the page, `"assets"` when they are browsing that page's files in the asset manager rather than the page itself.
 - `selection` — `null` if nothing is selected. Otherwise, the JSX element the user picked in the inspector:
   - `line` (1-indexed) and `column` (0-indexed) point to the JSX opening tag in the page source. This is the canonical handle — match against the source line.
-  - `tagName` is the rendered HTML tag, lowercased (`"h1"`, `"div"`, `"button"`).
+  - `tagName` is the rendered HTML tag, lowercased (`"h1"`, `"div"`, `"button"`). The source line it points at may be a shadcn component rather than that tag — a `"button"` selection usually lands on a `<Button>` line in the page, because `ui/` components spread the inspector tag onto their root. Edit the page line; never follow it into `ui/*.tsx`.
   - `text` is a trimmed text snippet (≤120 chars) of the element's content — a sanity check that you're looking at the right node.
   - Selection auto-clears whenever the user navigates to a different page or clears it in the viewer. HTML pages never produce a selection.
 - `updatedAt` — ISO timestamp of the last navigation or selection change. Use it to detect staleness.