michaelschiemer/docs/admin-design-system.md

# Admin Design System Documentation

**Version**: 1.0.0
**Last Updated**: 2025-10-19
**Status**: Production Ready ✅

## Overview

Das Admin Design System ist eine vollständig framework-kompatible, WCAG 2.1 AA konforme Design-Implementierung für die Admin-Oberfläche des Custom PHP Frameworks.

### Kernmerkmale

- ✅ **ITCSS Architecture** - 7-Layer CSS-Struktur für Skalierbarkeit
- ✅ **OKLCH Color Space** - Moderne perzeptive Farben für konsistentes Dark Mode
- ✅ **Framework-Compatible** - Nutzt `DesignToken`, `CssColor`, `LinkCollection` VOs
- ✅ **WCAG 2.1 AA Compliant** - Alle Kontraste ≥ 4.5:1 für normalen Text
- ✅ **Mobile-First** - Progressive enhancement von mobile → desktop
- ✅ **Dark Mode** - System preference + manueller Toggle
- ✅ **Accessibility First** - Skip links, ARIA, keyboard navigation

## File Structure

```
resources/css/admin/
├── admin.css                              # Main entry point
├── 01-settings/
│   ├── _tokens.css                        # Design Tokens (217 lines)
│   └── _breakpoints.css                   # Responsive breakpoints (97 lines)
├── 02-tools/
│   └── _mixins.css                        # CSS mixins/helpers
├── 03-generic/
│   └── _reset.css                         # CSS reset
├── 04-elements/
│   └── _base.css                          # HTML element styles
├── 05-objects/
│   ├── _layout.css                        # Core layout grid (199 lines)
│   └── _grid.css                          # Grid utilities (136 lines)
├── 06-components/
│   ├── _sidebar.css                       # Sidebar navigation (230 lines)
│   ├── _header.css                        # Header with search (267 lines)
│   ├── _breadcrumbs.css                   # Breadcrumb navigation (125 lines)
│   └── _content.css                       # Content area (298 lines)
├── 07-utilities/
│   ├── _accessibility.css                 # WCAG utilities (289 lines)
│   └── _theme-transitions.css             # Dark mode transitions (110 lines)
├── contrast-analysis.md                   # WCAG contrast analysis
└── dark-mode-test-guide.md               # Dark mode testing guide

src/Application/Admin/
├── ValueObjects/
│   ├── AdminTheme.php                     # Theme VO (implements Framework\Design\Theme)
│   └── AdminTokenRegistry.php             # Design token registry (349 lines)
└── templates/
    ├── layouts/
    │   └── admin.view.php                 # Main admin layout
    └── components/
        ├── sidebar.component.php          # Sidebar navigation
        ├── header.component.php           # Header component
        └── breadcrumbs.component.php      # Breadcrumbs (uses LinkCollection)

src/Framework/Design/
├── Theme.php                              # Generic Theme interface
└── ValueObjects/
    └── ThemeMode.php                      # Theme mode enum (LIGHT, DARK, AUTO)
```

## Design Tokens

### Color System (OKLCH)

**Light Mode**:
```css
--admin-bg-primary: oklch(98% 0.01 280);          /* Near white background */
--admin-content-text: oklch(20% 0.02 280);        /* Dark text (16.7:1 contrast) */
--admin-sidebar-bg: oklch(25% 0.02 280);          /* Dark sidebar */
--admin-sidebar-text: oklch(90% 0.01 280);        /* Light text (12.5:1 contrast) */
--admin-accent-primary: oklch(60% 0.2 280);       /* Primary blue */
--admin-accent-success: oklch(58% 0.22 145);      /* Green (4.8:1 contrast) */
--admin-accent-warning: oklch(62% 0.22 85);       /* Yellow (4.6:1 contrast) */
--admin-accent-error: oklch(60% 0.25 25);         /* Red (4.7:1 contrast) */
```

**Dark Mode** (auto-switches via `prefers-color-scheme: dark`):
```css
--admin-bg-primary: oklch(20% 0.02 280);          /* Dark background */
--admin-content-text: oklch(90% 0.01 280);        /* Light text (12.5:1 contrast) */
--admin-sidebar-bg: oklch(15% 0.02 280);          /* Darker sidebar */
--admin-sidebar-text: oklch(75% 0.02 280);        /* Medium-light text (8.9:1 contrast) */
--admin-link-color: oklch(70% 0.2 260);           /* Brighter blue (6.2:1 contrast) */
```

**WCAG AA Compliance**:
- ✅ Normal Text: All combinations ≥ 4.5:1
- ✅ Large Text: All combinations ≥ 3:1
- ✅ UI Components: All borders ≥ 3:1

### Spacing System

```css
--admin-spacing-xs: 0.25rem;     /* 4px */
--admin-spacing-sm: 0.5rem;      /* 8px */
--admin-spacing-md: 1rem;        /* 16px */
--admin-spacing-lg: 1.5rem;      /* 24px */
--admin-spacing-xl: 2rem;        /* 32px */
--admin-spacing-2xl: 3rem;       /* 48px */
```

### Typography System

```css
--admin-font-family-base: system-ui, -apple-system, "Segoe UI", ...;
--admin-font-family-mono: "SF Mono", Monaco, "Cascadia Code", ...;

--admin-font-size-xs: 0.75rem;   /* 12px */
--admin-font-size-sm: 0.875rem;  /* 14px */
--admin-font-size-base: 1rem;    /* 16px */
--admin-font-size-lg: 1.125rem;  /* 18px */
--admin-font-size-xl: 1.25rem;   /* 20px */

--admin-font-weight-normal: 400;
--admin-font-weight-medium: 500;
--admin-font-weight-semibold: 600;
--admin-font-weight-bold: 700;
```

### Shadow System

```css
--admin-shadow-sm: 0 1px 2px 0 oklch(0% 0 0 / 0.05);
--admin-shadow-md: 0 4px 6px -1px oklch(0% 0 0 / 0.1), 0 2px 4px -1px oklch(0% 0 0 / 0.06);
--admin-shadow-lg: 0 10px 15px -3px oklch(0% 0 0 / 0.1), 0 4px 6px -2px oklch(0% 0 0 / 0.05);
--admin-shadow-xl: 0 20px 25px -5px oklch(0% 0 0 / 0.1), 0 10px 10px -5px oklch(0% 0 0 / 0.04);
```

## Responsive Breakpoints

**Mobile-First Approach**:
```css
/* Base: Mobile (default, no media query) */
@media (--admin-tablet) { }     /* ≥ 768px */
@media (--admin-desktop) { }    /* ≥ 1024px */
@media (--admin-wide) { }       /* ≥ 1440px */

/* Mobile-specific */
@media (--admin-mobile-only) { }  /* < 768px */
```

## Component Usage

### Sidebar Navigation

**Template**: `src/Application/Admin/templates/components/sidebar.component.php`

**Data Requirements**:
```php
[
    'user' => $user,              // User VO with name, avatar, role
    'current_path' => '/admin/dashboard'  // Current route path for active state
]
```

**Features**:
- Collapsible sections with `admin-nav__section`
- Active link detection via `aria-current="page"`
- Mobile off-canvas menu
- User footer with avatar

### Header Component

**Template**: `src/Application/Admin/templates/components/header.component.php`

**Data Requirements**:
```php
[
    'page_title' => 'Dashboard',
    'breadcrumbs' => LinkCollection::fromUrlsAndTexts([...]),  // Framework VO
    'user' => $user,
    'notification_count' => 5
]
```

**Features**:
- Search bar with icon
- Notification badge
- Theme toggle (light/dark/auto)
- User dropdown menu

### Breadcrumbs

**Template**: `src/Application/Admin/templates/components/breadcrumbs.component.php`

**Data Requirements**:
```php
[
    'breadcrumbs' => LinkCollection::fromUrlsAndTexts([
        ['url' => '/admin/users', 'text' => 'Users'],
        ['url' => '/admin/users/123', 'text' => 'User Details', 'current' => true]
    ])
]
```

**Framework Integration**:
- Uses `LinkCollection` Value Object from `src/Framework/Core/ValueObjects/LinkCollection.php`
- Supports `HtmlLink` and `AccessibleLink` (with `aria-current`)
- Schema.org markup via `toBreadcrumbs()` method

## Dark Mode Implementation

### Automatic Detection

**System Preference**:
```javascript
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)');
prefersDark.addEventListener('change', (e) => {
    if (savedTheme === 'auto') {
        htmlElement.dataset.theme = e.matches ? 'dark' : 'light';
    }
});
```

### Manual Toggle

**Theme Cycle**: light → dark → auto → light

**Persistence**:
```javascript
localStorage.setItem('admin-theme-preference', 'dark');
```

**Data Attribute**:
```html
<html data-theme="dark">  <!-- Applied to <html> element -->
```

### CSS Detection

```css
/* System preference */
@media (prefers-color-scheme: dark) {
    :root { --admin-bg-primary: oklch(20% 0.02 280); }
}

/* Manual override */
[data-theme="dark"] {
    --admin-bg-primary: oklch(20% 0.02 280);
}
```

## Accessibility Features

### Keyboard Navigation

**Skip Link**:
```html
<a href="#main-content" class="admin-skip-link">Skip to main content</a>
```

**Focus Indicators**:
- 2px outline with `--admin-focus-ring` color
- 3:1 contrast ratio minimum
- `:focus-visible` for keyboard-only focus

### Screen Reader Support

**Utility Classes**:
```css
.sr-only                  /* Visually hidden, accessible to screen readers */
.admin-sr-only           /* Admin-specific variant */
.visually-hidden         /* Alternative naming */
```

**ARIA Attributes**:
```html
<nav aria-label="Main navigation">
<button aria-expanded="false" aria-haspopup="true">
<span aria-current="page">
```

### Reduced Motion

Automatically disables animations for users with motion sensitivity:
```css
@media (prefers-reduced-motion: reduce) {
    *, *::before, *::after {
        animation-duration: 0.01ms !important;
        transition-duration: 0.01ms !important;
    }
}
```

### Touch Target Size

Minimum 44x44px for mobile touch targets:
```css
@media (pointer: coarse) {
    button, a { min-width: 44px; min-height: 44px; }
}
```

## Framework Integration

### Theme Value Object

**Interface Implementation**:
```php
final readonly class AdminTheme implements Theme
{
    public static function light(): self;
    public static function dark(): self;
    public static function auto(): self;

    public function getMode(): ThemeMode;
    public function toDataAttribute(): string;
    public function toCssClass(): string;
    public function requiresPreferenceDetection(): bool;
}
```

**Usage in Controller**:
```php
$theme = AdminTheme::auto();
return new ViewResult(
    template: 'layouts/admin',
    data: ['theme' => $theme->getMode()->value]
);
```

### Design Token Registry

**AdminTokenRegistry** manages all design tokens:
```php
final readonly class AdminTokenRegistry
{
    public function getColorTokens(): array;
    public function getSpacingTokens(): array;
    public function getTypographyTokens(): array;
    public function toCss(): string;              // Light mode CSS
    public function toDarkModeCss(): string;      // Dark mode overrides
}
```

**Framework DesignToken Integration**:
```php
$tokens = [
    'admin-bg-primary' => DesignToken::color(
        'admin-bg-primary',
        new CssColor('oklch(98% 0.01 280)', ColorFormat::OKLCH),
        'Primary background color'
    )
];
```

## Performance Considerations

### CSS File Size

- **Unminified**: ~25KB total
- **Gzipped**: ~5KB
- **Critical CSS**: Inline first ~2KB for above-fold

### Theme Switching

- **Switch Time**: <50ms (CSS variable change only)
- **No Re-render**: Pure CSS, no HTML changes
- **Smooth Transition**: 0.2s color transition (respects reduced motion)

### Browser Support

**OKLCH Color Space**:
- ✅ Chrome 111+ (March 2023)
- ✅ Firefox 113+ (May 2023)
- ✅ Safari 15.4+ (March 2022)
- ⚠️ Edge 111+ (March 2023)

**Fallback Strategy**: Modern browsers (2023+) have full support. For legacy browsers, consider RGB fallbacks in critical paths.

## Testing Checklist

### Before Deployment

- [ ] All contrast ratios verified (Lighthouse accessibility audit ≥ 90)
- [ ] Keyboard navigation tested (Tab, Shift+Tab, Enter, Esc)
- [ ] Screen reader tested (VoiceOver/NVDA/JAWS)
- [ ] Dark mode tested on actual devices (desktop, mobile, tablet)
- [ ] Cross-browser testing (Chrome, Firefox, Safari, Edge)
- [ ] Reduced motion tested (OS settings enabled)
- [ ] High contrast mode tested (Windows High Contrast)
- [ ] Print styles verified (force light theme, remove shadows)
- [ ] Touch targets verified on mobile (minimum 44x44px)

### Performance Benchmarks

- [ ] Theme switch < 50ms
- [ ] First Contentful Paint < 1.5s
- [ ] Largest Contentful Paint < 2.5s
- [ ] Cumulative Layout Shift < 0.1
- [ ] No Flash of Unstyled Content (FOUC)

## Troubleshooting

### Dark Mode Not Applying

**Issue**: Dark mode colors not showing
**Solutions**:
1. Check `localStorage.getItem('admin-theme-preference')`
2. Verify `<html data-theme>` attribute is set
3. Inspect CSS custom properties in DevTools
4. Clear browser cache and hard reload

### Colors Look Different Across Browsers

**Issue**: OKLCH colors appear different
**Solutions**:
1. Verify browser supports OKLCH (2023+)
2. Check monitor color profile calibration
3. Test with multiple displays
4. Consider RGB fallbacks for legacy support

### Contrast Issues

**Issue**: Text hard to read
**Solutions**:
1. Use contrast checker tools (WebAIM)
2. Verify against `contrast-analysis.md`
3. Adjust lightness (L) value in OKLCH
4. Test with actual visually impaired users

### Theme Toggle Not Working

**Issue**: Theme doesn't change on click
**Solutions**:
1. Check browser console for JavaScript errors
2. Verify `[data-theme-toggle]` attribute present
3. Test `localStorage.setItem()` permissions
4. Check if multiple theme toggle buttons exist

## Contributing

### Adding New Components

1. **Create CSS file**: `06-components/_new-component.css`
2. **Import in admin.css**: `@import "./06-components/_new-component.css";`
3. **Follow BEM naming**: `.admin-component__element--modifier`
4. **Use design tokens**: Reference `--admin-*` variables only
5. **Ensure WCAG AA**: Test contrast ratios before commit

### Modifying Design Tokens

1. **Update `_tokens.css`**: Change CSS custom property
2. **Update both themes**: Light mode + dark mode + manual overrides
3. **Verify contrast**: Run contrast analysis
4. **Update documentation**: This file and `contrast-analysis.md`
5. **Test thoroughly**: All components using the token

### Adding New Utilities

1. **Create utility file**: `07-utilities/_new-utility.css`
2. **Use `@layer admin-utilities`**: Ensure correct cascade order
3. **Document usage**: Add examples to this file
4. **Test accessibility**: Verify screen reader, keyboard navigation

## References

- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [OKLCH Color Picker](https://oklch.com/)
- [ITCSS Architecture](https://www.xfive.co/blog/itcss-scalable-maintainable-css-architecture/)
- [Framework Design Module](src/Framework/Design/)
- [Contrast Analysis](resources/css/admin/contrast-analysis.md)
- [Dark Mode Test Guide](resources/css/admin/dark-mode-test-guide.md)

---

**Documentation Version**: 1.0.0
**Framework Version**: Custom PHP Framework
**CSS Architecture**: ITCSS with 7 layers
**Color Space**: OKLCH
**Accessibility Standard**: WCAG 2.1 AA
**Browser Support**: Modern browsers (2023+)
**Maintainer**: Development Team