ClinicFlow Design System — Apple-Tier

ClinicFlow Design System — Apple-Tier

Philosophy

Apple’s design language applied to SaaS: stark monochromes, vibrant digital accents (System Blue), hyper-legible neo-grotesque fonts (Satoshi). 1px razor-thin borders. Ambient glows instead of drop shadows. Liquid Glass panels with backdrop-blur. Spring physics on every animation. Every page cohesive — same tokens, same patterns, same feel.

Typography

• Font: Satoshi, self-hosted as a variable font (wght axis 300-900 — not Fontshare’s CDN, not Google Fonts)
• Body: font-sans (Satoshi, system-ui, sans-serif) — applied globally via body
• Headings: (Satoshi, system-ui)
• Monospace: ‘SF Mono’, ‘Fira Code’, monospace — sanctioned exception for code/IDs/data, not a Satoshi violation
• Source: frontend/public/fonts/Satoshi-Variable.woff2 + Satoshi-VariableItalic.woff2, @font-face in frontend/src/index.css
• Anti-patterns: No serif (Cormorant), no Bricolage Grotesque, no DM Sans, no Georgia

Color System — 15 Canonical Tokens

Token	Light	Dark	Tailwind Class
–background	#FAFAF9	#0A0A0A	bg-background
–foreground	#0C0A09	#FAFAF9	text-foreground
–primary	#1C1917	#FAFAF9	bg-primary
–primary-foreground	#FAFAF9	#1C1917	text-primary-foreground
–accent	#007AFF	#007AFF	bg-accent, text-accent
–accent-foreground	#FAFAF9	#0A0A0A	text-accent-foreground
–muted	#F5F5F4	#1C1917	bg-muted
–muted-foreground	#78716C	#A8A29E	text-muted-foreground
–card	#FFFFFF	#141414	bg-card
–card-foreground	#0C0A09	#FAFAF9	text-card-foreground
–border	rgba(0,0,0,0.08)	rgba(255,255,255,0.1)	border-border
–danger	#ef4444	#f87171	bg-danger, text-danger
–warning	#f59e0b	#fbbf24	bg-warning, text-warning
–success	#10b981	#34d399	bg-success, text-success
–info	#007AFF	#60A5FA	bg-info, text-info

Accent Variants

• –accent-soft: rgba(0,122,255,0.1) / rgba(0,122,255,0.15)
• –accent-dark: #0056CC / #60A5FA
• –accent-glow: rgba(0,122,255,0.3) / rgba(0,122,255,0.4)

Anti-patterns

• No gold (#CA8A04, #ffd700)
• No emerald (#34d399, #10b981 as accent — use only for success semantic)
• No brand green (#059669)
• No hardcoded hex in components — use Tailwind tokens

Spacing & Radius

Border Radius

• sm: 12px (rounded-sm) — minimum for any element
• md: 16px (rounded-md in config, but DONT use the Tailwind default rounded-md which is 6px)
• lg: 24px (rounded-lg in config)
• pill: 9999px (rounded-pill)
• Inputs: rounded-xl (12px)
• Cards: rounded-2xl (16px)
• Modals: rounded-2xl (16px)

Spacing

• 4px base unit (Tailwind scale: 1=4px, 2=8px, 3=12px, 4=16px, 5=20px, 6=24px, 8=32px)
• Section padding: p-6 to p-8
• Card padding: p-5 to p-6
• Input padding: px-11 py-3.5
• Gap between items: gap-2 to gap-4

Shadows — Ambient Glows Only

Token	Value	Tailwind
–shadow-card	0 2px 8px rgba(0,0,0,0.06)	shadow-card
–shadow-raised	0 8px 24px rgba(0,0,0,0.12)	shadow-raised
–shadow-cta	0 4px 14px rgba(0,122,255,0.3)	shadow-cta
–glow-sm	0 0 12px rgba(0,122,255,0.15)	shadow-glow-sm
–glow-md	0 0 24px rgba(0,122,255,0.2)	shadow-glow-md

Anti-patterns: No shadow-md, shadow-lg, shadow-xl, shadow-2xl (directional drop shadows). No shadow-inner.

Borders — 1px Razor-Thin

• Default: border border-border (1px, rgba(0,0,0,0.08) light / rgba(255,255,255,0.1) dark)
• Glass panels: border border-white/20 (light) / border-white/10 (dark)
• Anti-patterns: No border-2, border-3, border-4. No 2px+ anywhere.

Liquid Glass

.glass-panel {
  @apply bg-white/40 backdrop-blur-2xl border border-white/20 shadow-glass;
}

• Used on: dashboard cards, landing section cards, pricing cards, modals, FAQ accordions
• Morphing variant: .glass-panel-morph adds 600ms hover transitions with blue glow + 2px lift
• 48 instances across the codebase

Animations

Spring Physics

• ALL Framer Motion uses spring physics (type: ‘spring’). 69 uses. 0 cubic-bezier.
• Configs: micro-interactions (stiffness:400, damping:30), cards (300/28), modals (200/25), lists (350/28)

Stagger Entrances

• 23 staggerChildren across dashboard cards, table rows, landing sections
• staggerChildren: 0.04 (40ms between items), delayChildren: 0.1

Page Transitions

• page-enter class: animate-[fadeUp_0.5s_ease-out] on all 16 route-level pages

CTA Glow

• cta-glow class: 3s ease-in-out box-shadow pulse on 9 primary CTA buttons

ErnieMascot

• cf-ernie breathing/burst/converge/pulse animation system fully wired

State Changes

• 500ms fluid transitions on hover, focus, expand/collapse
• Spring-powered modals via AnimatePresence in Dialog component (cascades to 22+ modals)

Reduced Motion

• Global CSS guard: @media (prefers-reduced-motion: reduce) kills all animations
• 49 useReducedMotion hooks across pages and components

Interaction Patterns

Focus Rings

focus:outline-none focus:ring-4 focus:ring-accent/20 focus:border-accent

Applied to ALL interactive elements. Error state: focus:ring-red-500/20.

Buttons

• Primary CTA: bg-accent text-accent-foreground hover:opacity-90 transition-all hover:-translate-y-0.5 shadow-card hover:shadow-raised + cta-glow
• Secondary: btn-secondary class (bg-muted, hover accent border)
• Ghost: btn-ghost class (transparent, hover bg-muted)
• Danger: btn-danger class (bg-danger, white text)
• Loading: bg-muted-foreground cursor-not-allowed shadow-none

Inputs

w-full bg-card border border-border rounded-xl px-11 py-3.5 text-sm font-medium text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-4 focus:ring-accent/20 focus:border-accent transition-all shadow-card

Hover States

• transition-all duration-500 on all state changes
• hover:-translate-y-0.5 on cards
• hover:shadow-raised on elevated elements
• hover:bg-muted on list items

Component Patterns

Canonical className Strings

Input field (default):

w-full bg-card border border-border rounded-xl px-11 py-3.5 text-sm font-medium text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-4 focus:ring-accent/20 focus:border-accent transition-all shadow-card

Primary button:

bg-accent text-accent-foreground px-4 py-2 rounded-2xl font-medium hover:opacity-90 transition-all hover:-translate-y-0.5 shadow-card hover:shadow-raised

Card container (glass):

glass-panel rounded-2xl p-6

Label:

text-xs font-bold text-muted-foreground uppercase tracking-wider

Pre-Delivery Checklist

• No emojis as icons (use Phosphor SVG)
• cursor-pointer on all clickable elements
• Hover states with smooth transitions
• Light mode: text contrast 4.5:1 minimum
• focus:outline-none focus:ring-4 on ALL interactive elements
• prefers-reduced-motion respected
• Responsive: 375px, 768px, 1024px, 1440px
• No hardcoded hex colors
• No inline style={{}} for static values
• No serif fonts, gold, emerald, or drop shadows
• Spring physics on all Framer Motion
• page-enter on route component root
• glass-panel on card containers