# Example Specification: Interactive Data Visualization

**Spec Version:** 1.0.0
**Template Compatibility:** web-research-generator, code-generator
**Output Format:** HTML with embedded JavaScript

---

## Overview

Generate interactive data visualizations that demonstrate progressive learning from web resources or creative code generation.

## Output Requirements

### File Naming Pattern

```
viz_{{theme}}_{{number}}.html
```

- `theme`: Descriptive theme (e.g., "network", "timeline", "hierarchy", "flow")
- `number`: Zero-padded 3-digit iteration number (e.g., 001, 002, 025)

**Examples:**
- `viz_network_001.html`
- `viz_timeline_007.html`
- `viz_hierarchy_015.html`

### File Structure

Each visualization must be a complete, standalone HTML file with:

1. **Document Header:**
   ```html
   <!DOCTYPE html>
   <html lang="en">
   <head>
       <meta charset="UTF-8">
       <meta name="viewport" content="width=device-width, initial-scale=1.0">
       <title>{{Theme}} Visualization - Iteration {{Number}}</title>
       <!-- Attribution comment block here -->
   </head>
   ```

2. **Attribution Block:**
   ```html
   <!--
   Visualization: {{theme}} (Iteration {{number}})

   [For web-research-generator template:]
   Web Source: {{web_url}}
   Learning Focus: {{learning_focus}}
   Techniques Applied:
     1. {{technique_1}}
     2. {{technique_2}}
     3. {{technique_3}}

   [For code-generator template:]
   Theme: {{theme}}
   Unique Characteristics: {{unique_features}}

   Generated: {{timestamp}}
   Template: {{template_name}}
   -->
   ```

3. **Styles Section:**
   - CSS for visualization layout
   - Responsive design considerations
   - Professional appearance

4. **Content Area:**
   - SVG or Canvas element for visualization
   - Interactive controls if applicable
   - Legend or key explaining visualization

5. **Script Section:**
   - Visualization logic
   - Data generation or loading
   - Interaction handlers
   - Comments explaining techniques

### Required Functionality

1. **Visual Display:**
   - Clear, readable visualization
   - Professional appearance
   - Appropriate color scheme
   - Responsive to window size

2. **Interactivity:**
   - At least one interactive element (hover, click, drag, etc.)
   - Smooth transitions or animations
   - Visual feedback for interactions

3. **Data:**
   - Realistic or meaningful sample data
   - Sufficient data points to demonstrate visualization
   - Data clearly represented

4. **Documentation:**
   - Inline comments explaining key sections
   - Attribution of techniques (for web-research-generator)
   - Clear variable and function names

### Quality Standards

1. **Technical Quality:**
   - No JavaScript errors
   - Valid HTML5
   - Cross-browser compatible (modern browsers)
   - Efficient code (no unnecessary loops or operations)

2. **Visual Quality:**
   - Professional appearance
   - Readable text
   - Appropriate spacing
   - Color scheme with good contrast

3. **Code Quality:**
   - Well-organized and structured
   - Meaningful names
   - Commented appropriately
   - No code duplication

4. **Uniqueness:**
   - Different theme/approach from existing iterations
   - Novel combination of techniques (for web-research)
   - Creative interpretation

### Web Research Guidelines (for web-research-generator template)

When using the web-research-generator template:

1. **Extract Specific Techniques:**
   - Focus on concrete, implementable techniques
   - Look for code examples and patterns
   - Identify API methods or functions
   - Note design patterns or architectures

2. **Apply Learning:**
   - Use extracted techniques directly in implementation
   - Combine multiple techniques
   - Adapt techniques to fit theme
   - Document where each technique is applied

3. **Demonstrate Learning:**
   - Add comments showing technique application
   - Reference web source in code
   - Explain how technique enhances visualization

### Validation Checklist

Before considering a visualization complete, verify:

- [ ] File name follows pattern: `viz_{{theme}}_{{number}}.html`
- [ ] Attribution block present and complete
- [ ] HTML is valid and complete
- [ ] Visualization renders correctly
- [ ] At least one interactive element works
- [ ] No JavaScript errors in console
- [ ] Code is well-commented
- [ ] Unique theme/approach from existing iterations
- [ ] Professional appearance
- [ ] For web-research: Techniques from web source clearly applied

---

## Template Parameter Mappings

### For web-research-generator

```json
{
  "PROJECT_NAME": "Interactive Data Visualizations",
  "PROJECT_DESCRIPTION": "Progressive learning of visualization techniques from web resources",
  "SPEC_FILE": "specs/example_spec.md",
  "OUTPUT_DIR": "viz_output",
  "NAMING_PATTERN": "viz_{{theme}}_{{number}}.html",
  "MIN_TECHNIQUES": 2,
  "LEARNING_FOCUS": "[Varies by URL - e.g., 'D3 selection patterns', 'SVG path manipulation']"
}
```

### For code-generator

```json
{
  "PROJECT_NAME": "Interactive Data Visualizations",
  "PROJECT_DESCRIPTION": "Creative visualization implementations",
  "SPEC_FILE": "specs/example_spec.md",
  "OUTPUT_DIR": "viz_output",
  "NAMING_PATTERN": "viz_{{theme}}_{{number}}.html"
}
```

---

## Example Themes

**Network Themes:**
- Social network graph
- Neural network visualization
- Transportation network
- Ecosystem relationships

**Timeline Themes:**
- Historical events
- Project milestones
- Scientific discoveries
- Personal journey

**Hierarchy Themes:**
- Organizational chart
- File system tree
- Taxonomy
- Decision tree

**Flow Themes:**
- Sankey diagram
- Process flow
- Data pipeline
- Energy flow

---

## Success Criteria

A visualization is considered successful when:

1. All technical requirements met
2. Visually professional and polished
3. Interactivity smooth and intuitive
4. Code is clean and well-documented
5. Genuinely unique from other iterations
6. Demonstrates learning (for web-research template)
7. Can run standalone without errors

---

**Specification Design:** This spec is optimized for use with pluggable templates, providing clear requirements that can be parameterized and instantiated across multiple agents.
