/*
  ==========================================
  CARD COMPONENT SYSTEM
  MILLION DOLLAR BUGS ACADEMY
  ==========================================
  
  Comprehensive card system following Martin Fowler's composition patterns and
  Ian Sommerville's systematic component architecture principles.
  
  "Programs must be written for people to read, and only incidentally for machines to execute." - Harold Abelson
  "The best programs are written so that computing machines can perform them quickly 
  and so that human beings can understand them clearly." - Donald Knuth
  
  Architecture Philosophy:
  1. Compositional Design - Cards built from reusable structural components
  2. Content Agnostic - Flexible container that adapts to various content types
  3. Progressive Enhancement - Works without JavaScript, enhanced with interaction
  4. Educational Context - Special variants for learning management systems
  5. Accessibility First - Screen reader friendly with proper ARIA support
  
  Dependencies:
  - design-tokens.css (must be imported first)
*/

/*
  ==========================================
  1. BASE CARD FOUNDATION
  ==========================================
  Following Robert C. Martin's Single Responsibility Principle
*/

/**
 * Base card component - Container foundation
 * 
 * Design decisions explained:
 * - Relative positioning: Enables absolute positioning of child elements
 * - Overflow hidden: Contains child elements and enables border-radius clipping
 * - Transition on transform: Smooth hover animations without layout thrash
 * - Box-shadow instead of border: Cleaner visual separation, better performance
 * 
 * Educational value: Demonstrates modern CSS container patterns
 */
.card {
  background: var(--color-surface-primary);
  border: var(--card-border);
  border-radius: var(--card-radius);
  box-shadow: var(--card-shadow);
  padding: var(--card-padding);
  transition: var(--card-transition);
  position: relative;
  overflow: hidden;
}

/**
 * Hover enhancement - Subtle elevation increase
 * Following Sarah Drasner's principles of delightful microinteractions
 * Creates visual feedback without being distracting
 */
.card:hover {
  box-shadow: var(--card-shadow-hover);
  transform: translateY(-2px);
}

/*
  ==========================================
  2. CARD STRUCTURAL COMPONENTS
  ==========================================
  Modular composition following Brad Traversy's component patterns
*/

/**
 * Card Header - Title and metadata section
 * Semantic structure with consistent spacing and hierarchy
 * Border separator creates clear visual distinction
 */
.card__header {
  margin-bottom: var(--space-4);
  padding-bottom: var(--space-4);
  border-bottom: 1px solid var(--color-border-primary);
}

/**
 * Card Title - Primary heading
 * Uses semantic typography scale from design tokens
 * Proper color contrast for accessibility
 */
.card__title {
  font: var(--typography-heading-h3);
  color: var(--color-text-primary);
  margin-bottom: var(--space-2);
}

/**
 * Card Subtitle - Secondary information
 * Lower visual hierarchy through color and size
 * Complements title without competing for attention
 */
.card__subtitle {
  font: var(--typography-body-small);
  color: var(--color-text-secondary);
  margin-bottom: 0;
}

/**
 * Card Content - Main body area
 * Flexible container for various content types
 * Consistent spacing with other card sections
 */
.card__content {
  margin-bottom: var(--space-4);
}

/**
 * Card Footer - Actions and metadata
 * Flexbox for responsive layout between elements
 * Border separator creates visual hierarchy
 */
.card__footer {
  margin-top: var(--space-4);
  padding-top: var(--space-4);
  border-top: 1px solid var(--color-border-primary);
  display: flex;
  justify-content: space-between;
  align-items: center;
  gap: var(--space-4);
}

/**
 * Card Media - Image and video container
 * Responsive media handling with aspect ratio preservation
 * Negative margins for full-width media within padded card
 */
.card__media {
  margin: calc(-1 * var(--card-padding)) calc(-1 * var(--card-padding)) var(--space-4);
  border-radius: var(--card-radius) var(--card-radius) 0 0;
  overflow: hidden;
  background: var(--color-surface-tertiary);
}

.card__media img,
.card__media video {
  width: 100%;
  height: auto;
  display: block;
}

/**
 * Card media with fixed aspect ratio
 * Maintains consistent card heights in grid layouts
 */
.card__media--16-9 {
  aspect-ratio: 16 / 9;
}

.card__media--4-3 {
  aspect-ratio: 4 / 3;
}

.card__media--square {
  aspect-ratio: 1 / 1;
}

.card__media--16-9 img,
.card__media--4-3 img,
.card__media--square img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

/*
  ==========================================
  3. EDUCATIONAL CARD VARIANTS
  ==========================================
  Specialized for learning management context
*/

/**
 * Project Card - Showcases student/professional projects
 * Visual indicator bar shows learning progression
 * Hover effect emphasizes interactivity
 */
.card--project {
  position: relative;
  overflow: hidden;
  cursor: pointer;
}

.card--project::before {
  content: '';
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  height: 4px;
  background: linear-gradient(90deg, 
    var(--color-stage-beginner), 
    var(--color-stage-expert));
  z-index: 1;
}

.card--project:hover {
  transform: translateY(-4px);
  box-shadow: var(--shadow-lg);
}

/**
 * Stage Cards - Learning progression indicators
 * Color-coded left borders indicate complexity level
 * Enhanced padding compensates for border width
 */
.card--stage {
  border-left: 4px solid var(--color-stage-beginner);
  padding-left: calc(var(--card-padding) + var(--space-4));
  position: relative;
}

.card--stage::before {
  content: '';
  position: absolute;
  left: -4px;
  top: 0;
  bottom: 0;
  width: 4px;
  background: var(--color-stage-beginner);
  opacity: 0;
  transition: opacity var(--transition-timing-fast);
}

.card--stage:hover::before {
  opacity: 0.3;
}

/* Stage progression variants */
.card--stage.stage--intermediate {
  border-left-color: var(--color-stage-intermediate);
}

.card--stage.stage--intermediate::before {
  background: var(--color-stage-intermediate);
}

.card--stage.stage--expert {
  border-left-color: var(--color-stage-expert);
}

.card--stage.stage--expert::before {
  background: var(--color-stage-expert);
}

.card--stage.stage--master {
  border-left-color: var(--color-stage-master);
}

.card--stage.stage--master::before {
  background: var(--color-stage-master);
}

/**
 * Course Card - Educational content presentation
 * Specialized structure for course information display
 */
.card--course {
  display: flex;
  flex-direction: column;
  height: 100%;
}

.card--course .card__content {
  flex: 1;
  display: flex;
  flex-direction: column;
  margin-bottom: 0;
}

.card--course .card__description {
  flex: 1;
  margin-bottom: var(--space-4);
}

/**
 * Achievement Card - Progress and completion indicators
 * Visual emphasis through color and icons
 */
.card--achievement {
  background: var(--color-surface-success);
  border-color: var(--color-border-success);
  position: relative;
}

.card--achievement::after {
  content: '✓';
  position: absolute;
  top: var(--space-3);
  right: var(--space-3);
  width: 2rem;
  height: 2rem;
  background: var(--color-success);
  color: var(--color-text-inverse);
  border-radius: var(--radius-full);
  display: flex;
  align-items: center;
  justify-content: center;
  font-weight: var(--font-weight-bold);
  font-size: var(--font-size-sm);
}

/*
  ==========================================
  4. INTERACTIVE CARD STATES
  ==========================================
  Following Kent C. Dodds' progressive enhancement principles
*/

/**
 * Interactive Card - Clickable with enhanced feedback
 * Cursor and user-select indicate interactivity
 * Reduced active transform provides tactile feedback
 */
.card--interactive {
  cursor: pointer;
  user-select: none;
  transition: var(--card-transition), box-shadow var(--transition-timing-fast);
}

.card--interactive:hover {
  transform: translateY(-3px);
  box-shadow: var(--shadow-lg);
}

.card--interactive:active {
  transform: translateY(-1px);
  box-shadow: var(--shadow-md);
}

.card--interactive:focus-visible {
  outline: 2px solid var(--color-brand-primary);
  outline-offset: 2px;
}

/**
 * Selectable Card - Multi-select interfaces
 * Visual indication of selection state
 * Maintains accessibility with proper ARIA attributes
 */
.card--selectable {
  cursor: pointer;
  position: relative;
  border: 2px solid transparent;
  transition: var(--card-transition), border-color var(--transition-timing-fast);
}

.card--selectable:hover {
  border-color: var(--color-brand-primary);
  transform: translateY(-1px);
}

.card--selectable[aria-selected="true"] {
  border-color: var(--color-brand-primary);
  background: var(--color-brand-primary-light);
  box-shadow: var(--shadow-md);
}

.card--selectable[aria-selected="true"]::after {
  content: '✓';
  position: absolute;
  top: var(--space-2);
  right: var(--space-2);
  width: 1.5rem;
  height: 1.5rem;
  background: var(--color-brand-primary);
  color: var(--color-text-inverse);
  border-radius: var(--radius-full);
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: var(--font-size-xs);
  font-weight: var(--font-weight-bold);
}

/**
 * Completion States - Progress indication
 * Visual feedback for learning progress tracking
 */
.card--completed {
  background: var(--color-surface-success);
  border-color: var(--color-border-success);
  opacity: 0.8;
}

.card--in-progress {
  background: var(--color-surface-warning);
  border-color: var(--color-border-warning);
  position: relative;
}

.card--in-progress::before {
  content: '';
  position: absolute;
  top: 0;
  left: 0;
  height: 100%;
  width: var(--progress-width, 30%);
  background: linear-gradient(90deg, 
    transparent, 
    var(--color-warning-light));
  border-radius: var(--card-radius) 0 0 var(--card-radius);
  opacity: 0.3;
}

.card--locked {
  opacity: 0.6;
  cursor: not-allowed;
  background: var(--color-surface-tertiary);
  position: relative;
}

.card--locked::after {
  content: '🔒';
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  font-size: 2rem;
  opacity: 0.5;
}

.card--locked:hover {
  transform: none;
  box-shadow: var(--card-shadow);
}

/*
  ==========================================
  5. CARD SIZE VARIATIONS
  ==========================================
  Systematic scaling for different layout contexts
*/

/**
 * Compact Card - Reduced padding for dense layouts
 * Maintains proportional spacing relationships
 */
.card--compact {
  padding: var(--space-4);
}

.card--compact .card__header {
  margin-bottom: var(--space-3);
  padding-bottom: var(--space-3);
}

.card--compact .card__content {
  margin-bottom: var(--space-3);
}

.card--compact .card__footer {
  margin-top: var(--space-3);
  padding-top: var(--space-3);
}

/**
 * Large Card - Increased padding for hero sections
 * Enhanced visual presence for important content
 */
.card--large {
  padding: var(--space-8);
}

.card--large .card__header {
  margin-bottom: var(--space-6);
  padding-bottom: var(--space-6);
}

.card--large .card__content {
  margin-bottom: var(--space-6);
}

.card--large .card__footer {
  margin-top: var(--space-6);
  padding-top: var(--space-6);
}

.card--large .card__title {
  font: var(--typography-heading-h2);
}

/*
  ==========================================
  6. CARD LAYOUT PATTERNS
  ==========================================
  Complex compositions for specific use cases
*/

/**
 * Horizontal Card - Side-by-side media and content
 * Responsive layout that stacks on mobile
 */
.card--horizontal {
  display: flex;
  align-items: stretch;
  padding: 0;
}

.card--horizontal .card__media {
  flex: 0 0 40%;
  margin: 0;
  border-radius: var(--card-radius) 0 0 var(--card-radius);
}

.card--horizontal .card__body {
  flex: 1;
  padding: var(--card-padding);
  display: flex;
  flex-direction: column;
}

.card--horizontal .card__content {
  flex: 1;
}

/* Stack horizontally on mobile */
@media (max-width: 640px) {
  .card--horizontal {
    flex-direction: column;
  }
  
  .card--horizontal .card__media {
    flex: none;
    border-radius: var(--card-radius) var(--card-radius) 0 0;
  }
}

/**
 * Overlay Card - Content overlaid on media
 * Advanced positioning for hero-style presentations
 */
.card--overlay {
  padding: 0;
  color: var(--color-text-inverse);
  position: relative;
  min-height: 300px;
}

.card--overlay .card__media {
  position: absolute;
  inset: 0;
  margin: 0;
  border-radius: var(--card-radius);
}

.card--overlay .card__media::after {
  content: '';
  position: absolute;
  inset: 0;
  background: linear-gradient(
    180deg, 
    transparent 0%, 
    rgba(0, 0, 0, 0.7) 100%
  );
}

.card--overlay .card__body {
  position: relative;
  z-index: 1;
  padding: var(--card-padding);
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: flex-end;
}

.card--overlay .card__title,
.card--overlay .card__content {
  color: var(--color-text-inverse);
}

/*
  ==========================================
  7. CARD GRID SYSTEMS
  ==========================================
  Layout utilities for card collections
*/

/**
 * Card Grid Container
 * Responsive grid system for card layouts
 * Uses CSS Grid for modern, flexible layouts
 */
.card-grid {
  display: grid;
  gap: var(--space-6);
  grid-template-columns: 1fr;
}

/* Responsive breakpoints */
@media (min-width: 640px) {
  .card-grid {
    grid-template-columns: repeat(2, 1fr);
  }
}

@media (min-width: 1024px) {
  .card-grid {
    grid-template-columns: repeat(3, 1fr);
  }
}

@media (min-width: 1280px) {
  .card-grid {
    grid-template-columns: repeat(4, 1fr);
  }
}

/* Grid variations */
.card-grid--dense {
  gap: var(--space-4);
}

.card-grid--sparse {
  gap: var(--space-8);
}

.card-grid--2-col {
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
}

.card-grid--3-col {
  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
}

.card-grid--4-col {
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
}

/**
 * Masonry-style Card Layout
 * For cards with varying content heights
 */
.card-masonry {
  columns: 1;
  column-gap: var(--space-6);
}

.card-masonry .card {
  break-inside: avoid;
  margin-bottom: var(--space-6);
}

@media (min-width: 640px) {
  .card-masonry {
    columns: 2;
  }
}

@media (min-width: 1024px) {
  .card-masonry {
    columns: 3;
  }
}

@media (min-width: 1280px) {
  .card-masonry {
    columns: 4;
  }
}

/*
  ==========================================
  8. ACCESSIBILITY ENHANCEMENTS
  ==========================================
  Following WCAG 2.1 guidelines for inclusive design
*/

/**
 * Screen reader optimizations
 * Hidden content for assistive technology
 */
.card__sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

/**
 * Focus management for interactive cards
 * Ensures keyboard navigation accessibility
 */
.card--interactive:focus-visible {
  outline: 2px solid var(--color-brand-primary);
  outline-offset: 2px;
  z-index: 1;
}

/**
 * High contrast mode support
 * Ensures visibility in accessibility themes
 */
@media (prefers-contrast: high) {
  .card {
    border-width: 2px;
  }
  
  .card--stage {
    border-left-width: 6px;
  }
  
  .card--selectable {
    border-width: 3px;
  }
}

/**
 * Reduced motion preferences
 * Respects user accessibility settings
 */
@media (prefers-reduced-motion: reduce) {
  .card {
    transition: none;
  }
  
  .card:hover,
  .card--interactive:hover,
  .card--project:hover {
    transform: none;
  }
}

/*
  ==========================================
  9. UTILITY CLASSES
  ==========================================
  Helper classes for common card modifications
*/

/**
 * Card spacing utilities
 * Override default margins for layout control
 */
.card--no-padding {
  padding: 0;
}

.card--no-margin {
  margin: 0;
}

.card--margin-bottom {
  margin-bottom: var(--space-6);
}

/**
 * Card elevation utilities
 * Manual control over shadow depth
 */
.card--flat {
  box-shadow: none;
  border: 1px solid var(--color-border-primary);
}

.card--elevated {
  box-shadow: var(--shadow-lg);
}

.card--floating {
  box-shadow: var(--shadow-xl);
}

/**
 * Card width utilities
 * For responsive and layout-specific sizing
 */
.card--full-width {
  width: 100%;
}

.card--max-width {
  max-width: 100%;
}

.card--fixed-height {
  height: 400px;
  display: flex;
  flex-direction: column;
}

.card--fixed-height .card__content {
  flex: 1;
  overflow: hidden;
}

/*
  ==========================================
  CARD SYSTEM COMPLETE
  ==========================================
  
  This comprehensive card system demonstrates:
  ✅ Compositional Design - Reusable structural components
  ✅ Content Flexibility - Adapts to various content types
  ✅ Progressive Enhancement - Works without JS, enhanced with interaction
  ✅ Educational Context - Learning management specialized variants
  ✅ Accessibility First - Screen reader friendly with ARIA support
  ✅ Responsive Design - Mobile-first with flexible layouts
  ✅ Performance Conscious - Efficient CSS with minimal repaints
  ✅ Semantic Structure - Clear hierarchy and meaningful markup
  ✅ Visual Hierarchy - Consistent spacing and typography scales
  ✅ Maintainable Architecture - Uses design tokens throughout
  
  Usage Examples:
  
  <!-- Basic card -->
  <div class="card">
    <div class="card__header">
      <h3 class="card__title">Card Title</h3>
      <p class="card__subtitle">Supporting information</p>
    </div>
    <div class="card__content">
      <p>Main content goes here...</p>
    </div>
    <div class="card__footer">
      <button class="btn btn--primary">Action</button>
      <span class="badge badge--info">Status</span>
    </div>
  </div>
  
  <!-- Educational stage card -->
  <div class="card card--stage stage--expert">
    <div class="card__header">
      <h3 class="card__title">Advanced React Patterns</h3>
      <p class="card__subtitle">Expert Level</p>
    </div>
    <div class="card__content">
      <p>Master render props, higher-order components...</p>
    </div>
  </div>
  
  <!-- Project showcase card -->
  <div class="card card--project card--interactive">
    <div class="card__media card__media--16-9">
      <img src="project.jpg" alt="Project screenshot">
    </div>
    <div class="card__header">
      <h3 class="card__title">E-commerce Platform</h3>
      <p class="card__subtitle">Full-stack JavaScript</p>
    </div>
    <div class="card__footer">
      <div class="btn-group">
        <button class="btn btn--outline btn--small">Demo</button>
        <button class="btn btn--outline btn--small">Code</button>
      </div>
    </div>
  </div>
  
  <!-- Card grid layout -->
  <div class="card-grid card-grid--3-col">
    <div class="card">...</div>
    <div class="card">...</div>
    <div class="card">...</div>
  </div>
  
  Following Martin Fowler's composition patterns and Ian Sommerville's systematic architecture:
  "The art of programming is the art of organizing complexity, 
  of mastering multitude and avoiding its bastard chaos as effectively as possible."
*/