-
Couldn't load subscription status.
- Fork 12
Adding Get Started docs for set up instructions #2809
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 5 commits
9717456
8a81ecd
a9f217b
c9f26e1
1de5140
e91cb7a
27b55eb
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,193 @@ | ||
| import {Meta} from "@storybook/addon-docs/blocks"; | ||
|
|
||
| <Meta title="Get Started" /> | ||
|
|
||
| # Get Started | ||
|
|
||
| ## Design | ||
|
|
||
| The design system components are available in Figma: | ||
| - <a href="https://www.figma.com/design/EuFu0U7gqc1koXm8ZhlOLp/%E2%9A%A1%EF%B8%8F-Components?node-id=1-2">Wonder Blocks Component Library (Thunderblocks)</a> | ||
|
||
| - <a href="https://www.figma.com/design/VbVu3h2BpBhH80niq101MHHE/%F0%9F%92%A0-Main-Components?node-id=4249-1689">Original Wonder Blocks Component Library (Classic)</a> | ||
|
|
||
| For the most part, the Figma components should have an equivalent code component. | ||
| Reach out to the Wonder Blocks team if you have any questions on how to implement | ||
| a design using the code components! | ||
|
|
||
| ## Development | ||
|
|
||
| ### Installation | ||
|
|
||
| #### Setting up Wonder Blocks | ||
| 1. Install the <a href="https://github.com/Khan/wonder-blocks/blob/main/packages/wonder-blocks-core/package.json">`peerDependencies`</a> for the `wonder-blocks-core` package: | ||
| ```shell | ||
| pnpm install aphrodite@^1.2.5 [email protected] [email protected] [email protected] [email protected] react-router-dom-v5-compat@^6.30.0 | ||
| ``` | ||
| 2. Install the `wonder-blocks-core` and `wonder-blocks-tokens` packages: | ||
| - The <a href="/?path=/docs/packages-core-overview--docs">Core package</a> provides | ||
| building blocks and helpful utilities for | ||
| constructing components | ||
| - The <a href="/?path=/docs/packages-tokens-overview--docs">Tokens package</a> provides | ||
| tokens that define the look and feel of the design system. When implementing | ||
| features in an application, use these tokens so that it follows the principles | ||
| and theming of the design system. | ||
| ```shell | ||
| pnpm install @khanacademy/wonder-blocks-core @khanacademy/wonder-blocks-tokens | ||
| ``` | ||
|
|
||
| #### Importing Styles | ||
| 1. Import the styles from the tokens package. These styles are necessary since | ||
| they include the CSS variables used in Wonder Blocks. | ||
|
|
||
| ```css | ||
| // styles.css | ||
| @import "@khanacademy/wonder-blocks-tokens/styles.css"; | ||
| ``` | ||
|
|
||
| #### Typography | ||
| 1. Set the root font size to `62.5%` so that `1rem` is equal to `10px`. Many of | ||
| the Wonder Blocks components and typography use rems based on this unit. | ||
|
|
||
| ```css | ||
| html { | ||
| font-size: 62.5%; | ||
| } | ||
| ``` | ||
|
Comment on lines
+50
to
+54
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Kinda related to the other comment: https://github.com/Khan/wonder-blocks/pull/2809/files#r2396094476 I wonder if we could also include setting the root font size in a base WB stylesheet so that if we ever need to change this, we can change it in one place within WB! There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Good point! I think it would be safe to do it with our current sites. But I'm not fully sure how impactful would be with other places that combine WB with other styles/components. Maybe it would be better to let the consumer decide where to put that override (e.g. which selector). There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
If I'm understanding correctly, consumers will need the It is interesting though that the base rem value is defined outside of WB so WB isn't the thing that defines that 1rem is 10px (the apps or Storybook preview config determines it!) (There aren't any issues with how things are now so this can be a consideration for later!) |
||
|
|
||
| 2. More details to come on how to import fonts! | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I was taking a look at how the fonts were set up for thunderblocks in webapp: https://github.com/Khan/webapp/pull/32961 I saw we added the related font files and defined the css font faces in webapp/frontend. I'm wondering if it would make sense to include those in WB so that consumers don't need to set these things up in their project. And we could modify any fonts internally within WB. Let me know what you think! For now, I've included a placeholder for these steps and created WB-2102 to fill in more details about importing fonts! There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is a valid point! I think it would be a good idea to encapsulate fonts within WB :). |
||
|
|
||
| #### Theming | ||
|
|
||
| 1. Install the theming package: | ||
| ```shell | ||
| pnpm install @khanacademy/wonder-blocks-theming | ||
| ``` | ||
| 2. Wrap the root of your application with the <a href="/?path=/docs/packages-theming-themeswitcher--docs">Theme Switcher</a> | ||
| component. The theme can be set using the `theme` prop. Any descendants of this | ||
| that uses Wonder Blocks components or tokens will have styling for the selected | ||
| theme! | ||
|
|
||
| ```tsx | ||
| // App.tsx | ||
|
|
||
| import {ThemeSwitcher} from "@khanacademy/wonder-blocks-theming"; | ||
|
|
||
| export const App = () => { | ||
| return ( | ||
| <ThemeSwitcher theme="thunderblocks"> | ||
| {/* The application contents */} | ||
| </ThemeSwitcher> | ||
| ); | ||
| }; | ||
|
|
||
| ``` | ||
|
|
||
| #### Icons | ||
|
|
||
| We currently use icons from <a href="https://phosphoricons.com/">Phosphor Icons</a> or | ||
| custom icons. | ||
|
|
||
| ##### Phosphor Icons | ||
|
|
||
| 1. Install Phosphor Icons and the WB Icon packages | ||
| ```shell | ||
| pnpm install @phosphor-icons/core @khanacademy/wonder-blocks-icon | ||
| ``` | ||
| 2. Import an icon from the Phosphor Icon library | ||
| ```ts | ||
| import magnifyingGlassIcon from "@phosphor-icons/core/regular/magnifying-glass.svg"; | ||
| ``` | ||
| 3. Use with the Wonder Blocks <a href="/?path=/docs/packages-icon-phosphoricon--docs">PhosphorIcon</a> | ||
| component or other Wonder Blocks components that support Phosphor icons like Button, | ||
| IconButton, Banner, etc. | ||
|
|
||
| ```tsx | ||
| import magnifyingGlassIcon from "@phosphor-icons/core/regular/magnifying-glass.svg"; | ||
| import {PhosphorIcon} from "@khanacademy/wonder-blocks-icon"; | ||
|
|
||
| const icon = ( | ||
| <PhosphorIcon | ||
| icon={magnifyingGlassIcon} | ||
| size="medium" | ||
| /> | ||
| ); | ||
|
|
||
| const iconButton = ( | ||
| <IconButton | ||
| icon={magnifyingGlassIcon} | ||
| aria-label="An Icon" | ||
| onClick={(e) => console.log("Hello, world!")} | ||
| size="medium" | ||
| /> | ||
| ); | ||
| ``` | ||
|
|
||
| ##### Custom Icons | ||
|
|
||
| 1. Install the Wonder Blocks Icon package | ||
| ```shell | ||
| pnpm install @khanacademy/wonder-blocks-icon | ||
| ``` | ||
| 2. Import the icon asset. | ||
| - For custom icon assets, consider using semantic color tokens in inline svgs so | ||
| that the icon properly responds to theming in the system | ||
| - Note: The Wonder Blocks Icon package also includes a set of | ||
| <a href="/?path=/docs/packages-icon-custom-icon-components--docs">common custom icon assets</a>. | ||
|
|
||
| ```tsx | ||
| import {GemIcon} from "@khanacademy/wonder-blocks-icon"; | ||
| import customIcon from "./custom-icon.svg"; | ||
| ``` | ||
|
|
||
| 3. Use with the <a href="/?path=/docs/packages-icon-icon--docs">Wonder Blocks Icon</a> | ||
| component or other Wonder Blocks components that support Phosphor icons like Button, | ||
| IconButton, Banner, etc. | ||
| ```tsx | ||
| import {GemIcon} from "@khanacademy/wonder-blocks-icon"; | ||
| import customIcon from "./custom-icon.svg"; | ||
|
|
||
| const gemIcon = ( | ||
| <Icon size="large"> | ||
| <GemIcon aria-label="Gems" /> | ||
| </Icon> | ||
| ); | ||
|
|
||
| const customAssetIcon = ( | ||
| <Icon size="large"> | ||
| {customIcon} | ||
| </Icon> | ||
| ); | ||
|
|
||
| const gemIconButton = ( | ||
| <IconButton | ||
| icon={<GemIcon />} | ||
| aria-label="Gems" | ||
| onClick={(e) => console.log("Hello, world!")} | ||
| size="medium" | ||
| /> | ||
| ) | ||
| ``` | ||
|
|
||
| #### Components | ||
|
|
||
| 1. Install the package you need for a specific Wonder Blocks component. The | ||
| package name can be found in the docs for a component. | ||
|
|
||
| For example, to use the Wonder Blocks Button component, we would need to install | ||
| the `@khanacademy/wonder-blocks-button` component. | ||
|
|
||
| ```bash | ||
| pnpm install @khanacademy/wonder-blocks-button | ||
| ``` | ||
|
|
||
| 2. Install any other peer dependencies for that package. | ||
|
|
||
| 3. Read the component docs for information about best practices, guidelines, and | ||
| common examples! | ||
|
|
||
|
|
||
| <br /> | ||
| <br /> | ||
|
|
||
| As always, feel free to reach out to the Wonder Blocks team if you have any | ||
| questions or run into any issues! | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let me know if I'm missing anything, or feel free to update this as well!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This got me thinking. Do you think it would make sense to keep this guide here? or would it be better to move it to Confluence?
I'm not sure if it's hard for product engs to find these pages in Confluence and if it is better fit to keep these docs in Storybook instead.
For example, we have these simple instructions here: https://khanacademy.atlassian.net/wiki/spaces/WB/pages/2217541905/Installing+Web+Wonder+Blocks+in+your+local+environment, but I'm not sure if people have checked that page and if it would make sense to expand it if we see fit for it.
How do you feel about all of this? would love to hear your thoughts.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My assumption was that WB documentation is easier to find in Storybook since that is where devs go to find information on how to use components or tokens! I feel like the type of docs in our Confluence space (except for the release notes) are more about how to work on WB!
One thing I like about having technical documentation in Storybook is that the docs are searchable with the rest of the codebase! If we have to make updates to docs based on a code change, sometimes we are able to find related docs when searching in the repo, while searching and updating docs in Confluence is an additional step. For example, in these set up instructions, I added a step for installing peer dependencies which includes
aphrodite. When we migrate away fromaphrodite, we can search for the term"aphrodite"and it'd be a reminder we can update the getting started docs too!What are your thoughts on this? @marcysutton too in case you have thoughts on where docs like this should live!
Sidenote: I'm able to view analytics in Confluence and see 9 unique viewers all time on the doc you shared! Though, they are instructions for setting up the WB repo, rather than installing WB in another project! I'd be curious to know if we have access to any analytics for our Storybook docs!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the info! I think that's a totally fair observation.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
question: How do you feel about adding the CodeSandbox link here so folks still can see the steps in an IDE?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm weary of adding the CodeSandbox link to the docs since it would be an additional thing we'd need to maintain! I set it up mostly as a draft for testing 😄
It has crossed my mind though that it would be nice to have a WB environment to easily try out components (whether it be in CodeSandbox or something else!). I'm not sure what the proper way to do that is yet. I used my GitHub account on CodeSandbox to make the draft project (I was able to install WB packages since they are public on npm!)