michaelschiemer/backups/docs-backup-20250731125004/design-system/admin/overview.md

Admin Design System

Comprehensive design system for administrative interfaces with modern UI patterns, accessibility standards, and developer efficiency.

🎯 Design Principles

User Experience

• Clarity First - Information hierarchy and visual clarity over decoration
• Efficiency - Minimize cognitive load and interaction friction
• Consistency - Predictable patterns and behaviors across all interfaces
• Accessibility - WCAG 2.1 AA compliance and inclusive design

Technical Excellence

• Performance - Fast load times and smooth interactions
• Maintainability - Modular, reusable components
• Scalability - Adaptable to growing feature requirements
• Developer Experience - Clear documentation and easy implementation

🎨 Visual Language

Color System

/* Primary Admin Palette */
--admin-primary: #6366f1;        /* Indigo - Primary actions */
--admin-primary-hover: #5855eb;  /* Hover states */
--admin-primary-active: #4f46e5; /* Active states */
--admin-primary-light: #a5b4fc;  /* Backgrounds */

/* Semantic Colors */
--admin-success: #10b981;        /* Success states */
--admin-warning: #f59e0b;        /* Warning states */
--admin-error: #ef4444;          /* Error states */
--admin-info: #3b82f6;           /* Information */

/* Neutral System */
--admin-gray-50: #f8fafc;        /* Lightest backgrounds */
--admin-gray-100: #f1f5f9;       /* Light backgrounds */
--admin-gray-200: #e2e8f0;       /* Borders */
--admin-gray-300: #cbd5e1;       /* Disabled states */
--admin-gray-400: #94a3b8;       /* Placeholders */
--admin-gray-500: #64748b;       /* Secondary text */
--admin-gray-600: #475569;       /* Primary text */
--admin-gray-700: #334155;       /* Headings */
--admin-gray-800: #1e293b;       /* Dark text */
--admin-gray-900: #0f172a;       /* Darkest elements */

/* Dark Theme */
--admin-dark-bg: #0f172a;
--admin-dark-surface: #1e293b;
--admin-dark-border: #334155;
--admin-dark-text: #f1f5f9;

Typography

/* Font Stacks */
--admin-font-sans: 'Inter', system-ui, -apple-system, sans-serif;
--admin-font-mono: 'SF Mono', 'Monaco', 'Cascadia Code', monospace;

/* Type Scale */
--admin-text-xs: 0.75rem;     /* 12px - Small labels */
--admin-text-sm: 0.875rem;    /* 14px - Body text */
--admin-text-base: 1rem;      /* 16px - Default */
--admin-text-lg: 1.125rem;    /* 18px - Large body */
--admin-text-xl: 1.25rem;     /* 20px - Small headings */
--admin-text-2xl: 1.5rem;     /* 24px - Section headings */
--admin-text-3xl: 1.875rem;   /* 30px - Page titles */
--admin-text-4xl: 2.25rem;    /* 36px - Large titles */

/* Font Weights */
--admin-font-light: 300;
--admin-font-normal: 400;
--admin-font-medium: 500;
--admin-font-semibold: 600;
--admin-font-bold: 700;

Spacing System

/* 4px base unit scaling */
--admin-space-0: 0;
--admin-space-1: 0.25rem;     /* 4px */
--admin-space-2: 0.5rem;      /* 8px */
--admin-space-3: 0.75rem;     /* 12px */
--admin-space-4: 1rem;        /* 16px */
--admin-space-5: 1.25rem;     /* 20px */
--admin-space-6: 1.5rem;      /* 24px */
--admin-space-8: 2rem;        /* 32px */
--admin-space-10: 2.5rem;     /* 40px */
--admin-space-12: 3rem;       /* 48px */
--admin-space-16: 4rem;       /* 64px */
--admin-space-20: 5rem;       /* 80px */
--admin-space-24: 6rem;       /* 96px */

Elevation & Shadows

/* Shadow System */
--admin-shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
--admin-shadow-base: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06);
--admin-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
--admin-shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
--admin-shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);

/* Border Radius */
--admin-radius-none: 0;
--admin-radius-sm: 0.125rem;   /* 2px */
--admin-radius-base: 0.25rem;  /* 4px */
--admin-radius-md: 0.375rem;   /* 6px */
--admin-radius-lg: 0.5rem;     /* 8px */
--admin-radius-xl: 0.75rem;    /* 12px */
--admin-radius-2xl: 1rem;      /* 16px */
--admin-radius-full: 9999px;   /* Pill shape */

🏗 Layout System

Grid Foundation

/* Admin Layout Grid */
.admin-layout {
  display: grid;
  grid-template-areas: 
    "header header"
    "nav main"
    "nav footer";
  grid-template-columns: 250px 1fr;
  grid-template-rows: auto 1fr auto;
  min-height: 100vh;
}

.admin-header { grid-area: header; }
.admin-nav { grid-area: nav; }
.admin-main { grid-area: main; }
.admin-footer { grid-area: footer; }

/* Responsive Adaptations */
@media (max-width: 768px) {
  .admin-layout {
    grid-template-areas: 
      "header"
      "main"
      "footer";
    grid-template-columns: 1fr;
  }
  
  .admin-nav {
    transform: translateX(-100%);
    transition: transform 0.3s ease;
  }
  
  .admin-nav.is-open {
    transform: translateX(0);
  }
}

Content Layout

/* Page Structure */
.page-header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: var(--admin-space-6) 0;
  border-bottom: 1px solid var(--admin-gray-200);
  margin-bottom: var(--admin-space-6);
}

.page-content {
  max-width: none;
  padding: 0;
}

/* Content Sections */
.admin-section {
  background: var(--admin-surface);
  border: 1px solid var(--admin-border);
  border-radius: var(--admin-radius-lg);
  padding: var(--admin-space-6);
  margin-bottom: var(--admin-space-6);
}

.admin-section + .admin-section {
  margin-top: var(--admin-space-8);
}

🧩 Component Architecture

Base Component Classes

/* Button System */
.admin-button {
  display: inline-flex;
  align-items: center;
  gap: var(--admin-space-2);
  padding: var(--admin-space-2) var(--admin-space-4);
  border: 1px solid transparent;
  border-radius: var(--admin-radius-md);
  font-family: var(--admin-font-sans);
  font-size: var(--admin-text-sm);
  font-weight: var(--admin-font-medium);
  line-height: 1.5;
  text-decoration: none;
  cursor: pointer;
  transition: all 0.15s ease;
  
  &:focus {
    outline: 2px solid var(--admin-primary);
    outline-offset: 2px;
  }
  
  &:disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }
}

/* Button Variants */
.admin-button--primary {
  background: var(--admin-primary);
  color: white;
  
  &:hover:not(:disabled) {
    background: var(--admin-primary-hover);
  }
}

.admin-button--secondary {
  background: var(--admin-gray-100);
  color: var(--admin-gray-700);
  border-color: var(--admin-gray-200);
  
  &:hover:not(:disabled) {
    background: var(--admin-gray-200);
  }
}

.admin-button--ghost {
  background: transparent;
  color: var(--admin-gray-600);
  
  &:hover:not(:disabled) {
    background: var(--admin-gray-100);
  }
}

Form Components

/* Input System */
.admin-input {
  display: block;
  width: 100%;
  padding: var(--admin-space-3);
  border: 1px solid var(--admin-gray-300);
  border-radius: var(--admin-radius-md);
  font-family: var(--admin-font-sans);
  font-size: var(--admin-text-sm);
  line-height: 1.5;
  background: white;
  transition: all 0.15s ease;
  
  &:focus {
    outline: none;
    border-color: var(--admin-primary);
    box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.1);
  }
  
  &:disabled {
    background: var(--admin-gray-50);
    color: var(--admin-gray-400);
    cursor: not-allowed;
  }
  
  &.is-error {
    border-color: var(--admin-error);
    
    &:focus {
      box-shadow: 0 0 0 3px rgba(239, 68, 68, 0.1);
    }
  }
}

/* Form Groups */
.admin-form-group {
  margin-bottom: var(--admin-space-4);
}

.admin-label {
  display: block;
  margin-bottom: var(--admin-space-2);
  font-size: var(--admin-text-sm);
  font-weight: var(--admin-font-medium);
  color: var(--admin-gray-700);
}

.admin-help-text {
  margin-top: var(--admin-space-1);
  font-size: var(--admin-text-xs);
  color: var(--admin-gray-500);
}

.admin-error-text {
  margin-top: var(--admin-space-1);
  font-size: var(--admin-text-xs);
  color: var(--admin-error);
}

Data Display Components

/* Stats Cards */
.admin-stats-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  gap: var(--admin-space-6);
  margin-bottom: var(--admin-space-8);
}

.admin-stat-card {
  background: var(--admin-surface);
  border: 1px solid var(--admin-border);
  border-radius: var(--admin-radius-lg);
  padding: var(--admin-space-6);
  
  &:hover {
    border-color: var(--admin-primary-light);
    transform: translateY(-1px);
    box-shadow: var(--admin-shadow-md);
  }
}

.admin-stat-label {
  display: block;
  font-size: var(--admin-text-sm);
  font-weight: var(--admin-font-medium);
  color: var(--admin-gray-600);
  margin-bottom: var(--admin-space-2);
}

.admin-stat-value {
  font-size: var(--admin-text-3xl);
  font-weight: var(--admin-font-bold);
  color: var(--admin-gray-900);
  line-height: 1;
}

.admin-stat-trend {
  margin-top: var(--admin-space-2);
  font-size: var(--admin-text-xs);
  
  &.is-positive { color: var(--admin-success); }
  &.is-negative { color: var(--admin-error); }
  &.is-neutral { color: var(--admin-gray-500); }
}

Tables

/* Admin Tables */
.admin-table {
  width: 100%;
  border-collapse: separate;
  border-spacing: 0;
  background: var(--admin-surface);
  border: 1px solid var(--admin-border);
  border-radius: var(--admin-radius-lg);
  overflow: hidden;
}

.admin-table th {
  background: var(--admin-gray-50);
  padding: var(--admin-space-4);
  text-align: left;
  font-size: var(--admin-text-xs);
  font-weight: var(--admin-font-semibold);
  color: var(--admin-gray-600);
  text-transform: uppercase;
  letter-spacing: 0.05em;
  border-bottom: 1px solid var(--admin-border);
  
  &[data-sort] {
    cursor: pointer;
    user-select: none;
    
    &:hover {
      background: var(--admin-gray-100);
    }
    
    &.is-sorted-asc::after {
      content: " ↑";
      color: var(--admin-primary);
    }
    
    &.is-sorted-desc::after {
      content: " ↓";
      color: var(--admin-primary);
    }
  }
}

.admin-table td {
  padding: var(--admin-space-4);
  border-bottom: 1px solid var(--admin-gray-100);
  font-size: var(--admin-text-sm);
  color: var(--admin-gray-700);
}

.admin-table tbody tr:hover {
  background: var(--admin-gray-50);
}

.admin-table tbody tr:last-child td {
  border-bottom: none;
}

🌓 Dark Mode Support

/* Dark Theme Variables */
[data-theme="dark"] {
  --admin-surface: var(--admin-dark-surface);
  --admin-border: var(--admin-dark-border);
  --admin-text: var(--admin-dark-text);
  --admin-bg: var(--admin-dark-bg);
  
  /* Component Adaptations */
  --admin-gray-50: #334155;
  --admin-gray-100: #475569;
  --admin-gray-200: #64748b;
  --admin-gray-600: #cbd5e1;
  --admin-gray-700: #e2e8f0;
  --admin-gray-900: var(--admin-dark-text);
}

/* Theme Toggle Component */
.admin-theme-toggle {
  position: relative;
  width: 48px;
  height: 24px;
  background: var(--admin-gray-200);
  border: none;
  border-radius: var(--admin-radius-full);
  cursor: pointer;
  transition: background 0.2s ease;
  
  &::after {
    content: '';
    position: absolute;
    top: 2px;
    left: 2px;
    width: 20px;
    height: 20px;
    background: white;
    border-radius: 50%;
    transition: transform 0.2s ease;
  }
  
  &.is-dark {
    background: var(--admin-primary);
    
    &::after {
      transform: translateX(24px);
    }
  }
}

♿ Accessibility Standards

Focus Management

/* Focus Styles */
.admin-focus-visible {
  outline: 2px solid var(--admin-primary);
  outline-offset: 2px;
  border-radius: var(--admin-radius-sm);
}

/* Skip Links */
.admin-skip-link {
  position: absolute;
  top: -40px;
  left: 6px;
  background: var(--admin-primary);
  color: white;
  padding: 8px;
  text-decoration: none;
  border-radius: var(--admin-radius-md);
  z-index: 1000;
  
  &:focus {
    top: 6px;
  }
}

ARIA Support

<!-- Navigation with proper ARIA -->
<nav class="admin-nav" role="navigation" aria-label="Main navigation">
  <ul role="menubar">
    <li role="none">
      <a href="/admin" role="menuitem" aria-current="page">Dashboard</a>
    </li>
  </ul>
</nav>

<!-- Data tables with proper headers -->
<table class="admin-table" role="table" aria-label="User data">
  <thead>
    <tr role="row">
      <th role="columnheader" aria-sort="ascending">Name</th>
      <th role="columnheader">Email</th>
    </tr>
  </thead>
  <tbody role="rowgroup">
    <tr role="row">
      <td role="gridcell">John Doe</td>
      <td role="gridcell">john@example.com</td>
    </tr>
  </tbody>
</table>

📱 Responsive Behavior

Breakpoint System

/* Mobile First Breakpoints */
.admin-responsive {
  /* Mobile (default) */
  padding: var(--admin-space-4);
  
  /* Tablet */
  @media (min-width: 768px) {
    padding: var(--admin-space-6);
  }
  
  /* Desktop */
  @media (min-width: 1024px) {
    padding: var(--admin-space-8);
  }
  
  /* Large Desktop */
  @media (min-width: 1280px) {
    padding: var(--admin-space-12);
  }
}

/* Navigation Adaptations */
@media (max-width: 767px) {
  .admin-nav {
    position: fixed;
    top: 0;
    left: 0;
    width: 280px;
    height: 100vh;
    background: var(--admin-surface);
    border-right: 1px solid var(--admin-border);
    transform: translateX(-100%);
    transition: transform 0.3s ease;
    z-index: 1000;
    
    &.is-open {
      transform: translateX(0);
    }
  }
  
  .admin-nav-overlay {
    position: fixed;
    top: 0;
    left: 0;
    width: 100vw;
    height: 100vh;
    background: rgba(0, 0, 0, 0.5);
    opacity: 0;
    visibility: hidden;
    transition: all 0.3s ease;
    z-index: 999;
    
    &.is-active {
      opacity: 1;
      visibility: visible;
    }
  }
}

---

For implementation examples, see Admin Components
For JavaScript integration, see JavaScript Modules
For performance guidelines, see CSS Architecture