component_layer_rules

Purpose and Scope

• Component layer contains reusable UI components for frontend/components/**/*.tsx and feature-specific components under frontend/app/**/components/**/*.tsx
• Responsibilities: Create reusable components, implement business logic, handle interactions, provide consistent UI
• MANDATORY: All components must use TypeScript and functional components

UI Library and Icons

• Ant Design first: Use Ant Design for forms, data display, modals, buttons, layouts. See ui_standards_rules.mdc.
• Icons: Lucide icons primary (lucide-react), @ant-design/icons as fallback when Lucide lacks the icon.

// Prefer Lucide
import { Search, RefreshCw, Edit } from "lucide-react";

// Fallback when Lucide has no equivalent (e.g. ExclamationCircleFilled for modal)
import { ExclamationCircleFilled, InfoCircleFilled } from "@ant-design/icons";

Component Organization

• components/auth/ - Authentication-related components
• components/providers/ - Context providers and global state management

Component Structure

• Use functional components with TypeScript
• Define proper interfaces for all props
• Use React hooks for state management
• Implement proper error boundaries where needed
• Follow single responsibility principle
• Single component file should not exceed ~1000 lines: Split into subcomponents or extract logic to hooks/utils when a file grows. keep files digestible.

Props and State Management

• All props must be typed with interfaces
• Use optional props with default values when appropriate
• Prefer controlled components over uncontrolled
• Use local state for component-specific data
• Use context for shared state across components
• Avoid Prop Drilling: When a component receives more than ~7–10 props, or props are passed through multiple layers only to reach a deep child, prefer:
  • Context for cross-cutting state (auth, theme, feature flags)
  • Composition (children, render props) instead of passing many callbacks
  • Custom hooks to encapsulate shared logic; let children use the hook instead of receiving props from parent
• CRITICAL: All logging must use logger.ts - never use console.log