new-page
Add a new page to the website with the standard layout shell and correct navigation wiring. Use when asked to add or create a new page on the site.
SKILL.md.claude/skills/new-page/SKILL.md
GitHubnew-page
Add a new page to the website with the standard layout shell and correct navigation wiring.
When invoked
Use this skill when asked to add or create a new page on the website — phrases like "add a page for [X]", "create a [section] page", "add [X] to the site".
Component documentation pages and template screens are not built here: they belong to the design system, which lives in its own repo and at rift-ds.com.
Instructions
Gather requirements if not already provided:
- Page URL path (e.g.
/work/<slug>) - Which section it belongs to: the sidebar arrays in
website/src/config/navigation.tsare the authoritative list of sections (work, writing; writing is fed dynamically from Substack; standalone pages like/aboutand/contactlive in no sidebar array and declare their metadata as a literal). - Page title, a short
subDisplaytagline, and a 1–2 sentence description (for metadata and the intro block) - Figma URL (optional), for
PageLinks
- Page URL path (e.g.
Read the exemplars before writing anything. The live pages are the source of truth for structure — mirror them rather than writing a shell from memory:
website/src/app/privacy/page.tsx— a standard content page (layout shell, header and intro blocks)website/src/app/work/augmenta-ai/page.tsx+page.module.css+layout.tsx— the richest example, with per-page CSS and its own share cardwebsite/src/config/navigation.ts— nav config (single source of truth for sidebars, mega menu, and breadcrumbs; the sitemap derives its routes from the sidebar configs)
Create the directory
website/src/app/<path>/with three files, mirroring the exemplar:
File 1: page.tsx
- Copy the exemplar's shell exactly — same components, same nesting, same class names. Don't improvise structure.
- Invariants the exemplar can't teach:
subDisplayis a tagline inside the intro block — not the section name; the breadcrumb already shows where you are- All copy on the page (tagline, intro, body, metadata description) follows
content-design.md— voice, register, and the words-to-avoid tables - Sidebar links come from
getSidebarLinks(<section>SidebarLinks, "<your path>") - Include
PageLinksonly if the page has links to show (its props are the authoritative list of what it takes) - The on-this-page rail is automatic, not part of the shell.
SiteAnchorRailin the root layout reads every page's h2 headings after navigation and floats the rail on the right viewport edge, so a new page gets one with no wiring — never mount an anchor nav of your own by default. The gates live inwebsite/src/config/anchor-nav.ts, whose doc block owns the rules: an index or landing page registers inANCHOR_NAV_EXCLUDED_ROUTES; a page whose items must be derived server-side (markdown-extracted sections, labels that are not headings) mountsFloatingAnchorNavitself and registers inANCHOR_NAV_SELF_MANAGED_ROUTESso it never carries two (no page does today, so that set is empty).scripts/validate-route-config.mjsfails the build when either set names a path with no page behind it. Demo or furniture h2s that are not sections of the page sit insidedata-anchor-ignore(or an<aside>); the discovery rules live in the doc block ofwebsite/src/components/FloatingAnchorNav/SiteAnchorRail.tsx - Do not render a background.
BlurBackgroundis mounted once in the root layout and covers every route; adding it per page would build a second canvas and a second GL context on top of the first.scripts/validate-single-background-mount.mjsfails the build if you do
File 2: page.module.css
- Copy the exemplar's layout classes; add page-specific classes as needed
- Semantic design tokens only — no hardcoded colours or magic values
- Page assembly is a spec, not taste: the design system's spec (in the rift-ds repo and at rift-ds.com) owns the rhythm ladder and the assembly rules (parent owns spacing, one level of chrome, dividers last, prose never width-capped) — read it before laying out sections; the exemplar shows the pattern, the spec owns the rules
- No
ch-basedmax-widthon prose — doc paragraphs run the full content column; the layout column is the only width constraint (build-enforced byscripts/validate-copy-conventions.mjs) - Mobile type and section rhythm collapse at the token layer (display sizes and section-gap tokens step down system-wide — the design system's responsive spec owns the breakpoint) — do not add per-page
@mediaoverrides for tokenized values; when a page genuinely needs a breakpoint, use the canonical set in that same spec
File 3: layout.tsx
- Export
metadataas a literalMetadataobject with an explicitalternates.canonical, as the exemplar'slayout.tsxdoes - Standalone pages (
/contact,/design-system, pages in no sidebar array) do the same; seewebsite/src/app/design-system/layout.tsx, whose comment records why it is a literal - Deliberately hidden pages are the exception (
/coversand/rr-animatedare the precedent). A hidden page setsrobots: { index: false, follow: false }, skips the canonical and the sitemap entirely, appears in no nav surface, and records why in a comment beside that metadata: in itslayout.tsx, or in thepage.tsxitself when the page needs no layout of its own (/coversis the precedent for the simpler shape). A full-viewport page that should also render none of the shared chrome (the layout-mounted footer, chat panel, and command palette) additionally adds its route toCHROMELESS_ROUTESinwebsite/src/config/chromeless.ts; the set in that file is the authoritative list of what has taken the exception, andscripts/validate-route-config.mjsholds it to routes that exist. A hidden page also needs an entry inEXCLUDED_ROUTESinscripts/generate-site-corpus.mjswith a written reason, orvalidate-chat-coverage.mjsfails the build for an uncovered route. Suppressing chrome does not make the background full-bleed: by default every page gets the fixed-height band that fades into the page floor (the rules live inwebsite/src/app/globals.css). An immersive page must also render<FullBleedBackground />(exported fromwebsite/src/components/BlurBackground/BlurBackground.tsx), a hidden marker that CSS inglobals.cssreads to drop the fade and fill the viewport. Skip it and the page is chrome-free but band-limited, which looks wrong with nothing to explain why. Pick exactly one: the default band or full-bleed ambient - Default export wraps
{children}in a fragment
Register the page everywhere the site tracks pages:
- Sidebar (only if the page belongs to a section): add
{ href, label }to the section's array inwebsite/src/config/navigation.ts, matching that array's existing order convention (work is curated editorially, strongest first and roughly newest first) - Work pages are a second exception: a
/work/<slug>page must also be registered inwebsite/src/data/case-studies.json(near the top if it is the newest or the strongest —/workand the home page both derive from that order), with every fieldscripts/validate-case-studies.mjsrequires (itsREQUIREDlist is authoritative — read it rather than trusting any copy) and the logo/cover assets inwebsite/public. The validator fails the build for an unregistered case-study folder, so this is a gate, not a convention. A study with a vector cover has a second gate:scripts/validate-cover-rasters.mjsholdswebsite/src/data/cover-renders.json, the drawing map inwebsite/src/components/covers/case-study-covers.tsx, and the rendered webp files underwebsite/public/covers/renderedto each other in both directions — register the cover in all three (shoot the rasters withnpm run covers:renderagainst a running dev server) or the build fails. A study also gets a TLDR entry inwebsite/src/data/case-study-tldrs.ts(the key-claims block every /work page renders — that module's doc block owns why it lives outside the route folders, and content-design.md's register row owns its rules): no validator guards this pairing, so a missing entry fails silently unless the page's literal key lookup catches it - Standalone pages (no sidebar section): no array to edit, but the sitemap then knows nothing about the route, so add it to the
staticRouteslist inwebsite/src/app/sitemap.ts. If it is a top-level site page a visitor should reach from anywhere, also add it to thesiteLinksarray inwebsite/src/components/SiteFooter/SiteFooter.tsxand to the command palette's hand-writtennavigationgroup inwebsite/src/components/SitePalette/SitePaletteMount.tsx, or the page is unreachable from Cmd+K (no validator covers either). Hidden pages (see File 3) never enter the sitemap or the nav - Sitemap for sidebar-registered pages: automatic — it derives from the sidebar configs, so the entry above covers it
- Breadcrumbs: sub-pages of an existing section resolve automatically from the sidebar entry. Only if the page starts a new section: add a
breadcrumbSectionsentry inwebsite/src/config/navigation.ts - The site-chat corpus has a ceiling, and a visible page counts against it:
scripts/generate-site-corpus.mjsextracts every indexed page's prose automatically, so there is nothing to register — but a substantial page can push the corpus pastTOKEN_BUDGETand fail the build with an over-budget error before any validator runs. That constant's own doc block owns the call between raising the budget and trimming a section; read it, and runnode scripts/generate-site-corpus.mjs --sizesto see which section actually grew before deciding - The AI-summary panel: every page with the shared chrome gets the chat FAB, and hovering it opens a per-page summary with prompt chips. Add the page's entry to
website/src/data/page-summaries.json(routesmap: atitle, a super-concisetext, and 1 chip for a simple page, 2 for a dense one — the validator's field grammar is authoritative: text length and full stop, every chip carryingid/label/prompt, labels inside the suggestion budget, no em dashes) —scripts/validate-page-summaries.mjsfails the build for a route without one, so this cannot be skipped silently. Case-study pages derive theirs from their deks and need nothing here; an essay needs a hand-written entry under theessaysmap, keyed by its slug (written whennpm run sync:essaysbrings the essay in); a chromeless page has no FAB and is exempt automatically
- Sidebar (only if the page belongs to a section): add
Verify: load the page in the browser and confirm the sidebar highlights it, the breadcrumb trail is correct, and both themes render properly.