Wonder Blocks

The Khan Academy Wonder Blocks design system. This is work-in-progress and a lot of things are still in motion.

More information: https://khan.github.io/wonder-blocks/

Getting started

Prerequisites

• Node.JS v20.x
• pnpm

Installation

To install Wonder Blocks, you need to run the following commands:

pnpm install

Installs project dependencies

pnpm dev

Builds all the packages and watches for changes

pnpm start

Runs the docs in dev mode

Now you can open http://localhost:6061 to view the docs. This page will automatically update as you make changes to components.

AI agents / Storybook MCP: To use the Wonder Blocks MCP from another project (e.g. Cursor), clone this repo, run pnpm install and pnpm start, then add http://localhost:6061/mcp to your MCP client config (e.g. mcp.json). See AGENTS.md for full install steps and agentic workflows.

Contributing

Note for external contributors: We are not accepting external contributions at this time. We are working to make this happen in the future, and we will let you know when this is possible!

For a more detailed explanation about how to develop Wonder Blocks components, please refer to the internal documentation

Please note – before contributing ensure that any design changes you are wanting to make are reflected in the Wonder Blocks project in Figma.

Thanks

Thanks to Chromatic for providing the visual testing platform that helps us catch unexpected changes on time.