# Example Specification with Quality Criteria

## Overview

This specification demonstrates how to write specs for the Quality Evaluation & Ranking System. It includes explicit quality criteria that enable automated evaluation.

## What to Generate

**Component Type**: Interactive Data Visualization Card

**Description**: A self-contained HTML file featuring an interactive data visualization with controls, animations, and responsive design.

## Requirements

### Functional Requirements

1. **Data Visualization**
   - Display meaningful data using charts, graphs, or visual representations
   - Support at least one dataset with minimum 20 data points
   - Implement smooth transitions and animations

2. **Interactivity**
   - Provide user controls (buttons, sliders, dropdowns)
   - Respond to user input with visual feedback
   - Support hover states and tooltips

3. **Responsiveness**
   - Adapt layout to different screen sizes
   - Maintain readability on mobile and desktop
   - Scale visualizations appropriately

4. **Performance**
   - Render visualization within 500ms
   - Maintain 60fps for animations
   - Efficiently handle data updates

### Technical Requirements

1. **File Structure**
   - Single HTML file (self-contained)
   - Embedded CSS in `<style>` tag
   - Embedded JavaScript in `<script>` tag

2. **Dependencies**
   - May use CDN-hosted libraries (D3.js, Chart.js, etc.)
   - No build process required
   - No external file dependencies

3. **Code Quality**
   - Well-commented code
   - Modular function structure
   - Descriptive variable names
   - Error handling for edge cases

4. **Naming Convention**
   ```
   visualization_{iteration_number}_{theme}.html
   ```
   Example: `visualization_001_climate.html`

### Design Requirements

1. **Visual Design**
   - Cohesive color scheme (3-5 colors)
   - Clear typography hierarchy
   - Appropriate use of white space
   - Professional aesthetic

2. **User Experience**
   - Intuitive controls
   - Clear labels and legends
   - Helpful tooltips
   - Smooth interactions

3. **Accessibility**
   - Sufficient color contrast
   - Keyboard navigation support
   - Screen reader friendly labels
   - Clear focus indicators

## Quality Criteria

These criteria are used for automated quality evaluation:

### Technical Quality (35% weight)

**Code Quality (25 points)**
- Clean, readable code structure
- Consistent formatting and style
- Appropriate comments explaining complex logic
- No redundant or dead code
- DRY principle applied

**Architecture (25 points)**
- Modular function design
- Clear separation of concerns
- Reusable components
- Logical code organization
- Scalable structure

**Performance (25 points)**
- Fast initial render (< 500ms)
- Smooth animations (60fps)
- Efficient data processing
- Optimized DOM manipulation
- No memory leaks

**Robustness (25 points)**
- Input validation
- Error handling
- Edge case coverage
- Browser compatibility
- Graceful degradation

### Creativity Score (35% weight)

**Originality (25 points)**
- Novel visualization approach
- Unique interaction patterns
- Fresh perspective on data presentation
- Innovative use of web technologies

**Innovation (25 points)**
- Creative problem-solving
- Unexpected features
- Clever technical solutions
- Pushing boundaries of conventional design

**Uniqueness (25 points)**
- Differentiation from other iterations
- Distinctive visual identity
- Unique theme/topic selection
- Memorable user experience

**Aesthetic (25 points)**
- Visual appeal
- Design sophistication
- Color harmony
- Typography excellence
- Professional polish

### Spec Compliance (30% weight)

**Requirements Met (40 points)**
- All functional requirements implemented
- All technical requirements satisfied
- All design requirements addressed
- Complete feature set

**Naming Conventions (20 points)**
- Follows naming pattern exactly
- Appropriate iteration numbering
- Descriptive theme identifier
- Correct file extension

**Structure Adherence (20 points)**
- Single HTML file structure
- Embedded CSS and JS
- Proper use of CDN libraries
- No external dependencies

**Quality Standards (20 points)**
- Meets code quality baseline
- Satisfies accessibility requirements
- Achieves performance targets
- Demonstrates professional craftsmanship

## Themes & Creative Directions

Each iteration should explore a unique theme. Suggested themes:

**Data Themes:**
- Climate data (temperature, emissions, sea level)
- Economic data (stock prices, GDP, employment)
- Scientific data (astronomy, biology, chemistry)
- Social data (demographics, migration, education)
- Geographic data (population, resources, terrain)

**Visual Styles:**
- Minimalist
- Retro/vintage
- Futuristic/sci-fi
- Organic/natural
- Abstract/geometric
- Playful/whimsical
- Corporate/professional
- Artistic/experimental

**Interaction Styles:**
- Direct manipulation
- Parametric controls
- Time-based animation
- Gesture-driven
- Voice-controlled
- Game-like
- Story-driven
- Exploratory

## Evaluation Process

Each iteration will be evaluated using:

1. **Automated Technical Analysis**
   - Code quality metrics
   - Performance profiling
   - Architecture assessment
   - Robustness testing

2. **Creative Assessment**
   - Originality scoring
   - Innovation detection
   - Uniqueness comparison
   - Aesthetic evaluation

3. **Compliance Verification**
   - Requirements checklist
   - Naming validation
   - Structure verification
   - Standards audit

4. **Composite Scoring**
   - Weight dimensions: 35% technical, 35% creative, 30% compliance
   - Calculate composite score (0-100)
   - Generate detailed evaluation report

## Success Examples

**High Technical Quality Example:**
```javascript
// Clean, modular code structure
class DataVisualizer {
  constructor(data, config) {
    this.validateInputs(data, config);
    this.data = this.processData(data);
    this.config = { ...this.defaults, ...config };
    this.initialize();
  }

  validateInputs(data, config) {
    if (!Array.isArray(data) || data.length < 20) {
      throw new Error('Data must be array with minimum 20 points');
    }
    // ... more validation
  }

  processData(data) {
    // Efficient data transformation
    return data.map(d => ({
      ...d,
      normalized: this.normalize(d.value)
    }));
  }

  render() {
    // Optimized rendering with requestAnimationFrame
    requestAnimationFrame(() => {
      this.drawVisualization();
    });
  }
}
```

**High Creativity Example:**
- Unique spiral timeline visualization
- Data points represented as celestial bodies
- Gravity-based interaction model
- Poetic hover tooltips with haiku format
- Musical tones on data point selection

**Perfect Compliance Example:**
- File: `visualization_042_ocean_temperatures.html`
- All requirements met: interactive, responsive, performant
- Single self-contained HTML file
- CDN libraries for D3.js
- Professional code quality with comments

## Output Format

Each generated iteration should include:

1. **Complete Implementation**
   - Fully functional HTML file
   - All features working
   - Production-ready code

2. **Documentation Comments**
   ```html
   <!--
   Visualization: {theme_name}
   Iteration: {number}
   Creative Direction: {direction}
   Data Source: {source}
   Key Features:
   - {feature_1}
   - {feature_2}
   - {feature_3}

   Quality Self-Assessment:
   - Technical: {thoughts_on_technical_quality}
   - Creative: {thoughts_on_creativity}
   - Compliance: {thoughts_on_spec_adherence}
   -->
   ```

3. **Self-Assessment Section**
   - Brief reflection on quality dimensions
   - Identification of strengths
   - Acknowledgment of trade-offs made

## Iteration Uniqueness

Each iteration MUST be genuinely unique:

- Different data theme/topic
- Different visual style
- Different interaction approach
- Different technical implementation choices
- Different color schemes and typography

Avoid:
- Copying previous iterations with minor tweaks
- Reusing same visualization types repeatedly
- Similar color schemes across iterations
- Identical interaction patterns

## Quality Improvement Guidelines

For iterations to improve over time:

1. **Learn from Top Performers**
   - Study high-ranked iterations
   - Extract successful patterns
   - Adapt techniques appropriately

2. **Address Weaknesses**
   - Identify common failure modes
   - Strengthen weak quality dimensions
   - Avoid repeated mistakes

3. **Push Boundaries**
   - Try increasingly ambitious features
   - Experiment with novel approaches
   - Balance innovation with reliability

4. **Maintain Balance**
   - Don't sacrifice one dimension for another
   - Aim for multi-dimensional excellence
   - Seek synergies between quality aspects

---

**Version**: 1.0
**Last Updated**: 2025-10-10
**Quality System**: Automated evaluation with ReAct reasoning pattern