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:

--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):

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

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

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

--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:

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

[
    '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:

[
    '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:

[
    '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:

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:

localStorage.setItem('admin-theme-preference', 'dark');

Data Attribute:

<html data-theme="dark">  <!-- Applied to <html> element -->

CSS Detection

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

<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:

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

ARIA Attributes:

<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:

@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:

@media (pointer: coarse) {
    button, a { min-width: 44px; min-height: 44px; }
}

Framework Integration

Theme Value Object

Interface Implementation:

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:

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

Design Token Registry

AdminTokenRegistry manages all design tokens:

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:

$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
• OKLCH Color Picker
• ITCSS Architecture
• Framework Design Module
• Contrast Analysis
• Dark Mode Test Guide

---

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