Refine the theming docs (#507)

Co-authored-by: Benjamin Wiederkehr <benjamin@interactivethings.com>

Author: wiederkehr

docs/configuration/theming.md

@@ -1,72 +1,123 @@
-## Theming Catalog
-
-### `logoSrc`
-
-`string`
-
-Path to a logo image file which will be placed in the top-left corner.
-
-### `theme`
-
-`Object`
-
-Object which describes which colors, fonts and font sizes to use.
-
-```code
-…
-title: 'Catalog',
-theme: {
-  <theme configuration here…>
-}
-…
+> Catalog offers a few ways to customize the appearance to match your project. All of the customization options below can be made by changing the attributes of the `Catalog` component in `index.js`.
+
+## Logo
+You can add a plain text title or logo image to the header section of the sidebar. To use text, change the `title` attribute and if you’d like to use an image, add the URL of the image to the `logoSrc`.
+
+- `title` (`string`)
+- `logoSrc` (`string`)
+
+
+## Theme
+The visual design of the user interface of Catalog is customizable. Simply add a `theme` attribute to the `Catalog` component in `index.js` and override the default values below with your custom CSS definitions.
+
+- `theme` (`object`)
+
+### Base Typography
+```table
+rows:
+  - Attribute: '`baseFontSize`'
+    Default: '`16`'
+    Application: Base font size.
+  - Attribute: '`msRatio`'
+    Default: '`1.2`'
+    Application: Modular scale ratio for font sizes.
+  - Attribute: '`fontFamily`'
+    Default: '`Roboto, sans-serif`'
+    Application: Font family of the body text.
+  - Attribute: '`fontHeading`'
+    Default: '`Roboto, sans-serif`'
+    Application: Font family of the headings.
+  - Attribute: '`fontMono`'
+    Default: '`Source Code Pro, monospace`'
+    Application: Font family of the code text.
 ```
 
-#### `fontFamily` / `fontHeading` / `fontMono`
-
-The name (including any fallback fonts) of the font for copy text, headings and pre/code blocks.
-
-#### `baseFontSize` / `msRatio`
-
-The font size is derived from these two values. Default is 16px / 1.2. See [modularscale](http://www.modularscale.com/?16&px&1.2&web&text).
-
-#### Colors
-
-The [src/DefaultTheme.js](https://github.com/interactivethings/catalog/blob/master/src/DefaultTheme.js) file contains all colors which you can set.
-
-##### `background`, `textColor`, `codeColor`, `linkColor`
-
-The primary foreground and background colors.
-
-##### `lightColor`
-
-Used as a foreground or border color.
-
-##### `pageHeading{Background,TextColor,Height}`
-
-Used in PageHeader. `pageHeadingHeight` is not a color but the height of the
-whole PageHeader component.
-
-##### `navBar{Background,TextColor}`
-
-Used in the navigation bar.
-
-##### `brandColor`
-
-ResponsiveTabs (tab text), Download specimen (title text).
-Typography: headings.
+### Base Colors
+```table
+rows:
+  - Attribute: '`brandColor`'
+    Default: '`#003B5C`'
+    Application: Accent color used for headings
+  - Attribute: '`textColor`'
+    Default: '`#333333`'
+    Application: Font color of the text in the main column.
+  - Attribute: '`codeColor`'
+    Default: '`#00263E`'
+    Application: Font color of the code in the main column.
+  - Attribute: '`linkColor`'
+    Default: '`#FF5555`'
+    Application: Font color of links in the main column.
+  - Attribute: '`lightColor`'
+    Default: '`#D6D6D6`'
+    Application: Border color used for blockquotes in main column.
+```
 
-##### `sidebarColor{,Text,TextActive,Line,Heading}`
+### Page Header
+```table
+rows:
+  - Attribute: '`pageHeadingBackground`'
+    Default: '`#003B5C`'
+    Application: Background color of the header in the main column.
+  - Attribute: '`pageHeadingTextColor`'
+    Default: '`#FFFFFF`'
+    Application: Font color of the header in the main column.
+  - Attribute: '`pageHeadingHeight`'
+    Default: '`200`'
+    Application: Height of the header in the main column and sidebar.
+```
 
-Used in the sidebar.
+### Main Column
+
+```table
+rows:
+  - Attribute: '`background`'
+    Default: '`#F9F9F9`'
+    Application: Background color of the body in main column.
+  - Attribute: '`bgLight`'
+    Default: '`#F2F2F2`'
+    Application: Background color of light specimens.
+  - Attribute: '`bgDark`'
+    Default: '`#333333`'
+    Application: Background color of dark specimens.
+```
 
-##### `bg{Light,Dark}`, `checkerboardPattern{Light,Dark}`
+### Sidebar
+```table
+rows:
+  - Attribute: '`sidebarColor`'
+    Default: '`#FFFFFF`'
+    Application: Background color of the body in sidebar column.
+  - Attribute: '`sidebarColorLine`'
+    Default: '`#EBEBEB`'
+    Application: Border color of the links in sidebar column.
+  - Attribute: '`sidebarColorHeading`'
+    Default: '`#003B5C`'
+    Application: Font color of the header in the sidebar column.
+  - Attribute: '`sidebarColorText`'
+    Default: '`#003B5C`'
+    Application: Font color of the list items in the sidebar column.
+  - Attribute: '`sidebarColorTextActive`'
+    Default: '`#FF5555`'
+    Application: Font color of the active list item in the sidebar column.
+```
 
-Background colors and patterns for html, react, and image specimens.
+### Navigation Bar
+```table
+rows:
+  - Attribute: '`navBarBackground`'
+    Default: '`#F2F2F2`'
+    Application: Background color of the navigation bar at the bottom of the main column.
+  - Attribute: '`navBarTextColor`'
+    Default: '`#003B5C`'
+    Application: Font color of the navigation bar at the bottom of the main column.
+```
 
-##### `codeStyles`
+### Code Syntax Styles
+The code syntax highlighting is based on based on [PrismJS](http://prismjs.com/) and can be adjusted with `codeStyles`.
 
-Map from [PrismJS](http://prismjs.com/) token type to style object. Example:
+- `codeStyles` (`object`)
 
+Example:
 ```code
 codeStyles: {
   tag: {color: '#FF5555', fontWeight: 'bold'}