Skip to content

design_guidelines.md

Latest commit

 

History

History
127 lines (94 loc) · 4.8 KB

design_guidelines.md

File metadata and controls

127 lines (94 loc) · 4.8 KB

ICMRubyLens Design Guidelines

Design Approach

Selected Approach: Design System - Drawing from Linear's clean developer aesthetic and VS Code's interface patterns with a vibrant blue color theme

Justification: This is a utility-focused developer tool requiring efficiency, clarity, and information density. The interface must prioritize code readability, clear AI agent status, and seamless file management over visual flair. The blue theme provides a professional, tech-focused aesthetic that's easy on the eyes during extended coding sessions.

Color Palette

Blue Theme:

  • Primary Blue: Vibrant blue for interactive elements, primary actions, and focus states
  • Background: Light blue-tinted whites for light mode, deep blue-grays for dark mode
  • Surfaces: Subtle blue-tinted cards and panels
  • Text: High-contrast blue-blacks and blue-whites for optimal readability
  • Accents: Lighter blues for hover states and secondary elements

Typography

Font Stack:

  • Primary: Inter (via Google Fonts CDN) - for UI elements, labels, buttons
  • Code: JetBrains Mono (via Google Fonts CDN) - for all code displays
  • Weights: 400 (regular), 500 (medium), 600 (semibold)

Hierarchy:

  • Page Title: text-2xl font-semibold
  • Section Headers: text-lg font-medium
  • Body Text: text-sm font-normal
  • Code: text-sm (JetBrains Mono)
  • Labels/Meta: text-xs font-medium
  • Buttons: text-sm font-medium

Layout System

Spacing Primitives: Use Tailwind units of 2, 4, 6, 8 (e.g., p-4, gap-6, mb-8)

Grid Structure:

  • Main container: max-w-7xl mx-auto px-6
  • Two-column layout for code comparison: grid grid-cols-1 lg:grid-cols-2 gap-6
  • File upload area: Full-width at top
  • AI agents panel: Separate section with status indicators

Vertical Rhythm: Consistent py-6 for section spacing, py-4 for component internal padding

Core Components

File Upload Zone

  • Large dropzone area (min-h-48) with dashed border
  • Icon: Upload cloud (Heroicons - use throughout app)
  • Drag-and-drop support with visual state changes
  • File type badges showing .rb and .md acceptance
  • Recently uploaded files list below dropzone

Code Display Panels

Layout: Side-by-side panels (original left, AI-modified right)

  • Header: File name + download button (right-aligned)
  • Code container: Bordered panel with syntax highlighting (use Prism.js via CDN)
  • Max height with scroll: max-h-[600px] overflow-y-auto
  • Line numbers in gutter
  • Monospace font (JetBrains Mono)

AI Agent Status Panel

Position: Horizontal bar above code panels

  • Two agent cards side-by-side: DeepSeek | Claude
  • Each card shows: Agent name, current task, progress indicator
  • Status states: Idle (gray indicator), Processing (animated pulse), Complete (checkmark)
  • Compact height: py-4

Diff View Component

  • Split view showing original vs. suggested changes
  • Deletion highlights on left, addition highlights on right
  • Line-by-line comparison with connecting lines for context
  • Toggle button to switch between unified/split views

Action Buttons

  • Primary: Download modified files (prominent, top-right of each panel)
  • Secondary: Run code (if applicable), Clear/Reset
  • Icon + text labels
  • Consistent sizing: px-4 py-2

Mermaid Diagram Display

  • Dedicated panel below code sections
  • Rendered Mermaid diagrams with light background
  • Zoom controls for complex diagrams
  • Export diagram button

Component Library

Navigation: Minimal top bar with app logo/name, no heavy navigation needed

Forms: Simple input fields for AI agent parameters if needed (temperature, model selection)

Data Displays:

  • Code blocks with syntax highlighting
  • Markdown preview panels
  • Diff indicators (+ green additions, - red deletions)

Overlays: Toast notifications for upload success, AI processing complete, errors

Interaction Patterns

  • File upload: Click to browse OR drag-and-drop
  • Code panels: Click to focus, Cmd/Ctrl+A to select all
  • Download: Single-click download (no confirmation needed)
  • AI processing: Automatic trigger on file upload, manual re-run button available

Accessibility

  • All interactive elements keyboard navigable
  • Focus states visible on all inputs and buttons
  • ARIA labels for file upload zone, AI status indicators
  • Sufficient contrast for code syntax highlighting
  • Screen reader announcements for AI processing states

Animations

Minimal approach - Developer tools prioritize speed:

  • Upload progress: Simple linear progress bar (no fancy animations)
  • AI processing: Subtle pulse on active agent card
  • State transitions: 150ms ease for hover states only
  • NO page transitions, NO scroll animations

Images

No hero image - This is a functional web application, not a marketing page. Focus is entirely on the tool interface.

Icons Only: Use Heroicons library via CDN for all UI icons (upload, download, checkmark, code, etc.)