# Data Visualization Template
# Standardized template for data visualization design and implementation across the AI Agentic Data Stack Framework

metadata:
  template_id: "data-visualization-tmpl"
  name: "Data Visualization Template"
  version: "1.0.0"
  description: "Comprehensive template for creating effective data visualizations with best practices, accessibility, and user experience optimization"
  category: "data-visualization"
  tags: ["visualization", "charts", "graphs", "accessibility", "storytelling", "design"]
  created_by: "AI Agentic Data Stack Framework"
  created_date: "2025-01-23"

# Template Structure
template:
  name: "Data Visualization Template"
  description: "Template for creating effective data visualizations with accessibility and user experience optimization"
  version: "1.0.0"

sections:
  - visualization_config
  - data_config
  - visual_design
  - chart_elements
  - interactivity
  - animation
  - accessibility
  - responsive_design
  - performance
  - export_options
  - quality_assurance

# Visualization Configuration
visualization_config:
  # Basic Information
  visualization_id: "${visualization_id}"
  title: "${visualization_title}"
  subtitle: "${visualization_subtitle}"
  description: "${visualization_description}"
  purpose: "${visualization_purpose}" # explore, explain, exhibit, entertain
  
  # Visualization Type
  chart_type: "${chart_type}" # bar, line, pie, scatter, area, histogram, heatmap, treemap, sankey, network
  chart_subtype: "${chart_subtype}" # stacked, grouped, horizontal, vertical, filled, stepped
  
  # Context and Audience
  context:
    audience: "${target_audience}" # executive, analyst, general, technical
    usage_context: "${usage_context}" # presentation, dashboard, report, exploration
    decision_type: "${decision_type}" # strategic, operational, tactical, informational
    
  # Data Story
  narrative:
    key_message: "${key_message}"
    story_structure: "${story_structure}" # problem-solution, before-after, comparison, trend
    call_to_action: "${call_to_action}"

# Data Configuration
data_config:
  # Data Source
  source:
    type: "${data_source_type}" # database, api, file, stream
    connection: "${data_connection}"
    query: "${data_query}"
    
  # Data Processing
  processing:
    filters: ["${data_filters}"]
    aggregations: ["${data_aggregations}"]
    transformations: ["${data_transformations}"]
    sorting: "${data_sorting}"
    
  # Data Quality
  quality_checks:
    completeness_threshold: ${completeness_threshold}
    accuracy_validation: ${accuracy_validation_enabled}
    outlier_detection: ${outlier_detection_enabled}
    freshness_check: ${freshness_check_enabled}
    
  # Data Structure
  structure:
    dimensions: ["${dimension_fields}"]
    measures: ["${measure_fields}"]
    time_field: "${time_field}"
    categorical_fields: ["${categorical_fields}"]
    numerical_fields: ["${numerical_fields}"]

# Visual Design Configuration
visual_design:
  # Color Strategy
  color_strategy:
    approach: "${color_approach}" # sequential, diverging, categorical, custom
    palette_name: "${color_palette}"
    color_count: ${color_count}
    
    # Specific Colors
    colors:
      primary: "${primary_color}"
      secondary: "${secondary_color}"
      accent: "${accent_color}"
      neutral: "${neutral_color}"
      background: "${background_color}"
      
    # Color Accessibility
    accessibility:
      colorblind_safe: ${colorblind_safe}
      high_contrast: ${high_contrast_available}
      minimum_contrast_ratio: ${min_contrast_ratio}
      alternative_encoding: "${alternative_encoding}" # pattern, texture, shape
      
  # Typography
  typography:
    title_font: "${title_font_family}"
    title_size: ${title_font_size}
    title_weight: "${title_font_weight}"
    
    label_font: "${label_font_family}"
    label_size: ${label_font_size}
    label_weight: "${label_font_weight}"
    
    annotation_font: "${annotation_font_family}"
    annotation_size: ${annotation_font_size}
    
  # Layout and Spacing
  layout:
    width: ${visualization_width}
    height: ${visualization_height}
    aspect_ratio: "${aspect_ratio}"
    margins:
      top: ${margin_top}
      right: ${margin_right}
      bottom: ${margin_bottom}
      left: ${margin_left}
      
    padding:
      top: ${padding_top}
      right: ${padding_right}
      bottom: ${padding_bottom}
      left: ${padding_left}

# Chart-Specific Configuration
chart_elements:
  # Axes Configuration
  axes:
    x_axis:
      title: "${x_axis_title}"
      type: "${x_axis_type}" # linear, ordinal, time, log
      scale: "${x_scale_type}"
      tick_count: ${x_tick_count}
      tick_format: "${x_tick_format}"
      grid_lines: ${x_grid_lines_enabled}
      zero_line: ${x_zero_line_enabled}
      
    y_axis:
      title: "${y_axis_title}"
      type: "${y_axis_type}"
      scale: "${y_scale_type}"
      tick_count: ${y_tick_count}
      tick_format: "${y_tick_format}"
      grid_lines: ${y_grid_lines_enabled}
      zero_line: ${y_zero_line_enabled}
      start_at_zero: ${y_start_at_zero}
      
  # Legend Configuration
  legend:
    enabled: ${legend_enabled}
    position: "${legend_position}" # top, bottom, left, right, inside
    orientation: "${legend_orientation}" # horizontal, vertical
    title: "${legend_title}"
    
  # Data Labels
  data_labels:
    enabled: ${data_labels_enabled}
    position: "${label_position}" # inside, outside, center, end
    format: "${label_format}"
    rotation: ${label_rotation}
    
  # Reference Lines
  reference_lines:
    - type: "${reference_type}" # average, median, target, threshold
      value: ${reference_value}
      label: "${reference_label}"
      style: "${reference_style}" # solid, dashed, dotted
      color: "${reference_color}"

# Interactivity Configuration
interactivity:
  # Basic Interactions
  interactions:
    hover_enabled: ${hover_enabled}
    click_enabled: ${click_enabled}
    selection_enabled: ${selection_enabled}
    zoom_enabled: ${zoom_enabled}
    pan_enabled: ${pan_enabled}
    
  # Hover Effects
  hover:
    highlight_color: "${hover_highlight_color}"
    show_tooltip: ${hover_tooltip_enabled}
    cursor_style: "${hover_cursor}"
    
  # Tooltip Configuration
  tooltip:
    enabled: ${tooltip_enabled}
    content_template: "${tooltip_template}"
    position: "${tooltip_position}" # mouse, fixed, smart
    delay: ${tooltip_delay}
    
    # Tooltip Styling
    styling:
      background_color: "${tooltip_bg_color}"
      text_color: "${tooltip_text_color}"
      border_color: "${tooltip_border_color}"
      font_size: ${tooltip_font_size}
      
  # Drill-down and Filtering
  drill_down:
    enabled: ${drill_down_enabled}
    levels: ["${drill_down_levels}"]
    
  filtering:
    enabled: ${filtering_enabled}
    filter_types: ["${filter_types}"] # brush, click, menu
    
# Animation Configuration
animation:
  # Animation Settings
  enabled: ${animation_enabled}
  duration: ${animation_duration} # milliseconds
  easing: "${animation_easing}" # ease, ease-in, ease-out, linear
  delay: ${animation_delay}
  
  # Animation Types
  entrance_animation:
    type: "${entrance_type}" # fade, slide, grow, bounce
    duration: ${entrance_duration}
    stagger: ${entrance_stagger} # delay between elements
    
  transition_animation:
    type: "${transition_type}"
    duration: ${transition_duration}
    
  # Accessibility Considerations
  accessibility:
    respect_reduced_motion: ${respect_reduced_motion}
    provide_animation_controls: ${animation_controls_enabled}

# Accessibility Features
accessibility:
  # ARIA Labels and Descriptions
  aria_label: "${visualization_aria_label}"
  aria_description: "${visualization_aria_description}"
  
  # Alternative Text
  alt_text: "${visualization_alt_text}"
  long_description: "${visualization_long_description}"
  
  # Keyboard Navigation
  keyboard_navigation:
    enabled: ${keyboard_nav_enabled}
    tab_order: "${tab_order}"
    keyboard_shortcuts: ["${keyboard_shortcuts}"]
    
  # Screen Reader Support
  screen_reader:
    data_table_provided: ${data_table_provided}
    summary_provided: ${summary_provided}
    trend_description: "${trend_description}"
    
  # Visual Accessibility
  visual_accessibility:
    sufficient_contrast: ${sufficient_contrast}
    color_independent: ${color_independent_info}
    scalable_text: ${scalable_text_enabled}
    focus_indicators: ${focus_indicators_enabled}
    
  # Audio Description
  audio_description:
    enabled: ${audio_description_enabled}
    script: "${audio_script}"
    sonification: ${sonification_enabled}

# Responsive Design
responsive_design:
  # Breakpoints
  breakpoints:
    mobile:
      max_width: 480
      chart_modifications:
        - "simplify_design"
        - "reduce_data_points"
        - "stack_elements"
        - "increase_touch_targets"
        
    tablet:
      max_width: 768
      chart_modifications:
        - "adjust_font_sizes"
        - "reposition_legend"
        
    desktop:
      min_width: 769
      
  # Responsive Behavior
  behavior:
    maintain_aspect_ratio: ${maintain_aspect_ratio}
    scale_font_sizes: ${scale_fonts}
    adjust_margins: ${adjust_margins}
    reflow_content: ${reflow_content}
    
  # Mobile Optimizations
  mobile_optimizations:
    touch_friendly: ${touch_friendly_enabled}
    gesture_support: ${gesture_support}
    simplified_interactions: ${simplified_interactions}

# Performance Configuration
performance:
  # Data Optimization
  data_optimization:
    max_data_points: ${max_data_points}
    sampling_enabled: ${data_sampling_enabled}
    aggregation_level: "${aggregation_level}"
    
  # Rendering Optimization
  rendering:
    canvas_rendering: ${canvas_rendering_enabled}
    webgl_acceleration: ${webgl_enabled}
    progressive_rendering: ${progressive_rendering}
    lazy_loading: ${lazy_loading_enabled}
    
  # Caching
  caching:
    enabled: ${caching_enabled}
    cache_duration: ${cache_duration} # minutes
    cache_key: "${cache_key_pattern}"

# Export and Sharing
export_options:
  # Export Formats
  formats:
    png: ${png_export_enabled}
    svg: ${svg_export_enabled}
    pdf: ${pdf_export_enabled}
    csv: ${csv_export_enabled}
    json: ${json_export_enabled}
    
  # Export Settings
  settings:
    resolution: ${export_resolution} # DPI
    background_color: "${export_background}"
    include_title: ${export_include_title}
    include_legend: ${export_include_legend}
    
  # Sharing Options
  sharing:
    embed_code: ${embed_code_enabled}
    social_sharing: ${social_sharing_enabled}
    url_sharing: ${url_sharing_enabled}

# Quality Assurance
quality_assurance:
  # Design Validation
  design_validation:
    color_contrast_check: ${color_contrast_check}
    font_legibility_check: ${font_legibility_check}
    layout_consistency_check: ${layout_consistency_check}
    
  # Data Validation
  data_validation:
    accuracy_check: ${data_accuracy_check}
    completeness_check: ${data_completeness_check}
    consistency_check: ${data_consistency_check}
    
  # User Testing
  user_testing:
    comprehension_testing: ${comprehension_testing_enabled}
    usability_testing: ${usability_testing_enabled}
    accessibility_testing: ${accessibility_testing_enabled}

# Best Practices Configuration
best_practices:
  # Design Principles
  design_principles:
    clarity: ${clarity_prioritized}
    accuracy: ${accuracy_prioritized}
    efficiency: ${efficiency_prioritized}
    engagement: ${engagement_considered}
    
  # Cognitive Load Reduction
  cognitive_load:
    minimize_visual_clutter: ${minimize_clutter}
    progressive_disclosure: ${progressive_disclosure}
    consistent_conventions: ${consistent_conventions}
    clear_hierarchy: ${clear_hierarchy}
    
  # Storytelling Elements
  storytelling:
    clear_narrative: ${clear_narrative}
    appropriate_context: ${appropriate_context}
    actionable_insights: ${actionable_insights}
    emotional_connection: ${emotional_connection}

# Error Handling
error_handling:
  # Data Errors
  data_errors:
    no_data_message: "${no_data_message}"
    loading_error_message: "${loading_error_message}"
    invalid_data_message: "${invalid_data_message}"
    
  # Fallback Options
  fallbacks:
    fallback_chart_type: "${fallback_chart_type}"
    static_image_fallback: ${static_fallback_enabled}
    text_summary_fallback: ${text_fallback_enabled}
    
  # Error Recovery
  recovery:
    retry_mechanism: ${retry_enabled}
    alternative_data_source: "${alternative_source}"
    degraded_mode: ${degraded_mode_enabled}

# Customization Options
customization:
  # User Customization
  user_options:
    theme_selection: ${theme_selection_enabled}
    color_customization: ${color_customization_enabled}
    chart_type_switching: ${chart_switching_enabled}
    
  # Admin Customization
  admin_options:
    brand_customization: ${brand_customization_enabled}
    template_modification: ${template_modification_enabled}
    advanced_settings: ${advanced_settings_enabled}

# Validation Rules
validation_rules:
  required_fields:
    - visualization_id
    - title
    - chart_type
    - data_config.source
    
  field_constraints:
    chart_type:
      allowed_values: ["bar", "line", "pie", "scatter", "area", "histogram", "heatmap", "treemap", "sankey", "network"]
    purpose:
      allowed_values: ["explore", "explain", "exhibit", "entertain"]
    target_audience:
      allowed_values: ["executive", "analyst", "general", "technical"]
      
  accessibility_requirements:
    - aria_label: "required"
    - alt_text: "required"
    - sufficient_contrast: "required"
    - keyboard_navigation: "enabled"

# Chart Type Specific Configurations
chart_specific_configs:
  bar_chart:
    orientation: "${bar_orientation}" # horizontal, vertical
    stacking: "${bar_stacking}" # none, stacked, percentage
    gap_width: ${bar_gap_width}
    
  line_chart:
    line_style: "${line_style}" # solid, dashed, dotted
    line_width: ${line_width}
    markers_enabled: ${line_markers_enabled}
    area_fill: ${area_fill_enabled}
    
  pie_chart:
    start_angle: ${pie_start_angle}
    inner_radius: ${pie_inner_radius} # for donut charts
    slice_spacing: ${pie_slice_spacing}
    
  scatter_plot:
    point_size: ${scatter_point_size}
    point_opacity: ${scatter_point_opacity}
    trend_line: ${trend_line_enabled}
    
  heatmap:
    color_scale: "${heatmap_color_scale}"
    cell_border: ${heatmap_cell_border}
    value_display: ${heatmap_value_display}

# Usage Examples
examples:
  executive_kpi_chart:
    purpose: "exhibit"
    audience: "executive"
    chart_type: "bar"
    visual_design:
      color_strategy:
        approach: "categorical"
        colorblind_safe: true
        
  analytical_exploration:
    purpose: "explore"
    audience: "analyst"
    chart_type: "scatter"
    interactivity:
      drill_down:
        enabled: true
      filtering:
        enabled: true

# Documentation References
documentation:
  design_guidelines: "https://datavizcatalogue.com/"
  accessibility_standards: "https://www.w3.org/WAI/tutorials/images/complex/"
  color_theory: "https://colorbrewer2.org/"
  storytelling_guide: "https://storytelling-with-data.com/"
  
# Template Metadata
template_metadata:
  author: "AI Agentic Data Stack Framework"
  maintainer: "Data Experience Designer"
  last_updated: "2025-01-23"
  changelog:
    - version: "1.0.0"
      date: "2025-01-23"
      changes: "Initial template creation with comprehensive data visualization configuration"