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

/* 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

/* 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

/* 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

/* Block */
.card { }

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

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

Component States

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

📱 Responsive Design

Breakpoints

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

Media Query Mixins

@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

/* 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

/* 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

# 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