michaelschiemer/backups/docs-backup-20250731125004/design-system/css-architecture.md

# CSS Architecture

> ITCSS-based modular CSS architecture with component-driven development and utility-first approach.

## 📁 File Structure

```
resources/css/
├── styles.css                    # Main import file
├── settings/
│   ├── colors.css               # Color definitions
│   ├── typography.css           # Font sizes, fonts
│   ├── spacing.css              # Spacing (margin, padding)
│   └── variables.css            # Duration, easing, radius, z-index etc.
├── base/
│   ├── reset.css                # Reset/Normalize
│   ├── global.css               # Global styles for html, body, etc.
│   ├── typography.css           # h1, p, etc.
│   ├── focus.css                # Focus states
│   ├── media.css                # Media queries
│   └── index.css                # Base layer imports
├── layout/
│   ├── container.css            # .page-container, max-widths, etc.
│   └── grid.css                 # Custom grid system
├── components/
│   ├── header.css
│   ├── nav.css
│   ├── footer.css
│   ├── buttons.css
│   ├── card.css
│   └── sidebar.css
├── forms/
│   └── inputs.css
├── utilities/
│   ├── animations.css           # .fade-in, .shake, etc.
│   ├── helpers.css              # .skip-link, .hidden, .visually-hidden
│   ├── scroll.css               # scroll-behavior, scrollbar-style
│   ├── transitions.css
│   └── noise.css
└── themes/
    └── dark.css                 # Dark mode color adjustments
```

## 🏗 ITCSS Layer Hierarchy

1. **Settings** - Variables, colors, typography scales
2. **Base** - Reset, normalize, global element styles
3. **Layout** - Grid systems, containers, structural components
4. **Components** - UI components and modules
5. **Utilities** - Helper classes and overrides
6. **Themes** - Color scheme variations

## 🎨 Design Tokens

### Colors
```css
/* Primary Palette */
--color-primary: #007bff;
--color-primary-dark: #0056b3;
--color-primary-light: #66b3ff;

/* Semantic Colors */
--color-success: #28a745;
--color-warning: #ffc107;
--color-error: #dc3545;
--color-info: #17a2b8;

/* Neutral Palette */
--color-gray-50: #f8f9fa;
--color-gray-100: #e9ecef;
--color-gray-900: #212529;
```

### Typography
```css
/* Font Stacks */
--font-family-sans: system-ui, -apple-system, sans-serif;
--font-family-mono: 'SF Mono', Monaco, 'Cascadia Code', monospace;

/* Type Scale */
--font-size-xs: 0.75rem;    /* 12px */
--font-size-sm: 0.875rem;   /* 14px */
--font-size-base: 1rem;     /* 16px */
--font-size-lg: 1.125rem;   /* 18px */
--font-size-xl: 1.25rem;    /* 20px */
--font-size-2xl: 1.5rem;    /* 24px */
--font-size-3xl: 1.875rem;  /* 30px */
--font-size-4xl: 2.25rem;   /* 36px */
```

### Spacing System
```css
/* 8pt Grid System */
--space-1: 0.25rem;   /* 4px */
--space-2: 0.5rem;    /* 8px */
--space-3: 0.75rem;   /* 12px */
--space-4: 1rem;      /* 16px */
--space-5: 1.25rem;   /* 20px */
--space-6: 1.5rem;    /* 24px */
--space-8: 2rem;      /* 32px */
--space-10: 2.5rem;   /* 40px */
--space-12: 3rem;     /* 48px */
--space-16: 4rem;     /* 64px */
--space-20: 5rem;     /* 80px */
```

## 🧩 Component Patterns

### BEM Methodology
```css
/* Block */
.card { }

/* Element */
.card__header { }
.card__body { }
.card__footer { }

/* Modifier */
.card--large { }
.card--featured { }
.card__header--centered { }
```

### Component States
```css
.button {
  /* Base styles */
  
  &:hover { }
  &:focus { }
  &:active { }
  &:disabled { }
  
  &[aria-pressed="true"] { }
  &[aria-expanded="true"] { }
}
```

## 📱 Responsive Design

### Breakpoints
```css
/* Mobile First Approach */
--breakpoint-sm: 640px;
--breakpoint-md: 768px;
--breakpoint-lg: 1024px;
--breakpoint-xl: 1280px;
--breakpoint-2xl: 1536px;
```

### Media Query Mixins
```css
@media (min-width: 768px) {
  /* Tablet and up */
}

@media (min-width: 1024px) {
  /* Desktop and up */
}

@media (prefers-reduced-motion: reduce) {
  /* Reduced motion accessibility */
}

@media (prefers-color-scheme: dark) {
  /* Dark mode preferences */
}
```

## 🎯 Admin-Specific Extensions

### Admin Color Palette
```css
/* Admin Theme Colors */
--admin-primary: #6366f1;
--admin-secondary: #8b5cf6;
--admin-success: #10b981;
--admin-warning: #f59e0b;
--admin-error: #ef4444;

/* Admin Neutral Palette */
--admin-bg: #f8fafc;
--admin-surface: #ffffff;
--admin-border: #e2e8f0;
--admin-text: #1e293b;
--admin-text-muted: #64748b;
```

### Admin Components
```css
/* Admin Layout */
.admin-layout { }
.admin-header { }
.admin-nav { }
.admin-main { }
.admin-sidebar { }

/* Admin UI Components */
.admin-card { }
.admin-table { }
.admin-button { }
.admin-form { }
.admin-stats { }
```

## 🔧 Build Process

### CSS Processing
1. **PostCSS** for modern CSS features
2. **Autoprefixer** for browser compatibility
3. **CSS Nano** for minification
4. **PurgeCSS** for unused style removal

### Development Workflow
```bash
# Development with hot reload
npm run dev

# Production build
npm run build

# Watch for changes
npm run watch
```

## 📋 Best Practices

### Performance
- Use CSS custom properties for theme values
- Minimize selector specificity
- Leverage cascade and inheritance
- Use `contain` property for layout optimization
- Implement critical CSS loading

### Maintainability
- Follow BEM naming conventions
- Keep components isolated and reusable
- Use meaningful class names
- Document complex selectors
- Regular architecture reviews

### Accessibility
- Ensure sufficient color contrast ratios
- Support reduced motion preferences
- Use semantic markup structure
- Implement focus management
- Test with assistive technologies

---

*For component examples and live demos, visit [Admin Style Guide](/admin/docs)*