@arbor-education/design-system.components
The React component library for the Arbor design system. Components are built with TypeScript, styled with Sass, developed in Storybook, and tested with Vitest. This library serves millions of students and educators across the UK — handle with care.
Release
The latest version of the design system available to install is:
Storybook
The component library is documented and previewed in Storybook.
Production Storybook (built on every push to main):
https://main--6aad454d6baef787355e085a.chromatic.com/
Per-PR Storybook previews: every pull request automatically triggers a Chromatic build. Once it completes, a bot will comment on your PR with links to both the Storybook preview and the Chromatic visual diff for that branch.
To start the development server on port 6006:
yarn storybook
To run the story tests:
yarn test:storybook
Consuming the package
If you're integrating this library into a consumer project, check out the guide on Confluence:
Consuming the design system NPM package
Local setup
Prerequisites
Steps
nvm use
yarn install
yarn storybook
Storybook will build and open in your browser with hot reloading ready for development.
Commands
Development
| Command | Description |
|---|---|
yarn storybook | Start Storybook dev server on port 6006 |
yarn watch | Watch mode — rebuilds and pushes to Yalc consumers on changes |
Building
| Command | Description |
|---|---|
yarn build | Full production build (TypeScript + tsc-alias + Sass) |
yarn tsc | TypeScript compilation only |
yarn check-types | Type check without emitting files |
Testing
| Command | Description |
|---|---|
yarn test | Run Vitest in watch mode |
yarn test:coverage | Run tests once with coverage report |
Linting
| Command | Description |
|---|---|
yarn style-lint | Lint SCSS files with stylelint |
ESLint runs automatically on staged TypeScript files via lint-staged on git commit.
Creating a new component
Use the scaffolding script to generate all necessary files for a new component:
yarn create-component <ComponentName>
This creates Component.tsx, Component.test.tsx, Component.stories.tsx, and component.scss, and automatically adds the exports to src/index.ts and src/index.scss.
Local development with a consumer project
This library uses Yalc for local linking.
First time setup — install Yalc globally:
npm i yalc -g
Link the library to a consumer project:
# In this repo — build and publish to the local Yalc store
yarn build
yalc publish
# In the consumer project — add the local package
yalc add @arbor-education/design-system.components
For active development with hot updates, use watch mode instead:
# In this repo — automatically rebuilds and pushes to Yalc on file changes
yarn watch
Version management
This library uses Changesets for versioning and changelog generation.
If your change affects the public API (new components, changed props, removed exports), create a changeset before opening your PR:
yarn changeset
Contributing
Before opening a PR, please read CONTRIBUTING.md. Key points:
- One PR, one thing — if the title needs "and" or "also", split it
- Keep meaningful code diffs under 400 lines
- All tests must pass (
yarn test:coverage) - All type checks must pass (
yarn check-types) - Use the PR template — fill in every section