Skip to content

DESIGN.md

Latest commit

 

History

History
907 lines (629 loc) · 18.8 KB

DESIGN.md

File metadata and controls

907 lines (629 loc) · 18.8 KB
Raw

EditR Frontend Design System

A calm scientific workspace for repeatable base editing analysis.

EditR is not a marketing website. It is a functional research tool for uploading sequencing files, configuring base editing parameters, reviewing analysis results, and managing saved runs. The interface should feel professional, quiet, data-dense, and trustworthy.

The primary design goal is not visual impact. The goal is to help researchers complete repeated analysis tasks without confusion, fatigue, or accidental destructive actions.

Product Positioning

EditR should feel like:

  • a bioinformatics analysis console
  • a scientific data workspace
  • a lightweight LIMS-style tool
  • a repeatable analysis and record management system

EditR should not feel like:

  • a SaaS landing page
  • a product marketing website
  • a decorative dashboard mockup
  • a consumer app with oversized empty space

Useful references:

  • DNAnexus
  • Benchling
  • Galaxy Project
  • Terra.bio
  • Ant Design Pro
  • Carbon Design System data tables
  • GitHub, Linear, Vercel dashboard surfaces

Core Principles

1. Workflow Before Decoration

Every page should make the next action obvious. Visual styling exists to clarify hierarchy, not to impress.

Preferred workflow:

Upload files -> Configure sequence -> Set edit parameters -> Review -> Run analysis -> Inspect results -> Save / compare / export

2. Runs Are First-Class Objects

A single analysis should be treated as a Run.

Run = files + sequence template + edit parameters + results + notes + export history

This model should inform the UI. Results and records should not feel like isolated pages; they are views into saved runs.

3. Data Density With Breathing Room

EditR should support dense information, especially in file lists, sample tables, and records. Avoid oversized cards, giant hero text, and excessive section gaps.

4. Few Colors, Clear Meaning

Use color functionally:

  • Blue: primary action, active state
  • Green: success, recommended edit outcome
  • Amber: warning or partial issue
  • Red: danger or destructive action
  • Gray: neutral state, inactive state, secondary information

Do not assign a different color to every action.

5. Safe Operations

Destructive or irreversible actions should be visually quiet until needed, then confirmed explicitly.

Examples:

  • Delete actions live in overflow menus or danger zones
  • Clear all requires confirmation when files or records exist
  • Batch actions only appear after rows are selected

Information Architecture

Recommended top-level structure:

EditR
├─ Analyze
│  ├─ Single Sequence
│  └─ Batch Analysis
├─ Results
│  ├─ Overview
│  ├─ Samples
│  ├─ Editing Window
│  ├─ Files
│  └─ Settings
├─ Records
│  ├─ Runs
│  ├─ Groups
│  └─ Comparisons
└─ Templates
   ├─ Sequence Templates
   └─ Naming Rules

For the current product scope, the visible navigation can remain simple:

Analyze | Records

Results can be reached after running or opening a saved run.

Global Layout

Use a stable workspace layout.

┌──────────────────────────────────────────────┐
│ Top bar: EditR / Analyze / Records / Help     │
├──────────────────────────────────────────────┤
│                                              │
│        Main workspace, max-width 1280px       │
│                                              │
└──────────────────────────────────────────────┘

Avoid floating pill navigation. It is better suited to marketing pages than research software.

Page Width

  • Main content max-width: 1280px
  • Wide result/table views may use 1440px
  • Page horizontal padding: 24px desktop, 16px tablet/mobile

Page Rhythm

  • Page top padding below nav: 24px
  • Section gap: 24px
  • Card gap: 16px
  • Form field gap: 12px

Avoid 80px marketing-style vertical gaps.

Design Tokens

Colors

:root {
  --bg-page: #f6f8fb;
  --bg-surface: #ffffff;
  --bg-subtle: #f8fafc;
  --bg-muted: #f1f5f9;

  --text-primary: #111827;
  --text-secondary: #475569;
  --text-muted: #94a3b8;
  --text-inverse: #ffffff;

  --border-subtle: #e5e7eb;
  --border-strong: #cbd5e1;

  --primary: #2563eb;
  --primary-hover: #1d4ed8;
  --primary-soft: #eff6ff;

  --success: #16a34a;
  --success-soft: #ecfdf5;

  --warning: #d97706;
  --warning-soft: #fffbeb;

  --danger: #dc2626;
  --danger-hover: #b91c1c;
  --danger-soft: #fef2f2;

  --info: #0891b2;
  --info-soft: #ecfeff;
}

Typography

Use Inter or the system UI font stack.

:root {
  --font-sans: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;

  --text-page-title: 24px;
  --text-section-title: 16px;
  --text-card-title: 15px;
  --text-body: 14px;
  --text-table: 13px;
  --text-caption: 12px;

  --line-tight: 1.2;
  --line-normal: 1.45;
}

Use weights:

  • Page title: 600
  • Section title: 600
  • Field label: 500
  • Button label: 500 or 600
  • Body/table text: 400

Do not use large display headings such as 40px or 66px in the product workspace.

Spacing

Base unit: 4px

:root {
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 20px;
  --space-6: 24px;
  --space-8: 32px;
  --space-10: 40px;
}

Radius

:root {
  --radius-sm: 4px;
  --radius-md: 6px;
  --radius-lg: 8px;
  --radius-xl: 12px;
  --radius-full: 999px;
}

Recommended usage:

  • Cards: 8px
  • Inputs: 8px
  • Buttons: 6px or 8px
  • Tags: 999px
  • Menus/popovers: 8px

Avoid using pill buttons everywhere. Pills are useful for tags, segmented controls, and compact status indicators, not all actions.

Borders And Shadows

Use borders as the primary separation mechanism.

.surface {
  background: var(--bg-surface);
  border: 1px solid var(--border-subtle);
  border-radius: var(--radius-lg);
}

.surface-elevated {
  background: var(--bg-surface);
  border: 1px solid var(--border-subtle);
  border-radius: var(--radius-lg);
  box-shadow: 0 1px 2px rgba(15, 23, 42, 0.04);
}

Avoid heavy drop shadows and black borders.

Components

Top Bar

Role: global navigation and product identity.

Recommended layout:

EditR    Analyze    Records                         Help / v2.0.0

Rules:

  • Height: 56px to 64px
  • Background: white
  • Bottom border: 1px solid #e5e7eb
  • Active nav item: blue text or subtle blue background
  • Avoid floating nav capsules

Page Header

Role: identify current page and primary page actions.

Example:

Batch Analysis
Upload Sanger sequencing files and configure base editing parameters.

[Single Sequence] [Batch Analysis selected]                    [Open Records]

Rules:

  • Keep title compact
  • Subtitle is optional
  • Put page-level actions on the right
  • Avoid large hero-style headings

Buttons

Use five button types only.

Primary Button

Use for the most important page action.

Examples:

  • Start analysis
  • Save record
  • Open result

Style:

background: var(--primary);
color: white;
border: 1px solid var(--primary);
border-radius: 8px;
height: 40px;
padding: 0 16px;

Secondary Button

Use for normal actions.

Examples:

  • Export
  • Cancel
  • Save as template

Style:

background: white;
color: var(--text-primary);
border: 1px solid var(--border-strong);
border-radius: 8px;

Ghost Button

Use for low-emphasis actions in toolbars.

Danger Button

Use only for destructive actions.

Examples:

  • Delete
  • Clear all

Danger actions should usually be secondary or menu actions until confirmation is required.

Icon Button

Use in tables, compact toolbars, and overflow menus.

Examples:

  • More
  • Remove file
  • Refresh
  • Download

Forms

Rules:

  • Labels above fields
  • Helper text below fields
  • Validation message below helper text
  • Field height: 40px
  • Textarea min-height: 96px
  • Field radius: 8px
  • Field border: #cbd5e1
  • Focus ring: soft blue

Segmented Controls

Use for mode switching.

Examples:

  • Single sequence / Batch analysis
  • A / C / G / T base selection
  • Overview / Samples / Settings when tabs are too heavy

Selected state:

  • Blue background for active mode
  • White or subtle gray background for inactive modes

Base Selector

Role: choose original base and edited base.

Example:

Original base
[A] [C selected] [G] [T]

Edited base
[A] [C disabled] [G] [T selected]

Rules:

  • Original selected base: blue
  • Edited selected base: green
  • Invalid same-base option: disabled gray
  • Recommendation message uses --primary-soft

Cards

Cards should frame related controls or results, not every tiny element.

Rules:

  • Radius: 8px
  • Border: subtle gray
  • Padding: 20px or 24px
  • No heavy shadow
  • Do not nest cards inside cards unless necessary for repeated items

KPI Cards

Use at the top of result pages.

Recommended metrics:

  • Files
  • Successful samples
  • Average edit efficiency
  • Main conversion
  • Warnings

Example:

┌────────────┬────────────┬────────────┬────────────┐
│ Files      │ Success    │ Avg edit % │ Conversion │
│ 11         │ 10         │ 42.3%      │ C -> T     │
└────────────┴────────────┴────────────┴────────────┘

Data Tables

Tables are central to EditR.

Recommended table tokens:

:root {
  --table-header-height: 44px;
  --table-row-height: 52px;
  --table-font-size: 13px;
}

Rules:

  • Header background: #f8fafc
  • Row hover: #f8fafc
  • Selected row: #eff6ff
  • Use checkboxes for selection
  • Use one primary row action at most
  • Put secondary actions in an overflow menu
  • Put batch actions in a toolbar that appears after selection

Do not place 8 colored action buttons in every row.

Status Tags

Use tags for state, not actions.

Examples:

  • Success
  • Warning
  • Failed
  • Stored
  • Hidden
  • Synced

Style:

Success: green text on green soft background
Warning: amber text on amber soft background
Failed: red text on red soft background
Stored: slate text on gray background
Synced: cyan text on cyan soft background

Overflow Menu

Use for row-level secondary operations.

Recommended record row menu:

Download
Load for re-analysis
Push to Daily Work
Push formatted
Sync Grist
Edit
Group
Hide
Delete

Rules:

  • Delete is last
  • Delete is red
  • Menu width should fit labels without wrapping

Drawer / Detail Panel

Use right-side drawers for record details, run settings, and sample details.

Recommended width:

  • Desktop: 360px to 420px
  • Large desktop: up to 480px

Use a drawer when the user should keep table context while inspecting details.

Modal

Use modals for:

  • Confirm delete
  • Save template
  • Edit record metadata
  • Group records

Do not use modals for long multi-step analysis setup.

Empty States

Empty states should explain the next action briefly.

Example:

No files selected
Upload .ab1 files or a .zip archive to start a batch analysis.

[Browse files]

Avoid decorative illustrations unless they are simple and consistent with the product.

Page Designs

Analyze Page

The Analyze page should be a step-based workflow with a sticky run summary.

Recommended structure:

Batch Analysis

[1 Files] -> [2 Sequence Template] -> [3 Edit Parameters] -> [4 Review]

┌────────────────────────────────────────────┬────────────────────┐
│ Current step content                       │ Run Summary         │
│                                            │ Files: 11           │
│                                            │ Template: RD-103    │
│                                            │ Edit: C -> T        │
│                                            │ Target: 8           │
│                                            │                    │
│                                            │ [Start analysis]    │
└────────────────────────────────────────────┴────────────────────┘

Step 1: Files

Primary content:

  • Compact upload dropzone
  • Selected file count
  • Searchable file list
  • Clear all action
  • Invalid file warnings

Example:

[Drop .ab1 or .zip files here] [Browse files]

Selected files 11                                      [Clear all]
┌──────────────────────────────────────────────┐
│ File name                          Size   x   │
│ F-96-1.GALT...ab1                  213KB  x   │
│ F-96-2.GALT...ab1                  211KB  x   │
└──────────────────────────────────────────────┘

Step 2: Sequence Template

Fields:

  • Template selector
  • Template label
  • Reference sequence
  • Target position

Actions:

  • Save as template
  • More menu for delete or duplicate

Step 3: Edit Parameters

Fields:

  • Original base
  • Edited base
  • Edit window if available
  • Quality threshold if available

Recommendation panel:

Recommended: C -> T, common cytosine base editing

Step 4: Review

Show a compact confirmation summary before running.

Fields:

  • Files
  • Template
  • Reference sequence
  • Conversion
  • Target position
  • Naming rule

Primary action:

  • Start analysis

Results Page

The Results page should answer two questions first:

  1. Did the analysis succeed?
  2. What is the editing outcome?

Recommended structure:

Run: RD-103-msg-GA-3 / multi_2026-06-26
[Back] [Export] [Save record] [Compare]

KPI row

[Overview] [Samples] [Editing Window] [Files] [Settings]

Selected tab content

Overview Tab

Content:

  • KPI cards
  • Editing efficiency chart
  • Base composition chart
  • Warning summary

Samples Tab

Use a data table.

Recommended columns:

  • Selection checkbox
  • Sample
  • Status
  • Edit efficiency
  • Reads
  • Main edit
  • Notes
  • Action

Row actions:

  • View
  • More menu

Editing Window Tab

Content:

  • Sequence context
  • Highlighted target position
  • Base distribution
  • Per-position editing rate

Rules:

  • Use color to highlight biology-relevant states only
  • Avoid decorative chart colors

Files Tab

Content:

  • Source files
  • File status
  • Size
  • Parse result
  • Error messages

Settings Tab

Content:

  • Sequence template
  • Reference sequence
  • Target base
  • Edited base
  • Target position
  • Naming rule
  • Created time
  • Software version

This tab supports reproducibility.

Records Page

The Records page should be a record management workspace, not a wall of buttons.

Recommended structure:

Records

[Search records...] [Group: All] [Date] [Status]          [New analysis]

Bulk action bar appears after selection:
[Compare] [Export] [Group] [Hide] [Delete]

┌────┬──────────────┬────────────┬──────────┬───────┬────────────┬────────┐
│ □  │ Name         │ Batch      │ Saved at │ Files │ Note       │        │
├────┼──────────────┼────────────┼──────────┼───────┼────────────┼────────┤
│ □  │ Test run     │ multi_...  │ 06-26    │ 10    │ Test...    │ Open ⋯ │
└────┴──────────────┴────────────┴──────────┴───────┴────────────┴────────┘

Recommended columns:

  • Checkbox
  • Name
  • Project / Daily Work project
  • Batch
  • Saved time
  • File count
  • Note
  • Status
  • Action

Rules:

  • Row action: Open
  • Secondary actions: More menu
  • Batch actions appear after selection
  • Use right-side detail panel for selected record

Record Detail Panel

Example:

Test batch comparison 1
Saved 2026-06-26 17:16

Files: 10
Template: RD-103-msg-GA-3
Conversion: C -> T
Target position: 8

[Open result]
[Load for re-analysis]

Notes
Test multi-sequence comparison...

Interaction Rules

Primary Action Placement

  • Analyze page: Start analysis in sticky summary and final review step
  • Results page: Save record / Export in page header
  • Records page: New analysis in page header, Open in row

Batch Actions

Batch actions should appear only after row selection.

Example:

3 selected     [Compare] [Export] [Group] [Hide] [Delete]

Confirmation

Require confirmation for:

  • Clear all selected files
  • Delete record
  • Delete template
  • Hide many records

Error Handling

Errors should be local and actionable.

Examples:

  • Invalid file type: show in file row
  • Missing reference sequence: show below field
  • Analysis failure: show summary banner plus detailed log area

Visual Cleanup For Current Pages

Immediate improvements:

  • Replace black borders with #e5e7eb
  • Reduce card shadow and border weight
  • Use one blue primary button per page
  • Convert many colored row buttons into one Open button plus ...
  • Move destructive actions into menus or confirmation modals
  • Add table header backgrounds
  • Add row hover and selected states
  • Replace giant upload area with compact upload area after files are selected
  • Add KPI summary to results pages

Implementation Checklist

Phase 1: Visual Foundation

  • Add color tokens
  • Add typography tokens
  • Normalize buttons
  • Normalize card, input, table, tag styles
  • Remove heavy black borders
  • Reduce multicolor button usage

Phase 2: Workflow Improvements

  • Convert analysis page to step-based layout
  • Add sticky Run Summary
  • Add review step before analysis
  • Add result KPI row
  • Add result tabs

Phase 3: Records Improvements

  • Redesign records table
  • Add search and filters
  • Add batch action bar
  • Add row overflow menu
  • Add record detail drawer

Phase 4: Productization

  • Treat every analysis as a Run
  • Add run settings view
  • Add template management
  • Add comparison workflow
  • Add export history
  • Add reproducibility metadata

Design Mantra

EditR is a calm scientific workspace for repeatable base editing analysis. It prioritizes clear workflows, trustworthy results, compact data tables, and safe batch operations over decorative visual impact.