# Coding Conventions

**Analysis Date:** 2026-03-13

## Overview

This codebase follows conventions documented in `/sample_interface/guidelines/Guidelines.md` with React/TypeScript patterns optimized for a touchscreen industrial dashboard interface.

## Naming Patterns

### Files
- **Components:** PascalCase with `.tsx` extension (e.g., `RainfallView.tsx`, `Header.tsx`)
- **Views:** `[Feature]View.tsx` pattern (e.g., `SettingView.tsx`, `LoginView.tsx`)
- **UI Components:** Lowercase with hyphen separation (e.g., `button.tsx`, `card.tsx`)
- **Utilities:** camelCase (e.g., `utils.ts`)
- **Configuration:** `.config.ts` or `.config.mjs` (e.g., `vite.config.ts`, `postcss.config.mjs`)

### Functions & Variables
- **Functions:** camelCase (e.g., `scrollUp()`, `toggleExpanded()`, `formatTime()`)
- **React Components:** PascalCase (e.g., `function Card()`, `function Header()`)
- **State Variables:** camelCase with `is`/`has`/`should` prefix for booleans
  - `const [sidebarCollapsed, setSidebarCollapsed] = useState(false)`
  - `const [isOnline, setIsOnline] = useState(true)`
  - `const [selectedFile, setSelectedFile] = useState(...)`
- **Constants:** camelCase for objects/arrays, UPPERCASE for true constants
  - `const menuItems = [...]`
  - `const scrollAmount = 300`

### Props & Types
- **Props Interface:** `[ComponentName]Props` (e.g., `SidebarProps`, `MenuItem`)
- **Type Parameters:** PascalCase (e.g., `TFieldValues`, `TName`)
- **Event Handlers:** `on[Action]` prefix (e.g., `onToggle`, `onClick`)

## Code Style

### Formatting
- **No automated linting/formatting configured** (no ESLint, Prettier, or Biome detected)
- Indentation: 2 spaces
- Semicolons: Used consistently
- Quotes: Double quotes for strings
- Trailing commas: Not used consistently

### Component Structure
```typescript
// Named function declaration (preferred)
function Button({ className, variant, ...props }: ButtonProps) {
  return <Comp className={cn(buttonVariants({ variant, className }))} {...props} />;
}

// Arrow function for simpler components
export const router = createBrowserRouter([...]);

// Export at end of file for UI components
export { Button, buttonVariants };
```

## Import Organization

### Order
1. **React imports:** `import * as React from "react"`
2. **External libraries:** Radix UI, React Router, Lucide icons
3. **Internal components:** Relative paths from current file
4. **Utilities:** Local utility functions

### Examples
```typescript
// From button.tsx
import * as React from "react";
import { Slot } from "@radix-ui/react-slot";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "./utils";

// From views
import { Card, CardContent } from "../ui/card";
import { Button } from "../ui/button";
import { Settings } from "lucide-react";
```

### Path Aliases
- `@/` maps to `src/` directory (configured in `vite.config.ts`)
- Currently used in minimal places; relative imports preferred in existing code

## Component Patterns

### shadcn/ui Pattern
Components follow the shadcn/ui design pattern:
```typescript
// 1. Import React as namespace
import * as React from "react";

// 2. Use React.ComponentProps for HTML element props
function Card({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      data-slot="card"  // Data attribute for debugging
      className={cn("base-classes", className)}  // cn() utility for class merging
      {...props}
    />
  );
}

// 3. Export at end
export { Card, CardHeader, ... };
```

### View Components
Views follow consistent structure:
```typescript
export function ViewName() {
  // Local state and data
  const data = [...];
  
  return (
    <div className="space-y-4">
      {/* Header with icon and title */}
      <div className="flex items-center gap-3">
        <Icon className="w-6 h-6 text-blue-400" />
        <h1 className="text-2xl font-bold text-white">Title</h1>
      </div>
      
      {/* Content cards */}
      <Card>...</Card>
    </div>
  );
}
```

## Styling Conventions

### Tailwind CSS Usage
- **Primary styling method:** Tailwind utility classes
- **Dark theme default:** All components styled for dark UI
- **Custom colors:** Extended via CSS variables in `theme.css`

### Color Palette
- Backgrounds: `bg-gray-900` (primary), `bg-gray-950` (elevated), `bg-gray-800` (inputs)
- Primary actions: `bg-blue-600 hover:bg-blue-700`
- Success: `text-green-400`, Warning: `text-yellow-400`, Error: `text-red-400`
- Borders: `border-gray-700`

### Class Name Utility
All UI components use `cn()` utility from `utils.ts`:
```typescript
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}
```

### Touchscreen-First Design
- Minimum touch targets: 44x44px (preferably 56x56px)
- Button sizing: `h-14 w-14` for navigation, `h-9` for standard buttons
- Spacing: `p-3` or `p-4` for adequate touch area

## State Management

### Local State
- React `useState` for component-level state
- `useEffect` for side effects (timers, subscriptions)
- No global state management library detected

### Router State
- React Router v7 for routing
- `useLocation()` for current path
- URL as source of truth for navigation state

## Error Handling

### Patterns
- Minimal explicit error handling in UI code
- Form validation via react-hook-form (in `form.tsx`)
- Console errors for development debugging

### Type Safety
- TypeScript strict mode implied by usage
- Type imports using `type` keyword: `import { type ClassValue }`
- Generic components with proper type constraints

## Comments

### Guidelines
- Minimal inline comments
- Component purpose inferred from file name and structure
- Complex logic may have inline explanations

### JSDoc/TSDoc
- Not used extensively
- Type definitions provide documentation

## Function Design

### Size
- Components: Typically 30-120 lines
- View components: 50-110 lines each
- UI components: 20-90 lines each

### Parameters
- Destructured props with explicit typing
- Spread operator for passing through remaining props
- Default values inline in destructuring

### Return Values
- JSX.Element for React components
- Void for event handlers
- Typed arrays/objects for data functions

## Module Design

### Exports
- Named exports for all components (no default exports except App.tsx)
- Grouped exports at end of file for UI components
- Re-exports from barrel files not used

### File Organization
```
src/app/
├── App.tsx              # Default export, entry point
├── routes.ts            # Named export for router config
├── components/
│   ├── [Layout].tsx     # Named exports
│   ├── ui/              # UI primitives
│   │   └── [component].tsx
│   └── views/           # Page views
│       └── [View].tsx
└── styles/
    └── *.css
```

## Special Conventions

### Touchscreen Interface
- No scrollbars visible (hidden via CSS)
- Navigation via fixed Up/Down buttons
- Fixed button positioning: `fixed top-20 right-4`

### Data Display Pattern
- Icon + Title header for all views
- Card-based content organization
- Color-coded data categories

### Status Indicators
- Icon + text pattern: `<Wifi className="w-3 h-3 text-green-500" />`
- Dot indicators: `w-2 h-2 rounded-full`

## Configuration Files

- **`vite.config.ts`:** Build configuration with path alias
- **`postcss.config.mjs`:** PostCSS (minimal - Tailwind handles processing)
- **`package.json`:** Scripts limited to `build`
- **No lint/format config detected:** No ESLint, Prettier, or Biome configuration

---

*Convention analysis: 2026-03-13*