IMPROVE theming docs

storybookjs · Mar 4, 2019 · 0dbf67c · 0dbf67c · vercel · Mar 4, 2019
1 parent d173ec5
commit 0dbf67c
Show file tree

Hide file tree

Showing 2 changed files with 120 additions and 102 deletions.
diff --git a/docs/src/pages/configurations/theming/index.md b/docs/src/pages/configurations/theming/index.md
@@ -33,7 +33,7 @@ You can get these themes like so:
 
 ```js
 import { addParameters, configure } from '@storybook/react';
-import { themes } from '@storybook/components';
+import { themes } from '@storybook/theming';
 
 // Option defaults.
 addParameters({
@@ -46,57 +46,58 @@ addParameters({
 
 ## Create a theme quickstart
 
+The `storybook/theming` is build using TypeScript, so this should help create a valid theme for typescript users. The types are part of the package itself.
+
 The easiest way to customize Storybook to generate a new theme using `create()`. This function includes shorthands for the most common theme variables. Here's how to use it.
 
 First create a new file in `.storybook` called `yourTheme.js`.
 
 Next paste the code below and tweak the variables.
 
-```
+```ts
 import { create } from '@storybook/theming';
 
 export default create({
-  // Is this a 'light' or 'dark' theme?
-  base: 'light',
+  base: 'light';
 
-  // Color palette
-  colorPrimary: 'red', // primary color
-  colorSecondary: 'pink', // secondary color
+  colorPrimary: 'hotpink';
+  colorSecondary: 'deepskyblue';
 
   // UI
-  appBg: 'papayawhip',
-  appContentBg: 'white',
-  appBorderColor: 'rgba(0,0,0,.1)',
-  appBorderRadius: 4,
+  appBg: 'white';
+  appContentBg: 'silver';
+  appBorderColor: 'grey';
+  appBorderRadius: 4;
 
-  // Fonts
-  fontBase: '"Helvetica", Arial, sans-serif',
-  fontCode: 'Monaco, monospace',
+  // Typography
+  fontBase: '"Open Sans", sans-serif',
+  fontCode: 'monospace';
 
   // Text colors
-  textColor: '#FFFFFF',
-  textInverseColor: '#333333',
+  textColor: 'black';
+  textInverseColor: 'rgba(255,255,255,0.9)';
 
   // Toolbar default and active colors
-  barTextColor: '#999999',
-  barSelectedColor: 'blue',
-  barBg: 'white',
+  barTextColor: 'silver';
+  barSelectedColor: 'black';
+  barBg: 'hotpink';
 
   // Form colors
-  inputBg: 'white',
-  inputBorder: 'rgba(0,0,0,.1)',
-  inputTextColor: '#333333',
-  inputBorderRadius: 4,
-
-  // Brand logo/text
-  brand: `<svg .../>`,
+  inputBg: 'white';
+  inputBorder: 'silver';
+  inputTextColor: 'black';
+  inputBorderRadius: 4;
+
+  brandTitle: 'My custom storybook';
+  brandUrl: 'https://example.com';
+  brandImage: 'https://placehold.it/350x150';
 });
 ```
 
 Finally, import your theme into `.storybook/config` and add it to your Storybook parameters.
 
-```
-import {yourTheme} from './yourTheme';
+```js
+import { yourTheme } from './yourTheme';
 
 addParameters({
   options: {
@@ -105,13 +106,27 @@ addParameters({
 });
 ```
 
+Many them variables are optional, the `base` property is NOT. This is a perfectly valid theme:
+
+```ts
+import { create } from '@storybook/theming';
+
+export default create({
+  base: 'light';
+
+  brandTitle: 'My custom storybook';
+  brandUrl: 'https://example.com';
+  brandImage: 'https://placehold.it/350x150';
+});
+```
+
 ## Addons and theme creation
 
 Some addons require specific theme variables that a Storybook user must add. If you share your theme with the community make sure to support the official and other popular addons so your users have a consistent experience.
 
 For example, the popular Actions addon uses [react-inspector](https://github.com/xyc/react-inspector/blob/master/src/styles/themes/chromeLight.js) which has themes of it's own. Supply additional theme variables to style it like so:
 
-```
+```js
 addonActionsTheme: {
   ...chromeLight,
   BASE_FONT_FAMILY: typography.fonts.mono,
@@ -123,13 +138,13 @@ addonActionsTheme: {
 
 For a native Storybook experience, we encourage addon authors to reuse the theme variables above. The theming engine relies on [emotion](https://emotion.sh/), a CSS-in-JS library.
 
-```
+```js
 import { styled } from '@storybook/theming';
 ```
 
 Use the theme variables in object notation:
 
-```
+```js
 const Component = styled.div(
   ({ theme }) => ({
     background: theme.background.app,
@@ -138,9 +153,9 @@ const Component = styled.div(
 );
 ```
 
-Or with styled-components template literals:
+Or with template literals:
 
-```
+```js
 const Component = styled.div`
   background: `${props => props.theme.background.app}`
   width: 0;
@@ -149,81 +164,81 @@ const Component = styled.div`
 
 ### Advanced theming
 
-For further customization adjust theme variables manually.
+the `create` function creates an object like this:
 
-This is the master list:
+```js
+{
+  base: 'light' | 'dark',
+  color: {
+    primary
+    secondary
+    tertiary
+    ancillary
+
+    orange
+    gold
+    green
+    seafoam
+    purple
+    ultraviolet
+
+    lightest
+    lighter
+    light
+    mediumlight
+    medium
+    mediumdark
+    dark
+    darker
+    darkest
 
-```
-base: 'light' | 'dark',
-color: {
-  primary
-  secondary
-  tertiary
-  ancillary
-
-  orange
-  gold
-  green
-  seafoam
-  purple
-  ultraviolet
-
-  lightest
-  lighter
-  light
-  mediumlight
-  medium
-  mediumdark
-  dark
-  darker
-  darkest
-
-  border
-
-  positive
-  negative
-  warning
-
-  defaultText
-  inverseText
-}
-background: {
-  app
-  content
-  hoverable
-
-  positive
-  negative
-  warning
-}
-typography: {
-  fonts: {
-    base
-    mono
-  }
-  weight: {
-    regular
-    bold
-    black
-  }
-  size: {
-    s1
-    s2
-    s3
-    m1
-    m2
-    m3
-    l1
-    l2
-    l3
-    code
+    border
+
+    positive
+    negative
+    warning
+
+    defaultText
+    inverseText
+  },
+  background: {
+    app
+    content
+    hoverable
+
+    positive
+    negative
+    warning
+  },
+  typography: {
+    fonts: {
+      base
+      mono
+    }
+    weight: {
+      regular
+      bold
+      black
+    }
+    size: {
+      s1
+      s2
+      s3
+      m1
+      m2
+      m3
+      l1
+      l2
+      l3
+      code
+    }
   }
   input: {
     border
     background
     color
     borderRadius
-  };
+  },
 
   layoutMargin
   appBorderColor
@@ -235,5 +250,8 @@ typography: {
 
   brand
 }
-TODO finish this, what's the best way to document?
 ```
+
+All properties are required.
+
+Again the `@storybook/theming` package is built using TypeScript, so if you do create a theme like this, that should help.
diff --git a/lib/theming/src/create.ts b/lib/theming/src/create.ts
@@ -11,7 +11,7 @@ interface Rest {
 }
 
 interface ThemeVar {
-  base?: 'light' | 'dark';
+  base: 'light' | 'dark';
 
   colorPrimary?: string;
   colorSecondary?: string;