Merge pull request #343 from chromaui/chore_reword_design_systems

Author: domyen

content/design-systems-for-developers/index.md

@@ -79,7 +79,7 @@ twitterShareText: "I’m learning about building design systems! They're great f
     Prettier
   </div>
   <div class="badge">
-    CircleCI
+    GitHub Actions
   </div>
   <div class="badge">
     ESLint

content/design-systems-for-developers/react/en/build.md

@@ -55,16 +55,18 @@ Your Storybook should reload like this (notice that the font styles are a little
 
 #### Add global styles
 
-Our design system requires some global styles (a CSS reset) to be applied to the document for components to be rendered correctly. The styles can be added easily via a Styled Components global style tag. For reference here is how the code is exported from `src/shared/global.js`:
+Our design system requires some global styles (a CSS reset) to be applied to the document for components to be rendered correctly. The styles can be added easily via a Styled Components global style tag. Adjust your global styles, located in `src/shared/global.js` to the following:
 
 ```javascript
+// src/shared/global.js
+
 import { createGlobalStyle, css } from 'styled-components';
 import { color, typography } from './styles';
 
 export const fontUrl = 'https://fonts.googleapis.com/css?family=Nunito+Sans:400,700,800,900';
 
 export const bodyStyles = css`
-  /* global styles */
+  /* same as before */
 `;
 
 export const GlobalStyle = createGlobalStyle`
@@ -77,6 +79,8 @@ export const GlobalStyle = createGlobalStyle`
 To use the `GlobalStyle` “component” in Storybook, we can make use of a decorator (a component wrapper). In an app we’d place that component in the top-level app layout, but in Storybook we wrap all stories in it using the preview config file `.storybook/preview.js`
 
 ```javascript
+// .storybook/preview.js
+
 import React from 'react';
 import { addDecorator } from '@storybook/react';
 import { GlobalStyle } from '../src/shared/global';
@@ -116,6 +120,8 @@ The [actions addon](https://github.com/storybookjs/storybook/tree/next/addons/ac
 Let’s see how to use it in our Button element, which optionally takes a wrapper component to respond to clicks. We have a story that passes an action to that wrapper:
 
 ```javascript
+// src/Button.js
+
 import React from 'react';
 import styled from 'styled-components';
 import { action } from '@storybook/addon-actions';
@@ -145,6 +151,8 @@ yarn add --dev  @storybook/addon-storysource
 Add the addon in `.storybook/main.js`:
 
 ```javascript
+//.storybook/main.js
+
 module.exports = {
   stories: ['../src/**/*.stories.js'],
   addons: [
@@ -173,6 +181,8 @@ yarn add --dev @storybook/addon-knobs
 Add the addon in `.storybook/main.js`:
 
 ```javascript
+//.storybook/main.js
+
 module.exports = {
   stories: ['../src/**/*.stories.js'],
   addons: [
@@ -188,6 +198,8 @@ module.exports = {
 Add a story that uses knobs in `src/Avatar.stories.js`:
 
 ```javascript
+//src/Avatar.stories.js
+
 import React from 'react';
 import { withKnobs, select, boolean } from '@storybook/addon-knobs';
 
@@ -219,6 +231,8 @@ We'll visit the Accessbility and Docs addons in later chapters.
 
 ## Learn how to automate maintenance
 
-Now that our design system components are in Storybook, we need to set up the automated tooling that streamlines ongoing maintenance. A design system, like all software, should evolve. The challenge is to ensure UI components continue to look and feel as intended as the design system grows.
+Now that our design system components are in Storybook, we've taken one more step to create a industry-standard design system. Now it's a good time to commit our work to our remote repository. Then we can start thinking about how we setup the automated tooling that streamlines ongoing maintenance.
+
+A design system, like all software, should evolve. The challenge is to ensure UI components continue to look and feel as intended as the design system grows.
 
 In chapter 4 we’ll learn how to set up continuous integration and auto-publish the design system online for collaboration.

content/design-systems-for-developers/react/en/distribute.md

@@ -44,6 +44,8 @@ Learn more at [Learn Storybook](https://learnstorybook.com).
 Then, let’s create a `src/index.js` file to create a common entry point for using our design system. From this file we’ll export all our design tokens and the components:
 
 ```javascript
+//src/index.js
+
 import * as styles from './shared/styles';
 import * as global from './shared/global';
 import * as animation from './shared/animation';
@@ -71,7 +73,7 @@ To build the package, we’ll add a script to `package.json` that builds our sou
   "scripts": {
     "build": "cross-env BABEL_ENV=production babel src -d dist",
       ...
-  }
+  },
   "babel": {
     "presets": [
       "react-app"
@@ -84,7 +86,6 @@ We can now run `yarn build` to build our code into the `dist` directory -- we sh
 
 ```
 // ..
-storybook-static
 dist
 ```
 
@@ -154,7 +155,6 @@ NPM_TOKEN=<value you just got from npm>
 By adding the file to `.gitignore` we’ll be sure that we don’t accidentally push this value to an open-source repository that all our users can see! This is crucial. If other maintainers need to publish the package from locally (later we’ll set things up to auto publish when PRs are merged to master) they should set up their own `.env` file following this process:
 
 ```
-storybook-static
 dist
 .env
 ```
@@ -229,7 +229,7 @@ Yay! We’ve successfully published our package to npm and created a release on
 
 (Note that although `auto` auto-generated the release notes for the first release, we've also modified them to make sense for a first version).
 
-<h4>Set up scripts to use Auto</h4>
+#### Set up scripts to use Auto
 
 Let’s set up Auto to follow the same process when we want to publish the package in the future. We’ll add the following scripts to our `package.json`:
 
@@ -241,24 +241,80 @@ Let’s set up Auto to follow the same process when we want to publish the packa
 }
 ```
 
-Now, when we run `yarn release`, we’ll step through all the steps we ran above (except using the auto-generated changelog) in an automated fashion. We’ll ensure that all commits to master are published by adding a command to our circle config:
+Now, when we run `yarn release`, we'll go through all the steps we ran above (except using the auto-generated changelog) in an automated fashion. All commits to `master` will be published.
 
-```
-# ...
-- run: yarn test
-- run: npx chromatic --project-token=2wix88i1ziu
-- run: |
-    if [ $CIRCLE_BRANCH = "master" ]
-    then
-      yarn release
-    fi
-```
+Congratulations! You setup the infrastructure to manually publish your design system releases. Now learn how to automate releases with continuous integration.
+
+## Publish releases automatically
+
+We use GitHub Actions for continuous integration. But before proceeding, we need to securely store the GitHub and NPM tokens from earlier so that Actions can access them.
+
+#### Add your tokens to GitHub Secrets
+
+GitHub Secrets allow us to store sensitive information in our repository. In a browser window open your GitHub repository.
+
+Click the ⚙️ Settings tab then the Secrets link in the sidebar. You'll see the following screen:
+
+![Empty GitHub secrets page](/design-systems-for-developers/github-empty-secrets-page.png)
+
+Click the **New secret** button. Use `NPM_TOKEN` for the name and paste the token you got from npm earlier in this chapter.
+
+![Filled GitHub secrets form](/design-systems-for-developers/github-secrets-form-filled.png)
 
-We’ll also need to add an npm+GitHub token to your project’s Circle environment on the CircleCI website (https://circleci.com/gh/&lt;your-username&gt;/learnstorybook-design-system/edit#env-vars):
+When you add the npm secret to your repository, you'll be able to access it as `secrets.NPM_TOKEN`. You don't need to setup another secret for your GitHub token. All GitHub users automatically get a `secrets.GITHUB_TOKEN` associated with their account.
 
-![Setting environment variables on CircleCI](/design-systems-for-developers/circleci-set-env-vars.png)
+#### Automate releases with GitHub Actions
 
-Now every time you merge a PR to master, it will automatically publish a new version, incrementing the version number as appropriate due to the labels you’ve added.
+Every time a pull request is merged we want to publish the design system automatically. Create a new file called `push.yml` in the same folder we used earlier to <a href="https://www.learnstorybook.com/design-systems-for-developers/react/en/review/#publish-storybook">publish Storybook</a> and add the following:
+
+```yml
+# .github/workflows/push.yml
+
+## name of our action
+name: Release
+
+# the event that will trigger the action
+on:
+  push:
+    branches: [master]
+
+# what the action will do
+jobs:
+  release:
+    # the operating system it will run on
+    runs-on: ubuntu-latest
+    # this check needs to be in place to prevent a publish loop with auto and github actions
+    if: "!contains(github.event.head_commit.message, 'ci skip') && !contains(github.event.head_commit.message, 'skip ci')"
+    # the list of steps that the action will go through
+    steps:
+      - uses: actions/checkout@v2
+      - name: Prepare repository
+        run: git fetch --unshallow --tags
+      - name: Use Node.js 12.x
+        uses: actions/setup-node@v1
+        with:
+          node-version: 12.x
+      - name: Cache node modules
+        uses: actions/cache@v1
+        with:
+          path: node_modules
+          key: yarn-deps-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            yarn-deps-${{ hashFiles('yarn.lock') }}
+
+      - name: Create Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          yarn install --frozen-lockfile
+          yarn build
+          yarn release
+```
+
+Save and commit your changes to the remote repository.
+
+Success! Now every time you merge a PR to master, it will automatically publish a new version, incrementing the version number as appropriate due to the labels you’ve added.
 
 <div class="aside">We didn’t cover all of Auto’s many features and integrations that might be useful for growing design systems. Read the docs <a href="https://github.com/intuit/auto">here</a>.</div>
 
@@ -304,6 +360,8 @@ yarn add <your-username>-learnstorybook-design-system
 Now, let’s update the example app’s `.storybook/main.js` to import the design system components:
 
 ```javascript
+// .storybook/main.js
+
 module.exports = {
   stories: [
     '../src/**/*.stories.js',
@@ -320,6 +378,8 @@ module.exports = {
 Also we can add a global decorator to a new `.storybook/preview.js` config file use the global styles defined by the design system. Make the following change to the file:
 
 ```javascript
+// .storybook/preview.js
+
 import React from 'react';
 import { addDecorator } from '@storybook/react';
 import { global as designSystemGlobal } from '<your-username>-learnstorybook-design-system';
@@ -338,7 +398,7 @@ addDecorator(story => (
 
 You’ll now be able to browse the design system components and docs while developing the example app. Showcasing the design system during feature development increases the likelihood that developers will reuse existing components instead of wasting time inventing their own.
 
-Alternatively, you can browse your design system’s Storybook online if you deployed it to a web host earlier (see chapter 4).
+Alternatively, you can browse your design system’s Storybook online if you deployed it to <a href="https://www.learnstorybook.com/design-systems-for-developers/react/en/review/#publish-storybook">Chromatic </a> earlier (see chapter 4).
 
 We’ll use the Avatar component from our design system in the example app’s UserItem component. UserItem should render information about a user including a name and profile photo.
 
@@ -347,12 +407,16 @@ Navigate to the UserItem.js component in your editor. Also, find UserItem in the
 Import the Avatar component.
 
 ```javascript
+// src/components/UserItem.js
+
 import { Avatar } from '<your-username>-learnstorybook-design-system';
 ```
 
 We want to render the Avatar beside the username.
 
 ```javascript
+//src/components/UserItem.js
+
 import React from 'react';
 import styled from 'styled-components';
 import { Avatar } from 'learnstorybook-design-system';

content/design-systems-for-developers/react/en/document.md

@@ -44,6 +44,8 @@ yarn add --dev @storybook/addon-docs
 We'll add it to our addons list in `.storybook/main.js`:
 
 ```javascript
+// .storybook/main.js
+
 module.exports = {
   stories: ['../src/**/*.stories.js'],
   addons: [
@@ -75,6 +77,8 @@ So far we’ve made lots of progress with little effort. Yet, the documentation
 Start by adding more metadata that explains what the component does. In `src/Avatar.stories.js`, add a subtitle that describes what the Avatar is used for:
 
 ```javascript
+// src/Avatar.stories.js
+
 export default {
   title: 'Design System|Avatar',
 
@@ -88,6 +92,8 @@ export default {
 Next add JSdoc to the Avatar component (in `src/components/Avatar.js`) that provides a description to be read:
 
 ```javascript
+// src/components/Avatar.js
+
 /**
 - Use an avatar for attributing actions or content to specific users.
 - The user's name should always be present when using Avatar – either printed beside the avatar or in a tooltip.
@@ -103,6 +109,8 @@ You should now see this:
 Storybook Docs automatically generated the prop table that shows types and default values. That’s convenient, but it doesn’t mean Avatar is dummy-proof – several props can be misused. Add comments in your proptypes to render them in the auto-generated prop table.
 
 ```javascript
+// src/components/Avatar.js
+
 Avatar.propTypes = {
   /**
     Use the loading state to indicate that the data Avatar needs is still loading.
@@ -127,6 +135,8 @@ Avatar.propTypes = {
 By default, every Avatar story is rendered in the docs. We can’t assume other developers know what each story represents. Write some descriptive text for the stories in `src/Avatar.stories.js`:
 
 ```javascript
+// src/Avatar.stories.js
+
 export const sizes = () => (
   <div>
     <Avatar
@@ -167,6 +177,8 @@ Markdown is a straightforward format for writing text. MDX allows you to use int
 First, let’s take control of the Avatar doc generation from the default. Register MDX files in `.storybook/main.js` like so.
 
 ```javascript
+// .storybook/main.js
+
 module.exports = {
   // automatically import all files ending in *.stories.js|mdx
   stories: ['../src/**/*.stories.(js|mdx)'],
@@ -185,6 +197,8 @@ module.exports = {
 Create a new `src/Avatar.stories.mdx` file and supply some details. We’ll remove the `Avatar.stories.js` file and recreate the stories in the mdx file:
 
 ```javascript
+// src/Avatar.stories.mdx
+
 import { Meta, Story } from '@storybook/addon-docs/blocks';
 import { withKnobs, select, boolean } from '@storybook/addon-knobs';
 
@@ -284,6 +298,8 @@ Storybook Docs come with “Doc Blocks”, readymade components like interactive
 Let’s add the `Props` doc block, and wrap our initial story in a `Preview`
 
 ```javascript
+// src/Avatar.stories.mdx
+
 import { Meta, Story, Props, Preview } from '@storybook/addon-docs/blocks';
 
 # …
@@ -308,7 +324,9 @@ Nice! We’re back to where we started, but now with full control over ordering
 Customize Avatar’s docs with a note about use cases. This gives developers context about how to take advantage of this component. We can just add markdown as we would in any other markdown document:
 
 ```javascript
-// As before
+// src/Avatar.stories.mdx
+
+// Same content as before
 
 <Props of={Avatar} />
 
@@ -318,7 +336,7 @@ Avatar is used to represent a person or an organization. By default the avatar s
 
 ### Sizes
 
-// As before
+// Same content as before
 
 ```
 
@@ -331,6 +349,8 @@ Every design system comes with a cover page. Storybook Docs allows you to create
 Create a new file `src/components/Intro.stories.mdx`:
 
 ```javascript
+// src/components/Intro.stories.mdx
+
 import { Meta } from '@storybook/addon-docs/blocks';
 
 <Meta title="Design System|Introduction" />
@@ -349,7 +369,10 @@ This generates a new documentation-only page that is independent of the automate
 To get it to appear first, we have to tell Storybook to load the Introduction file in `.storybook/main.js`:
 
 ```javascript
+// .storybook/main.js
+
 module.exports = {
+  // changes the load order of our stories. First loads the Intro page
   // automatically import all files ending in *.stories.js|mdx
   stories: ['../src/components/Intro.stories.mdx', '../src/**/*.stories.(js|mdx)'],
   addons: [
@@ -385,16 +408,9 @@ In a previous chapter, we published Storybook online for visual review. It’s e
 }
 ```
 
-Save and commit. We could change our Netlify publication to deploy the docs site, or use a second deployment system (such as [now.sh](https://zeit.co/home)) to deploy the docs site on every commit.
-
-<!--
-Create a second Netlify integration to run the docs build script:
-
-![alt_text](/design-systems-for-developers/Feedback-wanted55.png)
-
-Great. Every time you commit, you’ll now see two PR checks. One takes you to the published Storybook. The other takes you to the published Storybook Docs.
+Save and commit.
 
-![alt_text](/design-systems-for-developers/Feedback-wanted56.png) -->
+Running `build-storybook-docs` in your command line or continuous integration tool will output a static site in the "docs" configuration. Set up a static site deployment tool [Netlify](https://www.netlify.com/) or [Vercel](https://vercel.com/) to deploy the docs site on every commit.
 
 <div class="aside">As your design system grows you may encounter organization-specific requirements that warrant custom tooling or even building your own static site using tools like Gatsby or Next. It’s easy to port markdown and MDX to other solutions.</div>