# Example Specification: Interactive Data Dashboard Components

## Purpose/Overview

This specification defines the requirements for generating unique, self-contained interactive data dashboard components. Each iteration should demonstrate a different data visualization technique, interaction pattern, or dashboard layout while maintaining professional quality and complete functionality.

**Goal:** Create a diverse collection of dashboard components that showcase various approaches to data presentation, interaction design, and visual communication.

**Use Case:** These components serve as a reference library for dashboard development, demonstrating best practices and creative approaches to data visualization.

**Success Criteria:**
- Each component is fully functional and self-contained
- Professional visual design and user experience
- Unique visualization or interaction approach per iteration
- Clear, well-documented code
- Responsive and accessible

## Output Structure

Each iteration must include:

### File Components
1. **Main HTML file** - Complete dashboard component
   - Full HTML document structure
   - Inline or linked CSS styles
   - Inline or linked JavaScript code
   - Sample data embedded or linked

2. **Documentation section** (within HTML comments or separate section)
   - Component purpose
   - Visualization technique used
   - Interaction features
   - Data structure expected
   - Usage instructions

### HTML Structure Requirements
```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>[Dashboard Name] - Iteration [N]</title>
    <style>
        /* Component styles */
    </style>
</head>
<body>
    <!-- Dashboard component -->
    <div class="dashboard-container">
        <!-- Visualization content -->
    </div>

    <script>
        // Component logic and interactivity
    </script>
</body>
</html>
```

### Required Sections/Components
- **Header/Title** - Component name and description
- **Data Visualization** - Main chart, graph, or display
- **Interactive Controls** - Filters, toggles, or input elements
- **Legend/Key** - Explanation of visual elements
- **Metadata** - Iteration number, technique used, data source

## Naming Conventions

### Pattern
```
dashboard_iteration_[NN]_[theme].html
```

### Components
- `NN` - Two-digit iteration number (01, 02, 03, ...)
- `theme` - Short descriptor of visualization technique or data type

### Examples
- `dashboard_iteration_01_sales_trends.html`
- `dashboard_iteration_02_network_graph.html`
- `dashboard_iteration_03_geographic_heatmap.html`
- `dashboard_iteration_04_time_series_comparison.html`
- `dashboard_iteration_05_hierarchical_treemap.html`

### Rules
- Use lowercase for all parts
- Use underscores to separate words
- Theme should be 2-4 words maximum
- Theme should clearly indicate the visualization approach or data type

## Quality Standards

### Minimum Requirements

**Functionality:**
- Component loads without errors
- All interactive elements work correctly
- Data visualization renders properly
- Responsive to different screen sizes
- Accessible (proper semantic HTML, ARIA labels)

**Code Quality:**
- Valid HTML5 syntax
- Well-organized CSS (logical grouping, consistent naming)
- Clean JavaScript (no console errors, proper scoping)
- Comments explaining key logic
- Consistent formatting and indentation

**Visual Design:**
- Professional appearance
- Thoughtful color scheme (accessible contrast)
- Clear typography hierarchy
- Proper spacing and alignment
- Polished, finished look (not prototype quality)

**Documentation:**
- Clear component description
- Explanation of visualization technique
- List of interaction features
- Data structure documentation
- Usage instructions

### Excellence Criteria (for high-quality iterations)

**Innovation:**
- Creative visualization approach
- Unique interaction pattern
- Novel data presentation
- Thoughtful design details

**User Experience:**
- Intuitive interactions
- Smooth animations/transitions
- Helpful feedback and guidance
- Delightful micro-interactions

**Technical Sophistication:**
- Efficient code
- Advanced visualization techniques
- Clever data transformations
- Sophisticated interactions

## Uniqueness Constraints

### What Must Be Unique Per Iteration

**Primary Variation Dimension:**
Each iteration must use a **different visualization technique or chart type**, such as:
- Bar chart (horizontal, vertical, grouped, stacked)
- Line chart (single, multiple, area)
- Pie/donut chart
- Scatter plot
- Bubble chart
- Heatmap
- Network/graph visualization
- Treemap or sunburst
- Gauge or meter
- Timeline visualization
- Geographic map
- Sankey diagram
- Radar/spider chart
- Box plot
- Candlestick chart

**Secondary Variation Dimensions (at least one must differ):**
- **Data domain:** Sales, finance, health, environment, social, education, etc.
- **Interaction pattern:** Hover tooltips, click filtering, drag controls, zoom/pan, etc.
- **Layout style:** Grid, single panel, multi-panel, sidebar, full-screen, etc.
- **Visual theme:** Minimalist, colorful, dark mode, high contrast, playful, corporate, etc.

### What Can Be Similar

**Acceptable similarities:**
- Overall HTML structure (DOCTYPE, basic tags)
- Code organization approach (CSS in head, JS in body)
- Responsive design techniques
- Accessibility patterns
- General color palette principles (though specific colors should vary)

### Duplication Boundaries

**Not acceptable:**
- Exact same chart type with only data changed
- Identical interaction patterns with different visuals
- Copy-paste code with minimal modifications
- Same layout with different colors only

**Acceptable:**
- Using similar libraries (D3.js, Chart.js, etc.) across iterations
- Reusing responsive design patterns
- Applying common accessibility practices
- Following consistent code style conventions

## How Utilities Help With This Spec

### /validate-spec
Before generating iterations:
- Confirms all required sections are present
- Verifies naming pattern is clear and unambiguous
- Checks that uniqueness constraints are well-defined
- Ensures quality standards are measurable

**Example benefit:** Catches missing variation dimensions early, preventing similar outputs.

### /analyze
After generating a batch:
- Identifies which visualization techniques have been used
- Detects if theme diversity is sufficient
- Spots unintended duplications or too-similar approaches
- Suggests unexplored visualization types or data domains

**Example benefit:** Reveals that 3 iterations all used bar charts, suggesting need for more variety.

### /test-output
After generation:
- Validates HTML syntax correctness
- Checks that all required sections are present
- Verifies naming convention compliance
- Tests that interactive elements are implemented
- Confirms documentation is complete

**Example benefit:** Catches iteration with missing interactive controls before user review.

### /debug
When issues occur:
- Diagnoses why iterations aren't sufficiently unique
- Identifies if spec guidance was unclear
- Traces root cause of quality issues
- Provides specific remediation steps

**Example benefit:** Determines that vague theme descriptions led to similar outputs, suggests spec refinement.

### /status
During long-running generation:
- Shows how many iterations completed
- Displays current quality scores
- Indicates if generation is on track
- Estimates time remaining

**Example benefit:** User can monitor 20-iteration batch and see progress without waiting for completion.

### /report
After generation completes:
- Summarizes visualization techniques used
- Analyzes quality distribution
- Compares against quality standards
- Recommends areas for improvement

**Example benefit:** Comprehensive report shows 18/20 iterations met excellence criteria, highlights two for revision.

## Chain-of-Thought Application

This specification demonstrates chain-of-thought principles:

1. **Clear reasoning for requirements** - Each section explains WHY, not just WHAT
2. **Explicit decision criteria** - Quality standards are specific and measurable
3. **Transparent variation logic** - Uniqueness constraints show reasoning about what matters
4. **Actionable guidance** - Sub-agents can follow step-by-step to create valid iterations
5. **Utility integration** - Shows how each utility command helps verify spec compliance

By making requirements explicit and reasoning transparent, sub-agents can better understand the intent and produce higher-quality outputs that truly meet the specification.
