Nookhive Logo
StyleguideAPI Reference

Imagery

The imagery system ensures that all visual content maintains accessibility and readability standards while creating engaging user experiences. When text is placed over images, standardized overlay treatments guarantee optimal contrast and legibility.

Principles

Accessibility Standards

  • WCAG AA Compliance: All text-on-image combinations meet 4.5:1 contrast ratio
  • Consistent Overlays: Standardized overlay treatments ensure predictable readability
  • Alternative Text: All images include descriptive alt text for screen readers
  • Responsive Design: Images adapt gracefully across all device sizes

Visual Hierarchy

  • Content Priority: Text content always takes precedence over decorative imagery
  • Overlay Consistency: Uniform overlay treatments create visual cohesion
  • Brand Alignment: Image choices support brand messaging and values
  • Performance Focus: Optimized images for fast loading across all connections

Text Overlay Standards

Black Overlay with White Text

Use a 50% opacity black overlay (#000000) with white text (#ffffff) for maximum contrast and readability. This is our primary text-on-image treatment.

Hero Section Title

Supporting text that remains highly readable against any background image.

Feature Highlight

Consistent overlay treatment ensures readability across diverse imagery.

Implementation
<!-- Black Overlay with White Text (semantic example) -->
<div style="position: relative; height: 256px; background: url(image.jpg) center/cover no-repeat; border-radius: 8px;">
  <div style="position: absolute; inset: 0; background: rgba(0,0,0,0.5); border-radius: 8px;"></div>
  <div style="position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; padding: 20px;">
    <div style="text-align: center; color: #ffffff;">
      <h3 style="margin: 0 0 8px 0;">Title</h3>
      <p style="margin: 0;">Supporting text</p>
    </div>
  </div>
</div>

White Overlay with Dark Text

Use an 80% opacity white overlay (#ffffff) with near-black text (#010101) for light, airy designs while maintaining excellent readability.

Clean Design

White overlay creates a light, modern aesthetic while ensuring text clarity.

Bright & Accessible

Perfect for content that needs a lighter, more approachable feel.

Implementation
<!-- White Overlay with Dark Text (semantic example) -->
<div style="position: relative; height: 256px; background: url(image.jpg) center/cover no-repeat; border-radius: 8px;">
  <div style="position: absolute; inset: 0; background: rgba(255,255,255,0.8); border-radius: 8px;"></div>
  <div style="position: absolute; inset: 0; display: flex; align-items: center; justify-content: center; padding: 20px;">
    <div style="text-align: center; color: #010101;">
      <h3 style="margin: 0 0 8px 0;">Title</h3>
      <p style="margin: 0;">Supporting text</p>
    </div>
  </div>
</div>

Usage Guidelines

When to Use Black Overlay

  • Hero sections and primary call-to-action areas
  • High-impact content that needs maximum attention
  • Images with varied brightness and contrast
  • Content requiring strong visual hierarchy
  • Marketing and promotional materials

When to Use White Overlay

  • Informational content and educational materials
  • Lighter, more approachable messaging
  • Content areas within longer articles
  • Secondary information and supporting details
  • Areas requiring a softer visual treatment

Accessibility Requirements

Mandatory Standards

Contrast Requirements
  • Black Overlay: White text (#ffffff) on 50% black overlay achieves 21:1 contrast ratio
  • White Overlay: Near-black text (#010101) on 80% white overlay achieves 16:1 contrast ratio
  • WCAG Compliance: Both treatments exceed AA standards (4.5:1) and meet AAA standards (7:1)
  • Testing Required: Always verify contrast ratios with accessibility tools
Implementation Standards
  • Alternative Text: All background images must include descriptive alt attributes
  • Semantic HTML: Use proper heading hierarchy and semantic elements
  • Keyboard Navigation: Ensure all interactive elements are keyboard accessible
  • Screen Readers: Test with screen reader software for proper content flow

Performance Guidelines

Image Optimization

  • Use WebP format with JPEG fallback for broad compatibility
  • Implement responsive images with appropriate srcset attributes
  • Compress images to balance quality and file size
  • Use lazy loading for images below the fold
  • Provide appropriate alt text for all images

Loading Strategy

  • Prioritize above-the-fold hero images for immediate loading
  • Use CSS background images for decorative imagery
  • Implement proper image dimensions to prevent layout shift
  • Consider using blur-up technique for progressive loading
  • Test performance on slower connections and devices