Frontend
Next.js apps, the @dental/ui design system, tokens, and the conventions every app follows.
Owner: Frontend PlatformLast reviewed:
All web apps are Next.js App Router apps (pinned via the pnpm version catalog) that follow the BFF pattern from ADR 0003: encrypted HttpOnly session cookies, tokens attached server-side, nothing sensitive in browser storage.
Apps
| App | Package | Port | Purpose |
|---|---|---|---|
| Clinic web | @dental/clinic-web | 3000 | Recording, documentation, treatment planning, review, clinic management |
| Patient portal | @dental/patient-portal | — | Document review, e-signature, treatment acceptance |
| Platform admin | @dental/platform-admin | — | Cross-tenant platform operations |
| Docs (this site) | @dental/docs | 3003 | Internal documentation (Fumadocs) |
| Storybook | @dental/storybook | 6006 | @dental/ui design-system explorer |
Shared packages
@dental/ui— the design system: tokens-driven components, floating-label fields, the semanticAppIconregistry (ADR 0015), theContextIsland(ADR 0014), waveform visualizers, and the application shell. Explore it interactively in Storybook (pnpm --filter @dental/storybook dev).@dental/design-tokens— semantic CSS custom properties (--dt-*) for color, radius, spacing, typography, motion, and elevation, with light/dark themes keyed offdata-theme.@dental/localization— next-intl messages and helpers (English/French).@dental/api-client— OpenAPI-generated types and a typed fetch client for core-api.@dental/schemas,@dental/clinical-types,@dental/template-definitions— shared zod schemas, clinical domain types, and document template definitions.@dental/permissions,@dental/observability,@dental/test-fixtures,@dental/configuration— role/permission maps, logging/tracing helpers, synthetic test data, and shared tsconfig/ESLint presets.
Conventions
- Dependencies come from the version catalog in
pnpm-workspace.yaml— apps declare"catalog:", never their own versions. - tsconfigs extend
@dental/configurationpresets (tsconfig.nextjs.jsonfor Next apps,tsconfig.base.jsonelsewhere). - Styling: Tailwind CSS v4. Each app's global stylesheet imports
tailwindcss, then@dental/ui/styles.css, then registers@source "../../../packages/ui/src"so utilities used by the shared UI are generated. Never hardcode design values — use token-mapped utilities likebg-surface,text-primary,rounded-card,rounded-toast. - Toasts: mount
<Toaster />once; use the imperativetoast.*API. Placement is top-center with--dt-radius-toast/shadow-floating. Never put PHI in toast copy (Storybook → Components/Toast). - Secure messaging chat: use
ChatPanel+ChatComposer+ChatBubble(compact bubbles, in-panel composer, Sent/Seen + seen-at, typing indicator, emoji picker with search/recent). Documented in Storybook → Components/Chat anddocs/product/secure-messaging-chat.md. - Icons: only through
<AppIcon name="…" />semantic names; importing glyph packages directly is blocked by ESLint (ADR 0015). - Workflow status UI: drive the
ContextIslandstate machine — never hand-rolled booleans (ADR 0014). - Accessibility: WCAG 2.2 AA — visible focus, reduced-motion variants, 44px touch targets, meaning never conveyed by color alone.