Design Guidelines

Comprehensive guide on when and where to use different design elements, components, and patterns in our design system.

Color Usage

Primary Colors

When to use: Primary colors should be used for main actions, links, and key interactive elements.

  • Call-to-action buttons
  • Active navigation links
  • Important highlights and accents
  • Interactive elements that require user attention

Background Colors

When to use: Background colors create visual hierarchy and define content areas.

  • Primary Background: Main page background, default container backgrounds
  • Secondary Background: Cards, elevated sections, alternate content blocks
  • Tertiary Background: Nested elements, subtle highlights, code blocks

Text Colors

When to use: Text colors ensure readability and establish information hierarchy.

  • Primary Text: Headings, main content, important information
  • Secondary Text: Descriptions, captions, supporting information
  • Tertiary Text: Placeholders, hints, less important details

Typography

Headings

When to use: Headings create content hierarchy and improve scannability.

  • H1: Page titles, hero sections (one per page)
  • H2: Major section headings
  • H3: Subsection headings
  • H4-H6: Nested content headings, card titles

Body Text

When to use: Body text is for main content and descriptions.

  • Paragraphs and main content blocks
  • Article text and descriptions
  • Form labels and helper text
  • Navigation items and menu text

Components

Navigation

When to use: Navigation provides site structure and access to main sections.

  • Top-level navigation for main site sections
  • Dropdown menus for related sub-sections
  • Breadcrumbs for deep page hierarchies
  • Mobile hamburger menu for responsive navigation

Buttons

When to use: Buttons trigger actions and guide user interactions.

  • Primary Buttons: Main actions (Submit, Apply, Sign Up)
  • Secondary Buttons: Alternative actions, less important actions
  • Text Links: Navigation, less prominent actions
  • Icon Buttons: Theme toggle, notifications, compact actions

Cards

When to use: Cards group related content and create visual separation.

  • Content collections and grids
  • Feature highlights and showcases
  • Information panels and sidebars
  • Dashboard widgets and metrics

Dropdowns

When to use: Dropdowns organize related options and save space.

  • Navigation menus with sub-items
  • Form select inputs
  • Action menus and options
  • Filter and sort controls

Effects & Animations

Liquid Glass Effect

When to use: Glassmorphism creates depth and modern aesthetics.

  • Navigation bars and headers
  • Modal dialogs and overlays
  • Dropdown menus
  • Floating action panels

Gradient Text

When to use: Animated gradient text draws attention to important elements.

  • Hero section titles
  • Special call-to-action buttons
  • Highlighted announcements
  • Brand elements and logos

Hover Effects

When to use: Hover effects provide feedback and indicate interactivity.

  • Interactive buttons and links
  • Navigation items
  • Cards and clickable elements
  • Icon buttons and controls

Spacing & Layout

Container Width

When to use: Consistent container widths maintain readability and visual balance.

  • Max-width 1200px: Main content containers, page sections
  • Full-width: Hero sections, banners, navigation
  • Narrow containers: Sidebars, forms, focused content

Padding & Margins

When to use: Consistent spacing creates rhythm and improves readability.

  • Section spacing: 3rem vertical padding
  • Card padding: 1.5rem internal spacing
  • Element gaps: 0.5rem to 2rem based on relationship
  • Mobile: Reduced spacing (1rem to 2rem)

Responsive Design

Breakpoints

When to use: Breakpoints ensure optimal experience across all devices.

  • Mobile: Below 768px - Stacked layouts, hamburger menu
  • Desktop: 768px and above - Side-by-side layouts, full navigation
  • Always test on multiple screen sizes
  • Use flexible units (rem, %, vw/vh) for scalability

Mobile-First Approach

When to use: Design for mobile first, then enhance for larger screens.

  • Start with mobile layout and constraints
  • Progressive enhancement for desktop
  • Touch-friendly targets (minimum 44x44px)
  • Optimize images and assets for mobile

Best Practices

Accessibility

  • Maintain sufficient color contrast ratios (WCAG AA minimum)
  • Provide alt text for images
  • Use semantic HTML elements
  • Ensure keyboard navigation works
  • Include ARIA labels where needed

Performance

  • Optimize images and assets
  • Minimize CSS and JavaScript
  • Use CSS variables for theming
  • Lazy load non-critical content
  • Test loading times on various connections

Consistency

  • Use design system components consistently
  • Follow established patterns and conventions
  • Maintain visual hierarchy
  • Keep spacing and sizing consistent
  • Document custom variations