Document Dashboard Structure Stage in BID Framework

This function documents the structure of the dashboard with automatic layout selection and generates ranked, concept-grouped actionable UI/UX suggestions. Layout is intelligently chosen based on content analysis of previous stages using deterministic heuristics. Returns structured recommendations with specific component pointers and implementation rationales.

Usage

bid_structure(
  previous_stage,
  concepts = NULL,
  telemetry_flags = NULL,
  quiet = NULL,
  ...
)

Arguments

previous_stage: A tibble or list output from an earlier BID stage function.
concepts: A character vector of additional BID concepts to include. Concepts can be provided in natural language (e.g., "Principle of Proximity") or with underscores (e.g., "principle_of_proximity"). The function uses fuzzy matching to identify the concepts. If NULL, will detect relevant concepts from previous stages automatically.
telemetry_flags: Optional named list of telemetry flags from bid_flags(). Used to adjust layout choice and suggestion scoring based on observed user behavior patterns.
quiet: Logical indicating whether to suppress informational messages. If NULL, uses getOption("bidux.quiet", FALSE).
...: Additional parameters. If layout is provided via ..., the function will abort with a helpful error message.

Value

A bid_stage object containing:

stage: "Structure"
layout: Auto-selected layout type
suggestions: List of concept groups with ranked suggestions
concepts: Comma-separated string of all concepts used

Details

Layout Auto-Selection: For backwards compatibility with versions < 0.3.0; to be removed in 0.4.0. Uses deterministic heuristics to analyze content from previous stages and select the most appropriate layout:

breathable: For information overload/confusion patterns
dual_process: For overview vs detail needs
grid: For grouping/comparison requirements
card: For modular/chunked content
tabs: For categorical organization (unless telemetry shows issues)

Suggestion Engine: Generates ranked, actionable recommendations grouped by UX concepts. Each suggestion includes specific Shiny/bslib components, implementation details, and rationale. Suggestions are scored based on relevance, layout appropriateness, and contextual factors.

Examples

notice_result <- bid_interpret(
  central_question = "How can we simplify data presentation?",
  data_story = list(
    hook = "Data is too complex",
    context = "Overloaded with charts",
    tension = "Confusing layout",
    resolution = "Introduce clear grouping"
  )
) |>
  bid_notice(
    problem = "Users struggle with information overload",
    evidence = "Survey results indicate delays"
  )
#> Stage 1 (Interpret) completed.
#>   - Central question: How can we simplify data presentation?
#>   - Your data story has all key elements. Focus on making each component compelling and relevant.
#>   - Your central question is appropriately scoped.
#>   - No user personas defined 
#> Auto-suggested theory: Processing Fluency (confidence: 70%)
#> Stage 2 (Notice) completed. (40% complete)
#>   - Problem: Users struggle with information overload
#>   - Theory: Processing Fluency (auto-suggested)
#>   - Evidence: Survey results indicate delays
#>   - Theory confidence: 70%
#>   - Next: Use bid_anticipate() for Stage 3 

# Auto-selected layout with concept-grouped suggestions
structure_result <- bid_structure(previous_stage = notice_result)
#> ℹ Auto-selected layout: breathable
#> ℹ Detected information overload patterns; choosing 'breathable' to reduce cognitive load.
#> Warning: Layout auto-selection is deprecated and will be removed in bidux 0.4.0. The BID framework will focus on concept-based suggestions instead. Existing code will continue to work until 0.4.0.
#> ℹ Tip: Learn more about any concept via bid_concept("<concept>").
#> Stage 4 (Structure) completed.
#>   - Auto-selected layout: breathable
#>   - Concept groups generated: 4
#>   - Total concepts: 4 
print(structure_result$layout) # Auto-selected layout
#> [1] "breathable" "breathable" "breathable" "breathable"
print(structure_result$suggestions) # Ranked suggestions by concept
#> [[1]]
#> [[1]]$concept
#> [1] "Cognitive Load Theory"
#> 
#> [[1]]$suggestions
#> [[1]]$suggestions[[1]]
#> [[1]]$suggestions[[1]]$title
#> [1] "Limit initial choices"
#> 
#> [[1]]$suggestions[[1]]$details
#> [1] "Show only core filters by default; defer advanced options to secondary views or accordions."
#> 
#> [[1]]$suggestions[[1]]$components
#> [1] "bslib::accordion"            "shiny::conditionalPanel"    
#> [3] "shiny::updateSelectizeInput"
#> 
#> [[1]]$suggestions[[1]]$rationale
#> [1] "Reduces initial cognitive load for new users while preserving functionality."
#> 
#> [[1]]$suggestions[[1]]$score
#> [1] 1
#> 
#> 
#> [[1]]$suggestions[[2]]
#> [[1]]$suggestions[[2]]$title
#> [1] "Use progressive complexity"
#> 
#> [[1]]$suggestions[[2]]$details
#> [1] "Start with simple views and allow users to add complexity incrementally."
#> 
#> [[1]]$suggestions[[2]]$components
#> [1] "shiny::tabsetPanel"  "bslib::accordion"    "shiny::actionButton"
#> 
#> [[1]]$suggestions[[2]]$rationale
#> [1] "Prevents overwhelming users with too many options at once."
#> 
#> [[1]]$suggestions[[2]]$score
#> [1] 0.91
#> 
#> 
#> [[1]]$suggestions[[3]]
#> [[1]]$suggestions[[3]]$title
#> [1] "Provide smart defaults"
#> 
#> [[1]]$suggestions[[3]]$details
#> [1] "Pre-select commonly used filters and settings to reduce decision fatigue."
#> 
#> [[1]]$suggestions[[3]]$components
#> [1] "shiny::selectInput"   "shiny::checkboxInput" "bslib::input_switch" 
#> 
#> [[1]]$suggestions[[3]]$rationale
#> [1] "Leverages the Default Effect to reduce cognitive burden."
#> 
#> [[1]]$suggestions[[3]]$score
#> [1] 0.88
#> 
#> 
#> 
#> 
#> [[2]]
#> [[2]]$concept
#> [1] "Visual Hierarchy"
#> 
#> [[2]]$suggestions
#> [[2]]$suggestions[[1]]
#> [[2]]$suggestions[[1]]$title
#> [1] "Establish clear information priority"
#> 
#> [[2]]$suggestions[[1]]$details
#> [1] "Use size, color, and spacing to guide attention to key metrics first."
#> 
#> [[2]]$suggestions[[1]]$components
#> [1] "bslib::card"      "shiny::h1"        "shiny::h2"        "bslib::value_box"
#> 
#> [[2]]$suggestions[[1]]$rationale
#> [1] "Helps users quickly identify what matters most in the interface."
#> 
#> [[2]]$suggestions[[1]]$score
#> [1] 0.9
#> 
#> 
#> [[2]]$suggestions[[2]]
#> [[2]]$suggestions[[2]]$title
#> [1] "Group related content visually"
#> 
#> [[2]]$suggestions[[2]]$details
#> [1] "Use consistent spacing and visual containers to show relationships."
#> 
#> [[2]]$suggestions[[2]]$components
#> [1] "bslib::layout_columns" "bslib::card"           "shiny::fluidRow"      
#> 
#> [[2]]$suggestions[[2]]$rationale
#> [1] "Leverages Gestalt principles to reduce cognitive processing."
#> 
#> [[2]]$suggestions[[2]]$score
#> [1] 0.87
#> 
#> 
#> 
#> 
#> [[3]]
#> [[3]]$concept
#> [1] "Progressive Disclosure"
#> 
#> [[3]]$suggestions
#> [[3]]$suggestions[[1]]
#> [[3]]$suggestions[[1]]$title
#> [1] "Use collapsible advanced filters"
#> 
#> [[3]]$suggestions[[1]]$details
#> [1] "Place seldom-used filters in accordion sections or 'Show more' toggles."
#> 
#> [[3]]$suggestions[[1]]$components
#> [1] "bslib::accordion"        "shiny::conditionalPanel"
#> 
#> [[3]]$suggestions[[1]]$rationale
#> [1] "Reveals complexity on demand without overwhelming the interface."
#> 
#> [[3]]$suggestions[[1]]$score
#> [1] 0.88
#> 
#> 
#> [[3]]$suggestions[[2]]
#> [[3]]$suggestions[[2]]$title
#> [1] "Implement drill-down navigation"
#> 
#> [[3]]$suggestions[[2]]$details
#> [1] "Allow users to start with summaries and progressively reveal details."
#> 
#> [[3]]$suggestions[[2]]$components
#> [1] "shiny::actionButton"  "DT::datatable"        "reactable::reactable"
#> 
#> [[3]]$suggestions[[2]]$rationale
#> [1] "Matches user mental models of exploration from general to specific."
#> 
#> [[3]]$suggestions[[2]]$score
#> [1] 0.84
#> 
#> 
#> 
#> 
#> [[4]]
#> [[4]]$concept
#> [1] "Processing Fluency"
#> 
#> [[4]]$suggestions
#> [[4]]$suggestions[[1]]
#> [[4]]$suggestions[[1]]$title
#> [1] "Apply Processing Fluency principles"
#> 
#> [[4]]$suggestions[[1]]$details
#> [1] "Consider how Processing Fluency applies to your breathable layout design."
#> 
#> [[4]]$suggestions[[1]]$components
#> [1] "bslib::card"           "shiny::fluidRow"       "bslib::layout_columns"
#> 
#> [[4]]$suggestions[[1]]$rationale
#> [1] "Systematic application of Processing Fluency can improve user experience."
#> 
#> [[4]]$suggestions[[1]]$score
#> [1] 0.75
#> 
#> 
#> 
#> 

summary(structure_result)
#> === BID Framework: Structure Stage Summary ===
#> 
#> Metadata:
#>    layout_type : breathable 
#>    auto_selected_layout : Yes 
#>    concepts_count : 4 
#>    suggestion_groups_count : 4 
#>    stage_number : 4 
#>    stage_number_previous : 3 
#>    total_stages : 5 
#> 
#> Stage Data:
#>    stage : Structure 
#>    layout : breathable 
#>    concepts : Cognitive Load Theory, Visual Hierarchy, Progressive Disclosure, Processing F... 
#>    previous_problem : Users struggle with information overload 
#>    previous_theory : Processing Fluency 
#>    suggestions : list(concept = "Cognitive Load Theory", suggestions = list(list(title = "Limi... 
#> 
#> Generated: 2025-09-23 23:04:52