med-plan-assistant/docs/README.CSS_UTILITY_CLASSES.md

Custom CSS Utility Classes

This document describes the centralized CSS utility classes defined in src/styles/global.css for consistent styling across the application.

Error & Warning Classes

Validation Bubbles (Popups)

.error-bubble

• Used for error validation popup messages on form fields
• Light mode: Soft red background with dark red text
• Dark mode: Very dark red background (80% opacity) with light red text
• Includes border for visual separation
• Example: Input field validation errors

.warning-bubble

• Used for warning validation popup messages on form fields
• Light mode: Soft amber background with dark amber text
• Dark mode: Very dark amber background (80% opacity) with light amber text
• Includes border for visual separation
• Example: Input field warnings about unusual values

Borders

.error-border

• Red border for form inputs with errors
• Uses the destructive color from the theme
• Example: Highlight invalid input fields

.warning-border

• Amber border for form inputs with warnings
• Uses amber-500 color
• Example: Highlight input fields with unusual but valid values

Background Boxes (Static Sections)

.error-bg-box

• For static error information sections
• Light mode: Light red background
• Dark mode: Dark red background (40% opacity)
• Includes border
• Example: Persistent error messages in modals

.warning-bg-box

• For static warning information sections
• Light mode: Light amber background
• Dark mode: Dark amber background (40% opacity)
• Includes border
• Example: Warning boxes in settings

.info-bg-box

• For informational sections
• Light mode: Light blue background
• Dark mode: Dark blue background (40% opacity)
• Includes border
• Example: Helpful tips, contextual information

Text Colors

.error-text

• Dark red text in light mode, light red in dark mode
• High contrast for readability
• Example: Inline error messages

.warning-text

• Dark amber text in light mode, light amber in dark mode
• High contrast for readability
• Example: Inline warning messages

.info-text

• Dark blue text in light mode, light blue in dark mode
• High contrast for readability
• Example: Inline informational text

Usage Examples

Form Validation Popup

{hasError && (
  <div className="error-bubble w-80 text-xs p-2 rounded-md">
    {errorMessage}
  </div>
)}

{hasWarning && (
  <div className="warning-bubble w-80 text-xs p-2 rounded-md">
    {warningMessage}
  </div>
)}

Input Field Borders

<Input
  className={cn(
    hasError && "error-border",
    hasWarning && !hasError && "warning-border"
  )}
/>

Static Information Boxes

{/* Warning box */}
<div className="warning-bg-box rounded-md p-3">
  <p className="warning-text">{warningText}</p>
</div>

{/* Info box */}
<div className="info-bg-box rounded-md p-3">
  <p className="info-text">{infoText}</p>
</div>

{/* Error box */}
<div className="error-bg-box rounded-md p-3">
  <p className="error-text">{errorText}</p>
</div>

Accessibility

All classes are designed with accessibility in mind:

• ✅ High contrast ratios - Meet WCAG AA standards for text readability
• ✅ Dark mode optimized - Reduced saturation and brightness in dark mode (80% opacity for bubbles, 40% for boxes)
• ✅ Consistent theming - Semantic color usage (red=error, amber=warning, blue=info)
• ✅ Icon visibility - Muted backgrounds ensure icons stand out
• ✅ Border separation - Clear visual boundaries between elements

Opacity Rationale

• Validation bubbles: 80% opacity in dark mode - Higher opacity for better text readability during focused interaction
• Background boxes: 40% opacity in dark mode - Lower opacity for persistent elements to reduce visual weight

Migration Guide

When updating existing code to use these classes:

Before:

className="bg-red-50 dark:bg-red-950/50 text-red-900 dark:text-red-200 border border-red-300 dark:border-red-800"

After:

className="error-bubble"

This reduces duplication, ensures consistency, and makes it easier to update the design system in the future.

Files Using These Classes

• src/components/ui/form-numeric-input.tsx
• src/components/ui/form-time-input.tsx
• src/components/settings.tsx
• src/components/data-management-modal.tsx
• src/components/disclaimer-modal.tsx
• src/components/day-schedule.tsx