`, and never fetch menu links on hover or tap: a menu, drawer, or mega menu renders its links in the server HTML and only hides them. A fragment (`#…`) never changes indexable content.
- Collapsed content that search engines need stays in the DOM: tabs, accordions, `
`, and sliders render those panels and slides in the server HTML, and only hide them (island's `TabsPanel` takes `forceMount` for this). Never mount such a panel when it opens (`{isOpen && }`), and never fetch its content on click: Google sees neither.
- Content that loads on visibility (`LoadOnVisible`) may or may not render for Google, and content that loads on interaction never does. Neither holds primary content or the only link to a page. Never lazy-load what shows when the page opens.
- Pagination: each page has its own URL (`?page=2`) and is its own canonical, and page 1 has one URL, without `?page=1`. Each page links to the previous, the next, and numbered pages with `` in both templates. "Load more" and infinite scroll fetch the same URLs and update the address with the History API. A page past the last answers 404.
- Filters: decide for each filter whether its URLs are indexable. Indexable filter URLs separate parameters with `&`, keep one parameter order, use one key per filter (`?color=red,blue`), and answer 404 for an empty, duplicate, or unknown combination; internal links always use that form. `robots.ts` disallows every other filter parameter and every sort order on listing paths, and an empty combination that includes one of those parameters answers 200 with the `no-results` empty state and Clear filters.
- Internal search: `robots.ts` disallows `/search` with one rule, and the page sets no robots tag, because Google never fetches a blocked URL to read one. Search never answers 5xx for an unknown query, and category pagination reaches every product without it. `/compare` is disallowed the same way, because every set of products is a new URL. A URL pattern that Google has already indexed gets `noindex` first, and `robots.ts` blocks it only after it drops out of the index.
- `robots.ts` never disallows product, cart, or checkout pages, or the JS and CSS files a template needs. Storebot-Google walks product, cart, and checkout pages to check prices and shipping, and it obeys `User-agent: *` rules; cart and checkout carry `noindex` instead. Add-to-cart works for an automated browser that keeps cookies.
- `sitemap.ts` lists every indexable URL in its canonical form, as a second path for discovery.
- Variants: each variant has its own URL (`?color=green&size=s`), linked with ``. The server preselects the variant's image, price, and availability from the URL, the canonical drops the variant parameters, and the `ProductGroup` markup stays the same for every variant. `robots.ts` never blocks a variant URL.
- An out-of-stock product stays a 200, indexable page with its stock text, a disabled buy button, and `OutOfStock` in its offer. The status codes for missing, replaced, and empty pages are in [error-handling.md](error-handling.md#b2cb2b-server).
- The URL decides the locale and the currency of an indexable page, never a cookie, `Accept-Language`, or the IP. Googlebot sends no `Accept-Language` and crawls mostly from US addresses, so it would index only one locale.
- Google's renderer keeps no cookies or storage, so viewer-dependent parts render their guest variant for it. Make that variant a neutral, same-size UI, never an error message or an empty box, which Google may report as a soft 404. Every request such a part sends while Google renders the page counts against the API host's crawl budget.
- Under overload, the reverse proxy or the CDN answers crawlers with 503 and `Retry-After`. A 5xx or 429 lowers Google's crawl rate for the whole host.
`apps//src/app/robots.ts`. `configs/seo.ts` lists `CRAWL_BLOCKED_PARAMS`, the sort, view, and non-indexable filter keys, and `LISTING_PATHS`, the path prefixes of filterable listings, such as `'/category/'`, `'/brand/'`, `'/seller/'`, `'/campaign/'`, and `'/offers'`. The parameter rules name only those paths, because product variant URLs use the same keys (`?color=green&size=s`) and stay open.
```ts
import type { MetadataRoute } from 'next';
import { CRAWL_BLOCKED_PARAMS, LISTING_PATHS } from '../configs';
import { clientEnv } from '../env';
export const dynamic = 'force-dynamic';
export default function robots(): MetadataRoute.Robots {
const params = LISTING_PATHS.flatMap((path) =>
CRAWL_BLOCKED_PARAMS.flatMap((key) => [`${path}*?${key}=`, `${path}*&${key}=`]),
);
return {
// Product pages and their variants, cart, and checkout stay open: Storebot-Google checks prices and shipping there.
rules: { userAgent: '*', disallow: ['/search', '/compare', ...params] },
sitemap: `${clientEnv.NEXT_PUBLIC_SITE_URL}/sitemap.xml`,
};
}
```
## Copy
- Every label, button, tooltip, and message is a simple, complete description of its purpose. Buttons name the action and its object ("Add this item to the cart", not "Add"). Headings describe their content. Tooltips describe the outcome, not the control.
- Error messages have three parts: what went wrong, why (if known), and what the user can do. "The file could not be uploaded because it is larger than 10 MB. Compress the image or choose a smaller file, then try again."
- Empty states say what would normally be here, why it is empty, and the next step, with a primary action when there is one: "Your cart is empty. Browse today's offers to find something you like." plus a "See offers" button.
## Feedback
- Every completed action shows a toast that says exactly what was done, naming the object when possible: "'Wireless headphones' was added to your cart". Success toasts auto-dismiss after 4–6 s. Error toasts come from `showActionError` ([code-patterns.md](code-patterns.md#validation-model-and-server-errors)): they stay until dismissed, name what failed, carry the hint or a support sentence with the reference ID, and offer Try again or Reload when the error's cause allows it.
- Destructive actions ask for confirmation, naming the object and the consequence: "Remove the saved address 'Home'? This cannot be undone."
- Prefer reversible designs: "Undo" in the toast when the back end supports it.
## Stability
Refetches, state updates, and re-renders must never make the UI disappear and reappear.
- Never switch between `isLoading ? :
` on refetch. Keep showing the data with a subtle inline indicator driven by `isFetching`.
- Keep layout containers mounted and swap only their contents.
- Use skeletons with the final content's dimensions, and reserve space for images and embeds with fixed aspect ratios.
- A part whose model uses `useSuspenseQuery` changes its query key inside `startTransition`, so a page or filter change keeps the current content instead of falling back to the skeleton.
## Loading, progress, and empty states
- Design the loading and empty states together with the populated state. Loading states are skeletons that match the final layout. Empty states use island's `EmptyState` (`no-data`, `no-results`, `not-found`, `no-access`) with one sentence and a primary action when there is one ([error-handling.md](error-handling.md#empty-states)).
- Anything that takes more than about 2 seconds shows progress and the current step. Never show a bare spinner for more than 3 seconds.
- The clicked button shows a spinner, becomes disabled, and changes its label to the in-progress form ("Placing order…"). The rest of the form stays visible and read-only.
## File uploads
- Every upload shows a progress bar with a numeric percentage ("Uploading… 63%"), the file name and size, a cancel button while uploading, and a clear success or failure state with a retry action. Uploads go through the feature client's `upload()`: its `onProgress` drives the bar, and the cancel button aborts the `signal`. Uploads never retry automatically; the retry action sends the file again (see [lib-http.md](lib-http.md#files)).
## Forms
- Validate on the client with valibot before submitting, and show errors inline under the field in plain language that says how to fix them ("Enter a 10-digit postal code without spaces."). Validate on blur first, then on change (`mode: 'onTouched'`).
- Put server errors in the right place (code in code-patterns.md) and scroll to and focus the first invalid field.
- Disable the submit button only while submitting, never because the form is invalid; users need to click it to find out what's wrong.
## Keyboard and context
- Tab order follows reading order, Enter submits, and Esc closes. Set sensible default focus and keep primary actions in consistent places.
- Preserve context: filters, sort, page, and scroll position survive navigating to a detail page and back. Filters, sort, and page live in the URL, so views are shareable and survive a refresh.
- Respect `prefers-reduced-motion` and `prefers-color-scheme`.
- Every scroll the page starts is smooth: anchor jumps, `scrollIntoView`, and `scrollTo` animate instead of jumping, so the user sees where they went. island's `island.css` sets `scroll-behavior: smooth` on every element and turns it off under `prefers-reduced-motion` ([code-patterns.md](code-patterns.md#tokens-and-tailwind-wiring)). Code that scrolls never passes `behavior`, so the CSS and the user's motion setting decide.
- Every root layout's `` has `data-scroll-behavior="smooth"`. Without it, Next.js 16 animates the jump to the top on every route change.
- A scroll container that code holds in place, such as a virtualized list or a chat log pinned to its end, adds `scroll-auto`, or every position fix animates.