Styling System

Complete styling system - theme management, glass effects, dynamic wallpapers, interface sizes, and design guidelines

Styling System

Introduction

Styling system with theme management, glass effects, wallpapers, and interface sizes. Windows 11-inspired glassmorphism. Integrates with React contexts, Redux, and Tailwind CSS.

Theme System

Overview

Three modes: light, dark, system (OS preference). Persisted in cookies (1-year), matchMedia API for system detection, inline script prevents flash.

Files: src/utils/theme.js, src/contexts/ThemeProvider.jsx

Theme Utilities

Functions: isValidTheme, getSystemTheme, resolveTheme, applyTheme (adds/removes .dark class), createSystemThemeListener Cookie: getThemeFromCookie, setThemeCookie (Secure flag, 1-year), getInitialTheme (cookie → system → 'system') Color: generateColorScale (50-900), hexToHsl Flash Prevention: createThemeScript() (inline script for SSR)

ThemeProvider

Context: theme (user pref), resolvedTheme (light/dark), setTheme, toggleTheme Hooks: useAppTheme(), useTheme(), useResolvedTheme(), useThemeToggle() Props: defaultTheme, enableSystem, cookieString (SSR), onThemeChange

Brand Colors

Celeste #6ED0E0 (primary), Dark Blue #2B7FB8 (secondary), Sun #F59E42 (accent). Each has 50-900 color scale.

Semantic tokens: --background, --foreground, --card, --primary, --secondary, --accent, --muted, --border

Glass Effects System

Six effect types using CSS backdrop-filter. Files: src/utils/glass-effects.js, DESIGN_GUIDELINES.md

Effect Types

Type Usage Class Blur Opacity (L/D)
Mica Navigation mica 8px 0.95/0.9
Acrylic Headers, modals acrylic 24px + noise 0.75/0.7
Glass Subtle Secondary content glass-subtle 12px 0.9/0.8
Glass Medium Content cards glass-medium 20px 0.8/0.7
Glass Strong Hero sections glass-strong 30px 0.7/0.6
Glass Minimal Forms, inputs glass-minimal 8px 0.95

Utilities

Core: createGlassStyle, getMicaEffect, getAcrylicEffect Brand Tints: getCelesteGlass, getDarkBlueGlass, getSunGlass, getBrandGlassTint Elevation: getElevationShadow (5 levels), getBrandGlow, combineElevationAndGlow Responsive: getResponsiveGlass (size-aware), getFluentRadius Theme: getThemeGlass, getSemanticGlass Accessibility: supportsBackdropFilter, getFallbackGlass, shouldReduceTransparency Performance: optimizeGlassLayers, debounceGlassAnimation Classes: getGlassClasses, GLASS_PRESETS_EXPORT

Usage

Navigation: getMicaEffect('dark'), Content: createGlassStyle('medium'), Modals: getAcrylicEffect + getBrandGlow, Headers: class="glass-subtle", Forms: class="glass-minimal"

Accessibility

WCAG 4.5:1 text contrast, 3:1 interactive elements. Respect prefers-reduced-transparency. Provide fallback for unsupported browsers. Use appropriate effect for context, test over wallpapers.

Wallpaper System

Backend API integration with preloading, 5-min caching, theme-aware CSS variables. Files: src/utils/wallpaper.js, src/app/layout.js, DESIGN_GUIDELINES.md

API

Fetch: fetchAvailableWallpapers, getAvailableWallpapers (cached), refreshWallpapers Validation: validateWallpaperFile (10MB max, JPG/PNG/WebP/GIF) Preload: preloadWallpaper (prevents flash) CSS: updateWallpaperCSS (sets --wallpaper-url / --wallpaper-url-dark), formatWallpaperUrl Utils: getCategoryDisplayName, applyWallpaperWithTransition, resetToDefaultWallpaper

WallpaperApplier: Component in provider hierarchy, reads Redux appSettings.wallpaper, updates CSS on wallpaper/theme change

Categories: abstract, nature, minimal, gradient, geometric

Design for Wallpapers

Use glass effects for content separation (glass-medium/strong for cards, mica for nav, acrylic for headers/modals, glass-minimal for forms). Test with light/dark/busy/minimal wallpapers. WCAG 4.5:1 text contrast. Preload before applying to prevent flash.

Interface Size System

Four variants (sm, md, lg, xl) with CSS custom properties, Redux persistence. Files: src/components/ui/size-provider.jsx, DESIGN_GUIDELINES.md, src/app/layout.js

SizeProvider

Context: size, setSize, availableSizes, sizeLabels (Compact/Standard/Comfortable/Spacious), getSizeLabel, getNextSize, getPrevSize, isValidSize, CSS class utilities

Behavior: Applies size-{variant} class to <html>, generates CSS custom properties, warns if multiple providers

Props: size (controlled), defaultSize (md), children

Size Variants

sizeVariants[size][category][property] object with size-specific Tailwind classes.

Typography:

Size Main Heading Subheading Heading 2 Text Small
sm text-2xl sm:text-3xl lg:text-4xl text-lg sm:text-xl lg:text-2xl text-base sm:text-lg lg:text-xl text-sm text-xs
md text-3xl sm:text-4xl lg:text-5xl text-xl sm:text-2xl lg:text-3xl text-lg sm:text-xl lg:text-2xl text-base text-sm
lg text-4xl sm:text-5xl lg:text-6xl text-2xl sm:text-3xl lg:text-4xl text-xl sm:text-2xl lg:text-3xl text-lg text-base
xl text-5xl sm:text-6xl lg:text-7xl text-3xl sm:text-4xl lg:text-5xl text-2xl sm:text-3xl lg:text-4xl text-xl text-lg

Layout Spacing (from sizeVariants.{size}.layout and sizeVariants.{size}.spacing):

Size Section Container Card Grid Section Spacing
sm space-y-3 p-3 gap-3 mb-4
md space-y-4 p-4 gap-4 mb-6
lg space-y-6 p-6 gap-6 mb-8
xl space-y-8 p-8 gap-8 mb-10

Grid System (from sizeVariants.{size}.grid):

Size Department Grid Computers Settings
sm grid grid-cols-1 gap-3 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-3 gap-3
md grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 2xl:grid-cols-5 gap-4 gap-4
lg grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 2xl:grid-cols-6 gap-6 gap-6
xl grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-5 2xl:grid-cols-7 gap-8 gap-8

Component Dimensions (from sizeVariants.{size}.{component}):

Component sm md lg xl
Navbar width 16rem 18rem 20rem 24rem
Icon size w-4 h-4 w-5 h-5 w-6 h-6 w-7 h-7
Avatar w-8 h-8 w-10 h-10 w-12 h-12 w-14 h-14
Input height h-8 h-10 h-12 h-14
Card padding p-3 p-4 p-6 p-8
Badge text text-xs text-sm text-base text-lg
Border radius rounded-md rounded-md rounded-lg rounded-xl
Popover width w-56 w-64 w-72 w-80
Animation duration 250ms 300ms 350ms 400ms

CSS Custom Properties

The generateSizeCustomProperties() function converts Tailwind classes from sizeVariants into CSS custom properties applied to :root. These variables update dynamically when the size changes.

Typography Variables:

--size-text: Base text size
--size-heading: Heading text size
--size-mainheading: Main heading size
--size-subheading: Subheading size
--size-heading2: Secondary heading size
--size-small: Small text size
--size-xsmall: Extra small text size

Spacing Variables:

--size-padding: Base padding
--size-gap: Gap between elements
--size-container: Container padding
--size-item: Item padding
--size-sub-item: Sub-item padding
--size-margin-xs: Extra small margin
--size-margin-sm: Small margin
--size-space-x: Horizontal spacing

Dimension Variables:

--size-height: Base element height
--size-width: Base element width
--size-icon: Icon dimensions
--size-icon-button: Icon button dimensions
--size-icon-nav: Navigation icon dimensions
--size-icon-hero: Hero icon dimensions
--size-avatar: Avatar dimensions
--size-thumbnail: Thumbnail dimensions
--size-logo: Logo height

Component-Specific Variables:

/* Input */
--size-input-height: Input element height
--size-input-padding: Input padding
--size-input-text: Input text size
--size-input-with-icon-left-padding: Input padding with left icon

/* Badge */
--size-badge-size: Badge dimensions
--size-badge-text: Badge text size
--size-badge-padding: Badge padding

/* Card */
--size-card-padding: Card padding
--size-card-title: Card title size
--size-card-description: Card description size
--size-card-content: Card content padding
--size-card-footer: Card footer padding

/* Navbar */
--size-navbar-width: Navbar width
--size-navbar-mobile-width: Mobile navbar width
--size-navbar-padding: Navbar padding
--size-navbar-fixed-width: Fixed navbar width

/* Popover */
--size-popover-width: Popover width

Layout Variables:

--size-card-grid: Card grid gap
--size-section-spacing: Section spacing
--size-max-width: Maximum container width
--size-radius: Border radius

Animation Variables:

--size-animation-duration: Animation duration (e.g., 300ms for md)
--size-animation-easing: Animation easing function

Usage Patterns

Using sizeVariants Object (Recommended):

import { sizeVariants, useSizeContext } from '@/components/ui/size-provider'

function CardComponent() {
  const { size } = useSizeContext()
  const variant = sizeVariants[size]

  return (
    <div className={variant.card.padding}>
      <h1 className={variant.typography.mainheading}>Title</h1>
      <p className={variant.typography.text}>Body text</p>
    </div>
  )
}

Using Helper Functions:

import { getTypographyClass, getLayoutSpacing, useSizeContext } from '@/components/ui/size-provider'

function Navigation() {
  const { size } = useSizeContext()

  return (
    <nav>
      <div className={getLayoutSpacing('container', size)}>
        <h2 className={getTypographyClass('heading2', size)}>Navigation</h2>
      </div>
    </nav>
  )
}

Using Root Size Classes:

The SizeProvider adds a size-{variant} class to the document root. Use CSS selectors to target specific sizes:

/* Applied to <html> element */
.size-sm .custom-component {
  font-size: 0.875rem;
}

.size-md .custom-component {
  font-size: 1rem;
}

.size-lg .custom-component {
  font-size: 1.125rem;
}

.size-xl .custom-component {
  font-size: 1.25rem;
}

Using CSS Custom Properties:

function DynamicComponent() {
  return (
    <div style={{
      fontSize: 'var(--size-text)',
      padding: 'var(--size-padding)',
      borderRadius: 'var(--size-radius)'
    }}>
      Dynamic sizing via CSS variables
    </div>
  )
}

Conditional Logic:

import { useSizeContext } from '@/components/ui/size-provider'

function ResponsiveComponent() {
  const { size, getSizeLabel } = useSizeContext()

  return (
    <div>
      <p>Current size: {getSizeLabel()}</p>
      {size === 'xl' && <LargeOnlyComponent />}
      {size === 'sm' && <CompactView />}
    </div>
  )
}

Optional Pattern: data-size Attribute:

If you prefer data-size attributes for styling, you must set them explicitly:

import { useSizeContext } from '@/components/ui/size-provider'

function CustomComponent() {
  const { size } = useSizeContext()

  return (
    <div data-size={size} className="custom-component">
      Content adapts based on size
    </div>
  )
}

CSS:

[data-size="xl"] .custom-component {
  /* XL-specific styles */
}

Note: The data-size pattern requires manual implementation. The root size class (.size-{variant}) is automatically applied and recommended for most use cases.

SizeProvider Integration

SizeProviderWrapper (from layout.js):

function SizeProviderWrapper({ children }) {
  const settings = useSelector((state) => state.appSettings?.settings)
  const interfaceSize = settings?.interfaceSize || 'md'

  return (
    <SizeProvider size={interfaceSize}>
      {children}
    </SizeProvider>
  )
}

Integration Pattern:

  • Reads appSettings.settings.interfaceSize from Redux state
  • Provides size context to all child components via SizeProvider
  • Defaults to 'md' when settings not loaded
  • Automatically updates when Redux state changes

Best Practices

  • ✅ Use sizeVariants object for accessing size-specific classes (sizeVariants[size].card.padding)
  • ✅ Test all size variants for layout issues (sm, md, lg, xl)
  • ✅ Use CSS custom properties for dynamic scaling (var(--size-text))
  • ✅ Provide size toggle in settings UI
  • ✅ Use useSizeContext hook to access size state
  • ✅ Leverage root size classes for CSS styling (.size-md .component)
  • ❌ Don't hardcode dimensions - use sizeVariants or CSS variables
  • ❌ Don't forget responsive behavior - test all breakpoints
  • ❌ Don't mix size systems - use one approach consistently
  • ❌ Don't assume data-size attribute - it's not automatically set

Important Note on Size Alias Classes: Conceptual utility classes like text-size-h1, p-size-card, h-size-navbar, or rounded-size are not provided by the stock SizeProvider implementation. These would require a custom Tailwind plugin or additional stylesheet to generate. Instead, use the sizeVariants object (sizeVariants[size].card.padding), CSS custom properties (var(--size-card-padding)), or standard Tailwind classes.

Design Guidelines Reference

Overview

The comprehensive design system documentation (DESIGN_GUIDELINES.md) spans 1497 lines and covers all aspects of Infinibay's visual design. Version 2.0, last updated December 2024, serves as the single source of truth for design decisions, component patterns, and accessibility requirements.

Key Sections

Design Philosophy (from DESIGN_GUIDELINES.md):

  • Modern glassmorphism inspired by Windows 11
  • Clarity and readability over visual complexity
  • Accessibility as a core requirement (WCAG 2.1 AA)
  • Consistency across all interfaces
  • Performance-conscious design patterns
  • Adaptability to user preferences

Themes:

  • Dark/light/system mode architecture
  • Brand color definitions and scales
  • Semantic color token system
  • Theme transition patterns

Typography & Colors:

  • Six-level heading hierarchy
  • WCAG AA compliance requirements
  • Text color tokens for themes
  • Font sizing and line height scales

Size System:

  • Four size variant specifications (sm, md, lg, xl)
  • CSS class mapping reference
  • Usage patterns and examples
  • Component size configurations

Glass Effects System:

  • Six effect type specifications
  • Usage guidelines by context
  • Brand color integration patterns
  • Accessibility considerations

Readability & Contrast:

  • WCAG contrast standards
  • Contrast testing methodologies
  • Accessibility best practices
  • Reduced transparency support

Layout Guidelines:

  • Sidebar layout specifications
  • Header design patterns
  • Z-index hierarchy system
  • Page layout templates

Wallpaper Considerations:

  • Dynamic wallpaper challenges
  • Readability solutions
  • Glass effect recommendations
  • Testing guidelines

Content Management:

  • Scrollable content patterns
  • Virtualization strategies
  • Layered content organization
  • Custom scrollbar styling

Whitespace Management:

  • Spacing scale (0.5rem to 6rem)
  • Vertical rhythm principles
  • Visual hierarchy techniques
  • Responsive spacing

Settings & Style:

  • Style configuration UI
  • Wallpaper management interface
  • Accessibility settings
  • User preference persistence

Do's and Don'ts:

  • Best practices catalog
  • Common pitfalls to avoid
  • Decision-making guidelines
  • Anti-patterns

Conclusion & Quick Reference:

  • Essential imports
  • Key class reference
  • Testing checklist
  • Common patterns

WCAG Compliance

Text Contrast Requirements (from DESIGN_GUIDELINES.md "Readability & Contrast"):

Content Type Minimum Ratio Example
Normal text 4.5:1 Body text, paragraphs
Large text (18px+) 3:1 Headings, hero text
Interactive elements 3:1 Buttons, links, inputs
Graphical objects 3:1 Icons, charts

Color Accessibility:

  • ✅ Don't rely on color alone for information
  • ✅ Provide text labels for color-coded content
  • ✅ Use patterns or icons in addition to color
  • ✅ Test with color blindness simulators

Contrast Testing:

  • Use browser DevTools (Chrome, Firefox)
  • Online contrast checkers (WebAIM, Colorable)
  • Test all theme combinations
  • Verify against wallpaper backgrounds

Reduced Transparency:

  • Respect prefers-reduced-transparency media query
  • Provide high-opacity alternatives
  • Test accessibility settings integration
  • Document fallback behavior

Layout Patterns

Sidebar (from DESIGN_GUIDELINES.md "Layout Guidelines"):

// Sidebar specifications
{
  width: '240px',           // Expanded
  widthCollapsed: '64px',   // Collapsed
  effect: 'mica',           // Glass effect
  zIndex: 40,               // Above content
  responsive: {
    mobile: 'hidden',       // Hidden on <768px
    tablet: 'collapsible'   // Toggle button
  }
}

Header:

// Header specifications
{
  height: '64px',           // Fixed height
  effect: 'acrylic',        // Glass effect
  zIndex: 30,               // Below sidebar
  position: 'sticky',       // Sticky positioning
  top: 0
}

Z-Index Hierarchy:

Layer Z-Index Usage
Base content 0 Main page content
Sticky elements 10 Sticky headers, footers
Header 30 Page header
Sidebar 40 Navigation sidebar
Dropdown menus 50 Select menus, dropdowns
Modals 100 Dialog boxes, overlays
Toasts 200 Notifications, alerts

Page Layout (from DESIGN_GUIDELINES.md "Layout Guidelines"):

// Standard page layout
function PageLayout({ children }) {
  return (
    <div className="min-h-screen">
      <Header />
      <div className="flex">
        <Sidebar />
        <main className="flex-1 max-w-7xl mx-auto p-8">
          {children}
        </main>
      </div>
    </div>
  )
}

Note: This example uses standard Tailwind spacing (p-8). For size-responsive layouts, use sizeVariants[size].layout.container or CSS custom properties like var(--size-container).

Performance Considerations

Scrollable Content (from DESIGN_GUIDELINES.md "Content Management"):

  • ✅ Use virtualization for lists >100 items (react-window, react-virtuoso)
  • ✅ Implement progressive disclosure for large datasets
  • ✅ Lazy load images and heavy components
  • ✅ Debounce scroll event handlers
  • ❌ Don't render all items at once
  • ❌ Don't forget pagination for huge datasets

Custom Scrollbars:

/* Custom scrollbar styling */
.custom-scrollbar::-webkit-scrollbar {
  width: 8px;
}

.custom-scrollbar::-webkit-scrollbar-track {
  background: var(--background);
  border-radius: var(--size-radius);
}

.custom-scrollbar::-webkit-scrollbar-thumb {
  background: var(--primary);
  border-radius: var(--size-radius);
}

.custom-scrollbar::-webkit-scrollbar-thumb:hover {
  background: var(--primary-hover);
}

Layered Content:

  • ✅ Use tabs for related content (6-8 max)
  • ✅ Implement accordion patterns for collapsible sections
  • ✅ Provide clear navigation between layers
  • ✅ Maintain context when switching layers
  • ❌ Don't nest tabs more than 2 levels deep
  • ❌ Don't hide critical information in collapsed sections

Optimization:

  • ✅ Minimize backdrop-filter layers (max 3-4 per viewport)
  • ✅ Use will-change sparingly (memory impact)
  • ✅ Debounce glass effect animations (200ms)
  • ✅ Implement code splitting for large components
  • ❌ Don't animate backdrop-filter (performance intensive)
  • ❌ Don't apply glass effects to scrolling containers

Best Practices and Common Patterns

Theme Best Practices

Do's:

  • ✅ Use semantic color tokens (--primary, --secondary, --accent) instead of hardcoded values
  • ✅ Test both light and dark themes for contrast compliance (WCAG 2.1 AA)
  • ✅ Respect system preference by defaulting to 'system' mode
  • ✅ Provide theme toggle in accessible location (header/settings)
  • ✅ Use theme-aware components that adapt automatically
  • ✅ Flash prevention via inline script in <head>

Don'ts:

  • ❌ Don't hardcode colors - always use CSS variables
  • ❌ Don't assume user preference - check system first
  • ❌ Don't forget theme transitions - test switching experience
  • ❌ Don't skip contrast testing - verify all combinations
  • ❌ Don't ignore SSR hydration - use proper initialization

Glass Effects Best Practices

Do's:

  • ✅ Use appropriate effect for context (Mica for navigation, Acrylic for headers, Medium for content)
  • ✅ Ensure sufficient contrast (4.5:1 for text over glass)
  • ✅ Provide fallback for browsers without backdrop-filter
  • ✅ Respect reduced transparency (prefers-reduced-transparency)
  • ✅ Test over wallpapers (light, dark, busy, minimal)
  • ✅ Limit glass layers (3-4 max per viewport for performance)

Don'ts:

  • ❌ Don't overuse glass effects - performance degrades with many layers
  • ❌ Don't use low opacity for text-heavy content (use glass-minimal)
  • ❌ Don't animate backdrop-filter - extremely performance intensive
  • ❌ Don't forget accessibility - provide high-contrast alternatives
  • ❌ Don't skip browser testing - Safari, Firefox handle differently

Wallpaper Best Practices

Do's:

  • ✅ Preload wallpapers before applying (prevents flash)
  • ✅ Use glass effects for content over wallpapers (separation)
  • ✅ Test readability with various wallpaper types
  • ✅ Provide default wallpaper option (minimal, safe)
  • ✅ Cache wallpaper list for performance (5-minute TTL)
  • ✅ Validate file uploads (10MB max, JPG/PNG/WebP/GIF)

Don'ts:

  • ❌ Don't apply without preloading - causes flicker/flash
  • ❌ Don't use low-contrast text over busy wallpapers
  • ❌ Don't forget file size optimization - compress before upload
  • ❌ Don't skip error handling - gracefully handle load failures
  • ❌ Don't ignore theme switching - update wallpaper CSS on theme change

Size System Best Practices

Do's:

  • ✅ Use sizeVariants object for consistent sizing (sizeVariants[size].card.padding)
  • ✅ Test all size variants for layout issues (sm, md, lg, xl)
  • ✅ Use CSS custom properties for dynamic scaling (var(--size-text))
  • ✅ Provide size toggle in settings UI
  • ✅ Use useSizeContext hook to access size state and utilities
  • ✅ Leverage root size classes for CSS (.size-md .component)
  • ✅ Use helper functions like getTypographyClass() and getLayoutSpacing()

Don'ts:

  • ❌ Don't hardcode dimensions - use sizeVariants or CSS variables
  • ❌ Don't assume data-size attribute - it's not automatically set
  • ❌ Don't forget responsive behavior - test all breakpoints
  • ❌ Don't mix size systems - use one approach consistently
  • ❌ Don't skip accessibility - ensure all sizes are usable
  • ❌ Don't forget performance - avoid excessive re-renders

Integration Examples

Theme: Toggle button uses useAppTheme(), theme-aware components check resolvedTheme, SSR uses cookie with createThemeScript()

Glass: Cards use createGlassStyle('medium'), navigation uses getMicaEffect(theme), modals combine getAcrylicEffect + getBrandGlow

Wallpaper: Selector fetches with getAvailableWallpapers(), applies with applyWallpaperWithTransition(), upload validates with validateWallpaperFile()

Size: Components access sizeVariants[size], toggle dispatches Redux updateSettings({ interfaceSize }), CSS uses .size-{variant} root class

Troubleshooting

Theme Flash: Use createThemeScript() in <head> Theme Not Persisting: Check cookies, Secure flag (HTTPS only) System Theme Not Detected: Verify matchMedia support Hydration Mismatch: Pass cookieString to ThemeProvider

Glass Not Working: Check supportsBackdropFilter(), provide fallback Poor Performance: Reduce glass layers (max 3-4), don't animate backdrop-filter Low Contrast: Use glass-minimal (0.95 opacity) for text-heavy content Accessibility: Check shouldReduceTransparency(), provide solid fallback

Wallpaper Not Loading: Check API endpoint, handle errors Flash During Transition: Always preloadWallpaper() before applying Text Not Readable: Use glass-strong or semi-transparent overlay Cache Not Working: Check isWallpaperCacheValid(), use refreshWallpapers()

Size Classes Not Applying: Verify SizeProvider wraps component Layout Breaks: Use sizeVariants[size] or CSS variables, not hardcoded CSS Variables Not Working: Check getComputedStyle(document.documentElement).getPropertyValue('--size-text') Multiple Providers Warning: Use single SizeProvider at app root

Quick Reference

Essential Imports

// Theme
import { useAppTheme, useResolvedTheme, useThemeToggle } from '@/contexts/ThemeProvider'
import { createThemeScript, applyTheme, getSystemTheme } from '@/utils/theme'

// Glass Effects
import {
  createGlassStyle,
  getMicaEffect,
  getAcrylicEffect,
  getCelesteGlass,
  getElevationShadow,
  getBrandGlow
} from '@/utils/glass-effects'

// Wallpaper
import {
  getAvailableWallpapers,
  applyWallpaperWithTransition,
  preloadWallpaper,
  updateWallpaperCSS
} from '@/utils/wallpaper'

// Size
import { useSizeContext, useOptionalSizeContext, sizeVariants } from '@/components/ui/size-provider'

Key CSS Classes

/* Glass Effects */
.mica              /* Navigation, blur 8px, opacity 0.9 */
.acrylic           /* Headers, blur 24px, opacity 0.75 */
.glass-subtle      /* Subtle backgrounds, blur 12px, opacity 0.9 */
.glass-medium      /* Content cards, blur 20px, opacity 0.8 */
.glass-strong      /* Hero sections, blur 30px, opacity 0.7 */
.glass-minimal     /* Forms, blur 8px, opacity 0.95 */

/* Size Root Classes (applied to <html>) */
.size-sm           /* Compact size variant */
.size-md           /* Standard size variant (default) */
.size-lg           /* Comfortable size variant */
.size-xl           /* Spacious size variant */

Note: Size-specific classes (e.g., for typography, padding) are accessed via sizeVariants[size].{category}.{property}, not predefined CSS classes.

Testing Checklist

Theme Testing:

  • Test light theme contrast (WCAG AA)
  • Test dark theme contrast (WCAG AA)
  • Test system theme detection
  • Test theme toggle functionality
  • Test theme persistence across sessions
  • Test SSR hydration (no flash)

Glass Effects Testing:

  • Test all effect types (Mica, Acrylic, Subtle, Medium, Strong, Minimal)
  • Test readability over wallpapers
  • Test browser support (Safari, Firefox, Chrome)
  • Test reduced transparency mode
  • Test performance with multiple layers
  • Test fallback for unsupported browsers

Wallpaper Testing:

  • Test wallpaper loading and caching
  • Test preload functionality (no flash)
  • Test theme switching with wallpapers
  • Test upload validation (size, format)
  • Test error handling (network, invalid files)
  • Test all wallpaper categories

Size Testing:

  • Test all size variants (sm, md, lg, xl)
  • Test size persistence across sessions
  • Test responsive behavior at all sizes
  • Test component layouts at all sizes
  • Test typography scaling
  • Test spacing consistency
  • Test sizeVariants object access patterns
  • Test CSS custom properties update on size change

For more detailed information, refer to:

  • frontend/DESIGN_GUIDELINES.md - Complete design system documentation
  • frontend/src/utils/theme.js - Theme utilities and helper functions
  • frontend/src/utils/glass-effects.js - Glass effects utilities and presets
  • frontend/src/utils/wallpaper.js - Wallpaper API and management utilities
  • frontend/src/components/ui/size-provider.jsx - Size system provider and sizeVariants object
Previous
Frontend Architecture
Next
Button Components