# Mapbox 3D Globe Visualization - Progressive Web-Enhanced Specification

## Core Challenge
Create progressively sophisticated Mapbox GL JS 3D globe visualizations that improve with each iteration by integrating knowledge from Mapbox documentation, tutorials, and examples. Each iteration should represent a measurable improvement in visual design, interactivity, data handling, or technical implementation using the globe projection feature.

## Output Requirements

**Directory Naming**: `mapbox_globe_[iteration_number]/`

**Content Structure**: Multi-file Mapbox application
```
mapbox_globe_[iteration_number]/
├── index.html          # Main HTML with Mapbox GL JS setup
├── src/
│   ├── index.js       # Core visualization logic
│   └── data/
│       └── data.js    # Embedded GeoJSON or data
├── README.md          # Documentation of iteration
└── CLAUDE.md          # Project guidelines
```

### index.html Template
```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Globe Viz [N]: [Descriptive Title]</title>
    <link href="https://api.mapbox.com/mapbox-gl-js/v3.0.1/mapbox-gl.css" rel="stylesheet">
    <script src="https://api.mapbox.com/mapbox-gl-js/v3.0.1/mapbox-gl.js"></script>
    <style>
        /* Globe-specific styling */
        /* Overlays, legends, controls */
    </style>
</head>
<body>
    <div id="map"></div>
    <!-- Overlays: title, legend, info panel -->
    <script src="src/data/data.js"></script>
    <script type="module" src="src/index.js"></script>
</body>
</html>
```

### src/index.js Template
```js
// Mapbox access token (use public example token or placeholder)
mapboxgl.accessToken = 'pk.example...';

// Initialize map with globe projection
const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/[style]',
    projection: 'globe',
    center: [lng, lat],
    zoom: 1.5
});

map.on('load', () => {
    // Configure globe atmosphere
    map.setFog({...});

    // Add data source
    map.addSource('data-source', {...});

    // Add visualization layers
    map.addLayer({...});

    // Add interactions
    // Popups, filters, animations
});

// Add controls
map.addControl(new mapboxgl.NavigationControl());
```

## Progressive Enhancement Dimensions

### **Visual Complexity Evolution**
- **Iteration 1-3**: Single layer visualizations (heatmap OR points OR choropleth)
- **Iteration 4-6**: Multi-layer compositions (heatmap + points, choropleth + labels)
- **Iteration 7-10**: Advanced features (3D extrusions, custom markers, animations)
- **Iteration 11+**: Innovative techniques (custom shaders, WebGL layers, data-driven styling)

### **Data Handling Sophistication**
- **Basic**: Static GeoJSON with <100 features, simple properties
- **Intermediate**: Multiple data sources, 100-1000 features, property-based styling
- **Advanced**: Dynamic data loading, large datasets (1000+ features), spatial queries
- **Expert**: Real-time data, vector tiles, spatial analysis, clustering

### **Interactivity Progression**
- **Basic**: Hover popups, basic zoom/pan
- **Intermediate**: Click events, filtering, layer toggling, search
- **Advanced**: Timeline scrubbing, multi-view coordination, custom controls
- **Expert**: Data-driven animations, user data input, export capabilities

### **Technical Implementation**
- **Foundation**: Basic globe setup, single data source, simple layer
- **Intermediate**: Multiple layers, Mapbox expressions, custom styling
- **Advanced**: 3D features, custom projections, performance optimization
- **Expert**: Custom sources, WebGL integration, advanced expressions

## Web Research Integration Strategy

### **Initial Priming Phase URLs**
The priming agent should research these foundational topics:
1. Mapbox GL JS overview and globe projection
2. GeoJSON format and data structures
3. Mapbox expression syntax fundamentals
4. Layer types and their use cases
5. Performance best practices

### **Iteration URL Strategy**

**URL Categories for Progressive Learning:**

1. **Foundation URLs (Iterations 1-5)**
   - Mapbox GL JS getting started guide
   - Globe projection documentation
   - Basic layer types (circle, heatmap, fill)
   - GeoJSON data format
   - Simple popup and interaction patterns

2. **Intermediate URLs (Iterations 6-12)**
   - Advanced layer styling with expressions
   - Multiple data sources and layers
   - Custom controls and UI elements
   - Data-driven styling techniques
   - Filter and query features
   - Color ramps and visual variables

3. **Advanced URLs (Iterations 13-20)**
   - 3D extrusions and fill-extrusion layers
   - Custom markers and symbols
   - Animation techniques (flyTo, easeTo, camera animations)
   - Vector tiles integration
   - Spatial queries and analysis
   - Performance optimization for large datasets

4. **Expert URLs (Iterations 21+)**
   - Custom WebGL layers
   - Advanced projections
   - Real-time data integration
   - Custom shaders and rendering
   - Complex spatial analysis
   - Multi-map coordination

### **Dynamic URL Discovery**
Each iteration can also perform targeted web searches:
- "Mapbox GL JS [specific technique] example"
- "Mapbox globe [feature] tutorial"
- "Mapbox expressions [use case]"
- "Mapbox performance optimization [context]"

## Visualization Themes to Explore

### **Economic & Development**
- Global GDP, income distribution, trade flows
- Economic indicators, development indices
- Stock market data, cryptocurrency adoption
- Tourism, remittances, foreign investment

### **Environmental & Climate**
- Temperature anomalies, climate zones
- Deforestation, biodiversity hotspots
- Carbon emissions, renewable energy adoption
- Ocean currents, air quality, pollution

### **Demographic & Social**
- Population density, urbanization
- Life expectancy, health indicators
- Education levels, literacy rates
- Migration patterns, refugee flows

### **Infrastructure & Technology**
- Internet penetration, mobile usage
- Transportation networks, airports
- Renewable energy installations
- Satellite coverage, telecommunications

### **Political & Historical**
- Election results, democracy indices
- Conflict zones, peace agreements
- Colonial history, independence dates
- Language families, cultural regions

### **Natural Phenomena**
- Earthquake activity, volcanic zones
- Hurricane/typhoon tracks
- Meteor impact sites
- Magnetic field variations

## Data Format Requirements

### **GeoJSON Structure**
```javascript
const data = {
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Point", // or Polygon, LineString
                "coordinates": [longitude, latitude]
            },
            "properties": {
                "name": "Country/Region Name",
                "value": 12345,
                "category": "Type",
                "year": 2024,
                // Additional properties for styling/popups
            }
        }
    ]
};
```

### **Data Quality Standards**
- Accurate geographic coordinates (longitude, latitude order)
- Meaningful property names
- Realistic values appropriate to theme
- 50-500 features for most visualizations
- Include metadata (year, source, data type)

## Quality Standards

### **Code Quality**
- **Mapbox Best Practices**: Proper layer ordering, efficient expressions, appropriate layer types
- **Performance**: Smooth 60fps rotation, efficient rendering for large datasets
- **Accessibility**: Keyboard navigation, screen reader support where applicable
- **Responsive**: Works on desktop and mobile with appropriate touch controls
- **Clean Code**: Well-organized, commented, maintainable JavaScript

### **Visual Excellence**
- **Clarity**: Data patterns immediately apparent on the globe
- **Aesthetics**: Professional color schemes, appropriate visual hierarchy
- **Globe Features**: Proper atmosphere, stars, fog effects
- **Innovation**: Creative visualization approaches for data
- **Usability**: Intuitive controls, clear legends, informative popups

### **Web Integration Quality**
- **Source Attribution**: Each iteration credits the web source
- **Knowledge Application**: Demonstrates specific Mapbox technique learned
- **Progressive Learning**: Shows clear improvement over previous iteration
- **Novel Synthesis**: Combines multiple web sources creatively

## Iteration Evolution Pattern

### **Knowledge Accumulation Strategy**

**Wave 1 (Iterations 1-5): Foundation Building**
- Master basic globe setup and projection
- Learn fundamental layer types (circle, heatmap, fill)
- Establish data handling and GeoJSON patterns
- Focus: Technical competence with globe basics

**Wave 2 (Iterations 6-12): Enhancement & Styling**
- Advanced expression syntax
- Multi-layer compositions
- Interactive controls and filtering
- Focus: Visual sophistication and user experience

**Wave 3 (Iterations 13-20): Advanced Features**
- 3D extrusions and depth
- Custom markers and symbols
- Animation and camera control
- Focus: Technical excellence and innovation

**Wave 4 (Iterations 21+): Mastery & Experimentation**
- Custom WebGL layers
- Real-time data integration
- Novel visualization techniques
- Focus: Pushing Mapbox boundaries

### **Improvement Metrics**

Each iteration should improve on at least one dimension:
- **Visual Design**: Better colors, styling, visual hierarchy
- **Interactivity**: New interaction patterns, smoother animations
- **Data Handling**: More complex data, better transformations
- **Performance**: Faster rendering, optimized expressions
- **Features**: New Mapbox capabilities, creative techniques
- **Code Quality**: Cleaner architecture, better patterns

## Mapbox-Specific Techniques

### **Globe Projection Features**
```js
// Atmosphere and space effects
map.setFog({
    color: 'rgba(12, 20, 39, 0.9)',
    'high-color': 'rgba(36, 92, 223, 0.4)',
    'horizon-blend': 0.4,
    'space-color': '#000000',
    'star-intensity': 0.6
});

// Globe-specific camera positioning
map.flyTo({
    center: [lng, lat],
    zoom: 2,
    pitch: 45, // Tilt for 3D effect
    bearing: -17.6 // Rotation
});
```

### **Layer Types for Global Data**
- **Heatmap**: Density visualization (temperature, population, incidents)
- **Circle**: Point data with size/color encoding (cities, events, locations)
- **Fill**: Choropleth maps (country-level statistics)
- **Fill-extrusion**: 3D country/region extrusions
- **Line**: Connections, routes, boundaries
- **Symbol**: Labels, custom markers, icons

### **Expression Patterns**
```js
// Data-driven styling with expressions
'circle-radius': [
    'interpolate',
    ['linear'],
    ['get', 'value'],
    0, 5,
    1000, 20
]

// Conditional styling
'circle-color': [
    'step',
    ['get', 'value'],
    '#green', 100,
    '#yellow', 500,
    '#red'
]

// Zoom-based styling
'circle-opacity': [
    'interpolate',
    ['linear'],
    ['zoom'],
    1, 0.8,
    5, 1
]
```

## Web Research Directive

### **For Each Iteration**

**Before Generating:**
1. Fetch assigned Mapbox web URL
2. Analyze the content for:
   - New Mapbox GL JS techniques or APIs
   - Layer types and styling patterns
   - Expression syntax examples
   - Interaction patterns
   - Performance considerations
3. Identify 1-3 specific learnings to apply
4. Plan how to integrate with globe projection

**During Generation:**
1. Apply new technique from web source
2. Maintain globe projection focus
3. Document what was learned
4. Ensure genuine improvement

**After Generation:**
1. Document web source in README
2. Explain improvement over previous iteration
3. Note future exploration opportunities

## Data Strategy

### **Embedded Data Requirements**
- Use realistic, meaningful global datasets
- Data appropriate for globe-scale visualization
- Include enough features to demonstrate technique (50-500 typically)
- Proper GeoJSON format with valid coordinates
- Include metadata for popups and legends

### **Example Data Domains**
- **Economic**: GDP, trade, wages, development indices
- **Climate**: Temperature, precipitation, emissions
- **Social**: Population, education, health metrics
- **Infrastructure**: Cities, airports, networks
- **Natural**: Earthquakes, volcanoes, resources
- **Political**: Elections, conflicts, boundaries

## Ultra-Thinking Directive

Before each iteration, deeply consider:

**Web Source Integration:**
- What Mapbox technique does the URL teach?
- How can this improve globe visualizations?
- What makes this technique globe-appropriate?
- How can I adapt this learning creatively?

**Progressive Improvement:**
- What was limiting in the previous iteration?
- How does this represent genuine progress?
- What new Mapbox capability am I adding?
- How am I building on accumulated knowledge?

**Globe-Specific Design:**
- Does this work well on a spherical projection?
- How does data appear from different angles?
- Are interactions intuitive for globe navigation?
- How do layers compose in 3D space?

**Technical Excellence:**
- Am I using Mapbox expressions correctly?
- Is performance optimized for globe rendering?
- Are layer types appropriate for the data?
- What edge cases should I handle?

**Visual Communication:**
- Does the globe effectively show global patterns?
- Are visual encodings clear and intuitive?
- Do colors work on the dark globe style?
- What story does this visualization tell?

## Success Criteria

A successful Mapbox globe iteration demonstrates:
1. **Web Learning Applied**: Specific Mapbox technique from URL implemented correctly
2. **Measurable Improvement**: Clear advancement over previous iteration
3. **Globe-Appropriate**: Design works well with spherical projection
4. **Technical Quality**: Proper Mapbox patterns, performant rendering
5. **Visual Excellence**: Professional design, effective data communication
6. **Self-Contained**: Works perfectly as standalone application
7. **Documented**: Clear explanation of improvements and web source attribution

## File Organization Standards

### **index.html**
- Minimal, semantic HTML structure
- Mapbox GL JS v3.0+ CDN links
- Style block for overlays and UI
- Script loading order: data → main

### **src/index.js**
- Map initialization with globe projection
- Fog/atmosphere configuration
- Data source and layer setup
- Interaction handlers
- Control additions
- Well-commented code

### **src/data/data.js**
- Properly formatted GeoJSON
- Realistic data values
- Descriptive property names
- Exposed as global variable

### **README.md**
- Iteration number and title
- Web source attribution
- Techniques learned and applied
- How to run locally
- Data sources
- Improvement over previous iteration

### **CLAUDE.md**
- Local server commands
- Code guidelines
- Mapbox-specific patterns
- Project structure notes

Generate globe visualizations that progressively evolve from basic global data displays to masterful, interactive 3D visualizations through systematic web-enhanced learning of Mapbox GL JS capabilities.
