Visual Hierarchy System Documentation

This document describes the comprehensive visual hierarchy system implemented in theunpartyapp, providing branded depth effects and consistent interaction patterns across all UI components.

Overview

The visual hierarchy system is built on a foundation of CSS custom properties (design tokens) and semantic CSS classes that systematically apply depth effects, brand integration, and consistent animations throughout the application.

Design Token System

Depth Layers

Progressive shadow system for creating visual hierarchy:

css

--depth-raised: 0 2px 4px rgba(0, 0, 0, 0.1);           /* Subtle elevation */
--depth-elevated: 0 4px 8px rgba(0, 0, 0, 0.12);        /* Moderate elevation */
--depth-floating: 0 6px 12px rgba(0, 0, 0, 0.15);       /* Strong elevation */
--depth-modal: 0 8px 16px rgba(0, 0, 0, 0.15);          /* Modal/overlay depth */
--depth-overlay: 0 12px 24px rgba(0, 0, 0, 0.18);       /* Maximum depth */

Brand Integration

Unparty yellow (#F9C22E) branded effects:

css

--brand-shadow: 0 2px 4px rgba(249, 194, 46, 0.1);      /* Subtle brand shadow */
--brand-shadow-strong: 0 4px 8px rgba(249, 194, 46, 0.15); /* Strong brand shadow */
--brand-glow: 0 0 8px rgba(249, 194, 46, 0.2);          /* Brand glow effect */
--brand-glow-strong: 0 0 12px rgba(249, 194, 46, 0.25); /* Strong brand glow */
--brand-accent: rgba(249, 194, 46, 0.1);                /* Brand accent background */
--brand-accent-strong: rgba(249, 194, 46, 0.15);        /* Strong brand accent */

Animation Standards

Consistent timing and easing:

css

--transition-fast: 0.15s ease;                          /* Quick transitions */
--transition-standard: 0.2s ease;                       /* Standard transitions */
--transition-slow: 0.3s ease;                          /* Slow transitions */
--easing-brand: cubic-bezier(0.25, 0.46, 0.45, 0.94);  /* Smooth brand easing */
--easing-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55); /* Bounce effect */

Interactive States

Consistent interaction patterns:

css

--hover-lift: translateY(-1px);                         /* Subtle lift on hover */
--hover-lift-strong: translateY(-2px);                  /* Strong lift on hover */
--active-press: translateY(0) scale(0.98);              /* Press down effect */
--focus-ring: 0 0 0 3px rgba(249, 194, 46, 0.3);       /* Accessible focus ring */

Component Categories

Primary Interactive Elements (`.vh-primary-interactive`)

For main navigation, CTAs, and FAB buttons that demand attention:

Depth: Strong elevation with brand shadows

Hover: Lift with scale and enhanced shadows

Examples: FAB button, main CTA buttons, primary navigation

Applied to: .fab-button, main navigation buttons, active CTA sections

Secondary Interactive Elements (`.vh-secondary-interactive`)

For form inputs, secondary buttons, and interactive cards:

Depth: Moderate elevation

Hover: Subtle lift with brand accent

Examples: Form inputs, secondary buttons, menu items

Applied to: Header action buttons, navigation menu items, form elements

Content Containers (`.vh-content-container`)

For article cards, step containers, and modal backgrounds:

Depth: Light elevation with subtle brand integration

Hover: Gentle lift with brand accent reveal

Examples: Article cards, CTA panels, modals

Applied to: .article-table-item, CTA containers, dropdown menus

Supporting Elements (`.vh-supporting-element` / `.vh-supporting-element-brand`)

For icons, dividers, and labels:

Depth: Minimal drop shadows

Hover: Subtle scale with enhanced shadows

Examples: Icons, navigation arrows, category badges

Applied to: Navigation icons, category badges, supporting graphics

Responsive Scaling

The system automatically scales depth effects for different screen sizes:

css

/* Mobile (≤640px) */
--depth-scale-mobile: 0.8;     /* Reduced depth for smaller screens */

/* Tablet (641px-1024px) */
--depth-scale-tablet: 0.9;     /* Moderate depth scaling */

/* Desktop (≥1025px) */
--depth-scale-desktop: 1.0;    /* Full depth effects */

Usage Examples

Basic Component Enhancement

tsx

// Before
<button className="rounded-lg px-4 py-2 bg-yellow-400">
  Primary Action
</button>

// After
<button className="vh-primary-interactive rounded-lg px-4 py-2 bg-yellow-400">
  Primary Action
</button>

Form Elements

tsx

// Use pre-built form classes
<input className="unparty-input w-full" />
<button className="vh-button-primary">Submit</button>
<button className="vh-button-secondary">Cancel</button>

Card Components

tsx

// Content cards
<div className="vh-content-container rounded-lg p-4">
  <h3>Card Title</h3>
  <p>Card content...</p>
</div>

// Interactive cards
<div className="vh-secondary-interactive rounded-lg p-4">
  <h3>Interactive Card</h3>
</div>

Icons and Supporting Elements

tsx

// Regular supporting element
<Icon className="vh-supporting-element" />

// Brand-tinted supporting element
<Icon className="vh-supporting-element-brand" />

Implementation Notes

Dark Mode Support

All design tokens automatically adapt for dark mode with enhanced shadow opacity and adjusted brand colors.

Accessibility

Focus rings use brand colors with proper contrast ratios

All interactive elements maintain WCAG-compliant focus states

Hover states are complemented by focus states for keyboard navigation

Performance

CSS custom properties enable hardware acceleration

Transitions use optimized properties (transform, opacity)

No JavaScript required for basic hierarchy effects

Component Migration

Enhanced Components

The following components have been fully migrated to use the visual hierarchy system:

1. FAB (.fab-button) - Primary interactive with breathing animation 2. Header - Mixed hierarchy with primary logo, secondary actions 3. CTA - Content containers with interactive elements 4. Modal - Content container with secondary interactive close button 5. ArticleTable - Content containers with brand-tinted category badges 6. PaymentModal - Form elements using unparty form classes 7. IconButton - Secondary interactive with supporting element icons

Implementation Pattern

1. Identify component category (primary, secondary, content, supporting) 2. Apply appropriate vh-* class 3. Use existing unparty form classes for form elements 4. Test hover, focus, and active states 5. Verify dark mode compatibility

Best Practices

1. Consistent Application: Always use the semantic classes rather than custom shadows 2. Hierarchy Respect: Don't mix primary and secondary patterns on the same component 3. Brand Integration: Use brand-tinted effects for elements that should feel "unparty" 4. Responsive Consideration: Test depth effects on mobile devices 5. Accessibility First: Ensure all interactive states are keyboard accessible

Future Enhancements

1. Additional Utility Classes: Expand utility classes for specific use cases 2. Animation Refinement: Fine-tune timing based on user feedback 3. Performance Optimization: Monitor and optimize shadow rendering performance 4. Component Library: Create reusable component variations 5. Design Token Extension: Add additional brand integration patterns

This visual hierarchy system creates a cohesive, professional user experience while maintaining the distinctive unparty brand identity through subtle yet effective depth and interaction patterns.