Instruction file imported from ResearchHub/web (.cursor/rules/design-system.mdc). Copyright stays with the author.

ResearchHub Design System

This document outlines the design system and styling guidelines used in the ResearchHub codebase.

Styling Approach

ResearchHub uses Tailwind CSS as the primary styling solution, complemented by CSS modules for complex components when necessary.

1. Tailwind CSS:

   • Use Tailwind utility classes for most styling needs
   • Follow the "utility-first" approach
   • Use Tailwind's built-in responsive classes for responsive design

2. CSS Modules:

   • Use CSS modules for complex components that require custom animations or styles that are difficult to achieve with Tailwind
   • Name CSS module files with the .module.css extension

3. Styling Utilities:

   • Use the cn() utility function for conditional class name composition
   • Use class-variance-authority (cva) for component variants

Color System

1. Color Palette:

   • Use the color tokens defined in the Tailwind configuration
   • Primary colors: Shades of indigo and blue
   • Secondary colors: Gray scale and orange/yellow for accent
   • Semantic colors: Success (green), warning (yellow), error (red), info (blue)

   // Use semantic color tokens
   <div className="bg-primary-600 text-white">Primary button</div>
   <div className="bg-gray-100 text-gray-800">Secondary button</div>
   <div className="bg-red-100 text-red-800">Error state</div>

2. Color Usage:

   • Use primary colors for primary actions and branding
   • Use gray scale for UI structure, backgrounds, and secondary elements
   • Use semantic colors consistently for their respective meanings
   • Maintain appropriate contrast ratios for accessibility (4.5:1 minimum)

Typography

1. Font Family:

   • Primary font: Inter (sans-serif)
   • Heading font: Cal Sans for titles and large headings
   • Monospace font: For code blocks and technical content

2. Font Sizes:

   • Follow the Tailwind CSS font size scale
   • Use relative units (rem) for font sizes to support user preferences

   <h1 className="text-3xl font-semibold text-gray-900">Page Title</h1>
   <h2 className="text-xl font-medium text-gray-800">Section Heading</h2>
   <p className="text-base text-gray-700">Body text</p>
   <span className="text-sm text-gray-500">Caption text</span>

3. Font Weights:

   • Regular (400) for body text
   • Medium (500) for semi-emphasis
   • Semibold (600) for headings and emphasis
   • Bold (700) for strong emphasis

4. Line Heights:

   • Use appropriate line heights for readability
   • Body text: leading-normal (1.5)
   • Headings: leading-tight (1.25)
   • Single-line elements: leading-none (1)

Spacing

1. Spacing Scale:

   • Follow the Tailwind CSS spacing scale
   • Use consistent spacing for margins and padding
   • Use the spacing scale for gaps, grid gaps, and other spacing properties

   <div className="p-4">
     <div className="mb-6">
       <h2 className="mb-2">Section Title</h2>
       <p>Content</p>
     </div>
   </div>

2. Layout Spacing:

   • Page margins: px-4 sm:px-6 md:px-8 lg:px-12
   • Section spacing: my-8 md:my-12 lg:my-16
   • Component spacing: p-4 for cards, p-2 for smaller components

Components

1. Base Components:

   • Use the components in the components/ui directory as the foundation
   • Common components include Button, Input, Card, Badge, and more
   • All components are built with accessibility in mind

2. Component Variants:

   • Components have consistent variants using class-variance-authority
   • Common variants include size, color, and emphasis level

   // Button with variants
   <Button variant="primary" size="md">Primary Action</Button>
   <Button variant="secondary" size="sm">Secondary Action</Button>

3. Component Composition:

   • Build complex UI by composing smaller components
   • Use the children prop for flexible content
   • Use render props for complex rendering logic

Icons

1. Icon System:

   • Use Lucide icons as the primary icon set
   • Use Font Awesome for additional icons when necessary
   • Keep icons consistent in style and usage

   import { User, Settings, Bell } from 'lucide-react';
   
   <Button>
     <User className="w-4 h-4 mr-2" />
     Profile
   </Button>

2. Icon Sizing:

   • Use consistent sizing: sm (16px), md (20px), lg (24px)
   • Adjust stroke width for better visibility at different sizes
   • Maintain proper alignment with text using flex layout

Responsive Design

1. Breakpoints:

   • Follow Tailwind's breakpoint system:
     • sm: 640px
     • md: 768px
     • lg: 1024px
     • xl: 1280px
     • 2xl: 1536px
     • custom: wide (1200px), 3xl (1600px)

2. Mobile-first Approach:

   • Start with mobile layouts and progressively enhance for larger screens
   • Use responsive utilities to adapt layout, typography, and spacing

   <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
     {/* Content */}
   </div>

3. Responsive Components:

   • Design components to adapt to different screen sizes
   • Use responsive variants for component properties
   • Test all components across different breakpoints

Accessibility

1. Color Contrast:

   • Maintain a minimum contrast ratio of 4.5:1 for normal text
   • Maintain a minimum contrast ratio of 3:1 for large text and UI components
   • Test color combinations with accessibility tools

2. Keyboard Navigation:

   • Ensure all interactive elements are keyboard accessible
   • Implement proper focus states with visible focus indicators
   • Maintain a logical tab order

3. Screen Readers:

   • Add appropriate ARIA attributes when necessary
   • Use semantic HTML elements when possible
   • Provide alt text for images and aria-labels for interactive elements

4. Reduced Motion:

   • Respect user preferences for reduced motion
   • Provide alternatives to motion-heavy interactions

   <div className="transition-transform motion-reduce:transition-none">
     {/* Content */}
   </div>

Dark Mode

1. Color Adaptation:

   • Use Tailwind's dark mode utilities to adapt colors
   • Keep proper contrast in both light and dark modes
   • Test all components in both modes

   <div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
     {/* Content */}
   </div>

2. Dark Mode Strategy:

   • Implement dark mode based on user preference
   • Allow user toggling with persistent preference
   • Ensure smooth transitions between modes

Animation and Interaction

1. Transitions:

   • Use subtle transitions for state changes
   • Keep transitions short (150-300ms)
   • Use appropriate easing functions

   <button className="transition-colors duration-200 ease-in-out">
     {/* Content */}
   </button>

2. Hover and Focus States:

   • Provide clear visual feedback for hover and focus states
   • Keep hover effects subtle but noticeable
   • Ensure focus states meet accessibility standards

3. Loading States:

   • Show appropriate loading indicators for async operations
   • Use skeleton loaders for content loading
   • Maintain layout stability during loading states

These design system guidelines ensure a consistent, accessible, and visually cohesive user experience throughout the ResearchHub application.