@autono/open-pages 0.7.0 → 0.9.0

package/skills/create-page/SKILL.md

@@ -94,7 +94,11 @@ Read the **`page-authoring`** skill before writing — file contract, `@/ui/*` c
 
 ## Step 7 — Self-review
 
-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.
+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. Pay particular attention to the CTA and motion items: one label per intent, no wrapped button text at desktop, every animation answers "what does this communicate?".
+
+## Step 7b — Guidelines review
+
+Run the `web-design-guidelines` skill on `pages/<id>/` (it fetches Vercel's current Web Interface Guidelines and reports `file:line` findings). Fix what it finds in the page files, re-run until clean or until only findings you can justify remain, and mention any you left in the hand-off.
 
 ## Step 8 — Hand off to the user
 

package/skills/create-theme/SKILL.md

@@ -1,21 +1,22 @@
 ---
 name: create-theme
-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.
+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", "email theme for X". Produces a 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) — plus `components/email/theme-<id>.ts`, the same palette as an emailcn EmailTheme so emails match. Do NOT use for editing real pages — only for authoring the theme bundle.
 ---
 
 # Create a theme
 
 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.
 
-The bundle is three files sharing one stem under `themes/`:
+The bundle is three files sharing one stem under `themes/`, plus one under `components/email/`:
 
 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`.
+4. `components/email/theme-<id>.ts` — the same palette as an emailcn `EmailTheme` object (hex colors, px sizes, font stacks), generated from the CSS by a script (Step 6b). Mail clients cannot read CSS variables or `oklch()`, so this is how emails under `emails/` pick the theme up; the `create-email` skill consumes it.
 
-A page opts in with `meta.theme: '<id>'`; the runtime injects `themes/<id>.css` into that page's preview frame and into its export.
+A page opts in with `meta.theme: '<id>'`; the runtime injects `themes/<id>.css` into that page's preview frame and into its export. An email opts in by passing the exported theme object to `createEmailTailwindConfig` (or to a section's `theme` prop).
 
-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.
+You only write these four files. Never modify pages, emails, `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
 
@@ -25,6 +26,7 @@ A theme can be derived from any combination of:
 - **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 look should become reusable.
+- **A `DESIGN.md`** — a design-system document in the Google-spec shape (YAML frontmatter, then Overview, Colors, Typography, Layout, Elevation, Shapes, Components, Do's and Don'ts). [designmd.supply](https://designmd.supply) generates one from any public domain, so "match our brand" is: run the site through it, drop the file at `themes/<id>.design.md` (or paste the path), and ask for a theme.
 
 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.
 
@@ -34,6 +36,7 @@ If the user's original message already specifies the inputs unambiguously, skip
 - **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.
+- **`DESIGN.md`**: read it and map sections onto tokens — **Colors** gives `--background`/`--foreground`, `--primary`, `--secondary`, `--accent`, `--muted`, `--destructive` (primary = the brand's main action color, not its logo color, when they differ); **Typography** gives `--font-sans` / `--font-heading` and the type-scale feel; **Shapes** gives `--radius`; **Elevation** decides flat vs. card-with-shadow treatment in the component notes; **Layout** informs container widths and density in the demo; **Components** and **Do's and Don'ts** become the "Components in this theme" guidance. Colors may arrive as hex, `rgb()`, `hsl()`, `oklch()`, or CSS named colors — parse each by its own syntax, then convert to OKLCH. A single light palette is normal; derive the `.dark` block from it (invert lightness, keep hue and chroma) and say so in the `.md`.
 
 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.
 
@@ -148,6 +151,11 @@ Notes on how to use the `ui/` set so pages feel like this theme — which varian
 - Feedback: `<Alert>`, `sonner` toasts.
 - Avoid: gradients | shadows | more than one accent | … (whatever the theme forbids).
 
+## Email
+
+- `components/email/theme-<id>.ts` exports `<id>Theme`, generated from this CSS. Emails pass it to `createEmailTailwindConfig` or to a section's `theme` prop.
+- Any email-specific notes: which emailcn sections suit the brand, whether headings keep the serif via `<Font>`, what the footer must carry.
+
 ## Aesthetic
 
 One paragraph. What it feels like, the references it draws on, what to avoid. Commit to a single direction.
@@ -177,6 +185,21 @@ Contract:
 - 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 6b — Generate `components/email/theme-<id>.ts`
+
+Emails are rendered by react-email with emailcn's `createEmailTailwindConfig(theme)`, which takes a plain `EmailTheme` object, not CSS variables. Derive it from the finished CSS with the script that ships with this skill:
+
+```bash
+# once per workspace, if components/email/email-theme.ts does not exist yet
+npx shadcn@latest add @emailcn/react-email/theme-default
+
+node .agents/skills/create-theme/references/email-theme-from-css.mjs themes/<id>.css <id> > components/email/theme-<id>.ts
+```
+
+The script reads the `:root` block (emails are light documents; the `.dark` block is not used), converts every color to hex, and maps roles by `references/email-theme.md`: `--background` → `colorBackground`, `--foreground` → `colorText`, `--muted` / `--muted-foreground` → `colorBackgroundMuted` / `colorTextMuted`, `--secondary` → `colorBackgroundSubtle`, `--primary` / `--primary-foreground` → `colorPrimary` / `colorPrimaryForeground` and the primary button, `--border` → `colorBorder` and the secondary button's border, `--destructive` → `colorDanger`, `--radius` → `borderRadius` in px, `--font-sans` / `--font-mono` → `fontFamily` / `fontFamilyMono` with `var()` entries dropped. Success, warning, the type scale, and spacing keep emailcn's defaults because the CSS has no opinion on them.
+
+Open the generated file and review it: a web font in `fontFamily` needs a web-safe fallback after it (the script keeps whatever fallbacks the CSS listed), and `colorPrimaryHover` / `colorTextSubtle` are shifted from their base tokens, so glance that they still read well. Do not restyle it by hand beyond that; re-run the script after changing the CSS so the two never drift.
+
 ## Step 7 — Self-review
 
 - [ ] `themes/<id>.css` overrides every shadcn token in both `:root` and `.dark`, in OKLCH, with only those two selectors (plus an optional font `@import`).
@@ -185,15 +208,17 @@ Contract:
 - [ ] 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.
+- [ ] `components/email/theme-<id>.ts` generated from the CSS, exports `<id>Theme` typed as `EmailTheme`, hex colors only, and its font stacks end in a web-safe family.
+- [ ] All four files written with the same stem. No page or email changes, no `ui/` changes, no `styles/globals.css` changes.
 
 ## Step 8 — Hand off
 
 Tell the user:
 
-- The theme id and the three file paths.
+- The theme id and the four 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.
 - That any existing page can adopt it by setting `meta.theme: '<id>'` — no other change.
+- That emails adopt it by importing `<id>Theme` from `@/components/email/theme-<id>` and passing it to `createEmailTailwindConfig` (or to an emailcn section's `theme` prop); `/create-email` offers it whenever the file exists.
 - 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.
@@ -203,7 +228,8 @@ Do not run the dev server. Do not modify real pages — the demo `.tsx` is the d
 - ❌ 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.
+- ❌ Producing a subset of the files. A theme is the **bundle** — `.md`, `.css`, `.demo.tsx`, and `components/email/theme-<id>.ts`, every time.
+- ❌ Hand-typing hex values into the email theme. Generate it from the CSS with the script so the page and email palettes cannot disagree.
 - ❌ 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.

package/skills/create-theme/references/email-theme-from-css.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// Derives an emailcn EmailTheme module from a workspace theme's CSS.
+//
+//   node <this file> themes/<id>.css <id> > components/email/theme-<id>.ts
+//
+// Reads the :root block (emails are light-mode documents), converts each
+// OKLCH token to hex, and maps the shadcn roles onto EmailTheme fields.
+// Fields the CSS cannot decide (success, warning, type scale, spacing) take
+// emailcn's defaults so the file stays a drop-in for createEmailTailwindConfig.
+
+import { readFileSync } from 'node:fs';
+
+const [, , cssPath, rawId] = process.argv;
+if (!cssPath || !rawId) {
+  process.stderr.write('usage: email-theme-from-css.mjs themes/<id>.css <id>\n');
+  process.exit(1);
+}
+
+const css = readFileSync(cssPath, 'utf8');
+const rootBlock = css.match(/:root\s*\{([\s\S]*?)\}/)?.[1] ?? '';
+const tokens = {};
+for (const m of rootBlock.matchAll(/--([a-z0-9-]+)\s*:\s*([^;]+);/g)) tokens[m[1]] = m[2].trim();
+
+const missing = ['background', 'foreground', 'primary', 'primary-foreground', 'border'].filter(
+  (t) => !tokens[t],
+);
+if (missing.length) {
+  process.stderr.write(`${cssPath} :root is missing ${missing.map((t) => `--${t}`).join(', ')}\n`);
+  process.exit(1);
+}
+
+function clamp01(x) {
+  return Math.min(1, Math.max(0, x));
+}
+function linToSrgb(c) {
+  const v = clamp01(c);
+  return v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055;
+}
+function oklchToRgb(L, C, H) {
+  const h = (H * Math.PI) / 180;
+  const a = C * Math.cos(h);
+  const b = C * Math.sin(h);
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+  const l = l_ ** 3;
+  const m = m_ ** 3;
+  const s = s_ ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ].map(linToSrgb);
+}
+function toHex([r, g, b]) {
+  return `#${[r, g, b]
+    .map((v) =>
+      Math.round(v * 255)
+        .toString(16)
+        .padStart(2, '0'),
+    )
+    .join('')}`;
+}
+function parseOklch(value) {
+  const m = value.match(/oklch\(\s*([\d.]+)%?\s+([\d.]+)\s+([\d.]+)/);
+  if (!m) return null;
+  let L = Number(m[1]);
+  if (value.includes('%')) L /= 100;
+  return { L, C: Number(m[2]), H: Number(m[3]) };
+}
+function hex(value) {
+  if (!value) return null;
+  if (/^#[0-9a-f]{6}$/i.test(value)) return value.toLowerCase();
+  const m = value.match(/rgb\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/);
+  if (m) return toHex([m[1], m[2], m[3]].map((n) => Number(n) / 255));
+  const o = parseOklch(value);
+  if (!o) return null;
+  return toHex(oklchToRgb(o.L, o.C, o.H));
+}
+function shifted(value, dL) {
+  const o = parseOklch(value);
+  if (!o) return hex(value);
+  return toHex(oklchToRgb(clamp01(o.L + dL), o.C, o.H));
+}
+function px(value, fallback) {
+  if (!value) return fallback;
+  const m = value.match(/([\d.]+)\s*(rem|px)/);
+  if (!m) return fallback;
+  const n = Number(m[1]);
+  return `${Math.round(m[2] === 'rem' ? n * 16 : n)}px`;
+}
+function fontStack(value, fallback) {
+  if (!value) return fallback;
+  return value
+    .split(',')
+    .map((f) => f.trim())
+    .filter((f) => !f.startsWith('var('))
+    .map((f) => f.replace(/^'(.*)'$/, '"$1"'))
+    .join(', ');
+}
+
+const color = (name, fallback) => hex(tokens[name]) ?? fallback;
+const background = color('background', '#ffffff');
+const foreground = color('foreground', '#111827');
+const primary = color('primary', '#111827');
+const primaryForeground = color('primary-foreground', '#ffffff');
+const border = color('border', '#e5e7eb');
+const muted = color('muted', '#f9fafb');
+const mutedForeground = color('muted-foreground', '#6b7280');
+const secondary = color('secondary', '#f3f4f6');
+const radius = px(tokens.radius, '6px');
+const radiusPx = Number.parseInt(radius, 10);
+
+const theme = {
+  borderRadius: radius,
+  borderRadiusLg: `${radiusPx * 2}px`,
+  button: {
+    primary: {
+      backgroundColor: primary,
+      borderRadius: radius,
+      color: primaryForeground,
+      fontSize: '14px',
+      fontWeight: '500',
+      paddingX: '24px',
+      paddingY: '12px',
+    },
+    secondary: {
+      backgroundColor: 'transparent',
+      border: `1px solid ${border}`,
+      borderRadius: radius,
+      color: foreground,
+      fontSize: '14px',
+      fontWeight: '500',
+      paddingX: '24px',
+      paddingY: '12px',
+    },
+  },
+  colorBackground: background,
+  colorBackgroundMuted: muted,
+  colorBackgroundSubtle: secondary,
+  colorBorder: border,
+  colorBorderSubtle: tokens.input ? color('input', border) : muted,
+  colorDanger: color('destructive', '#ef4444'),
+  colorPrimary: primary,
+  colorPrimaryForeground: primaryForeground,
+  colorPrimaryHover: tokens.primary ? shifted(tokens.primary, -0.08) : '#374151',
+  colorSuccess: '#10b981',
+  colorText: foreground,
+  colorTextMuted: mutedForeground,
+  colorTextSubtle: tokens['muted-foreground']
+    ? shifted(tokens['muted-foreground'], 0.14)
+    : '#9ca3af',
+  colorWarning: '#f59e0b',
+  containerWidth: '600px',
+  fontFamily: fontStack(
+    tokens['font-sans'],
+    '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+  ),
+  fontFamilyMono: fontStack(tokens['font-mono'], '"Menlo", "Monaco", "Courier New", monospace'),
+  fontSizeBase: '14px',
+  fontSizeHeading: '28px',
+  fontSizeLg: '16px',
+  fontSizeSm: '12px',
+  fontSizeXl: '20px',
+  fontWeightBold: '600',
+  fontWeightMedium: '500',
+  fontWeightNormal: '400',
+  lineHeightBase: '1.6',
+  spacingBase: '24px',
+  spacingLg: '32px',
+  spacingXl: '48px',
+};
+
+const id = rawId.replace(/\.css$/, '');
+const exportName = `${id.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase())}Theme`;
+// Unquoted keys, single-quoted strings unless the string itself holds one.
+const body = JSON.stringify(theme, null, 2)
+  .replace(/"([a-zA-Z]+)":/g, '$1:')
+  .replace(/"((?:[^"\\]|\\.)*)"/g, (_, str) =>
+    str.includes("'") ? `"${str}"` : `'${str.replace(/\\"/g, '"')}'`,
+  );
+
+process.stdout.write(
+  `import type { EmailTheme } from '@/components/email/email-theme';\n\n// Derived from themes/${id}.css by the create-theme skill. Re-run the script\n// after changing the CSS rather than editing colors here by hand.\nexport const ${exportName}: EmailTheme = ${body};\n`,
+);

package/skills/create-theme/references/email-theme.md

@@ -0,0 +1,48 @@
+# Email theme mapping
+
+`components/email/theme-<id>.ts` is the workspace theme expressed as an emailcn `EmailTheme`: hex colors, pixel sizes, plain font stacks. `email-theme-from-css.mjs` in this folder generates it from `themes/<id>.css`; this file records what it does so the output can be reviewed.
+
+```bash
+node .agents/skills/create-theme/references/email-theme-from-css.mjs themes/<id>.css <id> > components/email/theme-<id>.ts
+```
+
+Only the `:root` block is read. Emails are light-mode documents; mail clients that force dark mode recolor on their own and cannot be steered by a `.dark` block.
+
+## Token → field
+
+| CSS token (`:root`) | EmailTheme field | Notes |
+| --- | --- | --- |
+| `--background` | `colorBackground` | body and container fill |
+| `--foreground` | `colorText` | body copy, and the secondary button's text |
+| `--muted` | `colorBackgroundMuted` | bands, table stripes |
+| `--secondary` | `colorBackgroundSubtle` | quieter fills |
+| `--muted-foreground` | `colorTextMuted` | supporting copy |
+| `--muted-foreground` lightened (+0.14 L) | `colorTextSubtle` | captions, legal lines |
+| `--primary` | `colorPrimary`, `button.primary.backgroundColor` | the accent and the CTA fill |
+| `--primary` darkened (−0.08 L) | `colorPrimaryHover` | link hover where clients honor it |
+| `--primary-foreground` | `colorPrimaryForeground`, `button.primary.color` | text on the accent |
+| `--border` | `colorBorder`, `button.secondary.border` | hairlines, outline buttons |
+| `--input` (else `--muted`) | `colorBorderSubtle` | softer rules |
+| `--destructive` | `colorDanger` | errors |
+| `--radius` (rem × 16) | `borderRadius`, both buttons' `borderRadius`; ×2 → `borderRadiusLg` | |
+| `--font-sans` | `fontFamily` | `var()` entries dropped; keep a web-safe family at the end |
+| `--font-mono` | `fontFamilyMono` | same |
+
+Fixed at emailcn's defaults because the CSS has no equivalent: `colorSuccess` `#10b981`, `colorWarning` `#f59e0b`, `containerWidth` `600px`, the `fontSize*`, `fontWeight*`, `lineHeightBase`, and `spacing*` fields, and the button padding.
+
+## Review after generating
+
+- Web fonts: Gmail ignores them. The stack must end in `Arial, sans-serif` or a similar system family; the script keeps whatever the CSS listed, so add one if the CSS relied on `system-ui` alone.
+- Contrast: `colorTextMuted` on `colorBackground` and `colorPrimaryForeground` on `colorPrimary` are the pairs to check; they inherit the CSS values, so they pass when the CSS did.
+- Serif headings: `EmailTheme` has one `fontFamily`. If the page theme uses a serif `--font-heading`, emails set it per heading with `<Font>` plus a `font-serif` class or an explicit `style`, and the theme's `.md` should say so under "Email".
+
+## Using the theme in an email
+
+```tsx
+import { createEmailTailwindConfig } from '@/components/email/email-theme';
+import { midnightSaasTheme } from '@/components/email/theme-midnight-saas';
+
+<Tailwind config={createEmailTailwindConfig(midnightSaasTheme)}>…</Tailwind>
+```
+
+emailcn sections take a `theme` prop; blocks pin their theme inside the file and need a copy under `emails/<id>/components/` to swap it. The `create-email` skill covers both.

package/skills/current-page/SKILL.md

@@ -43,10 +43,10 @@ Path is relative to the project root (the user's `cwd`, the directory that conta
 }
 ```
 
-- `pageId` — folder name under `pages/`. Use as-is for any `/__pages/<id>/...` API or as the URL segment (`/p/<id>`).
+- `pageId` — folder name under `pages/` (or under `emails/` when `view` is `"emails"`). Use as-is for any `/__pages/<id>/...` API or as the URL segment (`/p/<id>`, `/e/<id>` for an email).
 - `pageTitle` — the page's `meta.title` (or `<title>` for an HTML page), falling back to the id.
-- `pagePath` — page entry path **relative to the project root**: `pages/<id>/index.tsx`, or `pages/<id>/index.html` for a plain HTML page. Prefix it with the project root before handing it to `Read` / `Edit`. Note the selection may point into a file under `pages/<id>/components/` if the page is split — match the line against the file whose JSX contains that tag and text.
-- `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.
+- `pagePath` — entry path **relative to the project root**: `pages/<id>/index.tsx`, `pages/<id>/index.html` for a plain HTML page, or `emails/<id>/index.tsx` for an email. Prefix it with the project root before handing it to `Read` / `Edit`. Note the selection may point into a file under `pages/<id>/components/` (or `emails/<id>/components/`) if the entry is split — match the line against the file whose JSX contains that tag and text.
+- `view` — `"pages"` when the user is viewing a page, `"assets"` when they are browsing that page's files in the asset manager, `"emails"` when they are viewing an email template. An email means the `create-email` skill's rules apply (react-email components, no `ui/`), not `page-authoring`.
 - `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"`). 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`.

package/skills/page-authoring/SKILL.md

@@ -187,7 +187,10 @@ A theme is `themes/<id>.md` (direction and component notes) + `themes/<id>.css`
 - [ ] One coherent type scale across the page; contrast holds on dark sections.
 - [ ] Designed repeats are explicit component instances; data lists are a `.map` over a typed const.
 - [ ] No `window`/`document` access at module top level; effects clean up.
+- [ ] One label per CTA intent across the page ("Get started" in the nav, hero, and footer — not "Get started" / "Sign up free" / "Try it"), and no primary button label wraps at desktop width.
+- [ ] Every animation is motivated: it shows hierarchy, sequence, feedback, or a state change. If you cannot say which in one sentence, remove it. `motion-safe:` / `motion-reduce:` variants respect the user's preference.
 - [ ] Nothing outside `pages/<id>/` was edited.
+- [ ] Ran the `web-design-guidelines` skill on the page and resolved or justified its findings.
 
 ## Anti-patterns
 

package/skills/web-design-guidelines/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: web-design-guidelines
+description: Review page code against Vercel's Web Interface Guidelines — accessibility, focus and keyboard handling, forms, motion, layout, typography, and performance. Use when asked to "review my page", "check accessibility", "audit the design", "review UX", or as the review pass at the end of `create-page` and `apply-comments`.
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <page-id or file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Review page files for compliance with Vercel's [Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines) (MIT). Vendored from the [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) `web-design-guidelines` skill and scoped to an open-pages workspace.
+
+## How it works
+
+1. Fetch the latest guidelines from the source URL below.
+2. Read the files to review.
+3. Check them against every rule in the fetched guidelines.
+4. Report findings in the terse `file:line` format the guidelines specify.
+
+## Guidelines source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and the output format. If the fetch fails (offline, blocked), say so and fall back to the self-review checklist in the `page-authoring` skill instead of guessing at rules.
+
+## What to review
+
+- Given a page id, review the page's entry (`pages/<id>/index.tsx` or `pages/<id>/index.html`), everything under `pages/<id>/components/`, and any `styles.css`, `style.css`, or `main.js` beside the entry.
+- Given a file or glob, review those files.
+- Given nothing, resolve the current page with the `current-page` skill; if that yields nothing, ask which page to review.
+
+Never review or report on files under `ui/`, `lib/`, `hooks/`, or `styles/`. Those are the shared shadcn set and are not edited for one page; a finding there is a `create-theme` or upstream matter, not a page fix.
+
+## Applying findings
+
+Report first. When the user asks you to fix, or the review runs inside `create-page` or `apply-comments`, apply the fixes to the page files only, following the `page-authoring` skill: keep `@/ui/*` components, keep semantic tokens, keep the type scale. Do not add dependencies to satisfy a rule.

package/src/app/app.tsx

@@ -4,6 +4,8 @@ import { Toaster } from './components/ui/sonner';
 import { TooltipProvider } from './components/ui/tooltip';
 import { useLocale } from './lib/use-locale';
 import { AssetsPage } from './routes/assets';
+import { EmailView } from './routes/email';
+import { EmailsGalleryPage } from './routes/emails';
 import { Home } from './routes/home';
 import { HomeShell } from './routes/home-shell';
 import { PageView } from './routes/page';
@@ -22,11 +24,13 @@ export function App() {
               <Route path="/themes" element={<ThemesGalleryPage />} />
               <Route path="/themes/:themeId" element={<ThemeDetailPage />} />
               <Route path="/assets" element={<AssetsPage />} />
+              <Route path="/emails" element={<EmailsGalleryPage />} />
             </Route>
           ) : (
             <Route path="/" element={<NotFound />} />
           )}
           <Route path="/p/:pageId" element={<PageView />} />
+          <Route path="/e/:emailId" element={<EmailView />} />
           <Route path="*" element={<NotFound />} />
         </Routes>
       </TooltipProvider>

package/src/app/components/command/home-command-menu.tsx

@@ -1,12 +1,13 @@
-import { Presentation } from 'lucide-react';
+import { Mail, Presentation } from 'lucide-react';
 import { useMemo } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { useLocale } from '~/lib/use-locale';
 import { usePageTitles } from '~/lib/use-page-titles';
+import { emailIds, emailMeta } from '../../lib/emails';
 import { pageIds } from '../../lib/pages';
 import type { Folder } from '../../lib/sdk';
 import { FolderIconChip, SystemViewIcon } from '../sidebar/folder-item';
-import { ALL_DOCS_ID, ASSETS_ID, DRAFT_ID, THEMES_ID } from '../sidebar/sidebar';
+import { ALL_DOCS_ID, ASSETS_ID, DRAFT_ID, EMAILS_ID, THEMES_ID } from '../sidebar/sidebar';
 import { type CommandGroupSpec, CommandMenu, type CommandSpec } from './command-menu';
 
 export function HomeCommandMenu({
@@ -35,6 +36,14 @@ export function HomeCommandMenu({
       run: () => navigate(`/p/${id}`),
     }));
 
+    const emails: CommandSpec[] = emailIds.map((id) => ({
+      id: `email-${id}`,
+      label: emailMeta[id]?.title ?? id,
+      icon: <Mail />,
+      keywords: [id, 'email', emailMeta[id]?.subject ?? ''],
+      run: () => navigate(`/e/${id}`),
+    }));
+
     const folderItems: CommandSpec[] = [
       {
         id: `view-${ALL_DOCS_ID}`,
@@ -67,6 +76,13 @@ export function HomeCommandMenu({
         keywords: ['themes', 'design'],
         run: () => onSelectView(THEMES_ID),
       },
+      {
+        id: `view-${EMAILS_ID}`,
+        label: t.home.emails,
+        icon: <SystemViewIcon kind="emails" />,
+        keywords: ['emails', 'mail', 'templates'],
+        run: () => onSelectView(EMAILS_ID),
+      },
     ];
     if (import.meta.env.DEV) {
       navigation.push({
@@ -80,6 +96,7 @@ export function HomeCommandMenu({
 
     return [
       { id: 'pages', heading: t.commandMenu.groupDocs, items: pages },
+      { id: 'emails', heading: t.commandMenu.groupEmails, items: emails },
       { id: 'folders', heading: t.commandMenu.groupFolders, items: folderItems },
       { id: 'navigation', heading: t.commandMenu.groupNavigation, items: navigation },
     ];

package/src/app/components/selection-note.tsx

@@ -0,0 +1,71 @@
+import { Loader2, MessageSquarePlus, X } from 'lucide-react';
+import { Button } from '~/components/ui/button';
+
+export type Selection = { loc: string; tag: string; text: string };
+
+/**
+ * The floating note box that follows an inspector pick: shows the picked
+ * element and lets the user leave a comment for their agent.
+ */
+export function SelectionNote({
+  selection,
+  note,
+  saving,
+  onNoteChange,
+  onSubmit,
+  onClear,
+}: {
+  selection: Selection;
+  note: string;
+  saving: boolean;
+  onNoteChange: (note: string) => void;
+  onSubmit: () => void;
+  onClear: () => void;
+}) {
+  return (
+    <div className="fixed bottom-6 right-6 z-20 w-[340px] rounded-lg border bg-background p-3 shadow-xl">
+      <div className="flex items-center gap-2">
+        <span className="rounded bg-muted px-1.5 py-0.5 font-mono text-[11px]">
+          {selection.tag}
+        </span>
+        <span className="font-mono text-[11px] text-muted-foreground">
+          line {selection.loc.replace(':', ', col ')}
+        </span>
+        <Button
+          variant="ghost"
+          size="icon"
+          className="ml-auto size-6"
+          aria-label="Clear selection"
+          onClick={onClear}
+        >
+          <X className="size-3.5" />
+        </Button>
+      </div>
+      {selection.text && (
+        <p className="mt-1.5 line-clamp-2 text-xs text-muted-foreground">“{selection.text}”</p>
+      )}
+      <textarea
+        value={note}
+        onChange={(e) => onNoteChange(e.target.value)}
+        placeholder="Leave a note for your agent — e.g. “make this bold”"
+        rows={2}
+        className="mt-2 w-full resize-none rounded-md border bg-transparent px-2 py-1.5 text-sm outline-none focus:ring-1 focus:ring-ring"
+      />
+      <div className="mt-2 flex justify-end gap-2">
+        <Button
+          size="sm"
+          onClick={onSubmit}
+          disabled={!note.trim() || saving}
+          aria-label="Save comment"
+        >
+          {saving ? (
+            <Loader2 className="size-3.5 animate-spin" />
+          ) : (
+            <MessageSquarePlus className="size-3.5" />
+          )}
+          Comment
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/app/components/sidebar/folder-item.tsx

@@ -2,6 +2,7 @@ import {
   FolderOpen,
   LayoutGrid,
   type LucideIcon,
+  Mail,
   MoreHorizontal,
   Palette,
   Pencil,
@@ -42,13 +43,14 @@ function useDocDragActive() {
   return active;
 }
 
-export type SystemViewKind = 'all' | 'draft' | 'themes' | 'assets';
+export type SystemViewKind = 'all' | 'draft' | 'themes' | 'assets' | 'emails';
 
 const SYSTEM_VIEW_ICONS: Record<SystemViewKind, LucideIcon> = {
   all: LayoutGrid,
   draft: PenLine,
   themes: Palette,
   assets: FolderOpen,
+  emails: Mail,
 };
 
 export function SystemViewIcon({ kind, className }: { kind: SystemViewKind; className?: string }) {
@@ -103,6 +105,9 @@ type Row =
     }
   | {
       kind: 'assets';
+    }
+  | {
+      kind: 'emails';
     };
 
 export function FolderItem({
@@ -168,7 +173,9 @@ export function FolderItem({
           ? t.home.themes
           : row.kind === 'assets'
             ? t.home.assets
-            : row.folder.name;
+            : row.kind === 'emails'
+              ? t.home.emails
+              : row.folder.name;
 
   const commitRename = () => {
     if (row.kind !== 'folder') return;