sp80/.planning/codebase/CONVENTIONS.md

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

// 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

// 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:

// 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:

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:

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