Skip to Content
SsuperslateDocs

Web UI patterns

Use the shipped React components, state boundaries, accessibility behavior, and tests.

The web application uses CSS Modules and semantic tokens rather than a utility framework. Reuse the existing primitives when they fit; add product-specific composition in the owning module instead of turning packages/ui into a second product domain.

Ownership

PathResponsibility
packages/uireusable interaction and presentation primitives, shared with Start
packages/ui/styles/_variables.csssemantic color, spacing, typography, elevation, and motion tokens
apps/web/src/componentsweb-only compositions and the data wrappers around shared ones
apps/web/src/components/layoutapplication shell, navigation, responsive layout, and error surfaces
apps/web/src/modules/<domain>route pages and product-specific composition
apps/web/src/servicestyped Hono calls and TanStack Query lifecycle
apps/web/src/storedeliberate client-only Zustand state
apps/web/src/configs/rpc-client.tscredentialed transport and stable application errors

Applications import package modules by path:

import Button from '@app/ui/button/Button'

The package never imports a router or an application's translation files. Each application supplies both once:

  • Router. UiRouterProvider takes a UiRouter with a Link component, useSearch, and useNavigateSearch. apps/web/src/configs/ui-router.tsx adapts React Router. Links, URL-synced search and filters, and useQueryParams all go through it.
  • Strings. Package components translate in the ui i18next namespace. The application registers uiEn at start-up and loads loadUiMessages(locale) alongside its own catalog, as apps/web/src/i18n/index.ts does. A string a package component shows belongs in packages/ui/i18n; a string only the application shows belongs in the application's catalog.

The package also holds the application frame both apps render, so a screen looks the same in either: app-shell (layout, navbar, sidebar navigation, account and organization menus), page-header, auth-layout (the sign-in card and its form styles), settings-layout (the settings navigation, section pages, and the account, billing, and organization page styles), error-page, and brand. Each takes its data and labels as props; the web app wraps them in apps/web/src/components/layout and the Start edition in apps/start/src/components.

Four product features ship as shared compositions too, so both applications render one implementation: language-switcher (the locale menu and useLanguageOptions), notifications (NotificationBell, NotificationInbox, and the NotificationPreferences type-by-channel matrix), file-library (FileLibrary: table, filters, upload validation and progress, download, delete confirmation, storage-disabled and empty states, mobile cards), and user-directory (UserDirectory and the UserProfile detail body). They own layout, copy, and interaction state, and take plain data shapes and callbacks rather than a contract type or a service. The application wrapper owns the query, mutation, transport, error reporting, route mapping, and page title; in the web app those wrappers are the files, notifications, users, and notification-settings pages, the navbar bell, and apps/web/src/components/language-switcher. A list composition takes the caller's createTableStore store, so the caller derives its request parameters with useTableQueryParams.

TanStack Query owns remote data. Do not copy API results into Zustand. Components do not call raw fetch; service modules own query keys, mutations, invalidation, and error conversion.

Included primitives

The current inventory includes buttons, inputs, forms, checkboxes, switches, selects, selectors, tabs, menus, breadcrumbs, tooltips, modals, drawers, bottom sheets, cards, stat cards, tags, date and date-range pickers, tables with pagination, filters, search, infinite-scroll triggers, skeletons, spinners, empty states, toasts, avatars, identity cells, file icons, file cells, date cells, area charts, async images, keyboard hints, and truncated text. The web application adds its own command palette, floating action button, and upload hook in apps/web/src/components, because each one is bound to web routes, stores, or services. user-directory is the reference composition for a paginated data table (Table + createTableStore + useTableQueryParams against a typed list endpoint); file-library is the reference for table cell primitives (FileCell / FileIcon / DateCell) over an owner-scoped list; the dashboard module is the reference for stat cards and charts. Zag-backed popovers are composed inside the date controls and notification bell rather than exported as a standalone primitive.

FileIcon resolves its glyph and category tint through resolveFileType, which maps a MIME type onto a fixed category set and falls back to the filename extension. Extend that map when a new upload type ships; do not branch on MIME strings inside a page. Its category tints are the one place in the primitive library that sets colour outside the token palette, and each has a dark-mode value.

Zag.js-backed controls must retain their keyboard, focus, and ARIA behavior. A similar visual built from generic div elements is not an equivalent replacement. Keep semantic labels and error associations when composing form controls.

Responsive and application states

Every material screen should deliberately handle:

  • initial loading and mutation-pending states;
  • empty data and disabled-provider states;
  • recoverable and terminal errors;
  • unauthenticated and unauthorized behavior;
  • keyboard navigation, visible focus, and screen-reader labels;
  • narrow viewport layout and touch targets;
  • reduced motion and sufficient contrast;
  • long names, translated-like expansion, and unbroken user content.

The settings shell has distinct desktop and mobile layouts. Tables include mobile card rendering; test both representations when columns or filtering change.

Motion

Every transition and animation takes its duration and easing from the motion tokens in packages/ui/styles/_variables.css, so a perceived-speed change is one edit:

TokenUse
--ease-outevery interaction, entrance, and exit
--ease-drawera drawer or sheet travelling in from the viewport edge
--duration-instantexits of small floating surfaces such as tooltips
--duration-fasthover, focus, and state colour changes; popover entrances
--duration-baseoverlays, modals, banners, layout changes, and drawer exits
--duration-slowedge-travel entrances only, paired with --ease-drawer
--duration-spinone revolution of a loading spinner, with linear

Use ease-out rather than ease-in or linear: the element responds the moment the user acts, and an exit is no slower than its entrance. Keep interface motion at or under 300ms. Looping skeleton and splash pulses are ambient and keep their own slower timing. The global prefers-reduced-motion rule in _reset.css collapses every duration, so a component needs no reduced-motion branch of its own unless it animates from JavaScript.

Localization

The buyer SPA ships English, Spanish, and German through i18next and react-i18next. Locale resources live in apps/web/src/i18n/locales, and the language switcher is available on both authentication and authenticated application surfaces, with the same preference also exposed as a language field in /settings/profile. The selected locale is stored in app.locale; otherwise the browser language is used, with English as the fallback. The runtime updates the document lang attribute when the locale changes.

Use useTranslation from @/i18n in React components and the exported i18n instance in service callbacks that cannot use hooks. Use interpolation and plural keys for variable copy, and pass the resolved locale into Intl or date-fns formatting. Do not assemble translated sentences from fragments when word order can vary by language.

Add every new key to every locale file. The i18n test enforces key parity so a missing buyer-facing translation fails the web test suite. API-provided notification bodies and provider error messages remain server-owned content and are displayed verbatim.

The service worker fallback at apps/web/public/offline.html cannot import the React locale bundle, so it carries the minimal offline copy for each supported locale and reads the same app.locale preference. Update that static copy when adding a locale.

Testing

bun test runs without a DOM. Existing component contract tests use react-dom/server to prove important static zero-key and disabled-provider states. They do not prove focus, pointer, portal, measurement, animation, or browser navigation behavior.

Use the smallest useful layer:

vp run --filter @app/web test
vp run --filter @app/web build

Behavior that depends on focus, pointer, portal, measurement, animation, or browser navigation is not covered by an automated suite: exercise it in the running application. Keep static rendering tests for deterministic copy and availability contracts, and preserve the production bundle budget.

Branding

Change identity and tokens through Customize branding and design tokens. Do not introduce Tailwind into the buyer SPA, embed the product name into every component, or manually edit generated PWA assets.

On this page