Skip to content

new-spec.md

Latest commit

 

History

History
488 lines (403 loc) · 12.2 KB

new-spec.md

File metadata and controls

488 lines (403 loc) · 12.2 KB

ProofLab Frontend Specification

Overview

ProofLab is evolving from a pure benchmarking platform to a comprehensive ecosystem for ZK development. This specification outlines the key components and user experience flow for the redesigned frontend.

Core Navigation Structure

Header

  • Logo + Platform Name
  • Main Navigation:
    • Programs
    • ZK Spaces
    • Learn
  • Authentication Controls (right-aligned)

Key Pages & Components

1. Homepage

Hero Section

  • Headline: Clear value proposition focusing on ZK program development and deployment
  • Sub-headline: Emphasize the platform's role in helping developers choose and optimize ZK solutions
  • Call-to-action: "Explore Programs" or "Start Building"

Featured Sections

  • Top Programs (Most used/viewed ZK programs)
  • Featured Spaces (Highlighted implementations)
  • Getting Started Guide (Quick links to documentation)

2. Programs Page

Program Discovery Interface

  • Enhanced version of current benchmarking table
  • Filtering System:
    • Use Case Categories (e.g., "Computation", "Privacy", "Verification")
    • Performance Requirements
    • Language Support
    • Resource Constraints

Comparison View

  • Side-by-side detailed comparison
  • Performance visualization with interactive graphs
  • Resource usage breakdowns
  • Real-world benchmarks and example implementations

Program Detail View

  • Comprehensive performance metrics
  • Integration guides
  • Example implementations
  • Related Spaces using this program

3. ZK Spaces

Showcase Grid

  • Cards displaying interactive ZK applications
  • Filter by:
    • Use case
    • Underlying ZK program
    • Integration type
    • Resource requirements

Space Detail View

  • Live demo interface
  • Implementation details
  • Integration documentation
  • Performance characteristics
  • Deployment requirements

4. Learn Section

Getting Started

  • Interactive tutorials
  • Best practices guide
  • Common patterns and anti-patterns

Documentation

  • Technical documentation
  • API references
  • Integration guides
  • Performance optimization guides

Technical Requirements

Performance

  • Load time < 2s for main pages
  • Real-time filtering and sorting
  • Responsive design for all screen sizes

State Management

  • Persistent comparison selections
  • User preferences storage
  • Filter state maintenance

Data Visualization

  • Interactive performance graphs
  • Resource usage charts
  • Comparison visualizations

Search & Discovery

  • Full-text search across programs and spaces
  • Smart filtering system
  • Related content suggestions

User Experience Considerations

First-Time User Experience

  • Guided tour of key features
  • Context-sensitive help
  • Clear pathways to getting started

Power User Features

  • Keyboard shortcuts
  • Bulk comparison tools
  • Custom benchmark configurations

Progressive Disclosure

  • Basic metrics visible by default
  • Detailed technical information available on demand
  • Advanced features accessible but not overwhelming

Implementation Priorities

Phase 1

  1. Enhanced Programs/Benchmarking interface
  2. Basic ZK Spaces showcase
  3. Fundamental documentation structure

Phase 2

  1. Interactive demonstrations
  2. Advanced comparison tools
  3. Community features

Phase 3

  1. Custom benchmarking tools
  2. Advanced integration guides
  3. Performance optimization tools

Design Guidelines

Visual Hierarchy

  • Clear distinction between sections
  • Consistent use of space and typography
  • Visual cues for important actions

Color System

  • Primary: Current brand colors
  • Secondary: Performance indicator palette
  • Accent: Action and highlight colors

Typography

  • Clear hierarchy for technical information
  • Readable code displays
  • Consistent sizing system

Interaction Patterns

Navigation

  • Breadcrumb navigation for deep pages
  • Persistent comparison toolbar
  • Quick access to documentation

Filtering

  • Real-time updates
  • Save filter combinations
  • Share filtered views

Comparison

  • Side-by-side views
  • Highlight differences
  • Export comparison data

Accessibility Requirements

  • WCAG 2.1 AA compliance
  • Keyboard navigation support
  • Screen reader optimization
  • High contrast mode support

Analytics Implementation

Key Metrics to Track

  • Program popularity
  • Common comparison patterns
  • Feature usage patterns
  • User journey flows

User Behavior

  • Filter usage patterns
  • Common comparison scenarios
  • Documentation access patterns

Future Considerations

Extensibility

  • Plugin system for new metrics
  • Custom visualization support
  • API access for external tools

Community Features

  • User contributions
  • Discussion forums
  • Custom benchmark sharing

Design System

ProofLab Frontend Specification

Core Design System

Color System

Brand:
- Primary: #6366F1 (Indigo)
- Secondary: #3B82F6 (Blue)

Performance Indicators:
- High: #22C55E (Green)
- Medium: #FBBF24 (Yellow)
- Low: #DC2626 (Red)

Background:
- Page: #F9FAFB
- Card: #FFFFFF
- Hover: #F3F4F6

Text:
- Primary: #111827
- Secondary: #4B5563
- Muted: #9CA3AF

Typography

Font Stack:
- Interface: Inter
- Monospace: JetBrains Mono
- Fallbacks: system-ui

Scale:
- Display: 36/44px
- H1: 30/36px
- H2: 24/32px
- H3: 20/28px
- Body: 16/24px
- Small: 14/20px
- Mono: 14/20px

Layout Structure

Header

┌─────────────────────────────────────────────────┐
│ Logo   Programs  Spaces  Learn     Auth  Theme  │
└─────────────────────────────────────────────────┘

Programs List View

┌─────────────────────────────────────────────────┐
│ Filters & Search                                │
├─────────┬───────────────────────────────────────┤
│         │ ┌─────────────────────────────────┐   │
│ Filters │ │ Program Card                    │   │
│         │ └─────────────────────────────────┘   │
│         │ ┌─────────────────────────────────┐   │
│         │ │ Program Card                    │   │
│         │ └─────────────────────────────────┘   │
└─────────┴───────────────────────────────────────┘

Program Detail View

┌─────────────────────────────────────────────────┐
│ Program Header & Navigation                     │
├─────────────────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ │
│ │ TVS     │ │ Daily   │ │ 30D     │ │ Score  │ │
│ │ Stats   │ │ Stats   │ │ Stats   │ │ Card   │ │
│ └─────────┘ └─────────┘ └─────────┘ └────────┘ │
├─────────────────────────────────────────────────┤
│ Performance Graphs                              │
├─────────────────────────────────────────────────┤
│ Technical Details                               │
└─────────────────────────────────────────────────┘

Components

Program Card

┌──────────────────────────────────────┐
│ Logo  Name               Score Wheel │
│                                     │
│ Key Metrics                         │
│ ├─ Proving Time                     │
│ ├─ Memory Usage                     │
│ └─ Throughput                       │
│                                     │
│ Technical Badges                    │
└──────────────────────────────────────┘

Score Wheel

Component: RadialScore
- 5 segments for different metrics
- Color coded segments (red → yellow → green)
- Interactive tooltips on hover
- Animated transitions
- Central area for overall score

Performance Metrics

┌──────────────────────┐
│ Metric Name    Value │
│ └─ Trend       ↑↓ % │
│                     │
│ History Graph       │
│ └─ 7D/30D/90D      │
└──────────────────────┘

Comparison View

┌────────────┬────────────┬────────────┐
│ Program A  │ Program B  │ Program C  │
├────────────┼────────────┼────────────┤
│ Metrics    │ Metrics    │ Metrics    │
├────────────┼────────────┼────────────┤
│ Score      │ Score      │ Score      │
│ Wheel      │ Wheel      │ Wheel      │
└────────────┴────────────┴────────────┘

Interactive Elements

Score Tooltips

┌─────────────────────┐
│ Metric Name         │
│ Score: 4.5/5        │
│                     │
│ Details:            │
│ • Current value     │
│ • Scoring criteria  │
│ • Recent changes    │
└─────────────────────┘

Filter System

Categories:
- Programming Language
- Performance Range
- Memory Usage
- Feature Support
- Development Status

Display:
- Chips for active filters
- Dropdown menus
- Range sliders
- Search input

Data Tables

Features:
- Sortable columns
- Frozen first column
- Sticky header
- Pagination
- Row selection
- Expandable rows

Responsive Behavior

Mobile View (< 768px)

- Single column layout
- Collapsible filters
- Simplified metrics
- Stacked comparisons
- Touch-optimized controls

Tablet View (768px - 1024px)

- Two column layout
- Side panel filters
- Compact metrics
- 2-up comparisons

Desktop View (> 1024px)

- Multi-column layout
- Persistent filters
- Full metrics display
- 3-up comparisons

State Management

URL Parameters

Persisted State:
- Selected filters
- Sort order
- Comparison selections
- Time range
- View mode

Local Storage

Cached Data:
- Recent searches
- Preferred units
- Theme selection
- Hidden columns

Performance Optimizations

Data Loading

Strategy:
- Progressive loading
- Cached responses
- Debounced searches
- Optimistic updates

Rendering

Techniques:
- Virtualized lists
- Deferred loading
- Lazy components
- Skeleton screens

Accessibility

Keyboard Navigation

Shortcuts:
- J/K: Navigate items
- Enter: Open detail
- Esc: Close modal
- /: Focus search

Screen Readers

Features:
- ARIA labels
- Focus management
- State announcements
- Skip links

Animation Guidelines

Transitions

Duration:
- Fast: 150ms (hover)
- Medium: 250ms (expand)
- Slow: 350ms (page)

Timing:
- ease-out for enter
- ease-in for exit
- ease-in-out for movement

Loading States

Components:
- Skeleton screens
- Progress bars
- Fade transitions
- Shimmer effects