wealth/.claude/skills/front-end-architect/references/ui-rules.md

8.0 KiB
Raw Blame History

UI rules

UX, SEO, and asset rules for 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, or metadata. Work only on repositories, caches, actions, stores, or libs doesn't need it.

Contents: Images, fonts, and CSS (Fonts and the icon sprite) · SEO and i18n · 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.
  • 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). 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/<hash>.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 <use href> 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.
const immutable = [{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' }];

// inside headers()
{ source: '/fonts/:path*', headers: immutable },
{ source: '/icons/:path*', headers: immutable },

SEO and i18n

  • Build generateMetadata from configs/seo.ts: title, description, canonical URL, hreflang alternates, and Open Graph. Add JSON-LD for products, breadcrumbs, and the organization. Provide sitemap.ts and robots.ts.
  • Server Components translate with a per-request i18next instance from apps/<app>/src/i18n/; react-i18next hooks run only in client components. Set lang and dir on <html> from the locale.

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): 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 ? <Spinner /> : <List /> 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).
  • 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).

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.