Add a theme-variables.md doc

docs/creating-a-package.md

@@ -126,9 +126,9 @@ the command palette (`cmd-p`) and search for _styleguide_ or just
 `cmd-ctrl-shift-g`.
 
 If you do need styling, we try to keep only structural styles in the package
-stylesheets. Colors and sizing should be taken from the active theme's
-[ui-variables.less][ui-variables]. If you follow this guideline, your package
-will look good out of the box with any theme!
+stylesheets. If you must specify colors and sizing, these should be taken from
+the active theme's [ui-variables.less][ui-variables]. If you follow this
+guideline, your package will look good out of the box with any theme!
 
 An optional `stylesheets` array in your _package.json_ can list the stylesheets
 by name to specify a loading order; otherwise, stylesheets are loaded

docs/theme-variables.md

@@ -0,0 +1,111 @@
+# Style variables
+
+Atom's UI themes provide a set of variables you can use in your own themes and packages.
+
+## Use in UI Themes
+
+The main UI theme must specify a `ui-variables.less` file with all of the
+following variables. The top-most theme specified in the theme settings will be
+loaded and available for import.
+
+## Use in packages
+
+In any of your package's `.less` files, you can get access to the variables
+by importing the `ui-variables` file from Atom. The
+
+Your package should generally only specify structural styling. Your package
+should not specify colors or padding size in absolute pixels. You should instead
+use these variables. If you follow this guideline, your package will look good
+out of the box with any theme!
+
+```css
+@import "ui-variables";
+
+.my-selector{
+  background-color: @base-background-color;
+  padding: @component-padding;
+}
+```
+
+## Variables
+
+### Text colors
+
+* `@text-color`
+* `@text-color-subtle`
+* `@text-color-highlight`
+* `@text-color-selected`
+* `@text-color-info` - A blue
+* `@text-color-success`- A green
+* `@text-color-warning`- An orange or yellow
+* `@text-color-error` - A red
+
+### Background colors
+
+* `@background-color-info` - A blue
+* `@background-color-success` - A green
+* `@background-color-warning` - An orange or yellow
+* `@background-color-error` - A red
+* `@background-color-highlight`
+* `@background-color-selected`
+* `@app-background-color` - The app's background under all the editor components
+
+### Component colors
+
+* `@base-background-color` -
+* `@base-border-color` -
+
+* `@pane-item-background-color` -
+* `@pane-item-border-color` -
+
+* `@input-background-color` -
+* `@input-border-color` -
+
+* `@tool-panel-background-color` -
+* `@tool-panel-border-color` -
+
+* `@inset-panel-background-color` -
+* `@inset-panel-border-color` -
+
+* `@panel-heading-background-color` -
+* `@panel-heading-border-color` -
+
+* `@overlay-background-color` -
+* `@overlay-border-color` -
+
+* `@button-background-color` -
+* `@button-background-color-hover` -
+* `@button-background-color-selected` -
+* `@button-border-color` -
+
+* `@tab-bar-background-color` -
+* `@tab-bar-border-color` -
+* `@tab-background-color` -
+* `@tab-background-color-active` -
+* `@tab-border-color` -
+
+* `@tree-view-background-color` -
+* `@tree-view-border-color` -
+
+* `@ui-site-color-1` -
+* `@ui-site-color-2` -
+* `@ui-site-color-3` -
+* `@ui-site-color-4` -
+* `@ui-site-color-5` -
+
+### Component sizes
+
+* `@disclosure-arrow-size` -
+
+* `@component-padding` -
+* `@component-icon-padding` -
+* `@component-icon-size` -
+* `@component-line-height` -
+* `@component-border-radius` -
+
+* `@tab-height` -
+
+### Fonts
+
+* `@font-size` -
+* `@font-family` -