Contrast Zone System Documentation

Overview

The enhanced theme system provides sophisticated contrast zones while maintaining your monochromatic + yellow brand aesthetic. It works seamlessly with Bulma's framework and provides multiple levels of contrast for better visual hierarchy.

Contrast Zone Types

1. High Contrast Zone

Purpose: Maximum contrast for important content

Dark Theme: Light background (#e5e7eb) with dark text
Light Theme: Dark background (#0f1115) with light text

<!-- Bulma way -->
<div class="has-background-light">
    <h2>High Contrast Content</h2>
    <p>This stands out dramatically from the base theme.</p>
</div>

<!-- Custom utility way -->
<div class="bg-contrast-high">
    <h2>High Contrast Content</h2>
    <p>This stands out dramatically from the base theme.</p>
</div>

<!-- Card example -->
<div class="card contrast-high">
    <div class="card-content">
        <h3>Important Announcement</h3>
        <p>This card demands attention.</p>
    </div>
</div>

2. Medium Contrast Zone

Purpose: Balanced contrast for secondary content

Dark Theme: Medium gray background with appropriate text
Light Theme: Light gray background with appropriate text

<div class="bg-contrast-medium">
    <h3>Secondary Content</h3>
    <p>Noticeable but not overwhelming.</p>
</div>

<div class="card contrast-medium">
    <div class="card-content">
        <h3>Featured Article</h3>
        <p>Important but not urgent content.</p>
    </div>
</div>

3. Emphasis Zone

Purpose: Brand-aligned highlighting

Dark Theme: Gray-600 background with light text
Light Theme: Gray-800 background with light text

<section class="section emphasis">
    <div class="container">
        <h2>Call to Action Section</h2>
        <p>This emphasizes important actions or information.</p>
        <button class="button is-primary">Take Action</button>
    </div>
</section>

<div class="standout">
    <h4>Pro Tip</h4>
    <p>This content gets special attention.</p>
</div>

4. Subtle Zone

Purpose: Minimal contrast for secondary information

Dark Theme: Slightly lighter than primary background
Light Theme: Slightly darker than primary background

<div class="bg-subtle">
    <p class="has-text-muted">Subtle background information</p>
</div>

<div class="highlight-subtle">
    <span>Gently highlighted text</span>
</div>

Text Color Utilities

Context-Aware Text

<!-- Automatically chooses appropriate text color for background -->
<div class="bg-contrast-high">
    <p class="text-on-light">Perfect contrast text</p>
</div>

<!-- Emphasis text (always yellow/brand color) -->
<p class="has-text-emphasis">Brand-colored text</p>

<!-- Muted text for less important info -->
<p class="has-text-muted">Secondary information</p>

Component Examples

Hero Sections

<!-- High contrast hero -->
<section class="hero contrast-high">
    <div class="hero-body">
        <div class="container">
            <h1 class="title">Dramatic Hero Section</h1>
            <p class="subtitle">Maximum visual impact</p>
        </div>
    </div>
</section>

<!-- Emphasis hero -->
<section class="hero emphasis">
    <div class="hero-body">
        <div class="container">
            <h1 class="title">Brand-Aligned Hero</h1>
            <p class="subtitle">Strong but not overwhelming</p>
        </div>
    </div>
</section>

Content Sections

<!-- Alternating contrast for visual rhythm -->
<section class="section">
    <div class="container">
        <h2>Standard Section</h2>
        <p>Regular content flow.</p>
    </div>
</section>

<section class="section contrast-high">
    <div class="container">
        <h2>Highlighted Section</h2>
        <p>This section gets attention.</p>
    </div>
</section>

<section class="section">
    <div class="container">
        <h2>Back to Standard</h2>
        <p>Creating visual rhythm.</p>
    </div>
</section>

Cards and Components

<!-- Card grid with varying contrast -->
<div class="columns">
    <div class="column">
        <div class="card">
            <div class="card-content">Standard card</div>
        </div>
    </div>
    <div class="column">
        <div class="card contrast-medium">
            <div class="card-content">Featured card</div>
        </div>
    </div>
    <div class="column">
        <div class="card emphasis">
            <div class="card-content">Priority card</div>
        </div>
    </div>
</div>

Callouts and Alerts

<!-- Subtle callout -->
<div class="callout">
    <h4>Information</h4>
    <p>This is important but not urgent information.</p>
</div>

<!-- Standout alert -->
<div class="standout">
    <h4>⚠️ Important Notice</h4>
    <p>This requires immediate attention.</p>
</div>

Design Principles

1. Visual Hierarchy

Primary content: Standard backgrounds
Secondary content: Subtle or medium contrast
Important content: High contrast or emphasis
Critical content: Standout utility

2. Rhythm and Flow

Use contrast zones sparingly for maximum impact
Alternate between standard and contrast zones
Group related contrast levels together

3. Accessibility

All contrast zones meet WCAG AA standards
Text colors automatically adjust for readability
Focus states remain visible in all zones

4. Brand Consistency

Yellow remains the primary brand accent
Gray scale provides the contrast foundation
Light/dark themes flip the contrast logically

Migration Guide

From Old Bulma Classes

<!-- OLD -->
<div class="has-background-white has-text-black">Content</div>

<!-- NEW -->
<div class="bg-contrast-high">Content</div>

From Custom CSS

<!-- OLD -->
<div style="background: #f0f0f0; color: #333;">Content</div>

<!-- NEW -->
<div class="bg-contrast-medium">Content</div>

This system gives you the sophisticated contrast control you need while keeping everything within your monochromatic + yellow aesthetic and working seamlessly with Bulma's framework.