Skip to content

design_guidelines.md

Latest commit

 

History

History
192 lines (146 loc) · 5.7 KB

design_guidelines.md

File metadata and controls

192 lines (146 loc) · 5.7 KB
Raw

Design Guidelines: SWMM5 Import Documentation Portal

Design Approach

Reference-Based: Technical Documentation Pattern

  • Primary inspiration: GitHub Docs, Read the Docs, VS Code Documentation
  • Focus: Maximum readability, code clarity, efficient information architecture
  • Principle: Function over form, with clean professional aesthetic

Typography System

Font Families:

  • Headings: Inter or system-ui (weights: 600, 700)
  • Body: -apple-system, system-ui (weight: 400, 500)
  • Code: 'JetBrains Mono', 'Fira Code', monospace (weight: 400, 500)

Scale:

  • Page Title (h1): text-4xl font-bold
  • Section Headers (h2): text-2xl font-semibold
  • Subsections (h3): text-xl font-semibold
  • Body: text-base leading-relaxed
  • Code inline: text-sm
  • Captions/labels: text-sm text-gray-600

Layout System

Spacing Primitives: Use Tailwind units of 4, 6, 8, 12, 16 (p-4, gap-6, mb-8, py-12, mt-16)

Grid Structure:

  • Desktop: Sidebar (w-64) + Main content (flex-1 max-w-4xl)
  • Tablet: Collapsible sidebar + full-width content
  • Mobile: Stack vertically, hamburger navigation

Content Width:

  • Documentation text: max-w-3xl for optimal reading
  • Code blocks: max-w-full with horizontal scroll
  • Tables: max-w-4xl

Component Library

Navigation & Structure

Header Bar:

  • Sticky top navigation (h-16)
  • Logo/title on left
  • Search bar center (desktop)
  • Theme toggle, GitHub link on right

Sidebar Navigation:

  • Fixed position on desktop
  • Nested categories with expand/collapse
  • Active state: left border accent + background tint
  • Categories: Code Files, INP Format, ICM SWMM, ICM InfoWorks, Import Guide

Breadcrumbs:

  • Below header, shows current location in hierarchy
  • text-sm with arrow separators

Content Components

Code Viewer:

  • Dark theme code blocks with syntax highlighting
  • Line numbers in gutter (text-gray-500)
  • Tab interface for switching between UI/Exchange scripts
  • Copy button (top-right corner)
  • Filename label above block
  • Background: bg-gray-900 or similar dark shade

Tabs:

  • Horizontal tabs with underline active indicator
  • Tabs: "UI Script (788 lines)" | "Exchange Script (540 lines)"
  • Clean, minimal design

Collapsible Sections:

  • INP file format sections as accordion
  • Click to expand/collapse
  • Chevron icon rotates on state change
  • Organized by category (Hydrology, Hydraulics, Water Quality, etc.)

Comparison Table:

  • ICM InfoWorks vs ICM SWMM engine comparison
  • Sticky header row on scroll
  • Alternating row backgrounds
  • Responsive: stack on mobile

Info Cards:

  • Callout boxes for important notes
  • Border-left accent (blue for info, yellow for warning, green for tip)
  • Subtle background tint
  • Icon on left (info circle, warning triangle, lightbulb)

Search Interface:

  • Global search bar in header
  • Filter chips: "File Format" | "ICM SWMM" | "Import Process" | "All"
  • Results dropdown with highlighting

Data Display

Section Detail Cards:

  • For detailed INP section specifications
  • Header: Section name + description
  • Body: Fields table (Name | Type | Units | Description)
  • Footer: Code example in monospace

Statistics/Metrics:

  • Small stat cards showing: Total INP Sections (50+), Script Lines, Import Steps
  • Grid layout: 3-column on desktop, 1-column mobile

Code Annotations:

  • Inline comments in Ruby code highlighted
  • Hover tooltips for technical terms

Page Structure

Landing View:

  • Brief intro paragraph (2-3 lines)
  • Quick links to main sections in card grid (2x2)
  • "Getting Started" prominent CTA
  • No hero image - jump straight to content

Main Documentation Layout:

  • Left sidebar: persistent navigation
  • Center: documentation content with generous line-height
  • Right sidebar (desktop only): Table of contents for current page

Code View:

  • Full-width tabs at top
  • Code viewer occupies main content area
  • Sticky toolbar with copy, download, view raw buttons

Color Scheme

Primary Colors:

  • Blue: #2563eb (primary actions, links, headings)
  • Orange: #f97316 (accents, highlights, interactive states)

Application:

  • Primary buttons, active navigation: Blue
  • Hover states, CTAs, icons: Orange
  • Syntax highlighting: Blue for keywords, Orange for strings/numbers
  • Code viewer accents: Blue line numbers, Orange highlights

Visual Hierarchy

Section Separation:

  • Horizontal rules (border-gray-200) between major sections
  • Generous vertical spacing (py-12 to py-16)

Content Grouping:

  • Related items in subtle bordered containers
  • Gap-4 between list items
  • Gap-8 between major blocks

Focus States:

  • Clear focus rings on interactive elements (ring-2 ring-blue-500)
  • Code blocks with focus: subtle border highlight

Animations

Minimal & Purposeful:

  • Sidebar expand/collapse: 200ms ease
  • Accordion open/close: 150ms ease
  • Tab switching: fade transition 100ms
  • No scroll animations, parallax, or decorative motion

Images

No hero image. This is a technical documentation site prioritizing immediate content access.

Diagrams (if needed):

  • Flow diagrams for import process
  • Architecture diagrams for engine comparison
  • Use placeholder comments: <!-- DIAGRAM: SWMM5 to ICM import workflow -->

Accessibility

  • Skip to main content link
  • Semantic HTML5 sections
  • ARIA labels on icons
  • Keyboard navigation for all interactive elements
  • High contrast text (minimum 4.5:1 ratio)
  • Code blocks with screen reader-friendly alternatives

Responsive Breakpoints

  • Mobile: < 768px (stack, hamburger menu)
  • Tablet: 768px - 1024px (collapsible sidebar)
  • Desktop: > 1024px (persistent sidebar, TOC)

Design Philosophy: Clean, scannable, code-first documentation that gets users to the information they need with zero friction. Every element serves the goal of learning and reference.