Getting Started with bidux

In bidux: Behavior Insight Design: A Toolkit for Integrating Behavioral Science in UI/UX Design

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)

Introduction

The {bidux} package helps Shiny developers create more effective dashboards using the Behavior Insight Design (BID) Framework. This framework integrates behavioral science, 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. Interpret the User's Need - Understand the core questions and insights needed
2. Notice the Problem - Identify friction points and user struggles
3. Anticipate User Behavior - Consider cognitive biases that influence perception
4. Structure the Dashboard - Organize information for intuitive comprehension
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 science 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.

Stage 1: Interpret the User's Need

Start by clarifying the central question your dashboard needs to answer and structure the data story:

# Document the user's need
interpret_result <- bid_interpret(
  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)

The function evaluates our data story elements and provides suggestions for improvement (in the suggestions column). We've also added user personas to better target our design.

Stage 2: Notice the Problem

Now identify the specific problems users are encountering with your dashboard or interface:

# Document the problem
notice_result <- bid_notice(
  previous_stage = interpret_result,
  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"
)

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

Notice that the function automatically selected an appropriate theory based on our problem description. It also provides suggestions for addressing cognitive load which you can access from the suggestions column.

Stage 3: Anticipate User Behavior

Next, identify potential cognitive biases that might affect how users interpret your dashboard:

# Document bias mitigation strategies
anticipate_result <- bid_anticipate(
  previous_stage = notice_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"
  )
)

anticipate_result |>
  dplyr::select(bias_mitigations)

The function evaluates our bias mitigation strategies, providing implementation suggestions.

Stage 4: Structure the Dashboard

Now determine the layout and key design principles to implement:

# Document the dashboard structure
structure_result <- bid_structure(
  previous_stage = anticipate_result
)

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

The function automatically selects an appropriate layout based on the content from previous stages and provides ranked, actionable suggestions organized by UX concepts. The layout selection is transparent with clear rationale for why a particular layout was chosen.

Stage 5: Validate & Empower the User

Finally, document how you'll ensure users leave with clear insights and the ability to collaborate:

# Document validation approach
validate_result <- bid_validate(
  previous_stage = structure_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)

The validate function acknowledges our implementation of the Peak-End Rule through next steps and provides suggestions for refining our approach.

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(structure_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
2. Use the BID framework to document your design decisions before writing code
3. Identify key user needs and potential friction points
4. Define user personas to guide your design choices

5. Consider accessibility requirements early

6. Development Phase

7. Reference your BID documentation to implement appropriate UI patterns
8. Use bid_suggest_components() to get package-specific implementation ideas
9. Implement bias mitigation strategies in your interface

10. Build in progressive disclosure for complex interfaces

11. Testing Phase

12. Validate that your implementation addresses the issues identified in Stage 1
13. Test with actual users representing your defined personas
14. Specifically test bias mitigation strategies and accessibility features

15. Gather feedback on the effectiveness of your validation approach

16. Iteration Phase

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

Conclusion

The {bidux} package makes it easier to apply behavioral science 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 common principles are incorporated throughout your development workflow.

bidux documentation built on Aug. 30, 2025, 1:12 a.m.