Frontend & UI Architecture

Frontend & UI Architecture

ClinicFlow’s frontend prioritizes a premium, Apple-tier visual aesthetic (“Liquid Glass”) combined with rigorous accessibility and performance. To achieve this without technical debt, the UI layer relies on strict constraints rather than creative freedom.

Core Stack

• Radix UI: Provides headless, fully accessible primitives (Dialogs, Dropdowns, Tabs). We never build complex interactive state from scratch; Radix handles ARIA compliance and keyboard navigation.
• Framer Motion: Powers all complex scroll-driven animations and page transitions.

Motion Principles

Every animation in ClinicFlow uses physics-based spring animations, completely abandoning linear CSS transitions. For example, the PlanBuilderBar emerges using a precise spring configuration (stiffness: 400, damping: 30) to feel snappy and organic.

<motion.div
  initial={{ y: 50, opacity: 0 }}
  animate={{ y: 0, opacity: 1 }}
  exit={{ y: 50, opacity: 0 }}
  transition={{ type: 'spring', stiffness: 400, damping: 30 }}
>

---

Design Guard (design-guard.mjs)

To prevent the codebase from deteriorating into “spaghetti CSS”, ClinicFlow uses a custom Node.js script located at frontend/scripts/design-guard.mjs.

This script runs on CI and locally via npm run design:guard. It strictly bans:

1. Hardcoded Hex Colors: Prevents developers from writing an accent, emerald or gold hex directly. You must use the canonical OKLCH custom properties through their Tailwind tokens (e.g. text-accent, bg-muted). The palette is Tyrian Violet & Ivory; System Blue (#007AFF) is retired.
2. Legacy Typography: Throws an error if a retired font — Satoshi, Bricolage Grotesque, DM Sans — is reintroduced. UI and body text use the Apple native stack; Fraunces is sanctioned on the landing page’s display type only, and the guard enforces that scope too.
3. Thick Borders: Bans the use of border-2, border-3, or border-4 to preserve the 1px razor-thin border aesthetic of the “Liquid Glass” standard.

Exceptions are heavily vetted and explicitly whitelisted inside the script (e.g., SeasonalMatchMoment.tsx for dynamic particle colors).