Skip to content

design_guidelines.md

Latest commit

 

History

History
104 lines (86 loc) · 3.69 KB

design_guidelines.md

File metadata and controls

104 lines (86 loc) · 3.69 KB
Raw

SWMM Engine Design Guidelines

Design Approach

Selected System: Material Design with technical application adaptations Rationale: Engineering tool requiring information density, clear visual hierarchy, and stable UI patterns for professional workflows.

Core Design Principles

  1. Clarity Over Aesthetics: Function-first interface prioritizing readability and precision
  2. Information Density: Efficient use of screen space for technical data
  3. Workflow Efficiency: Minimize clicks, maximize visibility of critical controls
  4. Professional Restraint: Clean, technical aesthetic avoiding decorative elements

Typography System

  • Primary Font: Inter (via Google Fonts CDN)
  • Monospace: JetBrains Mono (for technical values, coordinates, IDs)
  • Hierarchy:
    • Headers: text-lg to text-2xl, font-semibold
    • Body: text-sm to text-base, font-normal
    • Labels: text-xs, font-medium, uppercase tracking-wide
    • Technical data: text-sm, font-mono

Layout & Spacing

Spacing Units: Tailwind units 1, 2, 4, 6, 8 for consistent rhythm

  • Panel padding: p-4 to p-6
  • Element spacing: gap-4, space-y-2
  • Tight spacing for dense data: space-y-1, gap-2

Layout Structure:

  • Top toolbar: Fixed height (h-14), full-width navigation/actions
  • Left sidebar: w-64 to w-80, collapsible panel for project tree/properties
  • Main canvas: Flex-grow area for network diagram editor
  • Right panel: w-80, contextual properties and settings (toggle-able)
  • Bottom panel: h-48, resizable for logs/output (toggle-able)

Component Library

Navigation/Toolbar:

  • Icon-based actions with tooltips (Heroicons via CDN)
  • Grouped button sets with dividers
  • File menu, edit tools, view controls, run simulation

Diagram Canvas:

  • Grid background (subtle, light lines)
  • Zoomable/pannable viewport
  • Node shapes: circles (junctions), squares (outfalls), rounded rectangles (storage)
  • Connection lines with directional arrows
  • Selection indicators with handles

Panels:

  • Tree views for project hierarchy (collapsible nodes)
  • Property grids: label-value pairs in two-column layout
  • Tabbed sections for organized information
  • Bordered containers with subtle shadows (shadow-sm)

Forms & Inputs:

  • Compact form controls with labels above
  • Numeric inputs with unit indicators
  • Dropdown selectors for enumerated values
  • Validation feedback inline

Data Tables:

  • Dense tables with alternating row backgrounds
  • Sortable headers with icons
  • Fixed header scrolling for long data
  • Monospace for numeric columns

Modals/Dialogs:

  • Centered overlays with backdrop blur
  • Clear header with title and close button
  • Content area with proper scrolling
  • Action buttons aligned right

Visual Treatment

  • Minimal shadows (shadow-sm for elevation, shadow-md for modals)
  • Subtle borders (border-gray-300) for panel separation
  • No gradients or decorative elements
  • Focus on functional clarity

Icons

Library: Heroicons (outline style via CDN) Usage: Toolbar actions, tree view indicators, status icons, property labels

Images

No hero images - This is a technical application, not a marketing site Diagrams only: User-generated network diagrams on canvas

Responsive Behavior

  • Desktop-first: Minimum 1280px wide for optimal experience
  • Tablet: Collapsible sidebars, simplified toolbar
  • Mobile: Not primary target; basic viewing/editing only

Animation

Minimal and purposeful:

  • Panel slide transitions (150ms ease)
  • Hover state changes (immediate)
  • Loading spinners only
  • No decorative animations

Accessibility

  • High contrast text ratios
  • Keyboard navigation for all actions
  • Focus indicators on interactive elements
  • ARIA labels for icon buttons
  • Resizable panels for user preference