# Example Specification: Interactive Data Visualization

This specification demonstrates how the pattern synthesis system works with a concrete example.

## Objective

Generate self-contained, interactive data visualizations using HTML, CSS, and JavaScript. Each visualization should be unique, educational, and demonstrate progressively improving quality through pattern learning.

## Output Requirements

### File Format
- **Type**: Single HTML file (self-contained)
- **Naming**: `visualization_{N}.html` where N is iteration number
- **Size**: 5-15KB (optimized but feature-complete)

### Technical Stack
- HTML5 for structure
- CSS3 for styling (embedded in `<style>` tag)
- JavaScript (ES6+) for interactivity (embedded in `<script>` tag)
- Optional: D3.js, Chart.js, or vanilla Canvas/SVG
- No external dependencies (all code must be inline)

## Content Requirements

### 1. Data Domain (Choose One Per Iteration)
- Scientific data (climate, astronomy, biology)
- Social good data (SDGs, health, education)
- Creative data (art, music, literature)
- Technical data (algorithms, systems, networks)
- Historical data (events, demographics, economics)

### 2. Visualization Type (Choose One Per Iteration)
- Force-directed network graph
- Animated bar/line chart
- Interactive scatter plot
- Hierarchical tree diagram
- Geographic map visualization
- Particle simulation
- Radial/circular layout
- Time series animation

### 3. Required Features

#### Visual Elements
- Clear title and description
- Legend explaining data representation
- Color-coded elements for clarity
- Smooth animations (if applicable)
- Responsive sizing (fits various screens)

#### Interactivity
- Hover tooltips showing data details
- Click interactions for deeper exploration
- Filter or search capability
- Zoom/pan controls (for complex visualizations)
- Play/pause controls (for animations)

#### Code Quality
- Well-structured HTML/CSS/JS
- Clear comments explaining logic
- Modular functions (reusable components)
- Error handling for edge cases
- Performance optimization

## Pattern Synthesis Examples

To demonstrate how patterns work, here are examples of what the pattern library might extract:

### Example Pattern 1: Modular Data-View-Controller Structure

```javascript
// PATTERN: Separate data, rendering, and interaction logic

// DATA LAYER
const dataset = {
  values: [/* data */],
  metadata: {/* info */},
  validate() { /* validation */ }
};

// VIEW LAYER
const renderer = {
  init(container) { /* setup */ },
  render(data) { /* draw */ },
  update(data) { /* redraw */ }
};

// CONTROLLER LAYER
const controller = {
  handleClick(event) { /* logic */ },
  handleHover(event) { /* logic */ },
  filterData(criteria) { /* logic */ }
};

// INITIALIZATION
document.addEventListener('DOMContentLoaded', () => {
  renderer.init('#container');
  renderer.render(dataset);
});
```

**Why this pattern works:**
- Clear separation of concerns
- Easy to test each layer independently
- Simple to extend with new features
- Self-documenting code structure

### Example Pattern 2: Progressive Enhancement Documentation

```html
<!-- PATTERN: Layer documentation from overview to details -->

<!DOCTYPE html>
<html>
<head>
  <title>Climate Data Network - Global Temperature Anomalies</title>
  <meta name="description" content="Interactive force-directed graph showing connections between global temperature stations">
</head>
<body>
  <!-- HIGH-LEVEL OVERVIEW -->
  <div class="info-panel">
    <h1>Global Temperature Network</h1>
    <p>Explore how temperature anomalies correlate across weather stations worldwide.</p>
  </div>

  <!-- INTERACTIVE VISUALIZATION -->
  <div id="viz-container">
    <!-- SVG will be injected here -->
  </div>

  <script>
    /**
     * OVERVIEW: Renders force-directed graph of temperature correlations
     *
     * TECHNICAL DETAILS:
     * - Uses D3.js force simulation with custom forces
     * - Nodes: weather stations (size = data quality, color = hemisphere)
     * - Edges: correlation strength (thickness = Pearson coefficient)
     *
     * INTERACTIONS:
     * - Hover node: highlight connected stations
     * - Click node: show detailed time series
     * - Drag node: reposition in force simulation
     *
     * DATA SOURCE: NOAA Global Historical Climatology Network
     */

    // ... implementation with inline comments
  </script>
</body>
</html>
```

**Why this pattern works:**
- Serves both casual users and developers
- Reduces onboarding time
- Makes code maintainable
- Demonstrates thoughtfulness

### Example Pattern 3: Defensive Rendering with Graceful Degradation

```javascript
// PATTERN: Handle all edge cases with informative fallbacks

function renderVisualization(data) {
  // GUARD: No data provided
  if (!data) {
    return renderErrorState({
      message: "No data available",
      suggestion: "Check data source connection",
      fallback: renderPlaceholder()
    });
  }

  // GUARD: Invalid data structure
  if (!Array.isArray(data.nodes) || !Array.isArray(data.links)) {
    return renderErrorState({
      message: "Invalid data format",
      expected: "{ nodes: [], links: [] }",
      received: typeof data,
      fallback: renderExampleData()
    });
  }

  // GUARD: Empty dataset
  if (data.nodes.length === 0) {
    return renderEmptyState({
      message: "No data points to visualize",
      action: "Add data or select different date range"
    });
  }

  // GUARD: Insufficient data for visualization
  if (data.nodes.length < 3) {
    return renderMinimalState({
      message: "Limited data available",
      note: "Visualization requires at least 3 data points",
      data: data.nodes // Still show what's available
    });
  }

  // SUCCESS: Proceed with full visualization
  return renderFullVisualization(data);
}

function renderErrorState({ message, suggestion, fallback }) {
  return `
    <div class="error-state">
      <h3>⚠️ ${message}</h3>
      <p>${suggestion}</p>
      ${fallback}
    </div>
  `;
}
```

**Why this pattern works:**
- Never crashes or shows blank screen
- Provides helpful error messages
- Offers fallback visualizations
- Improves debugging experience
- Better user experience under all conditions

## Quality Standards

### Minimum Requirements (All Iterations)
- ✓ Fully functional visualization
- ✓ No console errors
- ✓ Responsive to window resize
- ✓ Clear documentation
- ✓ Unique theme/dataset
- ✓ Meets all technical requirements

### Excellence Indicators (Pattern-Guided Iterations)
- ✓ Adopts 2+ patterns from library
- ✓ Innovates beyond existing patterns
- ✓ Exceptional code organization
- ✓ Thoughtful UX considerations
- ✓ Performance optimizations
- ✓ Comprehensive error handling
- ✓ Educational value (teaches concepts)

## Pattern Learning Progression

### Wave 1 (No Pattern Library)
Iterations generate diverse visualizations exploring different approaches:
- Some use classes, others use functions
- Various documentation styles
- Different organizational patterns
- Range of error handling approaches

**Result**: Pattern extraction identifies best approaches from Wave 1

### Wave 2 (Initial Pattern Library)
Iterations receive 3-5 exemplary patterns from Wave 1:
- Structural pattern (e.g., modular architecture)
- Content pattern (e.g., progressive documentation)
- Quality pattern (e.g., defensive rendering)

**Result**: Quality improves, consistency increases, new patterns emerge

### Wave 3+ (Refined Pattern Library)
Iterations receive best patterns from ALL previous waves:
- Top structural patterns proven across iterations
- Most effective content patterns
- Innovative techniques that worked well
- Robust quality patterns

**Result**: Continuous improvement with stable quality bar

## Uniqueness Requirements

Each iteration must be genuinely unique in:

1. **Data Domain**: Different subject matter
2. **Visualization Type**: Different chart/graph type
3. **Visual Style**: Different color schemes, layouts
4. **Interaction Model**: Different ways to explore data
5. **Technical Approach**: Different implementation strategies

**Example Diversity:**
- Iteration 1: Climate network graph with force simulation
- Iteration 2: SDG progress animated bar chart
- Iteration 3: Music genre scatter plot with clustering
- Iteration 4: Algorithm complexity tree diagram
- Iteration 5: Historical trade routes geographic map

## Success Metrics

Measure each iteration on:

1. **Functionality** (0-10): Does it work as specified?
2. **Visual Appeal** (0-10): Is it aesthetically pleasing?
3. **Code Quality** (0-10): Is code clean and maintainable?
4. **Innovation** (0-10): Does it introduce novel ideas?
5. **Pattern Adoption** (0-10): Does it use library patterns effectively?

**Overall Quality Score** = Average of all metrics

**Pattern Effectiveness** = (Post-pattern avg) - (Pre-pattern avg)

## Example Output Structure

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[Visualization Title]</title>
  <style>
    /* Embedded CSS */
  </style>
</head>
<body>
  <!-- Visualization HTML -->

  <script>
    // Embedded JavaScript
    // Implements patterns from library (if available)
    // Adds unique innovation
  </script>
</body>
</html>
```

## Notes for Pattern Synthesis

- **First Wave**: Generates without pattern library, explores diverse approaches
- **Pattern Extraction**: Identifies 3-5 best patterns per category from first wave
- **Subsequent Waves**: Use pattern library as multi-shot examples for consistency
- **Continuous Learning**: Library evolves with each wave, quality bar rises
- **Innovation Encouraged**: Patterns are foundation, not limitation

## Expected Outcomes

After 20 iterations with pattern synthesis:

1. **Consistent Quality**: Last 5 iterations should have <10% variance in quality scores
2. **Pattern Adoption**: 80%+ of iterations should use 2+ library patterns
3. **Continuous Innovation**: Each iteration adds something novel despite using patterns
4. **Established Style**: Clear "house style" emerges while maintaining creativity
5. **Reusable Patterns**: Library becomes valuable resource for future projects

This demonstrates the power of cross-iteration pattern synthesis - cumulative learning that improves quality while preserving diversity and innovation.
