infinite-agents-public/specs/d3_visualization_progressiv...

# D3 Data Visualization - Progressive Web-Enhanced Specification

## Core Challenge
Create progressively sophisticated D3.js data visualizations that improve with each iteration by integrating knowledge from web documentation, tutorials, and examples. Each iteration should represent a measurable improvement in visual design, interactivity, data handling, or technical implementation.

## Output Requirements

**File Naming**: `d3_viz_[iteration_number].html`

**Content Structure**: Self-contained D3 visualization with embedded data
```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>D3 Visualization [iteration_number]: [Descriptive Name]</title>
    <script src="https://d3js.org/d3.v7.min.js"></script>
    <style>
        /* Visualization-specific styling */
        /* Progressive enhancement of visual design */
    </style>
</head>
<body>
    <div id="visualization-container">
        <h1>[Descriptive Visualization Title]</h1>
        <div id="controls">
            <!-- Interactive controls for the visualization -->
        </div>
        <div id="viz">
            <!-- D3 renders here -->
        </div>
        <div id="insights">
            <!-- Data insights, legends, annotations -->
        </div>
    </div>

    <script>
        // Embedded data (realistic, demonstrative)
        const data = [/* data here */];

        // D3 visualization implementation
        // Progressive improvements from web research
        // New techniques learned from current iteration's URL

        // Iteration-specific innovations
        // Accessibility features
        // Responsive design
        // Interactive elements
    </script>

    <!-- Documentation footer -->
    <footer>
        <h3>Iteration [N] Improvements</h3>
        <ul>
            <li><strong>Web Source:</strong> [URL fetched for this iteration]</li>
            <li><strong>New Technique:</strong> [What was learned and applied]</li>
            <li><strong>Enhancement:</strong> [Specific improvement over previous iteration]</li>
        </ul>
    </footer>
</body>
</html>
```

## Progressive Enhancement Dimensions

### **Visual Design Evolution**
- **Iteration 1-3**: Basic chart types (bar, line, scatter) with clean styling
- **Iteration 4-6**: Advanced color schemes, gradients, annotations, responsive layouts
- **Iteration 7-10**: Complex compositions, small multiples, linked views, brushing
- **Iteration 11+**: Innovative visual encodings, custom force simulations, advanced interactions

### **Interactivity Sophistication**
- **Basic**: Tooltips, hover effects, clickable elements
- **Intermediate**: Zooming, panning, brushing, filtering, transitions
- **Advanced**: Drag interactions, real-time data updates, coordinated multi-view
- **Expert**: Custom force simulations, physics-based interactions, generative animations

### **Data Handling Complexity**
- **Simple**: Embedded arrays, basic data structures
- **Moderate**: Hierarchical data, nested structures, data transformations
- **Advanced**: Time-series data, geospatial data, network graphs
- **Expert**: Real-time data streams, large datasets with virtualization, external APIs

### **Technical Implementation**
- **Foundation**: Core D3 selections, scales, axes, basic shapes
- **Intermediate**: Layouts (hierarchy, force, chord), transitions, generators
- **Advanced**: Custom scales, advanced projections, data joins, enter/exit/update patterns
- **Expert**: WebGL integration, canvas rendering for performance, worker threads

## Web Research Integration Strategy

### **Initial Priming Phase URLs**
The priming agent should research these foundational topics:
1. D3.js official documentation (d3js.org)
2. Observable D3 tutorials and examples
3. D3 Graph Gallery for pattern library
4. Mike Bostock's blocks and articles
5. Recent D3.js best practices and v7+ features

### **Iteration URL Strategy**

**URL Categories for Progressive Learning:**

1. **Foundation URLs (Iterations 1-5)**
   - D3 official API documentation pages
   - Basic chart tutorials (bar, line, scatter, pie)
   - Scale and axis fundamentals
   - Selection and data binding basics

2. **Intermediate URLs (Iterations 6-12)**
   - D3 layout documentation (force, hierarchy, chord)
   - Transition and animation guides
   - Interactive visualization tutorials
   - Color theory and D3 color scales
   - Responsive D3 patterns

3. **Advanced URLs (Iterations 13-20)**
   - Complex force simulations
   - Geographic projections and maps
   - Network visualization techniques
   - Performance optimization for large datasets
   - Custom interpolators and transitions

4. **Expert URLs (Iterations 21+)**
   - Cutting-edge D3 techniques
   - WebGL integration with D3
   - Real-time data visualization
   - Advanced interaction patterns
   - Novel visual encoding research papers

### **Dynamic URL Discovery**
Each iteration can also perform targeted web searches:
- "D3.js [specific technique] tutorial"
- "D3 [chart type] best practices"
- "D3 interactive [feature] example"
- "Advanced D3 [specific area] technique"

## Visualization Types to Explore

### **Statistical Visualizations**
- Bar charts (vertical, horizontal, grouped, stacked)
- Line charts (single, multi-series, area, streamgraph)
- Scatter plots (basic, bubble, matrix)
- Box plots, violin plots, beeswarm plots
- Histograms and distribution plots

### **Hierarchical Visualizations**
- Tree diagrams (tidy tree, radial tree)
- Treemaps (squarified, binary, slice-dice)
- Sunburst diagrams
- Circle packing
- Icicle plots

### **Network Visualizations**
- Force-directed graphs
- Arc diagrams
- Chord diagrams
- Sankey diagrams
- Hierarchical edge bundling

### **Geographic Visualizations**
- Choropleth maps
- Point maps with clustering
- Flow maps
- Cartograms
- Globe projections

### **Temporal Visualizations**
- Time series with brushing
- Calendar heatmaps
- Gantt charts
- Horizon charts
- Streamgraphs

### **Advanced/Novel Visualizations**
- Parallel coordinates
- Voronoi diagrams
- Contour plots
- Custom force simulations
- Generative/algorithmic art with data

## Quality Standards

### **Code Quality**
- **D3 Best Practices**: Proper data joins, efficient updates, semantic selections
- **Performance**: Optimized for 60fps animations, efficient rendering
- **Accessibility**: ARIA labels, keyboard navigation, screen reader support
- **Responsive**: Works on mobile, tablet, desktop with appropriate scaling
- **Clean Code**: Well-organized, commented, maintainable JavaScript

### **Visual Excellence**
- **Clarity**: Information is immediately understandable
- **Aesthetics**: Professional design, harmonious colors, appropriate typography
- **Innovation**: Each iteration introduces novel elements or techniques
- **Data-Ink Ratio**: Maximize information, minimize clutter
- **Storytelling**: Visualization reveals insights and supports understanding

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

## Iteration Evolution Pattern

### **Knowledge Accumulation Strategy**

**Wave 1 (Iterations 1-5): Foundation Building**
- Learn core D3 APIs and patterns
- Master basic chart types
- Establish coding standards and structure
- Focus: Technical competence

**Wave 2 (Iterations 6-12): Enhancement & Interaction**
- Add sophisticated interactions
- Improve visual design substantially
- Introduce advanced D3 layouts
- Focus: User experience

**Wave 3 (Iterations 13-20): Innovation & Complexity**
- Tackle complex data structures
- Create novel visualization types
- Optimize for performance
- Focus: Technical excellence

**Wave 4 (Iterations 21+): Mastery & Experimentation**
- Push D3 boundaries
- Integrate cutting-edge techniques
- Create publication-quality visualizations
- Focus: Artistic and technical mastery

### **Improvement Metrics**

Each iteration should improve on at least one dimension:
- **Visual Design**: Better colors, layout, typography, spacing
- **Interactivity**: New interaction patterns, smoother transitions
- **Data Handling**: More complex data, better transformations
- **Performance**: Faster rendering, smoother animations
- **Accessibility**: Better keyboard support, ARIA labels, color contrast
- **Code Quality**: Cleaner architecture, better patterns
- **Innovation**: Novel techniques, creative applications

## Web Research Directive

### **For Each Iteration**

**Before Generating:**
1. Fetch assigned web URL
2. Analyze the content for:
   - New D3 techniques or APIs
   - Design patterns and best practices
   - Code examples and implementations
   - Visual design inspiration
   - Interaction patterns
3. Identify 1-3 specific learnings to apply
4. Plan how to integrate learnings with previous iterations

**During Generation:**
1. Apply new technique from web source
2. Maintain continuity with previous work where appropriate
3. Document what was learned and how it was applied
4. Ensure the iteration is genuinely improved, not just different

**After Generation:**
1. Document the web source in the footer
2. Explicitly state the improvement over previous iteration
3. Note what future iterations could explore

## Data Strategy

### **Embedded Data Requirements**
- Use realistic, meaningful datasets
- Data should be appropriate for the visualization type
- Include enough data to demonstrate the technique (50-500 data points typically)
- For hierarchical data, ensure proper nesting
- For network data, ensure connected graph structure

### **Example Data Domains**
- Sales/business metrics (revenue, growth, segments)
- Scientific data (measurements, experiments, observations)
- Social network data (connections, interactions, communities)
- Geographic data (countries, cities, regions, statistics)
- Temporal data (events over time, trends, patterns)
- Categorical data (comparisons, distributions, rankings)

## Ultra-Thinking Directive

Before each iteration, deeply consider:

**Web Source Integration:**
- What is the core lesson from the fetched URL?
- How can this technique improve upon the previous iteration?
- What aspects of the web example are most valuable?
- How can I adapt this learning to my specific visualization goal?

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

**Technical Excellence:**
- Am I using D3 best practices from the web source?
- Is my code efficient and maintainable?
- Have I applied the technique correctly?
- What edge cases should I handle?

**Visual Communication:**
- Does this visualization communicate data clearly?
- Have I improved the visual design?
- Are interactions intuitive and valuable?
- What story does this data tell?

**Innovation Balance:**
- Am I innovating while maintaining usability?
- Have I combined multiple learnings effectively?
- Is this iteration production-ready or experimental?
- What makes this visualization memorable?

## Success Criteria

A successful D3 iteration demonstrates:
1. **Web Learning Applied**: Specific technique from URL is implemented correctly
2. **Measurable Improvement**: Clear advancement over previous iteration
3. **Technical Quality**: Proper D3 patterns, performant code, accessible
4. **Visual Excellence**: Professional design, clear communication, aesthetic appeal
5. **Self-Contained**: Works perfectly as standalone HTML file with D3 CDN
6. **Documented**: Clear explanation of improvements and web source attribution

Generate visualizations that progressively evolve from competent implementations to masterful, publication-quality interactive data visualizations through systematic web-enhanced learning.