Appearance Settings

Appearance Settings

Component File: src/features/admin/components/Appearance.tsx Context: src/contexts/ThemeContext.tsx Access Level: All authenticated users Last Updated: March 5, 2026 Status: ✅ Production Ready

---

✨ Recent Updates

Custom Color Picker Upgraded (March 5, 2026)

• Color wheel now has an inner saturation-lightness square — users can drag inside the wheel to fine-tune color vibrancy and brightness, not just hue
• Outer ring: hue (0-360°), inner square: saturation (x-axis) + lightness (y-axis)
• Saturation and lightness values are persisted to localStorage and Supabase alongside hue
• Live preview updates in real-time as user drags either control
• Palette generation functions (generateLightPalette/generateDarkPalette) accept optional saturation/lightness overrides

Simple/Advanced Mode Removed (January 17, 2026)

• REMOVED the Simple/Advanced Interface Mode toggle
• Feature gating is now handled by user roles (position) at account creation
• See ROLE-TIER-IMPLEMENTATION-PLAN.md for the new role-based access system
• Positions: Director (full access), Bookkeeper (accounting focus), Assistant (limited), Custom (configurable)

UI Improvements (December 30, 2025)

• Changed Color Vision selector from 5 buttons to dropdown select
• Cleaner, more compact interface

Colorblind Accessibility Mode (December 29, 2025)

• Added Color Vision settings for colorblind users
• Five modes available:
• Normal - Standard color vision (default)
• Deuteranopia - Red-green colorblindness (most common, ~6% of males)
• Protanopia - Red-green colorblindness (red weakness)
• Tritanopia - Blue-yellow colorblindness (rare)
• Grayscale - Complete color blindness simulation
• Uses SVG filters for accurate color simulation
• Works with all light/dark themes independently
• Persisted to localStorage and Supabase

Hub View Mode (December 22, 2025)

• Added Tile View vs Icon View toggle for hub pages
• Tile View (default): 3-column card layout with title, description, and action link
• Icon View: 4-column compact grid with larger icons (48x48), title below, tooltip for description
• Persisted to localStorage and Supabase like other appearance settings
• Works on both desktop and mobile
• Created shared HubGrid component used by all 8 hub pages

Full Appearance Persistence to Database

• All appearance settings now sync to Supabase for cross-device persistence
• Settings stored in user_preferences.ui_preferences JSONB column
• Includes: mode, light theme, dark theme, text size, view mode, and color vision

---

Overview

The Appearance component allows users to customize the visual appearance of the application, including theme mode selection, theme variants, and text size preferences.

UI Features

Mode Selection

• Light Mode - Bright theme for daytime use
• Dark Mode - Dark theme for reduced eye strain
• System - Automatically follows OS preference

Light Theme Variants

• Organic - Warm earth tones (default)
• Sage - Soft green accents
• Cloud - Cool blue tones
• Custom - User-generated from color wheel

Dark Theme Variants

• Navy - Deep blue tones (default)
• Slate - Neutral gray tones
• Midnight - Pure dark theme
• Custom - User-generated from color wheel

Custom Color Picker

The custom theme option opens a dialog with:

• Outer hue ring — drag around the ring to select base hue (0-360°)
• Inner saturation-lightness square — drag inside to fine-tune:
• X-axis: Saturation (left = desaturated/gray, right = vivid/pure)
• Y-axis: Lightness (top = light, bottom = dark)
• Live preview — both light and dark mode previews update in real-time
• Color info — shows selected HSL values and the applied light/dark primary colors
• WCAG contrast ratios are automatically maintained regardless of S/L selection

Text Size

• Small - Compact text
• Normal - Default size
• Large - Increased readability
• Extra Large - Maximum accessibility

Color Vision (Colorblind Accessibility)

Dropdown selector with five options:

• Normal - Standard color vision (default)
• Deuteranopia - Red-green (most common)
• Protanopia - Red-green (red weakness)
• Tritanopia - Blue-yellow (rare)
• Grayscale - Complete color blindness

Hub View Mode

• Tiles (default) - Card layout with descriptions
• Icons - Compact icon grid with tooltips

Language (Moved)

Language selection lives in Settings → Preferences and is persisted alongside other user preferences.

Data Persistence

localStorage (Immediate)

Key: alignmint-appearance

{
  "mode": "dark",
  "lightTheme": "organic",
  "darkTheme": "navy",
  "textSize": "normal",
  "viewMode": "tile",
  "language": "en",
  "colorVision": "normal"
}

Supabase (Cross-Device Sync)

Table: user_preferences Column: ui_preferences (JSONB)

{
  "sidebarCollapsed": false,
  "appearance": {
    "mode": "dark",
    "lightTheme": "sage",
    "darkTheme": "midnight",
    "textSize": "large",
    "viewMode": "icon",
    "language": "en",
    "colorVision": "deuteranopia"
  }
}

Implementation Status

| Feature | Status |

|---------|--------|

| Mode toggle (Light/Dark/System) | ✅ Complete |

| System preference detection | ✅ Complete |

| Light theme variants | ✅ Complete |

| Dark theme variants | ✅ Complete |

| Text size selection | ✅ Complete |

| Hub view mode (Tile/Icon) | ✅ Complete |

| Language selection (i18n dropdown) | ✅ Complete (Settings → Preferences) |

| Color vision / Colorblind mode (dropdown) | ✅ Complete |

| Interface mode (Simple/Advanced) | ✅ Removed |

| localStorage persistence | ✅ Complete |

| Supabase sync | ✅ Complete |

Architecture

User changes appearance setting
    ↓
ThemeContext updates state
    ↓
Immediately saves to localStorage
    ↓
Debounced save to Supabase (1 second)
    ↓
On next login, loads from Supabase

Related Documentation

• ROLE-TIER-IMPLEMENTATION-PLAN.md - Role-based access system (replaces Simple/Advanced mode)
• I18N-IMPLEMENTATION.md - Historical internationalization notes

Technical Implementation

Color Vision Filters

Colorblind modes use SVG filters applied to the entire document via CSS:

[data-color-vision="deuteranopia"] {
  filter: url(#deuteranopia-filter);
}

SVG filter definitions are rendered by ColorVisionFilters.tsx component in App.tsx.

Key Files

| File | Purpose |

|------|--------|

| `src/types/theme.ts` | Type definitions for ColorVisionMode |

| `src/contexts/ThemeContext.tsx` | State management and persistence |

| `src/styles/globals.css` | CSS filter rules |

| `src/components/shared/ColorVisionFilters.tsx` | SVG filter definitions |

| `src/features/admin/components/Appearance.tsx` | UI selector |

| `src/components/shared/ColorWheelPicker.tsx` | Hue ring + SL square picker |

| `src/components/shared/ThemePreview.tsx` | Live theme preview |

| `src/lib/colorGenerator.ts` | Palette generation with S/L overrides |

| `src/types/customTheme.ts` | Custom theme (hue + saturation + lightness) type definitions |

Synced from IFMmvp-Frontend documentation: pages/administration/04-APPEARANCE.md