Page Consistency Guide — building a page that looks native¶

Audience: coding agents and contributors adding or editing pages. Companion to docs/design-language.md (tokens, themes, primitives) and app/CLAUDE.md (routing mechanics).

The site’s design language is Radial Avant-Garde Glass (see design-language.md): a radial shell — fixed ring backdrop, drifting aurora, slim top bar, and a central RMH hub that blooms into the liquid globe you turn to navigate — wrapping content rendered in the Liquid Glass material, in a strict high-contrast monochrome palette. The glass is shipped, not aspirational: surfaces are translucent tints over the shared aurora, every tier carries a rim glint, and the tier class is what the degradation switches (high contrast, reduced transparency, perf-lite) act on. Pages look consistent because they share four things: the _site radial shell, the PageLayout column system, the --site-* token contract, and the same route-level conventions (head/SEO, i18n, auth, loading and error states). This guide is the recipe.

1. Decide the page type first¶

Type	Where the file goes	Gets
Standard site page (feed, wallet, settings, admin, …)	`app/routes/_site/<name>.tsx`	Radial shell (ring backdrop, top bar, central hub nav), skip link, page entrance
Full-screen experience (game, `/login`, legal, marketing arm, Discord activity)	`app/routes/<name>.tsx` (top level)	Nothing — you own the whole viewport

This split is deliberate. Games, login, secret/*, the legal pages (terms, privacy, cookies, copyright, security) and discord/* are intentionally top-level — do not “fix” them into _site/.

2. Canonical standard page¶

// app/routes/_site/example.tsx
import { createFileRoute } from '@tanstack/react-router';
import { useTranslation } from 'react-i18next';
import { PageLayout } from '@/components/feed/PageLayout';

export const Route = createFileRoute('/_site/example')({
  head: () => ({ meta: [{ title: 'Example | RMH Studios' }] }),
  component: ExamplePage,
});

function ExamplePage() {
  const { t } = useTranslation('site');
  return (
    <PageLayout title={t('example-title', { defaultValue: 'Example' })}>
      <div className="px-4 pt-4 pb-12 max-w-2xl mx-auto">{/* content */}</div>
    </PageLayout>
  );
}

PageLayout (components/feed/PageLayout.tsx) supplies a flat, transparent big-type header — its h1 in the theme display font, sitting directly on the radial ring backdrop (the radial content layer strips the old bordered header capsule) — plus an optional back arrow (backTo/backLabel), optional breadcrumbs, and the width-constrained center column. There is no border-r app-frame edge and no in-page sidebar — the shell owns navigation (the radial hub everywhere, plus a persistent nav rail ≥1120px). The center column carries pb-dock to clear the mobile safe area.

rightSidebar is not an in-page column: it is portalled into the shell’s live rail, which exists only ≥1440px. Treat it as supplementary — anything load-bearing belongs in children.

Props: title, children, rightSidebar?, headerRight?, wide?, backTo?, backLabel?, breadcrumbs?.

The header is not sticky. The radial content layer unpins page-level sticky chrome — headers, tab strips, search bars — so every _site route flows on the document’s own scroll like the feed. That is what lets mobile Safari collapse its toolbars. Don’t re-pin one.

Feed-column variant¶

Pages that render a raw column (achievements, bookmarks) skip PageLayout and use AnimatedMain directly:

import { AnimatedMain } from '@/components/feed/AnimatedMain';
import { WIDE_NO_RIGHT_SIDEBAR_WIDTH } from '@/lib/layout-width';

<AnimatedMain className="w-full min-w-0 pb-dock" targetWidth={WIDE_NO_RIGHT_SIDEBAR_WIDTH}>
  {/* column content */}
</AnimatedMain>;

(No trailing spacer div is needed any more — the shell’s frame is a grid and owns the rail track.)

Widths come from lib/layout-width.ts: DEFAULT_WIDTH 648, WIDE_WIDTH 800, WIDE_NO_RIGHT_SIDEBAR_WIDTH 952. Don’t invent new column widths — they are the page’s preference (--main-target), and the shell raises the floor on wide screens (--rad-measure) so the column uses the window it is given. Pass wide (or wide on PageLayout) when the page should take the whole content track instead.

4. Full-screen games/apps¶

Apps (RMHbox, RMHType, RMHStudy, RMHTube, RMHMusic) are not freeform: they share the --app-* token contract and chrome in components/shared/ (app-theme.css, AppShell, AppHeader, AppToaster + lib/shared/app-toast, ConnectionStatus). A new app writes a palette class and nothing else — mount AppShell with it, use AppHeader for the app bar. See design-language.md §12; writing a sixth shell, header or toast store is the exact drift that tier exists to prevent.

Games own their viewport and their look, but still share:

components/shared/GameLoadingFallback.tsx and components/shared/GameErrorBoundary.tsx (strings in the shared namespace).
Auth via the same session (useSession() from @/components/Providers, or a beforeLoad redirect).
Reduced-motion respect where feasible (canvas/WebGL excluded).
The theme class is suppressed on game routes (THEME_EXCLUDED_ROUTES in components/Providers.tsx) — game UIs use their own palettes, often defined as dedicated variable groups in globals.css (e.g. --temple-*, --slice-*, --neon-*).
Realtime games connect through lib/<game>/socket.ts singletons — see server/CLAUDE.md for ports, paths, and event naming.

5. Common drift patterns to avoid¶

These are the mistakes that make a page feel “off” — reviewers will flag them:

Hardcoded colors (bg-zinc-900, text-white, hex values) instead of site-* tokens — breaks every theme at once. CI-enforced for site-tier files (design-language.md §13 rule 5). Two legitimate escapes, both tokenised: a chip that sits on a photograph uses the --site-media-* contract (theme-tracking ink over someone’s snapshot is the wrong answer), and a domain-fixed palette — a playing card, a roulette pocket — gets a scoped variable group like --casino-*.
rounded-lg/rounded-2xl instead of rounded-site* — hardcodes a radius that ignores each theme’s --site-radius / --site-radius-sm. CI-enforced (§13 rule 6). rounded-full and rounded-none are shapes, not radii, and stay fine. 2b. A dropdown / popover / menu / tooltip on .glass-fill instead of .glass-overlay. L1 has no backdrop blur — it is the tier for repeated cards — so a menu built on it is transparent over whatever it opened on top of. CI-enforced (§13 rule 7). 2b2. transition-all. It makes the engine watch every animatable property including the layout ones, so a state change that touches width or gap animates a reflow. Name what moves (transition-colors, transition-transform, transition-[a,b], or plain transition). CI-enforced (§13 rule 8). And if a layout property IS what you want to animate, reach for a transform first — a progress bar is scaleX on a full-width fill, not an animated width. 2c. A bare duration-200 / duration-300 instead of duration-site / duration-site-fast / duration-site-slow, which follow the theme’s --site-transition-speed. Anything the user drags is a spring (APPLE_SPRING), not a duration at all.
A custom page header instead of PageLayout’s — or re-pinning one. The shell’s header is a flat, transparent big-type block floating on the ring backdrop, and the radial content layer deliberately unpins page-level sticky chrome so every route flows on the document’s own scroll (which is the only way mobile Safari collapses its toolbars).
Arbitrary column widths instead of lib/layout-width.ts constants.
Hand-rolled modals/spinners/empty states/copy-buttons instead of the components/ui/ primitives, or native window.confirm instead of useConfirm.
Untranslated strings (missing t()), or t() without defaultValue.
Forgetting the bottom padding (pb-dock) on custom columns → content hidden behind the floating mobile dock. .pb-dock clears the dock, the home indicator, and iOS Safari’s floating tab bar (via --safe-bottom) on mobile and collapses to 0 at md+. Also: putting a backdrop tier (.glass-pane/chrome/overlay) on repeated list items (blur cost) or on an ancestor of a position:fixed element (containing block) — see design-language.md §5.1.
Adding react-icons, new font imports, or one-off animation systems. 8b. Re-introducing cursor tracking — a pointermove listener, a hover hotspot, a card tilt, a “follow the mouse” glow. The whole class of effect was removed in one pass (design-language.md §5.1.1). Same for a reveal-on-scroll that defaults to opacity: 0: use useReveal, whose hidden state is opt-in and therefore cannot strand content when the JS does not arrive.
Re-adding app-frame edges: border-r border-site-border on page columns, full-bleed sticky top-0 border-b headers, or a re-implemented sidebar — the radial shell owns the chrome (ring backdrop, top bar, central hub nav), and PageLayout’s header is a flat big-type block floating on the backdrop, not a bordered capsule.
Hand-rolling a layoutId tab capsule instead of LiquidTabs, or stacking .glass-refract onto a .glass-chrome--aside element (its ::before is the blur carrier, so the lens band has nowhere to live — see design-language.md §5.1). The aside’s glint rides its own border-box background layer now (§4.35), not a pseudo.

Page Consistency Guide — building a page that looks native¶

1. Decide the page type first¶

2. Canonical standard page¶

Feed-column variant¶

3. The consistency checklist¶

Structure¶

Visual tokens (see design-language.md §1)¶

States¶

Head / SEO (see app/CLAUDE.md for details)¶

i18n¶

Motion & accessibility¶

Before committing¶

4. Full-screen games/apps¶

5. Common drift patterns to avoid¶