Getting Started with bidux

Introduction

The {bidux} package helps Shiny developers create more effective dashboards using the Behavior Insight Design (BID) Framework. This framework integrates psychological principles, UX best practices, and data storytelling techniques to guide the development of dashboards that are easier to understand, more engaging, and more effective at supporting user decisions.

library(bidux)
library(dplyr)

The BID Framework

The BID framework consists of 5 sequential stages:

1. Notice the Problem - Identify friction points and user struggles
2. Interpret the User’s Need - Understand the core questions and insights needed
3. Structure the Dashboard - Organize information for intuitive comprehension
4. Anticipate User Behavior - Consider cognitive biases that influence perception
5. Validate & Empower the User - Provide clear takeaways and collaborative features

This sequential process forms a structured approach to dashboard design, with each stage building on the insights from previous stages.

Exploring the Concept Dictionary

The BID framework is built on established psychological and design principles. To explore these concepts, use bid_concepts() to list all available concepts, or search for specific terms:

# List all concepts
all_concepts <- bid_concepts()
head(dplyr::select(all_concepts, concept, category, description), 3)

# Search for specific concepts
bid_concepts("cognitive") |>
  dplyr::select(concept, description, implementation_tips)

For detailed information about a specific concept, use bid_concept():

# Get information about a specific concept
bid_concept("Processing Fluency") |>
  dplyr::select(concept, description, implementation_tips)

The bid_concept() function supports case-insensitive and partial matching:

# Case-insensitive matching
bid_concept("hick's law") |>
  dplyr::select(concept, description)

# Partial matching
bid_concept("proximity") |>
  dplyr::select(concept, description)

You can also explore concepts that are new to the BID framework:

# Explore new concepts from user-centric design
bid_concepts("visual hierarchy|breathable|gherkin") |>
  dplyr::select(concept, description)

Documenting a Dashboard Project with BID

Let’s walk through a complete example of using the BID framework to document and improve a dashboard project.

# Document the problem
notice_result <- bid_notice(
  problem = "Users are overwhelmed by too many filter options and struggle to find relevant insights",
  evidence = "User testing shows 65% of first-time users fail to complete their intended task within 2 minutes",
  target_audience = "Marketing team members with varying technical skills"
)

notice_result |>
  dplyr::select(problem, theory, evidence, target_audience)

# Document the user's need
interpret_result <- bid_interpret(
  previous_stage = notice_result,
  central_question = "How are our marketing campaigns performing across different channels?",
  data_story = list(
    hook = "Recent campaign performance varies significantly across channels",
    context = "We've invested in 6 different marketing channels over the past quarter",
    tension = "ROI metrics show inconsistent results, with some channels underperforming",
    resolution = "Identify top-performing channels and key performance drivers",
    audience = "Marketing team and executives",
    metrics = c("Channel ROI", "Conversion Rate", "Cost per Acquisition"),
    visual_approach = "Comparative analysis with historical benchmarks"
  ),
  user_personas = list(
    list(
      name = "Marketing Manager",
      goals = "Optimize marketing spend across channels",
      pain_points = "Difficulty comparing performance across different metrics",
      technical_level = "Intermediate"
    ),
    list(
      name = "CMO",
      goals = "Strategic oversight of marketing effectiveness",
      pain_points = "Needs high-level insights without technical details",
      technical_level = "Basic"
    )
  )
)

interpret_result |>
  dplyr::select(central_question, hook, tension, resolution)

# Document the dashboard structure
structure_result <- bid_structure(
  previous_stage = interpret_result,
  layout = "dual_process",
  concepts = c(
    "Principle of Proximity",
    "Default Effect",
    "Visual Hierarchy",
    "Breathable Layouts"
  ),
  accessibility = list(
    color_contrast = "Using WCAG AA-compliant color contrasts",
    keyboard_navigation = "All interactive elements are keyboard accessible",
    screen_reader = "Charts include descriptive alt text"
  )
)

structure_result |>
  dplyr::select(layout, concepts, accessibility)

# Document bias mitigation strategies
anticipate_result <- bid_anticipate(
  previous_stage = structure_result,
  bias_mitigations = list(
    anchoring = "Include previous period performance as reference points",
    framing = "Provide toggle between ROI improvement vs. ROI gap views",
    confirmation_bias = "Highlight unexpected patterns that contradict common assumptions"
  ),
  interaction_principles = list(
    hover_effects = "Show detailed metrics on hover for each channel",
    selection_feedback = "Highlight active filters with color and icon changes",
    progressive_disclosure = "Reveal advanced options only when basic filters are applied"
  )
)

anticipate_result |>
  dplyr::select(bias_mitigations, interaction_principles)

# Document validation approach
validate_result <- bid_validate(
  previous_stage = anticipate_result,
  summary_panel = "Executive summary highlighting top and bottom performers, key trends, and recommended actions for the next marketing cycle",
  collaboration = "Team annotation capability allowing marketing team members to add context and insights to specific data points",
  next_steps = c(
    "Review performance of bottom 2 channels",
    "Increase budget for top-performing channel",
    "Schedule team meeting to discuss optimization strategy",
    "Export findings for quarterly marketing review"
  )
)

validate_result |>
  dplyr::select(summary_panel, collaboration, next_steps)

Generating Implementation Suggestions

Once you’ve documented your dashboard with the BID framework, you can generate concrete suggestions for implementing the principles using common R packages:

# Get {bslib} component suggestions
bid_suggest_components(structure_result, package = "bslib") |>
  dplyr::select(component, description) |>
  head(2)

# Get {reactable} suggestions for showing data
bid_suggest_components(anticipate_result, package = "reactable") |>
  dplyr::select(component, description) |>
  head(2)

# Get suggestions from all supported packages
all_suggestions <- bid_suggest_components(validate_result, package = "all")
table(all_suggestions$package)

Creating a Complete BID Report

You can generate a complete report summarizing all stages of your BID process:

# Generate a text report (default)
report <- bid_report(validate_result)
cat(report)

# Generate an HTML report
html_report <- bid_report(
  validate_result,
  format = "html"
)

# Generate a markdown report
md_report <- bid_report(validate_result, format = "markdown")

Using BID in Your Shiny Development Workflow

Here’s how to integrate the BID framework into your development process:

1. Planning Phase

• Use the BID framework to document your design decisions before writing code
• Identify key user needs and potential friction points
• Define user personas to guide your design choices
• Consider accessibility requirements early

2. Development Phase

• Reference your BID documentation to implement appropriate UI patterns
• Use bid_suggest_components() to get package-specific implementation ideas
• Implement bias mitigation strategies in your interface
• Build in progressive disclosure for complex interfaces

3. Testing Phase

• Validate that your implementation addresses the issues identified in Stage 1
• Test with actual users representing your defined personas
• Specifically test bias mitigation strategies and accessibility features
• Gather feedback on the effectiveness of your validation approach

4. Iteration Phase

• Update your BID documentation as you refine the dashboard
• Use bid_report() to maintain comprehensive documentation
• Focus improvements on areas with the greatest impact on user experience
• Continue to apply BID principles as you add new features

Conclusion

The {bidux} package makes it easier to apply psychological principles and UX best practices to your Shiny dashboards. By following the 5-stage BID framework, you can create applications that are more intuitive, engaging, and effective for your users.

Future versions of {bidux} will include:

• User stories workflow integration following the Gherkin method
• Enhanced design patterns library
• Accessibility framework integration with WCAG guidelines
• A UI component library implementing BID principles
• Testing and validation tools for dashboard evaluation

Visit github.com/jrwinget/bidux for updates and to contribute to the package development. We welcome feedback and suggestions to help make the BID framework even more effective for Shiny developers.

Remember that good dashboard design is an iterative process that benefits from continuous user feedback. The BID framework provides structure to this process while ensuring psychological principles are incorporated throughout your development workflow.