diff --git a/docs/dls/contributing-to-storybook.md b/docs/dls/contributing-to-storybook.md index 058f4a23a7..41d2b56ec2 100644 --- a/docs/dls/contributing-to-storybook.md +++ b/docs/dls/contributing-to-storybook.md @@ -4,8 +4,38 @@ title: Contributing to Storybook description: Documentation on How to Contribute to Storybook --- +Storybook is an open source tool to provide users a way to explore the Backstage +UI elements and how to use them in developing the Backstage core and its +plugins. These UI elements are commonly called "components", and include things +such as buttons, tables, specialized widgets with specific formatting, and so +on. + You find our storybook at -[http://backstage.io/storybook](http://backstage.io/storybook) +[http://backstage.io/storybook](http://backstage.io/storybook). + +As noted in the [design introduction](design.md), Backstage's design is based +off of [Material-UI](https://material-ui.com/). Much of the UI elements use +direct Material-UI, while we've also extended and written custom ones to provide +specific functionality. + +![Storybook Page](../assets/dls/storybook-page.png) + +Storybook "Stories" are used to provide examples for how to use a specific +component, which are then displayed both visually and with sample code to be +copied. + +When custom Backstage components are created, they are placed in the +`@backstage/core` package and added to the Storybook. + +There may be times where an existing Material-UI component (in +`@material-ui/core`) is sufficient and doesn't need to be wrapped or duplicated. +However, we may want to identify an _opinionated_ way to use that component +inside of Backstage. In these cases, stories showing how to use those existing +components will also be put into our storybook. + +When a story example using Material-UI becomes more complex, requiring a +specific set of colors, variants, parameters, etc., it may become a candidate to +be refactored to become a full Backstage core component. ## Creating a new Story @@ -33,12 +63,10 @@ core Go to `packages/storybook`, run `yarn install` and install the dependencies, then run the following on your command line: `yarn start` -![](../assets/dls/running-storybook.png) +![Storybook command startup](../assets/dls/running-storybook.png) _You should see a log like the image above._ If everything worked out, your server will be running on **port 6006**, go to your browser and navigate to `http://localhost:6006/`. You should be able to navigate and see the Storybook page. - -![](../assets/dls/storybook-page.png)