Title:	Behavioral Insight Design: A Toolkit for Integrating Behavioral Science in UI/UX Design
Version:	0.3.1
Description:	Provides a framework and toolkit to guide 'shiny' developers in implementing the Behavioral 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, DBI, dplyr, jsonlite, readr (≥ 2.1.5), RSQLite, stats, 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
URL:	https://jrwinget.github.io/bidux/
NeedsCompilation:	no
Packaged:	2025-09-06 18:17:03 UTC; user
Author:	Jeremy Winget [aut, cre]
Maintainer:	Jeremy Winget <contact@jrwinget.com>
Repository:	CRAN
Date/Publication:	2025-09-07 22:10:25 UTC

bidux: Behavioral 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 Behavioral 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)

See Also

Useful links:

• https://jrwinget.github.io/bidux/

Calculate severity metrics for an issue

Description

Calculate severity metrics for an issue

Usage

.calculate_severity_metrics(issue_key, events, total_sessions)

Arguments

Value

List with severity, affected_sessions, and impact_rate

Classify issue type from issue key

Description

Classify issue type from issue key

Usage

.classify_issue_type(issue_key)

Arguments

Value

Classified issue type

Create tidy issues tibble from notice issues list

Description

Create tidy issues tibble from notice issues list

Usage

.create_issues_tibble(notice_issues, total_sessions, events)

Arguments

Value

Tibble with structured issue metadata

Extract global telemetry flags from issues and events

Description

Extract global telemetry flags from issues and events

Usage

.flags_from_issues(issues_tbl, events, thresholds)

Arguments

Value

Named list of boolean flags

Suggest theory from text with confidence scoring and messaging

Description

Internal helper that wraps suggest_theory_from_mappings with additional confidence scoring and user messaging. Factored out for reuse across different BID functions.

Usage

.suggest_theory_from_text(
  problem_text,
  evidence_text = NULL,
  mappings = NULL,
  show_message = TRUE
)

Arguments

Value

List with theory, confidence, and auto_suggested flag

Apply context-based scoring adjustments

Description

Apply context-based scoring adjustments

Apply context-based scoring adjustments

Usage

adjust_suggestion_score(suggestion, previous_stage, chosen_layout, concept)

adjust_suggestion_score(suggestion, previous_stage, chosen_layout, concept)

Apply suggestion rules to context data

Description

Evaluates suggestion rules against provided context data and returns applicable suggestions. Used by generate_stage_suggestions() for consistent suggestion generation.

Usage

apply_suggestion_rules(stage_name, context_data, rules_list = NULL)

Arguments

Value

Character vector of applicable suggestions

Convert bid_issues object to tibble

Description

Extracts the tidy issues tibble from a bid_issues object for analysis and visualization. This provides a structured view of all telemetry issues with metadata for prioritization and reporting.

Usage

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

Arguments

Value

A tibble with issue metadata including severity, impact, and descriptions

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

Create Notice stage from single telemetry issue (sugar)

Description

Convenience function that combines issue selection and Notice creation in one step. Useful for quick workflows where you want to address a specific issue immediately.

Usage

bid_address(issue, previous_stage, ...)

Arguments

Value

A bid_stage object in the Notice stage

Examples

## Not run: 
issues <- bid_telemetry("data.sqlite")
interpret <- bid_interpret("How can we improve user experience?")

# Address the highest impact issue
top_issue <- issues[which.max(issues$impact_rate), ]
notice <- bid_address(top_issue, interpret)

## End(Not run)

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,
  include_accessibility = TRUE,
  ...
)

Arguments

Value

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

Examples

interpret_stage <- 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"
  )
)

notice_stage <- bid_notice(
  previous_stage = interpret_stage,
  problem = "Issue with dropdown menus",
  evidence = "User testing indicated delays"
)

structure_info <- bid_structure(previous_stage = notice_stage)

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

# with accessibility included (default) and custom bias mitigations
anticipate_result <- bid_anticipate(
  previous_stage = structure_info,
  bias_mitigations = list(
    anchoring = "Use context-aware references",
    framing = "Toggle between positive and negative framing"
  ),
  include_accessibility = TRUE
)

summary(anticipate_result)

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

Extract telemetry flags from bid_issues object

Description

Extracts global telemetry flags and metadata from a bid_issues object. These flags provide boolean indicators for different types of issues and can be used for conditional logic in downstream BID stages.

Usage

bid_flags(x)

## S3 method for class 'bid_issues'
bid_flags(x)

## Default S3 method:
bid_flags(x)

Arguments

Value

A named list of boolean flags and metadata

Ingest telemetry data and identify UX friction points

Description

This function ingests telemetry data from shiny.telemetry output (SQLite or JSON) and automatically identifies potential UX issues, translating them into BID framework Notice stages. It returns a hybrid object that is backward-compatible as a list of Notice stages while also providing enhanced functionality with tidy tibble access and flags extraction.

Usage

bid_ingest_telemetry(path, format = NULL, thresholds = list())

Arguments

Value

A hybrid object of class c("bid_issues", "list") containing bid_stage objects for each identified issue in the "Notice" stage. The object includes:

    Use as_tibble() to access the tidy issues data, bid_flags() to extract flags,
    and legacy list access for backward compatibility.

Examples

## Not run: 
# Analyze SQLite telemetry database
issues <- bid_ingest_telemetry("telemetry.sqlite")

# Analyze JSON log with custom thresholds
issues <- bid_ingest_telemetry(
  "telemetry.log",
  format = "json",
  thresholds = list(
    unused_input_threshold = 0.1,
    delay_threshold_seconds = 60
  )
)

# Use results in BID workflow
if (length(issues) > 0) {
  # Take first issue and continue with BID process
  interpret_result <- bid_interpret(
    previous_stage = issues[[1]],
    central_question = "How can we improve user engagement?"
  )
}

## End(Not run)

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 1 in the BID framework.

Usage

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

Arguments

Value

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

Examples

# Basic usage
interpret_result <- bid_interpret(
  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"
  )
)

# With user personas
interpret_personas <- bid_interpret(
  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"
    )
  )
)

summary(interpret_personas)

Document User Notice Stage in BID Framework

Description

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

Usage

bid_notice(previous_stage, problem, theory = NULL, evidence = NULL, ...)

Arguments

Value

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

Examples

interpret_result <- bid_interpret(
  central_question = "How can we improve user task completion?",
  data_story = list(
    hook = "Users are struggling with complex interfaces",
    resolution = "Simplify key interactions"
  )
)

# Auto-suggested theory
bid_notice(
  previous_stage = interpret_result,
  problem = "Users struggling with complex dropdowns and too many options",
  evidence = "User testing shows 65% abandonment rate on filter selection"
)

# With explicit theory
notice_result <- bid_notice(
  previous_stage = interpret_result,
  problem = "Mobile interface is difficult to navigate",
  theory = "Fitts's Law",
  evidence = "Mobile users report frustration with small touch targets"
)

summary(notice_result)

Create Notice stage from individual telemetry issue

Description

Bridge function that converts a single telemetry issue row into a BID Notice stage. This allows seamless integration between telemetry analysis and the BID framework.

Usage

bid_notice_issue(issue, previous_stage = NULL, override = list())

Arguments

Value

A bid_stage object in the Notice stage

Examples

## Not run: 
issues <- bid_telemetry("data.sqlite")
interpret <- bid_interpret("How can we reduce user friction?")

# Convert first issue to Notice stage
notice <- bid_notice_issue(issues[1, ], previous_stage = interpret)

# Override problem description
notice <- bid_notice_issue(
  issues[1, ], 
  previous_stage = interpret,
  override = list(problem = "Custom problem description")
)

## End(Not run)

Create multiple Notice stages from telemetry issues

Description

Bridge function that converts multiple telemetry issues into Notice stages. Provides filtering and limiting options for managing large issue sets.

Usage

bid_notices(issues, filter = NULL, previous_stage = NULL, max_issues = 5, ...)

Arguments

Value

A named list of bid_stage objects in the Notice stage

Examples

## Not run: 
issues <- bid_telemetry("data.sqlite")
interpret <- bid_interpret("How can we reduce user friction?")

# Convert all critical issues
notices <- bid_notices(issues, filter = severity == "critical", interpret)

# Convert top 3 issues by impact
top_issues <- issues[order(-issues$impact_rate), ][1:3, ]
notices <- bid_notices(top_issues, previous_stage = interpret)

## End(Not run)

Create pipeline of Notice stages from top telemetry issues (sugar)

Description

Convenience function that creates a pipeline of Notice stages from the highest priority telemetry issues. Useful for systematic issue resolution workflows.

Usage

bid_pipeline(issues, previous_stage, max = 3, ...)

Arguments

Value

A named list of bid_stage objects in the Notice stage

Examples

## Not run: 
issues <- bid_telemetry("data.sqlite")
interpret <- bid_interpret("How can we systematically improve UX?")

# Create pipeline for top 3 issues
notice_pipeline <- bid_pipeline(issues, interpret, max = 3)

# Continue with first issue in pipeline
anticipate <- bid_anticipate(previous_stage = notice_pipeline[[1]])

## End(Not run)

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 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, ...)

Arguments

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.

Value

A bid_stage object containing:

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"
  )

# Auto-selected layout with concept-grouped suggestions
structure_result <- bid_structure(previous_stage = notice_result)
print(structure_result$layout)  # Auto-selected layout
print(structure_result$suggestions)  # Ranked suggestions by concept

summary(structure_result)

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")
}

Concise telemetry analysis with tidy output

Description

Preferred modern interface for telemetry analysis. Returns a clean tibble of identified issues without the legacy list structure. Use this function for new workflows that don't need backward compatibility.

Usage

bid_telemetry(path, format = NULL, thresholds = list())

Arguments

Value

A tibble of class "bid_issues_tbl" with structured issue metadata

Examples

## Not run: 
# Modern workflow
issues <- bid_telemetry("telemetry.sqlite")
high_priority <- issues[issues$severity %in% c("critical", "high"), ]

# Use with bridges for BID workflow  
top_issue <- issues[1, ]
notice <- bid_notice_issue(top_issue, previous_stage = interpret_stage)

## End(Not run)

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,
  include_exp_design = TRUE,
  include_telemetry = TRUE,
  telemetry_refs = NULL,
  include_empower_tools = TRUE
)

Arguments

Value

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

Examples

validate_result <- bid_interpret(
    central_question = "How can we improve delivery efficiency?",
    data_story = list(
      hook = "Too many delays",
      context = "Excessive shipments",
      tension = "User frustration",
      resolution = "Increase delivery channels"
    )
  ) |>
  bid_notice(
    problem  = "Issue with dropdown menus",
    evidence = "User testing indicated delays"
  ) |>
  bid_anticipate(
    bias_mitigations = list(
      anchoring = "Provide reference points",
      framing = "Use gain-framed messaging"
    )
  ) |>
  bid_structure() |>
  bid_validate(
   include_exp_design = FALSE,
   include_telemetry = TRUE,
   include_empower_tools = TRUE
  )

summary(validate_result)

Build suggestions for a specific concept

Description

Build suggestions for a specific concept

Build suggestions for a specific concept

Usage

build_concept_group(concept, chosen_layout, previous_stage)

build_concept_group(concept, chosen_layout, previous_stage)

Arguments

Value

List with concept name and suggestions

List with concept name and suggestions

Build suggestion groups organized by concept

Description

Build suggestion groups organized by concept

Build suggestion groups organized by concept

Usage

build_groups_with_suggestions(concepts_final, chosen_layout, previous_stage)

build_groups_with_suggestions(concepts_final, chosen_layout, previous_stage)

Arguments

Value

List of concept groups with suggestions

List of concept groups with suggestions

Create notice stage for confusion patterns

Description

Create notice stage for confusion patterns

Usage

create_confusion_notice(confusion_info, total_sessions)

Arguments

Value

bid_stage object

Create notice stage for delayed interactions

Description

Create notice stage for delayed interactions

Usage

create_delay_notice(delay_info, total_sessions, threshold)

Arguments

Value

bid_stage object

Create notice stage for error patterns

Description

Create notice stage for error patterns

Usage

create_error_notice(error_info, total_sessions)

Arguments

Value

bid_stage object

Create notice stage for navigation issues

Description

Create notice stage for navigation issues

Usage

create_navigation_notice(nav_info, total_sessions)

Arguments

Value

bid_stage object

Create notice stage for unused input

Description

Create notice stage for unused input

Usage

create_unused_input_notice(input_info, total_sessions)

Arguments

Value

bid_stage object

Remove duplicate warning-suggestion pairs

Description

Identifies and removes redundant warnings where the warning message duplicates information already provided in suggestions. Helps clean up verbose output by preferring actionable suggestions over warnings.

Usage

deduplicate_warnings_suggestions(
  warnings,
  suggestions,
  similarity_threshold = 0.7
)

Arguments

Value

List with cleaned warnings and suggestions

Auto-detect telemetry format from file extension

Description

Auto-detect telemetry format from file extension

Usage

detect_telemetry_format(path)

Arguments

Value

Format string ("sqlite" or "json")

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

Extract theory concepts from Stage 1 (Notice)

Description

Extract theory concepts from Stage 1 (Notice)

Extract theory concepts from Stage 1 (Notice)

Usage

extract_stage1_theory(previous_stage)

extract_stage1_theory(previous_stage)

Arguments

Value

Character vector of theory-based concepts

Character vector of theory-based concepts

Find confusion patterns (rapid repeated changes)

Description

Find confusion patterns (rapid repeated changes)

Usage

find_confusion_patterns(events, window_seconds = 10, min_changes = 5)

Arguments

Value

List of confusion patterns

Find sessions with delayed first interaction

Description

Find sessions with delayed first interaction

Usage

find_delayed_sessions(events, threshold_seconds = 30)

Arguments

Value

List with delay statistics

Find error patterns in telemetry

Description

Find error patterns in telemetry

Usage

find_error_patterns(events, threshold_rate = 0.1)

Arguments

Value

List of error patterns

Find navigation drop-offs or underused pages

Description

Find navigation drop-offs or underused pages

Usage

find_navigation_dropoffs(events, threshold = 0.2)

Arguments

Value

List of navigation issues

Find unused or under-used inputs

Description

Find unused or under-used inputs

Usage

find_unused_inputs(events, threshold = 0.05)

Arguments

Value

List of unused input information

Format field label based on output format

Description

Format field label based on output format

Usage

format_label(label, format, type = "field")

Arguments

Value

Formatted label string

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

Generate Cognitive Load Theory suggestions

Description

Generate Cognitive Load Theory suggestions

Generate Cognitive Load Theory suggestions

Usage

get_cognitive_load_suggestions(chosen_layout, previous_stage)

get_cognitive_load_suggestions(chosen_layout, previous_stage)

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

Centralized Suggestion Rules for BID Framework

Description

This file consolidates simple suggestion rules for Interpret, Notice, and Validate stages to reduce duplication and provide consistent messaging across the BID framework. Get consolidated suggestion rules for all BID stages

Returns a structured list of suggestion rules for each BID stage. These rules help generate consistent, context-aware suggestions based on user input patterns and common issues.

Usage

get_consolidated_suggestion_rules()

Value

Named list of suggestion rules by stage

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

Generate Dual-Processing Theory suggestions

Description

Generate Dual-Processing Theory suggestions

Generate Dual-Processing Theory suggestions

Usage

get_dual_processing_suggestions(chosen_layout, previous_stage)

get_dual_processing_suggestions(chosen_layout, previous_stage)

Generate fallback suggestions for stages without specific rules

Description

Provides generic but helpful suggestions for BID stages that don't have specific rules defined or when no rules match the context.

Usage

get_fallback_suggestion(stage_name)

Arguments

Value

Character string with fallback suggestion

Generate generic suggestions for unrecognized concepts

Description

Generate generic suggestions for unrecognized concepts

Generate generic suggestions for unrecognized concepts

Usage

get_generic_suggestions(concept, chosen_layout, previous_stage)

get_generic_suggestions(concept, chosen_layout, previous_stage)

Generate Information Scent suggestions

Description

Generate Information Scent suggestions

Generate Information Scent suggestions

Usage

get_information_scent_suggestions(chosen_layout, previous_stage)

get_information_scent_suggestions(chosen_layout, previous_stage)

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

Generate User Onboarding suggestions

Description

Generate User Onboarding suggestions

Generate User Onboarding suggestions

Usage

get_onboarding_suggestions(chosen_layout, previous_stage)

get_onboarding_suggestions(chosen_layout, previous_stage)

Generate Progressive Disclosure suggestions

Description

Generate Progressive Disclosure suggestions

Generate Progressive Disclosure suggestions

Usage

get_progressive_disclosure_suggestions(chosen_layout, previous_stage)

get_progressive_disclosure_suggestions(chosen_layout, previous_stage)

Generate Principle of Proximity suggestions

Description

Generate Principle of Proximity suggestions

Generate Principle of Proximity suggestions

Usage

get_proximity_suggestions(chosen_layout, previous_stage)

get_proximity_suggestions(chosen_layout, previous_stage)

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

Generate Visual Hierarchy suggestions

Description

Generate Visual Hierarchy suggestions

Generate Visual Hierarchy suggestions

Usage

get_visual_hierarchy_suggestions(chosen_layout, previous_stage)

get_visual_hierarchy_suggestions(chosen_layout, previous_stage)

Infer concepts from Stage 2 (Interpret) story elements

Description

Infer concepts from Stage 2 (Interpret) story elements

Infer concepts from Stage 2 (Interpret) story elements

Usage

infer_concepts_from_story(previous_stage)

infer_concepts_from_story(previous_stage)

Arguments

Value

Character vector of story-inferred concepts

Character vector of story-inferred concepts

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

Generate layout selection rationale

Description

Provides a concise explanation for why a particular layout was chosen based on the content analysis of the previous stage.

Usage

layout_rationale(previous_stage, chosen)

Arguments

Value

Character string with explanation for the layout choice

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'

Normalize telemetry column names

Description

Normalize telemetry column names

Usage

normalize_telemetry_columns(events)

Arguments

Value

Normalized data frame

Print method for bid_issues objects

Description

Displays a triage view of telemetry issues with severity-based prioritization and provides a reminder about legacy list access for backward compatibility.

Usage

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

Arguments

Value

Invisible x (for chaining)

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.

Rank and sort suggestions within each group

Description

Rank and sort suggestions within each group

Rank and sort suggestions within each group

Usage

rank_and_sort_suggestions(groups, previous_stage, chosen_layout)

rank_and_sort_suggestions(groups, previous_stage, chosen_layout)

Arguments

Value

List of groups with ranked suggestions

List of groups with ranked suggestions

Read telemetry data from file

Description

Read telemetry data from file

Usage

read_telemetry_data(path, format)

Arguments

Value

Data frame of events

Read telemetry from JSON log file

Description

Read telemetry from JSON log file

Usage

read_telemetry_json(path)

Arguments

Value

Data frame of events

Read telemetry from SQLite database

Description

Read telemetry from SQLite database

Usage

read_telemetry_sqlite(path)

Arguments

Value

Data frame of events

Safely convert text to lowercase with null handling

Description

Helper function that safely converts text to lowercase while handling NULL, NA, and non-character values gracefully.

Usage

safe_lower(x)

Arguments

Value

Character string in lowercase, or empty string if input is NULL/NA

Safe access to data_story elements from previous stage

Description

Safe access to data_story elements from previous stage

Usage

safe_stage_data_story_access(previous_stage, element)

Arguments

Value

Character string or empty string if not found

Generate ranked, concept-grouped, actionable UI/UX suggestions

Description

Creates structured suggestions organized by UX concepts with specific component recommendations and rationales. Suggestions are ranked by relevance and grouped by concept for systematic implementation.

Creates structured suggestions organized by UX concepts with specific component recommendations and rationales. Suggestions are ranked by relevance and grouped by concept for systematic implementation.

Usage

structure_suggestions(previous_stage, chosen_layout, concepts = NULL)

structure_suggestions(previous_stage, chosen_layout, concepts = NULL)

Arguments

Details

The function combines concepts from multiple sources:

• Stage 1 theory (from Notice)

• Stage 2 inferred concepts (from keywords in story)

• Optional user-provided concepts

Each suggestion includes:

• title: Brief actionable description

• details: Specific implementation guidance

• components: Shiny/bslib component recommendations

• rationale: 1-2 sentence explanation

• score: Relevance ranking (0-1)

The function combines concepts from multiple sources:

• Stage 1 theory (from Notice)

• Stage 2 inferred concepts (from keywords in story)

• Optional user-provided concepts

Each suggestion includes:

• title: Brief actionable description

• details: Specific implementation guidance

• components: Shiny/bslib component recommendations

• rationale: 1-2 sentence explanation

• score: Relevance ranking (0-1)

Value

List of concept groups with ranked suggestions

List of concept groups with ranked suggestions

Suggest layout based on previous stage content using heuristics

Description

Automatically suggests an appropriate layout type based on content analysis of previous BID stages. Uses deterministic heuristics to match keywords in problem descriptions, evidence, data story, and other contextual information to layout types that best address the identified issues.

Usage

suggest_layout_from_previous(previous_stage, telemetry_flags = NULL)

Arguments

Details

The heuristics follow a priority order:

1. breathable - if content suggests information overload, confusion, or cognitive load issues

2. dual_process - if content mentions overview vs detail, quick vs deep, or two-mode interactions

3. grid - if content focuses on grouping, clustering, visual hierarchy, or comparing related metrics

4. card - if content mentions cards, chunks, tiles, modular blocks, or per-item summaries

5. tabs - if content suggests sections, categories, progressive disclosure, but avoids tabs if telemetry shows tab drop-off

6. breathable - fallback for any unmatched cases

Value

Character string indicating the suggested layout type ("breathable", "dual_process", "grid", "card", "tabs", or fallback)

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