# UI rules UX, SEO, and asset rules for [b2c-b2b.md](b2c-b2b.md). Read it when you build or change what the user sees or what search engines read: a page, template, organism, form, copy, upload, image, font, icon, metadata, or viewport. Work only on repositories, caches, actions, stores, or libs doesn't need it. Contents: Images, fonts, and CSS (Fonts and the icon sprite) · Metadata and viewport · SEO and i18n · Crawlers · Copy · Feedback · Stability · Loading, progress, and empty states · File uploads · Forms · Keyboard and context ## Images, fonts, and CSS - Use `next/image` with explicit dimensions and `sizes`. Never lazy-load the LCP image: give it `loading="eager"` and `fetchPriority="high"`, or `preload` when it's discovered late. `priority` is deprecated in Next.js 16. Everything below the fold stays lazy. - Content images are `` elements with a `src`, as `next/image` renders them, never CSS backgrounds: Google indexes images only from ``. Both templates use the same image URLs and alt texts. A gallery or a slider renders every slide's `` in the HTML, and only the first one is eager. - Fonts come from `island/fonts` as variable woff2. Preload only the critical face, use `font-display: swap`, and give each face a size-adjusted fallback face so the swap doesn't shift layout ([code-patterns.md](code-patterns.md#tokens-and-tailwind-wiring)). Never use `next/font`: it renames the files (next section). - Reserve space for images, banners, ads, and embeds with fixed aspect ratios. - Register every project whose components use Tailwind classes as a source (see code-patterns.md). ### Fonts and the icon sprite Fonts and the icon sprite change rarely, and every page needs them. A hash in their file names changes whenever a build step changes its output, such as a Next.js or svgo upgrade or a new loader option, even when the file itself didn't change. Every visitor then downloads them again. So they keep fixed names, and only a developer decides when visitors download them again. - Names: fonts keep their own names, such as `yekan-bakh-vf.woff2`, and the sprite stays `symbol-defs.svg`. Each app serves them from `public/fonts/` and `public/icons/`. - No step adds a hash to them or renames them: not the bundler, not the CSS pipeline, not `next/font` (it copies fonts to `_next/static/media/.woff2`), not `icon-sprite-plugin`, not a CDN upload. `fonts.css` names each file by its root path, `url('/fonts/yekan-bakh-vf.woff2')`, which Next.js leaves alone. A relative path such as `url('../fonts/...')` goes through the bundler and gets a hash. - Fonts have no version. A font file never changes under its name: a changed font ships as a new file with a new name. - The sprite has a version in its link, never in its file name: `/icons/symbol-defs.svg?v=1`. island `constants.ts` holds `ICON_SPRITE_VERSION` and the `ICON_SPRITE_URL` built from it, and the `Icon` atom points `` at `${ICON_SPRITE_URL}#${name}`. A new Icomoon import or a changed svgo config raises `ICON_SPRITE_VERSION` in the same commit. Never reuse or lower a version. - The critical font's path lives in island `constants.ts` as `CRITICAL_FONT_URL`, and each root layout preloads it with `preload(CRITICAL_FONT_URL, { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })`. The preload URL must equal the one in `fonts.css`, or the browser downloads the font twice. - Serve them as immutable. Next.js serves `public/` with `Cache-Control: public, max-age=0`, so the browser asks again on every visit. Add this to the `headers()` in `next.config.ts`, and keep the same header on the CDN. The CDN must keep the query string in its cache key, or a new `?v=` still gets the old sprite. ```ts const immutable = [{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' }]; // inside headers() { source: '/fonts/:path*', headers: immutable }, { source: '/icons/:path*', headers: immutable }, ``` - The pwa lib's service worker keeps them too, by exact URL with the `?v=` included ([lib-pwa.md](lib-pwa.md)). A new sprite version reaches each visitor with their next request, and the worker deletes the old one. The worker checks fonts and the sprite in the background (stale-while-revalidate), so a font changed under its old name reaches each visitor one visit late; a changed font still always gets a new name. ## Metadata and viewport - Metadata is always in ``. Since Next.js 15.2, metadata streams into `` after the shell, and only a built-in list of HTML-limited bots waits for it in ``. Every app's `next.config.ts` sets that list to every user agent, so crawlers, link previews, and iOS's Add to Home Screen all find the tags in ``: ```ts htmlLimitedBots: /.*/, ``` - The body still streams: Suspense parts arrive after the first flush as before. - The cost: the first flush waits for `generateMetadata`, so it becomes the page's TTFB, and on a client-side navigation the page's content waits for it too (a `loading.tsx` still shows at once; a link to an indexable page, which has none, is a `NavLink` that shows a pending hint). Keep it fast: it reads only the caches the page's first paint awaits anyway, so it adds no request. - A request without a `User-Agent` header still gets streamed metadata. - Fixed values use the `metadata` export: tags that are the same for every request, such as `robots: { index: false }` in the `(account)` layout, or `APPLE_WEB_APP` in the root layout ([lib-pwa.md](lib-pwa.md#splash-screens)). `generateMetadata` is only for values that depend on the request or on data: params, search params, the locale, or a cache read. The same split holds for `viewport` and `generateViewport`. A segment exports one of each pair, never both: when part of it is dynamic, `generateMetadata` spreads the fixed values from a constant. - Build metadata from `configs/seo.ts`: title, description, canonical URL, `hreflang` alternates, and Open Graph. Provide `sitemap.ts`, `robots.ts`, and the web app manifest's `manifest.ts` ([lib-pwa.md](lib-pwa.md#web-app-manifest)). - Robots tags, the canonical URL, and the title come only from server metadata; only error boundaries render their own `noindex`. Client code never sets, changes, or removes them: Google may skip rendering a page whose server HTML says `noindex`, and it reads the canonical only in ``. So a page that should rank never ships `noindex` to remove it later. - Every root layout's viewport is `width: 'device-width', initialScale: 1, maximumScale: 1`, kept as `ROOT_VIEWPORT` in `configs/seo.ts`. Next.js renders ``, always in ``, because the viewport never streams. Without `maximum-scale=1`, Safari on iPhone zooms in whenever an input, select, or textarea with text smaller than 16px gets focus, and the page stays zoomed after the keyboard closes. The root layout's `generateViewport` returns `ROOT_VIEWPORT` with the `themeColor` of the theme the server chose; `themeColor` belongs to the viewport, never to `metadata`. - Accepted trade-off: iOS still lets the user pinch-zoom, but Chrome on Android doesn't unless the user turns on "Force enable zoom", and Lighthouse's `meta-viewport` accessibility audit fails. Reviews don't flag it. Never add `userScalable: false`: it blocks pinch-zoom everywhere else too. ## SEO and i18n - Every indexable page renders its schema.org JSON-LD with the json-ld lib ([lib-json-ld.md](lib-json-ld.md)): the business and the website on the home page, the product with its offer, rating, and breadcrumb on product pages, the breadcrumb on listing pages, and the store-wide return and shipping policies on their own pages. It says only what the page shows: the same name, price, availability, rating, and trail, in the page's language, with machine values (Latin digits, ISO 8601 dates, ISO 4217 currency). - Server Components translate with a per-request i18next instance from `apps//src/i18n/`; react-i18next hooks run only in client components. Set `lang` and `dir` on `` from the locale. ## Crawlers Googlebot Smartphone crawls the mobile template, and Google indexes what it reads there. Google renders JavaScript later, hours later for some pages, or never, and its renderer never clicks, scrolls, types, or keeps cookies. So what search engines need is in each template's server HTML. Each page's rendering doc records where every section stands ([page-rendering.md](page-rendering.md)). - The first flush of both templates holds the page's primary content: the H1; the main entity's name, price, availability, description, specs, and rating summary; the breadcrumb; the LCP image; the JSON-LD; and the links that are the only path to other pages. Streamed parts hold only secondary content. They sit in a hidden `
` at the end of the document until JavaScript moves them, Googlebot reads only the first 2 MB, and a slow part keeps the connection open, which uses up the site's crawl capacity. - Both templates hold the same primary content and headings, with one H1 that has the same text; the same internal links, image URLs, and alt texts; the same title, description, canonical, and robots tags; and the same JSON-LD and status. A template may collapse or reorder a section that search engines need, but never drop it; only a section they don't need, such as the mobile bottom navigation, may be in one template. Google indexes only the mobile template, and Googlebot Desktop still crawls product pages for Shopping. The breadcrumb shows in both templates, although Google shows it only in desktop results. - Links that crawlers follow are `` elements with a real URL in the server HTML: `next/link`, or an anchor. Never navigate with `onClick` and `router.push`, a `