Michael Schiemer
55a330b223
- Add DISCOVERY_LOG_LEVEL=debug - Add DISCOVERY_SHOW_PROGRESS=true - Temporary changes for debugging InitializerProcessor fixes on production
610 lines
14 KiB
Markdown
610 lines
14 KiB
Markdown
# 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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```css
|
|
/* 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
|
|
|
|
```html
|
|
<!-- 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
|
|
|
|
```css
|
|
/* 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](components.md)*
|
|
*For JavaScript integration, see [JavaScript Modules](../javascript.md)*
|
|
*For performance guidelines, see [CSS Architecture](../css-architecture.md)* |