@autono/open-pages 0.1.0

package/skills/page-authoring/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: page-authoring
+description: Technical reference for writing or editing open-pages pages — file contract, Tailwind via `className`, layout and responsive breakpoints, web type scale, interactivity with hooks and state, assets and fonts, plain `index.html` pages, and the self-review checklist. Consult this whenever you are about to write or modify any file under `pages/<id>/`, including from inside the `create-page` or `apply-comments` workflows, or for any ad-hoc page edit. Triggers on phrases like "edit the page", "fix the layout", "change the palette", "add a section", "make it responsive", "add a form", "investigate the page framework", "how do pages work here".
+---
+
+# Authoring open-pages pages
+
+This skill is the **technical reference** for everything that happens inside `pages/<id>/`. It does not own a workflow:
+
+- `create-page` owns "build a new page" — it asks the user scoping questions, then delegates the *how* to this skill.
+- `apply-comments` owns "process inspector markers" — it finds markers and applies edits, but the edits themselves follow the rules here.
+- `current-page` resolves deictic references ("this page", "this element") to a concrete `pageId` + selection. Consult it **first** when the user references the current page without naming it, then come back here for how to edit it.
+- Any ad-hoc page edit (manual tweak, one-off fix) should also consult this skill before touching the file.
+
+A page here is a **real web page**: one React component rendered into a real browser document. The workspace previews it live in an iframe, the inspector maps clicks back to source lines, and `open-pages export` turns it into a static folder you can deploy anywhere. Your job is a good web page; the runtime's job is preview, comments, and export.
+
+## Topic references
+
+Details live under `references/` in this skill. **Read the relevant file before using the feature**:
+
+| Topic | Read before | File |
+| --- | --- | --- |
+| Layout + responsive | any multi-column layout, nav, hero, grid; anything that must work on mobile | `references/layout-and-responsive.md` |
+| Typography + color | picking a type scale or palette, dark backgrounds, contrast | `references/typography-and-color.md` |
+| Interactivity | state, forms, tabs, toggles, anything with an event handler | `references/interactivity.md` |
+| Assets + fonts | images, icons, custom fonts, Google Fonts | `references/assets-and-fonts.md` |
+| Plain HTML pages | a page authored as `index.html` instead of React | `references/html-pages.md` |
+
+## Hard rules
+
+- Put the page under `pages/<kebab-case-id>/`.
+- Entry is `pages/<id>/index.tsx` (or `pages/<id>/index.html` for a plain HTML page — see `references/html-pages.md`).
+- Do **not** touch `package.json`, `open-pages.config.ts`, or other pages.
+- Do not add dependencies. Only `react`, `react-dom`, and `@autono/open-pages` (types) are available, plus browser APIs.
+- A page is `index.tsx` plus, optionally, `components/*.tsx`, `styles.css`, and `assets/` for its images and fonts — all inside `pages/<id>/`. Shared assets live in the root `assets/` folder and import via `@assets/...`. No `README.md`, no config files.
+- Style with Tailwind utilities on `className`. Tailwind is preconfigured and scans `pages/` and `themes/`; there is nothing to set up.
+
+## File contract
+
+```tsx
+// pages/<id>/index.tsx
+import type { PageMeta } from '@autono/open-pages';
+import { useState } from 'react';
+
+export const meta: PageMeta = {
+  title: 'Meridian — Launch',
+  description: 'Meridian turns your analytics into weekly decisions.',
+  createdAt: '2026-08-28T12:00:00.000Z',
+};
+
+export default function Launch() {
+  const [open, setOpen] = useState(false);
+  return (
+    <main className="min-h-screen bg-white text-slate-900 antialiased">
+      {/* sections */}
+    </main>
+  );
+}
+```
+
+- `export default` is **one zero-prop React component** — the whole page. It owns the viewport: set the page background and text color on the root element (`min-h-screen bg-… text-…`).
+- `meta.title` (optional) becomes the browser tab title and the workspace card label. Default is the folder name.
+- `meta.description` (optional) becomes `<meta name="description">` in the exported HTML.
+- `meta.theme` (optional) marks the page as built from a theme under `themes/`. The id must match a `<id>.md` basename. Omit if not derived from a registered theme.
+- `meta.createdAt` is an **ISO 8601 string literal** set once when the page is scaffolded — **immediately before writing the file, run `node -e "console.log(new Date().toISOString())"` via Bash and paste the exact output**. Must stay a plain string literal (the framework reads it via regex, never by evaluating the module).
+- Hooks, state, event handlers, `fetch`, `window`, client-side routing: all allowed. This is a browser. See `references/interactivity.md` for the constraints that still apply (no `window` at module top level, StrictMode double-invokes effects).
+
+## Styling: Tailwind on `className`
+
+Write the HTML you already know — `main`, `header`, `nav`, `section`, `h1`–`h3`, `p`, `ul`/`li`, `button`, `a`, `form`, `table` — styled with **Tailwind v4 utilities via `className`**:
+
+```tsx
+<section className="mx-auto max-w-5xl px-6 py-20">
+  <h2 className="text-3xl font-bold tracking-tight">Pricing</h2>
+  <p className="mt-3 max-w-xl text-lg text-slate-600">Simple plans that grow with you.</p>
+</section>
+```
+
+- `className`, never a `tw` prop. Arbitrary values are fine (`text-[15px]`, `bg-[#0b0b10]`, `max-w-[72ch]`).
+- Responsive variants are the default tool: `grid sm:grid-cols-2 lg:grid-cols-3`. Mobile-first — unprefixed utilities are the mobile layout.
+- State variants for interactive elements: `hover:`, `focus-visible:`, `disabled:`, `aria-pressed:`.
+- Use inline `style={{ … }}` only for values Tailwind cannot express (computed positions, CSS variables from data).
+- A page may import its own stylesheet (`import './styles.css'`) for keyframes, complex selectors, or a font `@import`. Keep it small; utilities first.
+- Preflight (Tailwind's reset) is applied inside the page, so headings and buttons start unstyled — set sizes and weights explicitly.
+
+## Web type scale and color
+
+| Element | Size |
+| --- | --- |
+| Hero heading | 48–72px (`text-5xl`–`text-7xl`), tight leading + tracking |
+| Section heading | 24–36px (`text-2xl`–`text-4xl`) |
+| Body | 16–18px (`text-base`–`text-lg`), `leading-relaxed` |
+| Secondary / captions | 13–14px (`text-sm`), muted color |
+| Labels, eyebrows | 11–12px (`text-xs`), `uppercase tracking-widest` |
+
+- One page = one palette: a background, a text color, a muted text color, one accent, one border tint. Hold it for the whole page.
+- Contrast: body text must pass 4.5:1 against its background; muted text on dark backgrounds is `text-white/60`, not `text-white/30`.
+- Details in `references/typography-and-color.md`.
+
+## Data rows vs designed repeats
+
+- **Repeated data belongs in a `.map` over a data array** — pricing tiers, feature lists, testimonials pulled from a typed const at the top of the file; keep the row JSX in the map body. A comment on any row means "this row template".
+- **Designed repeats that differ (hero vs. secondary CTA, three distinct feature panels with custom art) are explicit instances** of a small helper component defined in the same file or under `components/`. The inspector targets source JSX; explicit instances give each block its own address, so "make the middle one green" is one edit, not three.
+
+## Editing an existing page
+
+Locate the section first instead of reading the whole file:
+
+```bash
+grep -n '<section\|<h[12]\|<header\|<footer' pages/<id>/index.tsx
+```
+
+Landmarks and headings anchor sections; read the target range with `offset` + `limit`. Read the whole file when auditing palette or restructuring.
+
+## Themes
+
+If `themes/<id>.md` exists and the page is meant to follow it, **the theme file overrides the defaults in this skill** — its palette, typography, and fixed components are authoritative. Read the theme before applying anything else here. Themes are produced by the `create-theme` skill.
+
+## Runtime behavior you get for free
+
+- Home lists every folder under `pages/`; cards show a live, scaled-down preview of the real page.
+- The page view at `http://localhost:5173/p/<id>` renders the page in an iframe with **Desktop / Tablet (820px) / Mobile (390px)** viewport toggles, a reload button, and **Open** (the page by itself in a new tab).
+- **Inspect mode** (toolbar button or `i`): the user clicks any element, sees its tag and source line, and can leave a comment that lands in your source as an `@page-comment` marker (see `apply-comments`). The current selection is always in `node_modules/.open-pages/current.json` (see `current-page`).
+- Hot reload: save any file under `pages/<id>/` and the preview updates in place.
+- `open-pages export <id>` builds `export/<id>/` — `index.html` plus hashed assets with relative URLs. Drop the folder on Netlify, Vercel, Cloudflare Pages, GitHub Pages, or S3.
+
+## Self-review before finishing
+
+- [ ] `pages/<id>/index.tsx` default-exports **one** component; `meta` has `title` + fresh `createdAt` literal.
+- [ ] Root element sets `min-h-screen`, background, and text color; the page has a `<main>` landmark.
+- [ ] Preview it at `http://localhost:5173/p/<id>` (or ask the user to). No error banner, no console errors.
+- [ ] Check the **Mobile** viewport: no horizontal overflow, nav collapses or wraps, grids stack, text sizes step down.
+- [ ] Every `className` is Tailwind v4 the scanner will see (literal strings, no runtime-concatenated utility names).
+- [ ] Interactive elements are real `<button>`/`<a>`/`<input>` elements with visible `focus-visible:` styles and labels; images have `alt`.
+- [ ] One coherent palette and 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.
+- [ ] Nothing outside `pages/<id>/` was edited.
+
+## Anti-patterns
+
+- ❌ `tw` props, `pageOptions`, fixed-size "page" `<div>`s, or any document/slide thinking. This is a scrolling web page.
+- ❌ Desktop-only layouts: absolute pixel positioning, fixed widths on the root, `grid-cols-3` with no `sm:` fallback.
+- ❌ Building class names at runtime (`` `text-${size}` ``) — Tailwind only generates utilities it can read literally. Map to full class strings instead.
+- ❌ `<div onClick>` where a `<button>` belongs; `<a>` without `href`; icon buttons without `aria-label`.
+- ❌ Tiny typography (11px body). Web body is 16px+.
+- ❌ Global CSS resets or `body {}` rules in `styles.css` that fight Preflight — style the root element instead.
+- ❌ Installing packages, editing `package.json`/config/other pages, adding a `README.md` to the page folder.

package/skills/page-authoring/references/assets-and-fonts.md

@@ -0,0 +1,85 @@
+# Assets and fonts
+
+Both images and fonts follow the same rule: put the file under
+`pages/<id>/assets/`, import it, and reference the imported value. Vite
+resolves the import to a URL in the preview and to a hashed file in the
+export.
+
+## Images
+
+```tsx
+import hero from './assets/hero.png';
+
+<img src={hero} alt="Dashboard showing the weekly brief" width={1200} height={720} className="w-full rounded-xl" />
+```
+
+- **Always give `width` and `height`** (intrinsic pixels) so the browser
+  reserves space and the layout does not shift while loading. Let CSS
+  (`w-full h-auto`) size it visually.
+- **Always give `alt`**: descriptive for content images, `alt=""` for purely
+  decorative ones.
+- Below-the-fold images: `loading="lazy"`. The hero image: eager, and keep it
+  reasonably sized (≤ 1600px wide, WebP or JPEG).
+- Page-local images live in `pages/<id>/assets/`; images shared across pages
+  live in the root `assets/` folder and import via `@assets/...`.
+- Inline `<svg>` for logos, icons, and simple illustrations — crisp at any
+  size and styleable with `fill-current`/`stroke-current`. Icon-only buttons
+  need `aria-label`.
+- Remote images (`https://…`) work but make the export depend on that host.
+  Prefer local files; ask the user for their assets rather than inventing
+  stock imagery.
+
+## Fonts
+
+The default is the system font stack — fast, no files, always correct.
+Register a font only when the user names one or supplies files.
+
+### Google Fonts
+
+Render the link tags at the top of the page component:
+
+```tsx
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="" />
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap"
+/>
+```
+
+Then use it: `className="font-[Inter,ui-sans-serif,system-ui,sans-serif]"` on
+the root element, or in the page's `styles.css`:
+
+```css
+@import url('https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600&display=swap');
+```
+
+### Self-hosted
+
+```css
+/* pages/<id>/styles.css */
+@font-face {
+  font-family: 'Satoshi';
+  src: url('./assets/Satoshi-Variable.woff2') format('woff2');
+  font-weight: 300 900;
+  font-display: swap;
+}
+```
+
+`import './styles.css'` in `index.tsx`, then `font-[Satoshi,sans-serif]`.
+Always include a fallback family.
+
+## Favicons and `<head>`
+
+- `meta.title` and `meta.description` are written into the exported
+  `<head>`. Other head tags (favicon, Open Graph) are not supported yet; note
+  this to the user if they ask for them.
+
+## Anti-patterns
+
+- ❌ `<img>` without `alt`, or without `width`/`height`.
+- ❌ Multi-megapixel PNG screenshots as hero images.
+- ❌ `fontFamily` naming a font that was never loaded — it silently falls
+  back and the page looks nothing like the theme.
+- ❌ Loading four weights of two families for one heading.
+- ❌ Hotlinking images from someone else's site.

package/skills/page-authoring/references/html-pages.md

@@ -0,0 +1,65 @@
+# Plain HTML pages
+
+A page folder may hold an `index.html` instead of a React module. The
+workspace serves it as-is (through Vite, so scripts and styles are
+processed), the home card previews it live, and `open-pages export <id>`
+builds it into a static folder like any other page.
+
+## When to use it
+
+- The user hands you existing HTML/CSS/JS to host or tweak.
+- A tiny page where React is overhead: a one-screen announcement, a redirect
+  page, an embed target.
+- Prototypes that intentionally avoid a framework.
+
+For anything with real layout, state, or reuse, prefer `index.tsx`.
+
+## Contract
+
+```
+pages/<id>/
+  index.html     entry — must contain <title>
+  style.css      optional, referenced with a relative href
+  main.js        optional, referenced with a relative src (type="module" recommended)
+  assets/        images, fonts
+```
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Launch week</title>
+    <link rel="stylesheet" href="./style.css" />
+  </head>
+  <body>
+    <main>…</main>
+    <script type="module" src="./main.js"></script>
+  </body>
+</html>
+```
+
+- Reference siblings with **relative** URLs (`./style.css`, `./assets/logo.svg`,
+  `main.js`). Absolute paths (`/style.css`) do not resolve in the preview or
+  the export.
+- `<title>` is the card label in the workspace. There is no `meta` export;
+  the folder name is the page id.
+- If both `index.tsx` and `index.html` exist, the React entry wins and the
+  HTML is treated as a plain asset.
+- Tailwind is **not** wired into HTML pages. Write CSS, or use the React
+  entry when you want utilities.
+
+## What you do not get
+
+- No inspector, no click-to-comment, no `@page-comment` markers. Feedback on
+  an HTML page comes as plain requests; apply them by editing the file.
+- No hot module replacement for the HTML itself — the preview reloads the
+  frame on save. CSS and JS changes still hot-update.
+
+## Anti-patterns
+
+- ❌ Absolute or root-relative asset paths.
+- ❌ Inline `<script>` blobs of application logic — put them in `main.js`.
+- ❌ Reaching for `index.html` when the request is "a landing page with a
+  pricing toggle". That is a React page.

package/skills/page-authoring/references/interactivity.md

@@ -0,0 +1,77 @@
+# Interactivity
+
+Pages are real React 18 components running in the browser, wrapped in
+`StrictMode`. Everything React can do is available; the constraints below
+keep pages preview-safe, export-safe, and inspectable.
+
+## State
+
+```tsx
+const [tab, setTab] = useState<'monthly' | 'yearly'>('monthly');
+
+<button
+  type="button"
+  onClick={() => setTab('yearly')}
+  aria-pressed={tab === 'yearly'}
+  className={tab === 'yearly' ? 'bg-slate-900 text-white' : 'text-slate-600'}
+>
+  Yearly
+</button>
+```
+
+- Keep state local and small: tabs, toggles, accordions, filters, form values.
+- Derive, do not duplicate: compute filtered lists with `useMemo` (or inline)
+  from the source array and the filter state.
+- Toggle/tab buttons carry `aria-pressed` or `role="tablist"` semantics;
+  disclosure buttons carry `aria-expanded` and `aria-controls`.
+
+## Forms
+
+- Real `<form>` with `onSubmit={(e) => { e.preventDefault(); … }}`.
+- Every input has a `<label htmlFor>` (or `aria-label`), a `name`, and a
+  sensible `type`/`inputMode`/`autoComplete`.
+- No backend exists in the workspace or the export. Either mirror submitted
+  values into local state ("Thanks, we'll be in touch"), or point the form at
+  a URL the user supplies (`action="https://formspree.io/…" method="post"`).
+  Never invent an endpoint.
+
+## Network and browser APIs
+
+- `fetch`, `localStorage`, `IntersectionObserver`, `matchMedia` are fine —
+  inside effects or handlers, with loading and error states.
+- Assume the exported page may run from `file://` or a static host with no
+  API: gate network features behind a URL the user supplied, and render
+  something meaningful without it.
+- Access `window`/`document` only inside `useEffect` or event handlers.
+  Module-top-level `window.innerWidth` breaks the module import and the
+  export build.
+
+## Effects and StrictMode
+
+- Effects run twice in development (StrictMode). Every subscription,
+  observer, timer, and listener must be cleaned up in the effect's return.
+- No side effects in render. No `Date.now()` / `Math.random()` in render for
+  layout-affecting values; seed them in state via a lazy initializer.
+
+## Progressive enhancement
+
+- Content must be visible with JavaScript disabled or before hydration: no
+  empty shells that only fill from an effect.
+- Hover-only affordances need a keyboard/touch equivalent.
+- Animations: `motion-safe:transition-*`; respect `prefers-reduced-motion`.
+
+## Routing inside a page
+
+- Simple multi-view pages: a `view` state and conditional rendering, with
+  `<a href="#section">` anchors for in-page navigation.
+- Hash routing is acceptable when the user asks for "pages" inside one export
+  (`window.location.hash`, read in an effect). Path-based routing needs a
+  host with rewrites — mention this to the user before choosing it.
+
+## Anti-patterns
+
+- ❌ `useEffect` to compute something derivable from props/state.
+- ❌ Fetching from an endpoint nobody set up.
+- ❌ `document.querySelector` to mutate the DOM React owns.
+- ❌ Global listeners without cleanup; timers that outlive the component.
+- ❌ Interactive `<div>`s. Use `<button>`, `<a>`, `<input>`, `<select>`.

package/skills/page-authoring/references/layout-and-responsive.md

@@ -0,0 +1,71 @@
+# Layout and responsive design
+
+The viewer previews every page at three widths — **Desktop** (the full
+viewport), **Tablet** (820px), and **Mobile** (390px). A page is done when all
+three look intentional. Tailwind is mobile-first: unprefixed utilities are the
+phone layout; `sm:` (640px), `md:` (768px), `lg:` (1024px), `xl:` (1280px)
+layer larger layouts on top.
+
+## Containers
+
+```tsx
+<section className="mx-auto max-w-6xl px-6 py-16 sm:py-24">…</section>
+```
+
+- Center content with `mx-auto max-w-*`; keep horizontal padding (`px-6`) so
+  text never touches the viewport edge on mobile.
+- Reading columns: `max-w-2xl` / `max-w-[65ch]` for prose. Marketing grids:
+  `max-w-5xl`–`max-w-7xl`.
+- Vertical rhythm: `py-16` between sections on mobile, `sm:py-24` on desktop.
+  Sections separate by space or a hairline (`border-t border-slate-200`), not
+  both.
+
+## Grids and stacks
+
+```tsx
+<div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+  {features.map((f) => <FeatureCard key={f.title} {...f} />)}
+</div>
+```
+
+- Default to a single column, add columns at `sm:`/`lg:`.
+- `flex flex-col gap-4 sm:flex-row sm:items-center` for header rows that must
+  stack on phones.
+- Use `gap-*`, not margins on children, for spacing inside grids and flex rows.
+
+## Navigation
+
+- Desktop nav links: `hidden sm:flex gap-8`. On mobile either show a compact
+  set of links, or a `<button aria-expanded>` that toggles a stacked menu with
+  `useState`. Never let a nav overflow horizontally.
+- Sticky headers: `sticky top-0 z-10 bg-white/90 backdrop-blur` — give them a
+  background so content does not bleed through.
+
+## Hero
+
+- Heading `text-4xl sm:text-6xl lg:text-7xl`, `leading-[1.05] tracking-tight`.
+- Constrain the heading (`max-w-3xl`) and the lede (`max-w-xl`) independently.
+- CTA row: `flex flex-col gap-3 sm:flex-row` so buttons stack on mobile.
+
+## Full-viewport pages (dashboards, app UIs)
+
+- Root: `min-h-screen` (not `h-screen`) so content can scroll.
+- Sidebars: `hidden lg:block w-64` plus a mobile alternative (top tabs or a
+  toggle). Content area: `min-w-0 flex-1` so tables and code blocks can shrink.
+- Wide content (tables, charts) scrolls inside its own `overflow-x-auto`
+  wrapper; the page body must never scroll horizontally.
+
+## Checklist
+
+- [ ] Mobile: no horizontal scrollbar, every grid stacks, headings shrink.
+- [ ] Tablet: two-column layouts where three would cramp.
+- [ ] Desktop: content is capped by a `max-w-*`, not stretched edge to edge.
+- [ ] Touch targets ≥ 40px tall on mobile (`py-2.5` on buttons and links).
+
+## Anti-patterns
+
+- ❌ Fixed pixel widths on layout containers (`w-[1200px]`).
+- ❌ `absolute` positioning for layout (fine for badges, overlays, decoration).
+- ❌ `h-screen` on scrolling pages; `overflow-hidden` on `body`/root.
+- ❌ Grids with no mobile fallback (`grid-cols-4` alone).
+- ❌ Text sized only for desktop (`text-7xl` with no smaller base).

package/skills/page-authoring/references/typography-and-color.md

@@ -0,0 +1,60 @@
+# Typography and color
+
+## Type scale (web)
+
+| Role | Tailwind | Notes |
+| --- | --- | --- |
+| Hero heading | `text-5xl sm:text-7xl font-bold leading-[1.02] tracking-tight` | one per page |
+| Page / section heading | `text-3xl sm:text-4xl font-bold tracking-tight` | |
+| Subsection | `text-xl font-semibold` | |
+| Lede | `text-lg sm:text-xl text-<muted>` | under the hero heading |
+| Body | `text-base leading-relaxed` (16px) | never smaller for running copy |
+| Secondary | `text-sm text-<muted>` | captions, metadata, table cells |
+| Eyebrow / label | `text-xs font-semibold uppercase tracking-[0.2em]` | above headings |
+| Code | `font-mono text-[0.9em]` with a subtle background | |
+
+- Line-height: tight (`leading-[1.05]`–`leading-tight`) for display sizes,
+  `leading-relaxed` (1.625) for body.
+- Measure: cap prose at `max-w-[65ch]` / `max-w-2xl`.
+- Numbers in tables and prices: `tabular-nums`.
+- Fonts: the system stack is the default and is fine. Register a display or
+  brand font only when the user names one — see `assets-and-fonts.md`.
+
+## Palette structure
+
+One page, one palette. Name the roles up front and reuse them literally:
+
+| Role | Light example | Dark example |
+| --- | --- | --- |
+| background | `bg-white` | `bg-[#0b0b10]` |
+| surface | `bg-slate-50` / `bg-white` cards with `border-slate-200` | `bg-white/[0.04]` with `border-white/10` |
+| text | `text-slate-900` | `text-white` |
+| muted | `text-slate-600` (never lighter than `slate-500` on white) | `text-white/60` |
+| accent | one hue, one shade for fills (`bg-indigo-600`) and one for text (`text-indigo-600`) | `bg-emerald-400 text-black` |
+| border | `border-slate-200` | `border-white/10` |
+
+- Define the palette as repeated utilities or as a small `const` map of class
+  strings when a page uses many surfaces. Do not build class names at runtime.
+- Accent is for actions and one highlight per screen. Two accents means no
+  accent.
+- Dark pages: prefer near-black (`#0b0b10`, `#111`) over pure black; lift
+  surfaces with translucent white (`bg-white/[0.03]`), not grey hex soup.
+
+## Contrast
+
+- Body text ≥ 4.5:1 against its background; large headings ≥ 3:1.
+- Muted text on white: `slate-500` is the floor. On dark: `white/60` is the
+  floor; `white/40` only for decorative metadata.
+- Accent text on white must be a 600+ shade (`indigo-600`, `emerald-700`).
+  `emerald-400` text on white fails.
+- Links inside prose: underline or a clearly different color, not color alone
+  at low contrast.
+
+## Anti-patterns
+
+- ❌ Body text under 16px, or `text-xs` for anything the user must read.
+- ❌ Three font families. Two is the ceiling (display + body).
+- ❌ Pure black on pure white for long text (`text-slate-900` on white reads
+  better); pure white on pure black for dark pages.
+- ❌ Gradient text, drop shadows, and glows on every heading. One flourish, once.
+- ❌ Palette drift: a new grey shade every section.

package/src/app/app.tsx

@@ -0,0 +1,45 @@
+import config from 'virtual:open-pages/config';
+import { BrowserRouter, Route, Routes } from 'react-router-dom';
+import { Toaster } from './components/ui/sonner';
+import { useLocale } from './lib/use-locale';
+import { AssetsPage } from './routes/assets';
+import { Home } from './routes/home';
+import { HomeShell } from './routes/home-shell';
+import { PageView } from './routes/page';
+import { ThemeDetailPage, ThemesGalleryPage } from './routes/themes';
+
+export function App() {
+  return (
+    <BrowserRouter basename={import.meta.env.BASE_URL}>
+      <Routes>
+        {config.build.showPageBrowser ? (
+          <Route element={<HomeShell />}>
+            <Route path="/" element={<Home />} />
+            <Route path="/themes" element={<ThemesGalleryPage />} />
+            <Route path="/themes/:themeId" element={<ThemeDetailPage />} />
+            <Route path="/assets" element={<AssetsPage />} />
+          </Route>
+        ) : (
+          <Route path="/" element={<NotFound />} />
+        )}
+        <Route path="/p/:pageId" element={<PageView />} />
+        <Route path="*" element={<NotFound />} />
+      </Routes>
+      <Toaster />
+    </BrowserRouter>
+  );
+}
+
+function NotFound() {
+  const t = useLocale();
+  return (
+    <div className="grid h-screen place-items-center bg-background px-6 text-center text-foreground">
+      <div>
+        <p className="folio">{t.notFound.eyebrow}</p>
+        <h1 className="mt-2 font-heading text-2xl font-semibold tracking-tight">
+          {t.notFound.title}
+        </h1>
+      </div>
+    </div>
+  );
+}