@autono/open-pages 0.1.0 → 0.3.0

package/skills/page-authoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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".
+description: Technical reference for writing or editing open-pages pages — file contract, composing from the preinstalled shadcn/ui set under `ui/`, semantic theme tokens, layout and responsive breakpoints, web type scale, interactivity with hooks and forms, 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", "use a dialog", "investigate the page framework", "how do pages work here".
 ---
 
 # Authoring open-pages pages
@@ -10,19 +10,37 @@ This skill is the **technical reference** for everything that happens inside `pa
 - `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.
+- `shadcn` (the vendored official skill) covers the shadcn CLI, registries, presets, and component-level docs. Consult it for "how does `<Combobox>` work" or "add a block from a registry"; this skill covers how pages in *this* workspace use those components.
 - 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.
 
+## What the workspace already gives you
+
+Every workspace is a shadcn/ui project out of the box. Nothing needs installing:
+
+| Path | What it is |
+| --- | --- |
+| `ui/*.tsx` | The full shadcn/ui set (61 components: accordion, alert, alert-dialog, aspect-ratio, attachment, avatar, badge, breadcrumb, bubble, button, button-group, calendar, card, carousel, chart, checkbox, collapsible, combobox, command, context-menu, dialog, direction, drawer, dropdown-menu, empty, field, form, hover-card, input, input-group, input-otp, item, kbd, label, marker, menubar, message, message-scroller, native-select, navigation-menu, pagination, popover, progress, radio-group, resizable, scroll-area, select, separator, sheet, sidebar, skeleton, slider, sonner, spinner, switch, table, tabs, textarea, toggle, toggle-group, tooltip). Import as `@/ui/<name>`. |
+| `lib/utils.ts` | `cn()` for merging class names. Import as `@/lib/utils`. |
+| `hooks/use-mobile.ts` | `useIsMobile()` breakpoint hook. Import as `@/hooks/use-mobile`. |
+| `styles/globals.css` | Tailwind v4 entry: `@source` for `pages/ ui/ lib/ hooks/ themes/`, the `dark` variant, `:root`/`.dark` OKLCH tokens, `@theme inline`, base layer. Loaded into every page automatically. |
+| `components.json` | shadcn config (style `new-york`, base `radix`, aliases `@/ui`, `@/lib/utils`, `@/hooks`, `@/components`). Activates the `shadcn` skill and CLI lookups. |
+| `themes/<id>.css` | Optional token overrides a page opts into with `meta.theme` (see Themes). |
+
+Installed deps you may import directly: `lucide-react` (icons), `radix-ui`, `class-variance-authority`, `clsx`, `tailwind-merge`, `cmdk`, `sonner`, `vaul`, `recharts`, `react-day-picker`, `date-fns`, `react-hook-form`, `zod`, `@hookform/resolvers`, `input-otp`, `embla-carousel-react`, `react-resizable-panels`, `next-themes`. Nothing else.
+
+`npx shadcn@latest add <item>` is only for **blocks** (`dashboard-01`, `login-03`, …) or third-party registries; every core component is already under `ui/`. For lookups use `npx shadcn@latest docs <component> --json`, `view`, `search` — details in the `shadcn` skill.
+
 ## 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` |
+| Layout + responsive | any multi-column layout, nav, app shell, sidebar, grid; anything that must work on mobile | `references/layout-and-responsive.md` |
+| Typography + color | picking a type scale, the token system, dark sections, contrast | `references/typography-and-color.md` |
+| Interactivity | state, forms, dialogs, toasts, tabs, 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` |
 
@@ -30,10 +48,11 @@ Details live under `references/` in this skill. **Read the relevant file before
 
 - 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.
+- A page may contain only `index.tsx`, `components/*.tsx`, `styles.css`, and `assets/`. Shared assets live in the root `assets/` folder and import via `@assets/...`. No `README.md`, no config files.
+- `ui/`, `lib/`, `hooks/`, `styles/globals.css`, and `components.json` are **workspace-level and shared by every page**. Do not edit a file under `ui/` to suit one page — wrap or extend it in `pages/<id>/components/` instead (`<Button className={cn('rounded-full', …)}>`, or a `HeroButton` that renders `<Button>`). Do not edit `styles/globals.css` from a page task; token changes belong to a theme (`create-theme`).
+- Do **not** touch `package.json`, `open-pages.config.ts`, or other pages. Do not add dependencies beyond the installed list above.
+- **Use `@/ui/*` first.** Hand-roll an element only when no shadcn component covers it (a hero, a marketing feature grid, a footer). Buttons, inputs, cards, dialogs, tabs, tables, menus, tooltips, forms: always the `ui/` component.
+- **Style with semantic tokens**, not raw palette classes: `bg-background text-foreground`, `bg-card`, `bg-primary text-primary-foreground`, `text-muted-foreground`, `border-border`, `bg-muted`, `bg-accent`, `text-destructive`, `ring-ring`, `rounded-lg`. Themes restyle every token at once; a page written in `bg-slate-900` ignores them. Raw palette utilities are for deliberate one-off brand moments only.
 
 ## File contract
 
@@ -41,6 +60,9 @@ Details live under `references/` in this skill. **Read the relevant file before
 // pages/<id>/index.tsx
 import type { PageMeta } from '@autono/open-pages';
 import { useState } from 'react';
+import { Button } from '@/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/ui/card';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/ui/tabs';
 
 export const meta: PageMeta = {
   title: 'Meridian — Launch',
@@ -49,100 +71,133 @@ export const meta: PageMeta = {
 };
 
 export default function Launch() {
-  const [open, setOpen] = useState(false);
+  const [yearly, setYearly] = useState(false);
   return (
-    <main className="min-h-screen bg-white text-slate-900 antialiased">
-      {/* sections */}
+    <main className="min-h-screen bg-background text-foreground antialiased">
+      <section className="mx-auto max-w-5xl px-6 py-20">
+        <h1 className="text-5xl font-bold tracking-tight">Your analytics, turned into decisions</h1>
+        <div className="mt-8 flex gap-3">
+          <Button size="lg">Start free</Button>
+          <Button size="lg" variant="outline">See how it works</Button>
+        </div>
+      </section>
+      <section className="mx-auto max-w-5xl px-6 pb-20">
+        <Tabs defaultValue={yearly ? 'yearly' : 'monthly'} onValueChange={(v) => setYearly(v === 'yearly')}>
+          <TabsList>
+            <TabsTrigger value="monthly">Monthly</TabsTrigger>
+            <TabsTrigger value="yearly">Yearly</TabsTrigger>
+          </TabsList>
+          <TabsContent value="monthly">
+            <Card>
+              <CardHeader><CardTitle>Growth</CardTitle></CardHeader>
+              <CardContent className="text-muted-foreground">$49 / month</CardContent>
+            </Card>
+          </TabsContent>
+        </Tabs>
+      </section>
     </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-…`).
+- `export default` is **one zero-prop React component** — the whole page. Its root is `min-h-screen bg-background text-foreground` (add `dark` to the root's `className` for a dark page — the variant is `&:is(.dark *)`, so every token flips underneath it).
 - `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.theme` (optional) opts the page into `themes/<id>.css` — the runtime injects that stylesheet into the preview frame and the export. The id must match a `themes/<id>.md` basename. Omit for the default neutral tokens.
 - `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`
+## Styling: tokens first, then shadcn, then utilities
 
-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`**:
+1. **Tokens.** Surfaces and text use the semantic classes from `styles/globals.css`. Pairs go together: `bg-primary text-primary-foreground`, `bg-card text-card-foreground`, `bg-muted text-muted-foreground`. Borders are `border-border`; focus rings `ring-ring`; radius `rounded-md`/`rounded-lg`/`rounded-xl` (all scale from `--radius`).
+2. **shadcn components** carry their own token styling and variants (`<Button variant="outline" size="sm">`, `<Badge variant="secondary">`). Reach for a variant before adding classes; add classes via `className` (merged with `cn`) for layout — width, margin, grid placement — not to repaint the component.
+3. **Tailwind utilities** on `className` for everything structural: containers, grids, spacing, type sizes, responsive variants. Arbitrary values are fine (`max-w-[72ch]`). Mobile-first: unprefixed utilities are the phone layout, `sm:`/`md:`/`lg:` layer on top.
 
 ```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>
+  <Badge variant="secondary">Pricing</Badge>
+  <h2 className="mt-4 text-3xl font-bold tracking-tight">Simple plans</h2>
+  <p className="mt-3 max-w-xl text-lg text-muted-foreground">Grow at your own pace.</p>
+  <div className="mt-8 grid gap-6 sm:grid-cols-3">
+    {plans.map((p) => (
+      <Card key={p.name} className={cn(p.featured && 'border-primary')}>…</Card>
+    ))}
+  </div>
 </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.
+- `className`, never a `tw` prop. Build class strings literally; `cn()` for conditionals — never `` `text-${size}` ``.
+- Icons: `lucide-react` (`<ArrowRight className="size-4" />`), sized with `size-*`, `aria-hidden` when decorative.
+- `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; never redefine the tokens there — that is a theme's job.
+- Preflight plus the shadcn base layer are applied inside the page: headings start unstyled (set sizes and weights explicitly); `body` already carries `bg-background text-foreground`.
 
-## Web type scale and color
+## Web type scale
 
 | 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 |
+| Secondary / captions | 13–14px (`text-sm text-muted-foreground`) |
 | 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`.
+- Contrast: body text must pass 4.5:1. The tokens pass by construction; if you reach for `text-foreground/40`, you are below the floor.
+- Details and the token → OKLCH map 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.
+- The inspector tags components as well as host elements: shadcn components spread their props onto their root, so a click on a rendered `<Button>` resolves to the `<Button>` line in *your* page, not to `ui/button.tsx`.
 
 ## 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
+grep -n '<section\|<h[12]\|<header\|<footer\|<Card\b\|<Dialog\b' 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.
+Landmarks, headings, and top-level shadcn wrappers anchor sections; read the target range with `offset` + `limit`. Read the whole file when auditing tokens 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.
+A theme is `themes/<id>.md` (direction and component notes) + `themes/<id>.css` (token overrides) + `themes/<id>.demo.tsx` (a demo page). If the page is meant to follow one, **read `themes/<id>.md` first — its guidance overrides the defaults in this skill** — and set `meta.theme: '<id>'`; the runtime injects the CSS. Do not paste token values into the page; the whole point is that the page stays token-based and the theme repaints it. 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`).
+- **Inspect mode** (toolbar button or `i`): the user clicks any element or component, 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.
+- `open-pages export <id>` builds `export/<id>/` — `index.html` plus hashed assets with relative URLs, bundling only the `ui/` components the page imports. 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.
+- [ ] `pages/<id>/index.tsx` default-exports **one** component; `meta` has `title` + fresh `createdAt` literal (+ `theme` if built from one).
+- [ ] Root element is `min-h-screen bg-background text-foreground`; the page has a `<main>` landmark.
+- [ ] Every button, input, card, dialog, tab, table, menu, tooltip, or form is the `@/ui/*` component, not a hand-rolled lookalike.
+- [ ] Colors are semantic tokens; raw palette classes appear only where a one-off brand moment was intended.
+- [ ] Nothing under `ui/`, `lib/`, `hooks/`, or `styles/` was edited.
 - [ ] 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.
+- [ ] Every `className` is Tailwind v4 the scanner will see (literal strings, `cn()` for conditionals).
+- [ ] Interactive elements are real `<Button>`/`<a>`/`<Input>` with visible focus styles and labels; images have `alt`.
+- [ ] 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.
 - [ ] Nothing outside `pages/<id>/` was edited.
 
 ## Anti-patterns
 
+- ❌ A hand-rolled `<button className="rounded-md bg-slate-900 px-4 …">` when `<Button>` exists. Same for inputs, cards, dialogs, dropdowns, tabs, tables.
+- ❌ Repainting a component with raw colors (`<Button className="bg-blue-600">`). Use a variant, or change the theme.
+- ❌ Editing `ui/button.tsx` because one page wants rounder buttons. Wrap it under `pages/<id>/components/`.
 - ❌ `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`.
+- ❌ Building class names at runtime (`` `text-${size}` ``) — Tailwind only generates utilities it can read literally.
+- ❌ `<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.
+- ❌ Global CSS resets, `body {}` rules, or `:root { --primary: … }` in the page's `styles.css`. Tokens belong to themes.
+- ❌ Installing packages, `npx shadcn add` for a component already in `ui/`, editing `package.json`/config/other pages, adding a `README.md` to the page folder.

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

@@ -2,49 +2,94 @@
 
 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.
+keep pages preview-safe, export-safe, and inspectable. Interactive UI comes
+from `ui/` first — `Tabs`, `Accordion`, `Dialog`, `Sheet`, `Drawer`,
+`DropdownMenu`, `Popover`, `Tooltip`, `Switch`, `Select`, `Combobox`,
+`Command`, `Slider`, `Toggle`, `Collapsible` all ship with keyboard handling
+and ARIA wired. Hand-rolled state is for what they do not cover.
 
 ## 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>
+const [billing, setBilling] = useState<'monthly' | 'yearly'>('monthly');
+
+<Tabs value={billing} onValueChange={(v) => setBilling(v as typeof billing)}>
+  <TabsList>
+    <TabsTrigger value="monthly">Monthly</TabsTrigger>
+    <TabsTrigger value="yearly">Yearly</TabsTrigger>
+  </TabsList>
+</Tabs>
 ```
 
 - 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`.
+- Controlled vs. uncontrolled: shadcn components accept `defaultValue` for
+  fire-and-forget UI and `value` + `onValueChange` (or `open` +
+  `onOpenChange`) when the page needs the value.
+- When you must hand-roll a toggle, it is a `<Button variant="outline"
+  aria-pressed={on}>`; a disclosure carries `aria-expanded` and
+  `aria-controls` — or just use `<Collapsible>`.
 
 ## 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`.
+Simple forms: `<form onSubmit>` with `@/ui/field`, `@/ui/input`, `@/ui/label`,
+`@/ui/select`, `@/ui/checkbox`, `@/ui/textarea`, `@/ui/button`. Validated
+forms: `react-hook-form` + `zod` through `@/ui/form`:
+
+```tsx
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+import { Button } from '@/ui/button';
+import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/ui/form';
+import { Input } from '@/ui/input';
+
+const schema = z.object({ email: z.string().email('Enter a valid work email') });
+
+const form = useForm<z.infer<typeof schema>>({ resolver: zodResolver(schema), defaultValues: { email: '' } });
+
+<Form {...form}>
+  <form onSubmit={form.handleSubmit((values) => setSubmitted(values))} className="flex flex-col gap-4">
+    <FormField control={form.control} name="email" render={({ field }) => (
+      <FormItem>
+        <FormLabel>Work email</FormLabel>
+        <FormControl><Input type="email" autoComplete="email" {...field} /></FormControl>
+        <FormMessage />
+      </FormItem>
+    )} />
+    <Button type="submit">Join the waitlist</Button>
+  </form>
+</Form>
+```
+
+- Every input has a label (`<Label htmlFor>` or `<FormLabel>`), 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.
 
+## Dialogs, sheets, toasts
+
+- Modal confirmation: `<Dialog>` / `<AlertDialog>` with a `<DialogTrigger asChild><Button>…`.
+  Side panels: `<Sheet>`; mobile bottom panels: `<Drawer>`.
+- Toasts: render `<Toaster />` from `@/ui/sonner` once at the root of the
+  page, then `toast('Saved')` / `toast.success(…)` from `sonner` in handlers.
+- Menus: `<DropdownMenu>` for actions, `<Select>` for a value, `<Combobox>`
+  / `<Command>` for searchable lists.
+
 ## Network and browser APIs
 
 - `fetch`, `localStorage`, `IntersectionObserver`, `matchMedia` are fine —
-  inside effects or handlers, with loading and error states.
+  inside effects or handlers, with loading (`<Skeleton>`, `<Spinner>`) and
+  error (`<Alert variant="destructive">`) 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.
+  something meaningful without it (`<Empty>`).
 - Access `window`/`document` only inside `useEffect` or event handlers.
   Module-top-level `window.innerWidth` breaks the module import and the
-  export build.
+  export build. For breakpoints use `useIsMobile()` from `@/hooks/use-mobile`.
 
 ## Effects and StrictMode
 
@@ -57,21 +102,24 @@ const [tab, setTab] = useState<'monthly' | 'yearly'>('monthly');
 
 - 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.
+- Hover-only affordances need a keyboard/touch equivalent (`<Tooltip>` and
+  `<HoverCard>` already handle focus).
 - 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.
+  `<a href="#section">` anchors for in-page navigation and `<NavigationMenu>`
+  or `<Breadcrumb>` for chrome.
 - 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
 
+- ❌ A `useState` + two `<div>`s reimplementing `<Tabs>`, `<Accordion>`, or `<Dialog>`.
 - ❌ `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>`.
+- ❌ Interactive `<div>`s. Use `<Button>`, `<a>`, `<Input>`, `<Select>`.

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

@@ -4,7 +4,9 @@ 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.
+layer larger layouts on top. `useIsMobile()` from `@/hooks/use-mobile` is
+available when JS must know (swap a `<Sheet>` for a `<Drawer>`, collapse a
+table into cards).
 
 ## Containers
 
@@ -17,14 +19,19 @@ layer larger layouts on top.
 - 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.
+  Sections separate by space or a hairline (`border-t border-border`, or a
+  `<Separator />`), 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} />)}
+  {features.map((f) => (
+    <Card key={f.title}>
+      <CardHeader><CardTitle>{f.title}</CardTitle></CardHeader>
+      <CardContent className="text-muted-foreground">{f.body}</CardContent>
+    </Card>
+  ))}
 </div>
 ```
 
@@ -32,35 +39,48 @@ layer larger layouts on top.
 - `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.
+- Tabular data is `<Table>` from `@/ui/table` inside an `overflow-x-auto`
+  wrapper; on mobile either let it scroll or render a card list.
 
 ## 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.
+- Marketing header: wordmark + `<NavigationMenu>` (or plain links) with
+  `hidden sm:flex`, one `<Button>` CTA. On mobile, a `<Sheet side="left">`
+  opened by an icon `<Button variant="ghost" size="icon" aria-label="Menu">`
+  holding the stacked links. Never let a nav overflow horizontally.
+- Sticky headers: `sticky top-0 z-10 bg-background/90 backdrop-blur border-b border-border`.
+- Sub-navigation and hierarchy: `<Breadcrumb>`, `<Tabs>`, `<Pagination>`.
 
 ## 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.
+- CTA row: `flex flex-col gap-3 sm:flex-row` with `<Button size="lg">` and
+  `<Button size="lg" variant="outline">` so buttons stack on mobile.
 
-## Full-viewport pages (dashboards, app UIs)
+## App shells (dashboards, tools, docs)
 
 - 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.
+- Sidebar layouts use `@/ui/sidebar`: wrap the page in `<SidebarProvider>`,
+  render `<Sidebar>` + `<SidebarInset>`; it collapses to a sheet on mobile by
+  itself and gives you `<SidebarTrigger />` for the topbar. Do not hand-roll
+  a `hidden lg:block w-64` aside when this exists.
+- Split panes (editor + preview, list + detail): `@/ui/resizable`
+  (`ResizablePanelGroup` / `ResizablePanel` / `ResizableHandle`); stack them
+  (`direction="vertical"`) or render one pane at a time on mobile via
+  `useIsMobile()`.
+- Content area: `min-w-0 flex-1` so tables and code blocks can shrink. Wide
+  content scrolls inside its own `overflow-x-auto` wrapper (or
+  `<ScrollArea>`); the page body must never scroll horizontally.
+- Loading and empty states: `<Skeleton>` while data arrives, `<Empty>` when
+  there is none.
 
 ## Checklist
 
-- [ ] Mobile: no horizontal scrollbar, every grid stacks, headings shrink.
+- [ ] Mobile: no horizontal scrollbar, every grid stacks, headings shrink, nav collapses into a sheet or wraps.
 - [ ] 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).
+- [ ] Touch targets ≥ 40px tall on mobile (`<Button size="lg">` or `py-2.5` on links).
 
 ## Anti-patterns
 
@@ -69,3 +89,4 @@ layer larger layouts on top.
 - ❌ `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).
+- ❌ A hand-built sidebar or drawer when `@/ui/sidebar`, `<Sheet>`, or `<Drawer>` fits.

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

@@ -7,54 +7,72 @@
 | 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 |
+| Lede | `text-lg sm:text-xl text-muted-foreground` | 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 | |
+| Secondary | `text-sm text-muted-foreground` | captions, metadata, table cells |
+| Eyebrow / label | `text-xs font-semibold uppercase tracking-[0.2em]` or `<Badge variant="secondary">` | above headings |
+| Code | `font-mono text-[0.9em] bg-muted rounded px-1` | |
 
 - 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`.
+- Fonts: `--font-sans` from the tokens is the default (system stack unless a
+  theme sets it). Load a display or brand font only when the user names one
+  or a theme requires it — see `assets-and-fonts.md`.
 
-## Palette structure
+## The token system
 
-One page, one palette. Name the roles up front and reuse them literally:
+`styles/globals.css` defines the shadcn tokens in OKLCH for `:root` (light)
+and `.dark`, and exposes them as utilities through `@theme inline`. Pages
+and `ui/` components read the utilities; themes rewrite the values.
 
-| Role | Light example | Dark example |
+| Token pair | Utilities | Use for |
 | --- | --- | --- |
-| 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.
+| `--background` / `--foreground` | `bg-background text-foreground` | page root |
+| `--card` / `--card-foreground` | `bg-card text-card-foreground` | panels, `<Card>` |
+| `--popover` / `--popover-foreground` | `bg-popover` | menus, popovers (used by `ui/`) |
+| `--primary` / `--primary-foreground` | `bg-primary text-primary-foreground` | the one accent: primary CTA, active state |
+| `--secondary` / `--secondary-foreground` | `bg-secondary` | secondary buttons, badges |
+| `--muted` / `--muted-foreground` | `bg-muted text-muted-foreground` | subdued surfaces, secondary copy |
+| `--accent` / `--accent-foreground` | `bg-accent` | hover surfaces, selected rows |
+| `--destructive` | `text-destructive`, `<Button variant="destructive">` | delete, errors |
+| `--border`, `--input`, `--ring` | `border-border`, `border-input`, `ring-ring` | dividers, field borders, focus |
+| `--chart-1`…`--chart-5` | `text-chart-1`, `fill-chart-1` | `<Chart>` series |
+| `--sidebar*` | `bg-sidebar` … | `<Sidebar>` shell |
+| `--radius` | `rounded-sm`…`rounded-2xl` | all radii scale from one value |
+
+- Always use a pair together: a `bg-primary` without `text-primary-foreground`
+  breaks the moment a theme changes the primary hue.
+- Opacity modifiers work on tokens: `bg-primary/10` for a tinted band,
+  `border-border/60` for a softer rule.
+- Dark pages: put `dark` on the root element's `className`. Every token flips;
+  no manual `dark:` prefixes needed unless a single element must differ.
+- Dark *sections* on a light page: wrap the section in `<div className="dark bg-background text-foreground">`.
+- Raw palette classes (`bg-emerald-400`, `text-slate-600`) are for deliberate
+  brand moments a theme should not repaint — a neon launch button, a
+  gradient hero. Keep them rare and keep them out of `ui/` components.
 
 ## 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.
+- Body text ≥ 4.5:1 against its background; large headings ≥ 3:1. The token
+  pairs pass by construction; `text-muted-foreground` is the floor for
+  secondary copy.
+- Do not dim below the floor with opacity: `text-foreground/40` and
+  `text-white/30` fail. Decorative metadata at most `text-muted-foreground/80`.
+- Accent text on light backgrounds must be the darker shade a theme sets for
+  `--primary`; on dark, the lighter one. Never `bg-primary` text on
+  `bg-background` without checking.
+- Links inside prose: `underline underline-offset-4`, not color alone.
 
 ## 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.
+- ❌ Hardcoding a palette per page (`bg-white text-slate-900` everywhere)
+  when `bg-background text-foreground` exists — the page silently opts out of
+  every theme.
+- ❌ `dark:bg-…` sprinkled on every element instead of one `dark` on the root.
 - ❌ Gradient text, drop shadows, and glows on every heading. One flourish, once.
-- ❌ Palette drift: a new grey shade every section.
+- ❌ Palette drift: a new grey shade every section. There are `muted`,
+  `card`, and `background`; that is the whole grey scale.