Skip to content

Metricis Portal UI Design System

Status: Implemented Last Updated: 2026-01-21

Overview

This directory contains the UI design system reference for the Metricis Portal. The portal is built with React 18, Tailwind CSS v4, and shadcn/ui component patterns.

Implementation Status: The portal UI is fully implemented with 34+ pages and a comprehensive component library. See portal/src/ for the actual implementation.

Implemented Components

The portal includes the following component categories (see portal/src/components/):

Layout Components (/components/layout/)

  • AppShell - Main application shell wrapper
  • Sidebar - Dark-themed sidebar with grouped sections
  • Header - Top navigation with StudySelector and UserMenu
  • IconRail - Icon-only navigation rail (mobile-friendly)
  • ListPane / DetailPane - Master-detail layout pattern
  • MobileDrawer - Mobile navigation drawer

UI Components (/components/ui/)

  • Button - Reusable button component
  • Modal / ConfirmDialog - Dialog windows
  • PageHeader - Page title with breadcrumbs and actions
  • StatusBadge / StatusPill - Status indicators
  • StatCard - Metric display with trend indicators
  • SearchInput - Search with filtering
  • EmptyState - Empty state placeholder
  • Skeleton - Loading skeleton placeholders

Form Components (/components/forms/)

  • SurveyCreator - Full SurveyJS Creator wrapper
  • SurveyRunner - SurveyJS form runtime/player
  • TextInput, NumberInput, DateInput, Textarea, Select
  • CheckboxGroup, RadioGroup
  • FieldRow, FormSection, ConditionalBlock
  • SignatureCaptureModal - Modal for capturing signatures
  • SignaturePad - Canvas-based signature drawing

Design Principles

  1. Calm, clinical, high-trust aesthetic - Lots of whitespace, soft borders, restrained color
  2. Clear information hierarchy - Navigation → List → Detail
  3. Fast scanning - Strong typographic scale, consistent spacing, subtle separators
  4. Accessibility-first - WCAG AA compliant, keyboard navigable, clear focus states

Color Palette (Key Colors)

/* Primary */
--color-primary: #2563eb       /* Blue 600 - actions, links */
--color-primary-light: #dbeafe /* Blue 100 - selected backgrounds */

/* Text */
--color-text-primary: #0f172a  /* Slate 900 - headings */
--color-text-secondary: #475569 /* Slate 600 - body */
--color-text-muted: #94a3b8    /* Slate 400 - metadata */

/* Status */
--color-success: #22c55e       /* Green 500 */
--color-warning: #f59e0b       /* Amber 500 */
--color-danger: #ef4444        /* Red 500 */

/* Surfaces */
--color-bg-page: #f8fafc       /* Slate 50 - page background */
--color-bg-surface: #ffffff    /* White - cards */
--color-border: #e2e8f0        /* Slate 200 - borders */

/* Sidebar (dark theme) */
--sidebar-bg: #1e293b
--sidebar-text: #94a3b8
--sidebar-text-active: #ffffff

Typography Scale

Use Size Tailwind
Page titles 30px text-3xl font-semibold
Section headers 18px text-lg font-semibold
Body text 14-16px text-sm / text-base
Metadata 12px text-xs text-text-muted

Layout Pattern

3-Column Desktop (≥1024px)

┌──────────────┬──────────────┬────────────────────────┐
│   Sidebar    │  List Pane   │     Detail Pane        │
│   (260px)    │   (320px)    │      (flex-1)          │
│              │              │                        │
│ [Navigation] │ [Search]     │ [Header + Actions]     │
│              │ [List Items] │ [Content max-w-3xl]    │
│ [User Menu]  │              │                        │
└──────────────┴──────────────┴────────────────────────┘

Responsive Behavior

Breakpoint Sidebar List Pane Detail Pane
< 768px Hidden (drawer) Full screen Full screen (navigated)
768-1024px 64px icon rail Collapsible Remaining width
≥ 1024px 260px full 320px flex-1

Status Component Reference

// StatusPill supports these statuses:
<StatusPill status="draft" />       // Gray - bg-slate-100
<StatusPill status="published" />   // Green - bg-green-50
<StatusPill status="active" />      // Green - bg-green-50
<StatusPill status="completed" />   // Green - bg-green-50
<StatusPill status="locked" />      // Amber - bg-amber-50
<StatusPill status="pending" />     // Yellow - bg-yellow-50
<StatusPill status="overdue" />     // Red - bg-red-50
<StatusPill status="archived" />    // Gray outline

Technology Stack

  • React 18 with React Query (TanStack Query)
  • Tailwind CSS v4 with custom theme variables
  • SurveyJS for form building and rendering
  • Recharts for data visualization
  • Lucide React for icons
  • Zod for form validation

Archived Design Specifications

The original detailed UI specifications that informed the implementation have been archived to docs/archive/completed-plans/ui/:

  • forms-module-ui-spec.md - Original Forms module UI specification
  • forms-module-implementation-plan.md - Migration strategy and component inventory
  • forms-module-components.tsx - Reference component implementations

These documents are retained for historical reference but the actual implementation in portal/src/ is authoritative.