# Stylish

Welcome to Stylish - a clean, simple, customizable, theme aware, appearance 
only stylesheet.

Stylish provides visual appearance styling only, no script behaviours and no 
layout functionality. This is intentional.

In the following examples, click the </> buttons on the right
to view the underlying markup/script.

## Auto, Light and Dark Themes

Stylish supports light and dark themes.  By default the mode is selected
based on the user's preference, or you can force one or the other by
adding the `dark` or `light` class to the root `<html>` element 
of the document.

To simplify user selection of theme, stylish includes a theme switcher
checkbox (use the class 'theme-switch') and a script file to manage 
switching themes and saving the user preference.

In the `<head>` section of your page, add a reference to
`stylish-theme.js`

```
<script src="./stylish-theme.js"></script>
```

Once the script is loaded, the following API is available:

* `window.stylish.toggleMode` - toggles between dark and light modes
* `window.stylish.darkMode` - returns `true` if currently in dark mode
* `window.stylish.setThemeSwitches` - updates the state of all `theme-switch` classed checkboxes
* `window.stylish.addEventListener('darkModeChanged', (ev) => {ev.darkMode})` - notifies when dark mode changes

Note: the script stores the current selection in local storage with the
key `stylish-theme`.  When the selected theme matches the browser's user
preference the selection is saved as "auto".

## Colors

Stylish uses several classes to change the primary color of items:

* `accent`
* `success`
* `info`
* `warning`
* `danger`

## Text Styles

A normal paragraph

Colored text: accent success info warning danger

A link toptensoftware.com.

A link with warning color warning link.

The muted class can be used to dim text.

Heading 1

Paragraph

Heading 2

Paragraph

Heading 3

Paragraph

Heading 4

Paragraph

Heading 5

Paragraph

Heading 6

Paragraph

## Nav Areas

In `<nav>` sections:

* `<a>` links use normal body text color instead
of the in-text highlight color
* `<ul>` list items have bullets removed

## Buttons

Buttons support the the following classes:

* color classes as shown above
* `subtle` to remove the background from a button until hovered
* `dropdown` to add a drop down Arrow
* `small` and `large` to change the button size

Active:

Link

Disabled:

Subtle:

Link

Subtle Muted:

Link

With Drop Arrow:

Sized:

## Pills

Use the `pill` class on a `<span>` to make a pill.  The `small`
and `large` classes adjust the pill size:

Normal Accent Success Info Warning Danger

Small Medium Large

## Text Fields

Use the color classes re-color a the border of most controls:

Pick a Color

Text Area

## Control Groups

Control groups combine several controls together to appear as a single 
multi-part control.  

Use `<span>` to put indicators around text 
fields, or see below for examples of grouping radio and checkbox buttons.

$ .00

## Radio Buttons

Radio buttons can be styled with color classes, or made to 
look like buttons by adding the `button` class to the input 
element.  

Note: For button looking radio buttons the `<label>` 
must not be wrapping the input - it must placed as immediately
following sibling of the `<input>`.

Normal:

Radio 1

Radio 2

Radio 3

Horizontal:

Radio 1 Radio 2 Radio 3

Grouped Button Style:

Radio 1 Radio 2 Radio 3

Ungrouped Button Style:

Radio 1 Radio 2 Radio 3

## Checkboxes

Radio buttons can be styled with color classes, or made to 
look like buttons by adding the `button` class to the input 
element.  

Adding the `switch` class to a checkbox makes it appear as
a horizontal sliding switching instead of a checkmark.

Note: For button looking radio buttons the `<label>` 
must not be wrapping the input - it must placed as immediately
following sibling of the `<input>`.

Normal:

Checkbox

Colored Checkbox

Disabled Checkbox

Horizontal:

Apples Pears Bananas

Switches:

Switch

Colored Switch

Disabled Switch

Grouped Button Style:

Check 1 Check 2 Check 3

Ungrouped Button Style:

Check 1 Check 2 Check 3

Subtle Button Style:

Check 1 Check 2 Check 3

## Spinners

To create a spinner just add the `spinner` class to an
empty `<span>`.

Use `xsmall`, `small`, `large` and `xlarge` classed to adjut
the size of the spinner.

## Dialog Frames

Dialogs should be constructed with the following HTML structure:

```
dialog
    form
        header
            button.close
            span.title
        main
            (put your dialog content here)
        footer
            (put your OK, cancel buttons here)
            
```

## Grid System

Although Stylish is mostly about visual styling it also includes
a simple cell-12 system.

To use the grid system:

1. Use the class `grid` on the container (usually a `<div>`)
2. On the grid cells assign classes of the form `cell-N-M` where:
    * N is the column number to place the item in.
    * M is number of columns across the horizontal space.

For example:

* `cell-1-1` divides the horizontal space by 1, and uses the first column 
  (ie: full width)
* `cell-1-2` the first of two columns
* `cell-2-2` the second of two columns
* `cell-3-4` the third of four columns
* etc...

To span multiple columns, use two digits for `N` where the first is the
first column number and the second is the last column number.  (eg:
`cell-24-4` is columns 2,3 and 4 of a 4 column split).

1-1

1-2

2-2

1-3

2-3

3-3

1-3

23-3

12-3

3-3

1-4

2-4

3-4

4-4

1-4

23-4

4-4

1-4

24-4

13-4

4-4

1-6

2-6

3-6

4-6

5-6

6-6

1-6

23-6

45-6

6-6

## Customization

Most aspects of the theme can be adjusted with CSS variables applied
to the root element of the document:

Fonts:

* `--font-family` - the font family used by all text and controls
* `--font-size` - the base font size

To customize colors, provide colors for both the dark and the light theme:

* `--[dark/light]-link-color` - color for text links
* `--[dark/light]-button-color` - color for buttons without a color class
* `--[dark/light]-accent-color` - color of the `accent` color class
* `--[dark/light]-success-color` - color of the `success` color class
* `--[dark/light]-info-color` - color of the `info` color class
* `--[dark/light]-warning-color` - color of the `warning` color class
* `--[dark/light]-danger-color` - color of the `danger` color class
* `--[dark/light]-body-back-color` - color of the main document background
* `--[dark/light]-body-fore-color` - color of the text in the main document

All other colors are derived from the above and can be used when
styling your own elements:

* `--contrast-color` - the color of text in front of the other class colors
* `--focus-color` - color for focus-visible outline highlights
* `--link-color` - color for text links
* `--code-color` - color for code text
* `--gridline-color` - color for grid lines and outlines
* `--fore-color` - white for dark theme, black for light theme
* `--back-color` - black for dark theme, white for light Theme
* `--fore-color-l` - fore color luminosity (useful for blending other colors towards)
* `--back-color-l` - back color luminosity (useful for blending other colors towards)
* `--button-color` - color for buttons without a color class
* `--accent-color` - color of the `accent` color class
* `--success-color` - color of the `success` color class
* `--info-color` - color of the `info` color class
* `--warning-color` - color of the `warning` color class
* `--danger-color` - color of the `danger` color class
* `--body-back-color` - color of the main document background
* `--body-fore-color` - color of text in the main document
* `--class-text-color` - text color for the currently selected color class
* `--class-back-color` - background color for currently selected color class
* `--class-fore-color` - foreground color for currently selected color class
* `--class-accent-color` - accent color for currently selected color class