Skip to main content

Page template

This page is both a worked instruction sheet and the literal source authors copy when writing a new surface page. Each section below opens with one paragraph telling you what belongs there, then a short example in the same shape the Ethos onboarding seeds pilot uses.

To start a new page:

  1. Pick the next pending row from the inventory at Client surface.
  2. Copy this file (docs/client/page-template.mdx) to docs/client/<route-derived-slug>.mdx (e.g. route /admin/reindex → admin-reindex.mdx). One page per Expo Router route file is the default; group two routes only when they share the same mental model and the same backend calls. Do not prefix the new filename with an underscore — Docusaurus treats leading-underscore basenames as partials (importable, not routable), which is why this template is named page-template.mdx, not _template.mdx.
  3. Replace the frontmatter values (the explanations below tell you what each field is for).
  4. Fill in each section, deleting the inline guidance prose as you replace it with real content.
  5. Update the inventory row in docs/client/index.mdx: flip Status from Pending to Covered and link to the new page.

Frontmatter​

What to set on every surface page:

FieldWhat goes there
titleHuman screen name in Title Case, matching how a reader would refer to the screen. Becomes the page H1 and the og:title.
descriptionOne paragraph, ≤200 chars, describing what the screen is and the most-useful fact about it. Powers <meta description>, og:description, and the JSON-LD description.
sidebar_positionInteger. The pilot is 1. New pages slot by editorial priority — there is no automatic numbering.
last_reviewedISO date (YYYY-MM-DD) of when this page was last verified against the client repo. Pair this with the visible "Last reviewed against client commit <sha>" line at the top of the body.
imageOmit. The site-wide OG fallback (/img/og/default.png) is the conscious choice per seo-conventions.md §2. Add a per-page OG raster only when there is editorial reason.

Opening (H1 + identification paragraph + last-reviewed line)​

The H1 matches title. One short paragraph identifies the screen in plain language — what a user sees on it and when they reach it. Name the route (the Expo Router path) and the component (the React component that renders it, relative to gnostikon-client/src/). Keep this paragraph to four lines or fewer; details live in the sections below.

Underneath the paragraph, place a single-line blockquote pinning the review to a specific client commit. Update the sha (and the last_reviewed frontmatter date) each time you re-verify the page.

Example shape:

# Ethos onboarding seeds

The curated-catalog screen a new user reaches after accepting the
no-Ethos CTA. The route is `/ethos-onboarding/seeds`; the component is
`EthosSeedSelectionScreen` in
`gnostikon-client/src/components/ethos-onboarding/`.

> **Last reviewed against client commit `ea9d091` (`gnostikon-client`, branch `main`).**

Visible elements​

Every element a user can see or interact with on the screen, with one short line per element describing what it does. Use a bullet list. Cover header chrome, every UI state (loading, ready, empty, error, skeleton, etc.), every interactive control, and any non-obvious accessibility detail. Ground every claim in the component source — do not invent elements the code does not render.

If the screen has distinct UI states (loading / ready / empty / error), make each its own bullet so a reader scanning for "what does the empty state say" finds it without scrolling.

Events & calls​

What the screen dispatches. Two kinds of dispatch:

  • Backend calls — every HTTP request the screen issues. Name the method + path (e.g. GET /api/ethos/seeds), the hook or service that wraps it, and when it fires (on mount, on tap, on retry, etc.).
  • Product events — every event the screen sends to the product-events channel. Name the dot.notation event (e.g. ethos.onboarding.catalog_viewed), the condition that fires it, and the non-base properties it carries.

Link backend calls by named endpoint in prose into /api/ — do not use /api/?op=… query params or /api/#… anchor links (the API page is a client-rendered SPA and those targets do not exist in the static HTML, so they break onBrokenLinks: 'throw' and the broken-anchor check). The product events section is the right cross-link for the event taxonomy itself.

API endpoints consumed​

Re-list the backend calls from the section above as a flat checklist, named-endpoint-prose-linked into /api/. This is the section a reader scanning for "what does this screen call" lands on, and it deliberately repeats the call inventory from Events & calls so they don't have to parse the larger section.

If the screen issues zero backend calls, write that explicitly ("No backend calls") rather than omitting the section.

Every /docs/guides/* page that walks through this screen as part of its end-to-end flow. Bullet list, each entry naming the guide and a one-line note on the segment that touches this screen. Bidirectional: each linked guide must carry a Screen reference back-link to this page, placed adjacent to the section that discusses this screen (usually a short paragraph, not a new H2 — see how docs/guides/ethos-onboarding.mdx § Browsing the seed list and docs/guides/auto-generate-bypass.mdx § Related do it).

If no guide currently passes through this screen, write "None — open a dx- task if a guide should walk through this surface."

Every /docs/architecture/* page whose decisions shape this screen. Bullet list. May be empty — write "None" rather than omitting the section. Architecture pages are coarser-grained than surfaces, so it is normal for one ADR to be cited by many surface pages; back-links from architecture pages to surface pages are not required (would clutter ADRs that are cited by many surfaces).