Title:	Behavior Insight Design: A Toolkit for Integrating Behavioral Science in UI/UX Design
Version:	0.1.0
Description:	Provides a framework and toolkit to guide 'shiny' developers in implementing the Behavior Insight Design (BID) framework. The package offers functions for documenting each of the five stages (Notice, Interpret, Structure, Anticipate, and Validate), along with a comprehensive concept dictionary.
License:	MIT + file LICENSE
Encoding:	UTF-8
Depends:	R (≥ 4.1.0)
RoxygenNote:	7.3.2
Imports:	cli (≥ 3.6.5), dplyr (≥ 1.1.4), jsonlite (≥ 2.0.0), readr (≥ 2.1.5), stringdist (≥ 0.9.15), stringr (≥ 1.5.1), tibble (≥ 3.2.1), utils
Suggests:	DiagrammeR, knitr, rmarkdown, spelling, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
Language:	en-US
NeedsCompilation:	no
Packaged:	2025-06-11 19:30:41 UTC; user
Author:	Jeremy Winget [aut, cre]
Maintainer:	Jeremy Winget <contact@jrwinget.com>
Repository:	CRAN
Date/Publication:	2025-06-13 20:00:12 UTC

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

Description

Provides a framework and toolkit to guide 'shiny' developers in implementing the Behavior Insight Design (BID) framework. The package offers functions for documenting each of the five stages (Notice, Interpret, Structure, Anticipate, and Validate), along with a comprehensive concept dictionary.

Author(s)

Maintainer: Jeremy Winget contact@jrwinget.com (ORCID)

Convert bid_stage to tibble

Description

Convert bid_stage to tibble

Usage

## S3 method for class 'bid_stage'
as_tibble(x, ...)

Arguments

Value

A tibble

Document User Behavior Anticipation Stage in BID Framework

Description

This function documents the anticipated user behavior by listing bias mitigation strategies related to anchoring, framing, confirmation bias, etc. It also supports adding interaction hints and visual feedback elements.

Usage

bid_anticipate(
  previous_stage,
  bias_mitigations = NULL,
  interaction_principles = NULL
)

Arguments

Value

A tibble containing the documented information for the "Anticipate" stage.

Examples

structure_info <- bid_structure(
  bid_interpret(
    bid_notice(
      "Issue with dropdown menus",
      evidence = "User testing indicated delays"
    ),
    central_question = "How can we improve selection efficiency?",
    data_story = list(
      hook = "Too many options",
      context = "Excessive choices",
      tension = "User frustration",
      resolution = "Simplify menu"
    )
  ),
  layout = "dual_process",
  concepts = c("principle_of_proximity", "default_effect")
)

# Basic usage
bid_anticipate(
  previous_stage = structure_info,
  bias_mitigations = list(
    anchoring = "Use context-aware references",
    framing = "Toggle between positive and negative framing"
  )
)

# Let the function suggest bias mitigations based on previous stages
bid_anticipate(
  previous_stage = structure_info
)

# With interaction principles
bid_anticipate(
  previous_stage = structure_info,
  bias_mitigations = list(
    anchoring = "Use context-aware references",
    framing = "Toggle between positive and negative framing"
  ),
  interaction_principles = list(
    hover_effects = "Show additional information on hover",
    selection_feedback = "Highlight active filters with color change",
    progressive_actions = "Show advanced options only if basic ones are used"
  )
)

Get detailed information about a specific concept

Description

Returns detailed information about a specific BID framework concept, including implementation recommendations based on the concept's stage.

Usage

bid_concept(concept_name, add_recommendations = TRUE)

Arguments

Value

A tibble with detailed concept information

Search BID Framework Concepts

Description

Search for behavioral science and UX concepts used in the BID framework. Returns concepts matching the search term along with their descriptions, categories, and implementation guidance.

Usage

bid_concepts(search = NULL, fuzzy_match = TRUE, max_distance = 2)

Arguments

Value

A tibble containing matching concepts with their details

Document User Interpretation Stage in BID Framework

Description

This function documents the interpretation of user needs, capturing the central question and the data storytelling narrative. It represents stage 2 in the BID framework.

Usage

bid_interpret(
  previous_stage,
  central_question = NULL,
  data_story = NULL,
  user_personas = NULL
)

Arguments

Value

A tibble containing the documented information for the "Interpret" stage.

Examples

notice <- bid_notice(
  problem = "Users struggle with complex data",
  evidence = "Test results indicate delays"
)

# Basic usage
bid_interpret(
  previous_stage = notice,
  central_question = "What drives the decline in user engagement?",
  data_story = list(
    hook = "Declining trend in engagement",
    context = "Previous high engagement levels",
    tension = "Unexpected drop",
    resolution = "Investigate new UI changes",
    audience = "Marketing team",
    metrics = c("Daily Active Users", "Session Duration"),
    visual_approach = "Comparison charts showing before/after UI change"
  )
)

# Let the function suggest content based on previous stage
bid_interpret(
  previous_stage = notice
)

# With user personas
bid_interpret(
  previous_stage = notice,
  central_question = "How can we improve data discovery?",
  data_story = list(
    hook = "Users are missing key insights",
    context = "Critical data is available but overlooked",
    tension = "Time-sensitive decisions are delayed",
    resolution = "Highlight key metrics more effectively"
  ),
  user_personas = list(
    list(
      name = "Sara, Data Analyst",
      goals = "Needs to quickly find patterns in data",
      pain_points = "Gets overwhelmed by too many visualizations",
      technical_level = "Advanced"
    ),
    list(
      name = "Marcus, Executive",
      goals = "Wants high-level insights at a glance",
      pain_points = "Limited time to analyze detailed reports",
      technical_level = "Basic"
    )
  )
)

Document User Notice Stage in BID Framework

Description

This function documents the initial observation and problem identification stage. It represents stage 1 in the BID framework and now returns a structured bid_stage object with enhanced metadata and external mapping support.

Usage

bid_notice(problem, theory = NULL, evidence = NULL, target_audience = NULL)

Arguments

Value

A bid_stage object containing the documented information for the "Notice" stage with enhanced metadata and validation.

Examples

# Basic usage with auto-suggested theory
notice_result <- bid_notice(
  problem = "Users struggle with complex dropdown menus containing too many options",
  evidence = "User testing shows 65% abandonment rate on filter selection"
)

# Print shows human-friendly summary
print(notice_result)

# Access underlying data
summary(notice_result)

# Check stage and metadata
get_stage(notice_result)
get_metadata(notice_result)

# With explicit theory
notice_explicit <- bid_notice(
  problem = "Mobile interface is difficult to navigate",
  theory = "Fitts's Law",
  evidence = "Mobile users report frustration with small touch targets",
  target_audience = "Mobile users with varying technical expertise"
)

Generate BID Framework Report

Description

Creates a comprehensive report from a completed BID framework process. This report summarizes all stages and provides recommendations for implementation.

Usage

bid_report(
  validate_stage,
  format = c("text", "html", "markdown"),
  include_diagrams = TRUE
)

Arguments

Value

A formatted report summarizing the entire BID process

Examples

if(interactive()){
  # After completing all 5 stages
  validation_result <- bid_validate(...)

  # Generate a text report
  bid_report(validation_result)

  # Generate an HTML report
  bid_report(validation_result, format = "html")

  # Generate a markdown report without diagrams
  bid_report(
    validation_result,
    format = "markdown",
    include_diagrams = FALSE
  )
}

Constructor for BID result collection objects

Description

Constructor for BID result collection objects

Usage

bid_result(stages)

Arguments

Value

Object of class 'bid_result'

Constructor for BID stage objects

Description

Constructor for BID stage objects

Usage

bid_stage(stage, data, metadata = list())

Arguments

Value

Object of class 'bid_stage'

Document Dashboard Structure Stage in BID Framework

Description

This function documents the structure of the dashboard, including layout and design elements such as proximity, dual-processing, and default effects. It supports modern layout approaches like breathable layouts and visual hierarchies, while ensuring accessibility considerations are properly documented.

Usage

bid_structure(previous_stage, layout, concepts = NULL, accessibility = NULL)

Arguments

Value

A bid_stage object containing the documented information for the "Structure" stage.

Examples

interpret <- bid_notice(
  problem = "Users struggle with information overload",
  evidence = "Survey results indicate delays"
) |>
  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"
    )
  )

# Basic usage with natural language concept names
bid_structure(
  previous_stage = interpret,
  layout = "dual_process",
  concepts = c("Principle of Proximity", "Default Effect")
)

Suggest UI Components Based on BID Framework Analysis

Description

This function analyzes the results from BID framework stages and suggests appropriate UI components from popular R packages like shiny, bslib, DT, etc. The suggestions are based on the design principles and user needs identified in the BID process.

Usage

bid_suggest_components(bid_stage, package = NULL)

Arguments

Value

A tibble containing component suggestions with relevance scores

Examples

if(interactive()){
  # After completing BID stages
  notice_result <- bid_notice(
    problem = "Users struggle with complex data",
    theory = "Cognitive Load Theory"
  )

  # Get all component suggestions
  bid_suggest_components(notice_result)

  # Get only bslib suggestions
  bid_suggest_components(notice_result, package = "bslib")

  # Get shiny-specific suggestions
  bid_suggest_components(notice_result, package = "shiny")
}

Document User Validation Stage in BID Framework

Description

This function documents the validation stage, where the user tests and refines the dashboard. It represents stage 5 in the BID framework.

Usage

bid_validate(
  previous_stage,
  summary_panel = NULL,
  collaboration = NULL,
  next_steps = NULL
)

Arguments

Value

A tibble containing the documented information for the "Validate" stage.

Examples

structure_input <- bid_notice(
  problem  = "Issue with dropdown menus",
  evidence = "User testing indicated delays"
) |>
  bid_interpret(
    central_question = "How can we improve selection efficiency?",
    data_story = list(
      hook      = "Too many options",
      context   = "Excessive choices",
      tension   = "User frustration",
      resolution= "Simplify menu"
    )
  )

structure_result <- bid_structure(
  previous_stage = structure_input,
  layout         = "dual_process",
  concepts       = c("Principle of Proximity", "Default Effect")
)

anticipate <- bid_anticipate(
  previous_stage    = structure_result,
  bias_mitigations  = list(
    anchoring = "Provide reference points",
    framing   = "Use gain-framed messaging"
  )
)

bid_validate(
  previous_stage = anticipate,
  summary_panel  = "Clear summary of key insights with action items",
  collaboration  = "Team annotation and sharing features",
  next_steps     = c(
    "Conduct user testing with target audience",
    "Implement accessibility improvements",
    "Add mobile responsiveness"
  )
)

Extract specific stage from bid_result

Description

Extract specific stage from bid_result

Usage

extract_stage(workflow, stage)

Arguments

Value

A bid_stage object or NULL if not found

Enhanced suggestions generator for Notice stage

Description

Enhanced suggestions generator for Notice stage

Usage

generate_notice_suggestions(problem, theory, evidence, target_audience)

Arguments

Value

Character string with suggestions

Get accessibility recommendations for a given context

Description

Get accessibility recommendations for a given context

Usage

get_accessibility_recommendations(context = "", guidelines = NULL)

Arguments

Value

Character vector of relevant accessibility recommendations

Get bias mitigation strategies for concepts

Description

Get bias mitigation strategies for concepts

Usage

get_concept_bias_mappings(concepts, mappings = NULL)

Arguments

Value

Data frame with relevant bias mappings

Internal function to get concepts data from external files

Description

Internal function to get concepts data from external files

Usage

get_concepts_data()

Value

A tibble with all BID framework concepts

Get default concepts data (fallback when external file unavailable)

Description

Get default concepts data (fallback when external file unavailable)

Usage

get_default_concepts_data()

Value

A tibble with default BID framework concepts

Get default layout mappings (fallback)

Description

Get default layout mappings (fallback)

Usage

get_default_layout_mappings()

Value

Data frame with default layout mappings

Get default theory mappings (fallback)

Description

Get default theory mappings (fallback)

Usage

get_default_theory_mappings()

Value

Data frame with default theory mappings

Get concepts recommended for a layout

Description

Get concepts recommended for a layout

Usage

get_layout_concepts(layout, mappings = NULL)

Arguments

Value

Character vector of recommended concepts

Get metadata from bid_stage object

Description

Get metadata from bid_stage object

Usage

get_metadata(x)

Arguments

Value

List with metadata

Get stage name from bid_stage object

Description

Get stage name from bid_stage object

Usage

get_stage(x)

Arguments

Value

Character string with stage name

Check if object is a bid_stage

Description

Check if object is a bid_stage

Usage

is_bid_stage(x)

Arguments

Value

Logical indicating if object is bid_stage

Check if workflow is complete (has all 5 stages)

Description

Check if workflow is complete (has all 5 stages)

Usage

is_complete(x)

Arguments

Value

Logical indicating if workflow is complete

Load accessibility guidelines

Description

Load accessibility guidelines

Usage

load_accessibility_guidelines(custom_guidelines = NULL)

Arguments

Value

Data frame with accessibility guidelines

Load concept-bias mappings

Description

Load concept-bias mappings

Usage

load_concept_bias_mappings(custom_mappings = NULL)

Arguments

Value

Data frame with concept-bias mappings

Load layout-concept mappings

Description

Load layout-concept mappings

Usage

load_layout_mappings(custom_mappings = NULL)

Arguments

Value

Data frame with layout-concept mappings

Load theory mappings from external file or use defaults

Description

Load theory mappings from external file or use defaults

Usage

load_theory_mappings(custom_mappings = NULL)

Arguments

Value

Data frame with theory mappings

Create a BID result collection object (internal constructor)

Description

Create a BID result collection object (internal constructor)

Usage

new_bid_result(stages)

Arguments

Value

Object of class 'bid_result'

Create a BID stage result object (internal constructor)

Description

Create a BID stage result object (internal constructor)

Usage

new_bid_stage(stage, data, metadata = list())

Arguments

Value

Object of class 'bid_stage'

Print method for BID result objects

Description

Print method for BID result objects

Usage

## S3 method for class 'bid_result'
print(x, ...)

Arguments

Value

Returns the input bid_result object invisibly (class: c("bid_result", "list")). The method is called for its side effects: printing a workflow overview to the console showing completion status, stage progression, and key information from each completed BID stage. The invisible return supports method chaining while emphasizing the console summary output.

Print method for BID stage objects

Description

Print method for BID stage objects

Usage

## S3 method for class 'bid_stage'
print(x, ...)

Arguments

Value

Returns the input bid_stage object invisibly (class: c("bid_stage", "tbl_df", "tbl", "data.frame")). The method is called for its side effects: printing a formatted summary of the BID stage to the console, including stage progress, key stage-specific information, and usage suggestions. The invisible return allows for method chaining while maintaining the primary purpose of console output.

Suggest theory based on problem and evidence using mappings

Description

Suggest theory based on problem and evidence using mappings

Usage

suggest_theory_from_mappings(problem, evidence = NULL, mappings = NULL)

Arguments

Value

Character string with suggested theory

Summary method for BID result objects

Description

Summary method for BID result objects

Usage

## S3 method for class 'bid_result'
summary(object, ...)

Arguments

Value

Returns the input bid_result object invisibly (class: c("bid_result", "list")). The method is called for its side effects: printing a detailed workflow analysis to the console including completion statistics, duration metrics, and comprehensive stage-by-stage breakdowns with key data from each BID framework stage. The invisible return facilitates method chaining while focusing on comprehensive console reporting.

Summary method for BID stage objects

Description

Summary method for BID stage objects

Usage

## S3 method for class 'bid_stage'
summary(object, ...)

Arguments

Value

Returns the input bid_stage object invisibly (class: c("bid_stage", "tbl_df", "tbl", "data.frame")). The method is called for its side effects: printing a comprehensive summary to the console including stage metadata, all non-empty data columns, and timestamp information. The invisible return enables method chaining while prioritizing the detailed console output display.

Validate BID result object

Description

Validate BID result object

Usage

validate_bid_result(x)

Arguments

Value

TRUE if valid, throws error otherwise

Validate BID stage object

Description

Validate BID stage object

Usage

validate_bid_stage(x)

Arguments

Value

TRUE if valid, throws error otherwise