MetaCogna RAG Design Review

This document provides a comprehensive design review of the MetaCogna RAG application, documenting design patterns, component usage, and design generalities.

Project Overview

MetaCogna RAG is a Retrieval-Augmented Generation system built on Cloudflare Workers with a React frontend. It provides document management, vector search, knowledge graph extraction, and RAG-powered chat capabilities.

Purpose

Document ingestion and storage (R2, D1, Vectorize)
Semantic search and retrieval
Knowledge graph visualization
RAG-powered question answering
Multi-agent simulation interface

Design Philosophy

MetaCogna RAG follows the Paper UI design system with a focus on:

Functional Clarity: Interface prioritizes functionality over decoration
Visible Construction: Technical details (IDs, status, metadata) are visible
Hard Edges: Minimal border radius, hard shadows for physical depth
High Contrast: Clear visual hierarchy with Ink/Paper polarity

Color System Implementation

Current Implementation

MetaCogna RAG uses Tailwind CDN with inline configuration:

colors: {
  paper: '#ffffff',
  ink: '#18181b',        // Zinc 950
  accent: '#10b981',     // Emerald 500
  'accent-hover': '#059669',  // Emerald 600
  'accent-light': '#d1fae5',  // Emerald 100
  surface: '#f4f4f5',    // Zinc 100
  warning: '#ef4444',    // Red 500
}

Issues

No Dark Mode: Dark mode is not implemented
Direct Color Values: Uses hex values instead of CSS custom properties
Inconsistent Usage: Some components may use direct Tailwind colors

Migration to CSS custom properties is recommended for future dark mode support.

Typography

Font Families

Serif (Playfair Display): Headings, card titles
Sans-Serif (Inter): Body text, button labels
Monospace (JetBrains Mono): Technical inputs, badges, metadata

Typography Patterns

Headings:

H1/H2: Serif font, bold, tight tracking
Card titles: Serif, bold, uppercase, tracking-wide

Body Text:

Default: Sans-serif, standard weight, generous line-height
Code/metadata: Monospace, uppercase often

Inputs:

Font: Monospace (correct per Paper UI)
Labels: Monospace, uppercase, bold, small size

Component Inventory

Core Components

PaperCard

Basic implementation without animations
Supports title and action props
Hard shadows and borders

PaperButton

Variants: primary, secondary, ghost, danger
Sizes: sm, md, lg
Active state with translate animation

PaperInput

Label and error support
Monospace font (correct)
Focus shadow instead of ring

PaperBadge

Colors: blue, green, red, ink
Monospace, uppercase
Size: 10px (too small - should be 12px)

MarkdownText

Custom component for rendering markdown
Handles bold, inline code, code blocks

Application Components

Layout: Navigation sidebar with view switching
GlobalAIModal: Quick AI assistant (Cmd/Ctrl+I)
SupervisorWidget: Real-time supervisor advice
ErrorBoundary: React error boundary
GlobalToast: Toast notifications
GraphAnalysis: Graph metrics and insights

Layout Patterns

View-Based Routing

The application uses enum-based view routing:

enum ViewState {
  LANDING = 'LANDING',
  UPLOAD = 'UPLOAD',
  QUESTION = 'QUESTION',
  GRAPH = 'GRAPH',
  PROMPT = 'PROMPT',
  SETTINGS = 'SETTINGS',
  // ...
}

Main Layout Structure

Sidebar Navigation: Fixed left sidebar with view links
Main Content Area: View-specific content
Global Components: Toast, modals, AI assistant overlay

View Patterns

Landing Page:

Hero section with system status
Quick action cards
Morning briefing (AI-generated summary)

Upload View:

Tabbed interface (Upload, Documents, Statistics)
Drag-and-drop file upload
Document list with metadata
Progress tracking

Question View:

Chat interface layout
Message history
Input area with send button
Streaming response display

Knowledge Graph View:

Full-screen graph canvas
Sidebar with controls and filters
Node/edge information panels

Icon + text labels
Active state indication
Grouped by functionality
User profile access at bottom

View Switching

Programmatic view switching via setView()
No URL-based routing (SPA with state management)
View state persists in component state

Form Patterns

Input Patterns

Label above input (monospace, uppercase)
Error messages below input
Hard shadows on focus
No ring/outline focus styles

Button Patterns

Primary actions: Primary button variant
Secondary actions: Secondary or ghost variant
Destructive actions: Danger variant
Form submission: Full-width primary buttons common

Form Layout

Vertical stacking (flex-col)
Generous spacing between fields
Grouped related fields visually
Submit buttons at bottom

Data Visualization Patterns

Knowledge Graph

D3.js force-directed graph
PaperCard containers for controls
Monospace labels for node IDs
Color-coded node types

Progress Indicators

Pipeline stages with color coding
Percentage display
Animated progress bars
Stage-specific icons

Statistics Display

Card-based metric displays
Large numbers with labels
Status badges
Trend indicators (if applicable)

Unique Design Features

Pipeline Visualization

Four-stage ingestion pipeline with:

Color-coded stages (Blue, Purple, Indigo, Emerald)
Percentage progress (0-29%, 30-59%, 60-89%, 90-100%)
Animated diagonal stripes during processing

Morning Briefing

AI-generated daily summary:

Zero-UI approach (text-only)
PaperCard container
Generated on-demand

Document Metadata Tooltips

Hover interactions reveal:

Full metadata (author, category, tags)
Technical details (ID, status, chunk count)
Visible construction principle

Component Usage Patterns

Card Usage

Primary container for all major sections
Titles for section headers
Action buttons in headerAction slot
Nested cards for grouped content

Button Usage

Primary: Main actions (Upload, Submit, Save)
Secondary: Alternative actions
Ghost: Tertiary actions, less emphasis
Danger: Delete, destructive actions

Badge Usage

Status indicators (processing, indexed, error)
System status (ONLINE, OFFLINE)
Document status
Small, monospace, uppercase

Consistency Assessment

Strengths

✅ Consistent use of Paper UI colors
✅ Hard shadows throughout
✅ Minimal border radius
✅ Monospace for technical content
✅ Clear visual hierarchy

Areas for Improvement

❌ No dark mode support
❌ Badge font size too small (10px → 12px)
❌ No animations on cards (could enhance UX)
❌ Input font should remain monospace (currently correct)
❌ Missing some extended components (TextArea, Select, Modal)

Recommendations

High Priority

Add Dark Mode Support
- Migrate to CSS custom properties
- Update Tailwind config
- Test all components in dark mode
Fix Badge Size
- Change from text-[10px] to text-xs (12px)
- Improve readability
Add Missing Components
- PaperTextArea for multi-line inputs
- PaperSelect for dropdowns
- PaperModal for dialogs

Medium Priority

Add Animations
- Card fade-in animations
- Smooth transitions
- Enhanced interactivity
Standardize Component Props
- Align with baseline components
- Add missing props (noPadding, etc.)

Low Priority

Enhanced Visual Feedback
- Loading states
- Success animations
- Error states with icons

Design Generalities Summary

Overall Approach: Functional, technical, visible construction Key Characteristics:

Technical aesthetic with visible metadata
Hard edges and shadows for depth
High contrast for clarity
Monospace for technical content
Card-based layout patterns

Strengths: Clean, functional, consistent with Paper UI principles Weaknesses: No dark mode, limited animations, small badge text

Design System - Paper UI principles
Application Review - Cross-application review
Baseline Components - Standardized components
Tailwind Configuration - Setup guide

​Project Overview

​Purpose

​Design Philosophy

​Color System Implementation

​Current Implementation

​Issues

​Typography

​Font Families

​Typography Patterns

​Component Inventory

​Core Components

​Application Components

​Layout Patterns

​View-Based Routing

​Main Layout Structure

​View Patterns

​Navigation Patterns

​Sidebar Navigation

​View Switching

​Form Patterns

​Input Patterns

​Button Patterns

​Form Layout

​Data Visualization Patterns

​Knowledge Graph

​Progress Indicators

​Statistics Display

​Unique Design Features

​Pipeline Visualization

​Morning Briefing

​Document Metadata Tooltips

​Component Usage Patterns

​Card Usage

​Button Usage

​Badge Usage

​Consistency Assessment

​Strengths

​Areas for Improvement

​Recommendations

​High Priority

​Medium Priority

​Low Priority

​Design Generalities Summary

​Related Documentation

Project Overview

Purpose

Design Philosophy

Color System Implementation

Current Implementation

Issues

Typography

Font Families

Typography Patterns

Component Inventory

Core Components

Application Components

Layout Patterns

View-Based Routing

Main Layout Structure

View Patterns

Navigation Patterns

Sidebar Navigation

View Switching

Form Patterns

Input Patterns

Button Patterns

Form Layout

Data Visualization Patterns

Knowledge Graph

Progress Indicators

Statistics Display

Unique Design Features

Pipeline Visualization

Morning Briefing

Document Metadata Tooltips

Component Usage Patterns

Card Usage

Button Usage

Badge Usage

Consistency Assessment

Strengths

Areas for Improvement

Recommendations

High Priority

Medium Priority

Low Priority

Design Generalities Summary

Related Documentation