# Design Shiny UI

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

- Skill: `pjt222/design-shiny-ui-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pjt222/design-shiny-ui-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/design-shiny-ui-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/design-shiny-ui-2

---


# 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:

```r
# Sidebar layout — most common for data apps
ui <- page_sidebar(
  title = "My App",
  sidebar = sidebar("Controls here"),
  "Main content here"
)

# Navbar layout — for multi-page apps
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"))
)

# Fillable layout — content fills available space
ui <- page_fillable(
  card(
    full_screen = TRUE,
    plotOutput("plot")
  )
)

# Dashboard layout — grid of value boxes and cards
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

```r
my_theme <- bslib::bs_theme(
  version = 5,                      # Bootstrap 5
  bootswatch = "flatly",            # Optional preset theme
  bg = "#ffffff",                   # Background color
  fg = "#2c3e50",                   # Foreground (text) color
  primary = "#2c3e50",              # Primary brand color
  secondary = "#95a5a6",            # Secondary color
  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:

```r
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

```r
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")
  ),

  # KPI row — non-filling
  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"
    )
  ),

  # Main content row
  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

```r
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
        )
      }
    )
  })

  # Conditional panels (no server round-trip)
  # In 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:

```r
# Inline CSS
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; }
  "))),
  # ...
)

# External CSS file (place in www/ directory)
ui <- page_sidebar(
  theme = my_theme,
  tags$head(tags$link(rel = "stylesheet", href = "custom.css")),
  # ...
)
```

Para integración SCSS con bslib:

```r
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

```r
# Add ARIA labels to inputs
selectInput("category", "Category",
  choices = c("A", "B", "C")
) |> tagAppendAttributes(`aria-describedby` = "category-help")

# Add alt text to plots
output$plot <- renderPlot({
  plot(data(), main = "Distribution of Values")
}, alt = "Histogram showing the distribution of selected values")

# Ensure sufficient color contrast in theme
my_theme <- bslib::bs_theme(
  version = 5,
  bg = "#ffffff",      # White background
  fg = "#212529"       # Dark text — 15.4:1 contrast ratio
)

# Use semantic HTML
tags$main(
  role = "main",
  tags$h1("Dashboard"),
  tags$section(
    `aria-label` = "Key Performance Indicators",
    layout_columns(
      # value boxes...
    )
  )
)
```

**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