UI Page Standards

Use when creating a new page.tsx, route segment, or auditing existing pages.

Page Metadata (MANDATORY for New Pages)

Required Exports

• Every new page.tsx MUST export metadata (static) or generateMetadata (dynamic)
• NEVER ship a page with default/empty Next.js metadata

Required Fields

Link Preview Image

Every page needs a preview image for social sharing (Slack, Twitter, iMessage, LinkedIn).

• Check if the project already has a default preview image (/app/opengraph-image.png or similar)
• If a project default exists, reference it
• If a route-specific image makes sense, add opengraph-image.png (static) or opengraph-image.tsx (dynamic) in the route segment
• If no image exists and you don't know what to use: ASK THE USER. Do not skip it, do not use a placeholder.
• Standard dimensions: 1200x630px

Static vs Dynamic

• Static page with known content: use metadata export object
• Dynamic route with params (e.g., [slug]): use generateMetadata({ params }) function

New Page Checklist

When creating a new page, the builder MUST also create or verify:

Rules:

• loading.tsx skeleton MUST mirror the page's layout structure (not a generic spinner)
• error.tsx MUST show a user-friendly message with a "Try Again" button that calls reset()
• Navigation: check if the page should appear in the site's primary nav, sidebar, or footer. If unsure, ASK THE USER.
• For nested routes: check if breadcrumbs are appropriate

Component States

Every data-driven component MUST handle three states:

Rules:

• Loading skeletons must match the final layout shape (same heights, widths, spacing)
• Empty states must have an action when possible (create, import, change filters)
• Error states must offer retry. For persistent errors, offer an alternative path.
• Use Suspense boundaries at appropriate levels (page-level for main content, component-level for independent sections)
• If using React Server Components: errors in server components bubble to nearest error.tsx. The builder must ensure one exists.

Form Completeness

Every form MUST have:

Rules:

• Validation messages must be specific ("Email must include @") not generic ("Invalid input")
• Server-side validation is ALSO required for security -- client-side is for UX only
• For server actions: use useFormStatus() for pending state, useFormState() for error handling
• For API routes: validate input with Zod or similar, return structured errors
• If you don't know what validation rules to apply: ASK THE USER.

Mobile-First

Every UI change must work on mobile:

Rules:

• The builder's Design Intent MUST include a "Mobile Approach" section stating how the layout adapts
• If a design looks good on desktop but would clearly break on mobile, the builder must address it proactively

Structured Data and SEO

When creating pages that represent entities (articles, products, FAQs, events, organizations):

Rules:

• JSON-LD goes in a <script type="application/ld+json"> tag
• In Next.js App Router: use the metadata export or generateMetadata to include JSON-LD
• Canonical URLs: every page should have a canonical URL. Use metadata.alternates.canonical
• If you don't know the schema type for a page: ASK THE USER.
• This is NOT required for utility pages (settings, login, admin dashboards, etc.)

API Route Patterns

When creating or modifying Next.js API routes (route.ts files):

Rules:

• Never expose internal error messages to clients (security risk)
• For authenticated routes: check auth FIRST, before any other logic
• For mutations: consider idempotency (especially for payment-related routes)

Site Infrastructure

Check that these exist when working on a new Next.js project:

Rules:

• Don't create these automatically -- ASK if the project needs them
• For existing projects: check what exists and only flag what's missing
• This is a ONE-TIME check, not a per-page check

Dark Mode / Theme Considerations

When implementing or touching theme/color-related code:

Rules:

• Only applies when the project HAS dark mode or the task is adding dark mode
• If adding dark mode: use next-themes or a similar battle-tested solution
• Test both themes before declaring done