Merge pull request #10114 from storybookjs/9662-docs-theme

Addon-docs: Theme with `docs.theme` parameter

addons/docs/docs/theming.md

@@ -9,23 +9,33 @@
 
 ## Storybook theming
 
-Storybook theming is the **recommended way** to theme your docs. If you update your storybook theme according to [the documentation](https://storybook.js.org/docs/configurations/theming/), Storybook Docs should adapt in reasonable ways.
+Storybook theming is the **recommended way** to theme your docs. Docs uses the same theme system as [Storybook UI](https://storybook.js.org/docs/configurations/theming/), but is themed independently from the main UI.
 
-> In the documentation it will say you can theme storybook in `manager.js`, That's a newer more optimal way to theme storybook, but it's currently incompatible with docs.
->
-> We're working on making it compatible in 6.0.0, so for now use the method described below.
+Supposing you have a Storybook theme defined for the main UI in `.storybook/manager.js`:
 
-Here's how to change your docs (and Storybook) to the dark theme, by modifying `.storybook/preview.js`:
+```js
+import { addons } from '@storybook/addons';
+// or a custom theme
+import { themes } from '@storybook/theming';
+
+addons.setConfig({
+  theme: themes.dark,
+});
+```
+
+Here's how you'd specify the same theme for docs in `.storybook/preview.js`:
 
 ```js
-import { addParameters } from '@storybook/react';
 import { themes } from '@storybook/theming';
 
-addParameters({
-  options: {
-    theme: themes.dark,
+// or global addParameters
+export default {
+  parameters: {
+    docs: {
+      theme: themes.dark,
+    },
   },
-});
+};
 ```
 
 ## CSS escape hatches

addons/docs/src/blocks/DocsContainer.tsx

@@ -1,5 +1,7 @@
 import React, { FunctionComponent, useEffect } from 'react';
 import { document, window } from 'global';
+import deprecate from 'util-deprecate';
+import dedent from 'ts-dedent';
 import { MDXProvider } from '@mdx-js/react';
 import { ThemeProvider, ensure as ensureTheme } from '@storybook/theming';
 import { DocsWrapper, DocsContent } from '@storybook/components';
@@ -23,10 +25,20 @@ const defaultComponents = {
 
 export const DocsContainer: FunctionComponent<DocsContainerProps> = ({ context, children }) => {
   const { id: storyId = null, parameters = {} } = context || {};
-  const options = parameters.options || {};
-  const theme = ensureTheme(options.theme);
-  const { components: userComponents = null } = parameters.docs || {};
-  const allComponents = { ...defaultComponents, ...userComponents };
+  const { options = {}, docs = {} } = parameters;
+  let themeVars = docs.theme;
+  if (!themeVars && options.theme) {
+    deprecate(
+      () => {},
+      dedent`
+        options.theme => Deprecated: use  story.parameters.docs.theme instead.
+        See https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/theming.md#storybook-theming for details.
+    `
+    )();
+    themeVars = options.theme;
+  }
+  const theme = ensureTheme(themeVars);
+  const allComponents = { ...defaultComponents, ...docs.components };
 
   useEffect(() => {
     let url;

examples/official-storybook/preview.js

@@ -50,6 +50,7 @@ addParameters({
     { name: 'dark', value: '#222222' },
   ],
   docs: {
+    theme: themes.light,
     page: () => <DocsPage subtitleSlot={({ kind }) => `Subtitle: ${kind}`} />,
   },
 });