Skip to content
Merged
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 193 additions & 0 deletions __docs__/_get-started_.mdx
Copy link
Member Author

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!

Copy link
Member

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.

Copy link
Member Author

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 from aphrodite, 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!

Copy link
Member

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.

Copy link
Member

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?

Copy link
Member Author

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!)

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>
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using anchor tags for links so that they don't open in the Storybook iframe

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thing that I've noticed is that sometimes we get requests from external people to see our WB Figma files. I wonder if we should instead remove these links and move them to another place (maybe Confluence?).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question! We can create a Confluence page about the Figma files and link to that instead!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I created a Wonder Blocks Resources page in Confluence so we can link to that instead! https://khanacademy.atlassian.net/wiki/spaces/WB/pages/4396089552/Resources

I updated Figma links in the docs to this page instead 😄 Thanks for the suggestion!

- <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
Copy link
Member Author

Choose a reason for hiding this comment

The 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!

Copy link
Member

@jandrade jandrade Oct 24, 2025

Choose a reason for hiding this comment

The 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).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe it would be better to let the consumer decide where to put that override (e.g. which selector).

If I'm understanding correctly, consumers will need the font-size: 62.5% on the root html element in order for the correct rem values to work! Or is it fine for the root font-size to be a different value, since the system should scale according to it?

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!
Copy link
Member Author

Choose a reason for hiding this comment

The 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!

Copy link
Member

Choose a reason for hiding this comment

The 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!