Web frontend
The web runs on uncontrolled browsers and networks: HTML parsing, JS execution, style/layout, input, and accessibility. This page uses React + TypeScript as the primary reference (aligned with this docs site and many product stacks); ideas transfer to other frameworks.
Platform layers (in the browser)
| Layer | Focus | Notes |
|---|---|---|
| Document | Semantic HTML, SEO, progressive enhancement | Structure before chrome |
| Style | Layout, theme, responsive | Design tokens; limit global leakage |
| Behavior | Events, state, fetching | Validate API payloads at the edge |
| Assets | Images, fonts, splitting | AVIF/WebP, loading=lazy |
React app shape (default)
| Area | Role |
|---|---|
| Routing | URL ↔ views; loaders and error boundaries |
| Components | Presentational vs container; composition over inheritance |
| State | Separate server state from UI state |
| Data | fetch / RTK Query / React Query; cache & invalidation |
Server state (remote truth): query libraries for stale time, retry, dedupe.
UI state (local UX): useState / small context; avoid global stores by default.
Default data flow: props down, events up; context or light store across trees; global state only when measured need exists.
TypeScript and API edges
- Validate API responses at the boundary (zod, valibot) before deep trees
- Explicit prop types; stable list
keys - Strict
tsconfig:strict, addnoUncheckedIndexedAccessgradually if needed
Matches architecture · boundaries: do not leak backend DTO shapes into every component.
Performance checklist
| Item | Practice |
|---|---|
| First paint | Route-level code splitting, critical CSS |
| Render | Avoid needless child re-renders; memo only with profiling |
| Lists | Virtualize very long lists |
| Network | Cache headers, compression, fewer waterfalls |
| Images | srcset, placeholders, prioritize LCP |
Measure with Lighthouse and Web Vitals (LCP, INP, CLS); spot-check on real 4G devices.
Accessibility
- Prefer native controls or complete roles / keyboard / focus
- Contrast and type scale; respect system settings
- Forms: associated
label,aria-invalid, readable errors - Motion:
prefers-reduced-motion
Test pyramid (frontend)
| Level | Tools | Target |
|---|---|---|
| Unit | Vitest/Jest + RTL | Pure functions, hooks, small components |
| Integration | RTL | Forms, routing |
| E2E | Playwright | Critical paths, sampled browsers |
Run E2E smoke on PRs, fuller suites on schedule—see CI/CD.
This docs site
Built with Docusaurus + React: MDX as documentation components; i18n splits /docs and /en/docs. Theme or sidebar edits should keep builds and the English mirror in sync.