rtu_v5/v2/guidelines/Guidelines.md

Data Station Dashboard Design Guidelines

Overview

This dashboard is designed for 7-inch capacitive touchscreen displays used in industrial/environmental monitoring stations. The interface prioritizes touch-friendly interactions, clear information hierarchy, and robust functionality for field use.

---

Design Language

Color Palette

Background Colors:

• Primary Background: bg-gray-900 - Main content areas
• Secondary Background: bg-gray-950 - Sidebar, header, elevated surfaces
• Tertiary Background: bg-gray-800 - Cards, input fields, nested elements

Accent Colors:

• Primary Action: bg-blue-600, hover:bg-blue-700 - Buttons, active states
• Success/Positive: text-green-400 - Online status, calibrated sensors, positive values
• Warning: text-yellow-400 - Pending states, warnings
• Error/Critical: text-red-400 - Offline status, errors, delete actions
• Info: text-blue-400 - Icons, informational highlights
• Data Values: text-cyan-400, text-purple-400 - Different data categories

Text Colors:

• Primary Text: text-white - Headings, labels
• Secondary Text: text-gray-300 - Body text, menu items
• Tertiary Text: text-gray-400 - Supporting information, metadata
• Disabled Text: text-gray-500 - Disabled states

Border Colors:

• Default Borders: border-gray-700 - Cards, inputs, dividers

Typography

Font Sizes:

• Page Headers: text-2xl (h1)
• Card Titles: text-sm to text-base
• Body Text: text-sm
• Metadata/Labels: text-xs
• Tiny Text: text-[10px] (for dense information)
• Monospace: Use font-mono for time, data values, file contents

Font Weights:

• Bold: font-bold - Page headers, important labels
• Semibold: font-semibold - Card titles, emphasized values
• Normal: Default weight for body text

Spacing

Component Spacing:

• Between major sections: space-y-4
• Within cards: space-y-3 or space-y-4
• Compact spacing: space-y-2
• Card padding: p-3 or p-4
• Grid gaps: gap-3 or gap-4

Touch Targets:

• Minimum button height: h-14 (56px) for primary touch actions
• Standard button size: size-lg
• Navigation buttons: h-14 w-14 (56x56px minimum)
• List items: p-2 to p-3 for adequate touch area

---

Navigation

Sidebar Navigation

Structure:

• Collapsible sidebar with icon-only mode
• Width: w-64 (expanded), w-16 (collapsed)
• Always visible on left side
• Dark background (bg-gray-950)

Menu Hierarchy:

• Primary menu items: Icon + Label
• Expandable items: Show chevron indicator
• Sub-menu items: Indented with pl-11
• Active state: bg-blue-600 text-white
• Hover state: hover:bg-gray-800 hover:text-white

Menu Items:

1. HOME - Rainfall dashboard (default view)
2. GRAPH - Data visualization
3. UTILITY - Expandable with 10 sub-items
4. CALIBRATION - Sensor calibration
5. FLASH MEMORY - File manager
6. SETTING - System settings
7. LOGIN - Authentication

Page Navigation

No Traditional Scrollbars:

• All scrollbars are hidden for touchscreen usability
• Use permanent Up/Down buttons in top-right corner
• Buttons: 56x56px, bg-blue-600, positioned fixed top-20 right-4
• Smooth scroll behavior with 300px increments

Routing:

• Use React Router for multi-page navigation
• Route structure: / (home), /graph, /utility/[setting], etc.
• URL updates on navigation for state management

---

UI Elements

Buttons

Primary Button:

• Style: bg-blue-600 hover:bg-blue-700 text-white
• Use for: Main actions, saving, applying settings
• Size: Default or size-lg for touch

Secondary Button (Outline):

• Style: variant="outline" border-gray-700 text-gray-300 hover:bg-gray-800
• Use for: Alternative actions, cancel, secondary functions

Destructive Button:

• Style: variant="outline" border-red-700 text-red-400 hover:bg-red-950
• Use for: Delete, reset, dangerous actions

Icon Buttons:

• Size: Minimum 44x44px for touch
• Include text labels when space allows
• Use Lucide React icons consistently

Cards

Standard Card:

<Card className="bg-gray-900 border-gray-700">
  <CardHeader>
    <CardTitle className="text-white">Title</CardTitle>
  </CardHeader>
  <CardContent>
    {/* Content */}
  </CardContent>
</Card>

Data Display Card:

• Use color-coded backgrounds for data categories
• Format: Value (large) + Unit (small)
• Example: text-4xl font-bold text-blue-400 for values

Form Elements

Input Fields:

• Style: bg-gray-800 border-gray-700 text-white
• Labels: text-gray-300 above inputs
• Grid layout for multiple fields: grid grid-cols-2 gap-4

Switches:

• Use for enable/disable settings
• Layout: Label on left, switch on right
• Container: flex items-center justify-between p-3 bg-gray-800 rounded

Dropdowns:

• Style: bg-gray-800 border border-gray-700 rounded text-white
• Use native <select> for simplicity on touchscreens

Status Indicators

Icon + Text Pattern:

• Wifi status: <Wifi className="w-3 h-3 text-green-500" /> + status text
• Battery: <Battery className="w-3 h-3 text-green-500" /> + voltage
• Solar: <Sun className="w-3 h-3 text-yellow-500" /> + voltage

Status Colors:

• Online/Active/Good: Green (text-green-400/500)
• Pending/Warning: Yellow (text-yellow-400/500)
• Offline/Error: Red (text-red-400/500)
• Neutral/Info: Blue (text-blue-400)

Dot Indicators:

• Use w-2 h-2 rounded-full for compact status
• Paired with text labels

---

Panels

Header Panel

Layout:

• Fixed height, spans full width
• Background: bg-gray-950 border-b border-gray-700
• Padding: px-4 py-2
• Flexbox: flex items-center gap-4

Content (Left to Right):

1. Logo (8x8 icon + optional text)
2. Spacer (flex-1)
3. Real-time clock (HH:MM:SS format, font-mono)
4. Date (YYYY-MM-DD format, font-mono)
5. Station ID
6. Communication Status (icon + text)
7. Version number
8. Login status (dot + text)
9. Solar voltage (icon + value)
10. Battery voltage (icon + value)

Responsive Behavior:

• Items wrap with flex-wrap on smaller displays
• Hide optional labels when space is tight
• Maintain minimum readability

Details Panel

Container:

• ID: details-panel (for scroll control)
• Style: h-full overflow-y-auto bg-gray-800 p-4 scroll-smooth
• No visible scrollbar (hidden via CSS)

Content Structure:

• Page header with icon + title at top
• Main content in cards
• Consistent space-y-4 between sections

Sidebar Panel

Structure:

• Fixed width, full height
• Collapsible toggle in header
• Scrollable menu area
• Z-index layering for overlays

---

Component Naming Conventions

Files and Folders

Views/Pages:

• Location: /src/app/components/views/
• Naming: [Feature]View.tsx (e.g., RainfallView.tsx, SettingView.tsx)
• Export: Named export matching filename

Layout Components:

• Location: /src/app/components/
• Naming: [Purpose].tsx (e.g., Header.tsx, Sidebar.tsx, DashboardLayout.tsx)

Routes:

• Location: /src/app/routes.ts
• Path naming: Lowercase with hyphens (e.g., /utility/station-info)

Variables and Constants

State Variables:

• camelCase: sidebarCollapsed, selectedFile, isOnline
• Boolean prefix: is, has, should

Constants:

• camelCase for objects/arrays: menuItems, mockFiles, rainfallData
• UPPERCASE for true constants: SCROLL_AMOUNT

Props:

• camelCase: collapsed, onToggle, selectedFile
• Event handlers: on[Action] prefix

---

Data Display Patterns

Rainfall Card View

Layout:

• Grid: grid grid-cols-2 gap-4
• Four cards: Today, Hourly, MAR Acc, Yearly Acc
• Each card: Label (top), Value (large center), Unit (small)

Color Coding:

• Today: Blue (text-blue-400, bg-blue-500/20)
• Hourly: Cyan (text-cyan-400, bg-cyan-500/20)
• MAR Acc: Green (text-green-400, bg-green-500/20)
• Yearly Acc: Purple (text-purple-400, bg-purple-500/20)

List Views

Recent Data:

• Container: space-y-2
• Item: flex justify-between items-center p-2 bg-gray-800 rounded
• Timestamp on left (text-gray-400)
• Value on right (text-blue-400 font-semibold)
• Hover: hover:bg-gray-750 transition-colors

File Manager (Flash Memory)

Two-Column Layout:

• Left: 30% width, file list
• Right: 70% width, file content
• Grid: grid grid-cols-[30%_70%] gap-4

File List:

• Clickable items with selection state
• Selected: bg-blue-600 text-white
• Unselected: bg-gray-800 text-gray-300
• File icon + name + metadata (size, date)

File Content:

• Monospace font for code/logs
• Action buttons in header (Download, Delete)
• Metadata footer

Settings Views

Form Pattern:

• Card-based groupings
• Switch + Label rows for toggles
• Input fields in grids for related values
• Action buttons at bottom (full width or flex)

---

Icon Usage

Icon Library:

• Use Lucide React exclusively
• Size: w-5 h-5 for menu items, w-6 h-6 for page headers
• Color: Match parent text color or use accent colors

Common Icons:

• Home: <Home />
• Graph: <BarChart3 />
• Settings: <Settings />
• Utility: <Wrench />
• Calibration: <Gauge />
• Flash Memory: <HardDrive />
• Login: <LogIn />
• Info: <Info />
• Time: <Clock />
• Network: <Network />
• Sensors: <Activity />, <CloudRain />, <Wind />
• Actions: <Download />, <Trash2 />, <Check />
• Navigation: <ChevronUp />, <ChevronDown />, <ChevronRight />

---

Touchscreen Interaction Guidelines

Touch Targets

• Minimum size: 44x44px (preferably 56x56px for critical actions)
• Adequate spacing between adjacent targets
• Visual feedback on touch (hover states still apply)

Gestures

• Primary interaction: Tap/Click
• Scrolling: Via Up/Down buttons (no swipe scrolling reliance)
• No hover-dependent functionality
• No right-click menus

Visual Feedback

• Active states: Background color change
• Loading states: Consider adding when needed
• Transitions: transition-colors for smooth state changes
• Button press: Visual depression or color shift

---

Responsive Behavior

Target Screen Size:

• Primary: 7-inch touchscreen (approximately 800x480 to 1024x600)
• Orientation: Landscape preferred

Adaptation Rules:

• Header items wrap when needed
• Grid layouts adjust column count
• Text truncates with ellipsis when necessary
• Navigation remains accessible (sidebar stays visible)

Text Wrapping:

• Truncate with truncate class where space is limited
• Allow wrap with flex-wrap for multi-item containers

---

Performance Considerations

Optimization:

• Mock data for demonstrations
• Real-time updates at reasonable intervals (1 second for clock)
• Smooth scroll animations (scroll-smooth)
• Efficient re-renders (use React best practices)

Data Updates:

• Clock: Update every 1000ms
• Sensor data: Typical intervals 5-60 seconds
• File lists: Update on demand

---

Accessibility Notes

While optimized for touchscreen:

• Maintain keyboard navigation where possible
• Use semantic HTML elements
• Provide descriptive labels
• Color is not the only indicator (use icons + text)
• Sufficient contrast ratios for readability

---

Technical Specifications

Framework:

• React 18.3.1
• React Router 7.13.0 (Data mode)
• Tailwind CSS 4.1.12

Component Library:

• Radix UI components (via shadcn/ui pattern)
• Lucide React for icons

Styling:

• Tailwind utility classes
• Minimal custom CSS (only for scrollbar hiding)
• Dark theme by default

File Structure:

/src/app/
+-- App.tsx              (Entry point with RouterProvider)
+-- routes.ts            (Route configuration)
+-- components/
¦   +-- DashboardLayout.tsx
¦   +-- Header.tsx
¦   +-- Sidebar.tsx
¦   +-- NavigationButtons.tsx
¦   +-- views/           (All page views)
¦   +-- ui/              (Reusable UI components)
+-- styles/
    +-- theme.css        (Design tokens, custom CSS)
    +-- tailwind.css     (Tailwind imports)
    +-- fonts.css        (Font imports)

---

Future Enhancement Guidelines

When adding new features:

1. Follow existing naming conventions
2. Maintain consistent color palette
3. Ensure touch-friendly sizing
4. Add route to routes.ts
5. Add menu item to Sidebar.tsx if applicable
6. Use existing UI component patterns
7. Test on target screen size
8. Consider real-time data update needs

Common Additions:

• New utility settings: Follow existing setting view patterns
• New data displays: Use card-based layouts with color coding
• New navigation items: Add to menuItems array with icon
• New status indicators: Use icon + text + color pattern