---
title: "Styling and Theming"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Styling and Theming}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Overview

`shiny.webawesome` follows upstream Web Awesome styling patterns closely.

In practice, there are two main levels to know:

- page-level theming, palettes, and brand selection
- component-level styling through ordinary HTML hooks and Web Awesome design
  tokens

This article gives a short package-specific map and points you back to the
upstream Web Awesome docs for the broader styling system.

# Page-Level Themes and Palettes

Web Awesome's theme system is page-oriented, with theme, palette, and brand
classes applied to the `<html>` element. For example:

- `wa-palette-default`
- `wa-theme-default wa-palette-default wa-brand-blue`

In `shiny.webawesome`, the corresponding place to do that is
`webawesomePage(class = ...)`.

This executed example prints the HTML scaffold emitted by a themed
`webawesomePage()` call:

```{r styling-and-theming-executed}
library(shiny.webawesome)

themed_page <- webawesomePage(
  title = "Themed preview",
  class = "wa-theme-default wa-palette-default wa-brand-blue",
  wa_card("Styled preview")
)

cat(as.character(themed_page), sep = "\n")
```

Here is the corresponding full Shiny page pattern:

```{r theming-default, eval = FALSE}
library(shiny)
library(shiny.webawesome)

ui <- webawesomePage(
  title = "Themed page",
  class = "wa-theme-default wa-palette-default wa-brand-blue",
  wa_container(
    class = "wa-stack",
    style = "max-width: 32rem; margin: 2rem auto;",
    wa_badge("Beta", appearance = "filled"),
    wa_card("This page applies Web Awesome classes at the html root.")
  )
)

server <- function(input, output, session) {}

shinyApp(ui, server)
```

For the bundled non-default themes, `webawesomePage()` also recognizes the
root classes `wa-theme-awesome` and `wa-theme-shoelace` and loads the
matching bundled theme stylesheet automatically.

```{r theming-nondefault, eval = FALSE}
ui <- webawesomePage(
  title = "Awesome theme",
  class = "wa-theme-awesome wa-palette-bright wa-brand-blue",
  wa_container(
    style = "max-width: 32rem; margin: 2rem auto;",
    wa_card("The matching Awesome theme stylesheet is attached automatically.")
  )
)
```

For broader upstream theme and palette guidance, consult the upstream Web
Awesome theming documentation. The package keeps the control surface
upstream-first by treating page-root classes as the main theming hook.

# Styling Individual Components

For individual components, the first styling hooks are the standard wrapper
arguments `class` and `style`.

```{r component-class-style, eval = FALSE}
wa_card(
  "Styled card",
  class = "my-card",
  style = "max-width: 32rem;"
)
```

That works well for:

- ordinary CSS class hooks
- small app-local layout adjustments
- utility-class usage

When you need additional standard HTML attributes, append them with
`htmltools::tagAppendAttributes()`. See the `Extra Attributes via htmltools`
article for that pattern.

## Design tokens

Web Awesome also documents a larger design-token system for colors, spacing,
typography, shadows, and related styling primitives.

In `shiny.webawesome`, the intended approach is still upstream-first:

- apply page-level classes with `webawesomePage(class = ...)`
- style component instances with normal `class` and `style` hooks
- use Web Awesome design tokens in your app CSS when you need more control

For example, you can target a custom class and rely on Web Awesome token
variables in your own stylesheet:

```css
.my-card {
  border-color: var(--wa-color-brand-border-normal);
  box-shadow: var(--wa-shadow-l);
  padding: var(--wa-space-l);
}
```

This package does not try to wrap the full design-token catalog as a separate
R API. The goal is to stay close to upstream so that the Web Awesome styling
docs remain directly useful.

# Related Guidance

- Use `webawesomePage(class = ...)` for page-level theme, palette, and brand
  classes.
- Use wrapper `class` and `style` arguments for ordinary component-level
  styling hooks.
- Use `htmltools` when you need extra HTML attributes beyond the wrapper
  surface.
- Consult the upstream Web Awesome docs for the full theming and design-token
  system.
