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, slim top bar, and a central RMH hub that blooms the navigation — wrapping content that ships as a flat high-contrast monochrome baseline today and references Apple-style Liquid Glass optics as its direction. 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?.

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.
rounded-lg/rounded-2xl instead of rounded-site* — hardcodes a radius that ignores each theme’s --site-radius (16px) / --site-radius-sm (10px).
Custom headers instead of PageLayout’s sticky header.
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.
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 pushing¶

4. Full-screen games/apps¶

5. Common drift patterns to avoid¶