11-simpleDesign.Rmd

# (PART) Style Guide-Design Style {-}

# Design Style {#designStyle -}

Design Style is the second side of the Visual Appearance of every app. Here, we deal with visual aspects that go beyond the layout of your App. This includes issues of branding, color, how you make text look (font, size, emphasis), and graphics (plots, tables, and images).

We've broken Design Style into three parts:

11) ["Simple" Design Matters: Branding, Color, and Text](#simpleDesign)
12) [Static Images](#staticImages)
13) [`R` Graphics--Plots, Graphs, and Tables](#graphics)

You'll want to make sure that you look through each of these components, especially the section on R Graphics.

# Branding, Color, and Text {#simpleDesign}

The "Simple" Design matters include [PSU Branding](#logo), [Color](#colorChoices), and [Text Styling](#styleText). We refer to these as "simple" matters for the fact that for the most part, there is very little for you to have do decide. Rather, you just need to make sure that you are attending to guidelines we've laid out in this Style Guide. In other words, we've done all of the hard work for you in these cases.

## PSU Branding {#logo}

Given that we are all associated with Pennsylvania State University, we need to include the Penn State logo in each App. Rather than sticking the logo at the top of the Overview page, we are going to place the logo at the bottom of the sidebar. This has the benefit of having the logo appear throughout the entire App AND making the logo be as unobtrusive as possible.

If you have followed the directions for the [Sidebar Layout](#sidebar), then you don't have much to worry about as those instructions will ensure that you have properly branded your App.

## Colors {#colorChoices}

Your App needs to have a consistent color scheme throughout. The color scheme should be checked against colorblindness to meet [WCAG 2.1](https://www.w3.org/WAI/WCAG21/quickref/) Level AA. You can do so at the [Coloring for Colorblindness](https://davidmathlogic.com/colorblind/#%23000000-%23E69F00-%2356B4E9-%23009E73-%23F0E442-%230072B2-%23D55E00-%23CC79A7) website.  If you are following this Style Guide (as you should be) then the vast majority of this section will be automatically handled for you.

See [Section \@ref(colorUI)](#colorUI) and [Section \@ref(colorPlots)](#colorPlots) for additional information on the use of colors.

## Text Styling {#styleText}

Text styling refers the non-content aspects of the text on the page, such as the use of italics, boldface, alignment, as well as font size and color.

You should let the centralized CSS file do the heavy lifting for text styling. (Again, using `boastApp` will help you.) However, for this to work properly, you will need to tag content appropriately. (See the section on HTML, [Section \@ref(html)](#html).)

If you run into a situation where some element needs additional styling, __talk to Neil for help__. You might have come across an element that needs to get added the central CSS file or a bug.

### Headings

Use the Heading Tags for the short fragments that define the structure of your App. If you find yourself enclosing a complete sentence in Heading tag, you ARE NOT using headings correctly. Notice how the headings in this Style Guide aren’t complete sentences; your App should mimic this. Full sentences appear as regular paragraph text (i.e., enclosed in `p()`) and not be a Heading.

### Paragraph Text

If you enclose text that gives instructions or other information to your App’s users in `p()` or `li()` (the later should be wrapped in either `tags$ol()` or `tags$ul()`), your App will understand how to style that text correctly. The central CSS file contains controls that set the base font size much larger than Shiny does natively as well as making text sizing dynamic. (This is important for making our apps mobile device friendly.) Again, using `boastApp` makes this process easier.

If you want to make a certain word or phrase italic, you will need to wrap that text in `tags$em()`. Similarly, if you want do the same with boldface, you’ll use `tags$strong()`.

For example, this code:

```{r paraStyle1, echo=TRUE, eval=FALSE}
p(
  "When dealing with the ",
  tags$em("t"),
  "-distribution, we only have one parameter, the ",
  tags$strong("degrees of freedom"),
  "that we need to input."
)
```

Becomes:  

> When dealing with the *t*-distribution, we only have one parameter, the __degrees of freedom__ that we need to input.

Use italics (emphasis), and boldface (strong) sparingly.

### Mathematics

For the most part, any mathematics you need displayed should be done using [MathJax](https://www.mathjax.org/). Default to using inline typesetting with the `\\(` and `\\)` delimiters. If you need to use display style, you can use `\\[` and `\\]`. For the vast majority of mathematics, you’ll wrap both inline and display style mathematics inside of a paragraph environment (`p()`).

If you’re writing mathematics directly in your app, remember you’ll need to escape the LaTeX commands by putting an extra backslash (\\) in front; e.g., `\frac{3}{4}` would need to be `\\frac{3}{4}`.

If you’re reading in mathematical text from an external CSV file, you do not need the extra backslash in the CSV file.

If you need assistance in figuring out how to type up mathematics, please talk to Neil or Dennis.

__Note:__ Double dollar sign delimiters are generally not recommended for displaying math as they can lead to unintended results. See: [Writing Mathematics for MathJax](https://docs.mathjax.org/en/latest/basic/mathematics.html).

### [Game] Question Text

The text used as a question in a game should NOT be wrapped in a Heading tag; wrap the text in a paragraph tag.

### Label Text (Buttons, Sliders, Other Inputs and Alerts)

By using the central CSS file, any text you included in/on buttons, dropdown menus, sliders, radio buttons, choices, and other inputs as well as alert messages and popups/rollovers, will automatically be styled correctly.

Do not use heading tags, the paragraph tag, italics/emphasis, or boldface/strong with input labels. Input labels should be written in sentence case (i.e., capitalize only the first word and any proper nouns).

You may use these tags with popups/rollovers.

### Feedback and Hint Text

Again, let the central CSS file handle the styling of this type of text.

### Text in `R` Plots

Unfortunately, any text in `R` plots does not get controlled by CSS. This means that you’ll have to play around with the settings. Using the `ggplot2` package to make your plots (or other packages based upon the `grid` framework like `lattice`) will allow you to use the `theme` aspect to control text in your App.

Here is an example for how to do this:

```{r plotText1, echo=TRUE, eval=FALSE}
# Create a ggplot2 object
g1 <- ggplot2::ggplot(data=df, aes(x=x, y=y, color=grp)) 
# Add your layers, for example
g1 + ggplot2::geom_point()
# Use theme to control text size
g1 + ggplot2::theme(
  plot.caption = element_text(size = 18),
  text = element_text(size = 18)
  )
```

You will need to play around with the settings to find the appropriate value; text size 18 appears to work out well in many cases.

__Note:__ The text in your plot might not behave well for dynamic re-sizing on different mobile devices.

### Text Case

When writing text, you should use the appropriate case (i.e., which words you capitalize):

+ Headings: Use Title Case
+ Paragraphs/lists: use sentence case
+ Input labels: use sentence case
+ Figure Captions: Use Title Case
+ Table Captions: Use Title Case
+ Graphs (see [Section \@ref(graphLab)](#graphLab))
    - Titles: Use Title Case
    - Axes: use sentence case
    - Legends: use sentence dase
+ Default: sentence case