---

name: design-shiny-ui description: > Diseñar interfaces de usuario de aplicaciones Shiny usando bslib para temas, layout_columns para cuadrículas responsivas, cajas de valor, tarjetas y CSS/SCSS personalizado. Cubre layouts de página, accesibilidad y coherencia de marca. Úsalo al construir una nueva UI de app Shiny desde cero, al modernizar una app existente de fluidPage a bslib, al aplicar temas de marca, al hacer una app Shiny responsiva en diferentes tamaños de pantalla, o al mejorar la accesibilidad de una aplicación Shiny. locale: es source_locale: en source_commit: 6f65f316 translator: claude-opus-4-6 translation_date: 2026-03-16 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: shiny complexity: intermediate language: R tags: shiny, bslib, ui, theming, layout, css, accessibility, responsive

Design Shiny UI

Diseñar interfaces de aplicaciones Shiny responsivas y accesibles usando temas bslib, primitivas de layout modernas y CSS personalizado.

Cuándo Usar

• Al construir una nueva UI de app Shiny desde cero
• Al modernizar una app Shiny existente de fluidPage a bslib
• Al aplicar temas de marca (colores, fuentes) a una app Shiny
• Al hacer una app Shiny responsiva en diferentes tamaños de pantalla
• Al mejorar la accesibilidad de una aplicación Shiny

Entradas

• Requerido: Propósito de la aplicación y audiencia objetivo
• Requerido: Tipo de layout (sidebar, navbar, fillable, dashboard)
• Opcional: Colores y fuentes de marca
• Opcional: Si usar CSS/SCSS personalizado (predeterminado: solo bslib)
• Opcional: Requisitos de accesibilidad (nivel WCAG)

Procedimiento

Paso 1: Elegir el Layout de Página

bslib proporciona varios constructores de página:

# Layout sidebar — el más común para apps de datos
ui <- page_sidebar(
  title = "My App",
  sidebar = sidebar("Controls here"),
  "Main content here"
)

# Layout navbar — para apps de múltiples páginas
ui <- page_navbar(
  title = "My App",
  nav_panel("Tab 1", "Content 1"),
  nav_panel("Tab 2", "Content 2"),
  nav_spacer(),
  nav_item(actionButton("help", "Help"))
)

# Layout fillable — el contenido llena el espacio disponible
ui <- page_fillable(
  card(
    full_screen = TRUE,
    plotOutput("plot")
  )
)

# Layout dashboard — cuadrícula de cajas de valor y tarjetas
ui <- page_sidebar(
  title = "Dashboard",
  sidebar = sidebar(open = "closed", "Filters"),
  layout_columns(
    fill = FALSE,
    value_box("Revenue", "$1.2M", theme = "primary"),
    value_box("Users", "4,521", theme = "success"),
    value_box("Uptime", "99.9%", theme = "info")
  ),
  layout_columns(
    card(plotOutput("chart1")),
    card(plotOutput("chart2"))
  )
)

Esperado: El layout de página coincide con las necesidades de navegación y contenido de la aplicación.

En caso de fallo: Si el layout no se ve bien, verifica que estés usando page_sidebar() / page_navbar() (bslib) y no fluidPage() / navbarPage() (shiny base). Las versiones bslib tienen mejores valores predeterminados y soporte de temas.

Paso 2: Configurar el Tema bslib

my_theme <- bslib::bs_theme(
  version = 5,                      # Bootstrap 5
  bootswatch = "flatly",            # Tema preestablecido opcional
  bg = "#ffffff",                   # Color de fondo
  fg = "#2c3e50",                   # Color de primer plano (texto)
  primary = "#2c3e50",              # Color primario de marca
  secondary = "#95a5a6",            # Color secundario
  success = "#18bc9c",
  info = "#3498db",
  warning = "#f39c12",
  danger = "#e74c3c",
  base_font = bslib::font_google("Source Sans Pro"),
  heading_font = bslib::font_google("Source Sans Pro", wght = 600),
  code_font = bslib::font_google("Fira Code"),
  "navbar-bg" = "#2c3e50"
)

ui <- page_sidebar(
  theme = my_theme,
  title = "Themed App",
  # ...
)

Usa el editor de temas interactivo durante el desarrollo:

bslib::bs_theme_preview(my_theme)

Esperado: La app se renderiza con colores de marca, fuentes y componentes Bootstrap 5 coherentes.

En caso de fallo: Si las fuentes no cargan, verifica el acceso a internet (Google Fonts lo requiere) o cambia a fuentes del sistema: font_collection("system-ui", "-apple-system", "Segoe UI"). Si las variables del tema no se aplican, verifica que estés pasando theme a la función de página.

Paso 3: Construir el Layout con Tarjetas y Columnas

ui <- page_sidebar(
  theme = my_theme,
  title = "Analysis Dashboard",
  sidebar = sidebar(
    width = 300,
    title = "Filters",
    selectInput("dataset", "Dataset", choices = c("iris", "mtcars")),
    sliderInput("sample", "Sample %", 10, 100, 100, step = 10),
    hr(),
    actionButton("refresh", "Refresh", class = "btn-primary w-100")
  ),

  # Fila KPI — sin relleno
  layout_columns(
    fill = FALSE,
    col_widths = c(4, 4, 4),
    value_box(
      title = "Observations",
      value = textOutput("n_obs"),
      showcase = bsicons::bs_icon("table"),
      theme = "primary"
    ),
    value_box(
      title = "Variables",
      value = textOutput("n_vars"),
      showcase = bsicons::bs_icon("columns-gap"),
      theme = "info"
    ),
    value_box(
      title = "Missing",
      value = textOutput("n_missing"),
      showcase = bsicons::bs_icon("exclamation-triangle"),
      theme = "warning"
    )
  ),

  # Fila de contenido principal
  layout_columns(
    col_widths = c(8, 4),
    card(
      card_header("Distribution"),
      full_screen = TRUE,
      plotOutput("main_plot")
    ),
    card(
      card_header("Summary"),
      tableOutput("summary_table")
    )
  )
)

Primitivas de layout clave:

• layout_columns() — cuadrícula responsiva con col_widths
• card() — contenedor de contenido con cabecera/pie opcional
• value_box() — visualización de KPI con icono y tema
• layout_sidebar() — sidebar anidada dentro de tarjetas
• navset_card_tab() — tarjetas con pestañas

Esperado: Layout de cuadrícula responsiva que se adapta al tamaño de pantalla.

En caso de fallo: Si las columnas se apilan inesperadamente en pantallas anchas, verifica que la suma de col_widths sea 12 (cuadrícula Bootstrap). Si las tarjetas se superponen, asegúrate de fill = FALSE en las filas sin relleno.

Paso 4: Añadir Elementos de UI Dinámicos

server <- function(input, output, session) {
  output$dynamic_filters <- renderUI({
    data <- current_data()
    tagList(
      selectInput("col", "Column", choices = names(data)),
      if (is.numeric(data[[input$col]])) {
        sliderInput("range", "Range",
          min = min(data[[input$col]], na.rm = TRUE),
          max = max(data[[input$col]], na.rm = TRUE),
          value = range(data[[input$col]], na.rm = TRUE)
        )
      } else {
        selectInput("values", "Values",
          choices = unique(data[[input$col]]),
          multiple = TRUE
        )
      }
    )
  })

  # Paneles condicionales (sin viaje de ida y vuelta al servidor)
  # En UI:
  # conditionalPanel(
  #   condition = "input.show_advanced == true",
  #   numericInput("alpha", "Alpha", 0.05)
  # )
}

Esperado: Los elementos de UI se actualizan dinámicamente basándose en las selecciones del usuario y los datos.

En caso de fallo: Si la UI dinámica parpadea, usa conditionalPanel() (basado en CSS) en lugar de renderUI() donde sea posible. Si las entradas dinámicas pierden sus valores al volver a renderizar, añade session$sendInputMessage() para restaurar el estado.

Paso 5: Añadir CSS/SCSS Personalizado (Opcional)

Para estilos más allá de las variables del tema bslib:

# CSS en línea
ui <- page_sidebar(
  theme = my_theme,
  tags$head(tags$style(HTML("
    .sidebar { border-right: 2px solid var(--bs-primary); }
    .card-header { font-weight: 600; }
    .value-box .value { font-size: 2.5rem; }
  "))),
  # ...
)

# Archivo CSS externo (coloca en directorio www/)
ui <- page_sidebar(
  theme = my_theme,
  tags$head(tags$link(rel = "stylesheet", href = "custom.css")),
  # ...
)

Para integración SCSS con bslib:

my_theme <- bslib::bs_theme(version = 5) |>
  bslib::bs_add_rules(sass::sass_file("www/custom.scss"))

Esperado: Estilos personalizados aplicados sin romper los temas de bslib.

En caso de fallo: Si el CSS personalizado entra en conflicto con bslib, usa variables CSS de Bootstrap (var(--bs-primary)) en lugar de colores hardcodeados. Esto garantiza que los cambios de tema se propaguen a los estilos personalizados.

Paso 6: Garantizar la Accesibilidad

# Añadir etiquetas ARIA a las entradas
selectInput("category", "Category",
  choices = c("A", "B", "C")
) |> tagAppendAttributes(`aria-describedby` = "category-help")

# Añadir texto alternativo a los gráficos
output$plot <- renderPlot({
  plot(data(), main = "Distribution of Values")
}, alt = "Histogram showing the distribution of selected values")

# Asegurar suficiente contraste de color en el tema
my_theme <- bslib::bs_theme(
  version = 5,
  bg = "#ffffff",      # Fondo blanco
  fg = "#212529"       # Texto oscuro — ratio de contraste 15.4:1
)

# Usar HTML semántico
tags$main(
  role = "main",
  tags$h1("Dashboard"),
  tags$section(
    `aria-label` = "Key Performance Indicators",
    layout_columns(
      # cajas de valor...
    )
  )
)

Esperado: La app cumple los estándares WCAG 2.1 AA para contraste de color, navegación por teclado y compatibilidad con lectores de pantalla.

En caso de fallo: Prueba con la auditoría de accesibilidad de las herramientas de desarrollo del navegador (Lighthouse). Verifica los ratios de contraste de color con el verificador de contraste de WebAIM. Asegúrate de que todos los elementos interactivos sean accesibles por teclado.

Validación

• El layout de página se renderiza correctamente en anchos de escritorio y móvil
• El tema bslib se aplica consistentemente a todos los componentes
• Las cajas de valor se muestran con los temas e iconos correctos
• Las tarjetas se redimensionan correctamente en la cuadrícula responsiva
• El CSS personalizado usa variables de Bootstrap, no valores hardcodeados
• Todos los gráficos tienen texto alternativo para lectores de pantalla
• El contraste de color cumple WCAG AA (4.5:1 para texto)
• Los elementos interactivos son accesibles por teclado

Errores Comunes

• Mezclar UI de Shiny antigua y nueva: No mezcles fluidPage() con componentes bslib. Usa exclusivamente page_sidebar(), page_navbar() o page_fillable().
• Colores hardcodeados en CSS: Usa var(--bs-primary) en lugar de #2c3e50. Los colores hardcodeados se rompen cuando cambia el tema.
• fill = FALSE faltante en filas sin relleno: Las filas de cajas de valor y filas de resumen normalmente no deben estirarse para llenar el espacio disponible. Establece fill = FALSE.
• Google Fonts en entornos sin conexión: Si la app se despliega en una red aislada, usa fuentes del sistema o archivos de fuente auto-alojados en lugar de font_google().
• Ignorar el móvil: Prueba con el modo responsivo del navegador. layout_columns se apila automáticamente en pantallas estrechas, pero el CSS personalizado puede no hacerlo.

Habilidades Relacionadas

• scaffold-shiny-app — configuración inicial de la app incluyendo la configuración del tema
• build-shiny-module — crear componentes UI modulares
• optimize-shiny-performance — renderizado consciente del rendimiento
• review-web-design — revisión de diseño visual para layout, tipografía y color
• review-ux-ui — revisión de usabilidad y accesibilidad