5.6 KiB
5.6 KiB
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, or metadata. Work only on repositories, caches, actions, stores, or libs doesn't need it.
Contents: Images, fonts, and CSS · SEO and i18n · Copy · Feedback · Stability · Loading, progress, and empty states · File uploads · Forms · Keyboard and context
Images, fonts, and CSS
- Use
next/imagewith explicit dimensions andsizes. Never lazy-load the LCP image: give itloading="eager"andfetchPriority="high", orpreloadwhen it's discovered late.priorityis deprecated in Next.js 16. Everything below the fold stays lazy. - Fonts come from
island/fontsas variable woff2. Preload only the critical face, usefont-display: swap, and use a size-adjusted fallback so the swap doesn't shift layout.next/font/localdoes both. - 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).
SEO and i18n
- Build
generateMetadatafromconfigs/seo.ts: title, description, canonical URL,hreflangalternates, and Open Graph. Add JSON-LD for products, breadcrumbs, and the organization. Providesitemap.tsandrobots.ts. - Server Components translate with a per-request i18next instance from
apps/<app>/src/i18n/; react-i18next hooks run only in client components. Setlanganddiron<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 byisFetching. - 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
useSuspenseQuerychanges its query key insidestartTransition, 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(): itsonProgressdrives the bar, and the cancel button aborts thesignal. 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-motionandprefers-color-scheme.