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:**
```tsx
<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